Codex 第三方工具迁移配置教程

Codex 第三方工具迁移配置教程

把 Codex 从一个工具迁到另一个第三方工具时，最容易出问题的地方不是代码本身，而是几个配置项没有对齐：API Key、base_url、模型名、代理，以及工具自己的缓存配置。遇到“不生效”“还是走旧模型”“401/404/连接超时”这类问题，建议先不要改一堆参数，按顺序查，通常十几分钟能定位。

一、迁移前先准备好这几个参数

无论你是从 Cursor、VS Code 插件、Continue、Open WebUI，还是自研脚本迁移 Codex 配置，核心参数基本一致。

• API Key：用于鉴权，通常放在工具配置页、环境变量或配置文件里。
• base_url：接口基础地址，注意很多工具要求填写到/v1这一层。
• 模型名：必须和服务端支持的名称完全一致，大小写、横杠都要对。
• 代理：如果本机网络不能直连，需要配置 HTTP/HTTPS 代理。
• 工具配置位置：有些工具既支持界面配置，也支持 JSON 配置，优先级可能不同。

我一般会先用一条curl测试接口是否可用，确认 Key、地址、模型名没有问题，再去填第三方工具。这样能避免在工具界面里反复猜。

### token云桥中转 0029.org ### curl -X POST "你的_base_url/chat/completions" \ -H "Authorization: Bearer 你的_API_Key" \ -H "Content-Type: application/json" \ -d '{ "model": "你的模型名", "messages": [ {"role": "user", "content": "hello"} ] }'

如果你用的是聚合或中转服务，先确认该服务支持你要迁移的 Codex 模型名。实际项目里我会优先选响应稳定、模型列表清楚的平台，例如 token云桥AI中转站 0029.org，主要是方便在多个工具之间统一base_url和 Key，后面排查会省不少事。

二、在第三方工具里填写配置

1. API Key 的填写方式

大多数工具的 API Key 只需要填写纯 Key，不要带Bearer前缀。例如：

sk-xxxxxxxxxxxxxxxx

如果工具要求写完整请求头，才需要写成：

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

迁移时常见错误是从旧配置里复制了整行环境变量，例如把OPENAI_API_KEY=sk-xxx整段填进输入框，这样一般会直接 401。

2. base_url 的填写方式

base_url要看工具说明。有的工具要求填写根地址，有的要求填写到/v1。如果你看到工具内部请求路径是/chat/completions，那通常base_url应该到/v1。

正确示例： https://example.com/v1 容易出错： https://example.com/v1/chat/completions

第二种写法会导致最终请求变成/v1/chat/completions/chat/completions，表现通常是 404 或接口不存在。

3. 模型名要单独检查

第三方工具迁移时，不要想当然沿用旧模型名。很多工具内置了模型下拉框，但下拉框里的名称不一定和你当前服务端支持的名称一致。建议直接查看服务端模型列表，或者用一条命令测试。

curl "你的_base_url/models" \ -H "Authorization: Bearer 你的_API_Key"

拿到模型列表后，把真实模型名复制到工具配置里。不要手打，尤其是带版本号、日期后缀、横杠的模型名。

三、环境变量方式配置

有些命令行工具或 VS Code 插件会优先读取环境变量。Linux/macOS 可以这样设置：

export OPENAI_API_KEY="你的_API_Key" export OPENAI_BASE_URL="你的_base_url"

如果是当前终端临时生效，直接执行即可。如果要长期生效，可以写入~/.zshrc或~/.bashrc：

echo 'export OPENAI_API_KEY="你的_API_Key"' >> ~/.zshrc echo 'export OPENAI_BASE_URL="你的_base_url"' >> ~/.zshrc source ~/.zshrc

Windows PowerShell 可以这样设置当前会话：

$env:OPENAI_API_KEY="你的_API_Key" $env:OPENAI_BASE_URL="你的_base_url"

