OpenClaw 认证凭证语义指南

本文档定义了跨多个工具的标准凭证资格与解析语义，这些工具包括：

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

目标是确保选择阶段与运行时的行为保持一致。

稳定原因码

系统使用以下稳定的原因码来标识凭证状态：

• ok：凭证有效
• missing_credential：缺失凭证
• invalid_expires：过期时间无效
• expired：凭证已过期
• unresolved_ref：引用无法解析

令牌凭证

令牌凭证（类型："token"）支持内联令牌（token）和 / 或令牌引用（tokenRef）。

资格规则

当 token 和 tokenRef 均缺失时，令牌配置文件将不符合资格。 expires（过期时间）为可选字段。 如果存在 expires，则它必须是一个大于 0 的有限数值。 如果 expires 无效（NaN、0、负数、非有限值，或是错误类型），该配置文件将因 invalid_expires 而不符合资格。 如果 expires 已过期（时间在过去），该配置文件将因 expired 而不符合资格。 tokenRef 不会绕过 expires 的校验。

解析规则

解析器的语义与资格规则中的 expires 校验保持一致。 对于符合资格的配置文件，令牌内容可以从内联值或 tokenRef 中解析得到。 无法解析的引用会在 models status --probe 的输出中标记为 unresolved_ref。

向后兼容的消息

为了保证脚本兼容性，探测错误的首行保持不变：

Auth profile credentials are missing or expired.

人性化的详细信息与稳定原因码可以添加在后续的行中。