---
title: OpenCode · 火山方舟（豆包）
nav: OpenCode·方舟
summary: 一条命令把 OpenCode 接到火山方舟：选 Coding Plan 套餐或按量付费，key 贴进手机密钥卡，先真实调用一次才切，不通自动切回。
order: 45
---
# OpenCode · 火山方舟（豆包）

OpenCode 是开源的 AI 编程工具。火山方舟是字节跳动旗下的模型平台，提供豆包、DeepSeek、GLM、Kimi 等模型。Agent J 把两者合成了一个选项：底层用 OpenCode，模型走方舟。

还没决定用哪家？先看[按你用的模型选](/docs/models/)。方舟 Coding Plan 套餐怎么买、key 怎么拿，看[用火山方舟 Coding Plan](/docs/ark/)。安装、配对手机，看[安装](/docs/install/)。

## 适合谁 {#who}

- 在中国大陆，想用豆包 Seed 2.1 Pro 这类国产模型做 Agent J 的主力。
- 已经有方舟账号：有 Coding Plan 套餐就走套餐，没有就按量付费，按 token 扣余额。
- 只想在手机上点一下就换好，不想自己改 OpenCode 的配置文件。

## 两种接入：套餐还是按量 {#plan}

| | Coding Plan 套餐 | 按量付费 |
|---|---|---|
| 地址 | `…/api/coding/v3` | `…/api/v3`（方舟标准地址） |
| 怎么扣钱 | 扣套餐额度，包月 | 按 token 从账户余额扣 |
| 谁能用 | **只给编程 Agent 用**（OpenCode、Claude Code 等） | 任何程序都能用 |
| 默认模型 | `doubao-seed-2.1-pro` | `doubao-seed-2-1-pro-260915` |
| 存 key 的名字 | `ARK_CODING_PLAN_API_KEY` | `ARK_API_KEY` |

**套餐地址只能给编程 Agent 用。** 这是方舟的条款：别的程序拿套餐地址调用，会被判为滥用，可能封号。Agent J 只让你的 OpenCode 用它，Agent J 自己的程序从不调用套餐地址；客服 bot 也拿不到套餐 key。

同一把方舟 API Key 两个地址都能用，**是地址决定扣套餐还是扣余额**。价格以[火山方舟模型价格](https://www.volcengine.com/docs/82379/1099320)和下单页为准。

## 拿 key {#key}

1. 打开方舟控制台 https://console.volcengine.com/ark/ ，在 API Key 管理里新建一把 key。
2. 按量付费要先在控制台给账户充值，并在模型广场开通要用的模型。
3. **先别复制给任何人。** 等手机上弹出密钥卡再贴。

## 一步切换 {#switch}

在手机菜单点换 AI 编程工具，后面加上 OpenCode 火山方舟 几个字再发送；或者直接跟 Agent 说要切到 OpenCode 火山方舟。Agent 会先问你用套餐还是按量，然后运行其中一条：

```bash
agentj agent switch opencode --preset ark --plan coding
```

```bash
agentj agent switch opencode --preset ark --plan payg
```

它会依次做这些事：

1. 先看电脑上有没有 OpenCode。没有的话，按[装好 AI 命令行工具](/docs/setup-agents/#opencode)里的说明装一下。顺便看看有没有方舟官方的 arkcli。
2. 如果后台服务里还没有 key，会停下来让你填密钥卡。手机上弹出卡片，你只把 key 贴进去，Agent 看不到具体值。如果是按量付费的 key，贴完后会用方舟的模型列表核对一次。
3. 把方舟写进 OpenCode 的设置，你原来的设置一项都不动。
4. **先用 OpenCode 真实调用一次方舟**，通了才切换。切换后新的 Agent 会先跟你打招呼。
5. 任何一步不通，自动切回原来的工具，并把刚写进去的方舟设置撤掉。

想换别的方舟模型，加 `--model`，比如按量付费的 `--model doubao-seed-2-1-lite-260915`。

## 和 arkcli 的关系 {#arkcli}

arkcli 是火山方舟官方的命令行工具（`npm i -g @volcengine/ark-cli`）。它的 helper 能给 OpenCode 写方舟配置，但得在终端里用浏览器登录火山账号，手机上做不了。所以 Agent J 不调用它，自己写一份等价的设置，key 只按名字引用。装了 arkcli 也没关系，切换时会显示它的版本。

## 模型与看图 {#models}

按量付费默认写入这些模型（2026-10-17 从方舟模型列表读取）：

- 能看截图：`doubao-seed-2-1-pro-260915`（默认）、`doubao-seed-2-1-lite-260915`、`doubao-seed-2-1-turbo-260628`、`doubao-seed-2-0-code-preview-260215`。
- 只能读文字：`deepseek-v4-pro-ga-260813`、`deepseek-v4-1-flash-260910`、`glm-5-2-260617`、`glm-5-3-flash-260828`。

用浏览器自动化、发截图给它看时，选能看截图的模型。套餐的模型列表见[用火山方舟 Coding Plan](/docs/ark/#models)。

## 常见坑 {#pitfalls}

- 余额不足（按量付费）：方舟会拒绝调用，切换停在检查这一步，原来的工具照常。去控制台充值后再切。
- 模型没开通：按量付费要在模型广场先开通。换一个已开通的模型，或开通后再切。
- 套餐额度用完：等额度刷新，或换按量付费。
- 已经在用 OpenCode：方舟设置会写好，Agent 会告诉你怎么只换模型。

## 切回原来的工具 {#switch-back}

跟 Agent 说切回 Claude Code（或原来那个），或运行：

```bash
agentj agent switch --undo
```

详见[切换 AI 编程工具](/docs/switch-harness/)。

<details>
<summary>地址与名字</summary>

- 套餐：`https://ark.cn-beijing.volces.com/api/coding/v3`，服务商 `ark-coding-plan`，key 名 `ARK_CODING_PLAN_API_KEY`
- 按量：`https://ark.cn-beijing.volces.com/api/v3`，服务商 `ark-api`，key 名 `ARK_API_KEY`，核对接口 `GET /api/v3/models`
- OpenCode 设置文件：`~/.config/opencode/opencode.json`

</details>