本页内容

本页内容

网关

Auth 凭据语义

这些语义使选择时和运行时的 auth 行为保持一致。它们被以下部分共享:

  • resolveAuthProfileOrder(配置文件排序)
  • resolveApiKeyForProfile(运行时凭据解析)
  • openclaw models status --probe
  • openclaw doctor auth 检查(doctor-auth)

稳定检查原因代码

检查结果携带status桶(ok、auth、rate_limit、billing、timeout、format、unknown、no_model)加上一个稳定的reasonCode 当检查从未到达模型调用时:

reasonCode 含义
excluded_by_auth_order 该配置文件未包含在其提供者的显式认证顺序中。
missing_credential 未配置内联凭据或 SecretRef。
expired Token 的 expires 时间早于当前时间。
invalid_expires expires 不是一个有效的正 Unix 毫秒时间戳。
unresolved_ref 配置的 SecretRef 无法解析。
ineligible_profile 配置文件与提供者配置不兼容(包括格式错误的密钥输入)。
no_model 凭证存在,但没有可以测试解析的候选模型。

资格检查会将可用凭据的原因码报告为 ok。

Token 凭据

令牌凭证 (type: "token") 支持内联 token and/or tokenRef。

资格规则

  1. 当 token 和 tokenRef 都缺失时,Token 配置文件不符合资格(missing_credential)。
  2. expires 是可选项。存在时,它必须是一个有限的 Unix epoch 毫秒数,且大于 0,并且不大于 JavaScript Date 的最大时间戳(8640000000000000)。
  3. 如果 expires 无效(类型错误、NaN、0、负数、非有限值,或超过该最大值),则该配置文件不符合资格,错误为 invalid_expires。
  4. 如果 expires 已经过期,则该配置文件不符合资格,错误为 expired。
  5. tokenRef 不会绕过 expires 校验。

解析规则

  1. 解析器语义与 expires 的资格语义一致。
  2. 对于符合资格的配置文件,token 材料可以从内联值或 tokenRef 中解析。
  3. 无法解析的引用在 models status --probe 输出中生成 unresolved_ref。

手动API按键

在模型中保存手动 API 密钥会等待网关在刷新模型身份验证之前应用任何更改的提供程序绑定。替换绑定未改变的密钥只需要刷新认证即可。如果网关无法确认应用程序,密钥将保持保存,并且响应包括重新启动警告。这会保留配置的重新加载策略,包括禁用的重新加载。删除密钥仍然会拒绝同时更改的绑定或凭据。

命名现有兼容 API-key 或令牌配置文件的提供程序 apiKey 值是配置文件绑定,而不是文字凭证。模型发现通过聊天请求使用的相同配置文件分类来解析这些绑定,包括提供程序和基本 URL 兼容性检查。不命名存储的配置文件的值仍然是文字键。保存密钥不会更改存储的绑定格式。

设置替换

设置替换凭据保存在单独的配置文件 ID 下,并在现有凭据负载中使用内部 setup 描述符。它们无法进入正常轮换,无法通过显式配置文件 pin 进行解析,也无法复制到另一个代理。只有所属的设置操作才能测试所选的凭据。成功完成一次免工具转动后,安装程序会询问是否激活它。拒绝或失败测试会使保存的凭据保持非活动状态并保留当前连接。模型设置为新测试提供相同的已保存登录信息,无需再次登录。如果应用替换失败,恢复会在重建之前的连接之前恢复其非活动状态。网关激活等待配置申请;所需的重新启动将使替换保持不活动状态,直到重试安装为止。普通登录仍然是即时的。该描述符保留所选模型和连接设置以供重新启动后重试,而不缓存验证结果。这不会添加数据库架构或迁移;较旧的运行时不会强制执行非活动状态。降级之前,请删除保存的非活动替换或恢复设置之前的状态。

非交互式设置会保存替换凭据并打印 openclaw models auth activate <profileId> --agent <id> 命令来测试和激活保存的登录。模型设置提供相同的操作。交互式设置默认在测试成功后激活。重用现有凭据和首次运行非交互式设置保留其现有行为。

Agent 复制可移植性

