Pi Coding Agent 接入 NixAPI：models.json 与自定义 Provider 配置

Pi 是支持扩展的终端 Agent。本文依据 2026 年 10 月 30 日的官方仓库整理，介绍通过自定义 Provider 连接 NixAPI 的方式。以下配置基于官方协议说明；实际兼容性需要用你的 Key 和模型验证。

1. 安装当前版本

按官方安装说明，准备 Node.js 22.19 或更新版本，执行：

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

Pi 当前官方包名已变化，旧文章中的 @mariozechner/pi-coding-agent 不应直接作为当前安装指令使用。

2. 准备 Key 和模型

在 NixAPI 控制台创建 Key，从官网模型定价页复制支持工具调用的聊天模型 ID。

macOS / Linux 终端：

export NIXAPI_API_KEY='YOUR_NIXAPI_API_KEY'

Windows PowerShell：

$env:NIXAPI_API_KEY = 'YOUR_NIXAPI_API_KEY'

把占位值替换为你的 Key。这些命令作用于当前终端；从同一个终端启动 Pi。

3. 配置 models.json

创建或编辑 ~/.pi/agent/models.json。如已存在 providers，只合并 nixapi 项，保留其他设置：

{
  "providers": {
    "nixapi": {
      "baseUrl": "https://api.nixapi.com/v1",
      "api": "openai-completions",
      "apiKey": "${NIXAPI_API_KEY}",
      "authHeader": true,
      "models": [
        {
          "id": "NIXAPI_MODEL_ID",
          "name": "NixAPI coding model",
          "contextWindow": 32768,
          "maxTokens": 4096
        }
      ]
    }
  }
}

将 NIXAPI_MODEL_ID 替换为真实模型 ID；示例中的 32768 和 4096 仅用于展示配置结构，请按所选模型的真实上下文与最大输出填写。

注意 baseUrl 中的 l 是小写；apiKey 使用 ${NIXAPI_API_KEY} 插值，而不是直接写环境变量名称。authHeader: true 表示以 Bearer 方式携带 Key。字段定义见官方模型配置参考。

4. 启动和验证

在用于测试的项目目录运行，替换命令中的模型占位符：

pi --provider nixapi --model NIXAPI_MODEL_ID

先发送“只回复 NixAPI 连接成功”，再请求读取项目中的 package.json 并概括 scripts，暂不修改文件。检查是否执行了真实的 read 工具调用。

也可以在含有 package.json 的测试项目中执行只开放读取工具的验证命令：

pi --provider nixapi --model NIXAPI_MODEL_ID --no-mcp --tools read --print \
  'Read package.json using the read tool and summarize the scripts. Do not modify files.'

这些选项见官方 CLI 参考。普通文字回复成功只验证聊天链路，还需要确认工具调用返回能进入下一轮。

5. 常见问题

• 找不到 Provider：检查文件是否为 ~/.pi/agent/models.json、JSON 是否有效；当前模型使用指南说明 /model 会重新加载模型配置。
• 401：确认当前终端中已设置 NIXAPI_API_KEY，并且 JSON 使用了插值写法。
• 404：确认 Base URL 为 https://api.nixapi.com/v1，没有重复追加 /v1 或完整的 /chat/completions 路径。
• 模型不存在或工具失败：检查模型 ID、Key 的分组权限和工具调用能力，不要仅修改上下文数字来绕过错误。