跳转至

密钥运行时模型

本页介绍密钥在运行时如何表现:所有者隔离、出口时哨兵注入、代理访问边界、活跃表面过滤,以及报告这些内容的预检诊断。

运行时模型

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

这样可将密文提供方故障排除在热请求路径之外。

Gateway 入口保护、结构无效的配置或解析值、策略违规以及未知所有权依然会故障关闭。被隔离的所有者绝不会回退到较低优先级的凭据来源。

当启动数据库准入将某个代理标记为不可用时,密钥准备会省略该确切数据库的认证存储,而不会替换为空凭据存储。待处理的后台检查不是密钥故障:准入所有者会在准入该代理之前解析并发布该代理的凭据,并准备好其模型。成功准备后无需手动重载密钥。失败的检查与所有权拒绝仍为带有修复指导的冷存储所有者。没有匹配准入拒绝的不可读存储仍会导致准备失败;仅靠密钥重载无法重新准入该代理。

后台准备会将已保存的模型配置与运行时目录默认值分开保留,因此恢复不会禁用其他兼容的运行时选择,例如 Codex。

出口时注入(哨兵)

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

未知的哨兵形状值会在网络活动之前故障关闭。OpenClaw 拒绝发送该请求,而不是将未解析的哨兵转发给提供方。作为纵深防御措施,已解析的密文值也会被注册用于精确值日志脱敏。

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

  • 具有自定义 fetch 选项的 SDK 会收到 OpenClaw 的受防护 fetch,因此 SDK 保留哨兵。
  • 没有自定义 fetch 选项的 SDK 会在客户端构造之前立即解开哨兵。插件拥有的提供方流和代理 harness 在最终由核心拥有的交接处解开哨兵,因为这些传输不共享 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 结果为干净。
  • 任何剩余的不受支持或正在轮换的凭据都由操作系统隔离、容器隔离或外部凭据代理保护。

这就是为什么 audit/configure/apply 工作流是一个安全迁移门禁,而不仅仅是一个便捷助手。

Warning

SecretRefs 不会使任意可读文件变得安全。备份、复制的配置、旧版生成的模型目录以及不受支持的凭据类别,在删除、移出代理信任边界或单独隔离之前,仍然是生产机密。

活动表面过滤

SecretRefs 仅在有效活动表面上进行验证:

  • 已启用表面:对于已映射且可隔离的所有者,可重试故障会进入冷或陈旧降级。严格、失败关闭、Gateway 必需或未映射的故障会阻止启动/重载。
  • 非活动表面:未解析的引用不会阻止启动/重载;它们会发出非致命的 SECRETS_REF_IGNORED_INACTIVE_SURFACE 诊断。
非活动表面的示例
  • 已禁用的渠道/账户条目。
  • 没有任何已启用账户继承的顶层渠道凭据。
  • 已禁用的工具/功能表面。
  • 未被 tools.web.search.provider 选中的 Web 搜索 provider 特定密钥。在自动模式(provider 未设置)下,密钥会按优先级用于自动检测,直到其中一个解析成功;选择后,未选中的 provider 密钥为非活动。
  • 沙箱 SSH 认证材料(agents.defaults.sandbox.ssh.identityData、certificateData、knownHostsData,以及每个代理的覆盖项)仅在有效沙箱后端为 ssh 且沙箱模式不为 off 时,对默认代理或已启用代理处于活动状态。
  • gateway.remote.token / gateway.remote.password SecretRefs 在以下任一条件成立时处于活动状态:
  • gateway.mode=remote
  • gateway.remote.url 已配置
  • gateway.tailscale.mode 为 serve 或 funnel
  • 在本地模式且没有那些远程表面时:当 token 认证可以胜出且未配置 env/auth token 时,gateway.remote.token 处于活动状态;仅当 password 认证可以胜出且未配置 env/auth password 时,gateway.remote.password 处于活动状态。
  • 活动的 gateway.auth.token / gateway.auth.password SecretRefs 相对于 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD 保持权威;当相应的本地配置输入缺失时,环境变量凭据作为回退。

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 时,入门流程会在 check/dashboard 引导之前解析它(针对 env、file、exec 和 store 引用),并使用相同的快速失败门禁。
  • 生成的 Gateway token:setup 本身会生成 gateway.auth.token,因此引用模式没有需要提示的内容。如果导出了 OPENCLAW_GATEWAY_TOKEN,它会向该变量写入一个 env 引用,使后续轮换保持权威;否则,它会将 token 写入 secret store 下的 OPENCLAW_GATEWAY_TOKEN,并存储一个 store 引用。现有 store 条目会被复用而不是轮换,因此重新运行 setup 永远不会使已配对的客户端失效。

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

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