pi-endpoints

让 pi 通过你自己的 API 服务使用模型，例如自己部署的 CLIProxyAPI、Magpie，或者基于 new-api / one-api 的中转站。

• 只注册你选定的模型。 服务上有几十个模型时，pi 的模型列表里只出现你启用的那几个。
• 参数取自服务本身。 上下文长度、最大输出、思考档位优先用服务端目录返回的值。pi 不会提供服务不支持的档位，例如在只支持 low 到 max 的 GPT 上，不会出现"关闭思考"。
• 自动选择协议。 每个模型按服务端信息和模型名，选用 OpenAI Responses、OpenAI Chat Completions、Anthropic Messages 或 Google Generative AI 协议，也可以手动指定。
• 可以同时接入多个服务。 每个服务在 pi 里是一个服务商，模型写成 <服务名>/<模型 id>，例如 cpa/gpt-6.1-sol。
• 密钥和配置分开存放。 密钥单独存放在本机，配置文件可以同步到别的电脑。

安装

需要 pi 1.3.0 或更高版本。

pi install npm:pi-endpoints

快速上手

1. 在 pi 里运行 /endpoints，浏览器会打开管理页。
2. 点"添加服务"，填写显示名（如 CPA）、服务地址（如 https://example.com，不带 /v1）和 API 密钥。名字按显示名自动生成（如 cpa），也可以自己改。
3. 点"添加"。插件保存服务后立即读取服务上的模型列表，读取失败时页面顶部显示服务端返回的原因，服务照样保存。
4. 在"模型"页打开要用的模型的开关。打开后立即生效，在 /model 里就能选到，或者用 pi --model cpa/gpt-6.1-sol 指定。

管理页

插件只有一个命令 /endpoints，所有操作都在它打开的管理页里完成。

管理页只在本机 127.0.0.1 上开放，每次运行 /endpoints 都会生成新的随机链接。退出 pi，或者运行 /reload、/new、/resume 这类切换会话的命令后，页面失效，需要重新运行 /endpoints。

左栏底部显示插件的版本号。npm 上有新版本时，版本号右边出现绿色的向上箭头，点击打开这个版本的 Release 页面；用 pi update --extensions 更新。

左栏列出所有服务，服务名旁的圆点表示是否已注册到 pi，红色表示有错误。右边的开关停用整个服务：停用后不注册到 pi，已启用的模型、手动设置和密钥都保留，重新打开后恢复，并刷新一次目录。停用的服务排在启用的服务下面，中间用横线隔开；刚停用或刚启用的服务先留在原处，方便改回来，刷新页面后再挪到对应的一组。打开页面时默认选中第一个启用的服务。选中一个服务后，页头显示地址、密钥状态和目录的刷新时间，"刷新目录"按钮立即读取服务上的模型列表，也可以用来测试连接。下面分"模型"和"服务设置"两页。

• 模型：用开关启用或停用模型。列表按模型 id 的前缀分组，分组可以折叠。gpt、claude、gemini、grok 按这个顺序排在前面，其余前缀按字母序排在后面。每组按模型名里的版本号从新到旧排列，如 gpt-6.1-sol、gpt-6-sol、gpt-5.6-sol；名字里没有版本号的排在最后。列表上方的按钮可以只看已启用的模型或某个前缀的模型。在"已启用"里停用的模型先留在原处，方便改回来，再点一次"已启用"或刷新页面后移走。还可以按模型 id 或名称搜索，按协议和 owned_by 筛选；服务端标为隐藏（visibility: hide）的模型，以及名字里带 image 一词的图片生成模型，默认不显示，勾选"显示隐藏模型"后显示，也可以启用。上下文、最大输出和思考档位后面的圆点表示值的来源："服务端"、"pi 自带"（pi 内置的模型目录）、"手动"或"默认值"。用了默认值的模型标为"缺参数"，请手动补齐；已启用但服务上已经没有的模型标为"目录里没有"。
• pi 默认模型：pi 新开会话时使用的模型在模型名后面标一颗实心星；这个模型没有注册到 pi 时，星标变灰。鼠标移到其他模型上会出现空心星，点一下设为默认，只有已启用的模型可以设；再点实心星取消默认，pi 新开会话时改用 Ctrl+P 列表的第一个或 pi 自带的默认模型；模型详情里也有同样的星标。这和在 pi 的 /model 里按 Ctrl+S 是同一个设置，写在全局的 settings.json 里：新开的 pi 立即生效，运行中的 pi 需执行 /reload。项目目录的 .pi/settings.json 里设了 defaultModel 时，在那个目录里以项目设置为准。
• 模型详情：点一个模型，右侧打开详情，列出生效的参数和各自的来源，下面是手动设置。可以覆盖名称、协议、地址、上下文、最大输出、输入类型、思考档位、请求头、compat 和价格，留空的项自动取值。思考档位填 pi 的档位名，如 low, medium, high；只填 none 表示不支持调节思考；和其他档位一起写 none 或 off，表示可以关闭思考。
• 发送测试消息：在模型详情里，用当前生效的参数给模型发一条消息。失败时显示服务端返回的原文，中转站的错误信息常常直接说明了原因，例如提示不支持所选模型，多半是协议选错了。
• 服务设置：密钥，以及显示名、名字、地址、密钥环境变量、默认协议和加在这个服务所有请求上的请求头。名字里的大写字母在输入框失焦时转为小写；改显示名不会改名字，因为改名字会让 pi 里引用 <服务名>/<模型 id> 的设置失效。协议按模型分别判断，同一服务可混用多种协议，无需按协议拆分；默认协议仅在无法判断时使用。请求头的值按原样发送，不解释 $环境变量 这类写法。密钥只能写入，页面只显示"已设置"或"未设置"，以及密钥来自文件还是环境变量。

