Secrets 应用计划契约

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

计划文件要求¶

openclaw secrets apply --from <plan.json> 接受大小不超过 16 MiB（16,777,216 字节）的普通文件。该限制适用于完整的序列化文件，包括空白字符。目录、FIFO、设备文件以及超过该限制的文件会在 JSON 解析或目标校验之前被拒绝。

openclaw secrets configure --plan-out <plan.json> 在创建文件之前，会对 UTF-8 序列化输出强制执行相同的限制。手写计划和外部计划生成器也必须将序列化文件保持在此边界之内。

计划文件形状¶

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 以此形状生成计划。你也可以手写或编辑一份计划。

提供者 upsert 与删除¶

计划还可以包含两个可选的顶层字段，它们会在逐目标写入的同时修改 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 Credential Surface 中受支持的凭据路径。

目标类型行为¶

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

某些目标类型除了其规范类型名称之外，还接受一个兼容别名作为 target.type，用于现有计划：

路径校验规则¶

每个目标均需通过以下所有校验：

• type 必须是可识别的目标类型。
• path 必须是非空点路径。
• pathSegments 可以省略。若提供，其规范化结果必须与 path 完全一致。
• 禁止的段会被拒绝：__proto__、prototype、constructor。
• 规范化后的路径必须匹配该目标类型注册的路径形状。
• 若设置了 providerId 或 accountId，则必须匹配路径中编码的 id。
• SQLite auth-profile 目标需要 agentId。
• 创建新的 auth-profile 映射时，需包含 authProfileProvider。

失败行为¶

若目标未通过校验，apply 会退出并显示类似如下错误：

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

无效计划不会提交任何写入：目标解析和路径校验在任何状态变更之前执行。对于有效计划，apply 会在写入前捕获文件快照和 SQLite auth-store 快照。若后续写入失败，它将尝试恢复文件，并有条件地回滚 auth-store 写入，而不会覆盖并发发生的凭据变更。

Exec 提供者同意行为¶

• --dry-run 默认跳过 exec SecretRef 检查。
• 包含 exec SecretRef/提供者的计划在写入模式下会被拒绝，除非设置了 --allow-exec。
• 校验/应用包含 exec 的计划时，请在 dry-run 和写入命令中均传入 --allow-exec。

运行时与审计范围说明¶

• 仅含引用的 SQLite auth-profile 条目（keyRef/tokenRef）会纳入运行时凭据解析和审计覆盖范围。
• secrets apply 会写入受支持的 openclaw.json 目标和 SQLite auth-profile 目标。默认启用两个可选的清理（scrub）步骤：
• scrubEnv：从有效状态目录和活动配置目录中的 .env 文件移除已迁移的明文值。
• scrubAuthProfilesForProviderTargets：清除计划刚迁移的提供者在 auth 存储中的明文/未使用引用残留。

若要在计划中跳过某个步骤，请将该选项设为 false。

• scrubLegacyAuthJson 是一个已弃用的计划输入，且始终禁用。Doctor 负责遗留 auth.json 的迁移。secrets apply 不会读取或重写它。

操作员检查¶

# 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 重新生成计划，或将目标路径修复为上述支持的格式。

相关文档¶

• 机密管理
• CLI secrets
• SecretRef 凭据表面
• 配置参考