OpenClaw Config

Edit and validate OpenClaw Gateway config (openclaw.json / JSON5). Covers all config areas — gateway, agents, channels, models, auth, tools, commands, sessio...

sniper-one@aqbjqtd

Install

openclaw skills install @aqbjqtd/openclaw-config-master

OpenClaw Config

一句话

用 schema-first 工作流安全编辑 OpenClaw 配置文件，验证先行，避免无效 key 导致 Gateway 无法启动或安全策略被破坏。

核心要点（5条）

Schema 先行 — 不猜 key，用 gateway config.schema.lookup path="目标路径" 获取权威 schema
在线修改 — 优先用 gateway config.patch 在线修改（自动验证+重启），备选 openclaw config set CLI
验证不可跳 — config.patch 自动验证；手动编辑后必须跑 openclaw doctor
严格模式 — 大多数对象是 .strict()，未知 key 会导致 Gateway 拒绝启动
不轻易用 --fix — openclaw doctor --fix/--yes 会写文件，需用户明确同意
受保护路径 — 部分敏感路径（如 tools.exec.ask）config.patch 无法修改，会返回 cannot change protected config paths 错误。遇此情况需直接编辑 openclaw.json 后 openclaw gateway restart

配置覆盖范围（全部顶层 key）

顶层 key	子模块	说明
`gateway`	port, mode, bind, auth, tailscale, nodes, controlUi	网关核心：端口、模式、认证、Tailscale、节点策略
`agents`	defaults, list	Agent 配置：默认模型/工具/工作区 + agent 列表
`channels`	telegram, feishu, discord, slack, whatsapp, signal, imessage, ...	渠道配置：每个渠道的连接、策略、审批
`models`	providers, mode, bedrockDiscovery	模型目录：提供者定义、合并模式、Bedrock 发现
`auth`	profiles	认证配置：API Key / OAuth 认证档案
`tools`	exec, web, fs, media, links, sessions, loopDetection, message, agentToAgent, elevated, subagents, sandbox, sessions_spawn, profile, allow, alsoAllow, deny, byProvider	工具策略：执行、网络、文件系统、媒体、沙箱、子代理
`commands`	bash, config, mcp, plugins, debug, restart, text, native, nativeSkills, allowFrom, ownerDisplay, ...	命令控制：聊天命令开关、权限、提权规则
`session`	scope, dmScope, reset, resetByType, resetByChannel, store, typingMode, identityLinks, threadBindings, maintenance, sendPolicy, agentToAgent, ...	会话管理：路由、重置策略、存储、线程绑定、维护
`hooks`	internal, external	钩子：内部钩子（session-memory）+ 外部钩子
`secrets`	providers	密钥管理：文件/环境变量等密钥提供者
`acp`	enabled, backend, defaultAgent, allowedAgents	ACP 后端：Agent 托管运行时配置
`messages`	ackReactionScope	消息行为：确认反应范围等
`plugins`	enabled, allow, deny, load, slots, entries, installs	插件系统：启用/禁用、加载路径、安装记录
`skills`	(skills 配置)	技能配置
`meta`	lastTouchedVersion, lastTouchAt	系统元数据（自动管理）
`wizard`	lastRunAt, lastRunVersion, lastRunCommand, lastRunMode	向导元数据（自动管理）
`$include`	—	模块化配置：分割到多个 JSON5 文件

工作流程

重要：在提供任何配置指导之前，必须按以下步骤执行前置检查。

第一步：查官方文档（必做）

每次修改配置前，必须先查阅官方最新文档确认字段和用法。 技能内的文档可能滞后于官方更新。

在线文档（权威来源）

