OpenClaw Safe Config

Use when editing openclaw.json, adding or changing config keys, troubleshooting a gateway crash after a config change, validating config before restart, or r...

Security Scan

The instructions are coherent with a safe, local configuration-edit helper for openclaw.json — they only operate on local files, back up before changing, verify keys against local source, and validate before restart.

Purpose & Capability

The skill's name/description match the actions in SKILL.md: it backs up ~/.openclaw/openclaw.json, verifies key names against openclaw source, edits JSON via a safe Python snippet, validates via the openclaw CLI, and provides recovery steps. All requested operations are proportional to editing/validating config.

Instruction Scope

Instructions are narrowly scoped to the gateway config and local openclaw installation. One practical caveat: the grep path is hard-coded to an nvm node_modules path (~/.nvm/versions/node/v22.22.0/...), which may not exist on the user's system and could cause false negatives when verifying keys; the grep usage also requires the user to replace the KEY placeholder. Otherwise the steps do not read or transmit external data beyond the local filesystem and the local 'openclaw' CLI.

Install Mechanism

No install spec or code is included; this is instruction-only, so nothing is written or downloaded by the skill itself.

Credentials

The skill declares no environment variables or credentials and the instructions do not request secrets or unrelated configuration. All file accesses are to local openclaw files and (optionally) local node_modules for verification.

Persistence & Privilege

always is false and the skill does not request persistent system presence or modify other skills or system-wide agent settings. The default model-invocation setting (allowing autonomous calls) is normal and not problematic here given the limited, local scope of the instructions.

Assessment

This skill is an instruction-only helper for safely editing ~/.openclaw/openclaw.json. Before using it: confirm you have the openclaw CLI installed and working; ensure the hard-coded grep path matches where openclaw is installed on your system (your node/npm installation might be in a different path); replace the KEY placeholder in the grep commands when verifying keys; run the backup step before any edit and test restores in a safe environment if possible. The skill's commands operate only on local files and do not exfiltrate secrets.

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.