Codex / Claude Code / OpenCode 怎么接入火山方舟模型 API？

认准按量计费 Base URL，把 API Key 与模型 ID 填进各自的配置文件即可，文中给出三者的手工配置示例。

按量计费 API 和 Coding Plan / Agent Plan 有什么区别？

接口地址不同：Coding Agent 手工接入必须使用按量计费 API 的 Base URL，不要套用套餐类地址。

API Key 和模型 ID 怎么获取？

通过向量云获取火山方舟官方 API Key，并在控制台查看可用模型 ID。

火山方舟 · Coding Agent

Codex / Claude Code / OpenCode
接入火山方舟模型 API

手工配置 · 官方 API · 按量计费 · 即用即扣

Codex、Claude Code、OpenCode 是目前最主流的三款 Coding Agent（AI 编程助手）。它们都支持通过自定义 API 端点接入第三方模型服务——这意味着你可以把它们背后的模型换成字节跳动火山方舟上的 DeepSeek V4.1 Flash、DeepSeek V4 Pro、GLM-5.3 等模型，用官方 API 直接调用，成本更低、选择更灵活。

本文只讲手工配置方式：直接编辑配置文件或设置环境变量，把三款工具指向火山方舟的按量计费接口，不涉及任何自动化配置助手。

配置前必读

一、先搞清楚：按量计费 API ≠ Coding Plan / Agent Plan

这是配置前最容易踩坑的一点。火山方舟目前提供多种调用方式，它们的接口地址完全不同，配错了会直接调用失败：

调用方式	计费模式	OpenAI 兼容 Base URL	Anthropic 兼容 Base URL
方舟按量计费本文使用	预充值 · 即用即扣	`…/api/v3`	`…/api/compatible`
Coding Plan	订阅套餐	`…/api/coding/v3`	`…/api/coding`
Agent Plan	订阅套餐	—	`…/api/plan`

域名均为 ark.cn-beijing.volces.com

本文使用的 API Key 是按量计费的方舟官方 Key，因此：

所有工具一律使用 /api/v3（OpenAI 兼容）或 /api/compatible（Anthropic 兼容）；
不要使用 /api/coding、/api/coding/v3、/api/plan 等套餐专用地址，也不要混用套餐 API Key。

⚠️ 一句话记忆：套餐地址里带 coding 或 plan；按量计费地址里是 v3 或 compatible。

前置准备

二、获取 API Key 与模型 ID

配置三款工具之前，先拿到 API Key 和要用的模型 ID。

注册账号，完成首次充值打开 https://ark.tokenrize.cn/ 注册并验证邮箱，前往「钱包充值」完成首次充值（不少于 10 元）。余额实时到账，可用于抵扣模型调用费用；可用余额低于 10 元时无法创建 API Key。
创建 API Key，妥善保存进入「API Key 管理」页面，点击「创建 API Key」，填写名称后提交。系统将从资源池自动分配一把官方可用的 API Key。创建成功弹窗中会展示完整 Key，请立即复制保存——关闭弹窗后完整 Key 将不再展示。
记录配置信息把下面这几项记下来，三款工具配置时会反复用到。

项目	值
OpenAI 兼容 Base URL	`https://ark.cn-beijing.volces.com/api/v3`
Anthropic 兼容 Base URL	`https://ark.cn-beijing.volces.com/api/compatible`
API Key	你从向量云获取的 `ark-...88888` Key

可用模型 ID

模型名称	模型 ID	特点
DeepSeek-V4.1-Flash	`deepseek-v4-1-flash-260910`	全新 CED 架构，原生多模态
DeepSeek-V4-Pro 正式版	`deepseek-v4-pro-ga-260813`	深度思考旗舰，复杂推理首选
DeepSeek-V4-Flash 正式版	`deepseek-v4-flash-ga-260731`	高性价比极速响应
GLM-5.3	`glm-5-3-260903`	智谱最新旗舰，多语言能力提升
GLM 5.2	`glm-5-2-260617`	面向长程任务的旗舰模型

💡 建议直接使用完整模型 ID（带版本后缀，如 deepseek-v4-1-flash-260910），不要使用 deepseek-v4-1-flash 之类的简写别名，避免被路由到非预期版本。

