openclaw-config
Safe protocol for editing ~/.openclaw/openclaw.json. Wrong key names silently break the gateway — this skill prevents that.
The Protocol (Always Follow This Order)
1. Backup first
CODEBLOCK0
2. Verify the key exists in source before adding it
Never guess a config key name. Check the source:
CODEBLOCK1
Or check the full path:
CODEBLOCK2
If the key doesn't appear in source → it doesn't exist, don't add it.
3. Edit the config
Use Python to safely read/modify/write (avoids JSON syntax errors):
CODEBLOCK3
4. Validate before restarting
CODEBLOCK4
Doctor will flag unknown keys. If you see any → restore from backup, don't restart.
5. Restart only when clean
openclaw gateway restart
Recovery: If the Gateway Breaks
CODEBLOCK6
Common Keys + Correct Names
| What you want | Correct key path | Valid values |
|---|
| Cross-agent session visibility | INLINECODE1 | INLINECODE2 tree agent INLINECODE5 |
| Agent-to-agent messaging |
tools.agentToAgent.enabled |
true /
false |
| Compaction trigger threshold |
agents.defaults.compaction.maxHistoryShare |
0.0–
1.0 |
| Compaction mode |
agents.defaults.compaction.mode |
default safeguard |
| Reserve tokens before compaction |
agents.defaults.compaction.reserveTokens | integer |
| Primary model |
agents.defaults.model.primary |
provider/model-id |
| Tool allow/deny |
tools.allow /
tools.deny | array of tool names |
What NOT to Do
- - ❌ Guessing key names — always verify in source first
- ❌ Direct string editing of the JSON file — use Python to avoid syntax errors
- ❌ Restarting before validating — doctor catches unknown keys
- ❌ Skipping backup — a 5-second backup saves a 10-minute recovery
Why This Matters
A single unknown key in openclaw.json makes the gateway refuse to start. There's no warning — it just fails. The backup + source verification + doctor flow takes 30 seconds and prevents complete system outages.
Real example: tools.sessions.scope (doesn't exist) vs tools.sessions.visibility (correct) — one character difference, gateway down.
openclaw-config
编辑~/.openclaw/openclaw.json的安全协议。错误的键名会静默破坏网关——本技能可防止这种情况发生。
协议（请始终按此顺序执行）
1. 先备份
bash
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%Y%m%d-%H%M)
2. 添加前先在源码中验证键是否存在
切勿猜测配置键名。请检查源码：
bash
将KEY替换为你要添加的键（例如visibility、agentToAgent）
grep -r cfg\. ~/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/*.js \
| grep -o [a-zA-Z.]
KEY[a-zA-Z.] | sort -u | head -10
或检查完整路径：
bash
grep -r tools\.sessions\. ~/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/*.js \
| grep -o [a-z.]* | sort -u
如果该键未出现在源码中 → 该键不存在，不要添加。
3. 编辑配置
使用Python安全地读取/修改/写入（避免JSON语法错误）：
bash
cat ~/.openclaw/openclaw.json | python3 -c
import json, sys
cfg = json.load(sys.stdin)
在此处进行修改，例如：
cfg[tools][sessions][visibility] = all
with open($HOME/.openclaw/openclaw.json, w) as f:
json.dump(cfg, f, indent=2, ensure_ascii=False)
print(完成)
4. 重启前先验证
bash
openclaw gateway status 2>&1 | grep -i unknown\|invalid\|error
诊断工具会标记未知键。如果看到任何错误 → 从备份恢复，不要重启。
5. 仅在干净状态时重启
bash
openclaw gateway restart
恢复：如果网关崩溃
bash
列出备份
ls -lt ~/.openclaw/openclaw.json.bak-* | head -5
恢复最近的备份
cp ~/.openclaw/openclaw.json.bak-YYYYMMDD-HHMM ~/.openclaw/openclaw.json
重启
openclaw gateway restart
常用键 + 正确名称
| 你想要的功能 | 正确的键路径 | 有效值 |
|---|
| 跨代理会话可见性 | tools.sessions.visibility | self tree agent all |
| 代理间消息传递 |
tools.agentToAgent.enabled | true / false |
| 压缩触发阈值 | agents.defaults.compaction.maxHistoryShare | 0.0–1.0 |
| 压缩模式 | agents.defaults.compaction.mode | default safeguard |
| 压缩前保留令牌数 | agents.defaults.compaction.reserveTokens | 整数 |
| 主模型 | agents.defaults.model.primary | provider/model-id |
| 工具允许/拒绝 | tools.allow / tools.deny | 工具名称数组 |
禁止操作
- - ❌ 猜测键名——始终先在源码中验证
- ❌ 直接字符串编辑JSON文件——使用Python避免语法错误
- ❌ 在验证前重启——诊断工具会捕获未知键
- ❌ 跳过备份——5秒的备份能节省10分钟的恢复时间
为何如此重要
openclaw.json中单个未知键就会导致网关拒绝启动。没有任何警告——它只是直接失败。备份+源码验证+诊断工具流程只需30秒，却能防止整个系统宕机。
真实案例：tools.sessions.scope（不存在）vs tools.sessions.visibility（正确）——仅一个字符之差，网关崩溃。
