Skip to content

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
保存的凭据缺少签发时的客户端 IDcredential_format执行 /login openai
上述连接建立前的底层错误码connection延迟重试一次,之后提示检查网络/代理
HTTP 429throttled稍后继续,不宣称登录已过期
HTTP 5xxremote稍后继续,不宣称登录已过期
响应超时、套接字或响应体中断uncertain不自动重放,也不判定登录状态
成功响应中的令牌数据或权限范围无效response排查客户端兼容性,不重放
其它或含义不明确的错误unknown不重放,不臆测凭据过期
调用方取消/无关的 SDK 错误保持原状保留取消状态或原始错误

已识别的授权错误码为 invalid_grant、invalid_client、unauthorized_client、refresh_token_expired、refresh_token_reused、refresh_token_invalidated。无法识别的 401/403 响应体不能证明重新登录就能解决问题。