openclaw-config-helper

OpenClaw Config Helper - Configuration Modification Safety Assistant

⚠️ Mandatory Rules

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

When to use this skill

• The user requests to modify OpenClaw configuration (openclaw.json, agents configuration, channels configuration, etc.)
• The user requests to add/modify channel configurations such as Telegram, WhatsApp, etc.
• The user requests to modify bindings, models, agents.list, etc.
• Any operation involving gateway action=config.patch or gateway action=config.apply operations

Trigger words

• "modify config"
• "change the openclaw config"
• "add a binding"
• "configure telegram/whatsapp"
• "change groupPolicy"
• "add an agent"

Mandatory process (must be executed in order)

Step 1: Consult the Schema

# 获取完整配置 schema
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

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

# 使用 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

Or use search：

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

Step 3: Present the modification plan and confirm

Present to the user:

1. Current configuration(if applicable)
2. Planned modification(specific JSON snippet)
3. Reason for modification
4. Possible impact

Wait for user confirmation before executing the modification!

Step 4: Execute the modification

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

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

Step 5: Verify the modification

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

# 检查 Gateway 状态
openclaw status

Common configuration error cases

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

Error: putting the group ID in groupAllowFrom in

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

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

Lesson：groupAllowFrom is the sender whitelist (user IDs),groups is the group whitelist (group IDs)

Case 2: Missing binding causes bot to be unresponsive

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

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

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

Case 3: apiKey in pass: format is not supported

Error: OpenClaw does not support pass: format apiKey references

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

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

Quick reference

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

Checklist

Before modifying the configuration, confirm:

• Have consulted config.schema Confirm field types
• Have consulted the official documentation to confirm usage
• has already shown the modification plan to the user and obtained confirmation
• use config.patch rather than config.apply(unless necessary)
• verify the configuration takes effect after modification

Remember

Never modify the configuration on assumption! Consult the documentation first, then modify the configuration!