Secrets apply plan contract

此页面定义了由 openclaw secrets apply 强制执行的严格合约。

如果目标不符合这些规则，apply 将在变更配置之前失败。

Plan file shape

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

提供商插入和删除

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

providerUpserts — 一个以提供商别名为键的对象。每个值是一个提供商定义（与 openclaw.json 中 secrets.providers.<alias> 下接受的形状相同，例如 exec 或 file 提供商）。
providerDeletes — 要删除的提供商别名数组。

providerUpserts 在 targets 之前运行，因此 target.ref.provider 可以引用同一计划在 providerUpserts 中引入的提供商别名。如果没有这一点，引用 openclaw.json 中尚未配置别名的计划将失败，并提示 提供商 "<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 提供商 consent behavior 中的 exec 同意规则：包含 exec 提供商的计划需要处于写入模式的 --allow-exec。

支持的目标范围

计划目标被接受用于以下位置中支持的凭证路径：

SecretRef Credential Surface

目标类型行为

通用规则：

target.type 必须被识别，并且必须匹配规范化的 target.path 形状。

兼容性别名对于现有计划仍然被接受：

models.providers.apiKey
skills.entries.apiKey
channels.googlechat.serviceAccount

路径验证规则

每个目标都通过以下所有内容进行验证：

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

对于无效的计划，不会提交任何写入操作。

Exec 提供商同意行为

--dry-run 默认跳过 exec SecretRef 检查。
除非设置了 --allow-exec，否则在写入模式下会拒绝包含 exec SecretRefs/提供商的计划。
在验证/应用包含 exec 的计划时，请在 dry-run 和 write 命令中都传递 --allow-exec。

运行时和审计范围说明

仅 Ref 的 auth-profiles.json 条目（keyRef/tokenRef）包含在运行时解析和审计覆盖范围内。
secrets apply 写入支持的 openclaw.json 目标、支持的 auth-profiles.json 目标以及可选的 scrub 目标。

Operator 检查

# Validate plan without writes
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# Then apply for real
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

# For exec-containing plans, opt in explicitly in both modes
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

如果 apply 失败并显示无效的目标路径消息，请使用 openclaw secrets configure 重新生成计划，或将目标路径修复为上述支持的形状。