参数来源

每项参数按下面的顺序取值，越靠前越优先：

1. 你在管理页里手动填写的值。
2. 服务端目录返回的值。CLIProxyAPI 和 Magpie 会返回上下文、最大输出和思考档位，new-api 类中转站一般只返回模型名。
3. pi 自带的模型目录里同名模型的值。匹配时会去掉 codex/ 这类前缀，以及日期和 -high 这类后缀。这些是官方 API 的参数，可能和走订阅账号的服务不一致。
4. 保守的默认值：上下文 128000，最大输出 16384，不支持调节思考。

另外两项不从服务端读取：

• compat（协议兼容设置）：按模型原厂从 pi 自带目录里同名模型抄过来。背后是 ChatGPT 订阅的服务上的 GPT 模型，抄订阅版 openai-codex 的设置。
• 价格：按原厂从 pi 自带目录里抄官方 API 的价格，pi 显示的花费是"相当于官方 API 的花费"。找不到时为 0。

Anthropic 的 beta 请求头

走 Anthropic 协议的 Claude 模型，上下文超过 200000 时，插件自动在请求里加上 anthropic-beta: context-1m-2025-08-07。CLIProxyAPI 这类背后是 Claude 订阅账号的服务，只有请求带上它才提供 1M 上下文。不需要时，在模型的手动设置里把上下文改成 200000，就不会再加。

在服务或模型的请求头里写的 anthropic-beta，会追加到 pi 自己按模型能力生成的 beta 列表里，多个值用逗号分开。

配置文件

所有文件都在 pi 的配置目录下（默认 ~/.pi/agent/）：

文件	内容	可以同步
endpoints.json	服务列表、启用的模型、请求头和手动设置	可以。请求头也保存在这里，不要把密钥写进请求头
endpoints-auth.json	每个服务的密钥。在 macOS 和 Linux 上权限为 600	不要同步
endpoints-cache.json	各服务模型目录的缓存	不需要

在服务设置里填写"密钥环境变量"（如 CPA_API_KEY，只写名字，不带 $）后，只要这个环境变量有值，就优先用它作为密钥。适合 CI 这类没有管理页的环境：同步 endpoints.json，再设置环境变量即可。

可以同时运行多个 pi：每次修改前都会重新读取这几个文件，不会覆盖别的 pi 做的修改。别的 pi 要运行 /reload 才会用上新配置。手工编辑 endpoints.json 后也要运行 /reload。文件写坏时插件照常加载，管理页会显示错误，修好之前不能修改配置。

目录何时刷新

• 启动时用缓存注册模型，不等待网络，服务连不上也能照常启动。
• 交互模式和 RPC 模式启动后，以及打开 /model 时，pi 会刷新已注册服务的目录。
• 打开管理页时，在后台刷新所有已启用、已设置密钥的服务；在管理页重新启用一个服务时，刷新这个服务。
• 在管理页点"刷新目录"，会立即刷新这个服务。
• 用 pi -p 这类非交互方式运行时不刷新，直接用缓存。

每次刷新最多等 15 秒。刷新失败时保留上次的缓存，失败原因显示在管理页里。

限制

• 服务名不能和 pi 自带的服务商同名（如 openai、anthropic），否则会替换掉 pi 自带的模型。
• 不支持 Codex 原生协议（/backend-api/、Fast 模式、WebSocket）。GPT 模型走服务的 /v1/responses。
• 只有未停用、有已启用模型、并且设置了密钥的服务才会注册到 pi。

开发

需要 Node.js 22.19 或更高版本（和 pi 相同）。

npm install
npm run check   # 类型检查
npm test        # 单元测试
pi -e .         # 在 pi 里加载当前目录试用

架构、数据格式和设计约束见 技术文档。

许可证

GNU AGPL-3.0-or-later