文档	链接	用途
配置指南	https://docs.openclaw.ai/gateway/configuration	所有配置项的完整说明
配置参考	https://docs.openclaw.ai/gateway/configuration-reference	字段类型、默认值、示例
Config CLI	https://docs.openclaw.ai/cli/config	`config set/get/unset` 用法
Update CLI	https://docs.openclaw.ai/cli/update	版本更新命令
Channels CLI	https://docs.openclaw.ai/cli/channels	渠道管理命令
Skills CLI	https://docs.openclaw.ai/cli/skills	技能管理命令
Security CLI	https://docs.openclaw.ai/cli/security	安全审计命令
Models	https://docs.openclaw.ai/gateway/models	模型提供者配置
Agents	https://docs.openclaw.ai/gateway/agents	Agent 配置
Tools	https://docs.openclaw.ai/gateway/tools	工具配置
Plugins	https://docs.openclaw.ai/gateway/plugins	插件配置
Cron	https://docs.openclaw.ai/gateway/cron	定时任务配置
Session	https://docs.openclaw.ai/gateway/session	会话配置

内置文档搜索

bash

# 搜索特定主题的官方文档
openclaw docs "configuration"
openclaw docs "telegram"
openclaw docs "exec approvals"
openclaw docs "models"
openclaw docs "session"

在线 Schema 查询

text

# 通过 gateway 工具查询（推荐）
gateway config.schema.lookup path="目标路径"

# CLI 方式
openclaw config schema

何时查什么

场景	查什么
添加/修改模型	配置参考 + models 文档 + schema lookup
配置渠道	配置参考 + Channels CLI + schema lookup
修改安全策略	配置指南 + Security CLI + schema lookup
会话/重置策略	配置参考 + session 文档 + schema lookup
工具权限控制	配置参考 + tools 文档 + schema lookup
版本升级后配置不兼容	配置参考 + Update CLI + `references/version-migration.md`
不确定字段名/类型	先查 schema lookup，再查配置参考

第二步：版本检查

bash

# 检查本地版本
openclaw --version

# 检查最新版本
openclaw update status --json

如果本地版本不是最新：提醒用户先更新：openclaw update

第三步：执行修改

两种修改模式

模式 A：在线修改（推荐）

通过 gateway 工具直接修改，自动验证+重启：

text

# 1. 查询当前值
gateway config.get path="commands.bash"

# 2. 查询 schema 确认字段合法性
gateway config.schema.lookup path="commands"

# 3. 应用修改（用户确认后）
gateway config.patch raw='{"commands":{"bash":true}}' note="启用 bash 命令"

config.patch：部分更新，与现有配置合并，适合修改少量字段
config.apply：全量替换，适合大规模重构
两者都会自动验证 schema + 写入 + 重启 Gateway
note 参数必填，用于重启后通知用户

模式 B：CLI 命令（备选）

无法使用 gateway 工具时，生成命令供用户执行：

bash

# 设置值
openclaw config set <path> <value> --json

# 验证
openclaw config validate

# 重启
openclaw gateway restart

在线修改配置的标准流程

修改任何配置前，按此流程操作：

查 schema — gateway config.schema.lookup path="目标路径"，确认字段名和类型
读当前值 — gateway config.get path="目标路径"，了解现状
向用户说明 — 描述要改什么、为什么改、预期影响
执行修改 — 用户确认后，gateway config.patch raw='{...}' note="变更说明"
验证结果 — 重启后自动通知，检查新配置是否生效

注意：config.patch 会自动写入、验证 schema、重启 Gateway。不需要手动 openclaw doctor。

详细配置参考

gateway — 网关核心

json

"gateway": {
  "port": 18789,           // 监听端口
  "mode": "local",         // 运行模式：local
  "bind": "loopback",      // 绑定：loopback | 0.0.0.0
  "auth": {
    "mode": "token",       // 认证模式
    "token": "..."         // 认证 token
  },
  "tailscale": {
    "mode": "off",         // Tailscale 模式
    "resetOnExit": false
  },
  "controlUi": {
    "allowInsecureAuth": false
  },
  "nodes": {
    "denyCommands": [...]  // 节点禁止命令列表
  }
}

agents — Agent 配置

json

