跳转至

密钥操作和行为

本页介绍日常 secrets 操作：支持的凭据表面、所需行为与优先级、激活与恢复信号，以及审计、配置和应用工作流。

支持的凭据表面

规范的支持与不支持的凭据列于 SecretRef 凭据表面。

Note

运行时生成或轮换的凭据以及 OAuth 刷新材料被有意排除在只读 SecretRef 解析之外。

所需行为与优先级

  • 无 ref 的字段：保持不变。
  • 带 ref 的字段：在激活期间为活动表面所必需。
  • 如果明文和 ref 同时存在，则在支持的优先级路径上 ref 优先。
  • 脱敏哨兵 __OPENCLAW_REDACTED__ 保留用于内部配置脱敏/恢复，并作为字面提交的配置数据被拒绝。

警告与审计信号：

  • SECRETS_REF_OVERRIDES_PLAINTEXT（运行时警告）
  • REF_SHADOWED（当 SQLite auth-profile 凭据优先于 openclaw.json refs 时的审计发现）
  • STORE_PLAINTEXT_RESIDUE（当存储的名称仍具有等价的明文配置值时的审计发现）
  • PLACEHOLDER_VALUE（当已解析的凭据或存储条目包含已知脱敏占位符时的审计错误；计为未解析）

Google Chat 的 serviceAccount 接受内联 JSON 或 SecretRef。当 serviceAccountRef 未设置时，Doctor 会将已退役的兄弟字段 serviceAccountRef 移入此规范字段。

激活触发器

Secret 激活在以下时机运行：

  • 启动（预检加最终激活）
  • 配置重载热应用路径
  • 配置重载重启检查路径
  • 通过 secrets.reload 手动重载
  • Gateway 配置写入 RPC 预检（config.set / config.apply / config.patch），在持久化编辑之前验证所提交配置负载中的活动表面 SecretRef

激活契约：

  • 成功时以原子方式交换快照。
  • 严格的启动失败会中止 Gateway 启动。
  • 在冷启动期间，对于已映射、可隔离的非 Gateway 所有者，可重试的解析失败可能会发布快照，并将该确切所有者标记为 configured-unavailable。对该所有者的请求以 SECRET_SURFACE_UNAVAILABLE 失败；在显式 ref 失败后，模型提供者所有者不会回退到环境或 auth-profile 凭据。
  • 重载和重启检查会隔离符合条件的已映射所有者。未更改的 ref 身份、未更改的提供者定义以及未更改的完整非 secret 所有者契约会将其确切的最后已知良好值保留为 stale；已更改或新配置的未解析 ref 仅对该所有者发布 cold。严格的重载失败会保留先前活动的快照。
  • config.set、config.apply 和 config.patch 接受语法有效但未解析的 refs（针对可隔离所有者），并返回已脱敏的 degradedSecretOwners 报告。Gateway 入口认证、结构无效的配置或解析值、策略违规以及未知所有者仍会在磁盘修改前被拒绝。
  • 即使另一个所有者处于 cold 或 stale 状态，健康的兄弟所有者仍会正常解析和发布。
  • 已知的脱敏占位符会使其映射的、可隔离的所有者变为 configured-unavailable，且不会复用其先前的凭据，即使该所有者的另一个引用也失败。Gateway 令牌/密码认证会拒绝启动，并附带受影响的引用和修复指引。Doctor 可以在经过验证的备份后修复存储后端的 Gateway 令牌；其他 secrets 需要在其来源处替换。
  • 向外发辅助/工具调用提供显式的每次调用通道令牌不会触发 SecretRef 激活；激活点仍为启动、重载和显式 secrets.reload。

降级与恢复信号

当健康状态后的重载时激活失败时，OpenClaw 进入降级的 secrets 状态，并发出一次性系统事件和日志代码：

  • SECRETS_RELOADER_DEGRADED
  • SECRETS_RELOADER_RECOVERED