代理身份验证继承是通读的。当代理没有本地配置文件时,它会在运行时解析共享身份验证存储中的配置文件,而不将秘密材料复制到其自己的凭证存储中 (agents/<agentId>/agent/openclaw-agent.sqlite)。 openclaw doctor --fix 执行一次性重定位后,共享存储位于 state/openclaw.sqlite 中。在此之前,医生会报告旧的 agents/main/agent/openclaw-agent.sqlite 所有者,并使该代理无法删除。

OAuth 同级同步首先写入选定的主配置文件,然后在其他同级之前写入发现的共享所有者。无论文件系统目录顺序如何,这都会保留通读继承。所选代理树外部的共享所有者不会添加到同步目标。

身份验证使用和冷却更新等待其实际代理数据库所有者(包括旧共享存储)的写入许可。重新定位的共享状态身份验证使用自己的协调器。排队的更新保留其选定的状态根和共享所有者,然后在准入后读取当前配置文件。运行时快照在持久提交之后和下一个承认的编写器之前发布;在健康更新等待期间删除配置文件不会重新创建其健康状态。冷代理打开异步验证完整性并在写入之前重新检查所有权。 OAuth 更新插入在准入后重新检查当前本地或继承的凭证,然后再应用现有的代替换规则。

运行时身份验证存储更新将其读取、合并、编码和提交保留在现有的 SQLite 工作线程中。更新回调最多针对事务的当前行执行一次;在提交之前再次检查现场所有者的入场情况。本地更新拒绝在准备期间观察到的共享存储更改,而无需重放回调。大单元作为有界域跨越工作边界。共享凭证发布重用已提交的共享存储,并保持未受影响的本地快照及其修订完好无损。已解决的机密仍属于其现有运行时所有者。 Doctor auth 修复保留其架构维护租约所拥有的本机事务;他们不借用普通工人的权威。模型目录工作人员使用其请求的本机身份验证写入范围,固定到捕获的状态根。该请求等待声明的 OAuth 刷新解决,然后关闭该范围;保留的回调在关闭后无法写入。每个目录请求都携带网关承诺的共享存储所有权。重用的工作人员在读取凭据之前安装该事实,因此第一次登录的空存储重定位不能将发现附加到旧位置。目录准备携带持久存储检查结果和带有凭证视图的选定显示路径。标签重用该请求的源选择;下一次刷新会观察已提交的更改。外部凭证刷新和最终凭证授权检查保持不变。临时探针存储在删除凭据文件之前等待其数据库工作和共享注册表删除。如果处理失败,清理会保留该目录并报告其位置。存储格式、架构版本以及更新或回滚行为均保持不变。

内联 API-key 失败簿记通过其现有的 SQLite 工作线程读取并更新所选代理的身份验证状态。它保留凭证字节和其他配置文件的健康状态。运行时快照发布从线程外读取存储的本地和共享行,然后保留当前主机的已解析机密和外部配置文件覆盖。发布失败不会重播已提交的运行状况更新。同步 SDK 商店 API 保留其现有合约。

当凭证、配置文件排序或所有权或模型可用性发生变化(包括冷却时间和阻止状态转换)时,网关模型元数据会刷新。使用时间戳、成功历史记录和失败计数器会保留记录,而不会导致聊天元数据失效或向连接的客户端广播更改。

网关模型身份验证状态读取跨客户端为同一代理和发布的 config/auth 生成的共享提供程序准备。凭证警告和过期边界也会使准备工作无效;显式刷新会绕过它。每个回复仍然计算当前的到期持续时间,从其现有缓存中读取辅助使用情况,并应用请求客户端的配置文件身份可见性。文件支持的外部 CLI 引导程序运行状况与其读者的新鲜生命周期保持一致,因为外部登录可以在没有网关发布的情况下更改。

