认证凭证语义

本文档定义了以下各处使用的规范凭证资格与解析语义：

• resolveAuthProfileOrder
• resolveApiKeyForProfile
• models status --probe
• doctor-auth

目标是保持选择时行为与运行时行为一致。

# 稳定探测原因代码

• ok
• excluded_by_auth_order
• missing_credential
• invalid_expires
• expired
• unresolved_ref
• no_model

# 令牌凭证

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

# 资格规则

1. 当 token 和 tokenRef 都不存在时，令牌配置档案不符合条件。
2. expires 是可选的。
3. 如果存在 expires，它必须是大于 0 的有限数字。
4. 如果 expires 无效（NaN、0、负数、非有限值或类型错误），该配置档案不符合条件，并带有 invalid_expires。
5. 如果 expires 已过去，该配置档案不符合条件，并带有 expired。
6. tokenRef 不会绕过 expires 验证。

# 解析规则

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

# Agent 副本可移植性

智能体认证继承是读取穿透式的。当智能体没有本地配置档案时，它可以在运行时从默认/主智能体存储解析配置档案，而无需将密钥材料复制到自己的 auth-profiles.json 中。

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

• api_key 配置档案默认可移植，除非设置了 copyToAgents: false。
• token 配置档案默认可移植，除非设置了 copyToAgents: false。
• oauth 配置档案默认不可移植，因为刷新令牌可能是一次性的，或对轮换敏感。
• 提供商拥有的 OAuth 流程只有在已知跨智能体复制刷新材料是安全的情况下，才可以通过 copyToAgents: true 选择加入。

不可移植的配置档案仍可通过读取穿透式继承使用，除非目标智能体单独登录并创建自己的本地配置档案。

# 仅配置认证路由

带有 mode: "aws-sdk" 的 auth.profiles 条目是路由元数据，而不是存储的凭证。当目标提供商使用 models.providers.<id>.auth: "aws-sdk" 或内置 Amazon Bedrock 默认 AWS SDK 路由时，这些条目有效。即使 auth-profiles.json 中不存在匹配条目，这些配置档案 ID 也可以出现在 auth.order 和会话覆盖中。

不要将 type: "aws-sdk" 写入 auth-profiles.json。如果旧版安装中有此类标记，openclaw doctor --fix 会将其移动到 auth.profiles，并从凭证存储中移除该标记。

# 显式认证顺序过滤

• 当为某个提供商设置了 auth.order.<provider> 或认证存储顺序覆盖时，models status --probe 只探测仍保留在该提供商已解析认证顺序中的配置档案 ID。
• 对于该提供商存储的配置档案，如果被显式顺序省略，之后不会被静默尝试。探测输出会用 reasonCode: excluded_by_auth_order 报告它，并附带详情 Excluded by auth.order for this provider.

# 探测目标解析

• 探测目标可以来自认证配置档案、环境凭证或 models.json。
• 如果某个提供商有凭证，但 OpenClaw 无法为其解析出可探测的模型候选项，models status --probe 会报告 status: no_model，并带有 reasonCode: no_model。

# 外部 CLI 凭证发现

• 外部 CLI 拥有的仅运行时凭证，只有在该提供商、运行时或认证配置档案处于当前操作范围内，或该外部来源已有存储的本地配置档案时，才会被发现。
• 认证存储调用方应选择显式外部 CLI 发现模式：none 用于仅持久化/插件认证，existing 用于刷新已存储的外部 CLI 配置档案，或 scoped 用于具体的提供商/配置档案集合。
• 只读/Status 路径会传递 allowKeychainPrompt: false；它们只使用文件支持的外部 CLI 凭证，不会读取或复用 macOS Keychain 结果。

# OAuth SecretRef 策略防护

• SecretRef 输入仅用于静态凭证。
• 如果配置档案凭证为 type: "oauth"，则该配置档案凭证材料不支持 SecretRef 对象。
• 如果 auth.profiles.<id>.mode 是 "oauth"，则会拒绝该配置档案使用 SecretRef 支持的 keyRef/tokenRef 输入。
• 违规会在启动/重载认证解析路径中导致硬失败。

# 兼容旧版的消息

为保持脚本兼容性，探测错误会保持以下第一行不变：

Auth profile credentials are missing or expired.

可在后续行中添加面向用户的详情和稳定原因代码。

# 相关

• 密钥管理
• 认证存储