modbender 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 崩溃 = 通信中断 = 无法修复。预览 + 确认是唯一的防线。