重复的模型解析重用深度冻结的持久身份验证行,而身份验证发布修订和拥有的数据库身份保持不变。提交的身份验证写入、未分类的数据库写入和运行时快照重新加载会立即使这些行失效。被认证为仅会话的写入会保留相同的不可变行,而无需再次读取或冻结它们。每个请求保留自己的实时读取权限;缓存重用无法恢复已撤销的读取器。如果第一个会话创建该数据库,则在代理数据库存在之前准备的身份验证读取将保持为空。稍后读取观察新文件;替换已捕获的文件仍然会使其读取无效。每个请求仍会运行范围覆盖、迁移拒绝和个人帐户选择。隔离代理作用域和私有数据库快照不共享此缓存。网关缓存未重用其生命周期在关闭时结束的只读子级;每次读取都会重新获取其源许可并在返回之前关闭其 SQLite 句柄。 Reader 启动规范化有效状态目录,因此隐式默认目录和相同的显式固定目录重用该子目录。不同的状态目录、环境或源仍然会取代它。分离的连接、cron、心跳和挂钩回调保留该网关的只读工作范围,而不继承启动或请求权限。 Shutdown 在创建另一个读取器之前拒绝延迟回调。使用簿记会使以后的缓存重用无效,而允许的读取可以完成其快照。凭证、选择、所有权和生命周期的变化仍然会使飞行中的准备工作失效。模型选择在其读取器完成清理后重试过时读取一次,保留所选代理和任何显式配置文件引脚。如果正在进行的 OAuth 刷新使读取无效,则选择首先观察该所有者的持久结算,包括继承的凭证和受保护的对等点。此等待使用现有的刷新超时,既不读取凭据也不启动另一次刷新。重新连接释放等待被替换的声明;仍然被围起来的同行的读者继续等待所有者的清理工作。待更新的配置文件仍然是模型 id/mode 选择的候选者; OAuth 所有者仍先解决刷新问题,然后才能使用凭据。调用者超时不会从观察中撤销其持久结算,并且等待模型读取无法取消它。取消模型请求仅结束其结算等待;刷新所有者和其他等待请求独立继续。持续的更改、拒绝接纳和清理失败仍然是错误。

通过 resolveApiKeyForProvider 和 resolveApiKeyForProfile 的凭证查找也接受可选的中止信号。取消会结束呼叫者对排队准入、配置文件锁定或刷新的等待。排队任务在声明凭据之前重新检查取消。开始的锁定获取保留了其清理所有者,并且声称的刷新保留了其独立的持久结算。取消的调用者无法启动稍后的排队刷新或返回其凭据。省略信号的调用者保留现有的等待行为。

在行进入缓存之前,工作人员会验证提交的 SQLite 可见性。具有未发布或尾随 WAL 帧的读取会正常返回而不保留。

显式复制流程(例如 openclaw agents add)使用此可移植性策略:

  • api_key 和 token 配置文件是可移植的,除非 copyToAgents: false。
  • oauth 配置文件默认不可移植,因为刷新令牌可能是一次性的或对轮换敏感。
  • 仅当跨代理复制刷新材料已知安全时,Provider 拥有的 OAuth 流才可以选择使用 copyToAgents: true;仅当配置文件包含内联 access/refresh 材料时,选择加入才适用。

除非目标代理单独登录并创建自己的本地配置文件,否则不可移植的配置文件仍然可以通过共享通读库使用。

在 OAuth 刷新期间,当前凭证生成将被惰性持久标记替换。默认情况下,待定标记仍然不合格,并且仅按运行时路径排序,这些路径立即将它们传递到结算感知解析器。失败的标记是终端,需要操作员再次进行身份验证。

代理本地对等点永远不会收到复制的轮换刷新材料。只有在验证共享凭证属于同一帐户后,对等方才会删除其标记并继承共享凭证。如果无法验证该身份,则对等方将保持最终隔离状态,而不是继承另一个帐户。

目录发现通过与刷新凭证相同的请求拥有的本地作者来隔离和解决历史同行。每个对等点更新都会保留其捕获的数据库文件身份,并比较写入事务内的凭证;空代理存储不会阻止共享存储刷新。如果对等防护在提供程序刷新开始之前失败,则会恢复已声明的凭据。一旦提供者请求开始,失败的刷新仍然会终止,因为提供者可能已经消耗了旧的刷新令牌。

插件 SDK OAuth 验证