三款工具手工配置

三、Codex CLI 手工配置

Codex CLI 是 OpenAI 出品的命令行 AI 编程工具，通过 config.toml 自定义模型服务商。

3.1 配置文件路径

系统	路径
Windows	`C:\Users\<你的用户名>\.codex\config.toml`
macOS / Linux	`~/.codex/config.toml`

目录或文件不存在时手动创建：

# macOS / Linux
mkdir -p ~/.codex && touch ~/.codex/config.toml

# Windows PowerShell
New-Item -ItemType Directory -Path "$env:USERPROFILE\.codex" -Force
New-Item -ItemType File -Path "$env:USERPROFILE\.codex\config.toml" -Force

3.2 编辑 config.toml

# ~/.codex/config.toml

# 默认使用的模型（按需替换为其它模型 ID）
model = "deepseek-v4-1-flash-260910"

# 指定使用下方定义的自定义 provider
model_provider = "volcengine"

[model_providers.volcengine]
name = "火山方舟（按量计费）"
# 按量计费 OpenAI 兼容地址（注意：不是 /api/coding/v3）
base_url = "https://ark.cn-beijing.volces.com/api/v3"
# API Key 从该环境变量读取
env_key = "ARK_API_KEY"
# 使用 Chat Completions 协议
wire_api = "chat"

配置项	说明
model	默认模型 ID，必须是火山方舟的真实模型 ID
model_provider	指向下方自定义 provider 的 ID
base_url	火山方舟按量计费 OpenAI 兼容地址，以 `/v3` 结尾
env_key	API Key 所在的环境变量名，不要把 Key 写进配置文件
wire_api	固定填 `chat`

3.3 设置环境变量并启动

# macOS / Linux
export ARK_API_KEY="ark-你的APIKey"
codex

# Windows PowerShell
$env:ARK_API_KEY = "ark-你的APIKey"
codex

启动后直接发送一条消息（如「用 Python 写一个快速排序算法」），能正常收到回复即配置成功。

⚠️ base_url 必须以 /v3 结尾，不要写成 /api/coding/v3，也不要加 /chat/completions。

四、Claude Code 手工配置

Claude Code 是 Anthropic 出品的命令行 AI 编程工具。火山方舟提供 Anthropic 兼容接口，Claude Code 可以直接对接，无需协议转换中间件。

4.1 配置文件路径

系统	路径
Windows	`C:\Users\<你的用户名>\.claude\settings.json`
macOS / Linux	`~/.claude/settings.json`

4.2 编辑 settings.json

文件不存在则手动创建，写入以下内容（将 ark-你的APIKey 替换为实际 Key）：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ark.cn-beijing.volces.com/api/compatible",
    "ANTHROPIC_AUTH_TOKEN": "ark-你的APIKey",
    "ANTHROPIC_MODEL": "deepseek-v4-1-flash-260910",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-v4-flash-ga-260731",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

配置项	作用 / 值
ANTHROPIC_BASE_URL	火山方舟按量计费 Anthropic 兼容接口
ANTHROPIC_AUTH_TOKEN	从向量云获取的 API Key
ANTHROPIC_MODEL	默认模型 ID，如 `deepseek-v4-1-flash-260910`
ANTHROPIC_SMALL_FAST_MODEL	后台轻量任务模型，如 `deepseek-v4-flash-ga-260731`
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS	`"1"`，减少协议兼容问题

⚠️ 关键点：ANTHROPIC_BASE_URL 不要加 /v1 后缀。Claude Code 会自动拼接 /v1/messages，只需填到 /api/compatible。同样不要使用 /api/coding（Coding Plan）或 /api/plan（Agent Plan）。

4.3 或使用环境变量（临时方式）

# macOS / Linux
export ANTHROPIC_BASE_URL="https://ark.cn-beijing.volces.com/api/compatible"
export ANTHROPIC_AUTH_TOKEN="ark-你的APIKey"
export ANTHROPIC_MODEL="deepseek-v4-1-flash-260910"
claude

# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://ark.cn-beijing.volces.com/api/compatible"
$env:ANTHROPIC_AUTH_TOKEN = "ark-你的APIKey"
$env:ANTHROPIC_MODEL = "deepseek-v4-1-flash-260910"
claude

