身份验证凭据语义

这些语义可确保选择时与运行时的身份验证行为保持一致。以下功能共享这些语义：

• resolveAuthProfileOrder（配置文件排序）
• resolveApiKeyForProfile（运行时凭据解析）
• openclaw models status --probe
• openclaw doctor 身份验证检查（doctor-auth）

稳定的探测原因代码

探测结果包含一个 status 分类（ok、auth、rate_limit、billing、timeout、format、unknown、no_model）；如果探测从未执行模型调用，还会包含稳定的 reasonCode：

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

令牌凭据

令牌凭据（type: "token"）支持内联 token 和/或 tokenRef。

资格规则

1. 当 token 和 tokenRef 均不存在时，令牌配置文件不符合资格（missing_credential）。
2. expires 是可选的。提供时，它必须是一个有限的 Unix 纪元毫秒数，值大于 0，且不超过 JavaScript Date 时间戳的最大值（8640000000000000）。
3. 如果 expires 无效（类型错误、NaN、0、负数、非有限值或超过该最大值），配置文件将因 invalid_expires 而不符合资格。
4. 如果 expires 已过期，配置文件将因 expired 而不符合资格。
5. tokenRef 不会绕过 expires 验证。

解析规则

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

Agent 复制可移植性

Agent 身份验证继承采用透传读取方式。当某个 Agent 没有本地配置文件时，它会在运行时从默认/主 Agent 存储中解析配置文件，而不会将机密材料复制到自己的凭据存储（agents/<agentId>/agent/openclaw-agent.sqlite）中。

显式复制流程（例如 openclaw agents add）使用以下可移植性策略：

• 除非设置了 copyToAgents: false，否则 api_key 和 token 配置文件可移植。
• 默认情况下，oauth 配置文件不可移植，因为刷新令牌可能只能使用一次，或对轮换操作敏感。
• 仅当已知在 Agent 之间复制刷新材料是安全的情况下，提供商自有的 OAuth 流程才可通过 copyToAgents: true 选择启用；此选择启用仅在配置文件包含内联访问/刷新材料时适用。

不可移植的配置文件仍可通过透传读取继承使用，除非目标 Agent 单独登录并创建自己的本地配置文件。

仅配置的身份验证路由

具有 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，并从存储中移除该标记。

显式身份验证顺序过滤

• 当为某个提供商设置了 auth.order.<provider> 或身份验证存储顺序覆盖时，models status --probe 仅探测仍保留在该提供商最终身份验证顺序中的配置文件 ID。存储的覆盖优先于 auth.order 配置。
• 如果该提供商的某个已存储配置文件未包含在显式顺序中，系统不会在之后静默尝试它。探测输出会报告 reasonCode: excluded_by_auth_order，并附带详细信息 Excluded by auth.order for this provider.。

探测目标解析

• 探测目标可以来自身份验证配置文件、环境凭据或 models.json（结果的 source 为 profile、env 或 models.json）。
• 如果某个提供商拥有凭据，但 OpenClaw 无法为其解析出可供探测的候选模型，models status --probe 会报告 status: no_model 和 reasonCode: no_model。

外部 CLI 凭据发现

• 外部 CLI 自有的仅运行时凭据（claude-cli 的 Claude CLI、openai 的 Codex CLI、minimax-portal 的 MiniMax CLI）仅在提供商、运行时或身份验证配置文件处于当前操作范围内时发现，或者在已存在该外部来源的本地存储配置文件时发现。
• 身份验证存储调用方会选择显式的外部 CLI 发现模式：none 表示仅使用持久化/插件身份验证，existing 表示刷新已存储的外部 CLI 配置文件，scoped 表示使用具体的提供商/配置文件集合。
• 只读/状态路径会传入 allowKeychainPrompt: false；它们仅使用基于文件的外部 CLI 凭据，不会读取或复用 macOS Keychain 结果。

OAuth SecretRef 策略防护

SecretRef 输入仅用于静态凭据。OAuth 凭据可在运行时变更（刷新流程会持久化轮换后的令牌），因此由 SecretRef 支持的 OAuth 材料会将可变状态分散到多个存储中。

• 如果配置文件凭据为 type: "oauth"，则该配置文件的任何凭据材料字段都不接受 SecretRef 对象。
• 如果 auth.profiles.<id>.mode 为 "oauth"，则不接受该配置文件由 SecretRef 支持的 keyRef/tokenRef 输入。
• 在启动/重新加载机密准备和配置文件解析路径中，违规情况属于硬失败（抛出错误）。

兼容旧版的消息文本

为保持脚本兼容性，探测错误会原样保留以下首行：

Auth profile credentials are missing or expired.

便于理解的详细信息和稳定原因代码会显示在后续行中，格式为 ↳ Auth reason [code]: ...。

相关内容

• 机密管理
• 身份验证存储