从 openclaw/plugin-sdk/agent-runtime 导出的 resolveApiKeyForProfile 接受可选的 validateOAuthCredential 回调。解析器在返回 OAuth 凭证之前以及保留或采用刷新的凭证之前调用它。当旧版 provider:default 配置文件回退到替换 OAuth 配置文件时,回调也适用。

从回调中抛出会拒绝该凭据。被拒绝的回退不会返回或刷新,并且原始选定配置文件刷新失败仍然是操作员面临的错误。拒绝主动刷新或结算生成会阻止凭证访问,并可能使该生成及其对等体受到终端隔离,因此操作员必须再次进行身份验证。省略回调的调用者保留现有的解决方案和回退行为。

当切换到临时运行状态时,openclaw agent exec 保留原始共享存储根。其有界凭证范围从该共享存储读取可移植的 api_key 和 token 配置文件,而无需持久副本;配置的代理的本地配置文件仍然获胜。共享的 OAuth 配置文件被排除在此临时范围之外,即使使用 copyToAgents: true 也是如此,因此运行不会获取另一个刷新所有者。 --auth-env-only 完全禁用存储的凭据访问。

身份验证写入显式选择状态目录,包括隔离的 QA 暂存,使用该目录的共享存储来实现所有权和 OAuth 重复数据删除。它们的运行时发布和回滚保留相同的所有者;另一个进程本地状态根不是继承的基础。不相关的外部数据库可能较旧、较新或不可读,但不会阻止隔离的写入,但所选目标中的不可读或较新的数据库仍会阻止写入。没有显式状态目录的写入保留正常的环境状态和代理目录配置。

个人模特账户

从 设置 → 配置文件 → 连接的帐户 连接的帐户在共享状态数据库中有一个身份范围的所有者。它们的凭据和使用状态永远不会进入共享或代理本地身份验证存储、外部 CLI 镜像或全局运行时快照。运行时最多加载其会话选择的一个个人凭证。未链接的个人帐户仍然可以通过现有会话 pin 来使用,而不是通过自动选择新会话来使用。

个人 pin 保留现有的同一提供商故障转移策略:在固定帐户失败后可以尝试订购的共享帐户。他们不会将他人的个人账户作为备用账户。重连只能替换连接者自己的凭证;管理员创建的链接引用的共享凭据不是个人财产。请参阅 每人模型帐户。

仅配置的 auth 路由

auth.profiles 中 mode: "aws-sdk" 的条目是路由元数据,不是存储的凭据。它们在目标提供方使用 models.providers.<id>.auth: "aws-sdk" 时有效,这是插件拥有的 Amazon Bedrock 配置所写入的路由。这些 profile id 可能会出现在 auth.order 和会话覆盖中,即使凭据存储中没有匹配的条目。

不要在凭据存储中写入 type: "aws-sdk";存储的凭据只能是 api_key、token 或 oauth。如果旧版 auth-profiles.json 中有这样的标记,openclaw doctor --fix 会将其移到 auth.profiles,并从存储中移除该标记。

当删除选定的存储配置文件时,凭证范围的模型发现会在咨询动态模型元数据之前报告 selected_auth_profile_unavailable。恢复凭证或选择另一个配置的配置文件;注册模型并不能修复丢失的身份验证。仅配置 AWS SDK 配置文件在没有存储凭证的情况下仍然有效。当其凭据消失时,聊天准入和代理命令会保留显式的同一提供商选择,以便身份验证可以报告恢复情况。过时的自动选择和不兼容提供商的选择仍会被清除。

仅当提供商的帐户身份匹配器证明新凭证属于同一帐户时,OAuth 重新身份验证才会保留现有的配置文件 ID。不同或不明确的帐户保留提供者的新配置文件 ID,因此显式会话 pin 不会跨越帐户边界。不可用的引脚仍然严格并发出会话范围的警告。对于重新登录前已删除的凭证,请故意选择 model@profile 的已配置帐户,或重新连接 openclaw models auth login --provider <provider> --profile-id <selected-profile-id> 的预期帐户。升级期间不会重写任何会话行或存储的凭据。

