Pi - 火山方舟文档

Pi 是一款开源终端编程 Agent，通过统一 LLM API 兼容 OpenAI、Anthropic、Google 等多家协议。方舟 Coding Plan 支持在 Pi 中使用，可参考本文进行配置及使用。更多详情请参见 Pi 官方文档。

核心配置#

接入工具的核心参数如下：

模型配置#

支持以下两种方式配置模型：

在工具配置文件中指定 Model Name，可实时切换模型。支持配置的 Model Name：

doubao-seed-evolving
doubao-seed-2.1-pro
doubao-seed-2.1-lite
doubao-seed-2.0-mini
minimax-m3
glm-5.3 (glm-latest)
glm-5.3-flash
deepseek-v4.1-flash
deepseek-v4-flash
deepseek-v4-pro
kimi-k2.8-preview
kimi-k3

在配置文件中指定模型为ark-code-latest。
通过开通管理页面选择或切换目标模型，切换模型后 3-5 分钟即可生效。
支持 Auto 模式，通过「效果 + 速度」双维度智能算法自动选择模型。

Base URL#

不同的工具配置的 Base URL 根据兼容的协议会有不同：

兼容 Anthropic 接口协议工具：https://ark.cn-beijing.volces.com/api/coding
兼容 OpenAI 接口协议工具：https://ark.cn-beijing.volces.com/api/coding/v3

API Key#

获取 API Key

一、安装 Pi#

前提条件：安装 Node.js 20 或更新版本。

在命令行界面，执行以下命令安装 Pi。

1
2
3
4
5# 方式 1：npm 全局安装
npm install -g @earendil-works/pi-coding-agent

# 方式 2：官方一键脚本
curl -fsSL https://pi.dev/install.sh | sh

安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功。

1pi --version

需先额外安装 Git for Windows，Pi 依赖其提供的 bash.exe 执行 ! / !! shell 命令；官方 curl 一键脚本在 Windows 上不支持。

通过 npm 全局安装：

1npm install -g @earendil-works/pi-coding-agent

安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功。

1pi --version

二、配置 Pi#

方式 1：自动化助手（推荐）#

ArkCLI Helper 是一个编码工具助手，支持快速配置选择的工具接入 Coding Plan。安装并运行该助手，根据界面提示操作可自动完成工具配置，降低手动配置的时间成本和出错风险。

安装 Ark CLI。

1
2
3
4
5# 1. 通过 NPM 安装
npm install -g @volcengine/ark-cli@latest

# 2. 验证安装
arkcli --version

登录 Ark CLI。
Bash
```
1arkcli auth login
```
根据界面提示选择登录方式。若之前已登录过 arkcli，会沿用上次选择的配置；如需重新选择，请先执行 arkcli config reset 后再运行 arkcli auth login。首次登录时，按提示完成以下配置：
1. 选择项目（Project）：可按需选择，或默认选择账号全部资源。
2. 选择消费模式（Type）：选择 coding-plan。
运行 ArkCLI Helper，根据界面提示完成 Pi 的配置。
1. 在命令行界面输入 arkcli helper 命令，启动 ArkCLI Helper。
2. 选择要配置的 Plan profile：选择 coding-plan_cn-beijing_personal (Coding Plan)。
3. 选择默认 model：按需选择。
4. 选择要配置的 AI Agent：Pi。

完成上述操作后，将自动完成 Pi 的基础配置，无需手动安装。

方式 2：手动配置#

关注的配置信息如下：
- <ARK_API_KEY>：替换为您自己的 API Key。
- model：更新为需要使用的模型信息。

创建并编辑 ~/.pi/agent/models.json 文件。如目录不存在，先创建后再编辑。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89{
  "providers": {
    "coding-plan": {
      "api": "openai-completions",
      "apiKey": "<ARK_API_KEY>",
      "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3",
      "models": [
        {
          "id": "ark-code-latest"
        },
        {
          "contextWindow": 1048576,
          "id": "doubao-seed-evolving",
          "input": ["text", "image"],
          "maxTokens": 256000
        },
        {
          "contextWindow": 1048576,
          "id": "doubao-seed-2.1-pro",
          "input": ["text", "image"],
          "maxTokens": 256000
        },
        {
          "contextWindow": 1048576,
          "id": "doubao-seed-2.1-lite",
          "input": ["text", "image"],
          "maxTokens": 256000
        },
        {
          "contextWindow": 262144,
          "id": "doubao-seed-2.0-mini",
          "input": ["text", "image"],
          "maxTokens": 128000
        },
        {
          "contextWindow": 1048576,
          "id": "glm-5.3",
          "input": ["text"],
          "maxTokens": 128000
        },
        {
          "contextWindow": 1048576,
          "id": "glm-5.3-flash",
          "input": ["text", "image"],
          "maxTokens": 128000
        },
        {
          "contextWindow": 1048576,
          "id": "deepseek-v4-pro",
          "input": ["text"],
          "maxTokens": 393216
        },
        {
          "contextWindow": 1048576,
          "id": "deepseek-v4.1-flash",
          "input": ["text", "image"],
          "maxTokens": 393216
        },
        {
          "contextWindow": 1048576,
          "id": "deepseek-v4-flash",
          "input": ["text"],
          "maxTokens": 393216
        },
        {
          "contextWindow": 1048576,
          "id": "glm-latest",
          "input": ["text"],
          "maxTokens": 128000
        },
        {
          "contextWindow": 1048576,
          "id": "kimi-k2.8-preview",
          "input": ["text", "image"],
          "maxTokens": 1048576
        },
        {
          "contextWindow": 1048576,
          "id": "kimi-k3",
          "input": ["text", "image"],
          "maxTokens": 65536
        },
        {
          "id": "minimax-m3"
        }
      ]
    }
  }
}

三、使用 Pi#

进入项目目录并启动 Pi：
Bash
```
1pi
```
在 Pi 交互界面执行 /model，可选择切换刚才配置的 provider 和模型。
发送任意问题验证连通性，例如：
```
简单介绍一下当前目录的文件结构。
```
若返回内容正常，说明 Coding Plan 已成功接入。

更多 Pi 使用教程请参见 Pi 官方文档。

常见问题#

错误码#

在编程工具中使用 Coding Plan 套餐时可能会遇到报错，您可以根据错误信息查看对应的报错场景并定位问题，具体可参考错误码。