文档 · 供应商

火山方舟 Coding Plan 接入 Claude Code 和 Codex

火山方舟有三种用法：Coding Plan、Agent Plan 和按量付费。两个套餐各有自己的接口地址，套餐额度只在自己的地址上扣，发到按量付费的 /api/v3 会另外计费。在 magpie 里添加 Key 并选好套餐，Claude Code、Codex、Gemini CLI、OpenCode 和其他工具就都能通过本地网关 127.0.0.1:3425 用上方舟里的豆包、GLM、DeepSeek 和 Kimi。

添加火山方舟

拿到 Key在火山方舟控制台的 API Key 管理页（ark.volcengine.com）创建。套餐的 Key 要在套餐页面开通套餐后才能扣套餐额度。
添加供应商并选套餐在供应商页点＋添加供应商，选 Volcengine Ark，给 Key 选 Coding Plan、Agent Plan 或 Pay as you go，保存。
给工具选上在 Agent 页给某个工具选 ark-code-latest 或 doubao-seed-2.1-pro 这类模型。

终端

magpie claude volcengine/ark-code-latest
magpie codex volcengine/doubao-seed-2.1-pro
magpie opencode volcengine/glm-5.3

套餐与接口地址

套餐	接口地址（Chat Completions 与 Responses）	Anthropic Messages
Coding Plan	`https://ark.cn-beijing.volces.com/api/coding/v3`	`https://ark.cn-beijing.volces.com/api/coding`
Agent Plan	`https://ark.cn-beijing.volces.com/api/plan/v3`	`https://ark.cn-beijing.volces.com/api/plan`
按量付费	`https://ark.cn-beijing.volces.com/api/v3`	—（预设里没有 Anthropic 接口）

套餐的地址带版本号，magpie 原样使用，不会再加 /v1。供应商里的每个 Key 都标明自己的套餐，所以一个供应商可以同时放 Coding Plan、Agent Plan 和按量付费的 Key，每个 Key 的请求都发到它自己套餐的地址。

套餐里的模型

两个套餐的模型列表相同。套餐的 /models 不返回套餐里的模型（Coding Plan 返回的是方舟的通用目录，Agent Plan 返回 404），所以 magpie 用火山方舟套餐文档里列的文本模型，ark-code-latest 排第一：ark-code-latest、doubao-seed-evolving、doubao-seed-2.1-pro、doubao-seed-2.1-lite、doubao-seed-2.0-mini、glm-5.3、deepseek-v4-pro、deepseek-v4.1-flash、kimi-k3、kimi-k3.1-pro 等。哪些模型能看图也按文档来，比如 glm-5.3-flash 和 deepseek-v4.1-flash 支持图片输入，工具发来的图片会直接交给它们。按量付费的 Key 则读取方舟自己的模型列表。

在各个工具里用

Claude Code 说的是 Anthropic Messages。套餐有自己的 Anthropic 接口（/api/coding、/api/plan），请求原样转过去，扣的是套餐额度。见 Claude Code 接入国产模型。
Codex 只说 OpenAI Responses。方舟的套餐地址自己就提供 Responses，Codex 的请求原样转过去，模型出现在 Codex 的 /model 里。见 Codex 接入第三方模型。
Gemini CLI 说 Gemini 的 API，magpie 把它指向本地网关并做转换。见 Gemini CLI 接入其他模型。
OpenCode：magpie 把模型写进 opencode.json。见 OpenCode 接入其他模型。

联网搜索

方舟的 Responses 接口自己执行 web_search 工具，按量付费和两个套餐都支持；Chat 接口不支持。所以 Codex 的联网搜索会原样交给方舟，由方舟去搜，而不是从请求里删掉。方舟不接受的 include 取值会被去掉，避免整个请求被拒。

画图与视频

Agent Plan 还带 Seedream 画图模型（doubao-seedream-5-0-pro、doubao-seedream-5.0-flash）和 Seedance 视频模型（doubao-seedance-2.0、2.0-fast、2.0-mini、2.5）。在设置 → 图片里选上，就能通过 magpie 的画图和视频工具使用。方舟没有 OpenAI 式的视频接口，magpie 用方舟的异步视频生成任务接口提交并查询。

用量窗口

Coding Plan 和 Agent Plan 有 5 小时、每周和每月三个额度窗口。方舟只把它们告诉账号的管控面（open.volcengineapi.com），不告诉推理用的 Key，所以编辑供应商时 magpie 会请你填账号的 AccessKey ID 和 Secret。填上后，那一行显示套餐剩余额度；按量付费没有窗口。

常见问题

火山方舟 Coding Plan 怎么接入 Claude Code？

在 magpie 里添加 Volcengine Ark，把 Key 的套餐选成 Coding Plan，然后在 Claude Code 那一行选 ark-code-latest 这类模型，或运行 magpie claude volcengine/ark-code-latest。请求走套餐的 Anthropic 接口 https://ark.cn-beijing.volces.com/api/coding，扣套餐额度。

为什么用了 Coding Plan 的 Key 还被按量扣费？

套餐额度只在套餐自己的地址上扣：Coding Plan 是 /api/coding/v3 和 /api/coding，Agent Plan 是 /api/plan/v3 和 /api/plan。发到 /api/v3 就是按量付费。在 magpie 里给 Key 选对套餐，请求就会发到套餐的地址。

火山方舟能在 Codex 里用吗？

能。套餐地址自己提供 OpenAI Responses，magpie 把 Codex 的请求原样转过去，联网搜索也交给方舟执行。运行 magpie codex volcengine/doubao-seed-2.1-pro，或在 Codex 那一行选上。

怎么在 magpie 里看到方舟套餐还剩多少额度？

编辑火山方舟供应商，填上账号的 AccessKey ID 和 Secret。方舟只通过管控面告诉额度，填好后那一行显示 5 小时、每周和每月窗口。

同一套方法用在其他国产模型：GLM 编程套餐、Kimi、DeepSeek、通义千问。各工具的指南：Claude Code 接入国产模型、Codex 接入第三方模型。遇到报错？见常见错误排查，或到 Discord 提问。