openclaw secrets

用 openclaw secrets 管理 SecretRef，确保运行时快照健康。

命令分工：

  • reload：通过 gateway RPC（secrets.reload）重新解析引用，全部成功后原子替换运行时快照（不写入配置文件）。
  • audit：只读扫描配置 / 认证 / 生成的模型存储以及遗留残留，检查明文、未解析引用和优先级偏移。
  • configure：交互式规划工具，用于 provider 配置、目标映射和预检（需要 TTY）。
  • apply：执行已保存的计划（--dry-run 仅做验证），然后清除目标明文残留。

推荐的操作流程：

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

CI / 门控的退出码说明：

  • audit --check 有发现时返回 1。
  • 存在未解析引用时返回 2。

相关内容：

重载运行时快照

重新解析 secret 引用并原子替换运行时快照。

openclaw secrets reload
openclaw secrets reload --json

注意事项：

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

审计

扫描 OpenClaw 状态中的：

  • 明文密钥存储
  • 未解析引用
  • 优先级偏移（auth-profiles.json 中的凭据遮蔽了 openclaw.json 中的引用）
  • 生成的 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

退出行为：

  • --check 有发现时以非零码退出。
  • 未解析引用以更高优先级的非零码退出。

报告结构要点：

  • status：clean | findings | unresolved
  • 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} 引用）。
  • 最后预检和可选应用。

参数：

  • --providers-only：只配置 secrets.providers，跳过凭据映射。
  • --skip-provider-setup：跳过 provider 设置，直接将凭据映射到已有 provider。
  • --agent <id>：将 auth-profiles.json 目标发现和写入限定到某个 agent 存储。

注意事项：

  • 需要交互式 TTY。
  • --providers-only 和 --skip-provider-setup 不能同时使用。
  • configure 的目标是 openclaw.json 中的密钥字段以及所选 agent 范围内的 auth-profiles.json。
  • configure 支持在选择器流程中直接创建新的 auth-profiles.json 映射。
  • 规范支持的覆盖面：SecretRef Credential Surface。
  • 应用前会进行预检解析。
  • 生成的计划默认启用清除选项（scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson 全部开启）。
  • 对于已清除的明文值，应用路径是单向不可逆的。
  • 不传 --apply 时，CLI 在预检后仍会提示 Apply this plan now?。
  • 传了 --apply（但没有 --yes）时，CLI 会额外弹出一个不可逆操作确认。

exec provider 安全提示：

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

应用已保存的计划

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

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

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

apply 可能更新的内容：

  • openclaw.json（SecretRef 目标 + provider 的新增 / 更新 / 删除）
  • auth-profiles.json（provider 目标清除）
  • 遗留 auth.json 残留
  • ~/.openclaw/.env 中已迁移的已知密钥

为什么没有回滚备份

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

安全性来自严格的预检 + 近原子的应用操作，失败时尽力做内存恢复。

示例

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

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

arrow_back
上一页
Sandbox
下一页
Security
arrow_forward