从「一个模型」到「一堆提供方」
基础课里你完成了认证，第一次用 pi 跑通了会话。现在我们要往前走一步：理解 pi 背后的提供方生态。
pi 支持两类认证方式，对应两种接入模型的路子：
| 方式 | 走什么 | 适合谁 |
|---|---|---|
| 订阅（Subscription） | 通过 OAuth 登录 | 已有 ChatGPT / Claude / Copilot 等订阅的用户 |
| API Key | 环境变量或 auth.json | 按量付费、或想精确控制用量的用户 |
本节先讲订阅，下一节讲 API Key。记住一句话：模型是可换的，pi 是工具——你完全可以在不同项目、甚至同一会话里切换提供方。
md-tools 分发——把 Markdown 工具箱打包成 Pi Package 发出去。分发后，别人要装你的包，就得先能跑起来 pi。所以他们用**订阅还是 API Key**，直接决定了你要不要在你的包文档里写认证步骤：如果受众是订阅用户，告诉他们 /login 就行；如果是 API Key 用户，你得把环境变量写清楚。**这一节先搞懂提供方，后面才知道该给谁写什么文档。**订阅方式：用 /login 登录
在交互模式下，敲 /login，然后选择提供方即可。内置的订阅提供方包括：
- ChatGPT Plus/Pro（Codex）——需要 ChatGPT Plus 或 Pro 订阅，OpenAI 官方认可 Codex for OSS
- Claude Pro / Max——Anthropic 订阅认证，对 Pro/Max 账户生效
- GitHub Copilot——回车连 github.com，或输入你的 GitHub Enterprise Server 域名
- xAI（Grok / X 订阅）——跑
/login xai，选 "Use a subscription" - OpenRouter——通过 OpenRouter 的 PKCE 授权流程，铸造一把你自己的 API key
- Radius——一个动态 pi-messages 网关
登录后要登出，用 /logout 清掉凭据。
/login # 选择提供方
/login xai # 指定提供方登录
/logout # 清空凭据
这些登录令牌（OAuth tokens）存在 ~/.pi/agent/auth.json，过期会自动刷新。
订阅登录后会发生什么
登录完成后，两件事值得你心里有数：
- 令牌自动管理：OAuth 令牌过期后 pi 会静默刷新，你不用手动续期
- 特例是 OpenRouter：它不存会过期的令牌，而是铸造一把由你掌控的、不会自动过期的 API key，按你的 OpenRouter 余额计费
对生产环境来说，这意味着：订阅登录省心，但凭据生命周期不由你控制；API Key 更可控，但要在文档里写清楚。
几个提供方的实用细节
| 提供方 | 要记住的细节 |
|---|---|
| OpenAI Codex | 需 ChatGPT Plus 或 Pro 订阅 |
| Claude Pro/Max | 第三方工具的使用走额外额度，按 token 计费，不占 Claude 计划额度 |
| GitHub Copilot | 若提示 "model not supported"，去 VS Code 的 Copilot Chat → 模型选择器里 Enable |
| xAI | 通过 /login xai 选订阅，也仍可用 API key 方式 |
| OpenRouter | 远程/无头机器（如 SSH）上浏览器够不到本机回调，把重定向 URL 或授权码贴进登录提示即可 |
远程机器登录这个坑很真实——很多 CI 里的订阅登录就是卡在这一步。
落地练习：跑一次订阅登录流程
挑一个你手头有订阅的提供方，走一遍完整流程：
- 打开终端，进入一个空目录，运行
pi - 敲
/login，选一个你已订阅的提供方（如 Claude Pro、GitHub Copilot） - 按提示完成授权，回到会话后敲
/model，确认模型已经可选
怎么判断做对了？——
/model里能看到该提供方的模型，且能正常发起一次对话；~/.pi/agent/auth.json里出现对应的 OAuth 凭据。
卡住了怎么办？ 找不到提供方？先确认你的 pi 版本是最新的。登录后模型不可用？对照上面的「实用细节」表逐个排查，特别是 GitHub Copilot 需要在 VS Code 里 Enable 模型。
常见坑：把「订阅」和「API Key」当成一回事
新手最常见的误区，是以为订阅登录和 API Key 是同一个东西，随便配一个就行。
其实它们是两套并存的认证路径，而且很多提供方（如 xAI、OpenRouter）同时支持两种。区别在于：订阅走 OAuth 令牌、自动刷新、不计入你自己的 API 账单；API Key 走显式凭据、计费更透明、更适合脚本和 CI。
更隐蔽的坑是：你以为自己登录成功了，其实用的是环境变量里的老 Key。pi 解析凭据是有顺序的（CLI --api-key → auth.json → 环境变量），别被「看起来能跑」骗了。这一节先记住两种方式并存，下一节我们深挖解析顺序。
小结
- pi 支持订阅（OAuth）和 API Key 两类认证
- 订阅用
/login登录，令牌存 auth.json，过期自动刷新 - 订阅提供方：Codex、Claude Pro/Max、Copilot、xAI、OpenRouter、Radius
- 远程机器上 OpenRouter 登录要把回调 URL 贴进提示框
- 订阅与 API Key 并存，凭据解析有明确顺序
下一节，我们讲 API Key 与环境变量——这也是 md-tools 文档里最该写清楚的部分。