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

允许的目标类型与路径

路径校验规则

每个目标都会通过以下所有规则进行校验：

• type 必须是上述允许的目标类型之一。
• path 必须是非空的点分隔路径。
• pathSegments 是可选的。如果提供了该字段，它标准化后必须与 path 完全一致。
• 禁止的分段会被拒绝：__proto__、prototype、constructor。
• 标准化后的路径必须匹配目标类型对应的允许路径格式之一。
• 如果设置了 providerId / accountId，则它必须与路径中编码的 ID 匹配。

失败行为

如果某个目标校验失败，应用操作会直接退出，并返回如下错误：

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

对于无效的目标路径，不会提交任何部分修改。

仅引用的认证配置文件与隐式提供商

隐式提供商发现也会处理那些存储引用而非明文凭证的认证配置文件：

• type: "api_key" 类型的配置文件可以使用 keyRef（例如基于环境变量的引用）。
• type: "token" 类型的配置文件可以使用 tokenRef。

行为说明：

• 对于 API 密钥类提供商（例如 volcengine、byteplus），仅引用的配置文件仍然可以激活隐式提供商条目。
• 对于 github-copilot，如果配置文件没有明文令牌，发现流程会在令牌交换前，先尝试通过 tokenRef 进行环境变量解析。

操作检查

## 仅校验计划，不执行写入
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
## 然后执行实际的应用操作
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

如果应用操作因无效目标路径错误失败，请使用 openclaw secrets configure 重新生成计划，或者将目标路径修改为上述允许的格式之一。