openclaw-ops Skill 实战：给 AI Agent 的配置操作套上缰绳

背景

OpenClaw 的网关配置文件 openclaw.json 是整个系统的命脉——模型、插件、渠道、工具、Agent 全靠它驱动。我让凌云曦（我的 AI Agent）直接用 config.patch 改配置，跑了几周，没出大事，但总觉得哪里不对。

直到有一天它改错了插件配置的一个字段，网关直接挂了，Telegram 通道断了，我人不在电脑前。等我发现的时候已经过了两个小时。

这不是配置能不能改回来的问题——配置当然能改回来。问题是：我让一个 AI 直接操作核心配置，但没有任何流程约束它。它想改就改，改错了才发现。这跟让实习生直接改生产库没什么区别。

我需要一套流程，让 AI Agent 改配置这件事变得可控、可追溯、可回滚。

设计目标

核心诉求很明确：

  1. 改之前必须验证——不能靠猜，不能靠”我之前改过”
  2. 改之前必须确认——Agent 不能自己拍板
  3. 改之前必须备份——出了事能回滚
  4. 改了之后必须记录——谁改的、改了什么、为什么改

还有一个隐性需求：不修改配置的时候也要安全。比如我只是让 Agent “看看当前配置有没有问题”，它不应该趁机改什么。

两种模式的设计

分析下来，Agent 跟配置的交互就两种场景：

场景 动作 风险
“帮我看看这个配置” 只读分析 低
“帮我把 XX 改成 YY” 写入修改 高

如果只给修改动作加流程，分析场景会被拖慢。如果统一流程，分析也要走六步确认，太重了。

所以拆成两种模式：

Mode A：分析模式——只看不动。查 schema、查文档、给结论，然后停下来等指示。

Mode B：修改模式——六步流程，每步不可跳过。

为什么要拆？因为实际使用中，80% 的配置交互是分析。用户说”看看为什么这个插件没生效”，Agent 去查 schema、查文档、对比当前配置，给个结论。这种场景下如果强制走备份→确认→验证流程，效率太低。

但 Mode A 不是”随便看看”——它有自己的流程约束：必须查 schema，必须查官方文档，给出的结论必须有证据支撑。只是不需要备份和确认，因为不动文件。

从 Mode A 转到 Mode B 也有规则：分析完用户说”改吧”，Agent 直接从第三步（形成变更方案）开始，前两步的 schema 和文档证据复用，不重复查。

Mode B 的六步流程

这是整个 skill 的核心。六步走完才算一次合规的配置修改。

Step 1: Schema Lookup

1
config.schema.lookup(path="target.config.key")

验证目标 key 是否存在于 schema 中，类型是否匹配，有没有 enum 约束。

这不是走过场。OpenClaw 的配置结构层级很深，嵌套对象、数组、枚举值混在一起。凭记忆改配置迟早出错。Schema lookup 是客观锚定——这个 key 到底存不存在、类型对不对，不是 Agent 说了算，是 schema 说了算。

如果 schema lookup 失败或 key 不存在：立即停止。 不猜，不绕，不”试试看”。

Step 2: 官方文档验证

单靠 schema 不够。Schema 告诉你字段类型和取值范围，但不会告诉你：

  • 这个字段在不同 provider 下行为是否一致
  • 有没有版本限制
  • 有没有已知的副作用或坑

文档验证的优先级：

  1. QMD 本地索引（最快）
  2. docs.openclaw.ai 官方文档
  3. openclaw --help（兜底）

如果三个来源都找不到相关文档： 明确标注”未找到文档”，只用 schema 约束，不猜。

Step 3: 形成变更方案

把前两步的证据整理成结构化方案，呈现给用户：

  • 目标 key、当前值、拟修改值
  • Schema 证据（类型、约束）
  • 文档证据（来源 URL 或 QMD 引用）
  • 影响范围和风险

这一步的关键是让用户知道要改什么、为什么改、改了会怎样。方案本身就是决策依据。

Step 4: 用户确认

等用户明确同意。没有例外。

用户在 Mode A 分析后说”改吧”触发了 Mode B，但 Step 3 的方案仍然要呈现并确认。这是双重保险：触发是一回事，看到具体方案后确认是另一回事。

Step 5: 备份 + 执行

先备份：

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

备份失败则停止，不继续。

然后用 config.patch 执行修改。一个逻辑变更一次 patch——不同子树的修改必须拆开。

Step 6: 验证 + 日志

1
2
openclaw config validate  # 验证配置合法性
config.get(path="target.key")  # 确认值已生效

所有变更记录到 logs/config-changes.log，包含时间、操作、目标、旧值、新值、依据、备份路径。

四条红线

整个流程有四条绝对不可违反的约束：

  1. 无 schema 验证不修改——“我之前改过”不是证据
  2. 无文档支撑不修改——“应该可以”不是依据
  3. 用户未确认不修改——没有例外
  4. 无备份不修改——备份失败立即停止

这四条写在 skill 的 Hard Prohibitions 里。Agent 违反任何一条，行为就是不合规的。这不是建议，是约束。

双模型交叉审计

Skill 写完了，但有个问题：我怎么确认这套流程本身没有漏洞？

我是用 AI 写的 skill，再让 AI 执行 skill，这是自己审自己。所以我把完整的 skill 内容交给两个独立的模型做交叉审计：

  • MiniMax M2.7：作为外部审查者，逐条检查流程的完备性
  • Kimi Code：从另一个角度审查，重点关注实际执行中的边界情况

两个模型各自独立审计，不互相参考，最后我来汇总。

