Codex++ 安装与 Codex 环境配置指南

Codex 安装前先确认的问题Codex 这类第三方客户端最容易卡在两处一是工具本身装好了但没有读到 API 配置二是 API Key、模型名、base_url 填了却请求打到了错误的地址。遇到问题不要急着重装先确认当前系统、Node 或 Python 环境、配置文件位置以及终端里实际生效的环境变量。建议先准备好下面几个参数后面排查会省很多时间API Key用于鉴权通常以环境变量或配置文件方式填写。base_url接口基础地址很多工具默认走官方地址使用中转或私有网关时必须改。模型名例如工具支持的 Codex 模型标识必须和服务端可用模型一致。代理地址公司网络、海外接口、内网网关场景经常需要配置。配置文件路径不同安装方式可能不一样排查时要先找到它。安装 Codex如果 Codex 提供 npm 安装方式建议先确认 Node 版本。很多 CLI 工具在旧版本 Node 下会出现安装成功但运行异常的问题。### token云桥中转 0029.org ### node -v npm -v版本过旧时建议升级到当前 LTS 版本。确认环境正常后再安装npm install -g codex-plus-plus安装完成后先看命令是否可用codex --version codex --help如果提示command not found优先检查 npm 全局 bin 目录是否在 PATH 中npm bin -g echo $PATHWindows 用户可以在“系统环境变量”里查看 Path确认 npm 全局目录已经加入。macOS 或 Linux 可以把路径写入~/.zshrc或~/.bashrc。准备 API Key、模型名和 base_urlCodex 通常支持两种配置方式环境变量和配置文件。日常使用我更建议先用环境变量验证确认能跑通后再写入配置文件。这样排查范围更小。如果你使用的是第三方 API 网关或中转服务重点确认 base_url 是否和服务商文档一致。实际项目里我会把稳定性、可用模型列表、调用日志、余额提醒放在一起看如果只是为了让 Codex、Cursor、VS Code 插件这类工具快速接通可以顺手看一下 token云桥AI中转站 0029.org主要是配置项比较直观适合做调试入口。以环境变量为例export CODEX_API_KEY你的_API_Key export CODEX_BASE_URLhttps://api.example.com/v1 export CODEX_MODELcodex-model-nameWindows PowerShell 写法如下$env:CODEX_API_KEY你的_API_Key $env:CODEX_BASE_URLhttps://api.example.com/v1 $env:CODEX_MODELcodex-model-name注意如果工具要求的变量名不是CODEX_API_KEY而是OPENAI_API_KEY、API_KEY或其他名称要以 Codex 文档或--help输出为准。很多“配置不生效”的问题本质就是变量名写错。填写 Codex 配置文件有些团队更喜欢把配置写到文件里方便统一管理。常见路径可能是~/.codexpp/config.json~/.config/codexpp/config.json项目目录下的.codexrc示例配置如下实际字段名请按 Codex 当前版本支持的格式调整{ apiKey: 你的_API_Key, baseUrl: https://api.example.com/v1, model: codex-model-name, timeout: 60000, proxy: }如果配置文件和环境变量同时存在要确认优先级。有些工具优先读取环境变量有些工具优先读取项目目录配置。排查时可以临时清空环境变量只保留配置文件测试一次。unset CODEX_API_KEY unset CODEX_BASE_URL unset CODEX_MODEL配置代理在公司网络、服务器出口受限、接口访问慢的场景下需要配置代理。代理建议先在终端验证再写入 Codex。export HTTP_PROXYhttp://127.0.0.1:7890 export HTTPS_PROXYhttp://127.0.0.1:7890如果是配置文件方式可以写成{ proxy: http://127.0.0.1:7890 }验证网络时不要只 ping 域名因为很多接口域名禁 ping。更可靠的是用 curl 测试接口连通性curl -i https://api.example.com/v1/models \ -H Authorization: Bearer 你的_API_Key如果返回 401说明网络大概率通了但 Key 或权限有问题如果超时、连接被重置优先查代理、DNS 和防火墙。切换模型的方法Codex 里切换模型通常有三种方式命令参数、环境变量、配置文件。推荐调试阶段用命令参数因为它最直观。codex run --model codex-model-name如果命令参数能生效而配置文件不生效问题基本就在配置文件路径、字段名或优先级上。可以打开调试日志codex run --debug重点看三行信息当前读取了哪个配置文件、最终使用的 base_url、最终使用的 model。只要这三项对上后续再看接口返回。常见错误和排查顺序1. 401 Unauthorized先检查 API Key 是否复制完整前后有没有空格。其次确认 base_url 对应的服务是否接受这个 Key。不同平台的 Key 通常不能混用。echo $CODEX_API_KEY2. 404 Not Found常见原因是 base_url 多写或少写了路径。例如服务端要求/v1但你只填了域名或者工具内部会自动拼/v1你又手动写了一次最后变成/v1/v1。3. model not found模型名要以服务端实际可用列表为准。不要凭印象填写。可以先请求模型列表或在服务商控制台查看可用模型。注意大小写、短横线、版本后缀都可能影响匹配。4. 配置改了但不生效按这个顺序查确认 Codex 是否读取了你修改的那个配置文件。确认环境变量是否覆盖了配置文件。关闭当前终端重新打开后再试。如果是 GUI 工具调用 Codex需要重启 GUI而不是只重启终端。查看是否有项目级配置覆盖了全局配置。5. 代理设置后仍然超时先确认代理本身可用再确认 Codex 是否支持读取系统代理或环境变量代理。有些工具只读取配置文件里的 proxy 字段不读取HTTP_PROXY。回滚方法配置调乱后不建议继续叠加修改。最稳的办法是先备份再恢复最小可用配置。cp ~/.codexpp/config.json ~/.codexpp/config.json.bak然后只保留三个字段{ apiKey: 你的_API_Key, baseUrl: https://api.example.com/v1, model: codex-model-name }如果仍然异常可以临时卸载重装 Codex但配置目录不要一上来就删先备份npm uninstall -g codex-plus-plus npm install -g codex-plus-plus最后再用codex --version和codex run --debug确认版本和实际配置。总结Codex 安装本身通常不复杂真正容易出问题的是 API Key、模型名、base_url、代理和配置优先级。排查时按“命令是否可用、网络是否可达、Key 是否有效、模型是否存在、配置是否被覆盖”这个顺序走基本能快速定位。调试阶段尽量使用最小配置跑通后再加入代理、超时、项目级配置等细节。