pi coding agent 多站点模型接入:用一个扩展替代手写 models.json
用 pi coding agent 接第三方模型站点,默认流程是编辑 ~/.pi/agent/models.json,一个站点一段配置。站点少的时候没问题,站点一多就变成体力活:复制、改字段、重启、去 /model 里找,模型列表更新了还得手动对齐。
这篇介绍一个替代方案:用扩展在启动时把外部配置注册成 provider。配置存在单独的 provider-hub.json 里,models.json 不动。
本文覆盖安装、添加站点、连接测试、多站点切换、配置迁移、常见报错,以及它内部到底做了什么。文中的命令和配置都在 Windows 11 + Node 26 + pi 0.84.4 上实际跑过,Linux 和 macOS 路径同理,把 C:\Users\<你>\.pi\agent 换成 ~/.pi/agent 即可。
一、为什么不用手写
手写 models.json 有几个具体麻烦:
- 字段容易填错,且不报错。
contextWindow写成 0,表现是聊两句就触发压缩或者直接报上下文超限。 - 模型列表不会自动更新。站点上新、下线模型,你不去 curl
/models就不知道。 - key 和官方配置混在一起。备份目录、分享配置时容易连带泄露。
- 改完要重启。pi 不会监听这个文件的变化。
还有一个不容易想到的:apiKey 末尾多一个空格,JSON 完全合法,请求却一直 401。没有报错,没有日志,只能靠猜。
如果只有一两个站点,这些都能忍。五个以上,值得换个方式。
二、环境
- pi coding agent 0.84 及以上(
pi --version查看) - Node.js 20 以上(pi 自带运行时,一般不用单独装)
扩展用 TypeScript 写,pi 通过 jiti 在运行时转译,不需要构建,也没有编译产物。这意味着装下来的就是源码,node_modules 里只有开发用的类型依赖。
三、安装与卸载
从 npm 安装(推荐):
pi install npm:pi-provider-hub-multi
固定版本:
pi install npm:pi-provider-hub-multi@0.2.1
从 GitHub 安装指定 tag:
pi install git:github.com/Sunrisies/pi-provider-hub@v0.2.1
只对当前项目生效,加 -l:
pi install -l npm:pi-provider-hub-multi
装完重启 pi,输入 /providers 能打开菜单就说明成功。
注意:
npm install pi-provider-hub-multi不会让 pi 加载它。pi 的包管理走pi install,它会把包写进~/.pi/agent/settings.json的packages字段。
查看已装了什么:
pi list
升级:
pi update npm:pi-provider-hub-multi
卸载:
pi remove npm:pi-provider-hub-multi
卸载只从 settings.json 里移除条目,provider-hub.json 会保留。想彻底清干净,手动删掉它。
四、添加一个站点
输入 /providers,选「+ 添加新站点」,然后按提示填:
- 站点名称:随便起,比如
my-proxy。插件会据此生成 provider id(小写、连字符),中文名会让你补一个短 id。 - Base URL:只填域名也行,比如
api.example.com。它会先试https://api.example.com/v1/models,不通再试https://api.example.com/models。 - API Key:直接粘贴。注意这里是明文显示,pi 的输入框没有密码模式。
- 协议:不确定就选「自动检测」。它会先按 OpenAI 兼容试 Bearer,返回 401/403 再换
x-api-key(Anthropic 风格);选 Google 时用x-goog-api-key。 - 筛选关键词:可以留空(导入全部),也可以写
claude,gpt-4o;前面加-表示排除,比如-embedding,-whisper。 - 确认导入:会显示前几个模型、跳过数量和最终使用的接口地址。
几个填写示例:
| 站点类型 | Base URL | 协议 |
|---|---|---|
| OpenAI 兼容中转 | https://api.example.com/v1 |
OpenAI Chat |
| 只给域名 | api.example.com |
自动检测 |
| Anthropic 官方或中转 | https://api.anthropic.com/v1 |
Anthropic Messages |
| Google Gemini | https://generativelanguage.googleapis.com/v1beta |
|
| 本地 Ollama / LM Studio | http://127.0.0.1:11434/v1 |
OpenAI Chat |
保存后立刻生效,打开 /model 就能看到新站点下的模型。
五、验证
先看列表:
pi --list-models
输出里能找到 <provider-id> <model-id> <上下文> <输出上限> 就说明注册成功,例如:
my-proxy gpt-4o-mini 128K 8.2K
再做一次真实调用测试:
/providers test my-proxy
它会选一个模型发一句 ping,最多 16 个 token,成功时显示类似:
连接成功:my-proxy · gpt-4o-mini · 812ms · pong
失败时显示 HTTP 状态和错误信息,比如 HTTP 401: invalid api key。
状态码对照:
- 401:key 错、过期,或者鉴权方式选错(该用
x-api-key却发了 Bearer)。 - 403:key 有效但没权限,常见于没加 IP 白名单。
- 404:路径不对,多半是
/v1加多了或少了。 - 429:限流或额度用完,等一会儿或去充值。
- 超时:网络不通、代理没配,或者站点本身挂了。
六、多站点与默认模型
配好几个站点之后,/model 里会按 provider 分组列出模型,选中即切换,当前会话立即生效。
想让某个模型成为新会话的默认值,改 ~/.pi/agent/settings.json:
{
"defaultProvider": "my-proxy",
"defaultModel": "gpt-4o-mini"
}
也可以只在某次启动时指定,不改配置:
pi --provider my-proxy --model gpt-4o-mini
插件本身不修改这两个字段。默认模型属于使用习惯,交给用户自己定比较稳妥。
七、配置文件
所有站点存在 ~/.pi/agent/provider-hub.json,权限 0600。结构大致如下:
{
"version": 1,
"providers": [
{
"id": "my-proxy",
"name": "my-proxy",
"baseUrl": "https://api.example.com/v1",
"apiKey": "sk-xxxx",
"api": "openai-completions",
"filter": "claude,gpt-4o",
"models": [
{
"id": "gpt-4o-mini",
"name": "gpt-4o-mini",
"contextWindow": 131072,
"maxTokens": 8192,
"vision": true,
"reasoning": false
}
],
"createdAt": "2026-11-17T00:00:00.000Z",
"updatedAt": "2026-11-17T00:00:00.000Z"
}
]
}
字段说明:
api:openai-completions、anthropic-messages、openai-responses、google-generative-ai之一。filter:上次使用的筛选表达式,刷新时作为默认值带出来。models:注册给 pi 的模型快照,/providers refresh时整体替换。
换设备时把这个文件拷过去,或者在新设备上重新 /providers add。npm 包里不含任何 key 和站点配置。
八、从 models.json 迁移
如果你已经有 models.json,不想重新填一遍,可以写个一次性脚本转换。先备份原文件,再执行:
// migrate.mjs —— 把 models.json 里明文 key 的站点转到 provider-hub.json
import {
readFileSync, writeFileSync } from "node:fs";
import {
join } from "node:path";
const dir = process.env.PI_CODING_AGENT_DIR ?? join(process.env.USERPROFILE ?? process.env.HOME, ".pi", "agent");
const raw = JSON.parse(readFileSync(join(dir, "models.json"), "utf8"));
const now = new Date().toISOString();
const providers = Object.entries(raw.providers ?? {
}).map(([id, p]) => ({
id,
name: id,
baseUrl: p.baseUrl ?? "",
apiKey: p.apiKey ?? "",
api: p.api ?? "openai-completions",
filter: "",
models: (p.models ?? []).map((m) => ({
id: m.id,
name: m.name ?? m.id,
contextWindow: m.contextWindow ?? 131072,
maxTokens: m.maxTokens ?? 8192,
vision: (m.input ?? []).includes("image"),
reasoning: m.reasoning === true,
})),
createdAt: now,
updatedAt: now,
})).filter((p) => p.baseUrl && p.models.length > 0);
writeFileSync(
join(dir, "provider-hub.json"),
JSON.stringify({
version: 1, providers }, null, 2),
{
mode: 0o600 },
);
console.log(`已转换 ${
providers.length} 个站点`);
两个注意点:
- 只迁移
apiKey是明文的条目。如果models.json里用的是$ENV_VAR形式,直接搬过来会被当作字面量,鉴权会失败,需要手动改成实际 key。 - 迁移后把
models.json里对应的条目删掉或改名,否则同一个 id 会同时存在于两处,扩展注册时覆盖它,删站点之后又会恢复成旧配置,容易看花眼。
九、命令表
| 命令 | 作用 |
|---|---|
/providers |
打开菜单 |
/providers add |
添加站点 |
/providers list |
列出站点,选中可看详情 |
/providers refresh [id] |
重新拉取模型列表,省略 id 时选站点 |
/providers test [id] |
发 ping 测试连通性 |
/providers edit <id> |
改 URL、key、协议 |
/providers remove <id> |
删除站点并注销 provider |
/providers path |
打印配置文件路径 |
edit 里 URL 和 key 留空表示保持不变,避免每次改协议都要重输 key。
所有子命令都支持 Tab 补全,输入 /providers re 再按 Tab 会列出 refresh、remove。
十、常见问题
Q:拉了 0 个模型?
先确认 base URL。用 curl 直接试:
curl -s -H "Authorization: Bearer $KEY" https://api.example.com/v1/models | head -c 300
返回 404,把 /v1 去掉或加上再试;返回 HTML,说明这个地址不是 API 端点,可能少了 /v1 或者被网关拦了。
Q:模型列表有,但聊天报错?
多半是协议选错。Anthropic 风格的站点要选 anthropic-messages,路径是 /messages 而不是 /chat/completions。也可能站点只支持流式,而非流式请求被拒。用 -p 模式跑一句能快速确认:
pi --provider my-proxy --model gpt-4o-mini -p "say hi" --no-session
Q:key 会被上传吗?
不会。key 只写在本机的 provider-hub.json,扩展只在你点刷新或测试时发请求,发往你自己填的地址。
Q:价格为什么显示 0?
/models 接口通常不返回价格,插件统一填 0。这只影响 pi 的成本统计显示,不影响实际计费。
Q:内网网关能用吗?
能,地址填 http://192.168.x.x:8080/v1 即可,需要 pi 能访问到该地址。走 HTTP 而不是 HTTPS 也可以,插件不强制加密。
Q:和 models.json 冲突怎么办?
provider id 撞上内置或已存在的 provider 时会二次确认。确认后会覆盖同名 provider 的模型列表,删掉扩展配置后恢复原样。
Q:重启后配置丢了?
配置写在 ~/.pi/agent/provider-hub.json,不在项目目录,也不在会话里。如果文件存在但 /providers list 是空的,多半是 JSON 损坏,命令会提示是否覆盖重建,覆盖前先备份。
Q:能同步到其他客户端吗?
不能。它只注册给 pi。Cursor、Claude Code 有自己的配置方式,需要单独填。
十一、它做了什么
核心就一件事:在扩展初始化时调用 pi.registerProvider(id, config)。pi 会等待扩展的初始化函数执行完再进入会话,所以注册的 provider 对 pi --list-models 也是可见的。
export default function providerHub(pi: ExtensionAPI) {
const {
config } = loadConfig(getAgentDir());
for (const p of config.providers) {
if (p.models.length === 0) continue;
pi.registerProvider(p.id, toProviderConfig(p));
}
}
一个必须注意的点:registerProvider 传入 models 时是替换该 provider 的全部模型,不是追加。所以空模型列表不注册,否则会把内置的同名 provider 清空。
拉取模型时做了几件事:
- 枚举候选端点(带不带
/v1),逐个试 - 枚举鉴权方式(Bearer →
x-api-key),401/403 时切换 - 兼容
{data:[]}、{models:[]}、{result:{data:[]}}和裸数组几种返回 - 过滤 embedding、whisper、rerank 等非对话模型
- 上下文长度优先读接口字段,没有就按名字推断(
-128k、-1m、claude等) - 拉列表超时 15 秒,连接测试 20 秒
还有一个容易被忽略的细节:apiKey 里的 $ 会被 pi 当作环境变量插值,开头是 ! 会被当作命令执行。注册前必须转义成 $$ 和 $!,否则带 $ 的 key 会鉴权失败,而且很难查。
十二、局限
- 不支持自定义流式协议,只覆盖四种内置
api。 - key 明文存储,依赖文件权限保护。
- 不做路由、重试、负载均衡、用量统计。
- 模型列表是快照,站点更新后需要手动 refresh。
- 模型元数据靠接口字段加名称推断,
contextWindow和maxTokens可能不准,只影响 pi 的上下文管理和成本显示。
十三、参考
- 项目地址:https://github.com/Sunrisies/pi-provider-hub
- npm:https://www.npmjs.com/package/pi-provider-hub-multi
- pi.dev 页面:https://pi.dev/packages/pi-provider-hub-multi
- 安装:
pi install npm:pi-provider-hub-multi - 许可证:MIT
本文为原创,转载请注明出处。