# 用 models.json 把 Pi Agent 接到 Router One

> https://router.one/zh/integrations/pi 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-20

Pi 是在本机运行文件与 Shell 工具的终端编程 Agent，Router One 负责它发出的模型请求、路由与逐请求计费。本指南基于 earendil-works/pi 仓库发布的 @earendil-works/pi-coding-agent 0.86.1。先使用 openai-completions 适配器：这个名字对应 Chat Completions，并不是旧版文本 completions 端点。

## 安装 Pi，并导出专用网关 Key

Pi 0.86.1 要求 Node.js 22.19.0 或更新版本，先检查 Node 版本，再安装下方指定版本。为 Pi 创建一把设了 maxSpend 的专用 Router One Key，在即将启动 Pi 的终端中导出。ROUTER_ONE_API_KEY 是本指南自定义的变量名，models.json 会显式引用它。

`terminal`

```bash
node --version
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1
pi --version
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
```

## 把 Pi Agent 配置到 Router One base URL

在 ~/.pi/agent/models.json 的 providers 对象中加入 router-one，保留文件中已有的其他供应商。若设置了 PI_CODING_AGENT_DIR，则应编辑该目录下的 models.json。apiKey 使用 Pi 0.86.1 带美元符号的环境变量语法。router-one 是本地供应商标签，model.id 才是 Router One 的完整目录 ID。示例选择当前可用的聊天模型，关闭推理选项，首次测试把输出上限设为 4096 tokens；需要时可换成 /models 中其他当前可用的聊天模型。这里的 compat 让入门示例省略 store、developer 角色与 reasoning_effort 参数，不代表所有模型都不支持这些能力。

`~/.pi/agent/models.json`

```json
{
  "providers": {
    "router-one": {
      "baseUrl": "https://api.router.one/v1",
      "api": "openai-completions",
      "apiKey": "$ROUTER_ONE_API_KEY",
      "compat": {
        "supportsStore": false,
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "anthropic/claude-sonnet-5",
          "reasoning": false,
          "input": [
            "text"
          ],
          "maxTokens": 4096
        }
      ]
    }
  }
}
```

## 选中完整模型 ID，再测试一次文本响应

先用 --list-models 确认 Pi 加载了配置；它只列出本地配置，不能证明 Key 与接口已可用。在空目录运行下方文本测试，它关闭工具、会话保存、扩展与项目上下文，但模型请求仍可能计费。到 Dashboard → Logs 按模型、时间与 request_id 核对，再开始正常交互编程。--provider 与 --model 分开写，可以明确指定供应商，并保留目录 ID 中的斜杠。会话中修改 models.json 后，重新打开 /model 即可重载文件；在另一个 Shell 中新导出的环境变量不会进入已运行的 Pi 进程。

`terminal`

```bash
pi --list-models router-one
pi --provider router-one --model anthropic/claude-sonnet-5 \
  --no-tools --no-session --no-extensions --no-context-files \
  -p -- "Reply with one short greeting."

# 文本测试成功后，启动正常交互会话
pi --provider router-one --model anthropic/claude-sonnet-5
```

## 协议类型与基础地址要配套

Pi 根据 api 选择请求适配器，只改 URL 不会自动翻译协议。如果同时需要 Chat Completions 和原生协议，分别创建供应商条目。baseUrl 不要包含最后的 /chat/completions、/messages 或 /responses。

| Pi 的 api 值 | baseUrl | 请求路径与模型范围 |
| --- | --- | --- |
| openai-completions | https://api.router.one/v1 | POST /v1/chat/completions；当前聊天模型 |
| anthropic-messages | https://api.router.one | POST /v1/messages；兼容的 Claude 与 DeepSeek ID |
| openai-responses | https://api.router.one/v1 | POST /v1/responses；先在所选模型详情页确认支持 |

## 本地 token 与费用字段只是客户端配置

