Pi

Pi 可以通过 models.json 接入 HiAPI。下面以 deepseek-v4.1-flash 为例，本教程已在 Mac 的 Pi 1.3.0 上验证；Windows 需要先安装 Git Bash（第 3 步）。

1. 安装 Node.js

按 Node.js 环境 安装 LTS、22.19 或以上版本，已有的跳过。装好后在终端运行下面两条命令，能看到版本号即可：

node --version
npm --version

Windows 的 PowerShell 里，后面的 npm / npx 命令写成 npm.cmd / npx.cmd。

2. 安装 Pi

在终端逐行运行：

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

显示 1.3.0 即可。Windows PowerShell 用 npm.cmd install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0 和 pi.cmd --version。

3. Windows 先安装 Git Bash（Mac 跳过）

1. 打开 Git for Windows 官方下载页，下载对应架构的安装器并运行。安装目录保留 C:\Program Files\Git，PATH 选推荐的 Git from the command line and also from 3rd-party software，点 Install → Finish。已经装过 Git Bash 可以跳过。
2. 关掉旧的 PowerShell，重新打开，确认 Bash 路径：

& 'C:\Program Files\Git\bin\bash.exe' --version

看到 GNU bash 版本即可。装在其他目录时，在资源管理器里找到实际的 bin\bash.exe，把命令里的路径换掉。

3. Pi 一般会自动找到 Git Bash。只有启动后仍提示找不到 Bash 时，才用记事本打开 %USERPROFILE%\.pi\agent\settings.json（已有文件先备份），新增或更新 shellPath 字段，其他字段保留：

{
  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
}

路径填实际安装位置，反斜杠写两次。另存为 选「所有文件」、UTF-8、文件名 settings.json，保存后重开 Pi。

4. 获取 HiAPI API Key

按 获取 API Key 准备好 Key，点密钥行旁的复制图标，复制完整的 HiAPI API Key，第 7 步要用。

5. 打开模型配置文件

Mac 在终端逐行运行（已有 models.json 会先自动备份）：

mkdir -p "$HOME/.pi/agent"
if [ -f "$HOME/.pi/agent/models.json" ]; then cp "$HOME/.pi/agent/models.json" "$HOME/.pi/agent/models.json.bak-$(date +%Y%m%d-%H%M%S)"; fi
nano "$HOME/.pi/agent/models.json"

Windows PowerShell：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.pi\agent"
if (Test-Path "$env:USERPROFILE\.pi\agent\models.json") { Copy-Item "$env:USERPROFILE\.pi\agent\models.json" "$env:USERPROFILE\.pi\agent\models.json.bak-$(Get-Date -Format yyyyMMdd-HHmmss)" }
notepad "$env:USERPROFILE\.pi\agent\models.json"

如果设置过 PI_CODING_AGENT_DIR，编辑那个目录下的 models.json；没设置过就用上面的默认目录。

6. 填入 DeepSeek 配置并保存

1. 把下面的内容写进 models.json（不是在终端里逐行运行）。新文件直接粘贴全部内容；已有文件只把 hiapi-deepseek 合并进原来的 providers，保留其他供应商，最外层只留一个 providers。

{
  "providers": {
    "hiapi-deepseek": {
      "baseUrl": "https://api.hiapi.ai/v1",
      "api": "openai-completions",
      "apiKey": "${HIAPI_API_KEY}",
      "models": [
        {
          "id": "deepseek-v4.1-flash",
          "name": "DeepSeek V4.1 Flash (HiAPI)",
          "api": "openai-completions",
          "reasoning": true,
          "input": [
            "text"
          ],
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "thinkingLevelMap": {
            "minimal": null,
            "low": "low",
            "medium": null,
            "high": "high",
            "xhigh": null,
            "max": "max"
          },
          "compat": {
            "thinkingFormat": "deepseek",
            "maxTokensField": "max_tokens",
            "supportsReasoningEffort": true
          }
        }
      ]
    }
  }
}

2. apiKey 里的 ${HIAPI_API_KEY} 是 Pi 读取环境变量的写法，保持原样，下一步再设置 Key。JSON 用英文双引号和逗号，最后一项后面不加逗号，不写注释。

①在 providers 中新增完整 hiapi-deepseek 对象；②apiKey 保留环境变量占位符。图中已有的其他供应商可以保留。

3. 保存：Mac nano 按 Ctrl+O → 回车 → Ctrl+X；Windows 记事本 另存为 选「所有文件」、UTF-8，文件名必须是 models.json，不要存成 .json.txt。

7. 设置 API Key 并启动 Pi

1. Mac 在准备启动 Pi 的同一个终端里运行（把 YOUR_HIAPI_API_KEY 换成你的 HiAPI API Key，保留引号）：

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"

2. 进入项目文件夹启动 Pi，也可以新建一个空目录：

mkdir -p "$HOME/hiapi-project"
cd "$HOME/hiapi-project"
pi

Windows PowerShell：

$env:HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
New-Item -ItemType Directory -Force "$env:USERPROFILE\hiapi-project"
Set-Location "$env:USERPROFILE\hiapi-project"
pi.cmd

3. 环境变量只对当前终端有效，关掉终端后要重新设置。用 HiAPI 不需要在 Pi 里执行 /login。

8. 选择模型并验证

1. 在 Pi 输入框输入 /model 回车，搜索 hiapi，用方向键选中 DeepSeek V4.1 Flash (HiAPI)（provider 为 hiapi-deepseek），按 Enter。

①用方向键移到 DeepSeek 这一行；②按 Enter 选中。

2. 输入 /thinking 回车，在 off / low / high / max 里选一档按 Enter，第一次用可以选 low。

①在 off、low、high、max 中选一档；②按 Enter 应用到当前会话。

3. Enter 只对当前会话生效；想让以后的新会话也默认用这一档，按菜单提示 Ctrl+S 保存。
4. 发送「你好，用一句话介绍你自己。」，能正常回复就说明接入成功。在 HiAPI 控制台的 调用记录 里能看到这次请求，就说明走的是 HiAPI。

常见问题

下面只列 Pi 特有的问题，401、404、429 等通用报错见 通用报错。