Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw secrets
使用 openclaw secrets 管理 SecretRefs，并保持当前活动运行时快照处于健康状态。
命令角色：
reload：Gateway 网关 RPC（secrets.reload），重新解析引用，并且仅在完全成功时才切换运行时快照（不会写入配置）。audit：对配置/auth/生成的 model 存储以及旧版残留进行只读扫描，查找明文、未解析的引用和优先级漂移（除非设置了--allow-exec，否则会跳过 exec 引用）。configure：用于 provider 设置、目标映射和预检的交互式规划器（需要 TTY）。apply：执行已保存的计划（--dry-run仅用于验证；dry-run 默认跳过 exec 检查，而写入模式会拒绝包含 exec 的计划，除非设置了--allow-exec），然后清除目标明文残留。
exec SecretRefs/providers，请在 dry-run 和写入 apply 命令中都传入 --allow-exec。
适用于 CI/门控的退出码说明：
audit --check在发现问题时返回1。- 未解析的引用返回
2。
- 密钥指南：Secrets Management
- 凭证表面：SecretRef Credential Surface
- 安全指南：Security
重新加载运行时快照
重新解析密钥引用，并以原子方式切换运行时快照。- 使用 Gateway 网关 RPC 方法
secrets.reload。 - 如果解析失败，Gateway 网关会保留最后一个已知正常的快照并返回错误（不会部分启用）。
- JSON 响应包含
warningCount。
--url <url>--token <token>--timeout <ms>--json
审计
扫描 OpenClaw 状态中的以下内容：- 明文密钥存储
- 未解析的引用
- 优先级漂移（
auth-profiles.json中的凭证遮蔽了openclaw.json中的引用） - 生成的
agents/*/agent/models.json残留（provider 的apiKey值和敏感 provider headers） - 旧版残留（旧版 auth 存储条目、OAuth 提醒）
- 敏感 provider header 检测基于名称启发式规则（常见的认证/凭证 header 名称及片段，例如
authorization、x-api-key、token、secret、password和credential）。
--check会在发现问题时以非零状态退出。- 未解析的引用会以更高优先级的非零退出码退出。
status：clean | findings | unresolvedresolution：refsChecked、skippedExecRefs、resolvabilityCompletesummary：plaintextCount、unresolvedRefCount、shadowedRefCount、legacyResidueCount- 问题代码：
PLAINTEXT_FOUNDREF_UNRESOLVEDREF_SHADOWEDLEGACY_RESIDUE
配置（交互式辅助工具）
以交互方式构建 provider 和 SecretRef 变更，运行预检，并可选择应用：- 先进行 provider 设置（对
secrets.providers别名执行add/edit/remove）。 - 然后进行凭证映射（选择字段并分配
{source, provider, id}引用）。 - 最后进行预检和可选 apply。
--providers-only：仅配置secrets.providers，跳过凭证映射。--skip-provider-setup：跳过 provider 设置，并将凭证映射到现有 provider。--agent <id>：将auth-profiles.json的目标发现和写入范围限定为单个 agent 存储。--allow-exec：在预检/apply 期间允许 exec SecretRef 检查（可能会执行 provider 命令）。
- 需要交互式 TTY。
- 不能将
--providers-only与--skip-provider-setup组合使用。 configure以openclaw.json中承载密钥的字段以及所选 agent 范围内的auth-profiles.json为目标。configure支持在选择器流程中直接创建新的auth-profiles.json映射。- 规范支持范围：SecretRef Credential Surface。
- 它会在 apply 之前执行预检解析。
- 如果预检/apply 包含 exec 引用，请在这两个步骤中都保持设置
--allow-exec。 - 生成的计划默认启用清除选项（
scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson全部启用）。 - 对于已清除的明文值，apply 路径是单向的。
- 未使用
--apply时，CLI 仍会在预检后提示Apply this plan now?。 - 使用
--apply时（且未使用--yes），CLI 会额外提示一次不可逆确认。 --json会打印计划 + 预检报告，但该命令仍然需要交互式 TTY。
- Homebrew 安装通常会在
/opt/homebrew/bin/*下暴露符号链接二进制文件。 - 仅在信任的软件包管理器路径确有需要时设置
allowSymlinkCommand: true，并与trustedDirs配合使用（例如["/opt/homebrew"]）。 - 在 Windows 上，如果某个 provider 路径无法进行 ACL 验证，OpenClaw 会以默认拒绝的方式处理。仅对可信路径，可在该 provider 上设置
allowInsecurePath: true以绕过路径安全检查。
应用已保存的计划
应用或预检之前生成的计划：--dry-run会在不写入文件的情况下验证预检。- dry-run 默认跳过 exec SecretRef 检查。
- 写入模式会拒绝包含 exec SecretRefs/providers 的计划，除非设置了
--allow-exec。 - 使用
--allow-exec以在任一模式下选择启用 exec provider 检查/执行。
apply 可能更新的内容：
openclaw.json（SecretRef 目标 + provider upsert/delete）auth-profiles.json（provider-target 清除）- 旧版
auth.json残留 ~/.openclaw/.env中值已迁移的已知密钥键
为什么没有回滚备份
secrets apply 有意不写入包含旧明文值的回滚备份。
安全性来自严格的预检，以及在失败时尽最大努力进行内存恢复的近原子 apply。
示例
audit --check 仍然报告明文问题，请更新其报告的剩余目标路径，然后重新运行审计。