行为：

  • 降级：健康所有者刷新，stale 所有者保留最后已知的良好值，cold 所有者保持不可用。
  • 恢复：在下次成功激活后发出一次。它确认恢复，包括那些没有可用先前凭据的 cold 所有者。
  • 已处于降级状态时反复失败会记录警告，但不会重新发出该事件。
  • 严格的启动失败永远不会发出降级事件，因为运行时从未变为活动状态。带有 cold 所有者的成功启动会记录所有者降级，但不会发出重载器事件。
  • Ref 范围的启动和重载失败会为每个受影响的所有者发出结构化的 SECRETS_DEGRADED 警告。Provider 范围的中断会发出一次 SECRETS_PROVIDER_DEGRADED 警告，附带 provider 和完整的受影响所有者列表，而不是为每个所有者重复 provider 失败。警告包含脱敏的原因、cold 或 stale 所有者状态，以及 openclaw secrets reload 重试提示。它们从不包含已解析的值或 SecretRef id。
  • openclaw doctor 列出 cold 和 stale 所有者及其受影响的配置路径、脱敏原因和重试指引。
  • 通道健康和状态会将 cold 账户保持为已配置但不可用，与健康账户并列。只读检查不会解析非活动凭据或探测 cold 账户。/healthz 仍报告 Gateway 存活；/readyz 可能报告受影响的通道为失败状态，直到其恢复。恢复该 secret，然后运行 openclaw secrets reload。

命令路径解析

命令路径可以通过 gateway 快照 RPC 选择启用受支持的 SecretRef 解析。适用两种广泛的行为：

例如 openclaw memory 的远程内存路径，以及 openclaw qr --remote 在需要远程共享 secret refs 时。它们从活动快照读取，并在所需 SecretRef 不可用时快速失败。

例如 openclaw status、openclaw status --all、openclaw channels status、openclaw channels resolve、openclaw security audit，以及只读的 doctor/config 修复流程。它们同样优先使用活动快照，但在目标 SecretRef 不可用时选择降级而不是中止。

只读行为：

- 当网关正在运行时，这些命令首先从活动快照中读取。
- 如果网关解析不完整或网关不可用，它们会尝试针对该命令面进行定向的本地回退。
- 如果定向的 SecretRef 仍然不可用，命令会继续运行，并输出降级的只读结果和明确诊断：该 ref 已配置但在当前命令路径中不可用。
- 这种降级行为仅限当前命令本身；它不会削弱运行时启动、重载或发送/认证路径。

使用匹配且已准备好的网关快照的 Agent 轮次，不会在轮次启动时重新解析每个模型和工具凭据。因此，已配置但不可用的提供方不会阻塞使用健康提供方的轮次。选择不可用提供方时，仍会在环境或 auth-profile 回退之前以失败关闭（fail-closed）方式失败，且显式定向的渠道/账户凭据仍然保持严格。

未进行 config-ref 准备的独立 Agent 命令，以及使用不同配置的调用，仍采用严格的命令级解析。本地非投递类 Agent 命令不会解析无关的渠道或网关凭据。

其他说明：

  • 后端密钥轮换后的快照刷新由 openclaw secrets reload 处理。
  • 这些命令路径使用的网关 RPC 方法：secrets.resolve。

审计与配置工作流

默认操作流程：

1. 审计当前状态

openclaw secrets audit --check

2. 配置并应用 SecretRefs

openclaw secrets configure --apply

3. 重新审计

openclaw secrets audit --check

在重新审计结果干净之前，请勿将迁移视为完成。如果审计仍报告存在静态明文值，那么即使运行时 API 返回脱敏值，Agent 访问风险依然存在。

如果你在 configure 期间保存了计划而不是应用它，请在重新审计前使用 openclaw secrets apply --from <plan-path> 应用该保存的计划。

secrets audit

