跳转至

密钥操作和行为

This page covers day-to-day secrets operation: the supported credential surface, required behavior and precedence, activation and recovery signals, and the audit, configure, and apply workflow.

支持的凭据范围

规范的支持与不支持的凭据列于 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。当未设置时,Doctor 会将已弃用的同级 serviceAccountRef 移入此规范字段。

激活触发器

机密激活在以下情况运行:

  • 启动(预检加最终激活)
  • 配置重载热应用路径
  • 配置重载重启检查路径
  • 通过 secrets.reload 手动重载
  • 网关配置写入 RPC 预检(config.set / config.apply / config.patch),在持久化编辑之前验证已提交配置负载中活动表面的 SecretRefs

激活契约:

  • 成功时原子地交换快照。
  • 严格启动失败会中止网关启动。
  • 在冷启动期间,对于已映射、可隔离的非网关所有者,可重试解析失败可能发布快照,并使该确切所有者处于配置不可用状态。对该所有者的请求以 SECRET_SURFACE_UNAVAILABLE 失败;模型提供程序所有者在显式 ref 失败后不会回退到环境或 auth-profile 凭据。
  • 重载和重启检查会隔离符合条件的已映射所有者。未更改的 ref 标识,若提供程序定义未更改且完整的非机密所有者契约未更改,则保留其确切的最后已知良好值作为陈旧值;已更改或新配置的未解析 ref 仅为该所有者发布冷状态。严格重载失败会保留先前活动的快照。
  • config.set、config.apply 和 config.patch 接受可隔离所有者的语法有效未解析 ref,并返回脱敏的 degradedSecretOwners 报告。网关入口认证、结构无效的配置或已解析值、策略违规以及未知所有者仍会在磁盘变更之前被拒绝。
  • 即使另一个所有者处于冷或陈旧状态,健康的同级所有者也会正常解析并发布。
  • 已知脱敏占位符会使其已映射、可隔离的所有者处于配置不可用状态,而不会重用其先前凭据,即使该所有者的另一个引用也失败。网关 token/密码认证会拒绝启动,并给出受影响的引用和修复指导。Doctor 可以在经过验证的备份后修复基于存储的网关 token;其他机密需要在源头替换。
  • 为出站 helper/tool 调用提供显式的每次调用通道 token 不会触发 SecretRef 激活;激活点仍为启动、重载和显式 secrets.reload。

降级与恢复信号

当重载时激活在健康状态后失败,OpenClaw 进入机密降级状态,并发出一次性系统事件和日志代码:

  • SECRETS_RELOADER_DEGRADED
  • SECRETS_RELOADER_RECOVERED

行为:

  • 降级:健康所有者刷新,陈旧所有者保留最后已知良好值,冷所有者保持不可用。
  • 恢复:在下次成功激活后发出一次。它确认恢复,包括没有可用先前凭据的冷所有者。
  • 在已降级期间重复失败会记录警告,但不会重新发出事件。
  • 严格启动失败从不发出降级事件,因为运行时从未变为活动。带有冷所有者的成功启动会记录所有者降级,但不会发出 reloader 事件。
  • ref 范围的启动和重载失败会为每个受影响所有者发出结构化 SECRETS_DEGRADED 警告。提供程序范围的中断会发出一个 SECRETS_PROVIDER_DEGRADED 警告,包含提供程序和完整受影响所有者列表,而不是按所有者重复提供程序失败。警告包含脱敏原因、cold 或 stale 所有者状态,以及 openclaw secrets reload 重试提示。它们从不包含已解析值或 SecretRef id。
  • openclaw doctor 列出冷和陈旧所有者及其受影响配置路径、脱敏原因和重试指导。
  • 需要迁移的已弃用 auth-profile 文件会在网关警告和 Doctor 中报告 auth profile migration required,修复命令为 openclaw doctor --fix。Doctor 负责经过验证的导入和归档;重载机密不会迁移这些文件。
  • 通道健康和状态会将冷账户显示为已配置但不可用,与健康账户并列。只读检查不会解析非活动凭据或检查冷账户。/healthz 仍报告网关存活状态;/readyz 可能报告受影响通道失败,直到其恢复。恢复机密,然后运行 openclaw secrets reload。

命令路径解析

