最近被问得最多的一个问题Codex、Claude Code、OpenCode 这三个命令行 AI 编程工具到底怎么接火山方舟的模型 API我前前后后折腾了几天把三个工具的接入方式都跑通了。这篇直接把完整路径写出来包括配置文件怎么写、环境变量怎么设、模型 ID 怎么填、报错怎么排查照着抄就行。文章适合两类人一类是刚拿到火山方舟 API key想把 DeepSeek 这类模型用进日常编程的新手另一类是用过一阵子但总被各种 auth、endpoint、model not found 报错卡住的老手。1. 接入方案的整体设计为什么三个工具能共用一个端点1.1 先搞清楚三个工具各自是什么脾气Codex 是 OpenAI 官方出品的终端编程智能体默认走 OpenAI 自己的账号体系和模型服务特点是命令执行、文件读写、多轮代码编辑的能力很强。Claude Code 是 Anthropic 官方出的终端里跑起来像有个结对程序员在帮你改代码对长上下文的处理是它的强项。OpenCode 是 SST 团队开源的一个终端 AI 编程智能体用 Go 写的天生就是多 provider 的设计可以自由接各种模型服务。这三个工具的默认配置里Codex 只认 OpenAI 的接口Claude Code 只认 Anthropic 的接口OpenCode 倒是开放但默认模型列表里没有火山方舟的模型。想要统一走火山方舟关键就在于搞清楚一个事实火山方舟的 API 同时提供了两套兼容格式一套是 OpenAI 兼容格式一套是 Anthropic 兼容格式。这就意味着Codex 可以把它当成 OpenAI 兼容服务来配Claude Code 可以把它当成 Anthropic 兼容服务来配OpenCode 则可以直接定义一个自定义 provider 指向它的 OpenAI 兼容端点。这个设计思路就是接入的底层逻辑别一上来就找什么“特殊通道”不用折腾任何额外的东西。你要做的本质上就是告诉每个工具一句话API 地址换成火山方舟的API key 换成火山方舟的模型名换成火山方舟支持的模型 ID。剩下的事工具自己会处理。1.2 为什么要绕一圈接到火山方舟先说实话我一开始也觉得奇怪Codex 直接用 OpenAI 不好吗Claude Code 直接订阅 Claude 不好吗但实际用下来接火山方舟有几点是绕不开的刚需。第一是模型选择自由。火山方舟上能跑 DeepSeek V3、DeepSeek R1、豆包系列等一批模型这些开源模型的代码能力已经非常能打了尤其是 R1 这种推理模型在复杂重构、多文件改动这类任务上的表现超出很多人的预期。第二是费用可控。这些模型大多有按 token 计价的方案比订阅制更灵活重度使用的时候不用盯着固定月费心疼。第三是配置统一一个 API key三个工具都能用不需要每换一个工具就去重新开通一套服务。这里要提醒一句费控这件事一定要提前做。模型 API 费用的计算方式是每 1k token 多少钱看起来单价不高但 AI 编程工具跑一个任务会来回调很多次每次还带着大段上下文一个下午的重构任务可能就消耗几百万 token。火山方舟控制台里有费用中心建议接入前先去看看你想用的模型的计价表心里有个数。1.3 接入前需要准备好的三样东西在动手配置之前先把基础条件备齐不然配置到一半才发现缺东西来回排查很耗时间。一个火山方舟账号并且在控制台开通了你要用的模型。DeepSeek 系列、豆包系列在“开通管理”里能看到点开通即可。一个 API Key。在火山方舟控制台的“API Key 管理”里创建创建后只显示一次记得马上复制保存。一个模型 ID。这里有两种填法一种是在“在线推理”里创建“推理接入点”会得到一个 ep-xxx 格式的接入点 ID这种适合想锁定模型版本和推理参数的场景另一种是直接填模型名称比如 deepseek-v3-250324、deepseek-r1-250528 这种带日期后缀的模型 ID。我实际用下来觉得直接填模型 ID 最简单少一层创建接入点的操作。还有一点容易忽略火山方舟的 API 域名是 https://ark.cn-beijing.volces.com区域是 cn-beijing填 base URL 的时候别把区域写错更别画蛇添足加多余的路径后缀。2. 核心细节解析环境变量、模型 ID 与认证方式2.1 三个工具覆盖自定义 API 地址的机制先说 Codex。Codex 读取配置的路径是用户目录下的 ~/.codex/config.toml这个文件里可以定义多个 model provider每个 provider 有自己的 base_url、env_key 和 wire_api。你可以在全局配置里指定默认 provider也可以用命令行参数临时指定。需要注意Codex 新版默认走 OpenAI 的 Responses API也就是 /responses 这个接口这和传统 OpenAI 兼容服务提供的 /chat/completions 不是一回事。这也是很多人报错的根源后面排查部分我会细讲。再说 Claude Code。它认的是 Anthropic 那套环境变量核心是 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL 这三个。只要在启动 claude 之前把这三个变量设置好它就会完全绕开默认的 Anthropic 服务把请求发到你指定的地址。这个机制是三个工具里最直接的几乎没有歧义。最后是 OpenCode。OpenCode 的配置在 ~/.config/opencode/opencode.json 或者项目根目录的 opencode.json 里。它的 provider 体系基于 Vercel 的 AI SDK可以引入不同适配包来对接不同服务商。对于火山方舟这种 OpenAI 兼容服务用 ai-sdk/openai-compatible 这个包就行在配置里声明 provider再在里面列出可用模型。2.2 火山方舟两套兼容格式的区别这是全文最关键的一个技术点请你务必记清楚。OpenAI 兼容格式的完整 API 地址是 https://ark.cn-beijing.volces.com/api/v3请求路径是 /chat/completions鉴权方式是请求头里带 Authorization: Bearer 你的 API Key。Codex 和 OpenCode 都走这套。Anthropic 兼容格式的地址是 https://ark.cn-beijing.volces.com/api/v3/anthropic它模拟的是 Anthropic 的 Messages API请求路径是 /v1/messages。Claude Code 默认会在 ANTHROPIC_BASE_URL 后面拼上 /v1/messages所以配置的时候BASE_URL 就要填到 .../api/v3/anthropic 这一层千万别自己在后面加 /v1否则会变成 /v1/v1/messages直接 404。两套格式的模型 ID 是通用的都是你在控制台开通的模型 ID 或接入点 ID。API Key 也是同一个。理解了这两套格式的分工后面配置每个工具就只是填空题了。2.3 鉴权方式和费用计量的常见误区鉴权上最常见的坑是把两套格式的认证方式搞混。Claude Code 的环境变量叫 ANTHROPIC_AUTH_TOKEN很多人习惯性地想填 ANTHROPIC_API_KEY但这个变量名并不被 Claude Code 识别。OpenAI 这边则相反Codex 的 env_key 如果你命名成 OPENAI_API_KEY它读取的就是这个变量所以你要确保这个环境变量确实被导出了。费用计量上有两个容易被忽略的点。第一推理模型会有思考过程的 token 输出DeepSeek R1 这类模型在真正回答之前会先生成一大段思考内容这些思考 token 也是要计费的实际账单可能比预想高不少。第二AI 编程工具在编辑文件时会调用工具工具调用的结果会再次作为上下文发给模型这等于每一轮任务都有隐性消耗。我的习惯是每跑完一个任务就去火山方舟控制台看一眼用量不要等到月底再看账单。3. 实操过程三个工具的完整接入配置3.1 Codex 接入火山方舟的完整步骤第一步安装 Codex。如果你的电脑有 Node.js 环境直接用 npm 全局安装npm install -g openai/codex安装完先跑一下 codex --version 确认版本。接下来编辑配置文件 ~/.codex/config.toml把默认 provider 指向火山方舟同时把 wire_api 设置成 chat。这里就是前面说的那个关键点Codex 默认的 wire_api 是 responses火山方舟的 OpenAI 兼容端点目前主要提供的是 chat completions 接口所以必须显式改成 chat。model deepseek-v3-250324 model_provider ark [model_providers.ark] name Volcano Ark base_url https://ark.cn-beijing.volces.com/api/v3 env_key ARK_API_KEY wire_api chat然后导出环境变量export ARK_API_KEY你的火山方舟API Key之后运行 codex 时用 --provider ark 参数指定codex --provider ark 帮我写一个计算斐波那契数列的Python脚本如果你想临时切换模型比如用 R1 做复杂重构可以直接改配置文件里的 model 字段或在命令行里用 --model 参数覆盖。实测下来Codex 配合火山方舟的响应速度还是让人满意的唯一要注意的是不要把 max_tokens 设得太小推理模型的思考过程会占用大量输出 token设置太小容易中途截断。3.2 Claude Code 接入火山方舟的完整步骤Claude Code 的安装也是先走 npmnpm install -g anthropic-ai/claude-code在 macOS 或 Linux 上用环境变量配置export ANTHROPIC_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3/anthropic export ANTHROPIC_AUTH_TOKEN你的火山方舟API Key export ANTHROPIC_MODELdeepseek-v3-250324 export ANTHROPIC_SMALL_FAST_MODELdeepseek-v3-250324然后在同一个终端里直接运行 claude交互界面起来后让它干一个简单的活比如“读取当前目录的文件列表”确认它能正常调用工具。如果一切正常说明链路已经通了。Windows 用户注意PowerShell 和 CMD 的变量设置方式不一样。PowerShell 里临时设置是这样$env:ANTHROPIC_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3/anthropic $env:ANTHROPIC_AUTH_TOKEN你的火山方舟API Key $env:ANTHROPIC_MODELdeepseek-v3-250324 $env:ANTHROPIC_SMALL_FAST_MODELdeepseek-v3-250324如果要持久生效用 setx 命令写入用户环境变量。还有个细节ANTHROPIC_SMALL_FAST_MODEL 这个变量管的是 Claude Code 内部那些轻量任务比如生成 commit message、标题、补全这类后台小活。如果不设置Claude Code 会默认去找它自己熟悉的 small fast model在接第三方 API 的情况下就会报 model not found。我最早接入时就漏了这一个变量排查半天你们别踩这个坑。配置完成后想切 R1 做深度推理可以在 claude 的交互界面里输入 /model 来切换模型也可以直接在环境变量里改 ANTHROPIC_MODEL 后重启。3.3 OpenCode 接入火山方舟的完整步骤OpenCode 的安装方式根据系统来。macOS 上推荐用 Homebrewbrew install sst/tap/opencodeLinux 或 macOS 也可以用官方安装脚本curl -fsSL https://opencode.ai/install | bashWindows 上可以通过 npm 安装 opencode-ai 包或者从 GitHub Releases 页面下载对应平台的压缩包解压后把可执行文件放到 PATH 里。装好之后编辑 opencode 的配置文件。先打开用户级配置目录填入自定义 provider{ $schema: https://opencode.ai/config.json, provider: { ark: { npm: ai-sdk/openai-compatible, name: Volcano Ark, options: { baseURL: https://ark.cn-beijing.volces.com/api/v3, apiKey: {env:ARK_API_KEY} }, models: { deepseek-v3-250324: { name: DeepSeek V3 }, deepseek-r1-250528: { name: DeepSeek R1 } } } } }同样需要导出 ARK_API_KEY 环境变量export ARK_API_KEY你的火山方舟API Key之后运行 opencode 进入交互界面在模型选择器里应该能看到 ark 这个 provider 下面列出的两个模型。如果默认 provider 不是 ark可以在 TUI 里用 /models 命令切换或者直接启动时指定opencode run --model ark/deepseek-v3-250324 解释一下这段代码的意图OpenCode 有个特点是对 AGENTS.md 这类项目说明文件很敏感它会自动读取项目上下文。这个能力和模型本身无关接火山方舟的模型后同样生效。如果你要用 OpenCode 的 Skills 能力也只需要在项目里放好技能描述文件模型会读取技能说明来执行不需要额外的 API 配置。3.4 三个工具配置对照速查表为了方便复查我把三个工具的关键配置项整理成一张表照着核对就能一眼看出哪里漏了。工具配置文件/变量API 地址值模型字段Token 变量Codex~/.codex/config.toml 的 base_urlhttps://ark.cn-beijing.volces.com/api/v3model 模型IDenv_key ARK_API_KEYClaude CodeANTHROPIC_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3/anthropicANTHROPIC_MODELANTHROPIC_AUTH_TOKENOpenCodeopencode.json 的 options.baseURLhttps://ark.cn-beijing.volces.com/api/v3models 节点下的模型 IDoptions.apiKey配置完成的验证方式也统一说一下Codex 跑 codex exec 11Claude Code 跑 claude -p 11OpenCode 跑 opencode run 11。三个都能正常返回 2说明链路全通。4. 常见问题与排查技巧实录4.1 认证报错401、403 和 auth token is unavailable这类报错是最常见的。现象各不相同但根源高度集中。Codex 报 codex auth token is unavailable多半是因为你根本没有设置任何 API key。Codex 默认设计是要扫一遍 OpenAI 的登录凭据如果找不到就报这个错。接第三方 API 的时候不要靠 codex login 登录而是要让 config.toml 里 provider 的 env_key 指向一个真实存在的环境变量并且确保运行 codex 的终端里已经 export 过了。注意环境变量名的大小写要严格一致我试过在 config.toml 里写 env_key ark_api_key但环境变量名是 ARK_API_KEY结果怎么都鉴权失败后来才发现是大小写不匹配。Claude Code 报 401 的时候优先检查 ANTHROPIC_AUTH_TOKEN 是否真的设置了以及是否误写成了 ANTHROPIC_API_KEY。很多人会凭直觉填后者但 Claude Code 只认前者。OpenCode 报 401检查 opencode.json 里的 apiKey 写法{env:ARK_API_KEY} 这个占位符格式不能写错如果直接写死字符串也是可以的但注意别把 key 提交到 git 仓库里。4.2 cc switch 报 local proxy failed 怎么处理这个报错最近问的人很多完整信息大概是 cc switch local proxy failed while handling codex endpoint /responses。先说这个报错的来龙去脉很多人会用 cc switch 这类图形化配置切换器来管理多个 API 服务切换器会在本机启动一个转发通道把 Codex 的请求转发到你选定的目标服务。Codex 新版默认请求的是 /responses 接口而一些切换器内部转发逻辑只覆盖了 /chat/completions于是 Codex 一发出请求转发通道就处理不了了。我的建议很简单直接放弃用切换器管 Codex。Codex 自己的 config.toml 已经足够简单切换模型或改 base_url 只需要改几个字段没必要为这个再养一个转发进程。如果你确实需要保留切换器用那就用我前面说的办法在 Codex 配置里把 wire_api 显式设置为 chat让 Codex 不要发 /responses而是发标准的 chat completions这样切换器的转发逻辑就没有障碍了。这个坑我踩过cc switch 的报错信息看着唬人实际就是 endpoint 兼容性的问题。4.3 Claude Code 报 model not found 或 400 Bad Request接火山方舟后 Claude Code 报模型不存在优先排查三件事。第一件ANTHROPIC_BASE_URL 是否填到了 /api/v3/anthropic 这一层。如果多填了一层 /v1或者少填了 /anthropic请求路径就错了Ark 那边会返回 404 或 400。第二件ANTHROPIC_MODEL 里的模型 ID 是否准确。DeepSeek 的模型 ID 是带日期版本的比如 deepseek-v3-250324别把 v3 和版本号写错。第三件ANTHROPIC_SMALL_FAST_MODEL 有没有设置。前面说过这个变量管的是内部轻量任务不设置的话Claude Code 会拿一个 Anthropic 专属小模型名去请求Ark 自然不认识。400 Bad Request 还有一种可能是请求里带了 Anthropic 版本头而你的模型或接入点不支持某些参数。这种时候可以去火山方舟控制台确认你用的模型是否开启了对应的推理能力也可以换个模型 ID 试试比如从 V3 切到 R1看看是不是模型本身的问题。4.4 OpenCode 报 free tier 相关错误如果你看到类似 error from provider (console): opencodes free tier can only be used from wi... 这样的报错说明你还在用 OpenCode 自带的托管通道而不是自己的 provider。OpenCode 有一个官方托管服务提供免费套餐但这个免费套餐和使用环境、账号状态绑定并不适合所有人都能顺畅使用。解决办法很直接不要再依赖 OpenCode 的托管通道把你自己的火山方舟 provider 设置为首选。在 opencode.json 里配置好 ark 这个 provider然后在交互界面里用 /models 切到 ark 下的模型或者启动时用 --model ark/deepseek-v3-250324 指定。这样请求就会走你自己的 API key和 OpenCode 的托管服务完全无关。另外提一嘴OpenCode 的付费套餐 opencode go 解决的是托管和便捷性问题既然你已经接了火山方舟就没必要再额外买套餐了。4.5 费用异常偏高的排查思路如果你发现跑几个任务之后费用涨得离谱不要急着怪模型先从这几个角度查。一是确认模型类型。DeepSeek R1 这类推理模型的思考 token 会全部计费你看到回复只有几百字但背后的思考过程可能已经消耗了几万 token。二是检查上下文长度。AI 编程工具每次请求都会携带项目文件内容项目越大单次请求的 token 越多费用自然涨。三是看工具调用轮数。一次代码修改任务可能要经历读取文件、修改文件、验证结果多轮交互每一轮都算一次 API 调用。四是设置告警。火山方舟控制台提供用量和告警配置建议设置一个每日或每月的费用阈值超出就告警别等到账单出来才后悔。我个人的使用习惯是日常小改动用 V3速度快、费用低复杂重构、跨文件改动用 R1虽然贵一点但推理能力确实能减少来回试错的次数整体算下来反而省。最后再说点实在的三套配置我都实际跑过几周最大的感受是接火山方舟这件事本身不复杂真正的成本在于理解和排查。Codex 的 wire_api、Claude Code 的 SMALL_FAST_MODEL、OpenCode 的 provider 声明每一个坑都是文档里不会专门提醒你的。我倒不是说这些文档写得不好而是接入第三方服务时工具默认行为和第三方兼容层之间总有几个对不上的地方只能是踩过一次才能记住。几个小建议收尾第一三个工具可以共用同一个 API key同一个模型 ID不存在冲突第二别在配置文件里直接写死 API key用环境变量引用方便随时切换第三工具的更新频率很高如果某天突然报错先看看是不是工具出了新版本顺手升个级往往就解决了。这套配置跑顺之后日常的代码生成、文件修改、项目重构基本就都在终端里完成了。剩下的就是找一个你觉得顺手的工具然后多写几个真实项目试试手。