openclaw-config-helper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

OpenClaw Config Helper - Secure Configuration Modification Assistant

⚠️ 强制规则

⚠️ Mandatory Rules

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

Before modifying any OpenClaw configuration, you must complete the following steps, otherwise it may cause system crash or functional abnormality!

当使用此技能

When to use this skill

用户要求修改 OpenClaw 配置（openclaw.json、agents 配置、channels 配置等）
用户要求添加/修改 Telegram、WhatsApp 等渠道配置
用户要求修改 bindings、models、agents.list 等

任何涉及

gateway action=config.patch

或

gateway action=config.apply

的操作

User requests to modify OpenClaw configuration (openclaw.json, agents configuration, channels configuration, etc.)
User requests to add/modify channel configurations such as Telegram, WhatsApp, etc.
User requests to modify bindings, models, agents.list, etc.

Any operation involving

gateway action=config.patch

gateway action=config.apply

触发词

Trigger Words

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

"modify configuration"
"change OpenClaw configuration"
"add a binding"
"configure telegram/whatsapp"
"modify groupPolicy"
"add an agent"

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

Mandatory Process (must be executed in order)

步骤 1: 查阅 Schema

Step 1: Consult Schema

bash

undefined

bash

undefined

获取完整配置 schema

Get full configuration schema

gateway action=config.schema


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

gateway action=config.schema


**Check points**:
- Confirm the type of the field to be modified (string/number/array/object)
- Confirm whether the field is required
- Confirm the allowed values of the field (enum)
- Confirm the nested structure

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

Step 2: Consult official documentation (if schema is not clear enough)

bash

undefined

bash

undefined

使用 web_fetch 获取官方文档

Use web_fetch to get official documentation

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


**或者使用搜索**：
```bash
cd ~/clawd/skills/tavily && ./scripts/tavily.sh search "OpenClaw <配置项> 配置"

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


**Or use search**:
```bash
cd ~/clawd/skills/tavily && ./scripts/tavily.sh search "OpenClaw <configuration item> configuration"

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

Step 3: Present modification plan and get confirmation

向用户展示：

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

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

Present to the user:

Current configuration (if applicable)
Planned modification (specific JSON snippet)
Reason for modification
Possible impact

Wait for user confirmation before executing the modification!

步骤 4: 执行修改

Step 4: Execute modification

bash

undefined

bash

undefined

使用 config.patch 进行部分修改（推荐）

Use config.patch for partial modification (recommended)

gateway action=config.patch raw='{"修改的路径": "值"}'

gateway action=config.patch raw='{"modified path": "value"}'

或使用 config.apply 进行完整替换（谨慎使用）

Or use config.apply for full replacement (use with caution)

gateway action=config.apply raw='{"完整配置": "..."}'

undefined

gateway action=config.apply raw='{"full configuration": "..."}'

undefined

步骤 5: 验证修改

Step 5: Verify modification

bash

undefined

bash

undefined

检查配置是否生效

Check if the configuration takes effect

gateway action=config.get

检查 Gateway 状态

Check Gateway status

openclaw status

undefined

openclaw status

undefined

常见配置错误案例

Common Configuration Error Cases

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

Case 1: Telegram groupAllowFrom error (2026-02-22)

错误：把群 ID 放在

groupAllowFrom

里

json

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

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

教训：

groupAllowFrom

是发送者白名单（用户 ID），

groups

是群组白名单（群 ID）

Error: Put group ID in

groupAllowFrom

json

// ❌ Wrong
"groupAllowFrom": [-1003531486855, -1003890797239]  // These are group IDs, not user IDs!

// ✅ Correct
"groupAllowFrom": ["8518085684"]  // User ID
"groups": {
  "-1003531486855": {"groupPolicy": "open", "requireMention": true}
}

Lesson:

groupAllowFrom

is the sender whitelist (user ID),

groups

is the group whitelist (group ID)

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

Case 2: Bot does not respond due to missing binding

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

json

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

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

Error: The main bot (default account) is not bound to any agent

json

// ❌ Missing default → main binding
"bindings": [
  {"agentId": "ops", "match": {"accountId": "xiaoops"}},
  // ... Other bots, but no default
]

// ✅ Must be added
"bindings": [
  {"agentId": "main", "match": {"channel": "telegram", "accountId": "default"}},
  // ... Others
]

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

Case 3: apiKey in pass: format is not supported

错误：OpenClaw 不支持

pass:

格式的 apiKey 引用

json

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

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

Error: OpenClaw does not support

pass:

format apiKey reference

json

// ❌ Wrong
"apiKey": "pass:api/xingsuancode"  // Will be sent directly as a string

// ✅ Correct
"apiKey": "sk-f873092ea177b75b..."  // Must hardcode the real key

快速参考

Quick Reference

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

Configuration Item	Type	Description
`allowFrom`	User ID array	DM whitelist (user ID)
`groupAllowFrom`	User ID array	Group sender whitelist (user ID)
`groups`	Object	Group configuration (group ID as the key)
`bindings`	Array	accountId → agentId mapping
`accounts`	Object	Multi-account configuration (accountId as the key)

检查清单

Checklist

修改配置前，确认：

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

Before modifying the configuration, confirm:

Have checked
```
config.schema
```
to confirm the field type
Have consulted the official documentation to confirm the usage
Have presented the modification plan to the user and obtained confirmation
Use
```
config.patch
```
instead of
```
config.apply
```
(unless necessary)
Verify that the configuration takes effect after modification

记住

Remember

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

Never modify the configuration based on assumptions! Always check the documentation first before making any changes!