命令路径可以通过网关快照 RPC 选择加入支持的 SecretRef 解析。两种广义行为适用:

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

=== "只读命令路径" {#read-only-command-paths}

例如 `openclaw status`、`openclaw status --all`、`openclaw channels status`、`openclaw channels resolve`、`openclaw security audit`,以及只读 doctor/config 修复流程。它们也优先使用活动快照,但当目标 SecretRef 不可用时,会降级而不是中止。

只读行为:

- 当 gateway 正在运行时,这些命令会先从活动快照读取。
- 如果 gateway 解析不完整或 gateway 不可用,它们会针对该命令表面尝试定向本地回退。
- 如果目标 SecretRef 仍然不可用,命令会以降级的只读输出继续,并给出明确诊断:该 ref 已配置,但在该命令路径中不可用。
- 这种降级行为仅针对命令本地;它不会削弱运行时启动、reload 或 send/auth 路径。

使用匹配的准备就绪 Gateway 快照的 Agent 回合不会在回合启动时重新解析每个模型和工具凭据。因此,已配置但不可用的 provider 不会阻止使用健康 provider 的回合。选择不可用的 provider 仍会在 environment 或 auth-profile 回退之前失败关闭,并且显式指定的 channel/account 凭据仍保持严格。

没有 config-ref 准备的独立 agent 命令,以及使用不同 config 的调用,仍保留严格的命令范围解析。本地非投递 agent 命令不会解析无关的 channel 或 Gateway 凭据。

其他说明:

  • 后端 secret 轮换后的快照刷新由 openclaw secrets reload 处理。
  • 这些命令路径使用的 Gateway 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 条目中残留的明文敏感 provider 头。
  • 未解析的 refs。
  • 优先级遮蔽(SQLite auth profiles 优先于 openclaw.json refs)。
  • 存储残留(已存储的名称在 config 中仍有等效明文值)。

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

Exec 说明:默认情况下,audit 会跳过 exec SecretRef 可解析性检查,以避免命令副作用。使用 openclaw secrets audit --allow-exec 可在审计期间执行 exec providers。

头残留说明:敏感 provider 头检测基于名称启发式(常见的 auth/credential 头名称和片段,例如 authorization、x-api-key、token、secret、password 和 credential)。

secrets configure

交互式辅助工具,用于:

  • 首先配置 secrets.providers(env/file/exec/store,添加/编辑/删除)。
  • 让你选择 openclaw.json 中受支持的承载 secret 的字段,以及一个 agent 范围的 SQLite auth-profile 存储。
  • 可以直接在目标选择器中创建新的 auth-profile 映射。
  • 捕获 SecretRef 详情(source、provider、id)。
  • 运行预检解析,并可立即应用。

Exec 说明:除非设置 --allow-exec,否则预检会跳过 exec SecretRef 检查。如果你直接从 configure --apply 应用,并且计划包含 exec refs/providers,请在应用步骤也保持设置 --allow-exec。

有用模式:

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

configure 应用默认行为:

  • 从目标 provider 的 SQLite auth-profile 行中清除匹配的静态凭据。
  • 保持已弃用的 auth.json 不变;运行 openclaw doctor --fix 以迁移并归档它。
  • 从有效状态和活动配置 .env 文件中清除匹配的已知 secret 行(当两个路径匹配时去重)。
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/providers 的计划,除非设置 --allow-exec。

有关严格 target/path 契约详情和确切拒绝规则,请参阅 Secrets Apply Plan 契约。

单向安全策略

Warning

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

安全模型:

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

旧版身份验证兼容性说明

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

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

控制界面

打开 设置 → 密钥,以列出、添加、编辑、批量导入或软删除团队范围的条目。对于 SecretRefs 或绑定目标地址的 Gateway 出口所使用的仅可写入值,请选择 受保护的密钥。仅当 Gateway 托管的代理命令必须接收明文,并且代理可能打印、传输或持久化该明文时,才选择 代理可读环境。批量添加接受 dotenv NAME=VALUE 赋值,包括带引号的多行值。自动保护类似凭据的名称 会将凭据形态的名称默认设置为受保护模式。

此存储页面仅管理值。请通过其设置表单或原始编辑器,在受支持的字段上配置对应的 store SecretRef。身份范围的条目保留给后续版本,此页面不暴露这些条目。

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