Pi Coding Agent 配置 APIMaster.ai

在 Pi Coding Agent 中通过 models.json 与 auth.json 接入 apimaster.ai OpenAI 兼容 API，含 Windows 与 macOS 配置步骤。

Pi Coding Agent（@earendil-works/pi-coding-agent）是终端里的开源 AI 编程 Agent。APIMaster.ai 提供 OpenAI 兼容 接口（POST /v1/chat/completions），在 Pi 里添加自定义 provider apimaster 即可使用当前上架的聊天 / 代码模型。

开始前请获取 API Key。Pi 主要用于聊天与代码代理类文本模型；模型 id 与模型广场及 GET /v1/models 一致。
本文与 Pi 官方 models.json 文档对齐。

前置条件

安装 Node.js 18+ 与 npm。
全局安装 Pi：

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

已从 APIMaster 控制台复制 API Key（下文用占位符，不要把真实 Key 写进文档或提交到 Git）。

配置目录

平台	路径
Windows	`C:\Users\<用户名>\.pi\agent\`
macOS / Linux	`~/.pi/agent/`

需要创建或编辑的文件：

文件	作用
`models.json`	定义 `apimaster` provider、Base URL 与模型列表
`auth.json`	存储 `apimaster` 的 API Key（可选，若已用环境变量可二选一）

首次使用前创建目录：

# macOS / Linux
mkdir -p ~/.pi/agent
chmod 700 ~/.pi/agent

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.pi\agent"

第 1 步：编写 models.json

在配置目录创建 models.json。顶层必须是 providers，不能只写 {"apiKey": "..."}。

将 models.json 保存为 UTF-8 无 BOM（Windows 见下方「常见错误」）。

{
  "providers": {
    "apimaster": {
      "baseUrl": "https://apimaster.ai/v1",
      "api": "openai-completions",
      "apiKey": "$APIMASTER_API_KEY",
      "models": [
        {
          "id": "claude-haiku-4-5",
          "name": "Claude Haiku 4.5 via apimaster",
          "reasoning": true,
          "contextWindow": 128000,
          "maxTokens": 16384
        },
        {
          "id": "claude-opus-4-7",
          "name": "Claude Opus 4.7 via apimaster",
          "reasoning": true,
          "contextWindow": 128000,
          "maxTokens": 16384
        },
        {
          "id": "claude-opus-4-8",
          "name": "Claude Opus 4.8 via apimaster",
          "reasoning": true,
          "contextWindow": 128000,
          "maxTokens": 16384
        },
        {
          "id": "claude-sonnet-4-6",
          "name": "Claude Sonnet 4.6 via apimaster",
          "reasoning": true,
          "contextWindow": 128000,
          "maxTokens": 16384
        },
        {
          "id": "gpt-5.4",
          "name": "GPT 5.4 via apimaster",
          "reasoning": true,
          "contextWindow": 128000,
          "maxTokens": 16384
        },
        {
          "id": "gpt-5.5",
          "name": "GPT 5.5 via apimaster",
          "reasoning": true,
          "contextWindow": 128000,
          "maxTokens": 16384
        },
        {
          "id": "minimax-m3",
          "name": "MiniMax M3 via apimaster",
          "reasoning": true,
          "contextWindow": 128000,
          "maxTokens": 16384
        }
      ]
    }
  }
}

说明：

baseUrl 须为 https://apimaster.ai/v1（与 OpenAI 兼容接入一致）。
apiKey": "$APIMASTER_API_KEY" 表示从环境变量读取（推荐）；也可在 auth.json 中配置（见下一步）。
models.json 会在打开 /model 时热重载，一般无需重启 Pi。
上述 7 个 id 对应当前 APIMaster GET /v1/models 中的文本 / 代码代理模型。

第 2 步：编写 auth.json（可选）

若不想用环境变量，可在同一目录创建 auth.json（权限建议 0600）：

{
  "apimaster": {
    "type": "api_key",
    "key": "你的_apimaster_key"
  }
}

将 你的_apimaster_key 替换为控制台复制的 Key。不要将真实 Key 提交到 Git 或发到群聊。

Pi 解析凭据的优先级（节选）：CLI --api-key → auth.json → 环境变量 → models.json 中的 apiKey 字段。详见 Pi providers 文档。

第 3 步：配置环境变量

Windows（PowerShell）

当前终端临时生效：

$env:APIMASTER_API_KEY="你的_apimaster_key"

当前用户永久生效：

[Environment]::SetEnvironmentVariable("APIMASTER_API_KEY", "你的_apimaster_key", "User")

设置永久变量后，需重新打开 PowerShell 或终端窗口。

macOS / Linux

当前终端临时生效：

export APIMASTER_API_KEY="你的_apimaster_key"

永久写入 shell 配置（zsh 默认）：

echo 'export APIMASTER_API_KEY="你的_apimaster_key"' >> ~/.zshrc
source ~/.zshrc

若使用 bash，将 ~/.zshrc 改为 ~/.bashrc 或 ~/.bash_profile。

第 4 步：验证

在任意项目目录执行：

pi --list-models

应能看到 apimaster/ 前缀下的模型，例如 apimaster/gpt-5.5。

指定 provider 与模型启动（示例）：

pi --provider apimaster --model gpt-5.5

进入交互后还可用 /model 或 Ctrl+L 切换模型，Ctrl+P 在常用模型间循环。

一次性提问（非交互）：

pi --provider apimaster --model claude-sonnet-4-6 -p "用一句话介绍你自己"

常见错误

现象	原因与处理
`JSON.parse` / Unexpected token	Windows 用 PowerShell 写 JSON 时可能带 UTF-8 BOM。请用 VS Code「UTF-8」编码保存，或 Node：`node -e "require('fs').writeFileSync('models.json', JSON.stringify(obj,null,2))"`
`pi --list-models` 没有 apimaster 模型	检查文件路径是否为 `C:\Users\<用户名>\.pi\agent\models.json`（Windows）或 `~/.pi/agent/models.json`（macOS）
配置无效 / 无 provider	`models.json` 顶层必须是 `providers`，不能只写 `{"apiKey":"..."}`
401 / 鉴权失败	检查 `APIMASTER_API_KEY` 或 `auth.json` 中 Key 是否完整；新开终端使环境变量生效
404 / model not found	`models[].id` 须与模型广场的 model id 完全一致

核对清单

已安装 pi（pi --version 或 pi --help 可用）
~/.pi/agent/models.json（或 Windows 等价路径）顶层为 providers.apimaster
baseUrl = https://apimaster.ai/v1，api = openai-completions
已设置 APIMASTER_API_KEY 或 auth.json 中的 apimaster 项
pi --list-models 能列出 apimaster 下 7 个文本模型