文档中心

火山方舟

接入 AI 工具

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

一、前提条件

您已按需订阅 Agent Plan 套餐。如未，请访问开通管理-Agent Plan 页面订阅套餐。

您已正确安装 Pi，如未，请参见以下操作完成软件安装。

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

macOS/Linux
Windows

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

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

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

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

pi --version

二、配置 Pi

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

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

注意

ArkCLI Helper 是基于 Ark Helper 升级演进的工具配置服务，相关能力将持续在 ArkCLI Helper 上迭代更新。建议优先使用 ArkCLI Helper 完成工具配置。

ArkCLI Helper 支持 macOS、Linux、Windows 系统。

安装 Ark CLI。

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

# 2. 验证安装
arkcli --version

arkcli auth login

根据界面提示选择登录方式。若之前已登录过 arkcli，会沿用上次选择的配置；如需重新选择，请先执行 arkcli config reset 后再运行 arkcli auth login。首次登录时，按提示完成以下配置：

选择项目（Project）：可按需选择，或默认选择账号全部资源。

选择消费模式（Type）：选择 agent-plan。

运行 ArkCLI Helper，根据界面提示完成 Pi 的配置。

在命令行界面输入 arkcli helper 命令，启动 ArkCLI Helper。

选择要配置的 Plan profile：agent-plan_cn-beijing_personal (Agent Plan)。

选择默认 model：按需选择。

选择要配置的 AI Agent：Pi。

当前支持的 Harness 包括：AI Native 应用开发底座和Computer Use Agent，根据界面提示按需选择配置或者跳过。

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

方式 2：手动配置

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

关注的配置信息如下：

<ARK_API_KEY>：替换为您自己的专属 API Key。

model：见支持模型及 Harness，需配置文本生成模型。

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

{
"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": 262144,
"id": "kimi-k2.7-code",
"input": ["text", "image"],
"maxTokens": 32768
},
{
"id": "minimax-m3"
}
]
}
}
}

说明

修改 models.json 后无需重启 Pi，在对话中执行 /model 会自动重新加载。

三、启动并使用 Pi

在 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 接入。具体配置方法请参见接入视觉模型。

注意

不同的套餐支持的视觉模型有所不同，具体参见支持模型及 Harness。

视觉模型不支持通过 Auto 及控制台切换使用。

最近更新时间：2026.09.23 17:07:49

这个页面对您有帮助吗？

有用

无用