Skip to main content
此页面定义了 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 的兼容别名，以支持现有计划：
规范类型接受的别名
models.providers.apiKeymodels.providers.*.apiKey
skills.entries.apiKeyskills.entries.*.apiKey
channels.googlechat.serviceAccountchannels.googlechat.accounts.*.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
无效计划不会提交任何写入：目标解析和路径验证会在触碰任何文件之前运行。另外，一旦有效计划开始写入，apply 会先为每个被触碰的文件创建快照；如果同一次运行中的后续写入失败，它会恢复这些快照，因此部分写入永远不会让配置、auth-profile 或 env 状态不同步。

​
Exec 提供商同意行为

  • 默认情况下，--dry-run 会跳过 exec SecretRef 检查。
  • 包含 exec SecretRef/提供商的计划在写入模式下会被拒绝，除非设置了 --allow-exec。
  • 验证/应用包含 exec 的计划时，请在 dry-run 和写入命令中都传入 --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，即可跳过对应过程。

​
操作员检查

# 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 重新生成计划，或将目标路径修正为上面支持的形状。

​
相关文档