Secrets Apply Plan 合约

本文档定义了 openclaw secrets apply 命令强制执行的严格合约（strict contract）。如果 Plan 中的目标（targets）违反任何规则，apply 将在修改配置之前失败退出。

原子性保证

如果 Plan 中任何一个 target 验证失败，apply 会立即退出且不会写入任何更改。无效的 Plan 不会产生部分写入。

Plan 文件格式

openclaw secrets apply 命令期望一个包含 targets 数组的 JSON Plan 文件：

json5

{
  "version": 1,
  "protocolVersion": 1,
  "targets": [
    {
      "type": "models.providers.apiKey",
      "path": "models.providers.openai.apiKey",
      "pathSegments": ["models", "providers", "openai", "apiKey"],
      "providerId": "openai",
      "ref": {
        "source": "env",
        "provider": "default",
        "id": "OPENAI_API_KEY"
      }
    },
    {
      "type": "auth-profiles.api_key.key",
      "path": "profiles.openai:default.key",
      "pathSegments": ["profiles", "openai:default", "key"],
      "agentId": "main",
      "ref": {
        "source": "env",
        "provider": "default",
        "id": "OPENAI_API_KEY"
      }
    }
  ]
}

字段说明

字段	类型	必填	说明
`version`	`number`	是	Plan 文件版本
`protocolVersion`	`number`	是	协议版本
`targets`	`array`	是	目标数组
`targets[].type`	`string`	是	目标类型（必须是已注册的类型）
`targets[].path`	`string`	是	非空的点分隔路径
`targets[].pathSegments`	`string[]`	否	路径片段数组（如提供，必须与 `path` 一致）
`targets[].providerId`	`string`	否	Provider ID（如设置，必须与路径中编码的 ID 匹配）
`targets[].accountId`	`string`	否	账号 ID（如设置，必须与路径中编码的 ID 匹配）
`targets[].agentId`	`string`	条件	Agent ID（`auth-profiles.json` 目标必填）
`targets[].authProfileProvider`	`string`	条件	创建新的 `auth-profiles.json` 映射时需要
`targets[].ref`	`object`	是	SecretRef 引用对象

验证规则

Plan 中的每个 target 都必须通过以下所有验证规则：

1. 类型验证

type 必须是已注册的目标类型。不支持的类型将导致验证失败。

2. 路径验证

path 必须是非空的点分隔路径
标准化后的路径（normalized path）必须匹配目标类型的已注册路径模式

3. 路径片段一致性

pathSegments 是可选字段。如果提供，标准化后的结果必须与 path 完全一致。

4. 禁止的路径片段

以下路径片段会被拒绝，以防止原型链污染攻击：

__proto__
prototype
constructor

5. ID 一致性

如果设置了 providerId 或 accountId，它们必须与路径中编码的 ID 匹配。

6. Auth Profiles 专属规则

auth-profiles.json 类型的目标必须包含 agentId 字段
创建新的 auth-profiles.json 映射时，需要包含 authProfileProvider 字段

支持的目标类型

目标类型必须属于 SecretRef 凭证表面定义的范围。

主要类型别名

类型	说明
`models.providers.apiKey`	模型 Provider 的 API Key
`auth-profiles.api_key.key`	Auth Profile 中的 API Key
`auth-profiles.token.token`	Auth Profile 中的 Token
`skills.entries.apiKey`	Skill 条目的 API Key
`channels.googlechat.serviceAccount`	Google Chat Service Account（兼容性别名）

写入范围

apply 命令写入以下内容：

支持的 openclaw.json 目标 — 模型 Provider、渠道凭证、Gateway 认证等
支持的 auth-profiles.json 目标 — keyRef / tokenRef 引用
可选的 scrub 目标 — 清理旧的明文值

失败行为

当 target 验证失败时：

apply 立即退出并返回错误
不会写入任何更改（零部分写入）
错误信息会指出具体的验证问题

错误示例：

Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl

操作员检查

试运行（Dry Run）

使用 --dry-run 参数在不写入任何更改的情况下验证 Plan：

bash

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

执行应用

验证无误后执行实际写入：

bash

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

修复失败的 Plan

如果 apply 失败，可以：

使用 openclaw secrets configure 重新生成 Plan
手动修复 target 路径
再次使用 --dry-run 验证后执行

审计与运行时

Auth profile 中的 ref-only 条目（keyRef / tokenRef）包含在运行时解析和审计覆盖范围内
apply 命令会记录所有写入操作，便于事后审计

Secrets Apply Plan 合约 ​

Plan 文件格式 ​

字段说明 ​

验证规则 ​

1. 类型验证 ​

2. 路径验证 ​

3. 路径片段一致性 ​

4. 禁止的路径片段 ​

5. ID 一致性 ​

6. Auth Profiles 专属规则 ​

支持的目标类型 ​

主要类型别名 ​

写入范围 ​

失败行为 ​

操作员检查 ​

试运行（Dry Run） ​

执行应用 ​

审计与运行时 ​

相关文档 ​