Secrets apply 计划合约

本页定义了 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" },
    },
  ],
}

支持的目标范围

计划目标仅在以下文档列出的凭证路径上被接受：

SecretRef 凭证覆盖范围

目标类型行为

基本规则：

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

无效计划不会写入任何内容。

运行时与审计范围说明

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

操作员检查

# 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

如果 apply 因无效目标路径报错，用 openclaw secrets configure 重新生成计划，或将目标路径修正为上述支持的格式。