这个选择不是随便挑的。MiniMax 和 Kimi 是不同的技术栈和训练数据，对同一份流程的关注点会有差异——这正是交叉审计的价值。如果两个模型都指出同一个问题，那大概率是真问题。如果只有一个提到，可能是风格偏好，但也值得看看。

跑出来的 7 个问题

交叉审计跑下来，两个模型合计发现了 7 个真实问题。不是”建议优化”那种客套话，是实际会导致流程失败或安全漏洞的问题。

问题 1：Mode A 转 Mode B 的证据复用规则不明确

原始设计里说 Mode A 分析完用户说”改吧”就转 Mode B，但没说清楚前两步的 schema 和文档证据是否可以直接复用。如果要求重新查一遍，浪费时间。如果不查直接复用，万一分析到确认之间配置已经变了？

修复：明确规则——从 Mode A 转 Mode B 时，Step 1 和 Step 2 的证据可以复用，但 Step 5 执行前必须用 config.get 刷新当前值。如果当前值和 Mode A 分析时的值不同，需要重新走 Step 3。

问题 2：紧急修改没有快速通道

半夜网关挂了，需要紧急改配置，六步流程走完可能要十分钟。生产环境等不了。

修复：增加了紧急模式标记，流程不变（六步还是六步），但允许 Step 4 的确认走简短确认（比如用户说”紧急修复，确认”）。日志里标注 emergency: true。没有跳过任何步骤，只是降低确认的形式要求。

问题 3：config.patch 和 config.apply 的选择标准模糊

原始设计只说”优先用 patch”，没说清楚什么场景下必须用 apply，什么场景下 patch 搞不定要用 exec + Python。

修复：明确了三层降级路径：config.patch（部分更新，首选）→ config.apply（整个 section 替换）→ exec + Python JSON 编辑（删除 key 等特殊操作）。每层都给了适用场景。

问题 4：备份目录可能不存在

Step 5 的备份命令直接 cp 到 ~/.openclaw/backups/，但这个目录不一定存在。第一次跑就报错，还以为是权限问题。

修复：备份前先 mkdir -p 确保目录存在。

问题 5：变更日志格式缺少关键字段

原始日志格式没有记录备份文件路径和 schema 验证状态。出了问题要追溯时，得手动去找对应时间的备份文件。

修复：日志格式增加了 schema_verified、doc_source、user_approved、backup 四个字段。

问题 6：”一个逻辑变更”的定义不清

“一次只改一个东西”这个原则好说，但什么叫”一个”？加一个模型算一个，那加模型同时把它设为 fallback 算一个还是两个？

修复：给出了明确定义——同一子树内、服务于同一用户意图的变更算一个逻辑变更。跨子树的必须拆开。并给了具体的判断表。

问题 7：Schema lookup 对数组元素的处理不明确

配置里有数组类型的字段（比如 plugins.entries），查 schema 时需要知道怎么处理数组内的单个元素。

修复：增加了 Schema Drill-Down 指引——嵌套结构逐层查，用 * 通配符查数组元素的结构。

设计取舍

做这个 skill 的过程中有几个取舍值得说说。

为什么不用 JSON Schema 直接做运行时校验？

OpenClaw 已经有 config.validate 命令做运行时校验。但那是事后校验——改完了才知道对不对。Skill 的流程是事前校验——改之前就确认类型、约束、文档依据都对了。两者不冲突，互为补充。

为什么不让 Agent 自动判断风险等级？

试过。Agent 对”这个改动风险大不大”的判断不可靠。低风险改错也能把网关搞挂。所以最终选择了统一流程——所有修改操作走同一个六步流程，不区分风险等级。流程本身不重，六步走完也就一两分钟，不值得为了省这一两分钟去搞分级。

为什么交叉审计用两个模型而不是一个？

一个模型的审计有盲区——它对自己擅长的地方审查细致，不擅长的地方直接忽略。两个不同技术栈的模型交叉审，覆盖面更广。实际跑下来确实如此：MiniMax 更关注流程完备性，Kimi 更关注边界情况和执行细节。

实际效果

这套流程上线后跑了将近两周，期间 Agent 执行了十几次配置修改操作，零事故。

几个体感变化：

  1. 配置修改不再”凭感觉”：每次修改都有 schema + 文档双验证，Agent 不再靠记忆操作
  2. 可追溯性大幅提升：config-changes.log 里每次修改的完整上下文都有，出了问题能定位
  3. 用户确认环节拦住过一次误操作：Agent 提议修改一个 plugin 配置，我看了方案发现理解偏了，没让它改

最大的收获不是这套流程本身，而是给 AI Agent 的操作建立流程约束这件事是值得投入的。Agent 不是人，不会”小心点”，只能靠流程兜底。

适用边界

这套方案适合以下场景：

  • AI Agent 需要操作结构化配置文件（JSON/YAML）
  • 配置修改有潜在破坏性（影响服务可用性）
  • 需要可追溯和可回滚

不适合的场景：

  • 高频低风险配置变更（流程成本大于收益）
  • 实时性要求极高的场景（六步流程有延迟）
  • 配置文件结构不固定（没有 schema 可查）

如果有人也在做类似的”AI Agent 安全操作流程”，核心思路可以复用：事前验证、强制确认、必须备份、事后记录。具体步骤根据你的场景调整就行。

后续计划

目前还有两个待改进的点：

  1. Mode A 分析结果的缓存：短时间内多次分析同一 key，schema 和文档不需要每次重新查。可以做个短时缓存（比如 5 分钟），降低 token 消耗。
  2. 变更方案的 diff 展示：目前 Step 3 的方案是文字描述，理想情况应该直接展示 JSON diff，更直观。
许可协议

本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。

快来参与讨论吧~