"agents": {
  "defaults": {
    "model": {
      "primary": "provider/model-id",     // 默认模型
      "fallbacks": ["provider/fallback1"] // 回退模型列表
    },
    "models": {                           // 可用模型注册 + 别名
      "provider/model": { "alias": "别名" }
    },
    "workspace": "~/.openclaw/workspace", // 工作目录
    "contextPruning": { "mode": "cache-ttl", "ttl": "1h" },
    "compaction": { "mode": "safeguard" },
    "heartbeat": { "every": "30m" },
    "maxConcurrent": 2,
    "subagents": { "maxConcurrent": 2 }
  },
  "list": [
    {
      "id": "main",
      "tools": { "alsoAllow": [...] },
      "runtime": { "type": "acp", "acp": {...} }
    }
  ]
}

channels — 渠道配置

每个渠道（telegram/feishu/discord/slack/whatsapp/signal/imessage）有独立配置：

json

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "...",
    "dmPolicy": "allowlist|open",
    "groupPolicy": "allowlist|open",
    "allowFrom": ["user_id"],
    "streaming": "partial|full|off",
    "execApprovals": {
      "enabled": true,
      "approvers": ["user_id"],
      "target": "dm"
    },
    "groups": { "*": { "requireMention": true } }
  }
}

详细字段见 references/channels-config.md

models — 模型目录

json

"models": {
  "mode": "merge|replace",     // merge=保留内置+叠加自定义, replace=仅用自定义
  "providers": {
    "provider-id": {
      "baseUrl": "https://...",
      "apiKey": "...|secret-ref",
      "api": "openai-completions|anthropic-messages",
      "models": [
        {
          "id": "model-id",
          "name": "显示名",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 8192,
          "cost": { "input": 0, "output": 0 }
        }
      ]
    }
  },
  "bedrockDiscovery": { ... }   // AWS Bedrock 自动发现
}

auth — 认证档案

json

"auth": {
  "profiles": {
    "provider:default": {
      "provider": "provider-name",
      "mode": "api_key|oauth"
    }
  }
}

tools — 工具策略

json

"tools": {
  "profile": "...",           // 工具策略预设名
  "allow": [...],             // 绝对白名单（替换 profile 默认）
  "alsoAllow": [...],         // 白名单补充（叠加 profile）
  "deny": [...],              // 黑名单（优先级最高）
  "byProvider": { ... },      // 按渠道的工具策略覆盖
  "exec": {
    "security": "allowlist|full",
    "ask": "on-miss",
    "host": "sandbox",
    "safeBins": ["python", "node", "git"],
    "safeBinTrustedDirs": [...],
    "safeBinProfiles": [...],
    "timeoutSec": 120,
    "backgroundMs": 10000,
    "applyPatch": true
  },
  "web": {                    // 搜索/抓取工具策略
    "search": { "enabled": true, "provider": "brave" }
  },
  "fs": { ... },              // 文件系统工具
  "media": { ... },           // 媒体工具
  "links": { ... },           // 链接工具
  "sessions": { ... },        // 会话工具
  "loopDetection": { ... },   // 循环检测
  "message": { ... },         // 消息工具策略
  "agentToAgent": { ... },    // Agent 间工具调用
  "elevated": { ... },        // 提权工具访问
  "subagents": { ... },       // 子代理工具策略
  "sandbox": { ... },         // 沙箱策略
  "sessions_spawn": { ... }   // spawn 会话策略
}

commands — 命令控制

json

"commands": {
  "native": "auto",            // 原生命令注册（Discord/Slack/Telegram 菜单）
  "nativeSkills": "auto",      // 技能原生命令注册
  "text": true,                // 文本命令解析
  "bash": true,                // ! 和 /bash 命令（布尔值）
  "config": false,             // /config 命令读写配置
  "mcp": false,                // /mcp 命令管理 MCP 服务器
  "plugins": false,            // /plugins 命令管理插件
  "debug": false,              // /debug 运行时调试覆盖
  "restart": true,             // /restart 和 gateway 重启工具
  "useAccessGroups": false,    // 启用访问组策略
  "ownerAllowFrom": [...],     // 显式 owner 白名单
  "ownerDisplay": "raw|hash",  // owner ID 显示方式
  "ownerDisplaySecret": "...", // hash 模式的 HMAC 密钥
  "allowFrom": {               // 提权命令的 channel→用户映射
    "telegram": ["YOUR_TELEGRAM_USER_ID"]
  }
}

关键注意：

所有布尔字段必须用 true/false，不能是字符串 "true"
allowFrom 在 commands 下，不在 tools.exec 下
敏感命令（bash/config/mcp/plugins/debug）默认 false，需显式开启

session — 会话管理

json

"session": {
  "scope": "per-sender|global",          // 会话分组策略
  "dmScope": "main|per-peer|per-channel-peer|per-account-channel-peer",
  "dmScopePolicy": "...",                // DM 作用域策略
  "identityLinks": { ... },              // 身份映射（跨渠道同一用户）
  "resetTriggers": [...],                // 会话重置触发词
  "idleMinutes": 0,                      // 空闲重置分钟数（旧版兼容）
  "reset": { ... },                      // 默认重置策略
  "resetByType": {                       // 按聊天类型覆盖
    "direct": { ... },
    "group": { ... },
    "thread": { ... }
  },
  "resetByChannel": { ... },             // 按渠道覆盖
  "store": "path/to/store.db",           // 会话存储路径
  "typingMode": "never|instant|thinking|message",
  "typingIntervalSeconds": 5,
  "parentForkMaxTokens": 0,              // 父会话 fork 上限
  "mainKey": "...",                      // 主会话 key 覆盖
  "sendPolicy": {                        // 跨会话发送权限
    "allow": [...], "deny": [...]
  },
  "agentToAgent": { ... },               // Agent 间会话交换
  "threadBindings": { ... },             // 线程绑定路由
  "maintenance": {                       // 自动维护
    "maxAge": "...", "maxEntries": 1000, "rotateOnStartup": false
  }
}

hooks — 钩子

json

"hooks": {
  "internal": {
    "enabled": true,
    "entries": {
      "session-memory": { "enabled": true }  // 会话记忆钩子
    }
  },
  "external": { ... }                       // 外部 webhook 钩子
}

secrets — 密钥管理

json

"secrets": {
  "providers": {
    "lark-secrets": {
      "source": "file",
      "path": "~/.openclaw/credentials/lark.secrets.json"
    }
  }
}

acp — ACP 后端

json

"acp": {
  "enabled": false,
  "backend": "acpx",
  "defaultAgent": "claude",
  "allowedAgents": ["claude"]
}

messages — 消息行为

json

"messages": {
  "ackReactionScope": "group-mentions"  // 确认反应范围
}

plugins — 插件系统

json

"plugins": {
  "enabled": true,
  "allow": ["minimax", "telegram", "feishu"],  // 插件白名单
  "deny": [...],                                // 插件黑名单
  "load": { "paths": [...] },                   // 加载路径
  "slots": { "memory": "..." },                 // 独占槽位
  "entries": {                                  // 插件配置
    "plugin-id": { "enabled": true, "config": {...} }
  },
  "installs": { ... }                           // 安装记录（CLI 管理）
}

版本适配说明（2026.4.x 关键变更）

重要：以下内容记录了从旧版配置格式到当前版本的关键差异。

1. `tools.exec` — 不支持 `approvals` 和 `allowFrom`

错误写法（会导致 Gateway 崩溃）：

json

"tools": { "exec": { "approvals": { "enabled": true }, "allowFrom": {...} } }

正确写法：

json

"tools": { "exec": { "security": "allowlist", "ask": "on-miss" } }

tools.exec 支持的字段：host, node, security, ask, pathPrepend, safeBins, safeBinTrustedDirs, safeBinProfiles, strictInlineEval, backgroundMs, timeoutSec, cleanupMs, notifyOnExit, notifyOnExitEmptySuccess, applyPatch。

