openclaw secrets

管理 SecretRef，并保持活动运行时快照健康。

建议的操作员工作流程：

openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets audit --checkopenclaw secrets reload

如果计划包含 exec SecretRef/提供商，请在试运行和写入的 apply 命令中都传入 --allow-exec。

CI/门禁的退出代码：

• audit --check 发现问题时返回 1。
• 存在未解析的引用时返回 2（无论是否使用 --check）。

相关内容：密钥管理 · SecretRef 凭据范围 · 安全性

重新加载运行时快照

openclaw secrets reloadopenclaw secrets reload --jsonopenclaw secrets reload --url ws://127.0.0.1:18789 --token <token>

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

选项：--url <url>、--token <token>、--timeout <ms>、--json。

审计

扫描 OpenClaw 状态以查找：

• 明文密钥存储
• 未解析的引用
• 优先级偏移（auth-profiles.json 凭据遮蔽 openclaw.json 引用）
• 生成的 agents/*/agent/models.json 残留（提供商 apiKey 值和敏感的提供商标头）
• 旧版残留（旧版身份验证存储条目、OAuth 提醒）

敏感提供商标头检测基于名称启发式规则：名称匹配常见身份验证/凭据片段（authorization、x-api-key、token、secret、password、credential）的标头会被标记。

openclaw secrets auditopenclaw secrets audit --checkopenclaw secrets audit --jsonopenclaw secrets audit --allow-exec

报告结构：

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

配置（交互式辅助工具）

以交互方式构建提供商和 SecretRef 变更、运行预检，并可选择应用：

openclaw secrets configureopenclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.jsonopenclaw secrets configure --apply --yesopenclaw secrets configure --providers-onlyopenclaw secrets configure --skip-provider-setupopenclaw secrets configure --agent opsopenclaw secrets configure --json

流程：首先设置提供商（添加/编辑/移除 secrets.providers 别名），然后映射凭据（选择字段，分配 {source, provider, id} 引用），最后执行预检并可选择应用。

标志：

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

--providers-only 和 --skip-provider-setup 不能组合使用。

注意：

• 需要交互式 TTY。
• 目标包括 openclaw.json 中包含密钥的字段，以及所选智能体范围的 auth-profiles.json；规范支持范围请参阅：SecretRef 凭据范围。
• 支持直接在选择器流程中创建新的 auth-profiles.json 映射。
• 应用前会运行解析预检。
• 生成的计划默认启用清除选项（scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson）。对已清除明文值的应用操作不可逆。
• 不使用 --apply 时，CLI 仍会在预检后提示 Apply this plan now?。
• 使用 --apply（且未使用 --yes）时，CLI 会额外提示确认不可逆迁移。
• --json 会输出计划和预检报告，但仍需要交互式 TTY。

Exec 提供商安全性

Homebrew 安装通常会在 /opt/homebrew/bin/* 下提供符号链接二进制文件。仅在可信的软件包管理器路径确有需要时设置 allowSymlinkCommand: true，并同时配置 trustedDirs（例如 ["/opt/homebrew"]）。在 Windows 上，如果无法验证提供商路径的 ACL，OpenClaw 会采用失败关闭策略；仅对于可信路径，可在该提供商上设置 allowInsecurePath: true 以绕过路径安全检查。

应用已保存的计划

openclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

--dry-run 执行预检验证而不写入文件；试运行默认跳过 exec SecretRef 检查。除非使用 --allow-exec，否则写入模式会拒绝包含 exec SecretRef/提供商的计划。在任一模式中，使用 --allow-exec 可选择启用 exec 提供商检查/执行。

apply 可能更新：

• openclaw.json（SecretRef 目标 + 提供商更新插入/删除）
• auth-profiles.json（提供商目标清除）
• 旧版 auth.json 残留
• ~/.openclaw/.env 中值已迁移的已知密钥键

计划契约详情（允许的目标路径、验证规则、失败语义）：密钥应用计划契约。

为什么没有回滚备份

secrets apply 有意不写入包含旧明文值的回滚备份。安全性来自严格预检和近似原子的应用过程，并在失败时尽力在内存中恢复。

示例

openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets audit --check

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

相关内容

• CLI 参考
• 密钥管理
• Vault SecretRef