Pi - 火山方舟文档

本文介绍如何配置方舟 Agent Plan 到 Pi 中使用。Pi 是一款开源终端编程 Agent，通过统一 LLM API 兼容 OpenAI、Anthropic、Google 等多家协议。更多详情请参见 Pi 官方文档。

一、前提条件#

您已按需订阅 Agent Plan 套餐。如未，请访问开通管理-Agent Plan 页面订阅套餐。
您已正确安装 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 是一个编码工具助手，支持快速配置选择的工具接入 Agent 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）：选择 agent-plan。
运行 ArkCLI Helper，根据界面提示完成 Pi 的配置。
1. 在命令行界面输入 arkcli helper 命令，启动 ArkCLI Helper。
2. 选择要配置的 Plan profile：agent-plan_cn-beijing_personal (Agent Plan)。
3. 选择默认 model：按需选择。
4. 选择要配置的 AI Agent：Pi。
  
  当前支持的 Harness 包括：AI Native 应用开发底座和Computer Use Agent，根据界面提示按需选择配置或者跳过。

完成上述操作后，将自动完成 Pi 的基础配置，并按选择结果自动安装对应的 Harness 工具，无需手动安装。

方式 2：手动配置#

下面详细介绍如何手动完成配置。

关注的配置信息如下：
- <ARK_API_KEY>：替换为您自己的专属 API Key。
- model：见支持模型及 Harness，需配置文本生成模型。

创建并编辑 ~/.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
90
91
92{
  "providers": {
    "agent-plan": {
      "api": "openai-completions",
      "apiKey": "<ARK_API_KEY>",
      "baseUrl": "https://ark.cn-beijing.volces.com/api/plan/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.1-flash",
          "input": ["text", "image"],
          "maxTokens": 393216
        },
        {
          "contextWindow": 1048576,
          "id": "deepseek-v4-pro",
          "input": ["text"],
          "maxTokens": 393216
        },
        {
          "contextWindow": 1048576,
          "id": "deepseek-v4-flash",
          "input": ["text"],
          "maxTokens": 393216
        },
        {
          "contextWindow": 1048576,
          "id": "kimi-k3",
          "input": ["text", "image"],
          "maxTokens": 128000
        },
        {
          "contextWindow": 1048576,
          "id": "kimi-k2.8-preview",
          "input": ["text", "image"],
          "maxTokens": 1048576
        },
        {
          "contextWindow": 1048576,
          "id": "glm-latest",
          "input": ["text"],
          "maxTokens": 128000
        },
        {
          "contextWindow": 1048576,
          "id": "minimax-m3",
          "input": ["text", "image"],
          "maxTokens": 131072
        }
      ]
    }
  }
}

三、启动并使用 Pi#

进入项目目录并启动 Pi：
Bash
```
1pi
```
在 Pi 交互界面执行 /model，可选择切换刚才配置的 provider 和模型。支持的模型可见支持模型及 Harness。

发送任意问题验证连通性，例如：
```
简单介绍一下当前目录的文件结构。
```
若返回内容正常，说明 Agent Plan 已成功接入。

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

其他操作#

切换模型#

Pi 支持两种切换方式：

配置方式	操作
交互切换	在 Pi 对话界面执行 `/model`，从下拉列表选择目标模型。
修改配置	编辑 `~/.pi/agent/models.json`，在对应 provider 的 `models` 数组中新增或调整模型条目，保存后执行 `/model` 触发重载。

添加图片生成/视频生成能力#

方舟 Agent Plan Medium 及以上套餐提供图片生成模型配额，Large 及以上套餐提供视频生成模型配额。Pi 的 models[].input 只声明输入模态（text / image），图片/视频生成需要通过工具调用或 MCP 接入。具体配置方法请参见接入视觉模型。