Pi coding agent 的模型配置分为三层：内置 provider 使用 /login 登录（订阅或 API 密钥）或设置环境变量；Pi 没有内置、但兼容 OpenAI／Anthropic／Google API 的端点，写入 ~/.pi/agent/models.json；只有需要特殊身份验证或协议的服务才需要编写扩展。选好后使用 /model 切换。本文依据 Pi 在 2026 年 9 月 22 日改版后的文档，以及 2026 年 9 月 30 日发布的 v0.99.2 源代码，说明每一层的设置方式、密钥读取顺序（改版后已变化）、自定义模型的三个隐式错误默认值，以及连接 OpenAI 兼容端点的完整示例。
先确认你使用的是哪一个 Pi。本页讲的是 Earendil 公司在 pi.dev 发布的终端代码代理，代码库为 earendil-works/pi（原 badlogic/pi-mono），采用 MIT 许可证。它不是 Inflection 的聊天机器人 Pi（pi.ai）、不是 Pi Network 币、不是 Raspberry Pi，也不是另一位作者的 Oh My Pi。
先选择连接方式
Pi 的模型文档开头就是这张对照表：
| 你拥有的内容 | 建议做法 |
|---|---|
| 支持的订阅方案 | 使用 /login 登录 |
| 某个 provider 的 API 密钥 | 使用 /login 保存，或设置该 provider 的环境变量 |
| 本地 GGUF 模型 | 连接 llama.cpp router（使用 /llama 管理） |
| OpenAI、Anthropic 或 Google 兼容端点 | 写入 models.json |
| 自定义协议或身份验证流程的 provider | 编写或安装 provider extension |
Pi 内置一份模型目录，也可以从 pi.dev 叠加较新的目录数据；离线时沿用缓存；如需强制更新，可以运行 pi update --models。只有当 Pi 没有你需要的 provider 或端点时，才需要自定义模型配置。
在 Pi 中选择模型
/model：搜索并选择模型。只会列出 provider 已经拥有可用凭证的模型。- 在模型上按 Ctrl+S：将其保存为新工作会话的默认模型。
/thinking：选择当前模型的思考等级；Pi 只会列出该模型支持的等级；同样按 Ctrl+S 保存为启动默认值。- Ctrl+P：在可用模型之间轮换；
/scoped-models控制轮换列表并保存。
工作会话会记录模型和思考等级的变化，恢复会话时会照此还原，但不会修改新工作会话的默认设置。
密钥读取顺序（改版后已变化）
同时设置多个密钥来源时，Pi 文档写出的顺序是：运行时的 --api-key → auth.json 中保存的凭证 → models.json 的 apiKey → provider 的环境变量（或云平台的环境凭证）。因此，通过 /login 保存过的旧密钥会覆盖你刚写入文件的密钥，这是“修改了设置却仍在使用旧账户”最常见的原因；/logout 可以移除已保存的凭证。注意，在 9 月 22 日改版前，文档写的是环境变量排在 models.json 前面，网络上的旧教程可能仍然使用旧顺序。
另一个常见误解是：模型没有出现在 /model 中，多半是身份验证问题，而不是 JSON 写错。文档说明自定义模型可以从 models.json 加载，但在 Pi 解析出凭证之前，它会一直处于“不可用”状态。
models.json：连接 OpenAI 兼容端点的完整示例
Pi 自己的示例是本地 Ollama——dummy 密钥只是让模型变为可用，Ollama 本身不会检查它：
{
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434/v1",
"api": "openai-completions",
"apiKey": "ollama",
"models": [{ "id": "qwen2.5-coder:7b" }]
}
}
}连接需要身份验证的端点（例如 Kunavo）时，可以这样写：
{
"providers": {
"kunavo": {
"baseUrl": "https://api.kunavo.com/v1",
"api": "openai-completions",
"apiKey": "$KUNAVO_API_KEY",
"models": [
{
"id": "claude-sonnet-5",
"name": "Claude Sonnet 5",
"reasoning": true,
"input": ["text", "image"],
"contextWindow": 1000000,
"maxTokens": 128000
},
{
"id": "claude-haiku-4-5",
"name": "Claude Haiku 4.5",
"input": ["text", "image"],
"contextWindow": 200000,
"maxTokens": 64000
}
]
}
}
}baseUrl和api是必填项。可以写在 provider 层或模型层；根据 v0.99.2 源代码，缺少其中任意一个，Pi 就不会加载该模型。api不是四选一。在 9 月 22 日改版前，Pi 的文档为自定义 provider 列出四个值：openai-completions、openai-responses、anthropic-messages、google-generative-ai。改版后的文档不再列出清单，只在上面的对照表中写“OpenAI、Anthropic 或 Google 兼容的端点”，示例也只使用了openai-completions。v0.99.2 源代码将api定义为任意字符串，并交给十种内置实现中对应的一种处理——上述四种，加上openai-codex-responses、azure-openai-responses、google-vertex、mistral-conversations、bedrock-converse-stream、pi-messages。只有前四种曾在文档中写成自定义 provider 的用法；另外六种这里没有测试，本页也不主张它们可以连接第三方端点。openai-completions的baseUrl必须带有/v1。文档没有用一句话明确规定，但兼容端点示例全部带有版本路径。缺少/v1会得到 404，而不是身份验证错误。- 不要将密钥硬编码。
apiKey和标头值可以写$NAME或${NAME}来引用环境变量、直接写值，或使用!指令获取；文档说明models.json中的命令会在每次请求时执行，不会缓存。请对auth.json和任何获取密钥的命令保密。 - 修改后无需重启。打开
/model时会重新读取文件。models中具有相同 ID 的项目会新增或替换该 provider 的模型；如果想修改内置模型的元数据而不替换整个列表，请使用modelOverrides。
三个会悄悄出错的默认值
9 月 22 日的文档改版移除了字段表，但默认值仍在源代码中（v0.99.2 的 provider-composer.ts）。自定义模型只要未填写，就会应用以下默认值：
| 字段 | 未填写时的默认值 | 会导致的结果 |
|---|---|---|
cost | input、output、cacheRead、cacheWrite 全部为 0 | 底部和 /session 的花费一直显示 $0，不代表免费，只是没有价格来源 |
contextWindow | 128000 | 上下文更大的模型会过早被压缩 |
maxTokens | 16384 | 长回复被截短 |
另外 reasoning 默认 false、input 默认只有文本。上面的 Kunavo 示例已根据价目表填好上下文和输出上限，没有放 cost，因为把价格写死在文件里很快就会过期 —— 想让底部显示花费，就自己按照 价目表填入每百万 token 的价格。Pi 还支持 promptCache（以秒为单位声明供应商缓存的存活时间，用于缓存预热），文档建议取公开范围中较保守的一端。
anthropic-messages：可以接入，但 baseUrl 尚无定论
anthropic-messages 是改版前文档为自定义 provider 列出的四个值之一，Kunavo 也提供 Anthropic Messages 接口，所以 api: "anthropic-messages" 这条路是存在的。但 Pi 的文档从未说清楚这种类型的 baseUrl 是否应该带 /v1：改版前一个示例写 https://proxy.example.com/v1，另一个写不带路径的 https://proxy.example.com，改版后两个示例都删掉了，仍然没有定论。走这条路的话先试一种，第一次请求返回 404（而不是 401）就改这一行。compat 里也有几个专为非原厂端点设计的开关（例如 supportsEagerToolInputStreaming、supportsStrictTools），但文档提醒：兼容设置应该描述“已验证的行为差异”，不要只因为端点声称兼容 OpenAI 或 Anthropic 就打开。上面的 openai-completions 示例避开了这些问题，这才是建议从它开始的真正原因，不是因为它更快。
坦诚说明与付款
以上是根据 Pi 的文档和源代码整理出的设置参考，Kunavo 没有实际用 Pi 运行过自家端点 —— 没有运行过工作阶段、流式传输、工具往返，也没有确认请求最终落在哪个模型。请保留你当前能用的路线，给 Pi 一个会读写真实文件的任务试试；Pi 几乎每一步都依靠工具调用，这样的首次执行最能暴露流式或工具格式不兼容的问题。英文完整设置页见 Pi integration guide，各种付费路线（包括 Earendil 自己的 Radius 网关）比较见 Pi coding agent pricing。
Kunavo 采用预付充值、按 token 扣款的方式，没有月费。最低充值金额为 $10，结账使用 Stripe；台湾可使用信用卡（Visa、Mastercard、American Express、JCB、银联）、Apple Pay、Google Pay 和 Link；街口和 LINE Pay 不在可用列表中。详见计费说明，准备好后可以创建账户并生成密钥。
常见问题
如何在 Pi coding agent 中切换模型？
在 Pi 中输入 /model，搜索并选择可用模型；在某个模型上按 Ctrl+S，可将其保存为新工作会话的默认模型；使用 /thinking 选择思考等级（同样按 Ctrl+S 保存为启动默认值）；使用 Ctrl+P 在可用模型之间轮换；使用 /scoped-models 控制轮换范围。菜单只会列出已有可用凭证的 provider 的模型；工作会话会记录模型切换历史，恢复会话时也会一并恢复，但不会修改新工作会话的默认设置。
如何为 Pi 连接自定义 API 端点？
内置 provider 使用 /login 或环境变量即可；对于 Pi 没有内置、但使用其支持的 API（OpenAI、Anthropic 或 Google 兼容）的端点，在 ~/.pi/agent/models.json 中添加一个 provider 区块：baseUrl、api、apiKey，以及 models 列表。缺少 baseUrl 或 api 任意一个，Pi 的源代码就不会加载该模型。api 不是固定的几选一：在 2026 年 9 月 22 日文档改版前，Pi 为自定义 provider 文档化了四个值（openai-completions、openai-responses、anthropic-messages、google-generative-ai）；改版后的文档不再列出清单；v0.99.2 源代码将 api 定义为任意字符串，并交给十种内置实现中对应的一种处理，另外六种从未在文档中写成自定义 provider 的用法，这里也没有测试。连接 OpenAI 兼容端点时，填写改版后文档示例仍在使用的 openai-completions。只有需要自定义流式传输、模型探索或特殊身份验证流程的服务，才需要编写 provider extension。
Pi 从哪里读取 API 密钥？顺序是什么？
Pi 的模型文档（2026 年 10 月 1 日）所写的顺序是：运行时的 --api-key 优先级最高，其次是 auth.json 中保存的凭证（/login 保存的就是这个），然后是 models.json 的 apiKey，最后才是 provider 的环境变量。因此，之前通过 /login 保存的旧密钥会覆盖你刚写入 models.json 的密钥。apiKey 字段可以写 $NAME 或 ${NAME} 来引用环境变量、直接写值，或使用以 ! 开头的命令获取。注意：在 2026 年 9 月 22 日文档改版前，这个顺序不同（环境变量排在 models.json 前面），旧教程可能仍然写着旧顺序。
为什么我自己添加的模型在 Pi 底部显示 $0？
因为自定义模型的 cost 默认全部为 0（依据 v0.99.2 源代码），底部和 /session 中显示的是配置文件里的价格，而不是端点实际收取的费用。并不是免费，只是没有价格来源；请按照提供商的价格表填写每百万 token 的 input、output、cacheRead、cacheWrite。还要填写 contextWindow 和 maxTokens：未填写时分别默认为 128000 和 16384，大上下文模型会过早压缩，回复也会被截断。
Pi 的 baseUrl 需要加 /v1 吗？
openai-completions 类型需要加。Pi 的文档没有用一句话明确写出规则，但其兼容端点示例是 Ollama 的 http://localhost:11434/v1，改版前的 OpenRouter、Vercel AI Gateway、llama.cpp 示例也都带有版本路径。因此，OpenAI 兼容端点应填写带 /v1 的根地址，例如 https://api.kunavo.com/v1。anthropic-messages 类型则没有定论：改版前的文档一处写 /v1，另一处不写；改版后的两个示例都移除了它，仍未说明哪种写法正确。
2026 年 10 月 1 日核查：pi.dev/docs/latest/models（Choose a Model）与 providers 页面、earendil-works/pi 标签 v0.99.2 的 src/core/model-config.ts 与 provider-composer.ts，以及 GitHub API 的版本信息。同日另外核查了 api 字段：models 页面目前列出的值（只有 Ollama 示例中的 openai-completions）、v0.99.2 的 model-config.ts 中 api 的类型（任意字符串，第 191、233 行）、provider-composer.ts 对自定义模型的分派（第 579 行），以及 packages/ai/src/compat.ts 的 BUILTIN_APIS（第 180 行，共十种）。Kunavo 没有实际用 Pi 运行过自家端点。