身份验证凭据语义
这些语义使选择时和运行时的认证行为保持一致。它们由以下部分共享:
resolveAuthProfileOrder(配置文件排序)resolveApiKeyForProfile(运行时凭据解析)openclaw models status --probeopenclaw doctor认证检查(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 凭据¶
Token 凭据(type: "token")支持内联 token 和/或 tokenRef。
资格规则¶
- 当
token和tokenRef均缺失时,Token 配置文件不符合资格(missing_credential)。 expires是可选的。如果存在,它必须是有限的 Unix 纪元毫秒数,大于0且不超过 JavaScriptDate的最大时间戳(8640000000000000)。- 如果
expires无效(类型错误、NaN、0、负数、非有限值或超过该最大值),则配置文件不符合资格,原因为invalid_expires。 - 如果
expires在过去,则配置文件不符合资格,原因为expired。 tokenRef不会绕过expires验证。
解析规则¶
- 解析器语义与
expires的资格语义一致。 - 对于符合资格的配置文件,Token 材料可以从内联值或
tokenRef解析。 - 无法解析的引用会在
models status --probe输出中产生unresolved_ref。
手动 API 密钥¶
在 Models 中保存手动 API 密钥时,会等待 Gateway 应用任何已更改的提供方绑定,然后再刷新模型认证。替换绑定未更改的密钥时,只需要刷新认证。如果 Gateway 无法确认已应用,密钥仍会保存,并且响应中包含重启警告。这会保留已配置的重新加载策略,包括禁用的重新加载。删除密钥时,仍会拒绝并发更改的绑定或凭据。
设置替换¶
设置替换凭据以独立的配置文件 ID 保存,并在现有凭据负载中包含内部 setup 描述符。它们不能进入正常轮换,不能通过显式配置文件固定解析,也不能复制到另一个 agent。只有拥有该设置的操作可以测试所选凭据。在一次成功的无工具轮次后,设置会询问是否激活它。拒绝或测试失败会使已保存的凭据保持非活动状态,并保留当前连接。Model Setup 会为新的测试提供相同的已保存登录,而无需再次登录。如果应用替换失败,恢复会在重建先前连接之前恢复其非活动状态。Gateway 激活会等待配置应用;如果需要重启,则替换保持非活动状态,直到设置重试。普通登录仍然立即进行。描述符会保留所选模型和连接设置,以便在重启后重试,而不会缓存验证结果。这不会添加数据库架构或迁移;旧运行时不会强制实施非活动状态。在降级之前,请删除已保存的非活动替换,或恢复设置之前的状态。
非交互式设置会保存替换凭据,并打印 openclaw models auth activate <profileId> --agent <id> 命令,以测试并激活已保存的登录。Model Setup 提供相同操作。交互式设置默认在测试成功后激活。重用现有凭据和首次运行的非交互式设置保留其现有行为。
Agent 副本可移植性¶
Agent 认证继承是读穿的。当 agent 没有本地配置文件时,它会在运行时从共享认证存储中解析配置文件,而不会将秘密材料复制到其自身的凭据存储(agents/<agentId>/agent/openclaw-agent.sqlite)。在 openclaw doctor --fix 执行一次性迁移后,共享存储位于 state/openclaw.sqlite。在此之前,doctor 会报告旧版 agents/main/agent/openclaw-agent.sqlite 的所有者,并使该 agent 无法删除。
OAuth 同级同步首先写入所选的主配置文件,然后在写入其他同级之前写入已发现的共享所有者。无论文件系统目录顺序如何,这都保留了读穿继承。位于所选 agents 树之外的共享所有者不会被添加到同步目标中。
认证使用情况和冷却时间更新会等待其实际 agent 数据库所有者的写入许可,包括旧版共享存储。迁移后的共享状态认证使用自己的协调器。排队的更新保留其选定的状态根和共享所有者,然后在许可后读取当前配置文件。运行时快照在持久提交之后、下一个获许可的写入者之前发布;在其健康更新等待期间删除配置文件不会重新创建其健康状态。冷 agent 打开会异步验证完整性,并在写入前重新检查所有权。OAuth upsert 在许可后、应用现有代际替换规则之前,会重新检查当前本地或继承的凭据。
运行时 auth-store 更新将读取、合并、编码和提交保留在现有 SQLite 工作线程中。更新回调针对事务的当前行最多执行一次;提交前会再次检查实时所有者准入。本地更新在准备期间观察到 shared-store 变更时会拒绝,且不会重放回调。大型单元格以有界字段形式跨越工作线程边界。共享凭据发布复用已提交的共享存储,并保持未受影响的本地快照及其修订版本不变。已解析的机密保留在其现有运行时所有者处。
Doctor 认证修复保留由其架构维护租约拥有的原生事务;它们不会借用普通工作线程权限。
模型目录工作线程使用其请求的原生认证写入作用域,并固定到捕获的状态根。请求在关闭该作用域前等待已声明的 OAuth 刷新完成;保留的回调在其关闭后不能写入。每个目录请求携带 Gateway 已提交的 shared-store 所有权。复用的工作线程在读取凭据前设置该事实,因此首次登录的空存储重定位不会使发现仍附着在旧位置。临时探测存储等待其数据库工作和 shared-registry 移除后再删除凭据文件。如果处置失败,清理会保留目录并报告其位置。
存储格式、架构版本以及更新或回滚行为保持不变。
内联 API 密钥失败记账通过其现有 SQLite 工作线程读取并更新所选代理的认证状态。它保留凭据字节以及其他配置的健康状态。运行时快照发布在独立线程中读取规范的本地和共享行,然后保留当前主机已解析的机密和外部配置覆盖层。发布失败不会重放已提交的健康更新。同步 SDK 存储 API 保留其现有契约。
当凭据、配置顺序或所有权,或模型可用性发生变化时,Gateway 模型元数据会刷新,包括冷却和阻塞状态转换。使用时间戳、成功历史和失败计数器仍会被记录,而不会使聊天元数据失效或向已连接客户端广播变更。
Gateway 模型认证状态读取针对同一代理和已发布的配置/认证代次,在客户端之间共享提供方准备。凭据警告和过期边界也会使准备失效;显式刷新会绕过它。每个响应仍会计算当前过期时长,从其现有缓存读取辅助使用情况,并应用请求客户端的配置身份可见性。基于文件的外部 CLI 引导健康状态保留在其读取器的新鲜度生命周期中,因为外部登录可能在无 Gateway 发布的情况下发生变化。
重复的模型解析在拥有数据库的写入代次和文件身份保持不变时,复用已持久化的认证行。已提交的认证写入和运行时快照重载会立即使这些行失效。在热缓存命中时,数据库、WAL 和日志身份最多每 100 ms 检查一次;在该间隔或之后的首次读取会检测来自其他进程的变更。命中不会延长此新鲜度窗口。缓存未命中仍会在读取行之前和之后检查身份。作用域覆盖层、迁移拒绝和个人账户选择仍会在每个请求中运行。隔离的代理作用域和私有数据库快照不共享此缓存。Gateway 缓存未命中会复用一个只读子进程,其生命周期在关闭时结束;每次读取都会重新获取其源准入,并在返回前关闭其 SQLite 句柄。读取器启动会规范化有效状态目录,因此隐式默认目录和相同显式固定目录会复用该子进程。不同的状态目录、环境或源仍会替换它。分离的连接、cron、心跳和钩子回调保留该 Gateway 的只读工作线程作用域,而不继承启动或请求权限。关闭会在迟到的回调能够创建另一个读取器之前拒绝它们。使用记账会使后续缓存复用失效,同时已准入的读取可以完成其快照。凭据、选择、所有权和生命周期变更仍会使进行中的准备失效。
模型选择在其读取器完成清理后,会重试该过期读取一次,保留所选代理和任何显式配置固定。如果进程内 OAuth 刷新使读取失效,选择会先观察该所有者的持久化结算,包括继承的凭据和被隔离的对等节点。此等待使用现有刷新超时,既不读取凭据,也不启动另一个刷新。重连会释放对被替换声明的等待;仍被隔离的对等节点的读取器继续等待所有者的清理。待刷新的配置仍是模型 id/模式选择的候选项;OAuth 所有者仍会在凭据可用前完成刷新结算。调用方超时不会使其持久化结算从观察中退出,等待中的模型读取也不能取消它。取消模型请求仅结束其结算等待;刷新所有者和其他等待请求独立继续。持续变更、准入拒绝和清理失败仍为错误。
通过 resolveApiKeyForProvider 和 resolveApiKeyForProfile 进行的凭据查找也接受可选的取消信号。取消会结束调用方对排队准入、配置锁或刷新的等待。排队任务在声明凭据前会重新检查取消。已开始的锁获取保留其清理所有者,已声明的刷新保持其独立的持久化结算。已取消的调用方不能启动稍后排队的刷新,也不能返回其凭据。省略该信号的调用方保留现有等待行为。
工作线程在行进入缓存前确认已提交的 SQLite 可见性。带有未发布或尾部 WAL 帧的读取正常返回且不被保留。
显式复制流程,例如 openclaw agents add,使用此可移植性策略:
api_key和token配置文件是可移植的,除非copyToAgents: false。oauth配置文件默认不可移植,因为刷新令牌可能是一次性的或对轮换敏感。- 提供商拥有的 OAuth 流程仅在选择跨代理复制刷新材料已知安全时,才可通过
copyToAgents: true选择加入;该选择加入仅在配置文件携带内联访问/刷新材料时适用。
不可移植配置文件仍可通过共享读透基座使用,除非目标代理单独登录并创建自己的本地配置文件。
在 OAuth 刷新期间,当前凭据代际会被替换为一个惰性持久标记。待处理标记默认保持不可用,并且仅由立即将其传递给结算感知解析器的运行时路径进行排序。失败的标记为终态,并要求操作员重新认证。
代理本地对等体绝不会收到复制的已轮换刷新材料。对等体仅在验证共享凭据属于同一账户后,才会移除其标记并继承共享凭据。如果无法验证该身份,对等体将保持终态隔离,而不是继承另一个账户。
插件 SDK OAuth 验证¶
resolveApiKeyForProfile 从 openclaw/plugin-sdk/agent-runtime 导出,接受一个可选的 validateOAuthCredential 回调。解析器在返回 OAuth 凭据之前,以及在持久化或采用刷新后的凭据之前调用它。当旧版 provider:default 配置文件回退到替代 OAuth 配置文件时,该回调也适用。
从回调抛出异常会拒绝该凭据。被拒绝的回退不会被返回或刷新,原始所选配置文件刷新失败仍是面向操作员的错误。拒绝活动刷新或结算代际会失败关闭,并可能使该代际及其对等体处于终态隔离,因此操作员必须重新认证。省略回调的调用方保留现有解析和回退行为。
openclaw agent exec 在切换到临时运行状态时保留原始共享存储根。其有界凭据范围从该共享存储读取可移植 api_key 和 token 配置文件,而不持久化副本;已配置代理的本地配置文件仍然优先。共享 OAuth 配置文件被排除在此临时范围之外,即使 copyToAgents: true,因此运行不会获得另一个刷新所有者。--auth-env-only 完全禁用存储凭据访问。
显式选择状态目录的认证写入,包括隔离的 QA 暂存,使用该目录的共享存储进行所有权和 OAuth 去重。其运行时发布和回滚保留同一所有者;另一个进程本地状态根不是继承基座。无关的外部数据库可能更旧、更新或不可读,而不会阻塞隔离写入,但所选目标中不可读或更新的数据库仍会失败关闭。未显式指定状态目录的写入保留正常的环境状态和代理目录配置。
个人模型账户¶
从 设置 → 个人资料 → 已连接账户 连接的账户在共享状态数据库中具有身份范围的所有者。其凭据和使用状态绝不会进入共享或代理本地认证存储、外部 CLI 镜像或全局运行时快照。运行时最多加载其会话所选的一个个人凭据。未关联的个人账户仍可由现有会话固定使用,但不会为新会话自动选择。
个人固定保留现有同提供商故障转移策略:固定账户失败后,可以尝试有序共享账户。它们不会将他人的个人账户作为回退。重新连接只能替换连接者本人的凭据;管理员创建的链接所引用的共享凭据不是个人财产。参见每人模型账户。
仅配置认证路由¶
具有 mode: "aws-sdk" 的 auth.profiles 条目是路由元数据,不是存储凭据。当目标提供商使用 models.providers.<id>.auth: "aws-sdk" 时有效,这是插件拥有的 Amazon Bedrock 设置写入的路由。即使凭据存储中不存在匹配条目,这些配置文件 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,因此显式会话固定不会跨越账户边界。不可用的固定保持严格,并发出会话范围警告。对于重新登录前已移除的凭据,请使用 model@profile 有意选择已配置账户,或使用 openclaw models auth login --provider <provider> --profile-id <selected-profile-id> 重新连接目标账户。升级期间不会重写任何会话行或存储凭据。
显式认证顺序过滤¶
- 当为提供商设置了
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。引用名称永远不会作为凭据发送,也不会被替换为其他配置的凭据。在 Gateway 上,重试发现之前请恢复密钥并运行 openclaw secrets reload。
当所有符合条件的 OAuth 候选项准备失败时,发现会报告 unavailable 并附带尝试过的配置身份,而不是将提供程序视为未配置。兼容的先前清单仍保持可用。可用的回退凭据仍会提供其自身的目录结果。
当目录截止时间到期时,迟到的提供程序结果会在最终确定之前被丢弃。已启动的钩子或 OAuth 刷新可以完成,包括持久化轮换后的凭据,但不能发布到已过期的目录运行。
面向 API 密钥和完整认证的目录回调保留其现有源优先级。插件必须保持凭据字节及其认证模式来自同一选择。目录失败和恢复保留模型清单契约;它们不会更改消息执行配置轮换或会话固定。
检查目标解析¶
- 检查目标可以来自认证配置、环境凭据或
models.json(结果source:profile、env、models.json)。 - 如果提供程序具有凭据,但 OpenClaw 无法解析一个可对其进行测试的模型候选项,
models status --probe会报告status: no_model并带有reasonCode: no_model。
外部 CLI 凭据发现¶
- 仅当提供程序、运行时或认证配置在当前操作范围内,或者该外部源已存在存储的本地配置时,才会发现受支持的外部 CLI 凭据。
- 认证存储调用方选择显式的外部 CLI 发现模式:
none仅用于持久化/插件认证,existing用于刷新已存储的外部 CLI 配置,或scoped用于具体的提供程序/配置集合。 - 只读/状态路径传递
allowKeychainPrompt: false;它们仅使用基于文件的外部 CLI 凭据,并且不读取或重用 macOS Keychain 结果。 /models会重用已与其目录一起准备的外部登录证据,因此这些提供程序无需第二次 OpenClaw 登录即可保持可见。打开默认菜单不会重复外部 CLI 发现;显式认证顺序和路由兼容性仍然适用。
Codex 拥有其原生登录。常规状态和模型读取不会将其凭据导入 OpenClaw 配置。若要保留已配置的基于 CLI 的 openai:default 配置,请使用 openclaw models auth login --provider openai --method device-code 显式导入当前 Codex 登录。当该 OAuth 配置已在 auth.profiles 中声明,源是当前原生 Codex 主目录,并且不存在其他受管理的 OpenAI OAuth 配置时,导入会保留配置 ID 及其现有模型和会话固定。已配置的模型和原生凭据文件保持不变。显式隔离的代理主目录会继续通过其隔离运行时使用导入的 OpenClaw 配置。
自 2026.9.5 起,原生 Codex 登录不再提供仅运行时的 openai:default 配置。如果该 OAuth 配置仍被声明,但缺失于某个代理的规范凭据存储中,openclaw doctor --fix、Doctor lint 和 Gateway 启动会使用上述导入命令发出警告。该警告不会复制凭据或阻止更新。缺失配置错误会标识本地存储缺失,而不报告提供程序 HTTP 401;错误记录的是本地查找失败,而不是提供程序拒绝。
对于多个代理,请在登录命令中添加 --agent <id> 以选择受影响的代理。
新导入会保留账户范围的配置 ID。匹配的现有账户和用户会重用其存储的配置。从另一个主目录导入、缺失账户/用户身份,或已存在受管理账户,不会占用旧版固定。在这些情况下,请显式使用报告的已导入配置。在持久化之前检测到的源更改和冲突配置只会停止所选导入。
OAuth SecretRef 策略保护¶
SecretRef 输入仅用于静态凭据。OAuth 凭据在运行时可变(刷新流程会持久化轮换后的令牌),因此基于 SecretRef 的 OAuth 材料会将可变状态拆分到不同存储中。
- 如果配置凭据为
type: "oauth",则该配置的任何凭据材料字段都会拒绝 SecretRef 对象。 - 如果
auth.profiles.<id>.mode为"oauth",则该配置的基于 SecretRef 的keyRef/tokenRef输入会被拒绝。 - 违规在启动/重新加载密钥准备和配置解析路径中是硬性失败(抛出错误)。
遗留兼容消息传递¶
当空的 SQLite 身份验证存储旁边存在已弃用的 auth-profiles.json 时,运行时仅检查提供商元数据,而不会导入或解析其凭据。AUTH_PROFILE_MIGRATION_REQUIRED 仅阻止这些提供商,包括其身份验证别名;无关提供商的身份验证仍可用。无法读取或无法识别的遗留数据保留所有者范围的拒绝。已填充的 SQLite 存储保留其仅警告的行为。已记录的拒绝在生命周期明确清除之前保持有效;更改或删除遗留文件不会解除它们。Doctor 列出受影响的提供商,并且 openclaw doctor --fix 执行受支持的已验证导入和归档。
会话读取器保留其本地和共享身份验证存储的所有者,并在返回凭据之前检查每个所有者当前的拒绝。共享提供商的拒绝不会用环境变量或配置身份验证替换无关的本地凭据,未解析的本地 SecretRef 仍然失败关闭。只有已识别的凭据条目才能缩小遗留拒绝的范围;仅元数据对象和未知布局仍保持所有者范围。
凭据写入仅针对其目标数据库检查所有者范围的迁移就绪状态。共享存储的拒绝不会阻止刷新无关的代理本地 OAuth 凭据;写入目标上的拒绝仍会阻止它。
会话迁移守卫使用与模型发现相同的固定运行时配置以及所请求模型的端点,以解析依赖端点的提供商别名。已准备的会话视图保留来自两个所有者的规范配置文件,并验证它们的 SecretRef;迁移元数据不会过滤这些配置文件。感知端点的请求守卫决定准入。每个选定的凭据还会在合并和异步解析过程中保留其物理源所有者。由该所有者持有的拒绝会继续隔离由另一个进程导入的匹配凭据,直到明确的生命周期清除/重新加载。另一个所有者的凭据保持独立。此来源信息仅存在于运行时,并且从不存储在 SQLite 中。如果所请求的提供商需要端点来识别其凭据域,并且该上下文缺失,则任何待处理的迁移拒绝都会阻止它。明确配置的无关端点仍可使用。
为了脚本兼容性,检查错误保持此第一行不变:
Auth profile credentials are missing or expired.
人类可读的详细信息和稳定的原因代码随后出现在后续行中,形式为 ↳ Auth reason [code]: ...。
相关¶
- 密钥管理
- 身份验证存储
- SecretRef 凭据表面 - 哪些凭据字段接受 SecretRef 而不是原始秘密值
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw