Config Safe Edit

安全修改配置文件的系统性流程。当需要修改 openclaw.json、models.json、或其他任何系统配置文件时激活。核心价值：改前备份 + 版本对比 + 确认差异后再操作。适合：（1）修改任何配置文件前；（2）升级后出现异常需要溯源；（3）无法确认某字段来源时；（4）用户要求验证配置变化时。避免因配置错误...

Edit config files without breaking things.

The Problem

Configuration files are where agents cause the most irreversible damage. One wrong keystroke and your system won't start. This skill makes config changes predictable and reversible.

Core Principle

Backup → Edit → Diff → Commit or Recover

Never edit a config file without being able to undo it.

---

Standard Workflow (5 Steps)

Step 1: Scope the Change

Before touching anything, answer these:

1. What file? Full path.
2. What fields? Exact key paths.
3. What should change? Before/after values.

If any answer is unclear → stop and ask.

Step 2: Choose Your Tool

Tool	When to use
gateway config.patch	Safe, validates JSON, hot-reload when possible
Direct file edit (edit tool)	Credentials, protected paths, or when patch fails

Protected paths that always need direct edit: appId, clientSecret, appSecret, token, apiKey, apiKey*, password

Test if a field is protected by trying config.patch first. If it errors with "cannot change protected config paths" → use direct edit.

Step 3: Locate Before You Edit

Use search to find exact line numbers, then edit precisely:

bash

# Find field and surrounding context
grep -n "the_field_name" /path/to/config.json

powershell

# PowerShell equivalent
Select-String -Path "C:\path\to\config.json" -Pattern "the_field_name" -Context 0,2

Never do blind edits. Always confirm you know exactly which occurrence to change.

Step 4: Backup

bash

# Linux/Mac
cp /path/to/config.json /path/to/config.json.backup

# Windows
Copy-Item "C:\path\to\config.json" "C:\path\to\config.json.backup"

Always overwrite the same file — no date suffix. This keeps exactly one backup on disk. After diff confirms the change is correct, the backup is no longer needed and can be overwritten by the next edit.

Step 5: Diff Before Restarting

bash

# Linux/Mac
diff /path/to/config.json.backup.* /path/to/config.json

# PowerShell
diff (Get-Content "config.bak") (Get-Content "config.json")

Only proceed if diff shows exactly what you intended. Any unexpected lines = revert immediately.

---

Common Failure Patterns

1. Protected field with wrong tool

Symptom: gateway config.patch errors with "cannot change protected config paths" Fix: Use direct edit on the file instead

2. Typo in field name

Symptom: Config appears correct but system behaves unexpectedly Fix: Always search first (Step 3), don't guess field names

3. JSON syntax error

Symptom: Gateway won't start, error about JSON parse failure Fix: Before any edit, validate JSON: python3 -c "import json; json.load(open('config.json'))"

4. Trailing comma or missing bracket

Symptom: Same as above — JSON malforms Fix: After any edit, always validate JSON before restarting

5. Only one backup file exists

Problem: Backup is overwritten each time — no historical versions Fix: If you need a dated snapshot before a risky edit, manually cp config.json config.json.backup.2026-05-07 first. The standard workflow uses a single overwrite-safe backup.

---

Recovery Checklist

When something goes wrong:

1. diff current vs backup → identify the unexpected change
2. Copy backup over current: cp backup.json config.json
3. Validate JSON: python3 -c "import json; ..." or Get-Content x.json | ConvertFrom-Json
4. Only after JSON validates clean → restart

---

Quick Reference

text

SCOPE:   What file, what field, what's new value?
LOCATE:  grep/Select-String before touching anything
BACKUP:  cp config.json config.json.backup   # overwrite-safe, no date suffix
EDIT:    edit tool or config.patch
DIFF:    diff backup vs new — only proceed if exact match
RECOVER: cp config.json.backup config.json → validate → restart

When to Skip This Skill

• Read-only operations (reading config, searching)
• Non-critical files (user preferences, cosmetic settings)
• Files with automatic backup (version-controlled config files)

Always use this for: credentials, API keys, server addresses, port numbers, security settings, channel configurations.

---

High-Risk Edits: OpenClaw Startup Files

Some edits can lock you out of your own system. Treat these with extra care.

What Counts as High-Risk

Edits to these fields are high-risk — they can prevent OpenClaw from starting:

• gateway.port, gateway.bind, gateway.auth
• plugins, plugins.allow, plugins.entries
• meta.version, meta.lastTouchedVersion
• channels (channel misconfiguration can crash the plugin loader)

High-Risk Workflow (adds 2 extra steps)

Before the edit: Manually create a dated snapshot backup:

bash

# Windows
Copy-Item "openclaw.json" "openclaw.json.backup.$(Get-Date -Format 'yyyy-MM-dd')"

After the edit, before saying "OK to restart": Always validate JSON syntax:

bash

# Windows PowerShell
python3 -c "import json; json.load(open('C:/path/to/openclaw.json'))"

If Python returns nothing → JSON is valid. If it throws an exception → syntax error, fix before continuing.

After restart: If Gateway won't come back:

1. OpenClaw auto-generates .bak files on each config save — find the latest one in the same directory
2. If the directory is accessible from outside (e.g., via Explorer): restore the .bak file
3. If Gateway is completely unresponsive: this is a true lockout — human intervention required

Honest Limit

If the JSON is valid but the config is semantically wrong (e.g., wrong port number), Gateway will start but behave unexpectedly. There is no automated fix for this — it requires human diagnosis. The best defense is Step 1 (Scope): always know exactly what you're changing and why before you touch anything.