配置安全编辑

编辑配置文件，不引发系统故障。

问题所在

配置文件是智能体造成**不可逆损坏**风险最高的地方。一次误操作（如敲错一个字符），就可能导致系统无法启动。本技能使配置变更具备可预测性与可回滚性。

核心原则

备份 → 编辑 → 对比 → 提交或恢复

绝不在无法撤销的前提下直接编辑配置文件。

标准工作流（5 步）

步骤 1：明确变更范围

动手前，务必回答以下问题：

1. 修改哪个文件？ 给出完整路径。
2. 修改哪些字段？ 精确到 key 路径（例如 gateway.port）。
3. 如何修改？ 明确变更前/后的具体值。

任一问题答案不明确 → 立即停止并提问。

步骤 2：选择合适工具

始终需用直接编辑的受保护路径：appId、clientSecret、appSecret、token、apiKey、apiKey*、password

判断字段是否受保护：先尝试 config.patch；若报错 “cannot change protected config paths” → 改用直接编辑。

步骤 3：编辑前先定位

使用搜索定位精确行号，再精准编辑：

# 查找字段及其上下文
grep -n "the_field_name" /path/to/config.json

# PowerShell 等效命令
Select-String -Path "C:pathtoconfig.json" -Pattern "the_field_name" -Context 0,2

禁止盲目编辑。 务必确认你清楚要修改的是哪一处匹配项。

步骤 4：执行备份

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

# Windows
Copy-Item "C:pathtoconfig.json" "C:pathtoconfig.json.backup"

始终覆盖同一备份文件 — 不添加日期后缀。 这确保磁盘上仅保留一份备份。待 diff 确认变更无误后，该备份即不再需要，并可在下次编辑时被新备份覆盖。

步骤 5：重启前执行对比

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

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

仅当 diff 输出完全符合预期时，才继续操作。 出现任何非预期行 → 立即回退。

常见失败模式

1. 对受保护字段误用工具

现象：gateway config.patch 报错 “cannot change protected config paths”
修复：改用 edit 工具直接编辑文件

2. 字段名拼写错误

现象：配置看似正确，但系统行为异常
修复：始终先执行搜索（步骤 3），切勿猜测字段名

3. JSON 语法错误

现象：Gateway 无法启动，报错提示 JSON 解析失败
修复：编辑前务必校验 JSON 合法性：python3 -c "import json; json.load(open('config.json'))"

4. 多余逗号或缺失括号

现象：同上 — JSON 结构损坏
修复：每次编辑后、重启前，必须再次校验 JSON 合法性

5. 仅存在单个备份文件

问题：备份文件每次都被覆盖 — 无历史版本留存
修复：若需为高风险编辑保留带日期的时间点快照，请手动执行：cp config.json config.json.backup.2026-05-07。标准工作流默认采用单文件覆盖式备份。

恢复检查清单

发生异常时：

1. 用 diff 对比当前文件与备份 → 定位非预期变更
2. 将备份覆盖当前文件：cp backup.json config.json
3. 校验 JSON 合法性：python3 -c "import json; ..." 或 Get-Content x.json | ConvertFrom-Json
4. 仅当 JSON 校验通过后 → 才可重启

速查备忘

SCOPE:   修改哪个文件？哪个字段？新值是什么？
LOCATE:  编辑前先用 grep / Select-String 定位
BACKUP:  cp config.json config.json.backup   # 覆盖安全，不加日期后缀
EDIT:    使用 edit 工具 或 config.patch
DIFF:    对比 backup 与新文件 — 仅当完全匹配才继续
RECOVER: cp config.json.backup config.json → 校验 → 重启

可跳过本技能的情形

• 只读操作（查看配置、搜索内容）
• 非关键文件（用户偏好设置、界面外观配置等）
• 自带自动备份机制的文件（例如已纳入版本控制的配置文件）

以下情形必须使用本技能：凭据（credentials）、API 密钥（API keys）、服务器地址（server addresses）、端口号（port numbers）、安全配置（security settings）、通道配置（channel configurations）。

高危编辑：OpenClaw 启动文件

某些编辑可能致使你彻底失去对自身系统的访问权限。请对此类操作格外审慎。

属于高危编辑的情形

以下字段的编辑属于高危操作 — 可能导致 OpenClaw 无法启动：

• gateway.port、gateway.bind、gateway.auth
• plugins、plugins.allow、plugins.entries
• meta.version、meta.lastTouchedVersion
• channels（通道配置错误可能导致插件加载器崩溃）

高危编辑工作流（额外增加 2 步）

编辑前：手动创建带日期的快照备份：

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

编辑完成后、确认“可重启”前：务必校验 JSON 语法：

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

若 Python 无输出 → JSON 合法；若抛出异常 → 存在语法错误，须修复后方可继续。

重启后：若 Gateway 无法恢复运行：

1. OpenClaw 每次保存配置时会自动生成 .bak 文件 — 在同目录下查找最新版本
2. 若该目录可从外部访问（例如通过文件资源管理器）：还原对应 .bak 文件
3. 若 Gateway 完全无响应：即为真正意义上的“锁死”，需人工介入处理

客观限制说明

若 JSON 语法合法，但语义错误（例如填入错误的端口号），Gateway 将能正常启动，但行为异常。此类问题**无自动化修复手段**，必须依赖人工诊断。最有效的防御措施是 步骤 1（明确变更范围）：动手前，务必清晰知晓你要修改什么、为何修改。