Config Safe

Config Safe

安全地修改 OpenClaw 配置，避免写入无效配置导致 Gateway 无法启动。

核心理念

配置修改是高风险操作。 OpenClaw 有严格的配置验证，任何错误都会导致 Gateway 拒绝启动 一旦配置损坏，Gateway 崩溃，无法与你通信，只能通过 CLI 修复 核心原则：先预览，后验证，再确认，绝不直接修改。

验证方法

在修改配置之前，可以使用以下方法验证配置是否有效：

方法 1: Schema 验证（静态检查）

获取配置的 JSON Schema，检查字段类型和必填项： openclaw gateway call config.schema --params '{}' 用途： 检查字段名是否正确 检查值的类型是否正确 检查必填字段是否遗漏 示例： // Schema 返回结构 { "schema": { "type": "object", "properties": { "channels": { "type": "object" }, "agents": { "type": "object" } }, "required": ["agents"] } }

方法 2: 模拟写入验证（动态检查）

使用 config.patch 尝试验证配置（不会实际写入，除非验证通过）： openclaw gateway call config.patch --params '{ "raw": "{\"channels\":{\"telegram\":{\"enabled\":true}}}", "baseHash": "<current-hash>" }' 行为： 如果配置无效 → 返回错误，不写入，Gateway 继续运行 如果配置有效 → 写入并重启 Gateway 注意： 验证通过后会实际写入配置，所以要先向用户展示预览并获得确认。

Step 1: 读取官方最新文档

在修改任何配置之前，先阅读相关文档： # 配置总览和验证规则 cat /opt/homebrew/lib/node_modules/openclaw/docs/gateway/configuration.md # 配置示例（常见场景） cat /opt/homebrew/lib/node_modules/openclaw/docs/gateway/configuration-examples.md 必读内容： 严格配置验证 (Strict config validation) 配置字段的类型和默认值 相关功能的具体配置示例

Step 2: 获取当前配置（只读）

openclaw gateway call config.get --params '{}' 只读取，不修改。 保存返回的 JSON 和 hash。

Step 3: Schema 验证（可选但推荐）

先用 schema 验证配置结构： openclaw gateway call config.schema --params '{}' 检查你的变更是否符合 schema 要求。

Step 4: 生成预览

• 向用户展示变更内容：
• === 配置变更预览 ===
• 要修改:
• channels.telegram.enabled: false → true
• channels.telegram.botToken: [已隐藏]
• 变更前:
• {
• "channels": { "telegram": { "enabled": false } }
• }
• 变更后:
• {
• "channels": { "telegram": { "enabled": true, "botToken": "***" } }
• }
• ⚠️ 风险检查:
• 字段名正确 ✓
• 类型正确 ✓
• botToken 必填 ✓

Step 5: 用户确认

必须明确获得用户确认后才继续： 请确认以上变更？输入 "确认" 继续，或 "取消" 放弃。

Step 6: 验证并写入

# 部分更新（推荐） openclaw gateway call config.patch --params '{ "raw": "{\"channels\":{\"telegram\":{\"enabled\":true}}}", "baseHash": "<hash>" }' # 全量替换（仅当你完全理解风险时使用） openclaw gateway call config.apply --params '{ "raw": "<完整配置>", "baseHash": "<hash>" }' 注意： 写入成功后 Gateway 会自动重启。

Step 7: 验证结果

重启后检查配置是否生效： openclaw status openclaw doctor

添加/修改 channel

{ channels: { telegram: { enabled: true, botToken: "your-token", dmPolicy: "pairing" } } }

配置 agent 身份

{ agents: { list: [{ id: "main", identity: { name: "Samantha", emoji: "🦥" } }] } }

配置 sandbox

{ agents: { defaults: { sandbox: { mode: "all", scope: "session" } } } }

错误处理

如果配置写入后 Gateway 无法启动： 运行 openclaw doctor 查看具体错误 运行 openclaw doctor --fix 尝试自动修复 如果无法修复，手动编辑 ~/.openclaw/openclaw.json 常见错误： Unknown key: 字段名拼写错误 Invalid type: 值的类型不对 Missing required field: 缺少必填字段

黄金法则

在你这个技能中，永远不要： ❌ 直接写入配置而不预览 ❌ 直接写入配置而不确认 ❌ 使用 config.apply 而不提醒用户风险 你应该： ✅ 先读取文档 ✅ Schema 验证配置结构 ✅ 生成变更预览 ✅ 明确要求用户确认 ✅ 优先使用 config.patch

安全检查清单

在确认配置变更前，确认用户已经： 看到变更预览（变更前 vs 变更后） 了解潜在风险 输入 "确认" 明确同意 记住：Gateway 崩溃 = 通信中断 = 无法修复。预览 + 确认是唯一的防线。