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

说明

需要先访问方舟 Coding Plan活动，按需订阅套餐后再配置使用编程工具。

# 核心配置接入工具的核心参数如下： ## **模型配置** 支持以下两种方式配置模型：配置 Model Name (配置文件指定) 在工具配置文件中指定 Model Name，可实时切换模型。支持配置的 Model Name：

注意

配置 Model Name 时，支持使用全小写格式，同时也支持直接复制开通管理页面中的模型名称。

* \`doubao-seed-evolving\` * \`doubao-seed-2.1-turbo\` * \`doubao-seed-2.0-lite\` * \`minimax-m3\` * \`glm-5.3\` (\`glm-latest\`) * \`glm-5.3-flash\` * \`deepseek-v4-flash\` * \`deepseek-v4-pro\` * \`kimi-k2.7-code\` * \`kimi-k3\`

说明

Model Name 不支持配置为 Auto，如需使用，请通过控制台切换该模式。

配置 ark-code-latest (控制台管理) 1. 在配置文件中指定模型为\`ark-code-latest\`。 2. 通过[开通管理页面](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe)选择或切换目标模型，切换模型后 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\`

注意

请勿使用 https://ark.cn-beijing.volces.com/api/v3 ：该 Base URL 不会消耗您的 Coding Plan 额度，而是会产生额外费用。

## **API Key** [获取 API Key](https://ark.volcengine.com/region:cn-beijing/apikey) # 一、安装 Pi 前提条件：安装 [Node.js 20 或更新版本](https://nodejs.org/en/download/)。 macOS/Linux 在命令行界面，执行以下命令安装 Pi。 ```Bash # 方式 1：npm 全局安装 npm install -g @earendil-works/pi-coding-agent # 方式 2：官方一键脚本 curl -fsSL https://pi.dev/install.sh | sh ``` 安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功。 ```Bash pi --version ``` Windows 需先额外安装 [Git for Windows](https://git-scm.com/download/win)，Pi 依赖其提供的 `bash.exe` 执行 `!` / `!!` shell 命令；官方 curl 一键脚本在 Windows 上不支持。通过 npm 全局安装： ```Bash npm install -g @earendil-works/pi-coding-agent ``` 安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功。 ```Bash pi --version ``` # 二、配置 Pi ## 方式 1：自动化助手（推荐） ArkCLI Helper 是一个编码工具助手，支持快速配置选择的工具接入 Coding Plan。安装并运行该助手，根据界面提示操作可自动完成工具配置，降低手动配置的时间成本和出错风险。

注意

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

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

1. 安装 Ark CLI。 ```Bash # 1. 通过 NPM 安装 npm install -g @volcengine/ark-cli@latest # 2. 验证安装 arkcli --version ``` 2. 登录 Ark CLI。 ```Bash arkcli auth login ``` ![图片](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260624-144256-509.png) 根据界面提示选择登录方式。若之前已登录过 arkcli，会沿用上次选择的配置；如需重新选择，请先执行 `arkcli config reset` 后再运行 `arkcli auth login`。首次登录时，按提示完成以下配置： 1. **选择项目（Project）** ：可按需选择，或默认选择**账号全部资源**。 2. **选择消费模式（Type）** ：选择 `coding-plan`。 ![图片](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260624-163746-727.png) 3. 运行 ArkCLI Helper，根据界面提示完成 Pi 的配置。 1. 在命令行界面输入 `arkcli helper` 命令，启动 ArkCLI Helper。 2. **选择要配置的 Plan profile**：选择 `coding-plan_cn-beijing_personal (Coding Plan)`。 ![图片](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260624-163451-813.png) 3. **选择默认 model**：按需选择。 4. **选择要配置的 AI Agent**：`Pi`。 ![图片](https://arkdoc.tos-cn-beijing.volces.com/images/CodingPlan/pi-ark-cli.png) 完成上述操作后，将自动完成 Pi 的基础配置，无需手动安装。 ## 方式 2：手动配置 1. 关注的配置信息如下： * ``：替换为您自己的 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。 * `model`：更新为需要使用的模型信息。 2. 创建并编辑 `~/.pi/agent/models.json` 文件。如目录不存在，先创建后再编辑。 ```JSON { "providers": { "coding-plan": { "api": "openai-completions", "apiKey": "", "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": 262144, "id": "doubao-seed-2.1-turbo", "input": ["text", "image"], "maxTokens": 256000 }, { "contextWindow": 262144, "id": "doubao-seed-2.0-lite", "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-flash", "input": ["text"], "maxTokens": 393216 }, { "contextWindow": 1048576, "id": "glm-latest", "input": ["text"], "maxTokens": 128000 }, { "contextWindow": 262144, "id": "kimi-k2.7-code", "input": ["text", "image"], "maxTokens": 32768 }, { "contextWindow": 1048576, "id": "kimi-k3", "input": ["text", "image"], "maxTokens": 65536 }, { "id": "minimax-m3" } ] } } } ```

说明

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

# 三、使用 Pi 1. 进入项目目录并启动 Pi： ```Bash pi ``` 2. 在 Pi 交互界面执行 `/model`，可选择切换刚才配置的 provider 和模型。 ![图片](https://arkdoc.tos-cn-beijing.volces.com/images/CodingPlan/cp-personal-pi-choose-model.png) 3. 发送任意问题验证连通性，例如： ```Plain Text 简单介绍一下当前目录的文件结构。 ``` 若返回内容正常，说明 Coding Plan 已成功接入。 > 更多 Pi 使用教程请参见 [Pi 官方文档](https://pi.dev/docs/latest)。 # 常见问题 * [OpenCode 如何开启深度思考模式？](https://ark.volcengine.com/region:cn-beijing/docs/82379/2165245?lang=zh#1cfacd2b) * [如何升级 Ark Helper？](https://ark.volcengine.com/region:cn-beijing/docs/82379/2165245?lang=zh#7bdd6584) * [如何卸载 Ark Helper？](https://ark.volcengine.com/region:cn-beijing/docs/82379/2165245?lang=zh#e2f455fc) # 错误码在编程工具中使用 Coding Plan 套餐时可能会遇到报错，您可以根据错误信息查看对应的报错场景并定位问题，具体可参考[错误码](https://ark.volcengine.com/region:cn-beijing/docs/82379/1299023?lang=zh)。

火山方舟