审计发现包括：

  • 静态明文值（openclaw.json、SQLite auth-profile 行、.env 以及生成的 agents/*/agent/models.json）。
  • 生成的 models.json 条目中包含明文敏感提供方请求头残留。
  • 未解析的 refs。
  • 优先级遮蔽（SQLite auth-profile 优先于 openclaw.json refs）。
  • Store 残留（某个已存储名称在配置中仍存在等价的明文值）。

初始缺失的生成 models.json 文件会被跳过。读取现有文件时，审计强制执行 5 MiB 限制，并将叶符号链接、非普通文件以及读取或解析失败报告为 REF_UNRESOLVED。解析诊断会标明文件，但不会回显其内容。

Exec 说明：默认情况下，审计会跳过 exec SecretRef 可解析性检查，以避免命令副作用。如需在审计期间执行 exec 提供方，请使用 openclaw secrets audit --allow-exec。

请求头残留说明：敏感提供方请求头检测基于名称启发式规则（常见的认证/凭据请求头名称和片段，如 authorization、x-api-key、token、secret、password 和 credential）。

secrets configure

交互式辅助工具，可以：

  • 首先配置 secrets.providers（env/file/exec/store，添加/编辑/移除）。
  • 允许你在 openclaw.json 中选择受支持的承载密钥字段，并为单个 Agent 作用域选择 SQLite auth-profile 存储。
  • 可以直接在目标选择器中创建新的 auth-profile 映射。
  • 捕获 SecretRef 详细信息（source、provider、id）。
  • 运行预检解析，并可立即应用。

Exec 说明：除非设置了 --allow-exec，否则预检会跳过 exec SecretRef 检查。如果你直接从 configure --apply 应用，且计划中包含 exec refs/提供方，请确保 apply 步骤中也设置了 --allow-exec。

实用模式：

  • openclaw secrets configure --providers-only
  • openclaw secrets configure --skip-provider-setup
  • openclaw secrets configure --agent <id>

configure 的 apply 默认行为：

  • 清除目标提供方在 SQLite auth-profile 行中匹配的静态凭据。
  • 保留已退役的 auth.json 不动；运行 openclaw doctor --fix 以迁移并归档它。
  • 从生效状态和活动配置 .env 文件中清除匹配的已知密钥行（当两个路径匹配时去重）。
secrets apply

应用已保存的计划：

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec

Exec 说明：dry-run 会跳过 exec 检查，除非设置了 --allow-exec；写模式会拒绝包含 exec SecretRefs/提供方的计划，除非设置了 --allow-exec。

有关严格目标/路径契约的详细信息以及精确的拒绝规则，请参阅 Secrets Apply Plan Contract。

单向安全策略

Warning

OpenClaw 有意不写入包含历史明文密钥值的回滚备份。

安全模型：

  • 进入写模式前，预检必须成功。
  • 提交前会验证运行时激活是否成功。
  • Apply 使用原子文件替换更新文件，并在失败时尽力恢复。

旧版认证兼容性说明

对于静态凭据，运行时不再依赖明文旧版认证存储。

  • 运行时凭据来源是解析后的内存快照。
  • 发现旧版静态 api_key 条目时会将其清除。
  • 与 OAuth 相关的兼容性行为保持独立。

控制界面

打开 Settings → Secrets 可列出、添加、编辑、批量导入或软删除团队级条目。对于由 SecretRefs 使用或用于目标绑定的网关出站的只写值，请选择 Protected secret。仅当网关托管的 Agent 命令必须以明文接收，且该 Agent 可能打印、传输或持久化该值时，才选择 Agent-readable environment。Bulk Add 接受 dotenv 格式的 NAME=VALUE 赋值，包括带引号的多行值。Protect credential-like names automatically 默认会将形似凭据的名称设为受保护模式。

此 store 页面仅管理值。请通过其设置表单或原始编辑器，在受支持的字段上配置对应的 store SecretRef。身份作用域条目保留给后续版本，此页面不会暴露它们。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw