OpenClaw Config

一句话

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

核心要点（5条）

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

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

工作流程

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

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

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

在线文档（权威来源）

内置文档搜索

CODEBLOCK0

在线 Schema 查询

CODEBLOCK1

何时查什么

第二步：版本检查

CODEBLOCK2

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

第三步：执行修改

两种修改模式

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

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

CODEBLOCK3

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

模式 B：CLI 命令（备选）

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

CODEBLOCK4

在线修改配置的标准流程

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

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

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

详细配置参考

gateway — 网关核心

CODEBLOCK5

agents — Agent 配置

CODEBLOCK6

channels — 渠道配置

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

CODEBLOCK7

详细字段见 INLINECODE41

models — 模型目录

CODEBLOCK8

auth — 认证档案

CODEBLOCK9

tools — 工具策略

CODEBLOCK10

commands — 命令控制

CODEBLOCK11

关键注意：

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

session — 会话管理

CODEBLOCK12

hooks — 钩子

CODEBLOCK13

secrets — 密钥管理

CODEBLOCK14

acp — ACP 后端

CODEBLOCK15

messages — 消息行为

CODEBLOCK16

plugins — 插件系统

CODEBLOCK17

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

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

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

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

正确写法：
CODEBLOCK19

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

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

CODEBLOCK20

3. 新旧格式对照速查表

$include（模块化配置）

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

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

Guardrails（避免 Schema 错误）

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

常用配方

开启 /config 命令
CODEBLOCK21

配置 exec 安全策略
CODEBLOCK22

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

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

获取用户 ID（日志法）
CODEBLOCK25

验证渠道连接
CODEBLOCK26

配置 Telegram exec 审批
CODEBLOCK27

配置命令权限
CODEBLOCK28

修改会话空闲重置
CODEBLOCK29

配置会话维护
CODEBLOCK30

添加模型提供者
CODEBLOCK31

启用插件
CODEBLOCK32

配置 hooks

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

常见配置错误和修复

复杂配置操作流程

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

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

版本升级流程

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

快速链接

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 源码 → INLINECODE105

工具脚本

• - scripts/openclaw-config-check.sh — 配置验证
• INLINECODE107 — 配置备份
• INLINECODE108 — 配置恢复
• INLINECODE109 — 配置验证
• INLINECODE110 — 迁移验证

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

故障诊断

• - openclaw doctor — 快速诊断
• INLINECODE112 — 日志分析