本页内容
本页内容
网关
Secrets apply 计划契约
本页定义了 openclaw secrets apply 强制执行的严格合同。如果目标与这些规则不匹配,则在更改任何文件之前应用会失败。
计划文件要求
openclaw secrets apply --from <plan.json> 接受最多 16 MiB(16,777,216 字节)的常规文件。该限制适用于完整的序列化文件,包括空格。在 JSON 解析或目标验证之前,目录、FIFO、设备文件和大于限制的文件将被拒绝。
在创建文件之前,openclaw secrets configure --plan-out <plan.json> 对 UTF-8 序列化输出强制执行相同的限制。手写计划和外部计划生成器也必须将序列化文件保持在此边界内。
平面文件形状
openclaw secrets apply --from <plan.json> 期望一个 targets 数组,其中包含计划目标:
openclaw secrets configure 会生成这种形状的计划。你也可以手动编写或编辑一个。
提供者上插入与删除
计划还可以包含两个可选的顶层字段,这些字段会在逐目标写入的同时修改 secrets.providers 映射:
providerUpserts——由提供者别名键入的对象。每个值都是一个提供程序定义(在openclaw.json、e.g.、exec或file提供程序中的secrets.providers.<alias>下接受的形状相同)。providerDeletes—— 一个要移除的提供者别名数组。
providerUpserts 会在 targets 之前运行,因此 target.ref.provider 可以引用同一个计划在 providerUpserts 中引入的提供者别名。没有这个顺序的话,引用尚未在 openclaw.json 中配置的别名的计划会失败,并报错 provider "<alias>" is not configured。
通过 providerUpserts 引入的 Exec 提供者仍然受 Exec provider consent behavior 中的 exec 同意规则约束:包含 exec 提供者的计划在写入模式下需要 --allow-exec。
支持的目标范围
对于 SecretRef Credential Surface 中支持的凭据路径,计划目标是可接受的。
目标类型行为
target.type 必须是一个可识别的目标类型,并且规范化后的 target.path 必须与该类型注册的路径形状匹配。
除了主要类型名称之外,某些目标类型还接受现有计划的兼容性别名 target.type:
| 初级型 | 接受的别名 |
|---|---|
models.providers.apiKey |
models.providers.*.apiKey |
skills.entries.apiKey |
skills.entries.*.apiKey |
channels.googlechat.serviceAccount |
channels.googlechat.accounts.*.serviceAccount |
路径校验规则
每个目标都会经过以下全部校验:
type必须是可识别的目标类型。path必须是非空的点路径。pathSegments可以省略。如果提供,则其规范化结果必须与path完全相同。- 禁止的段会被拒绝:
__proto__、prototype、constructor。 - 规范化后的路径必须与该目标类型已注册的路径形状匹配。
- 如果设置了
providerId或accountId,它必须与路径中编码的 id 匹配。 - SQLite 身份验证配置文件目标需要
agentId。 - 创建新的身份验证配置文件映射时,请包含
authProfileProvider。
失败行为
如果某个目标未通过校验,apply 会以如下错误退出:
不会为无效计划提交任何写入:在更改任何状态之前运行目标解析和路径验证。对于有效的计划,请在写入之前应用捕获文件快照和 SQLite 身份验证存储快照。如果以后的写入失败,它会尝试恢复文件并有条件地回滚身份验证存储写入,而不覆盖并发凭据更改。
Exec provider 同意行为
--dry-run默认会跳过 exec SecretRef 检查。- 包含 exec SecretRefs/providers 的计划在写入模式下将被拒绝,除非设置了
--allow-exec。 - 当 validating/applying 执行包含计划时,在空运行和写入命令中传递
--allow-exec。
运行时与审计范围说明
-
Ref-only SQLite 身份验证配置文件条目 (
keyRef/tokenRef) 包含在运行时凭证解析和审计覆盖范围中。 -
secrets apply写入支持的openclaw.json目标和 SQLite auth-profile 目标。默认情况下,两个可选的擦洗通道处于启用状态:scrubEnv从有效状态和 active-config 目录中的.env文件中删除迁移的明文值。scrubAuthProfilesForProviderTargets为刚刚迁移的计划的提供商清除授权存储中的 plaintext/unused-ref 残留。
在计划中将任一选项设置为
false以跳过该过程。 -
scrubLegacyAuthJson是已弃用的计划输入,并且始终处于禁用状态。 Doctor 拥有旧版auth.json迁移。secrets apply不读取或重写它。
操作检查
如果 apply 因无效目标路径消息而失败,请使用 openclaw secrets configure 重新生成计划,或将目标路径修正为上述受支持的形状。