关闭终端后失效，适合临时测试；永久生效推荐用 settings.json。启动后发送一条消息（如「你好」），收到回复即配置成功；也可在 Claude Code 内执行 /status 查看当前 Base URL 与模型。

五、OpenCode 手工配置

OpenCode 是开源 AI 编程助手，通过 opencode.json 自定义 provider，走 OpenAI 兼容协议。

5.1 配置文件路径

系统	路径
Windows	`%USERPROFILE%\.config\opencode\opencode.json`
macOS / Linux	`~/.config/opencode/opencode.json`

5.2 编辑 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "volcengine": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "火山方舟（按量计费）",
      "options": {
        "baseURL": "https://ark.cn-beijing.volces.com/api/v3",
        "apiKey": "{env:ARK_API_KEY}"
      },
      "models": {
        "deepseek-v4-1-flash-260910": {
          "name": "DeepSeek-V4.1-Flash",
          "limit": { "context": 1024000, "output": 384000 }
        },
        "deepseek-v4-pro-ga-260813": {
          "name": "DeepSeek-V4-Pro 正式版",
          "limit": { "context": 1024000, "output": 384000 }
        },
        "deepseek-v4-flash-ga-260731": {
          "name": "DeepSeek-V4-Flash 正式版",
          "limit": { "context": 1024000, "output": 384000 }
        }
      }
    }
  },
  "model": "volcengine/deepseek-v4-1-flash-260910"
}

配置项	说明
provider.volcengine	自定义 provider ID，可自取，需与顶层 `model` 引用一致
npm	OpenAI 兼容协议固定填 `@ai-sdk/openai-compatible`
options.baseURL	火山方舟按量计费 OpenAI 兼容地址
options.apiKey	API Key，支持 `{env:ARK_API_KEY}` 环境变量语法
models	模型映射，key 即真实模型 ID，`name` 为界面显示名
model	默认模型，格式为 `provider ID/模型 key`

5.3 设置环境变量并启动

# macOS / Linux
export ARK_API_KEY="ark-你的APIKey"
opencode

启动后可用 /models 命令查看与切换已配置的模型。

⚠️ models 的 key 必须是真实模型 ID（如 deepseek-v4-1-flash-260910），否则请求会报模型不存在；options.baseURL 必须以 /v3 结尾。

验证与排查

六、curl 验证：配置前先确认 Key 可用

任何工具配置后不工作时，先用 curl 验证 API Key 与端点是否可用，能快速定位问题在哪一层。

OpenAI 协议验证：

curl https://ark.cn-beijing.volces.com/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ark-你的APIKey" \
  -d '{
    "model": "deepseek-v4-1-flash-260910",
    "messages": [{"role": "user", "content": "你好"}]
  }'

Anthropic 协议验证：

curl https://ark.cn-beijing.volces.com/api/compatible/v1/messages \
  -H "x-api-key: ark-你的APIKey" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash-260910",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "你好"}]
  }'

能正常返回 JSON → Key 与端点没问题，问题在工具配置层面；返回错误 → 按错误信息排查 Key、模型 ID 或余额。

七、常见问题排查

问题 1：401 / 403 鉴权失败

检查 API Key 是否复制完整、前后有无多余空格；
确认 Key 在平台 ark.tokenrize.cn 中处于启用状态；
确认账户余额充足；Claude Code 确认使用 ANTHROPIC_AUTH_TOKEN。

问题 2：404 Not Found

检查 Base URL：OpenAI 兼容用 /api/v3，Anthropic 兼容用 /api/compatible；
不要使用 /api/coding、/api/coding/v3、/api/plan 等套餐地址；
Claude Code 的 ANTHROPIC_BASE_URL 不要加 /v1。

问题 3：model not found / 模型不存在

模型 ID 拼写错误，注意全小写、连字符、版本后缀不能少；
OpenCode 的 models key 必须与真实模型 ID 完全一致；
建议直接从平台模型列表复制模型 ID。

问题 4：调用计费异常 / 提示套餐未开通

大概率是误用了套餐地址（/api/coding、/api/plan）；
本文使用按量计费 Key，请统一改用 /api/v3 或 /api/compatible。

配置速查

八、三款工具配置速查表

