openclaw secrets

使用 openclaw secrets 管理 SecretRef 并保持活跃运行时快照的健康状态。

命令职责：

• reload：发起 Gateway RPC（secrets.reload），在完全成功时重新解析 ref 并原子性交换运行时快照（不写入配置）。
• audit：对配置/认证/生成的模型存储及遗留残留进行只读扫描，检查明文、未解析的 ref 和优先级漂移（除非设置 --allow-exec，否则跳过 exec ref）。
• configure：Provider 设置、目标映射和预检的交互式规划器（需要 TTY）。
• apply：执行已保存的计划（--dry-run 仅验证；干运行默认跳过 exec 检查；写入模式拒绝包含 exec 的计划，除非设置 --allow-exec），然后清除目标明文残留。

推荐的运维流程：

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

如果计划包含 exec SecretRef/Provider，在干运行和写入 apply 命令中都需要传入 --allow-exec。

CI/门控的退出码说明：

• audit --check 在发现问题时返回 1。
• 未解析的 ref 返回 2。

相关文档：

• Secrets 指南：Secrets Management
• 凭证界面：SecretRef Credential Surface
• 安全指南：Security

重载运行时快照

重新解析 Secret ref 并原子性交换运行时快照。

openclaw secrets reload
openclaw secrets reload --json

说明：

• 使用 Gateway RPC 方法 secrets.reload。
• 解析失败时，Gateway 保留上一个已知的良好快照并返回错误（不会部分激活）。
• JSON 响应包含 warningCount。

审计

扫描 OpenClaw 状态，检查以下内容：

• 明文 Secret 存储
• 未解析的 ref
• 优先级漂移（auth-profiles.json 中的凭证覆盖了 openclaw.json 中的 ref）
• 生成的 agents/*/agent/models.json 残留（Provider apiKey 值和敏感 Provider 请求头）
• 遗留残留（遗留认证存储条目、OAuth 提醒）

请求头残留说明：

• 敏感 Provider 请求头检测基于名称启发式规则（常见的认证/凭证请求头名称和片段，如 authorization、x-api-key、token、secret、password 和 credential）。

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec

退出行为：

• --check 在发现问题时以非零状态退出。
• 未解析的 ref 以更高优先级的非零状态退出。

报告结构要点：

• status：clean | findings | unresolved
• resolution：refsChecked、skippedExecRefs、resolvabilityComplete
• summary：plaintextCount、unresolvedRefCount、shadowedRefCount、legacyResidueCount
• 发现代码：
  • PLAINTEXT_FOUND
  • REF_UNRESOLVED
  • REF_SHADOWED
  • LEGACY_RESIDUE

交互式配置助手

交互式构建 Provider 和 SecretRef 变更，运行预检，并可选择应用：

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

流程：

• 先进行 Provider 设置（对 secrets.providers 别名执行 add/edit/remove）。
• 再进行凭证映射（选择字段并分配 {source, provider, id} ref）。
• 最后进行预检并可选择应用。

参数：

• --providers-only：仅配置 secrets.providers，跳过凭证映射。
• --skip-provider-setup：跳过 Provider 设置，将凭证映射到现有 Provider。
• --agent <id>：将 auth-profiles.json 目标发现和写入范围限定到某个 Agent 存储。
• --allow-exec：允许在预检/应用期间进行 exec SecretRef 检查（可能会执行 Provider 命令）。

注意事项：

• 需要交互式 TTY。
• --providers-only 和 --skip-provider-setup 不能同时使用。
• configure 目标为 openclaw.json 中携带 Secret 的字段，以及所选 Agent 范围的 auth-profiles.json。
• configure 支持在选择器流程中直接创建新的 auth-profiles.json 映射。
• 规范支持的界面：SecretRef Credential Surface。
• 应用前会执行预检解析。
• 如果预检/应用包含 exec ref，两步都需要保持 --allow-exec。
• 生成的计划默认启用清除选项（scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson 全部启用）。
• 应用路径对已清除的明文值是单向的。
• 不带 --apply 时，CLI 仍会在预检后提示 Apply this plan now?。
• 带 --apply（且不带 --yes）时，CLI 会额外提示一次不可逆操作确认。

exec Provider 安全说明：

• Homebrew 安装通常会在 /opt/homebrew/bin/* 下暴露符号链接的二进制文件。
• 仅在受信任的包管理器路径需要时设置 allowSymlinkCommand: true，并配合 trustedDirs（如 ["/opt/homebrew"]）使用。
• 在 Windows 上，如果某个 Provider 路径的 ACL 验证不可用，OpenClaw 会失败关闭。仅对受信任路径设置 allowInsecurePath: true 来绕过路径安全检查。

应用已保存的计划

应用或预检之前生成的计划：

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

exec 行为：

• --dry-run 验证预检但不写入文件。
• 干运行中默认跳过 exec SecretRef 检查。
• 写入模式拒绝包含 exec SecretRef/Provider 的计划，除非设置 --allow-exec。
• 使用 --allow-exec 在任一模式中选择 exec Provider 检查/执行。

计划约定详情（允许的目标路径、验证规则和失败语义）：

• Secrets Apply Plan Contract

apply 可能更新的内容：

• openclaw.json（SecretRef 目标 + Provider 插入/删除）
• auth-profiles.json（Provider 目标清除）
• 遗留 auth.json 残留
• ~/.openclaw/.env 中已迁移值的已知 Secret 键

为什么不提供回滚备份

secrets apply 有意不写入包含旧明文值的回滚备份。

安全性来自严格的预检 + 准原子性应用（失败时尽力内存恢复）。

示例

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

如果 audit --check 仍报告明文发现，更新其余报告的目标路径后重新运行审计。