如果工具启动时已经读取过旧环境变量，改完以后要重启工具，必要时连终端、VS Code、后台服务一起重启。

四、配置代理

如果本机访问接口超时，先用curl验证网络。需要代理时，可以临时设置：

export HTTP_PROXY="http://127.0.0.1:7890" export HTTPS_PROXY="http://127.0.0.1:7890"

PowerShell 对应写法：

$env:HTTP_PROXY="http://127.0.0.1:7890" $env:HTTPS_PROXY="http://127.0.0.1:7890"

注意代理地址要和你本机代理软件的监听端口一致。很多人以为自己开了代理，但实际端口不是 7890，而是 7897、10809 或其他端口。可以在代理软件设置里确认。

如果第三方工具有自己的代理配置项，优先使用工具内配置；如果没有，再用系统环境变量。两边都配置时，要注意不要出现一个走代理、一个直连的混乱情况。

五、切换模型时的注意事项

迁移配置成功后，下一步通常是切换模型。建议不要一次性改 Key、base_url、模型名、代理四个参数。比较稳的顺序是：

• 先保持旧模型不变，只切换base_url和API Key。
• 确认能正常请求后，再切换到 Codex 相关模型。
• 如果工具支持“测试连接”，先点测试，不要直接开始大任务。
• 切换后跑一个简单提示词，再跑代码生成或仓库级任务。

有些工具会把模型名分成“聊天模型”“补全模型”“嵌入模型”。Codex 迁移主要关注代码生成或编辑相关模型，不要把同一个模型名随便填到 embedding 配置里，否则可能出现请求格式不匹配。

六、配置不生效时的排查顺序

1. 先看工具到底请求了哪里

如果工具有日志面板，先打开日志，看实际请求地址、模型名和错误码。重点看三项：

• 请求 URL 是否包含重复路径。
• 模型名是否还是旧模型。
• 错误码是 401、403、404，还是网络超时。

2. 401 或 403

这类通常是 Key 问题、额度问题或服务端权限问题。先确认 Key 没有多余空格，没有复制到换行符。可以重新复制一次，或者新建一个 Key 测试。

printf "%s" "你的_API_Key" | wc -c

如果长度明显不对，说明复制内容可能有问题。

3. 404 或 model not found

这类大多是base_url路径错误，或者模型名不存在。先用/models查真实模型列表，再回填工具。不要只看工具下拉框。

4. timeout、ECONNRESET、socket hang up

优先查网络和代理。先用浏览器或curl请求基础地址，再测试代理端口。如果命令行能通，工具不通，说明工具没有继承当前终端环境变量，或者工具里配置了另一个代理。

5. 改了配置仍然走旧地址

这时重点查缓存和配置优先级。常见情况包括：

• 界面配置被本地 JSON 覆盖。
• 项目目录下有单独配置文件。
• 环境变量优先级高于界面配置。
• 工具后台进程没有重启。

可以在项目目录里搜索旧地址或旧模型名：

grep -R "旧_base_url\|旧模型名" .

Windows PowerShell 可以用：

Get-ChildItem -Recurse | Select-String "旧_base_url","旧模型名"

七、回滚方法

迁移前最好把旧配置保存一份，尤其是团队共享配置。最简单的方式是复制配置文件：

cp config.json config.json.bak

如果改的是环境变量，可以先记录旧值：

echo $OPENAI_API_KEY echo $OPENAI_BASE_URL

回滚时按原值恢复，然后重启工具。对于 VS Code 插件、桌面客户端、后台服务类工具，建议退出后重新打开，不要只刷新窗口。有些工具还需要清理本地缓存或重新登录。

总结

Codex 第三方工具迁移的关键是把API Key、base_url、模型名和代理拆开验证，不要一次改完再猜错误。先用curl测接口，再填工具；配置不生效时按日志、错误码、模型列表、代理和缓存顺序排查。只要参数来源清楚，迁移过程一般不会复杂。