密钥应用计划契约

此页面定义了 openclaw secrets apply 强制执行的严格契约。如果目标不符合这些规则，apply 会在修改任何文件之前失败。

计划文件结构

openclaw secrets apply --from <plan.json> 要求提供包含计划目标的 targets 数组：

{  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" },    },  ],}

openclaw secrets configure 会生成这种结构的计划。你也可以手动编写或编辑计划。

提供商更新插入和删除

计划还可以包含两个可选的顶层字段，用于在写入各个目标的同时修改 secrets.providers 映射：

• providerUpserts -- 以提供商别名为键的对象。每个值都是一个提供商定义（结构与 openclaw.json 中 secrets.providers.<alias> 所接受的结构相同，例如 exec 或 file 提供商）。
• providerDeletes -- 要移除的提供商别名数组。

providerUpserts 在 targets 之前运行，因此 target.ref.provider 可以引用同一计划在 providerUpserts 中引入的提供商别名。如果没有此执行顺序，引用尚未在 openclaw.json 中配置的别名的计划将失败，并显示 provider "<alias>" is not configured。

{  version: 1,  protocolVersion: 1,  providerUpserts: {    onepassword_anthropic: {      source: "exec",      command: "/usr/bin/op",      args: ["read", "op://Vault/Anthropic/credential"],    },  },  providerDeletes: ["legacy_unused_alias"],  targets: [    {      type: "models.providers.apiKey",      path: "models.providers.anthropic.apiKey",      pathSegments: ["models", "providers", "anthropic", "apiKey"],      providerId: "anthropic",      ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" },    },  ],}

通过 providerUpserts 引入的 Exec 提供商仍受 Exec 提供商同意行为中的 Exec 同意规则约束：包含 Exec 提供商的计划在写入模式下需要使用 --allow-exec。

支持的目标范围

计划目标接受 SecretRef 凭证范围中受支持的凭证路径。

目标类型行为

target.type 必须是可识别的目标类型，并且规范化后的 target.path 必须与该类型已注册的路径结构匹配。

除规范类型名称外，某些目标类型还接受兼容性别名作为 target.type，以支持现有计划：

路径验证规则

每个目标都会根据以下所有规则进行验证：

• type 必须是可识别的目标类型。
• path 必须是非空的点分路径。
• 可以省略 pathSegments。如果提供，其规范化结果必须与 path 完全相同。
• 禁止使用以下路径段：__proto__、prototype、constructor。
• 规范化后的路径必须与目标类型已注册的路径结构匹配。
• 如果设置了 providerId 或 accountId，则必须与路径中编码的 ID 匹配。
• auth-profiles.json 目标需要 agentId。
• 创建新的 auth-profiles.json 映射时，请包含 authProfileProvider。

失败行为

如果目标验证失败，apply 会退出并显示类似以下错误：

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

无效计划不会提交任何写入：目标解析和路径验证会在接触任何文件之前运行。另外，有效计划开始写入后，apply 会先为每个涉及的文件创建快照；如果同一次运行中的后续写入失败，则恢复这些快照，因此部分写入绝不会导致配置、身份验证配置文件或环境变量状态不同步。

Exec 提供商同意行为

• 默认情况下，--dry-run 会跳过 Exec SecretRef 检查。
• 在写入模式下，除非设置 --allow-exec，否则包含 Exec SecretRef 或提供商的计划会被拒绝。
• 验证或应用包含 Exec 的计划时，在试运行和写入命令中都要传递 --allow-exec。

运行时和审计范围说明

• 仅含引用的 auth-profiles.json 条目（keyRef/tokenRef）会纳入运行时凭证解析和审计范围。
• secrets apply 会写入受支持的 openclaw.json 目标、受支持的 auth-profiles.json 目标，并执行三个默认启用的可选清理步骤：scrubEnv（从 .env 中移除已迁移的明文值）、scrubAuthProfilesForProviderTargets（针对计划刚迁移的提供商，清除 auth-profiles.json 中残留的明文或未使用引用）和 scrubLegacyAuthJson（从旧版 auth.json 存储中删除已迁移的 api_key 条目）。在计划中将 options.scrubEnv、options.scrubAuthProfilesForProviderTargets 或 options.scrubLegacyAuthJson 中任一项设为 false，即可跳过对应步骤。

操作员检查

# 验证计划但不执行写入openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run # 然后实际应用openclaw secrets apply --from /tmp/openclaw-secrets-plan.json # 对于包含 exec 的计划，在两种模式下都显式选择启用openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

如果 apply 因无效目标路径消息而失败，请使用 openclaw secrets configure 重新生成计划，或将目标路径修正为上述受支持的结构。

相关文档

• 密钥管理
• CLI secrets
• SecretRef 凭证范围
• 配置参考