aaaaqwq/openclaw-config-helper

OpenClaw Config Helper - 配置修改安全助手

• Author: Daniel Li
• Copyright © Daniel Li. All rights reserved.

⚠️ 强制规则

修改任何 OpenClaw 配置前，必须完成以下步骤，否则可能导致系统崩溃或功能异常！

当使用此技能

• 用户要求修改 OpenClaw 配置（openclaw.json、agents 配置、channels 配置等）
• 用户要求添加/修改 Telegram、WhatsApp 等渠道配置
• 用户要求修改 bindings、models、agents.list 等
• 任何涉及 gateway action=config.patch 或 gateway action=config.apply 的操作

触发词

• "修改配置"
• "改一下 openclaw 配置"
• "添加一个 binding"
• "配置 telegram/whatsapp"
• "改 groupPolicy"
• "添加一个 agent"

强制流程（必须按顺序执行）

步骤 1: 查阅 Schema

# 获取完整配置 schema
gateway action=config.schema

检查要点：

• 确认要修改的字段类型（string/number/array/object）
• 确认字段是否必填
• 确认字段的允许值（enum）
• 确认嵌套结构

步骤 2: 查阅官方文档（如 schema 不够清晰）

# 使用 web_fetch 获取官方文档
web_fetch: https://docs.openclaw.ai/channels/telegram
web_fetch: https://docs.openclaw.ai/channels/whatsapp
web_fetch: https://docs.openclaw.ai/gateway/configuration-reference

或者使用搜索：

cd ~/clawd/skills/tavily && ./scripts/tavily.sh search "OpenClaw <配置项> 配置"

步骤 3: 展示修改方案并确认

向用户展示：

1. 当前配置（如适用）
2. 计划修改（具体 JSON 片段）
3. 修改原因
4. 可能影响

等待用户确认后才执行修改！

步骤 4: 执行修改

# 使用 config.patch 进行部分修改（推荐）
gateway action=config.patch raw='{"修改的路径": "值"}'

# 或使用 config.apply 进行完整替换（谨慎使用）
gateway action=config.apply raw='{"完整配置": "..."}'

步骤 5: 验证修改

# 检查配置是否生效
gateway action=config.get

# 检查 Gateway 状态
openclaw status

常见配置错误案例

案例 1: Telegram groupAllowFrom 错误 (2026-02-22)

错误：把群 ID 放在 groupAllowFrom 里

// ❌ 错误
"groupAllowFrom": [-1003531486855, -1003890797239]  // 这是群 ID，不是用户 ID！

// ✅ 正确
"groupAllowFrom": ["8518085684"]  // 用户 ID
"groups": {
  "-1003531486855": {"groupPolicy": "open", "requireMention": true}
}

教训：groupAllowFrom 是发送者白名单（用户 ID），groups 是群组白名单（群 ID）

案例 2: 缺少 binding 导致 bot 无响应

错误：主 bot (default account) 没有绑定到任何 agent

// ❌ 缺少 default → main 的绑定
"bindings": [
  {"agentId": "ops", "match": {"accountId": "xiaoops"}},
  // ... 其他 bot，但没有 default
]

// ✅ 必须添加
"bindings": [
  {"agentId": "main", "match": {"channel": "telegram", "accountId": "default"}},
  // ... 其他
]

案例 3: pass: 格式的 apiKey 不被支持

错误：OpenClaw 不支持 pass: 格式的 apiKey 引用

// ❌ 错误
"apiKey": "pass:api/your-provider"  // 会被当作字符串直接发送

// ✅ 正确
"apiKey": "sk-f873092ea177b75b..."  // 必须硬编码真实 key

快速参考

| 配置项 | 类型 | 说明 | |--------|------|------| | allowFrom | 用户 ID 数组 | DM 白名单（用户 ID） | | groupAllowFrom | 用户 ID 数组 | 群组发送者白名单（用户 ID） | | groups | 对象 | 群组配置（群 ID 作为 key） | | bindings | 数组 | accountId → agentId 映射 | | accounts | 对象 | 多账号配置（key 是 accountId） |

检查清单

修改配置前，确认：

• [ ] 已查阅 config.schema 确认字段类型
• [ ] 已查阅官方文档确认用法
• [ ] 已向用户展示修改方案并获得确认
• [ ] 使用 config.patch 而非 config.apply（除非必要）
• [ ] 修改后验证配置生效

记住

永远不要想当然地修改配置！先查文档，再改配置！