工具集成/pi-dev 接入

把 UniGateway 接入 Pi。

pi-dev 接入

pi-dev 是一款通过 npm 分发的终端 AI 编程代理。通过将 pi 接入 UniGateway，你可以通过单一统一端点访问多种模型，实现集中密钥管理、自动回退，且无需修改任何上游 SDK。

兼容性说明

UniGateway 完全支持 OpenAI Chat Completions 协议，可以作为自定义提供商无缝集成到 pi 中。配置使用 openai-completions API 类型，并将 baseUrl 指向 UniGateway 端点。

注意 baseUrl 必须以 /v1 结尾 — 完整 URL 为 https://api.unigateway.ai/v1。pi 会自动拼接后续路径，因此请不要省略 /v1 后缀，也不要重复添加。

配置

第 1 步：安装 pi

使用 npm 全局安装 pi 编程代理：

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

第 2 步：配置 models.json

在以下路径新建配置文件：

Windows：

C:\Users\<你的用户名>\.pi\agent\models.json

macOS / Linux：

~/.pi/agent/models.json

然后填入以下内容：

{
  "providers": {
    "unigateway": {
      "baseUrl": "https://api.unigateway.ai/v1",
      "api": "openai-completions",
      "apiKey": "your api key",
      "models": [
        { "id": "gpt-5.5" }
      ]
    }
  }
}

重要： 将 apiKey 字段替换为你实际的 UniGateway API Key。你可以在 UniGateway 控制台获取你的 API Key。

models 数组中的模型 ID 应与 GET /v1/models 返回的模型 ID 一致 — 参见 模型列表。你可以在数组中添加多个模型。

模型推荐

建议添加不同能力和价格梯度的模型以适应各种使用场景：

  • 高复杂度任务（多文件重构、调试、复杂逻辑）：claude-sonnet-4-6、gpt-5.2
  • 均衡任务（通用编程、解释）：gemini-2.5-pro、gpt-4.1
  • 快速迭代（简单编辑、问答）：gpt-4.1-mini、deepseek-chat

第 3 步：最后验证

新开一个 PowerShell（或终端）窗口，输入 pi 启动：

pi

向 AI 发送一条简单消息，如能成功收到回复，则接入完成。

故障排除

API Key 错误

问题： pi 提示 API Key 无效或未授权。

解决方案：

  • 检查 API Key 是否复制正确，避免多余空格或换行
  • 确认 API Key 已激活且账户余额充足
  • 重新编辑 models.json 并验证 apiKey 字段

配置文件未找到

问题： pi 无法找到或读取配置文件。

解决方案：

  • 确保 models.json 位于 ~/.pi/agent/models.json（Windows 上为 C:\Users\<你的用户名>\.pi\agent\models.json）
  • 检查 JSON 语法是否正确，可使用 JSON 验证器
  • 确保 providers、baseUrl、api、apiKey 和 models 字段均已填写

模型不可用

问题： 配置的模型无响应或返回 404。

解决方案：

  • 确认 models.json 中的模型 id 与 GET /v1/models 返回的完全一致 — 一个字符的差异会导致 404
  • 验证 baseUrl 设置为 https://api.unigateway.ai/v1（注意 /v1 后缀）

连接被拒绝/超时

问题： 无法连接到 UniGateway 端点。

解决方案：

  • 验证网络连通性，尝试在浏览器中访问 https://api.unigateway.ai
  • 确保防火墙或代理设置未阻止对 UniGateway 服务器的访问
  • 确认 baseUrl 包含 /v1 后缀

参见