使用手册 · 洞察

配置版本

追踪、比较并安全回滚 Agent 配置变更。

/config

概述#

配置版本是 ClawButler 的配置安全系统。每次从 OpenClaw 同步 Agent 配置时，ClawButler 会自动生成快照。这些快照构成一条版本时间线，让你精确了解哪些配置发生了变化、何时变化、以及变更是否引入了风险。

系统支持语义差异比对（按领域分类的字段级对比）、风险分级（红线与黄线字段）、配置漂移检测（运行时配置与存储配置的比较）、以及带预演模式的回滚。这些能力确保你的 Agent 配置变更是有意为之、可审计且可逆的。

前置条件#

前置条件
  • 至少配置并同步了一个连接器（参见「连接器」）
  • 已发现 Agent 并在 Agent 页面中可见

OpenClaw 侧配置#

Agent 配置通过 config.get RPC 方法从 OpenClaw 网关读取。ClawButler 使用 resolved 视图，其中包含合并了所有默认值的完整配置。这确保你看到的是实际生效的完整配置，而非仅用户级覆盖。

resolved 配置包括 Agent 身份、模型设置（主模型和备用模型）、工具、技能、通道、定时任务和依赖项。直接在 OpenClaw 配置 YAML 中的更改会在下一次同步时被捕获。

提示
ClawButler 始终读取 resolved 配置（已合并默认值），而非原始的 config 视图。这意味着继承自 agents.defaults 的 Agent 会显示完整的生效配置，即使其在 YAML 中的独立条目非常简短。

ClawButler 侧配置#

配置快照自动管理，关键行为如下：

  • -自动快照：每次连接器同步时自动生成新的配置版本，无需手动操作。
  • -作用域追踪：每个快照记录 4 种作用域之一——agent_config、workspace_bundle、bindings 或 dependency_meta——便于按类别筛选变更。
  • -信任基线：你可以手动将任意版本设为信任基线（已知良好的参考点），用于后续比较。这是 TCC（可信变更控制）第 02 步。

使用反馈#

同步后，配置版本页面提供以下内容：

  • -版本时间线：按时间顺序排列的每个 Agent 配置快照列表，包含时间戳、作用域标签和版本 ID
  • -语义差异视图：任意两个版本间的逐字段比较，变更按身份、模型、工具、技能、绑定、依赖分类
  • -风险标识：红线字段（关键级——如 permissions、allowed_tools、security_policy、api_keys）和黄线字段（高级——如 model、temperature、system_prompt）在差异中高亮显示
  • -漂移告警：漂移检测发现运行时配置与存储快照存在差异时，受影响的字段会被标记，并应用噪声过滤（排除时间戳、缓存统计等仅运行时字段）

Web 端操作#

在侧边栏的「洞察」分区中点击「配置版本」进入页面。选择一个 Agent 查看其配置历史。

版本历史

从下拉菜单选择 Agent，然后选择作用域（agent_config、workspace_bundle、bindings 或 dependency_meta）筛选时间线。每条记录显示版本 ID、时间戳和作用域。点击任意版本查看完整快照。

语义差异

从时间线中选择两个版本进行比较。差异视图将变更分为身份、模型、工具、技能、绑定和依赖等领域。每个字段标记为新增、移除或修改。红线字段（permissions、security_policy、api_keys 等）和黄线字段（model、temperature、system_prompt 等）以视觉高亮显示。

漂移检测

点击漂移检测按钮，将 Agent 当前的运行时配置（实时从 OpenClaw 获取）与最新存储快照进行比较。比较过程应用噪声过滤，排除仅运行时字段（时间戳、缓存统计、临时状态），仅报告有实际意义的差异。

回滚

选择目标版本并点击回滚。预演模式会在确认前展示所有将要变更的内容。确认后，ClawButler 应用快照并通过与 OpenClaw 网关的哈希比对验证回滚结果，确保正确执行。

信任基线

将任意版本标记为信任基线——一个已知良好的参考配置。后续差异对比可以针对此基线进行，检测非预期的偏离。这是 TCC（可信变更控制）第 02 步的一部分。

CLI 端操作#

列出指定 Agent 的所有配置版本，按时间排序

Terminal
$ ap config versions <agent_id>

显示两个配置版本之间的语义差异

Terminal
$ ap config diff <agent_id> --v1 <id1> --v2 <id2>

检查运行时配置与存储配置之间的漂移

Terminal
$ ap config drift-check <agent_id>

预览回滚操作（预演模式不实际应用变更）

Terminal
$ ap config rollback <agent_id> --version <id> --dry-run

将当前配置设为信任基线

Terminal
$ ap config baseline <agent_id> --set

移动端操作#

在移动端，配置历史可在 Agent 详情页面中查看。从 Agent 标签页进入某个 Agent，向下滚动到配置历史区域。

  • -按时间排列的配置版本列表，显示作用域和时间戳
  • -点击任意版本查看完整快照内容
  • -下拉刷新以检查同步后的新版本

常见问题#

问：什么操作会触发新的配置快照？
答：每次连接器同步运行时都会自动生成新快照，包括计划同步和手动「同步 Agent」操作。即使配置自上次快照以来没有变化，仍会记录新版本以维护完整的时间线。
问：红线字段和黄线字段有什么区别？
答：红线字段是关键的安全敏感设置：permissions、allowed_tools、blocked_tools、security_policy、max_cost_per_call、kill_switch、api_keys、secrets 和 auth_config。对这些字段的更改需要格外审慎。黄线字段是高影响的运营设置：model、temperature、max_tokens、system_prompt 和 skills。这些变更影响 Agent 行为，但不构成直接的安全风险。
问：可以回滚到任意版本吗？
答：可以。你可以回滚到任何之前捕获的快照。预演模式会在确认前展示所有将要变更的字段。回滚后，ClawButler 通过与 OpenClaw 网关的哈希比对验证结果，确认回滚已正确执行。
配置版本 — ClawButler 用户手册