OpenAI OAuth 适配与故障恢复
本页描述本包对已锁定 Pi SDK 的认证适配,面向排障和维护者。登录、模型与服务提供方配置见配置指南。
适用范围
全局命令行工具通过 ModelRuntime.getAuth 适配器处理 OpenAI OAuth 刷新失败。SDK 1.1.0 继续负责登录、凭据存储、过期检查、加锁和持久化;本适配不增加后台续期定时器、另一套认证存储、自动登出、任务归档或业务仓库修改。
其它服务提供方、API 密钥以及非刷新类失败仍沿用 SDK 行为。启动时的模型目录刷新和 checkAuth 仍由 SDK 执行;此适配只作用于请求时的 getAuth,包括子会话使用的 ModelRegistry 访问入口。
工具与接口
ts
resolveOpenAIAuth<T>(resolve: () => Promise<T>, signal?: AbortSignal): Promise<T>resolve 使用相同模型和覆盖参数重新调用 SDK 原有的 getAuth。刷新前,SDK 在锁内读取最新凭据;成功轮换访问令牌和刷新令牌后,先持久化再释放锁。
行为约定
- SDK 会刷新所存剩余有效期不足五分钟的凭据;ChatGPT 保存的过期时间已经提前扣除了三分钟安全余量。
- SDK 的刷新请求有 15 秒期限。请求发出后,调用方取消不会丢弃 SDK 最终轮换得到的凭据。
- 只有
code=oauth且带有精确 OpenAI 刷新错误前缀的 SDK 错误进入此策略。SDK 会将底层原因追加到错误消息中。 - 当最底层传输错误码为
EAI_AGAIN、ENOTFOUND、ECONNREFUSED或UND_ERR_CONNECT_TIMEOUT时,最多尝试两次getAuth,间隔一秒。这些错误表示连接尚未建立。取消会停止等待并阻止下一次尝试;不拦截全局fetch。 - 其它失败不自动重试。特别是响应超时或连接重置,可能发生在服务端已成功轮换刷新令牌之后。
- HTTP 429 归为临时限流,但此处不重试,因为 SDK 异常没有保留
Retry-After。HTTP 5xx 也无法确定令牌是否已轮换;用户之后显式继续时再进入 SDK。 - 错误的
cause只包含{kind: "openai_oauth_refresh", reason, attempts, status?, oauthCode?, transportCode?},错误码受允许列表约束。不附加或记录服务提供方原始响应体、error_description、凭据、URL、请求头或原始异常。这里提供的是脱敏诊断,不是原始异常链。 - 命令行提示使用错误类别说明;精确 HTTP/传输错误码只保留在结构化诊断中。SDK 1.1.0 会通过英文错误文本和数字 HTTP 状态码决定是否重试整个助手回合,因此这些适配错误不能触发另一层重试。
ModelRegistry必须保留提示,不能解包原始原因而泄露服务提供方内容。
结果与错误处理
| 依据 | 原因码 | 处理方式 |
|---|---|---|
| HTTP 400/401/403,且带有已识别的授权、客户端或刷新令牌失效错误码 | authorization | 执行 /login openai |
| 保存的凭据缺少签发时的客户端 ID | credential_format | 执行 /login openai |
| 上述连接建立前的底层错误码 | connection | 延迟重试一次,之后提示检查网络/代理 |
| HTTP 429 | throttled | 稍后继续,不宣称登录已过期 |
| HTTP 5xx | remote | 稍后继续,不宣称登录已过期 |
| 响应超时、套接字或响应体中断 | uncertain | 不自动重放,也不判定登录状态 |
| 成功响应中的令牌数据或权限范围无效 | response | 排查客户端兼容性,不重放 |
| 其它或含义不明确的错误 | unknown | 不重放,不臆测凭据过期 |
| 调用方取消/无关的 SDK 错误 | 保持原状 | 保留取消状态或原始错误 |
已识别的授权错误码为 invalid_grant、invalid_client、unauthorized_client、refresh_token_expired、refresh_token_reused、refresh_token_invalidated。无法识别的 401/403 响应体不能证明重新登录就能解决问题。