密钥操作和行为
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.jsonrefs 时的审计发现)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_DEGRADEDSECRETS_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. 审计当前状态
2. 配置并应用 SecretRefs
3. 重新审计
在重新审计干净之前,不要将迁移视为完成。如果审计仍报告存储的明文值,即使运行时 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.jsonrefs)。 - 存储残留(已存储的名称在 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-onlyopenclaw secrets configure --skip-provider-setupopenclaw 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