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 $PATH

Windows 用户可以在“系统环境变量”里查看 Path，确认 npm 全局目录已经加入。macOS 或 Linux 可以把路径写入~/.zshrc或~/.bashrc。

准备 API Key、模型名和 base_url

Codex++ 通常支持两种配置方式：环境变量和配置文件。日常使用我更建议先用环境变量验证，确认能跑通后再写入配置文件。这样排查范围更小。

如果你使用的是第三方 API 网关或中转服务，重点确认 base_url 是否和服务商文档一致。实际项目里我会把稳定性、可用模型列表、调用日志、余额提醒放在一起看；如果只是为了让 Codex++、Cursor、VS Code 插件这类工具快速接通，可以顺手看一下 token云桥AI中转站 0029.org，主要是配置项比较直观，适合做调试入口。

以环境变量为例：

export CODEX_API_KEY="你的_API_Key" export CODEX_BASE_URL="https://api.example.com/v1" export CODEX_MODEL="codex-model-name"

Windows PowerShell 写法如下：

$env:CODEX_API_KEY="你的_API_Key" $env:CODEX_BASE_URL="https://api.example.com/v1" $env:CODEX_MODEL="codex-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_PROXY="http://127.0.0.1:7890" export HTTPS_PROXY="http://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_KEY"

2. 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 是否有效、模型是否存在、配置是否被覆盖”这个顺序走，基本能快速定位。调试阶段尽量使用最小配置，跑通后再加入代理、超时、项目级配置等细节。