Pi 不会自动用 Router One 的 /models 接口填充这个自定义供应商。每个模型 ID 都要自行添加，并按所选模型调整 contextWindow、maxTokens、input 和 reasoning。Pi 0.86.1 的 contextWindow 默认是 128000；maxTokens 限制的是输出，不能把上下文窗口填进这个字段。示例把输出限制为 4096，只启用文本输入；开启图片或推理前，再核对模型详情页的当前能力。cost 省略时默认全为零，因此 Pi 可能显示零预估费用，但 Router One 仍正常计费。实际费用以 Router One Logs 中已结算记录为准；Pi 的本地费率不会自动同步账户折扣、套餐规则或长上下文分段。工具往返、重试与上下文压缩还可能增加模型调用。

## Pi Agent 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Pi Agent 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

## Pi Agent 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

## 在 trace 里验证 Pi Agent 的调用

先在 Pi Agent 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### 升级旧版 Pi 后，原来能用的 models.json 密钥为什么失效了？

环境变量语法变了。Pi 0.86.1 要写 apiKey: "$ROUTER_ONE_API_KEY"；不带美元符号的 "ROUTER_ONE_API_KEY" 会被当作字面量密钥发送，可能得到 401。旧的 0.74.2 包会把未加美元符号的变量名从环境中解析，而它的解析器不支持这里的新美元符号写法。先看 pi --version，再采用对应版本的文档。本指南统一使用 0.86.1，保留美元符号；本地模拟服务已验证新版会原样发送未加美元符号的变量名。

### /model 里找不到 router-one，或者仍在使用旧 Key，该查什么？

先检查实际配置目录、JSON 结构，以及是否在启动 Pi 之前导出了 ROUTER_ONE_API_KEY。0.86.1 引用的环境变量不存在时，凭据处于未解析状态，模型可能不出现在可用列表中。凭据优先级为命令行 --api-key、该供应商已保存的认证、内置供应商环境凭据，最后才是 models.json。因此同名 router-one 下曾保存的 Key 可能覆盖本配置。改文件后重新打开 /model；如果需要新导出的环境变量，则重启 Pi 进程。

### 400 错误提到参数时，需要修改 compat 吗？

先看实际错误。Pi 的 OpenAI 适配器通常请求 stream_options.include_usage，并可通过 compat.maxTokensField 选择发送 max_completion_tokens 或 max_tokens。支持 usage 时应保留，仅在所选模型响应要求时调整输出 token 字段。同样，reasoning 与对应格式要按模型设置，不要假定每个目录 ID 都接受 OpenAI 的 reasoning_effort。供应商级 compat 作用于该供应商的所有模型，模型级 compat 可以覆盖单个模型的设置。

### 这样会复用 ChatGPT、Claude 订阅，或改掉 Pi 原有登录吗？

不会。router-one 是独立自定义供应商，使用 Router One 账户结算；Pi 内置 OAuth 供应商及其 /login 会话是另一套连接。保留独立名称，不要替换 openai、openai-codex 或 anthropic；只改内置供应商的 base URL，可能仍沿用原来的凭据与内置模型 ID。Router One 不执行 Pi 的本地工具，也不管理其会话存储、Skills 或扩展。

### Pi Agent 能通过网关用哪些模型？

选用当前目录中同时支持 Pi Agent 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只证明模型发现成功，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- Pi Agent 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Cline 接入：https://router.one/zh/integrations/cline
- Aider 接入：https://router.one/zh/integrations/aider
- OpenCode 接入指南：https://router.one/zh/integrations/opencode
- 连接与协议排查：https://router.one/zh/api-connection-troubleshooting
- Pi 0.86.1 官方文档：自定义模型：https://github.com/earendil-works/pi/blob/v0.86.1/packages/coding-agent/docs/models.md
- Pi 0.86.1 官方文档：供应商认证：https://github.com/earendil-works/pi/blob/v0.86.1/packages/coding-agent/docs/providers.md
- Pi 官方安装包：https://www.npmjs.com/package/@earendil-works/pi-coding-agent
- Pi 更新日志：配置迁移：https://github.com/earendil-works/pi/blob/v0.86.1/packages/coding-agent/CHANGELOG.md
- 网关层负责什么：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/pi
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md