Pi Agent

Pi 是一个命令行编码 agent（带 read / bash / edit / write 工具和会话管理）。它内置了一批供应商，但本站属于自定义端点，需要自己写一个 models.json——这页就讲怎么写。

安装

bash

# 全局安装 Pi Agent
# --ignore-scripts 禁用依赖包的生命周期脚本，提高安装安全性
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

没有 Node.js 环境先看 Node.js 环境安装。

配置文件位置

Pi 的自定义模型全部写在 models.json 里：

平台	路径
Linux / macOS	`~/.pi/agent/models.json`
Windows	`%USERPROFILE%\.pi\agent\models.json`

文件默认不存在，自己新建。目录位置可以用环境变量 PI_CODING_AGENT_DIR 改掉。

不用重启

改完 models.json 后在 Pi 里输入 /model 就会重新加载，不需要退出重开。

配置方式一：Claude 原生格式（推荐）

本站支持 Claude 的 Messages API，用这种方式接 Claude 系列模型最省事，思考（thinking）等特性也齐全。

json

{
  "providers": {
    "wow3": {
      "name": "WOW3",
      "baseUrl": "https://api.wow3.top",
      "api": "anthropic-messages",
      "apiKey": "$WOW3_API_KEY",
      "models": [
        {
          "id": "claude-opus-5",
          "name": "Opus 5",
          "reasoning": true,
          "contextWindow": 200000,
          "maxTokens": 64000
        },
        {
          "id": "claude-sonnet-5",
          "name": "Sonnet 5",
          "reasoning": true,
          "contextWindow": 200000,
          "maxTokens": 64000
        }
      ]
    }
  }
}

baseUrl 不要带 /v1

anthropic-messages 会自己拼上 /v1/messages。写成 https://api.wow3.top/v1 会变成 /v1/v1/messages，直接 404。

然后设好环境变量：

bash

# Linux / macOS，建议写进 ~/.bashrc 或 ~/.zshrc
export WOW3_API_KEY=sk-你的key

powershell

# Windows PowerShell，永久生效
[Environment]::SetEnvironmentVariable('WOW3_API_KEY','sk-你的key','User')

Key 在控制台 → 令牌管理创建。

配置方式二：OpenAI 兼容格式

想用非 Claude 的模型（比如 GPT 系列），走 OpenAI 兼容格式：

json

{
  "providers": {
    "wow3-openai": {
      "name": "WOW3 (OpenAI 兼容)",
      "baseUrl": "https://api.wow3.top/v1",
      "api": "openai-completions",
      "apiKey": "$WOW3_API_KEY",
      "models": [
        { "id": "gpt-5.4", "name": "GPT-5.4", "contextWindow": 400000 }
      ]
    }
  }
}

这里的 baseUrl 要带 /v1

openai-completions 拼的是 /chat/completions，所以 baseUrl 必须是 https://api.wow3.top/v1。和方式一正好相反，这是最容易配错的一个点。

两个 provider 可以同时写在一个文件里，providers 下并列即可，Pi 会把两边的模型都列出来。

字段说明

provider 层

字段	必填	说明
`baseUrl`	是	端点地址，注意上面说的 `/v1` 差异
`api`	是	协议类型。本站可用 `anthropic-messages`、`openai-completions`、`openai-responses`、`google-generative-ai`
`apiKey`	是	你的 key，写法见下
`name`	否	显示名，只影响界面
`headers`	否	额外请求头，值同样支持变量插值
`models`	否	模型列表。同 ID 会替换该 provider 上的同名模型
`modelOverrides`	否	只改已有模型的元数据，不替换整个列表

providers 下面那层的键名（例子里的 wow3）是你自己起的 provider ID，随便取，只要文件里不重复。

model 层

id 是唯一必填项，其余都可省：

字段	说明
`id`	模型名，必须和本站模型广场里的名字一致
`name`	显示名
`reasoning`	是否支持思考。Claude / GPT 的推理模型填 `true`
`contextWindow`	上下文窗口 token 数，Pi 用它判断何时压缩上下文
`maxTokens`	单次最大输出 token
`input`	支持的输入类型，可选 `"text"`、`"image"`。要传图就写 `["text", "image"]`
`baseUrl`	模型级会覆盖 provider 级，个别模型走不同地址时用
`cost`	价格，用于统计花费，单位是每百万 token 的美元数
`promptCache`	声明缓存保留秒数，如 `{ "short": 300, "long": 3600 }`
`headers`	该模型专用的请求头