2. exec 审批 → `channels.<channel>.execApprovals`

json

"channels": {
  "telegram": {
    "execApprovals": { "enabled": true, "approvers": ["YOUR_TELEGRAM_USER_ID"], "target": "dm" }
  }
}

3. 新旧格式对照速查表

功能	旧版（错误）位置	正确位置
exec 审批	`tools.exec.approvals`	`channels.telegram.execApprovals`
命令权限白名单	`tools.exec.allowFrom`	`commands.allowFrom`
bash 命令开关	`commands.bash = "true"`	`commands.bash = true`（布尔值）
exec 安全策略	`tools.exec.security`	`tools.exec.security`（不变）

$include（模块化配置）

$include 在 schema 验证前解析，支持将配置分割到多个 JSON5 文件：

支持 "$include": "./base.json5" 或数组
相对路径相对于当前配置文件目录
深度合并规则：对象递归合并，数组拼接，原始值后者覆盖前者
限制：最大深度 10；循环 include 被检测并拒绝

Guardrails（避免 Schema 错误）

大多数对象是 strict (.strict())：未知 key 导致 Gateway 拒绝启动
channels 是 .passthrough()：扩展 channels 可添加自定义 key
env 是 .catchall(z.string())：可直接放字符串环境变量
密钥处理：优先用 secrets.providers 或环境变量，避免将 token/API key 写入 openclaw.json

常用配方

开启 /config 命令

text

gateway config.patch raw='{"commands":{"config":true}}' note="开启 /config 命令"

配置 exec 安全策略

text

gateway config.patch raw='{"tools":{"exec":{"security":"allowlist","ask":"on-miss"}}}' note="配置 exec 安全策略"

配置 Telegram（安全模式：仅自己私聊，禁止群聊）

text

gateway config.patch raw='{"channels":{"telegram":{"enabled":true,"botToken":"YOUR_TELEGRAM_BOT_TOKEN","dmPolicy":"allowlist","allowFrom":["YOUR_TELEGRAM_USER_ID"],"groupPolicy":"disabled"}},"plugins":{"entries":{"telegram":{"enabled":true}}}}' note="配置 Telegram 安全模式"

配置飞书（安全模式：仅自己私聊，群聊开放需 @）

text

gateway config.patch raw='{"channels":{"feishu":{"enabled":true,"appId":"YOUR_FEISHU_APP_ID","appSecret":"YOUR_FEISHU_APP_SECRET","dmPolicy":"allowlist","allowFrom":["YOUR_FEISHU_USER_ID"],"groupPolicy":"open","groupAllowFrom":["*"],"requireMention":true,"connectionMode":"websocket"}},"plugins":{"allow":["openclaw-lark","minimax"],"entries":{"openclaw-lark":{"enabled":true},"minimax":{"enabled":true}}}}' note="配置飞书安全模式"

获取用户 ID（日志法）

bash

# 飞书
tail -500 /tmp/openclaw/openclaw-*.log | grep "message from"
# Telegram
tail -500 /tmp/openclaw/openclaw-*.log | grep "telegram.*message"

验证渠道连接

bash

openclaw channels status
openclaw doctor

配置 Telegram exec 审批

text

gateway config.patch raw='{"channels":{"telegram":{"execApprovals":{"enabled":true,"approvers":["YOUR_TELEGRAM_USER_ID"],"target":"dm"}}}}' note="启用 Telegram exec 审批"

配置命令权限

text

gateway config.patch raw='{"commands":{"bash":true,"allowFrom":{"telegram":["YOUR_TELEGRAM_USER_ID"]}}}' note="启用 bash 命令并配置权限"

修改会话空闲重置

text

gateway config.patch raw='{"session":{"idleMinutes":60}}' note="设置会话 60 分钟空闲后重置"

配置会话维护

text

gateway config.patch raw='{"session":{"maintenance":{"maxEntries":500}}}' note="限制会话存储最多 500 条"