对比项	Codex CLI	Claude Code	OpenCode
配置文件	`~/.codex/config.toml`	`~/.claude/settings.json`	`~/.config/opencode/opencode.json`
协议	OpenAI 兼容	Anthropic 兼容	OpenAI 兼容
Base URL	`/api/v3`	`/api/compatible`	`/api/v3`
关键字段	`model_provider` `base_url` `env_key`	`ANTHROPIC_BASE_URL` `ANTHROPIC_AUTH_TOKEN`	`options.baseURL` `options.apiKey`

三款工具的核心逻辑完全一致：填按量计费 Base URL + 填 API Key + 选真实模型 ID，区别只在配置文件格式不同。

九、总结

获取 Key → 在 ark.tokenrize.cn 注册充值，创建火山方舟官方 API Key；
认准地址 → 按量计费统一用 /api/v3（OpenAI 兼容）或 /api/compatible（Anthropic 兼容），不要用 /api/coding、/api/plan 等套餐地址；
手工配置 → 编辑 Codex / Claude Code / OpenCode 的配置文件，填入 Base URL、Key 与模型 ID；
开始使用 → 启动工具，选择模型，直接开干。

✅ 核心优势：官方 API 不经中转，性能稳定；按量计费、预充值、即用即扣、不设账期；通过向量云获取低折扣 Token，充值 10 元起步；一把 Key 调用 DeepSeek V4.1 Flash、V4 Pro、V4 Flash、GLM-5.3 等多款模型。

关于向量云

向量云（南京）科技有限公司

面向大模型应用落地的技术服务型企业，依托字节跳动火山方舟能力，为合作方提供低折扣模型 Token、可独立部署的运营支撑平台及全链路运营支持。

低折扣 Token 官方 API Key 按量计费 · 即用即扣 Coding Agent 接入充值开票服务

Codex / Claude Code / OpenCode
接入火山方舟模型 API

一、先搞清楚：按量计费 API ≠ Coding Plan / Agent Plan

二、获取 API Key 与模型 ID

可用模型 ID

三、Codex CLI 手工配置

3.1 配置文件路径

3.2 编辑 config.toml

3.3 设置环境变量并启动

四、Claude Code 手工配置

4.1 配置文件路径

4.2 编辑 settings.json

4.3 或使用环境变量（临时方式）

五、OpenCode 手工配置

5.1 配置文件路径

5.2 编辑 opencode.json

5.3 设置环境变量并启动

六、curl 验证：配置前先确认 Key 可用

七、常见问题排查

问题 1：401 / 403 鉴权失败

问题 2：404 Not Found

问题 3：model not found / 模型不存在

问题 4：调用计费异常 / 提示套餐未开通

八、三款工具配置速查表

九、总结

常见问题（FAQ）

Q1. Codex / Claude Code / OpenCode 怎么接入火山方舟模型 API？

Q2. 按量计费 API 和 Coding Plan / Agent Plan 有什么区别？

Q3. API Key 和模型 ID 怎么获取？

Codex / Claude Code / OpenCode接入火山方舟模型 API

一、先搞清楚：按量计费 API ≠ Coding Plan / Agent Plan

二、获取 API Key 与模型 ID

可用模型 ID

三、Codex CLI 手工配置

3.1 配置文件路径

3.2 编辑 config.toml

3.3 设置环境变量并启动

四、Claude Code 手工配置

4.1 配置文件路径

4.2 编辑 settings.json

4.3 或使用环境变量（临时方式）

五、OpenCode 手工配置

5.1 配置文件路径

5.2 编辑 opencode.json

5.3 设置环境变量并启动

六、curl 验证：配置前先确认 Key 可用

七、常见问题排查

问题 1：401 / 403 鉴权失败

问题 2：404 Not Found

问题 3：model not found / 模型不存在

问题 4：调用计费异常 / 提示套餐未开通

八、三款工具配置速查表

九、总结

常见问题（FAQ）

Q1. Codex / Claude Code / OpenCode 怎么接入火山方舟模型 API？

Q2. 按量计费 API 和 Coding Plan / Agent Plan 有什么区别？

Q3. API Key 和模型 ID 怎么获取？

Codex / Claude Code / OpenCode
接入火山方舟模型 API