Pi 接入 Models Hub:models.json 自定义供应商

编辑 Pi(pi-mono)的 ~/.pi/agent/models.json,添加 Models Hub 作为自定义 OpenAI 兼容供应商,附验证步骤与常见报错排查。

Pi(包名 pi-mono,命令行叫 pi)是一个极简且高度可扩展的终端编码框架,支持 TypeScript 扩展、技能和提示模板,通过 ~/.pi/agent/models.json 添加自定义模型供应商。把 Models Hub 配置进去后,pi 里的对话与代码修改都会用 Models Hub 的额度调用你指定的模型。本文只讲接入,不讲 Pi 本身的用法。

三样东西

接入只需要:Models Hub 的 API Key、接入地址 https://modelsok.com/v1、一个模型名。没有一键配置,Pi 不在 Models Hub CLI 的支持范围内。

准备

已安装 Pi。运行 npm install -g @earendil-works/pi-coding-agent,装完 pi --version 能出版本号即可,详见 GitHub 仓库。
一个 Models Hub API Key。在控制台的令牌页创建,令牌所在分组要能访问你打算用的模型。

用途	模型名	定价	实时状态
日常编码首选	`claude-sonnet-4-6`	查看价格	可用率与延迟
更强推理与长任务	`gpt-5.5`	查看价格	可用率与延迟
便宜快速的小改动	`gpt-5.4-mini`	查看价格	可用率与延迟

配置步骤

第一步:设置环境变量

export MODELSOK_API_KEY="你的 Models Hub API Key"

第二步:编辑 models.json

创建或编辑 ~/.pi/agent/models.json:

{
  "providers": {
    "modelsok": {
      "baseUrl": "https://modelsok.com/v1",
      "api": "openai-completions",
      "apiKey": "$MODELSOK_API_KEY",
      "models": [
        {
          "id": "claude-sonnet-4-6",
          "name": "Claude Sonnet 4.6",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 128000
        },
        {
          "id": "gpt-5.4-mini",
          "name": "GPT-5.4 Mini",
          "contextWindow": 128000,
          "maxTokens": 16384
        }
      ]
    }
  }
}

字段要点

字段	说明
`baseUrl`	接入地址,以 `/v1` 结尾
`api`	协议类型,OpenAI 兼容协议写 `openai-completions`;Pi 也支持 `anthropic-messages` 等其它协议
`apiKey`	用 `$环境变量名` 语法引用,避免明文写进配置文件
`models[].id`	必须与 Models Hub 控制台的模型名完全一致
`models[].reasoning`	标记该模型是否支持推理,非推理模型可以省略

models 字段是整体替换

一旦给某个供应商写了 models 数组,它会替换该供应商下的全部内置模型,不是追加。想保留其它模型就把它们也列进这个数组。

验证

启动 Pi,输入 /model 打开模型选择器(每次打开都会重新读取 models.json),选择 modelsok 供应商下的模型,发一句测试消息,能正常回复即接通。再打开 Models Hub 控制台的用量日志,几秒内会出现一条对应模型名的请求。

常见报错

现象	原因	处理
`/model` 里看不到 modelsok 下的模型	`~/.pi/agent/models.json` 不是合法 JSON,或路径不对	用 `cat ~/.pi/agent/models.json` 检查文件内容,确认是合法 JSON
`401 Unauthorized`	`MODELSOK_API_KEY` 没有导出到当前 shell	检查环境变量,重开终端后再试
模型不存在	`models[].id` 与 Models Hub 控制台不一致	对照定价页核对名字
改了配置没生效	Pi 只在打开 `/model` 时重新读取文件	重新打开一次模型选择器
其它内置模型消失了	`models` 数组替换而不是追加,把原有模型顶掉了	把需要保留的模型也写进同一个数组

更多排查见故障排查。

常见问题

计费方式? 按请求实际消耗的输入与输出 token 计费,价格在各模型的定价页,用量日志里能看到每一条请求的明细。

和直接用官方 API 有什么区别? Pi 通过 openai-completions 协议把请求发给 Models Hub 网关,你不需要单独申请对应厂商的账号,一个 Key 能用所有模型。

怎么切换模型? 在 Pi 里输入 /model 打开选择器,选中目标模型即可;新增模型改完 models.json 后重新打开一次选择器就会生效。