openclaw-config
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.
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/codeinonenight/openclaw-safe-configopenclaw-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
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-codeinonenight-openclaw-safe-config": {
"enabled": true,
"auto_update": true
}
}
}