openclaw secrets

使用 openclaw secrets 将凭据从明文迁移�?SecretRefs 并保持活动密钥运行时健康�?

命令角色�?

  • reload：网�?RPC（secrets.reload），重新解析引用并在完全成功时切换运行时快照（不写入配置）�?
  • audit：仅读扫描配�?+ 认证存储 + 传统残留（.env、auth.json），查找明文、未解析的引用和优先级漂移�?
  • configure：提供商设置 + 目标映射 + 预检的交互式规划器（需�?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�?

相关链接�?

重新加载运行时快�?

重新解析密钥引用并原子交换运行时快照�?

openclaw secrets reload
openclaw secrets reload --json

注意事项�?

  • 使用网关 RPC 方法 secrets.reload�?
  • 如果解析失败，网关保留最后已知的良好快照并返回错误（无部分激活）�?
  • JSON 响应包括 warningCount�?

审计

扫描 OpenClaw 状态以查找�?

  • 明文密钥存储
  • 未解析的引用
  • 优先级漂移（auth-profiles 遮盖配置引用�?
  • 传统残留（auth.json、OAuth 超出范围说明�?
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

配置（交互式助手�?

交互式构建提供商 + 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 --json

流程�?

  • 首先是提供商设置（secrets.providers 别名�?add/edit/remove）�?
  • 其次是凭据映射（选择字段并分�?{source, provider, id} 引用）�?
  • 最后是预检和可选应用�?

标志�?

  • --providers-only：仅配置 secrets.providers，跳过凭据映射�?
  • --skip-provider-setup：跳过提供商设置并将凭据映射到现有提供商�?

注意事项�?

  • 需要交互式 TTY�?
  • 你不能将 --providers-only �?--skip-provider-setup 组合使用�?
  • configure 面向 openclaw.json 中包含密钥的字段�?
  • 包含你打算迁移的所有包含密钥的字段（例�?models.providers.*.apiKey �?skills.entries.*.apiKey），以便审计可以达到干净状态�?
  • 它在应用之前执行预检解析�?
  • 生成的计划默认为清理选项（scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson 都启用）�?
  • 已迁移明文值的应用路径是单向的�?
  • 没有 --apply，CLI 仍会在预检后提�?现在应用此计划？”
  • �?--apply（且没有 --yes），CLI 会提示额外的不可逆迁移确认�?

Exec 提供商安全说明：

  • Homebrew 安装通常�?/opt/homebrew/bin/* 下公开符号链接二进制文件�?
  • 仅在需要受信任的包管理器路径时才设�?allowSymlinkCommand: true，并将其�?trustedDirs 配对（例�?["/opt/homebrew"]）�?

应用保存的计�?

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

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 目标 + 提供�?upsert/删除�?
  • auth-profiles.json（提供商目标清理�?
  • 传统�?auth.json 残留
  • ~/.openclaw/.env 中其值已迁移的已知密�?

为什么没有回滚备�?

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

安全性来自严格的预检 + 原子式应用，失败时尽最大努力恢复内存中的状态�?

示例

# 首先审计，然后配置，然后确认干净�?
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

如果部分迁移�?audit --check 仍报告明文发现，请验证你也迁移了技能密钥（skills.entries.*.apiKey）和任何其他报告的目标路径�?