用 models.json 把 Pi Agent 接到 Router One

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

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

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 参数，不代表所有模型都不支持这些能力。

{
  "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 进程。

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。

本地 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；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题