CLI secrets 命令

openclaw secrets 用于管理 SecretRef 并维护运行时快照健康状态。

子命令概览

子命令	作用
reload	通过 gateway RPC 重新解析 refs，原子替换运行时快照
audit	只读扫描，检测明文、未解析 refs、优先级漂移
configure	交互式配置 provider 和 SecretRef 映射（需要 TTY）
apply	执行已保存的 plan，清除明文残留

推荐操作流程

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

audit 命令

扫描以下问题：

• 明文 secret 存储（PLAINTEXT_FOUND）
• 未解析的 refs（REF_UNRESOLVED）
• 优先级漂移：auth-profiles.json 凭据覆盖 openclaw.json refs（REF_SHADOWED）
• 遗留残留（LEGACY_RESIDUE）

openclaw secrets audit --check   # 有发现时退出码为 1，未解析 refs 退出码为 2
openclaw secrets audit --json
openclaw secrets audit --allow-exec  # 包含 exec 类型 refs 的检查

configure 命令

交互式流程：先配置 provider（add/edit/remove），再映射凭据字段，最后 preflight 并可选 apply。

openclaw secrets configure --plan-out /tmp/plan.json
openclaw secrets configure --providers-only      # 仅配置 providers
openclaw secrets configure --skip-provider-setup # 跳过 provider，直接映射凭据
openclaw secrets configure --agent ops           # 限定到指定 agent

注意：--providers-only 与 --skip-provider-setup 不可同时使用。

apply 命令

执行已保存的 plan 文件：

openclaw secrets apply --from /tmp/plan.json --dry-run  # 仅验证，不写文件
openclaw secrets apply --from /tmp/plan.json            # 实际执行
openclaw secrets apply --from /tmp/plan.json --allow-exec

apply 可能修改的文件：openclaw.json、auth-profiles.json、遗留 auth.json、~/.openclaw/.env。

apply 不写回滚备份（含旧明文），安全性依赖严格 preflight + 原子 apply。

exec provider 安全注意

• Homebrew 路径下的 symlink 需设 allowSymlinkCommand: true 并配合 trustedDirs
• Windows 上 ACL 不可用时，需设 allowInsecurePath: true 才能绕过路径安全检查

相关链接

• docs/gateway/secrets — Secrets 管理指南
• cli-security — 安全审计命令