配置 pi agent 自定义模型提供商

最近在折腾 pi 这个 AI 编码助手（@earendil-works/pi-coding-agent）——一个类似 Claude Code、Codex 的命令行工具，支持多种 AI 模型后端，可以用自然语言驱动写代码、执行命令。

刚好手头有一些第三方 API 额度，所以记录一下怎么给它配一个自定义（OpenAI 兼容）的模型提供商。

免责声明：本文涉及的 API Key 等敏感信息均已脱敏处理。

pi 的架构

pi 的模型管理分两层：

• 内置 provider — openai、anthropic、deepseek、openrouter、google 等几十个，开箱即用
• 自定义 provider — 通过 ~/.pi/agent/models.json 配置，支持 OpenAI 兼容接口

自定义配置的 schema 官方文档在 pi.dev/models。

配置步骤

1. 准备 API Key

把 API Key 写入环境变量（推荐，避免明文写在配置文件中）：

1
2

# ~/.zshrc
export KRILL_API_KEY=your_api_key_here

2. 创建 models.json

pi 的配置目录在 ~/.pi/agent/，创建 models.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
  "providers": {
    "krill": {
      "name": "Krill API",
      "baseUrl": "https://api.krill-ai.com/codex/v1",
      "api": "openai-completions",
      "apiKey": "$KRILL_API_KEY",
      "models": [
        { "id": "deepseek-v4-flash", "contextWindow": 128000, "maxTokens": 16384, "reasoning": true },
        { "id": "deepseek-v4-pro", "contextWindow": 128000, "maxTokens": 16384, "reasoning": true },
        { "id": "gpt-5.4", "contextWindow": 256000, "maxTokens": 32768 },
        { "id": "gpt-5.5", "contextWindow": 256000, "maxTokens": 32768 },
        { "id": "kimi-k2.7-code", "contextWindow": 128000, "maxTokens": 16384, "reasoning": true },
        { "id": "gemini-3.1-pro-preview", "contextWindow": 1048576, "maxTokens": 32768 },
        { "id": "qwen3.7-plus", "contextWindow": 128000, "maxTokens": 16384 },
        { "id": "grok-4.5", "contextWindow": 131072, "maxTokens": 16384 }
      ]
    }
  }
}

关键字段说明：

3. 验证配置

1
2
3
4
5

# 列出所有模型
pi --list-models

# 输出中会看到 krill provider 和配置的模型列表
# Auth 列显示 yes 表示 API Key 已就绪

测试调用：

1

pi --provider krill --model deepseek-v4-flash --print "hello"

原理

pi 的模型加载流程：

1. 启动时读取 ~/.pi/agent/models.json
2. 合并内置 provider 和自定义 provider
3. 根据 apiKey 字段中的 $ENV_VAR 读取环境变量
4. 用 openai-completions API 模块创建 OpenAI 客户端
5. 请求时 baseURL 指向 model.baseUrl，model 参数传 model.id

所以只要是 OpenAI 兼容的接口——无论是 Krill、OpenRouter、还是本地跑的 vLLM、Ollama——都可以用同样的方式接入。

一点经验

• API Key 别写死在 JSON 里 — 用 $ENV_VAR 引用环境变量，安全且方便切换
• cost 字段不填也行 — 默认 0，不影响使用
• contextWindow 和 maxTokens — 按模型的实际能力填，不影响调用但对规划有帮助
• reasoning: true 开启思维链，适合 deepseek、kimi 等支持推理的模型
• 如果遇到 insufficient balance — 那是 API 提供商侧欠费了，检查账户余额就行

小结

pi 的自定义 provider 机制设计得很灵活，一个 models.json 就能接任意 OpenAI 兼容接口。这种”配置驱动”的方式比硬编码更干净，改模型只要改配置文件就行，不用动工具本身。

• ← Previous Post
• Next Post →