添加模型提供者

text

gateway config.patch raw='{"models":{"providers":{"new-provider":{"baseUrl":"https://...","api":"openai-completions","models":[...]}}}}' note="添加新模型提供者"

启用插件

text

gateway config.patch raw='{"plugins":{"allow":["new-plugin"],"entries":{"new-plugin":{"enabled":true}}}}' note="启用新插件"

配置 hooks

text

gateway config.patch raw='{"hooks":{"internal":{"enabled":true,"entries":{"session-memory":{"enabled":true}}}}}' note="启用 session-memory 钩子"

常见配置错误和修复

错误现象	常见原因	修复方法
Gateway 启动崩溃	`tools.exec` 中有未知字段（如 `approvals`）	移除不支持的字段
Schema 验证失败	`commands.bash` 设为字符串 `"true"`	改为布尔值 `true`
exec 审批不生效	在 `tools.exec` 中配置审批	移至 `channels.telegram.execApprovals`
命令权限不生效	在 `tools.exec.allowFrom` 配置白名单	移至 `commands.allowFrom`
会话不重置	`session.reset` 配置不当	检查 `resetByType`/`resetByChannel` 是否覆盖

复杂配置操作流程

复杂配置变更（添加新模型提供者、配置新频道等）遵循增强流程：

前置检查 — 确认凭证/参数、验证平台可用性、备份配置
详细配置 — 参考 references/complex-operations.md，遵循渐进式修改原则
验证测试 — 逐步测试 + 准备回滚
文档记录 — 记录变更、更新文档

版本升级流程

升级前准备 — 参阅 references/version-migration.md、创建备份、检查兼容性
执行迁移 — 更新字段、处理废弃字段
验证回滚 — 运行测试、准备快速回滚

快速链接

Channel 配置 → references/channels-config.md Telegram + 飞书配置模板 → references/complex-operations.md（含安全模式/开放模式模板、AppSecret 安全存储、常见错误） 复杂配置操作 → references/complex-operations.md 常见错误修复 → references/common-errors.md 版本迁移 → references/version-migration.md 字段索引 → references/openclaw-config-fields.md Schema 源码 → references/schema-sources.md

工具脚本

scripts/openclaw-config-check.sh — 配置验证
scripts/backup-config.sh — 配置备份
scripts/restore-config.sh — 配置恢复
scripts/validate-config.sh — 配置验证
scripts/validate-migration.sh — 迁移验证

官方文档 → 详见上方「第一步：查官方文档」的完整链接表

故障诊断

openclaw doctor — 快速诊断
~/.openclaw/logs/openclaw.log — 日志分析

OpenClaw Config

Install

OpenClaw Config

一句话

核心要点（5条）

配置覆盖范围（全部顶层 key）

工作流程

第一步：查官方文档（必做）

在线文档（权威来源）

内置文档搜索

在线 Schema 查询

何时查什么

第二步：版本检查

第三步：执行修改

两种修改模式

模式 A：在线修改（推荐）

模式 B：CLI 命令（备选）

在线修改配置的标准流程

详细配置参考

gateway — 网关核心

agents — Agent 配置

channels — 渠道配置

models — 模型目录

auth — 认证档案

tools — 工具策略

commands — 命令控制

session — 会话管理

hooks — 钩子

secrets — 密钥管理

acp — ACP 后端

messages — 消息行为

plugins — 插件系统

版本适配说明（2026.4.x 关键变更）

1. tools.exec — 不支持 approvals 和 allowFrom

2. exec 审批 → channels.<channel>.execApprovals

3. 新旧格式对照速查表

$include（模块化配置）

Guardrails（避免 Schema 错误）

常用配方

常见配置错误和修复

复杂配置操作流程

版本升级流程

快速链接

Related skills

1. `tools.exec` — 不支持 `approvals` 和 `allowFrom`

2. exec 审批 → `channels.<channel>.execApprovals`