Pi

在 models.json 中配置自定义 Provider，将终端编程 Agent Pi 接入 CoffeeRouter。

接入前准备

  • 安装支持当前 Pi 版本的 Node.js。
  • 在 CoffeeRouter 创建独立 API Key，并确认目标模型 ID。
  • 准备 https://www.coffeerouter.ai/v1 作为 OpenAI Compatible Base URL。

配置步骤

1. 安装 Pi

当前官方 npm 包：

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

也可以使用官方安装脚本：

curl -fsSL https://pi.dev/install.sh | sh

2. 设置 API Key

Linux / macOS：

export COFFEEROUTER_API_KEY="sk-your-api-key"

Windows PowerShell：

$env:COFFEEROUTER_API_KEY="sk-your-api-key"

3. 创建模型配置

在 ~/.pi/agent/models.json 中添加 CoffeeRouter：

{
    "providers": {
        "coffeerouter": {
            "baseUrl": "https://www.coffeerouter.ai/v1",
            "api": "openai-completions",
            "apiKey": "$COFFEEROUTER_API_KEY",
            "models": [
                {
                    "id": "your-model-id",
                    "name": "CoffeeRouter Model",
                    "reasoning": false,
                    "input": ["text"],
                    "contextWindow": 128000,
                    "maxTokens": 8192
                }
            ]
        }
    }
}

模型能力字段必须按 CoffeeRouter 中的实际模型调整。不要为所有模型统一加入推理兼容参数。

4. 选择模型

启动 Pi，输入 /model 或按 Ctrl+L，选择 coffeerouter 和目标模型。models.json 会在打开模型选择器时重新加载。

验证接入

选择模型后发送一个简单的代码任务。如果 Pi 能正常流式输出并执行基础工具调用，即表示配置成功。

推理模型配置

使用当前 thinkingLevelMap

当前 Pi 已将旧的 compat.reasoningEffortMap 迁移为模型级 thinkingLevelMap。只有在确认目标模型接受相应推理等级时才添加，例如：

{
    "id": "your-reasoning-model-id",
    "reasoning": true,
    "thinkingLevelMap": {
        "minimal": "low",
        "low": "low",
        "medium": "medium",
        "high": "high",
        "xhigh": null
    }
}

不要沿用旧示例中的 thinkingFormat: "anthropic"；它不在当前 Pi 文档列出的 OpenAI Compatibility 格式中。

常见问题

Provider 或模型没有显示

确认文件路径为 ~/.pi/agent/models.json、JSON 格式正确，并且 COFFEEROUTER_API_KEY 已设置。没有可用认证时，模型可能已加载但不会在选择器中启用。

返回 401

重新设置 API Key，并从同一个 shell 启动 Pi。确认令牌没有过期、禁用或超出限制。

推理模型行为异常

先移除自定义 compat 和 thinkingLevelMap，确认普通调用正常，再依据具体模型协议逐项添加兼容参数。

旧的 Pi 配置还能使用吗

旧仓库名、旧 npm 包和 reasoningEffortMap 已过时。新文档应使用 earendil-works/pi、@earendil-works/pi-coding-agent 和模型级 thinkingLevelMap。

安全提示

  • 不要把真实 Key 写入文档、截图、会话记录或版本库。
  • Pi 的扩展和技能可以执行代码，安装第三方包前请审查来源和权限。
  • 建议为 Pi 使用独立 CoffeeRouter 令牌，并按需限制模型与额度。
  • Pi 会把提示词、必要代码上下文和工具调用数据发送到 CoffeeRouter。

官方资料