Codex + 豆包/火山方舟配置

这一篇带你把 Codex 连接到火山方舟上的豆包模型。

火山方舟这篇最容易踩的坑是：你在控制台里看到的“豆包模型名称”和 API 调用时填的 model 不一定是同一个东西。很多情况下，API 里填的是 推理接入点 ID，也就是你在火山方舟控制台创建或选择的 Endpoint。

所以本篇重点不是背一个模型名，而是先搞清楚：

Base URL 是哪个
API Key 放哪里
推理接入点 ID 是哪个
Codex 配置里 model 应该填什么

前置教程：Codex + 智谱 GLM 配置
如果你还没有完整跑过“官方参数 -> 环境变量 -> 配置草稿 -> 只读验收”的流程，建议先完成前置教程，再回到本篇。

依据来源：OpenAI Codex 官方手册中的 Custom model providers、config.toml、环境变量认证说明；火山方舟官方文档中的 Base URL 及鉴权、对话 Chat API、兼容 OpenAI SDK、推理接入点说明。

本篇目标

跟着本篇做完后，你应该能做到：

从火山方舟官方文档确认 API Base URL。
分清“豆包模型”和“推理接入点 ID”。
创建或准备火山方舟 API Key。
找到可用的推理接入点 ID。
把 API Key 放到 Windows 环境变量 ARK_API_KEY。
让 Codex 生成火山方舟配置草稿。
写入配置后用最小对话和只读项目分析验收。
失败时能判断是 Key、Base URL、Endpoint、额度还是模型开通问题。

本篇不做什么

本篇不做这些事：

不讲火山方舟所有模型。
不评测豆包所有版本。
不让你把真实 API Key 发给 Codex。
不讲视频、图片、向量化、批量推理等接口。
不在配置未验收前让 Codex 修改业务代码。

本篇只解决一个目标：

让 Codex 可以通过火山方舟 Chat API 正常响应，并完成一次只读项目分析。

第 1 步：打开火山方舟官方文档

先打开火山方舟 API 参考：

https://www.volcengine.com/docs/82379/1541595

重点看这几个页面：

获取 API Key 并配置。
Base URL 及鉴权。
对话 Chat API。
兼容 OpenAI SDK。
管理推理接入点 Endpoint。

你要确认 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 和完整接口

火山方舟 OpenAI 兼容调用常见 Base URL 是：

https://ark.cn-beijing.volces.com/api/v3

对话接口完整路径会在这个 Base URL 后面拼接类似：

/chat/completions

所以 Codex 配置里建议写：

https://ark.cn-beijing.volces.com/api/v3

不要写成：

https://ark.cn-beijing.volces.com/api/v3/chat/completions

否则后续如果 Codex 或 provider 再拼路径，就可能请求到错误地址。

第 3 步：找到推理接入点 ID

这是火山方舟配置的核心。

你不要直接把模型写成：

doubao

也不要凭感觉写：

doubao-pro

你要进入火山方舟控制台，找到“推理接入点”或 Endpoint 管理页面，确认你要调用的接入点 ID。

这个 ID 可能长得像：

ep-xxxxxxxxxxxxxxxx

也可能是控制台里你创建或复制出来的其他 Endpoint 标识。

本篇后续用示例写法：

你的推理接入点 ID

你实际操作时要替换成自己的真实接入点 ID。

第 4 步：确认模型和接入点可用

在写 Codex 配置之前，先确认：

你已经开通火山方舟。
你已经有 API Key。
你已经创建或选择了推理接入点。
推理接入点对应的是适合文本/代码对话的模型。
账号有可用额度。
接入点没有被停用。

如果你还没有推理接入点，先不要继续写配置。

第 5 步：准备火山方舟 API Key

进入火山方舟控制台：

https://console.volcengine.com/ark/

你要做：

登录火山引擎账号。
进入火山方舟。
找到 API Key 管理入口。
创建或复制 API Key。
保存到安全位置。
确认账号有可用额度。

不要把 API Key 放到这些地方：

不要发给 Codex。
不要写进 Markdown。
不要发到微信。
不要截图露出完整 Key。
不要提交到 Git。

第 6 步：设置 Windows 环境变量

