> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capriole.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pi

> 配置 Pi 使用 Capriole AI。

## Pi 是什么

Pi 是面向终端的开源极简编程代理。它从 `models.json` 读取自定义端点，每个模型都可以使用不同的 API 协议。这套配置把 Capriole AI 作为一个提供商添加到该文件中。

## 前置条件

开始前请确保你已经拥有以下内容。

* Capriole AI 账户，可在[此处注册](https://capriole.ai)
* Capriole AI API Key，可在[此处获取](https://capriole.ai?view=api)

## 安装

使用官方安装脚本安装 Pi。

```bash theme={null}
curl -fsSL https://pi.dev/install.sh | sh
```

也可以使用 npm 安装（需要 Node.js 22.19 或更高版本）。

```bash theme={null}
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
```

## 配置

### 模型验证

使用下方配置，Pi 1.3.0 经 Capriole AI 调用“支持的模型”一节中的每个模型，都通过了文件读取、文件写入和最终答案检查。

创建或更新 `~/.pi/agent/models.json`。

```json theme={null}
{
  "providers": {
    "capriole": {
      "name": "Capriole AI",
      "baseUrl": "https://api.caprioletech.com/v1",
      "api": "openai-completions",
      "apiKey": "$CAPRIOLE_AI_API_KEY",
      "authHeader": true,
      "models": [
        {
          "id": "openai-latest",
          "contextWindow": 1050000,
          "maxTokens": 128000,
          "reasoning": true,
          "api": "openai-responses"
        },
        {
          "id": "openai/gpt-6.1-sol",
          "contextWindow": 1050000,
          "maxTokens": 128000,
          "reasoning": true,
          "api": "openai-responses"
        },
        {
          "id": "claude-latest",
          "contextWindow": 1000000,
          "maxTokens": 128000,
          "reasoning": true,
          "api": "anthropic-messages",
          "baseUrl": "https://api.caprioletech.com",
          "compat": { "forceAdaptiveThinking": true }
        },
        {
          "id": "claude-opus-5-5",
          "contextWindow": 1000000,
          "maxTokens": 128000,
          "reasoning": true,
          "api": "anthropic-messages",
          "baseUrl": "https://api.caprioletech.com",
          "compat": { "forceAdaptiveThinking": true }
        },
        {
          "id": "zai/glm-5.3-flash",
          "contextWindow": 1000000,
          "maxTokens": 128000,
          "reasoning": true
        },
        {
          "id": "moonshot/kimi-k3",
          "contextWindow": 1048576,
          "maxTokens": 131072,
          "reasoning": true
        },
        {
          "id": "xai/grok-4.7",
          "contextWindow": 500000,
          "maxTokens": 128000,
          "reasoning": true
        }
      ]
    }
  }
}
```

然后在 `~/.pi/agent/settings.json` 中把 Capriole AI 设为默认。

```json theme={null}
{
  "defaultProvider": "capriole",
  "defaultModel": "claude-latest"
}
```

各项设置的作用如下。

* 提供商的 `api` 是 `openai-completions`，因此 Grok、GLM 和 Kimi 使用 Chat Completions。GPT 模型用 `openai-responses` 覆盖它，Claude 模型则用 `anthropic-messages` 和不含 `/v1` 的 `baseUrl` 覆盖它。
* `$CAPRIOLE_AI_API_KEY` 从环境变量读取你的 API Key。
* `authHeader: true` 让每种协议都以 Bearer Token 形式发送 Key。没有它时，Claude 模型会在 `x-api-key` 请求头中发送 Key，而 Capriole AI 不接受这种方式。
* `forceAdaptiveThinking` 让 Claude 模型使用自适应思考。Opus 5.5 会拒绝固定的思考预算。
* `contextWindow` 和 `maxTokens` 告诉 Pi 每个模型的限制。

## 运行 Pi

设置 API Key，然后在项目目录中启动 Pi。

```bash theme={null}
export CAPRIOLE_AI_API_KEY="YOUR_CAPRIOLE_AI_API_KEY"
pi
```

使用 `/model` 切换模型。如需非交互式运行，请使用 print 模式。

```bash theme={null}
pi -p --model xai/grok-4.7 "Explain this repository."
```

## 支持的模型

| 模型 | 模型 ID | 协议 |
| - | - | - |
| OpenAI latest | `openai-latest` | Responses |
| GPT-6.1 Sol | `openai/gpt-6.1-sol` | Responses |
| Claude latest | `claude-latest` | Anthropic Messages |
| Opus 5.5 | `claude-opus-5-5` | Anthropic Messages |
| Grok 4.7 | `xai/grok-4.7` | Chat Completions |
| GLM 5.3 Flash | `zai/glm-5.3-flash` | Chat Completions |
| Kimi K3 | `moonshot/kimi-k3` | Chat Completions |

`openai-latest` 和 `claude-latest` 始终指向各自系列中我们最新的旗舰模型。

## 故障排除

### 为什么 Capriole AI 模型没有出现在 `/model` 中

Pi 在能解析自定义模型的 API Key 之前会隐藏该模型。启动 Pi 前，请在同一个 Shell 中导出 `CAPRIOLE_AI_API_KEY`。

### 为什么 Pi 返回身份验证错误

确认提供商设置了 `"authHeader": true`。

### 为什么 Opus 5.5 因 `requires adaptive thinking` 失败

确认 Claude 模型条目包含 `"compat": { "forceAdaptiveThinking": true }`。

### 为什么 Claude 请求因 `Unsupported Claude Messages model` 失败

使用 `anthropic-messages` 的 Claude 模型需要不带前缀的 Claude ID，例如 `claude-opus-5-5`。带 `anthropic/` 前缀的 ID 用于 Chat Completions。

## 说明

* 如需添加其他 Capriole AI 模型，请复制同一系列中某个模型的条目并修改 ID。`GET https://api.caprioletech.com/v1/models` 会列出所有模型 ID。
* 官方参考资料包括 [Pi](https://pi.dev)、[Pi 文档](https://pi.dev/docs)、[选择模型](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)和 [Pi 配置](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/configuration.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.