显式 auth 顺序过滤

  • 当为提供程序设置 auth.order.<provider> 或验证存储顺序覆盖时,models status --probe 仅检查保留在该提供程序的已解析验证顺序中的配置文件 ID。存储的覆盖优先于 auth.order 配置。
  • 稍后不会静默尝试从显式订单中省略的该提供者的存储配置文件。检查输出报告 reasonCode: excluded_by_auth_order 和详细信息 Excluded by auth.order for this provider.
  • 有效的会话用户固定配置是一个明确的每会话例外:即使该配置文件未包含在提供方顺序中,OpenClaw 也会先尝试该配置文件,然后使用按顺序排列的同提供方配置文件作为重试候选项。冷却或禁用窗口只适用于受影响的配置文件;不会抑制其符合资格的同级配置文件。

准备好的代理请求使用其选择的插件元数据、配置、工作区和环境来获取身份验证配置文件资格、排序和环境凭证证据。空的选定插件集仍然具有权威性;另一个请求的插件别名无法添加配置文件或更改凭证所有者。

模型目录发现

用于模型发现的存储配置文件选择遵循已解析的身份验证顺序和资格规则。仅限于一种模型的冷却时间不会抑制帐户范围的目录发现。配置的订阅模式仍然附加到直接凭据,并且成功的 OAuth 准备将解析的当前令牌提供给其目录使用者,而不是捕获的商店的旧令牌。

当配置的 SecretRef 在活动运行时快照中具有匹配的凭据时,延迟提供程序目录会保留发现的模型。目录准入仅使用该凭据作为可用性证据:它不会再次解析引用或将值复制到模型行中。生成的目录中保留的未解决的引用和凭据不会授予许可。

环境支持的配置文件保留发现环境中的可用值,包括冷命令和工作路径。当该材料丢失时,只有所选配置文件的激活快照可以提供;否则,发现会在目录 HTTP 之前报告 unavailable。参考名称永远不会作为凭据发送或替换为其他配置文件的凭据。在网关上,恢复机密并运行 openclaw secrets reload,然后重试发现。

当每个符合条件的 OAuth 候选者准备失败时,发现会报告 unavailable 以及尝试的配置文件身份,而不是将提供程序视为未配置。兼容的先前库存仍然可用。可用的后备凭证仍然提供其自己的目录结果。

当目录截止日期到期时,迟到的提供商结果将在最终确定之前被丢弃。已启动的挂钩或 OAuth 刷新可能会完成,包括保留轮换凭证,但无法发布到过期的目录运行。

API-面向密钥和完全身份验证的目录回调保留其现有的源优先级。插件必须将凭证字节及其身份验证模式保持在同一选择中。目录失效和恢复保留模型库存合约;它们不会更改消息执行配置文件轮换或会话引脚。

检查目标解析

  • Check 目标可以来自身份验证配置文件、环境凭证或 models.json(结果 source:profile、env、models.json)。
  • 如果提供者具有凭证,但 OpenClaw 无法解析可对其进行测试的候选模型,则 models status --probe 会报告 status: no_model 和 reasonCode: no_model。

外部 CLI 凭据发现

  • 仅当提供程序、运行时或身份验证配置文件位于当前操作的范围内,或者该外部源的存储本地配置文件已存在时,才会发现受支持的外部 CLI 凭据。
  • Auth 存储调用者选择显式外部 CLI 发现模式:none 仅用于 persisted/plugin 身份验证,existing 用于刷新已存储的外部 CLI 配置文件,或 scoped 用于具体provider/profile 套装。
  • 读取-only/status路径通过allowKeychainPrompt: false;它们仅使用文件支持的外部 CLI 凭证,不会读取或重复使用 macOS 钥匙串结果。
  • /models 重复使用其目录中已准备好的外部登录证据,因此这些提供者无需再次登录 OpenClaw 即可保持可见。打开默认菜单不重复外部CLI发现;显式身份验证顺序和路由兼容性仍然适用。

Codex 拥有其本机登录。普通状态和模型读取不会将其凭据导入到 OpenClaw 配置文件中。要保留配置的 CLI- 支持的 openai:default 配置文件,请使用 openclaw models auth login --provider openai --method device-code 显式导入当前 Codex 登录名。当在 auth.profiles 中声明 OAuth 配置文件时,源是当前本机 Codex 主目录,并且不存在其他托管 OpenAI OAuth 配置文件,导入将保留配置文件 ID 及其现有模型和会话引脚。配置的模型和本机凭证文件保持不变。显式隔离的代理主目录继续通过其隔离的运行时使用导入的 OpenClaw 配置文件。