本篇建议环境变量名：

ARK_API_KEY

方法 A：用 Windows 图形界面设置

适合新手。

操作步骤：

按 Win 键。
搜索 环境变量。
打开“编辑系统环境变量”。
点击“环境变量”。
在“用户变量”区域点击“新建”。
变量名填写：

ARK_API_KEY

变量值填写你的真实火山方舟 API Key。
点击确定。
关闭所有设置窗口。
关闭当前 PowerShell。
重新打开一个新的 PowerShell。

方法 B：用 PowerShell 设置

适合熟悉 PowerShell 的用户。

打开 PowerShell，运行：

setx ARK_API_KEY "你的真实火山方舟 API Key"

注意：

引号里替换成你的真实 Key。
执行后关闭当前 PowerShell。
重新打开 PowerShell 才能读到新变量。

第 7 步：验证环境变量能读取

重新打开 PowerShell 后运行：

$env:ARK_API_KEY

如果能看到一串 Key，说明环境变量能读到。

截图时一定要遮住输出。

如果没有输出，先不要继续配置 Codex。

按顺序检查：

变量名是不是 ARK_API_KEY。
设置后有没有重开 PowerShell。
API Key 有没有复制完整。
你是不是在另一个 Windows 用户里启动了 Codex。

第 8 步：让 Codex 生成配置草稿

打开 Codex。

先不要让它直接写文件。

把下面这段复制给 Codex。注意把 你的推理接入点 ID 替换成你自己的 Endpoint ID：

我准备把 Codex 连接到火山方舟的 OpenAI 兼容 Chat API。

我已经从火山方舟官方文档和控制台确认：
- base_url：https://ark.cn-beijing.volces.com/api/v3
- model：你的推理接入点 ID
- API Key 环境变量名：ARK_API_KEY

要求：
1. 先不要修改任何文件。
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 字段；如果你不确定，请写“不确定”，不要编。
9. 请提醒我 model 应该填火山方舟推理接入点 ID，不要凭空写 doubao。

你希望 Codex 给出的草稿大概像这样：

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"

重点检查：

model 是你的推理接入点 ID。
model_provider 是 volcengine。
[model_providers.volcengine] 和 model_provider 对得上。
base_url 没有带 /chat/completions。
env_key 是 ARK_API_KEY，不是你的真实 Key。
没有凭空把模型名写成 doubao。

关于 wire_api 的说明

火山方舟官方文档提供 OpenAI SDK 兼容和 Chat API。

OpenAI Codex 官方手册说明自定义 provider 涉及 Base URL、wire API、认证和可选请求头；当前手册示例里的 wire_api 注释为 responses，并标注这是支持值。

所以本篇继续采用保守做法：

不要自己随便加 wire_api。
先让 Codex 根据当前版本解释是否需要。
最终用只读任务验收能不能跑通。

如果 Codex 要加 wire_api = "chat"，你要追问：

请说明你添加 wire_api = "chat" 的依据来自哪里。当前 Codex 官方手册是否支持这个值？如果没有明确依据，请不要添加。

第 9 步：让 Codex 写入配置

确认配置草稿没问题后，再发：

我确认火山方舟配置草稿可以继续。

请把 volcengine provider 写入 Codex 用户级配置文件。

要求：
1. 修改前先告诉我目标配置文件路径。
2. 只修改 Codex 配置文件。
3. 不要写入真实 API Key。
4. 只写入 env_key = "ARK_API_KEY"。
5. 如果配置文件不存在，请先说明将创建哪个文件。
6. 修改后展示 diff。
7. 用中文解释每一处变化。
8. 不要修改业务项目文件。

Windows 上 Codex 用户级配置一般位于：

C:\Users\你的用户名\.codex\config.toml

也可以理解成：

~\.codex\config.toml

如果你设置过 CODEX_HOME，让 Codex 先解释实际路径。

第 10 步：重启 Codex

配置文件和环境变量改完后，建议重新启动。

操作顺序：

退出当前 Codex。
关闭当前 PowerShell。
重新打开 PowerShell。
进入练习项目目录。
重新启动 Codex。

这样可以确保新环境变量和新配置都被读取。

