# pi 接入指南

https://modelportal.ai/docs/integrations/pi?lang=zh

> 极简的开源终端编程代理，自定义端点写在 models.json 里。

## 适用场景

适合想要一个小而可扩展的终端编程代理的用户。pi 把自定义端点写在 `~/.pi/agent/models.json`，`api` 填 `openai-completions` 即走 chat/completions 协议。

## 使用建议

编程代理一次任务会连续发出很多请求，输入也长，建议选上下文较长、支持工具调用的模型，并给密钥设置每日消费上限。

## 推理档位

发不发推理档位取决于你在配置里给模型设的推理参数（Chat 接口的 `reasoning_effort`）。平台按模型实际走的线路能接受的档位处理：上游不收请求的档位时改用更高一档，高过最高档时取最高档；模型不能关闭思考时，要求关闭会返回 400 `unsupported_parameter`。每个模型的对照表见[模型目录](/catalog)里该模型的「推理档位」一节；发生改写的调用，用量明细里会显示「推理档位改写」。

## 连不通时检查

1. `baseUrl` 填 `https://modelportal.ai/v1`，不要多写 `/chat/completions`。
2. 密钥以 `mp-`（早期的为 `key_`）开头且没有被暂停或撤销，错误码 `invalid_api_key` 表示密钥不可用。
3. 模型 ID 与[模型目录](/catalog)一致，并且在这把密钥的可用模型里。
4. 余额不足会返回 `insufficient_balance`，更多错误见[常见错误](/docs/errors)。

## 配置步骤

1. 安装：npm install -g --ignore-scripts @earendil-works/pi-coding-agent（需要 Node.js 22.19 以上）。
2. 把下面这段写进 ~/.pi/agent/models.json。
3. 在项目目录执行 pi --model modelportal/{{model}}，或在会话里用 /model 切换。

## 配置参数

- API 地址：`https://modelportal.ai/v1`
- API 密钥：`YOUR_API_KEY`
- 模型：`MODEL_ID`

> 这份配置按 pi 官方文档整理，平台尚未实测，遇到问题请提交工单并附上请求 ID。

```json
{
  "providers": {
    "modelportal": {
      "name": "ModelPortal.AI",
      "baseUrl": "https://modelportal.ai/v1",
      "api": "openai-completions",
      "apiKey": "YOUR_API_KEY",
      "models": [{ "id": "MODEL_ID" }]
    }
  }
}
```

## 常见问题

### 上下文长度显示不对怎么办？

pi 默认把自定义模型当作 128K 上下文、16K 输出。模型实际更小或更大时，在 models 里给它加 contextWindow 与 maxTokens。

### 改了 models.json 要重启吗？

不用，在会话里打开 /model 会重新读取。