---
description: "将 Pi Coding Agent 接入在问 OpenAI Responses 协议。"
---

# 接入 Pi

> Pi（Pi Coding Agent）是开源终端编程 Agent，类似于 Claude Code / Codex，通过 npm 一键安装：
>
> ```bash
> npm install -g --ignore-scripts @earendil-works/pi-coding-agent
> ```

## 配置步骤

### 1. 保存 API Key 到 `~/.pi/agent/auth.json`

```json
{
  "zaiwenai": {
    "type": "api_key",
    "key": "你的在问APIKEY"
  }
}
```

如果该文件中已经有其他供应商的凭据，请先备份，再手动合并或替换。

也可以使用以下辅助命令自动备份并写入。macOS、Linux 或 WSL：

```bash
PI_DIR="$HOME/.pi/agent"
mkdir -p "$PI_DIR"
AUTH_PATH="$PI_DIR/auth.json"
[ ! -f "$AUTH_PATH" ] || cp "$AUTH_PATH" "$AUTH_PATH.bak"
printf '%s\n' '{"zaiwenai":{"type":"api_key","key":"你的在问APIKEY"}}' > "$AUTH_PATH"
```

Windows PowerShell：

```powershell
$piDir = Join-Path $HOME ".pi\agent"
New-Item -ItemType Directory -Force -Path $piDir | Out-Null
$authPath = Join-Path $piDir "auth.json"
if (Test-Path $authPath) { Copy-Item $authPath "$authPath.bak" -Force }
@{ zaiwenai = @{ type = "api_key"; key = "你的在问APIKEY" } } | ConvertTo-Json -Depth 5 | Set-Content -Encoding utf8 $authPath
```

### 2. 配置模型到 `~/.pi/agent/models.json`

打开 `~/.pi/agent/models.json`，文件不存在则创建，写入以下内容：

```json
{
  "providers": {
    "zaiwenai": {
      "baseUrl": "https://oneapi.zaiwenai.com/v1",
      "api": "openai-responses",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": true
      },
      "models": [
        {
          "id": "gpt-5.6-terra",
          "name": "GPT-5.6-Terra",
          "reasoning": true,
          "thinkingLevelMap": {
            "off": "none",
            "minimal": null,
            "low": "low",
            "medium": "medium",
            "high": "high",
            "xhigh": "xhigh",
            "max": "max"
          },
          "input": ["text", "image"],
          "contextWindow": 262144,
          "maxTokens": 128000
        },
        {
          "id": "gpt-5.6-luna",
          "name": "GPT-5.6-Luna",
          "reasoning": true,
          "thinkingLevelMap": {
            "off": "none",
            "minimal": null,
            "low": "low",
            "medium": "medium",
            "high": "high",
            "xhigh": "xhigh",
            "max": "max"
          },
          "input": ["text", "image"],
          "contextWindow": 262144,
          "maxTokens": 128000
        }
      ]
    }
  }
}
```

如果该文件中已有其他自定义供应商配置（如 Ollama），请先备份，再手动合并 `providers` 节点。

### 3. 验证

在项目目录启动 Pi，按 `/model` 选择 `zaiwenai / GPT-5.6-Terra` 即可开始使用：

```bash
cd /path/to/project
pi
```

::: tip 配置说明
- `api = "openai-responses"`：在问平台提供 OpenAI Responses 协议（`/v1/responses`），与 Codex 的 `wire_api = "responses"` 一致，能正确下发推理强度参数
- `contextWindow = 262144`：上下文窗口配置为 256K。一是低于 OpenAI 短上下文计费阈值（272K），避免按长上下文倍率整体计费；二是让 pi 的自动压缩更早触发（接近 272K 上限才压缩，容易频繁截断或压缩失败）
- 推理强度：两个模型按 OpenAI 官方实际支持全档暴露——`off`（关闭，`effort=none`）/ `low` / `medium` / `high` / `xhigh` / `max` 全部直通；`minimal` 官方仅原版 GPT-5 支持（gpt-5.1+ 不支持），故隐藏
- 默认思考档位为 `medium`（OpenAI 官方默认值，同时是 Pi 的 `DEFAULT_THINKING_LEVEL`）。档位切换：交互模式按 `Shift+Tab` 循环切换，或用 `/model` 选择器；手动切换的档位会持久化为 `settings.json` 的全局 `defaultThinkingLevel`（不分模型）
- 辅助命令会在覆盖前将已有文件备份为 `.bak`
:::

## 推荐扩展

以下为 Pi 社区常用扩展，按需安装即可。全部通过 `pi install` 一键安装：

### 一键安装（全部）

```bash
pi install npm:pi-subagents
pi install npm:pi-exit-alias
pi install npm:@narumitw/pi-goal
pi install npm:@monotykamary/pi-retry
```

### 按需选择

| 扩展 | 安装命令 | 说明 |
| --- | --- | --- |
| Subagents 多智能体协作 | `pi install npm:pi-subagents` | 单智能体委派与脚本化多智能体工作流 |
| Exit 别名 | `pi install npm:pi-exit-alias` | 为 `/quit` 增加 `/exit` 与裸 `exit` 别名 |
| Goal 单目标自主执行 | `pi install npm:@narumitw/pi-goal` | 单目标自主完成的 `/goal` 扩展 |
| Retry 自动重试 | `pi install npm:@monotykamary/pi-retry` | 自动处理 400/413 与网络连接错误的重试套件 |

### 验证与更新

```bash
# 查看已安装扩展
pi list

# 更新全部（本体 + 全部扩展）
pi update --all

# 更新单个扩展，例如
pi update npm:pi-subagents
```

### 联网搜索（内建 MCP，无需插件）

Pi 0.99 起原生支持 [MCP](https://modelcontextprotocol.io)，联网搜索不用再装 `pi-exa` 插件，直接配 Exa 官方 MCP 即可（免费档免 key，有限流）。

先升级到最新版：

```bash
pi update --all
```

然后写入 `~/.pi/agent/mcp.json`（文件不存在则创建，已存在则合并 `mcpServers` 节点）：

```json
{
  "mcpServers": {
    "exa": {
      "url": "https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa",
      "exposure": "direct"
    }
  }
}
```

macOS、Linux 或 WSL 一键写入（会备份已有文件）：

```bash
MCP_PATH="$HOME/.pi/agent/mcp.json"
[ ! -f "$MCP_PATH" ] || cp "$MCP_PATH" "$MCP_PATH.bak"
printf '%s\n' '{"mcpServers":{"exa":{"url":"https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa","exposure":"direct"}}}' > "$MCP_PATH"
```

Windows PowerShell：

```powershell
$piDir = Join-Path $HOME ".pi\agent"
New-Item -ItemType Directory -Force -Path $piDir | Out-Null
$mcpPath = Join-Path $piDir "mcp.json"
if (Test-Path $mcpPath) { Copy-Item $mcpPath "$mcpPath.bak" -Force }
@{ mcpServers = @{ exa = @{ url = "https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa"; exposure = "direct" } } } | ConvertTo-Json -Depth 5 | Set-Content -Encoding utf8 $mcpPath
```

生效与验证：

```bash
# 应显示 exa: connected, 3 tools
pi mcp list
```

然后在 Pi 里执行 `/reload`（或重开会话），模型即可直接调用 `mcp__exa__web_search_exa` 等工具。如之前装过旧的 `pi-exa` 插件，建议移除避免工具重复：

```bash
pi remove npm:pi-exa
```