第 11 步：做最小对话验证

进入 Codex 后，先发：

请只用一句中文回复：火山方舟配置验证开始。

如果能正常回复，说明模型调用链路有机会是通的。

如果这里失败，不要继续项目操作，先看错误信息。

第 12 步：做只读项目验证

最小对话能回复后，再做项目只读验证。

复制这段给 Codex：

请只读分析当前项目，不要修改任何文件，不要创建文件，不要删除文件。

请按下面格式输出：

## 1. 响应状态
- 你是否能正常响应：
- 如果你能判断，本次使用的模型/provider 是什么：
- 如果不能判断，请写“不能判断”：

## 2. 当前项目
- 当前目录：
- 是否像项目根目录：
- 判断依据：

## 3. 只读检查
- 你查看了哪些文件或目录：
- 有没有运行只读命令：
- 有没有修改文件：

## 4. 火山方舟配置提醒
- 当前 model 是否像推理接入点 ID：
- 如果接入点不存在，应该先查哪里：
- 如果账号无额度或 API Key 无效，应该先查哪里：

## 5. 下一步建议
- 如果配置正常，下一篇应该做什么：
- 如果配置异常，先查哪 3 件事：

你希望看到：

Codex 能正常输出。
它能读到当前项目路径。
它没有修改文件。
它能提醒 model 应该是推理接入点 ID。
它能说明不确定的地方。

第 13 步：确认没有改业务文件

继续让 Codex 检查：

请检查当前 Git 状态，确认这次火山方舟配置验证有没有修改业务项目文件。

要求：
1. 只运行只读检查。
2. 不要修改任何文件。
3. 如果工作区噪音较多，请列出变化文件，并说明这些变化是否和本次配置有关。

如果工作区干净，本篇验收更稳。

如果有变化，先截图，再让 Codex 解释 diff，先不要提交。

常见问题

问题 1：API Key 无效或 401

优先检查：

ARK_API_KEY 是否存在。
Key 是否复制完整。
Key 是否属于当前火山方舟账号。
账号是否有额度。
是否设置后没有重开 PowerShell。

可以问 Codex：

Codex 提示 ARK_API_KEY 相关错误。
请只读检查当前环境是否能读取这个环境变量。
不要显示完整 Key，只告诉我是否存在，以及长度是否大于 0。

问题 2：模型不存在或 endpoint not found

优先检查：

model 是否填的是推理接入点 ID。
推理接入点是否启用。
接入点对应模型是否可用。
账号是否有权限访问该接入点。
Base URL 是否写错。

不要把 model 随便写成：

doubao

可以问 Codex：

火山方舟返回 endpoint 或 model 不存在。
请不要修改配置，先列出我应该去火山方舟控制台确认的 5 个位置。

问题 3：Base URL 写成了完整接口

Codex 配置里建议写：

https://ark.cn-beijing.volces.com/api/v3

不要写成：

https://ark.cn-beijing.volces.com/api/v3/chat/completions

问题 4：能聊天，但代码任务效果不稳定

这不一定是配置错误。

可能原因：

推理接入点对应的模型不适合代码代理任务。
选的是轻量模型。
项目上下文太长。
提示词太模糊。
任务范围太大。
Codex 权限范围不够。

先用只读项目分析和单文件小改动验证，不要一上来重构。

本篇验收结果

做到这里，如果满足下面 8 条，就说明火山方舟配置教程完成：

你从火山方舟官方文档确认了 Base URL。
你知道 model 应该填推理接入点 ID。
你确认了推理接入点可用。
你把 API Key 放进了 ARK_API_KEY 环境变量。
Codex 配置文件没有出现真实 API Key。
Codex 能正常回复一句中文验证消息。
Codex 能完成一次只读项目分析。
Git 状态确认没有意外业务文件变化。

下一篇学什么

下一篇看：第一次让 Codex 阅读项目。

如果你想继续补齐国内模型系列，后面可以加一篇“国内模型配置排障总表”。

参考资料

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
火山方舟对话 Chat API：https://www.volcengine.com/docs/82379/1494384
火山方舟兼容 OpenAI SDK：https://www.volcengine.com/docs/82379/1330626