Pi 接中转 API：models.json 配置、多轮 400 与多模型排查

1. Pi 为什么要接中转

Pi（Pi Coding Agent）定位与 Claude Code、Codex、OpenCode 类似，但更精简、更轻量，通过 npm 安装：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

它原生支持多供应商，接中转有两个直接动机：一是官方端点在国内不稳，改用可直连的中转 Base URL；二是用一个 Pi 同时调 Claude、GPT、Gemini 与国产模型，而不必为每家单独换客户端。中转（API 网关）如何转发请求，可先看什么是 AI API 中转站。

2. 手动配置 models.json

编辑 ~/.pi/agent/models.json（Windows 为 %USERPROFILE%\.pi\agent\models.json），在 providers 下新增一个指向中转的供应商。大部分服务都支持 OpenAI chat 格式，api 填 openai-completions 即可；需要时也可填 openai-responses 或 anthropic-messages。

{
  "providers": {
    "codex789": {
      "baseUrl": "https://www.codex789.com/v1",
      "api": "openai-completions",
      "apiKey": "YOUR_API_KEY",
      "models": [
        {
          "id": "MODEL_ID",
          "name": "显示名称",
          "reasoning": MODEL_SUPPORTS_REASONING,
          "input": INPUT_MODALITIES,
          "contextWindow": CONTEXT_WINDOW,
          "maxTokens": MAX_TOKENS
        }
      ]
    }
  }
}

id 必须与网关返回的模型 id 完全一致，从模型广场或 /v1/models 复制，不要手写。input 决定该模型能否接收图片，纯文本模型不要加 "image"。OpenAI 兼容 SDK 的通用用法见OpenAI 兼容 API 接入指南。若不想手写，社区也有把中转站一键写入 models.json 的配置工具（TUI 向导，从 models.dev 拉取模型参数）。

3. 一份配置调 Claude、GPT、Gemini 与国产模型

Pi 的 providers 可以并列多个供应商，也可以在同一供应商下列多个模型，用一份 models.json 覆盖不同任务：

• 复杂架构与跨文件重构：Claude Opus 5、Claude Sonnet 5（Claude 系可用 anthropic-messages 协议）。
• 日常修复与批量任务：GPT-5.6、DeepSeek V4 Pro、GLM-5.3、MiniMax M3。
• 长上下文：Gemini 3 Pro。

各模型价格与倍率口径见中转倍率说明；担心网关返回的不是所选模型时，参考如何验证中转返回的是真模型。

4. 多轮工具调用返回 400：补 reasoning_content

接部分推理模型（DeepSeek 及跟进同一协议的模型，如 MiMo 等）时，单轮正常、一进入带工具调用的多轮会话就报 400，是最容易踩的坑。原因是这类模型要求：在包含工具调用的历史里，assistant 消息必须完整回传 reasoning_content 字段，否则 API 直接返回 400。

解决办法是在该模型的配置里打开对应兼容开关，把推理内容随 assistant 消息回传：

{
  "id": "MODEL_ID",
  "reasoning": true,
  "input": ["text"],
  "contextWindow": CONTEXT_WINDOW,
  "maxTokens": MAX_TOKENS,
  "compat": {
    "requiresReasoningContentOnAssistantMessages": true
  }
}

这个开关是模型级的，只影响对应的 OpenAI 兼容模型；用 Anthropic 协议的 Claude 系通常不受影响。改完重开会话再测。通用 HTTP 状态码（400/401/429/5xx）排查见API 错误码对照。

5. 会话中途换模型与识图异常

• 不要在同一会话里切模型。历史消息的推理/工具字段格式与模型强相关，中途换模型容易触发 400 或串上下文。换模型时新开一个会话，别在旧会话里直接切。
• 识图“乱说”先查 input。模型答非所问、看不到图，多半是配置里没给该模型声明 "image" 输入，或该模型本身不支持多模态。确认 input 含 "image" 且模型确实支持图像；不支持的模型不要硬塞图片。
• 先小步验证再放权。配好后先让 Pi 只读项目结构、发一个短任务，确认响应正常、返回的模型 id 与预期一致、控制台有对应用量，再允许写文件。

6. 常见问题

Pi 的配置文件在哪里？

在 ~/.pi/agent/models.json（Windows 为 %USERPROFILE%\.pi\agent\models.json）。若目录下只有 settings 和 auth 文件，手动新建 models.json 并填入 providers 即可。

接中转 api 该填什么？

大部分中转是 OpenAI 兼容，填 openai-completions；Claude 系可用 anthropic-messages。协议要与 Base URL 对应的端点匹配。

多轮对话报 400 怎么办？

多为推理模型要求 assistant 消息回传 reasoning_content。在该模型配置加 compat.requiresReasoningContentOnAssistantMessages: true，重开会话再测。

能用一份配置调多个模型吗？

可以。providers 下并列多个供应商或在同一供应商下列多个模型，即可用一个 Pi 跨模型开发，模型 id 以网关返回为准。