OpenClaw Safe Config

面向 OpenClaw 网关配置文件的编辑规范：先备份 openclaw.json，再在安装目录的 Node 源码中确认配置键确实存在，用 Python 读写 JSON 避免语法错误，通过 openclaw gateway status 校验无未知键后才重启；另附常见键名对照表与网关崩溃后的备份恢复步骤。

codeinonenight

热度 44.39

最近更新 2026-05-11 17:34:06

分类：开发依赖：代码执行 / 读写文件应用场景：DevOps / 工作流 / 自动化脚本

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add openclaw-safe-config

Metadata

name: openclaw-config
description: Use when editing openclaw.json, adding or changing config keys, troubleshooting a gateway crash after a config change, validating config before restart, or recovering from an unknown key error. Also use when asked to set tools.sessions, agents, channels, compaction, or any gateway setting.

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

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%Y%m%d-%H%M)

2. Verify the key exists in source before adding it

Never guess a config key name. Check the source:

# Replace KEY with the key you're about to add (e.g. "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

Or check the full path:

grep -r "tools\.sessions\." ~/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/*.js \
  | grep -o '"[a-z.]*"' | sort -u

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):

cat ~/.openclaw/openclaw.json | python3 -c "
import json, sys
cfg = json.load(sys.stdin)

# Make your change here, e.g.:
# cfg['tools']['sessions']['visibility'] = 'all'

with open('$HOME/.openclaw/openclaw.json', 'w') as f:
    json.dump(cfg, f, indent=2, ensure_ascii=False)
print('Done')
"

4. Validate before restarting

openclaw gateway status 2>&1 | grep -i "unknown\|invalid\|error"

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

# List backups
ls -lt ~/.openclaw/openclaw.json.bak-* | head -5

# Restore most recent
cp ~/.openclaw/openclaw.json.bak-YYYYMMDD-HHMM ~/.openclaw/openclaw.json

# Restart
openclaw gateway restart

Common Keys + Correct Names

What you want	Correct key path	Valid values
Cross-agent session visibility	`tools.sessions.visibility`	`self` `tree` `agent` `all`
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.