Secrets apply 计划规范

本页定义了 openclaw secrets apply 强制执行的严格规范。

若目标不符合这些规则，apply 命令会在修改任何配置之前报错退出。

计划文件结构

openclaw secrets apply --from <plan.json> 期望一个包含 targets 数组的计划目标：

json5

{
  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 命令会以如下错误退出：

text

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

无效计划不会提交任何写入操作。

Exec provider 授权行为

--dry-run 默认跳过 exec SecretRef 检查。
包含 exec SecretRef/provider 的计划在写入模式下被拒绝，除非设置了 --allow-exec。
验证/应用包含 exec 的计划时，在 dry-run 和写入命令中都要传入 --allow-exec。

运行时与审计范围说明

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

Operator 操作命令

bash

# 不写入地验证计划
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-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

若 apply 因无效目标路径报错，请通过 openclaw secrets configure 重新生成计划，或将目标路径修改为上述支持的格式。

Secrets apply 计划规范 ​

计划文件结构 ​

支持的目标范围 ​

目标类型行为 ​

路径验证规则 ​

失败行为 ​

Exec provider 授权行为 ​

运行时与审计范围说明 ​

Operator 操作命令 ​

相关文档 ​