> 想少折腾？ 接入国内大模型推荐先看 Codex + DeepSeek 配置：用 Codex++ 图形界面一键切换模型，本篇模型照着同样方式配置即可。
> 协议状态（2026-08 核对）： 火山方舟官方文档已经提供 https://ark.cn-beijing.volces.com/api/v3/responses，Codex 自定义 provider 可以使用 wire_api = "responses"。模型与套餐的实际可用范围仍以控制台为准。
这一篇带你把 Codex 连接到 火山方舟 上的 豆包 模型。
火山方舟这篇最容易踩的坑是：你在控制台里看到的“豆包模型名称”和 API 调用时填的 model 不一定是同一个东西。很多情况下，API 里填的是 推理接入点 ID，也就是你在火山方舟控制台创建或选择的 Endpoint。
所以本篇重点不是背一个模型名，而是先搞清楚：
``text
Base URL 是哪个
API Key 放哪里
推理接入点 ID 是哪个
Codex 配置里 model 应该填什么
`
> 前置教程：Codex + 智谱 GLM 配置
> 如果你还没有完整跑过“官方参数 -> 环境变量 -> 配置草稿 -> 只读验收”的流程，建议先完成前置教程，再回到本篇。
> 依据来源：OpenAI Codex 官方手册中的 Custom model providers、config.toml、环境变量认证说明；火山方舟官方 Responses API、Base URL、鉴权和模型说明。
跟着本篇做完后，你应该能做到：
- 从火山方舟官方文档确认 API Base URL。
- 不讲火山方舟所有模型。
- 不评测豆包所有版本。
- 不让你把真实 API Key 发给 Codex。
- 不讲视频、图片、向量化、批量推理等接口。
- 不在配置未验收前让 Codex 修改业务代码。
- 获取 API Key 并配置。
- Base URL 及鉴权。
- Responses API。
- 兼容 OpenAI SDK。
- 管理推理接入点 Endpoint。
- 你已经开通火山方舟。
- 登录火山引擎账号。
- 不要发给 Codex。
- 不要写进 Markdown。
- 不要发到微信。
- 不要截图露出完整 Key。
- 不要提交到 Git。
- 按 Win
键。 - 变量值填写你的真实火山方舟 API Key。
- 引号里替换成你的真实 Key。
- 执行后关闭当前 PowerShell。
- 重新打开 PowerShell 才能读到新变量。
- 变量名是不是 ARK_API_KEY
。 - base_url：https://ark.cn-beijing.volces.com/api/v3
- model：你的推理接入点 ID
- API Key 环境变量名：ARK_API_KEY
- 先不要修改任何文件。
- model
是你的推理接入点 ID。 - model_provider
是volcengine。 - [model_providers.volcengine]
和model_provider对得上。 - base_url
只写到/api/v3，Codex 会按 Responses API 请求/responses。 - env_key
是ARK_API_KEY，不是你的真实 Key。 - 没有凭空把模型名写成 doubao
。 - 修改前先告诉我目标配置文件路径。
- 退出当前 Codex。
- 你是否能正常响应：
- 如果你能判断，本次使用的模型/provider 是什么：
- 如果不能判断，请写“不能判断”：
- 当前目录：
- 是否像项目根目录：
- 判断依据：
- 你查看了哪些文件或目录：
- 有没有运行只读命令：
- 有没有修改文件：
- 当前 model 是否像推理接入点 ID：
- 如果接入点不存在，应该先查哪里：
- 如果账号无额度或 API Key 无效，应该先查哪里：
- 如果配置正常，下一篇应该做什么：
- 如果配置异常，先查哪 3 件事：
- Codex 能正常输出。
- 它能读到当前项目路径。
- 它没有修改文件。
- 它能提醒 model 应该是推理接入点 ID。
- 它能说明不确定的地方。
- 只运行只读检查。
- ARK_API_KEY
是否存在。 - model
是否填的是推理接入点 ID。 - 推理接入点对应的模型不适合代码代理任务。
- 选的是轻量模型。
- 项目上下文太长。
- 提示词太模糊。
- 任务范围太大。
- Codex 权限范围不够。
- 你从 火山方舟 官方文档确认了 Base URL。
- OpenAI Codex 官方手册：https://developers.openai.com/codex/codex-manual.md
- 火山方舟 API 参考：https://www.volcengine.com/docs/82379/1541595
- 火山方舟 Base URL 及鉴权：https://www.volcengine.com/docs/82379/1298459
- 火山方舟 Responses API：https://www.volcengine.com/docs/82379/1958524
- 火山方舟兼容 OpenAI SDK：https://www.volcengine.com/docs/82379/1330626`
2. 分清“豆包模型”和“推理接入点 ID”。
3. 创建或准备火山方舟 API Key。
4. 找到可用的推理接入点 ID。
5. 把 API Key 放到 Windows 环境变量 ARK_API_KEY。
6. 让 Codex 生成火山方舟配置草稿。
7. 写入配置后用最小对话和只读项目分析验收。
8. 失败时能判断是 Key、Base URL、Endpoint、额度还是模型开通问题。
本篇不做这些事：
本篇只解决一个目标：
`text
让 Codex 可以通过火山方舟 Responses API 正常响应，并完成一次只读项目分析。
`
先打开 火山方舟 API 参考：
`text
https://www.volcengine.com/docs/82379/1541595
`
重点看这几个页面：
你要确认 4 件事：
| 要确认的信息 | 本篇采用值 | 你要记下什么 |
| -------- | ---------------------------------------- | ------------ |
| Base URL | https://ark.cn-beijing.volces.com/api/v3 | Codex 配置里写这个 |
| 鉴权方式 | Bearer API Key | 需要 API Key |
| model 参数 | 推理接入点 ID | 从控制台复制，不要自己猜 |
| 环境变量名 | ARK\_API\_KEY | 本篇使用这个变量名 |
第 2 步：理解 Base URL 和完整接口
Section titled “第 2 步：理解 Base URL 和完整接口”
火山方舟 OpenAI 兼容调用常见 Base URL 是：
`text
https://ark.cn-beijing.volces.com/api/v3
`
对话接口完整路径会在这个 Base URL 后面拼接类似：
`text
/chat/completions
`
所以 Codex 配置里建议写：
`text
https://ark.cn-beijing.volces.com/api/v3
`
不要写成：
`text
https://ark.cn-beijing.volces.com/api/v3/chat/completions
`
否则后续如果 Codex 或 provider 再拼路径，就可能请求到错误地址。
这是火山方舟配置的核心。
你不要直接把模型写成：
`text
doubao
`
也不要凭感觉写：
`text
doubao-pro
`
你要进入火山方舟控制台，找到“推理接入点”或 Endpoint 管理页面，确认你要调用的接入点 ID。
这个 ID 可能长得像：
`text
ep-xxxxxxxxxxxxxxxx
`
也可能是控制台里你创建或复制出来的其他 Endpoint 标识。
本篇后续用示例写法：
`text
你的推理接入点 ID
`
你实际操作时要替换成自己的真实接入点 ID。
在写 Codex 配置之前，先确认：
2. 你已经有 API Key。
3. 你已经创建或选择了推理接入点。
4. 推理接入点对应的是适合文本/代码对话的模型。
5. 账号有可用额度。
6. 接入点没有被停用。
如果你还没有推理接入点，先不要继续写配置。
第 5 步：准备 火山方舟 API Key
Section titled “第 5 步：准备 火山方舟 API Key”
进入火山方舟控制台：
`text
https://console.volcengine.com/ark/
`
你要做：
2. 进入火山方舟。
3. 找到 API Key 管理入口。
4. 创建或复制 API Key。
5. 保存到安全位置。
6. 确认账号有可用额度。
不要把 API Key 放到这些地方：
第 6 步：设置 Windows 环境变量
Section titled “第 6 步：设置 Windows 环境变量”
本篇建议环境变量名：
`text
ARK_API_KEY
`
方法 A：用 Windows 图形界面设置
Section titled “方法 A：用 Windows 图形界面设置”
适合新手。
操作步骤：
2. 搜索 环境变量。
3. 打开“编辑系统环境变量”。
4. 点击“环境变量”。
5. 在“用户变量”区域点击“新建”。
6. 变量名填写：
`text
ARK_API_KEY
`
2. 点击确定。
3. 关闭所有设置窗口。
4. 关闭当前 PowerShell。
5. 重新打开一个新的 PowerShell。
方法 B：用 PowerShell 设置
Section titled “方法 B：用 PowerShell 设置”
适合熟悉 PowerShell 的用户。
打开 PowerShell，运行：
`powershell
setx ARK_API_KEY "你的真实火山方舟 API Key"
`
注意：
重新打开 PowerShell 后运行：
`powershell
$env:ARK_API_KEY
`
如果能看到一串 Key，说明环境变量能读到。
截图时一定要遮住输出。
如果没有输出，先不要继续配置 Codex。
按顺序检查：
2. 设置后有没有重开 PowerShell。
3. API Key 有没有复制完整。
4. 你是不是在另一个 Windows 用户里启动了 Codex。
第 8 步：让 Codex 生成配置草稿
Section titled “第 8 步：让 Codex 生成配置草稿”
打开 Codex。
先不要让它直接写文件。
把下面这段复制给 Codex。注意把 你的推理接入点 ID 替换成你自己的 Endpoint ID：
`text
我准备把 Codex 连接到火山方舟的 Responses API。
我已经从火山方舟官方文档和控制台确认：
要求：
2. 不要让我把真实 API Key 发给你。
3. 请根据当前 Codex 官方配置方式，给出 config.toml 配置草稿。
4. provider_id 使用 volcengine。
5. 配置里只能写环境变量名，不能写真实 API Key。
6. base_url 只写到 /api/v3，不要写完整 /chat/completions。
7. 请解释每一行配置是什么意思。
8. 明确写入 wire_api = "responses"，不要使用 chat。
9. 请提醒我 model 应该填火山方舟推理接入点 ID，不要凭空写 doubao。
`
你希望 Codex 给出的草稿大概像这样：
`toml
model = "你的推理接入点 ID"
model_provider = "volcengine"
[model_providers.volcengine]
name = "Volcengine Ark / Doubao"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "ARK_API_KEY"
wire_api = "responses"
`
重点检查：
火山方舟官方文档已经给出 /api/v3/responses 以及 OpenAI SDK 的 client.responses.create(...) 示例；Codex 自定义 provider 也使用 Responses wire API。因此这里应明确写：
`toml
wire_api = "responses"
`
确认配置草稿没问题后，再发：
`text
我确认火山方舟配置草稿可以继续。
请把 volcengine provider 写入 Codex 用户级配置文件。
要求：
2. 只修改 Codex 配置文件。
3. 不要写入真实 API Key。
4. 只写入 env_key = "ARK_API_KEY"。
5. 如果配置文件不存在，请先说明将创建哪个文件。
6. 修改后展示 diff。
7. 用中文解释每一处变化。
8. 不要修改业务项目文件。
`
Windows 上 Codex 用户级配置一般位于：
`text
C:\Users\你的用户名\.codex\config.toml
`
也可以理解成：
`text
~\.codex\config.toml
`
如果你设置过 CODEX_HOME，让 Codex 先解释实际路径。
配置文件和环境变量改完后，建议重新启动。
操作顺序：
2. 关闭当前 PowerShell。
3. 重新打开 PowerShell。
4. 进入练习项目目录。
5. 重新启动 Codex。
这样可以确保新环境变量 and 新配置都被读取。
进入 Codex 后，先发：
`text
请只用一句中文回复：火山方舟配置验证开始。
`
如果能正常回复，说明模型调用链路有机会是通的。
如果这里失败，不要继续项目操作，先看错误信息。
最小对话能回复后，再做项目只读验证。
复制这段给 Codex：
`text
请只读分析当前项目，不要修改任何文件，不要创建文件，不要删除文件。
请按下面格式输出：
1. 响应状态
2. 当前项目
3. 只读检查
4. 火山方舟配置提醒
5. 下一步建议
`
你希望看到：
继续让 Codex 检查：
`text
请检查当前 Git 状态，确认这次火山方舟配置验证有没有修改业务项目文件。
要求：
2. 不要修改任何文件。
3. 如果工作区噪音较多，请列出变化文件，并说明这些变化是否和本次配置有关。
`
如果工作区干净，本篇验收更稳。
如果有变化，先截图，再让 Codex 解释 diff，先不要提交。
问题 1：API Key 无效或 401
Section titled “问题 1：API Key 无效或 401”
优先检查：
2. Key 是否复制完整。
3. Key 是否属于当前火山方舟账号。
4. 账号是否有额度。
5. 是否设置后没有重开 PowerShell。
可以问 Codex：
`text
Codex 提示 ARK_API_KEY 相关错误。
请只读检查当前环境是否能读取这个环境变量。
不要显示完整 Key，只告诉我是否存在，以及长度是否大于 0。
`
问题 2：模型不存在或 endpoint not found
Section titled “问题 2：模型不存在或 endpoint not found”
优先检查：
2. 推理接入点是否启用。
3. 接入点对应模型是否可用。
4. 账号是否有权限访问该接入点。
5. Base URL 是否写错。
不要把 model 随便写成：
`text
doubao
`
可以问 Codex：
`text
火山方舟返回 endpoint 或 model 不存在。
请不要修改配置，先列出我应该去火山方舟控制台确认的 5 个位置。
`
问题 3：Base URL 写成了完整接口
Section titled “问题 3：Base URL 写成了完整接口”
Codex 配置里建议写：
`text
https://ark.cn-beijing.volces.com/api/v3
`
不要写成：
`text
https://ark.cn-beijing.volces.com/api/v3/chat/completions
`
问题 4：能聊天，但代码任务效果不稳定
Section titled “问题 4：能聊天，但代码任务效果不稳定”
这不一定是配置错误。
可能原因：
先用只读项目分析和单文件小改动验证，不要一上来重构。
做到这里，如果满足下面 8 条，就说明火山方舟配置教程完成：
2. 你知道 model 应该填推理接入点 ID.
3. 你确认了推理接入点可用。
4. 你把 API Key 放进了 ARK_API_KEY 环境变量。
5. Codex 配置文件没有出现真实 API Key。
6. Codex 能正常回复一句中文验证消息。
7. Codex 能完成一次只读项目分析。
8. Git 状态确认没有意外业务文件变化。
下一篇看：第一次让 Codex 阅读项目。
如果你想继续补齐国内模型系列，后面可以加一篇“国内模型配置排障总表”。