Secrets
openclaw secrets
Section titled “openclaw secrets”使用 openclaw secrets 管理 SecretRefs 并保持当前运行时快照健康。
命令角色：
reload：网关 RPC（secrets.reload），仅在完全成功时重新解析引用并交换运行时快照（不写入配置）。audit: 对 configuration/auth/generated-模型 存储和遗留残留进行只读扫描，检查明文、未解析的引用和优先级漂移（除非设置了--allow-exec，否则将跳过 exec 引用）。configure: 用于提供商设置、目标映射和预检的交互式计划器（需要 TTY）。apply: 执行保存的计划（--dry-run仅用于验证；默认情况下，dry-run 跳过 exec 检查，写入模式会拒绝包含 exec 的计划，除非设置了--allow-exec），然后清除目标明文残留。
建议的操作员循环：
openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets audit --checkopenclaw secrets reload如果您的计划包含 exec SecretRefs/提供商，请在 dry-run 和写入应用命令上传递 --allow-exec。
CI/网关的退出代码说明：
audit --check在发现问题时返回1。- 未解析的引用返回
2。
相关内容：
- Secrets 指南：Secrets Management
- 凭证覆盖范围：SecretRef Credential Surface
- 安全指南：Security
重新加载运行时快照
Section titled “重新加载运行时快照”重新解析密钥引用并原子交换运行时快照。
openclaw secrets reloadopenclaw secrets reload --jsonopenclaw secrets reload --url ws://127.0.0.1:18789 --token <token>说明：
- 使用网关 RPC 方法
secrets.reload。 - 如果解析失败，网关将保留最后已知良好的快照并返回错误（无部分激活）。
- JSON 响应包含
warningCount。
选项：
--url <url>--token <token>--timeout <ms>--json
扫描 OpenClaw 状态以查找：
- 明文 secret 存储
- 未解析的引用
- 优先级漂移（
auth-profiles.json凭证遮蔽openclaw.json引用） - 生成的
agents/*/agent/models.json残留（提供商apiKey值和敏感提供商标头） - 遗留残留（遗留认证存储条目，OAuth 提醒）
标头残留说明：
- 敏感提供商标头检测基于名称启发式方法（常见的认证/凭证标头名称和片段，例如
authorization、x-api-key、token、secret、password和credential）。
openclaw secrets auditopenclaw secrets audit --checkopenclaw secrets audit --jsonopenclaw secrets audit --allow-exec退出行为：
- 发现问题时
--check退出代码为非零。 - 未解析的引用退出时带有更高优先级的非零代码。
报告格式亮点：
status：clean | findings | unresolvedresolution：refsChecked、skippedExecRefs、resolvabilityCompletesummary：plaintextCount、unresolvedRefCount、shadowedRefCount、legacyResidueCount- 发现代码：
PLAINTEXT_FOUNDREF_UNRESOLVEDREF_SHADOWEDLEGACY_RESIDUE
配置（交互式助手）
Section titled “配置（交互式助手）”以交互方式构建提供商和 SecretRef 更改，运行预检，并可选择应用：
openclaw secrets configureopenclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.jsonopenclaw secrets configure --apply --yesopenclaw secrets configure --providers-onlyopenclaw secrets configure --skip-provider-setupopenclaw secrets configure --agent opsopenclaw secrets configure --json流程：
- 首先设置提供商（
add/edit/remove用于secrets.providers别名）。 - 其次进行凭证映射（选择字段并分配
{source, provider, id}引用）。 - 最后进行预检和可选应用。
标志：
--providers-only：仅配置secrets.providers，跳过凭据映射。--skip-provider-setup：跳过提供商设置并将凭据映射到现有提供商。--agent <id>：将auth-profiles.json目标发现和写入范围限制在一个代理存储中。--allow-exec：允许在预检/应用期间执行 exec SecretRef 检查（可能会执行提供商命令）。
注意：
- 需要交互式 TTY。
- 您不能将
--providers-only与--skip-provider-setup组合使用。 configure针对的是openclaw.json中包含机密的字段，以及所选代理范围的auth-profiles.json。configure支持在选择器流程中直接创建新的auth-profiles.json映射。- 规范支持的范围：SecretRef Credential Surface。
- 它在应用之前执行预检解析。
- 如果预检/应用包含 exec 引用，请在这两个步骤中保持
--allow-exec已设置。 - 生成的计划默认为清理选项（
scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson均已启用）。 - 对于已清理的明文值，应用路径是单向的。
- 如果没有
--apply，CLI 仍会在预检后提示Apply this plan now?。 - 使用
--apply（且没有--yes）时，CLI 会提示进行额外的不可逆确认。 --json会打印计划 + 预检报告，但该命令仍需要交互式 TTY。
Exec 提供商安全提示：
- Homebrew 安装通常会在
/opt/homebrew/bin/*下暴露符号链接二进制文件。 - 仅当需要针对受信任的包管理器路径时才设置
allowSymlinkCommand: true，并将其与trustedDirs配对（例如["/opt/homebrew"]）。 - 在 Windows 上，如果提供商路径的 ACL 验证不可用，OpenClaw 将以失败关闭。仅对于受信任的路径，在该提供商上设置
allowInsecurePath: true以绕过路径安全检查。
应用保存的计划
Section titled “应用保存的计划”应用或预检之前生成的计划：
openclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --jsonExec 行为：
--dry-run在不写入文件的情况下验证预检。- exec SecretRef 检查在 dry-run 中默认被跳过。
- 除非设置了
--allow-exec，否则写入模式会拒绝包含 exec SecretRefs/提供商的计划。 - 使用
--allow-exec可以在任一模式下选择加入 exec 提供商检查/执行。
计划合约详情（允许的目标路径、验证规则和失败语义）：
apply 可能更新的内容：
openclaw.json(SecretRef 目标 + 提供商 upserts/deletes)auth-profiles.json(提供商目标清理)- 遗留
auth.json残留 ~/.openclaw/.env值已迁移的已知密钥
为什么没有回滚备份
Section titled “为什么没有回滚备份”secrets apply 故意不写入包含旧明文值的回滚备份。
安全性来自严格的预检 + 准原子性应用，失败时尽力进行内存恢复。
openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets audit --check如果 audit --check 仍然报告明文发现，请更新剩余报告的目标路径并重新运行审计。