Skip to main content

​
openclaw secrets

管理 SecretRef，并保持活动运行时快照健康。 建议的操作员流程：
如果计划包含 exec SecretRef/提供商，请在试运行和写入 apply 命令中都传入 --allow-exec。 CI/门禁的退出代码：
  • audit --check 在发现问题时返回 1。
  • 未解析的引用返回 2（无论是否指定 --check）。
相关内容：密钥管理 · SecretRef 凭据界面 · 安全

​
重新加载运行时快照

使用 Gateway 网关 RPC 方法 secrets.reload。健康的所有者会独立刷新。仅当引用标识、提供商定义和完整的非密钥所有者契约保持不变时，符合条件的故障所有者才会变为陈旧状态；新增或发生变化的故障会变为冷状态。这种降级激活会成功，并报告 warningCount。严格模式故障或未映射故障会返回错误，并保留之前的活动快照。 选项：--url <url>、--token <token>、--timeout <ms>、--json。

​
审计

扫描 OpenClaw 状态以查找：
  • 明文密钥存储
  • 未解析的引用
  • 优先级漂移（auth-profiles.json 凭据遮蔽 openclaw.json 引用）
  • 生成的 agents/*/agent/models.json 残留（提供商 apiKey 值和敏感的提供商标头）
  • 旧版残留（旧版身份验证存储条目、OAuth 提醒）
.env 扫描覆盖有效状态目录和包含活动配置的目录。当两个路径指向同一文件时，只扫描一次。 敏感提供商标头的检测基于名称启发式规则：它会标记名称与常见身份验证/凭据片段（authorization、x-api-key、token、secret、password、credential）匹配的标头。
报告结构：
  • status：clean | findings | unresolved
  • resolution：refsChecked、skippedExecRefs、resolvabilityComplete
  • summary：plaintextCount、unresolvedRefCount、shadowedRefCount、legacyResidueCount
  • 发现代码：PLAINTEXT_FOUND、REF_UNRESOLVED、REF_SHADOWED、LEGACY_RESIDUE

​
配置（交互式辅助工具）

以交互方式构建提供商和 SecretRef 变更，运行预检，并可选择应用：
流程：先设置提供商（添加/编辑/删除 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）。对于已清除的明文值，应用操作不可逆。
  • --plan-out 拒绝创建 UTF-8 序列化形式超过 16 MiB（16,777,216 字节）的计划，这与 apply --from 输入限制一致。
  • 如果未指定 --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 以绕过路径安全检查。

​
应用已保存的计划

--dry-run 会在不写入文件的情况下验证预检；试运行默认跳过 exec SecretRef 检查。除非指定 --allow-exec，否则写入模式会拒绝包含 exec SecretRef/提供商的计划。在任一模式下，使用 --allow-exec 可选择启用 exec 提供商检查/执行。 --from 必须指向不大于 16 MiB（16,777,216 字节）的常规文件。字节限制适用于包括空白字符在内的完整序列化文件。 apply 可能更新的内容：
  • openclaw.json（SecretRef 目标 + 提供商更新插入/删除）
  • auth-profiles.json（提供商目标清除）
  • 旧版 auth.json 残留
  • 有效状态目录和活动配置目录中的 .env 文件，针对值已迁移的已知密钥键
计划契约详情（允许的目标路径、验证规则、失败语义）：密钥应用计划契约。

​
为什么没有回滚备份

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

​
示例

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

​
相关内容