自 2026.9.5 起,本机 Codex 登录不再提供仅运行时的 openai:default 配置文件。如果该 OAuth 配置文件仍然已声明,但在代理的凭证存储中不存在,则 openclaw doctor --fix、Doctor lint 和网关启动会使用上面的导入命令发出警告。该警告不会复制凭据或阻止更新。缺少配置文件错误识别本地商店缺席,而不报告提供商 HTTP 401;该错误记录的是本地查找失败,而不是提供商拒绝。对于多个代理,请在登录命令中添加 --agent <id> 以选择受影响的代理。

新导入保留帐户范围的配置文件 ID。匹配的现有帐户和用户重复使用其存储的个人资料。从另一个家庭导入、缺少 account/user 身份或现有管理帐户未声明旧 PIN 码。在这些情况下,明确使用报告的导入配置文件。在持久性之前检测到的源更改和冲突的配置文件仅停止选定的导入。

OAuth SecretRef 策略保护

SecretRef 输入仅用于静态凭据。OAuth 凭据是在运行时可变的(刷新流程会持久化轮换后的令牌),因此由 SecretRef 支持的 OAuth 材料会将可变状态分散到不同的存储中。

  • 如果配置文件凭证是 type: "oauth",则该配置文件上的任何凭证材料字段都会拒绝 SecretRef 对象。
  • 如果 auth.profiles.<id>.mode 为 "oauth",则该 profile 的 SecretRef 支持的 keyRef/tokenRef 输入将被拒绝。
  • 违规是 startup/reload 秘密准备和配置文件解析路径中的硬故障(引发错误)。

向后兼容消息

当空的 SQLite 身份验证存储旁边有已停用的 auth-profiles.json 时,运行时会检查提供程序元数据,而不导入或解析其凭据。 AUTH_PROFILE_MIGRATION_REQUIRED 仅阻止那些提供商,包括其身份验证别名;不相关的提供商身份验证仍然可用。无法读取或无法识别的遗留数据保留所有者范围内的拒绝。已填充的 SQLite 存储保留其仅警告行为。记录的拒绝会一直保留,直到生命周期明确清除它们为止;更改或删除旧文件不会释放它们。 Doctor 列出了受影响的提供程序,openclaw doctor --fix 执行支持的验证导入和存档。

会话读取器保留其本地和共享身份验证存储所有者,并在返回凭据之前检查每个所有者当前的拒绝。共享提供者拒绝不会用环境或配置身份验证替换不相关的本地凭据,并且未解析的本地 SecretRefs 仍会阻止凭据访问。只有经过认可的凭证条目才能缩小遗留拒绝的范围;仅元数据对象和未知布局保留在所有者范围内。

凭证写入仅检查其目标数据库的所有者范围内的迁移准备情况。共享存储拒绝不会阻止刷新不相关的代理本地 OAuth 凭证;写入目标的拒绝仍然会阻止它。

会话迁移防护使用与模型发现相同的固定运行时配置和请求的模型的端点来解析依赖于端点的提供程序别名。准备好的会话视图保留了双方所有者的存储配置文件并验证其 SecretRefs;迁移元数据不会过滤这些配置文件。端点感知的请求防护决定准入。每个选定的凭证还通过合并和异步解析保留其物理源所有者。该所有者持有的拒绝继续隔离由另一个进程导入的匹配凭据,直到显式生命周期 clear/reload. 其他所有者的凭据保持独立。该来源仅是运行时的,并且永远不会存储在 SQLite 中。如果请求的提供程序需要一个端点来识别其凭证领域并且缺少该上下文,则任何待处理的迁移拒绝都会阻止它。显式配置的不相关端点仍然可用。

为了脚本兼容性,检查错误保持第一行不变:

Auth profile credentials are missing or expired.

人类可读的详细信息和稳定的原因代码会在后续行中以 ↳ Auth reason [code]: ... 的形式给出。

相关内容

本页有帮助吗?