密钥运行时模型

本页介绍机密（secrets）在运行时的行为：所有者隔离、出口时哨兵注入、代理访问边界、活动表面过滤，以及报告这些情况的预检诊断。

运行时模型¶

• 机密会在激活期间主动解析为内存中的运行时快照，而非在请求路径上惰性解析。
• 冷 Gateway 启动时，如果某个可重试的 SecretRef 故障所对应的已知非 Gateway 所有者支持隔离，则该故障会被隔离。已映射的所有者类别包括模型提供方和技能、媒体/TTS/定时任务提供方、符合条件的认证配置文件、每个代理的内存、沙箱 SSH、频道账户，以及清单声明的插件路由。Gateway 会正常启动，将该所有者记录为“已配置但不可用”，并发出经过脱敏处理的降级警告。Gateway 入站认证、结构无效的引用或解析值、fail-closed 的所有者，以及运行时所有者未映射的引用，仍会导致启动失败。
• 重载会独立验证每个已映射的所有者，然后发布一个原子快照。健康的所有者会刷新。符合条件的失败所有者会保留其上次已知的良好值，并且仅当其引用标识、提供方定义和完整的非机密所有者契约均未改变时，才会变为过期（stale）；发生改变或新增的失败所有者会变为冷（cold）。严格失败会拒绝重载并保留当前活动的快照。
• 配置重载还会在机密提供方编辑更改了解析后的凭据时，协调频道连接。支持账户级重载的插件只重启受影响的命名账户；共享、默认、已删除或未解析的账户更改则使用插件的整频道重启策略。冷账户会停止，符合条件的过期账户会继续使用其上次已知的良好凭据，恢复过程会保留手动停止状态。
• 策略违规（例如 OAuth 模式的认证配置文件与 SecretRef 输入组合）会在运行时切换之前导致激活失败。
• 运行时请求只读取当前活动的内存快照。模型提供方的 SecretRef 凭据在出口之前，以进程本地哨兵的形式通过认证存储和流选项传递。出站投递路径（Discord 回复/线程投递、Telegram 操作发送）也读取该快照，不会每次发送都重新解析引用。
• 只读频道能力发现会独立评估账户。一个已配置但不可用的账户不会隐藏健康兄弟账户的消息操作，而通过该不可用账户的直接发送仍然 fail-closed。

这使机密提供方的故障不会进入热请求路径。

Gateway 入站保护、结构无效的配置或解析值、策略违规以及未知所有权仍然 fail-closed。被隔离的所有者绝不会回退到较低优先级的凭据源。

当启动时数据库准入将某个代理标记为不可用时，机密的准备工作会省略该数据库的认证存储，并将其拒绝和修复指导记录为冷存储所有者。它不会用空的凭据存储替代。没有对应准入拒绝的不可读存储仍然会导致准备失败。数据库准入所有者控制恢复；仅靠机密重载无法重新准入该代理。

出口时注入（哨兵）¶

对于由 SecretRef 支持的模型提供方凭据，OpenClaw 在模型认证解析期间生成一个不透明的、进程本地的哨兵。因此，认证存储、流选项、SDK 配置、日志、错误对象以及大多数运行时内省看到的都是类似 oc-sent-v2.<authenticated-ciphertext>.end 的值，而不是提供方凭据。受保护的模型 fetch 和受管理的本地提供方健康探测会在每个请求离开进程之前，立即替换 URL 和头部值中的已知哨兵。

未知的哨兵形状值会在网络活动之前 fail-closed。OpenClaw 拒绝发送请求，而不是将未解析的哨兵转发给提供方。已解析的机密值也会被注册为精确值日志脱敏对象，作为纵深防御措施。

提供方适配器使用其 SDK 支持的最新注入点：

• 具有自定义 fetch 选项的 SDK 会收到 OpenClaw 的受保护 fetch，因此 SDK 保留哨兵。
• 没有自定义 fetch 选项的 SDK 会在客户端构造之前立即解包哨兵。插件拥有的提供方流和代理框架在最终核心所有的交接点解包，因为这些传输不共享 OpenClaw 的受保护 fetch。

哨兵减少了模型调用链中的明文暴露，但它们不是进程隔离。真实值仍然存在于同进程内存中，并出现在最终适配器边界。未通过 SecretRef 配置的普通环境凭据仍然是明文，并且不在此机制范围内。

设置 OPENCLAW_SECRET_SENTINELS=off（也接受 0 或 false，不区分大小写）可在事件响应或兼容性故障排查期间禁用模型提供方哨兵生成。此开关既不会禁用精确值脱敏注册，也不会禁用 Gateway 托管子进程的保护存储密封。

代理访问边界¶

SecretRef 阻止凭据被持久化到配置和生成的模型文件中，但它们不是进程隔离边界。如果明文凭据留在磁盘上代理可读的路径中，仍可通过文件或 shell 工具读取，从而绕过 API 级别的脱敏。

对于代理可访问文件在范围内的生产部署，仅当以下所有条件成立时，才应将迁移视为完成：

• 受支持的凭据使用 SecretRef 而非明文值。
• 遗留明文残留已从 openclaw.json、SQLite 认证配置文件存储、.env 和生成的 models.json 文件中清除。已退役的认证 JSON 是 doctor 拥有的迁移输入，绝不会被 secrets apply 重写。
• 迁移后，openclaw secrets audit --check 干净无报错。
• 任何剩余的不受支持或轮换凭据都已通过 OS 隔离、容器隔离或外部凭据代理得到保护。

这就是为什么 audit/configure/apply 工作流是一道安全迁移门禁，而不仅仅是一个便利工具。

活动表面过滤¶

SecretRefs 仅在实际有效的活动表面上进行验证：

• 已启用表面：对于已映射且可隔离的所有者，可重试故障会进入冷降级或过期降级。严格、失败关闭、Gateway 必需或未映射的故障会阻止启动/重新加载。
• 非活动表面：未解析的引用不会阻止启动/重新加载；它们会发出非致命的 SECRETS_REF_IGNORED_INACTIVE_SURFACE 诊断。

Gateway 身份验证表面诊断¶

当在 gateway.auth.token、gateway.auth.password、gateway.remote.token 或 gateway.remote.password 上设置了 SecretRef 时，Gateway 启动/重新加载会在代码 SECRETS_GATEWAY_AUTH_SURFACE 下记录表面状态：

• active：该 SecretRef 是有效身份验证表面的一部分，并且必须解析。
• inactive：另一个身份验证表面胜出，或远程身份验证已禁用/非活动。

日志条目包含所使用的活动表面策略的原因。

入门引用预检¶

在交互式入门过程中，选择 SecretRef 存储会在保存前运行预检验证：

• Env 引用：验证环境变量名称，并确认在设置期间可见非空值。
• Provider 引用（file、exec 或 store）：验证 provider 选择，解析 id，并检查解析后的值类型。
• 快速入门流程：当 gateway.auth.token 已经是 SecretRef 时，入门流程会在 probe/dashboard 引导之前解析它（针对 env、file、exec 和 store 引用），并使用相同的快速失败门控。
• 生成的 Gateway token：设置本身会签发 gateway.auth.token，因此引用模式没有需要提示的内容。如果导出了 OPENCLAW_GATEWAY_TOKEN，它会向该变量写入一个 env 引用，使后续轮换保持权威；否则，它会将 token 写入 OPENCLAW_GATEWAY_TOKEN 下的 secret store，并存储一个 store 引用。现有 store 条目会被复用而不是轮换，因此重新运行设置永远不会使已配对的客户端失效。

验证失败会显示错误并允许你重试。