10 认证与账号 API key / OAuth / IAM 三条路，以及它们共同的过期问题

先记住这一句

这一章短，但有一个容易被忽略的结构性后果：因为认证要动态解析，第 03 章那个循环必须持有一个 getApiKey 回调而不是一个字符串。一个看似琐碎的运维事实，反向约束了核心 API 的形状。

解析顺序：显式值永远赢

集合在 models.stream() 时经所属 provider 解析认证并合并进请求，而每次请求里显式传的值优先于一切——环境变量、存储的凭证、OAuth token 都在其后。ai/README.md:330

循环里的那个回调

const resolvedApiKey =
    (config.getApiKey ? await config.getApiKey(config.model.provider) : undefined) || config.apiKey;

如果认证在构造 Agent 时固定成一个字符串，一个跑 40 分钟的 run 会在 token 过期的那一刻整体失败——而且失败在最不该失败的地方（工具都跑完了，只差最后一次总结）。

可以不发请求就查解析结果

models.getAuth(provider) 返回 provider 级认证；传 model 则会带上该模型的静态 headers。ai/README.md:343

这个 API 的存在本身说明了一件事：当有三类凭证来源时，「现在到底用的哪个」是高频问题，值得一个专门的查询入口。

为什么支持订阅账号是个大决定

支持 Claude Pro / ChatGPT 这类订阅账号（而不只是 API key），意味着要实现 OAuth 流程、token 刷新、以及各家不同的账号态处理。这是 packages/ai 里 auth/oauth 单独成目录的原因。

收益是准入门槛：用户不需要先去开一个 API 账单账户。对一个想要广泛使用的开源 CLI，这可能是采用率上最重要的一个功能——但它的成本全部落在 pi-ai 这一层，且每家 provider 的实现都不一样。

「显式值永远赢」这条规则的价值

多来源凭证系统最容易出的问题是优先级不确定：环境变量和存储凭证同时存在时用哪个？pi 的答案是把优先级写成一条可背诵的规则，并且让最显式的那个赢。

这条规则让调试可行：怀疑认证有问题时，直接在调用里传一个 key，如果好了就说明是解析问题而不是凭证问题。

• token 刷新失败没有在循环层面的重试语义。getApiKey 抛错或返回过期 token，表现为一次普通的 provider 错误，走 第 03 章 §5 那条直接 return 的路径。
• 订阅账号的可用性受 provider 政策约束，且这类政策变化不体现在代码里。本章不评估任何 provider 的服务条款。
• 凭证存储在 ~/.pi/agent 下。第 15 章提到的容器化建议里有一条直接相关：不要把宿主的 ~/.pi/agent 挂进容器，否则等于把全部凭证交给容器里的代码。

• 凭证解析做成「每次调用一个回调」，不是「构造时一个字符串」。只要你支持任何有有效期的凭证，长任务就一定会撞上过期。 适用条件：OAuth / STS / 任何短期凭证。纯静态 API key 场景不需要，但加上也几乎无成本。
• 把凭证优先级写成一条能背下来的规则，并让最显式的赢。「显式参数 > 存储凭证 > 环境变量」比任何文档表格都好用。 适用条件：凭证有两个以上来源。
• 提供一个「不发请求就能查认证怎么解析的」入口。它把「凭证错了」和「解析错了」区分开——这是支持工单里最常见的二义性。 适用条件：同上。

给场景，判断 pi 会怎么做