cost 四个子字段都必填：input、output、cacheRead、cacheWrite。不填 cost 的话 Pi 算不出花费，但不影响使用——反正准确账目看使用日志。

API Key 的三种写法

写法	例子	说明
环境变量	`"$WOW3_API_KEY"` 或 `"${WOW3_API_KEY}"`	推荐，key 不落在配置文件里
执行命令取值	`"!security find-generic-password -ws wow3"`	从密码管理器取，每次请求时执行，Pi 不缓存结果
直接写死	`"sk-xxxx"`	图省事，但配置文件一旦被同步或分享就泄漏

要写字面量的 $ 用 $$，开头要写字面量的 ! 用 $!。

别把 models.json 提交到 Git

直接写死 key 的话这个文件就是明文凭据。配合令牌管理里的 IP 白名单和额度上限，能把泄漏后的损失限住。

Pi 找 key 的优先级是：命令行 --api-key → auth.json 里存的 → models.json 里的 apiKey → 供应商的环境变量。

选模型和用起来

配好后启动 pi，然后：

操作	作用
`/model`	搜索并切换模型，同时重新加载 `models.json`
在 `/model` 里按 `Ctrl+S`	把当前模型存为新会话的默认
`Ctrl+P`	快速轮换模型
`/thinking`	调思考强度，按 `Ctrl+S` 保存为启动默认
`/scoped-models`	配置 `Ctrl+P` 轮换的范围

会话会记录模型和思考强度的改动，恢复会话时一并还原，不会影响新会话的默认值。

进阶：只改元数据

模型已经能用，只是某个参数不对（比如上下文窗口标小了），不用重写整个 models 列表，用 modelOverrides：

json

{
  "providers": {
    "wow3": {
      "baseUrl": "https://api.wow3.top",
      "api": "anthropic-messages",
      "apiKey": "$WOW3_API_KEY",
      "modelOverrides": {
        "claude-opus-5": {
          "contextWindow": 200000,
          "promptCache": { "short": 300, "long": 3600 }
        }
      }
    }
  }
}

只给已有 provider 补 baseUrl 或 headers 时，它内置的模型列表会保留。写不存在的模型 ID 会被静默忽略，不报错。

常见问题

/model 里看不到我配的模型 Pi 只显示凭据能解析出来的模型。模型能从 models.json 加载，但 key 取不到就不会出现在列表里。检查环境变量是不是在启动 Pi 的那个终端里生效了。

换了个终端就不行了 key 来自环境变量而不是 auth.json。环境变量必须在启动 Pi 的进程里存在——写进 ~/.bashrc / ~/.zshrc 再开新终端。

报 404 八成是 baseUrl 的 /v1 加错了。anthropic-messages 不带，openai-completions 要带。

报 401 key 不对，或者被令牌管理里的 IP 白名单挡了。先到操练场用同一把 key 测一次，确认 key 本身没问题。

提示模型不存在id 必须和模型广场里的名字完全一致。另外确认令牌所在分组包含这个模型，且没被令牌的「模型限制列表」挡掉。

改了配置没生效 输入 /model 触发重载。语法错误时 Pi 会直接提示 models.json error，照提示改。

JSON 写错了 整个文件解析失败会导致所有自定义模型都不加载。逗号、引号是最常见的问题，可以先用站内工具箱的 JSON 格式化校验一遍。

思考模式不起作用 模型定义里要有 "reasoning": true，然后用 /thinking 选强度。

Pi Agent ​

安装 ​

配置文件位置 ​

配置方式一：Claude 原生格式（推荐） ​

配置方式二：OpenAI 兼容格式 ​

字段说明 ​

provider 层 ​

model 层 ​

API Key 的三种写法 ​

选模型和用起来 ​

进阶：只改元数据 ​

常见问题 ​

Pi Agent

安装

配置文件位置

配置方式一：Claude 原生格式（推荐）

配置方式二：OpenAI 兼容格式

字段说明

provider 层

model 层

API Key 的三种写法

选模型和用起来

进阶：只改元数据

常见问题