Secrets 应用计划契约

本页定义�?openclaw secrets 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" },
    },
  ],
}

允许的目标类型和路径

target.type允许�?target.path 形状可�?ID 匹配规则
models.providers.apiKeymodels.providers.<providerId>.apiKeyproviderId 必须匹配 <providerId>（当存在时）
skills.entries.apiKeyskills.entries.<skillKey>.apiKeyn/a
channels.googlechat.serviceAccountchannels.googlechat.serviceAccountaccountId 必须为空/省略
channels.googlechat.serviceAccountchannels.googlechat.accounts.<accountId>.serviceAccountaccountId 必须匹配 <accountId>（当存在时）

路径验证规则

每个目标都经过以下全部验证：

  • type 必须是上述允许的目标类型之一�?
  • path 必须是非空的点路径�?
  • pathSegments 可以省略。如果提供，它必须规范化为与 path 完全相同的路径�?
  • 禁止的段被拒绝：__proto__、prototype、constructor�?
  • 规范化路径必须匹配目标类型允许的路径形状之一�?
  • 如果设置�?providerId / accountId，它必须与路径中编码�?ID 匹配�?

失败行为

如果目标验证失败，应用退出并显示如下错误�?

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

不会为该无效目标路径提交部分变更�?

�?ref �?auth-profile 和隐式提供�?

隐式提供者发现还考虑存储 ref 而非明文凭证�?auth-profile�?

  • type: "api_key" �?profile 可以使用 keyRef（例�?env 支持�?ref）�?
  • type: "token" �?profile 可以使用 tokenRef�?

行为�?

  • 对于 API 密钥提供者（例如 volcengine、byteplus），�?ref �?profile 仍然可以激活隐式提供者条目�?
  • 对于 github-copilot，如�?profile 没有明文令牌，发现将在令牌交换之前尝�?tokenRef env 解析�?

操作员检�?

# 验证计划而不写入
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# 然后实际应用
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

如果应用失败并显示无效目标路径消息，使用 openclaw secrets configure 重新生成计划或将目标路径修复为上述允许的形状之一�?

相关文档