Codex 简介¶

🚀 核心特性¶

• Agentic 编程能力：能够根据任务自主分析代码库、制定修改方案、编辑文件并验证结果，而不仅仅是进行代码问答。
• 本地项目操作：可以直接读取和修改当前项目文件，并调用 Shell 命令、Git、测试框架和其他开发工具。
• 自动测试与修复：能够在修改代码后运行测试，根据报错继续修复，形成“分析—执行—验证”的工作循环。
• 灵活的模型配置：支持 OpenAI 官方服务，也可以通过 model_providers 配置兼容 OpenAI Responses API 的第三方或自建 API 服务。
• 多配置切换：支持通过模型参数或 Profile 在不同模型、不同 API Provider 之间快速切换。

📋 安装¶

请优先参考 OpenAI Codex 官方文档。

这里以 Ubuntu / WSL 环境为例。

安装 Node.js¶

Codex 可以通过 npm 安装，因此首先需要安装较新的 Node.js 环境。

如果系统已经安装 Node.js，可以先查看版本：

node -v
npm -v

建议使用较新的 Node.js LTS 版本，例如 Node.js 22。

如果已经安装 fnm，可以直接创建并启用 Node.js 22 环境：

fnm install 22
fnm default 22
fnm use 22

如果由于网络问题无法安装 fnm，也可以直接通过 NodeSource 安装：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

安装完成后确认版本：

node -v
npm -v

安装 Codex¶

通过 npm 全局安装：

npm install -g @openai/codex

如果当前 Node.js 是系统级安装，可能需要：

sudo npm install -g @openai/codex

安装完成后检查：

codex --version

alias proxy_on='export http_proxy="http://10.66.0.101:7890"; export https_proxy="http://10.66.0.101:7890"'
alias proxy_off='unset http_proxy; unset https_proxy'

proxy_on

proxy_off

配置大模型¶

Codex 默认可以使用 OpenAI 官方服务，也支持通过 ~/.codex/config.toml 自定义模型服务。

这里以 New API 中转服务 为例。

首先创建配置目录：

mkdir -p ~/.codex
nano ~/.codex/config.toml

加入以下配置：

model = "gpt-5.6-sol"
model_provider = "newapi"

[model_providers.newapi]
name = "New API"
base_url = "https://api.iomics.pro/v1"
env_key = "NEWAPI_API_KEY"
wire_api = "responses"

其中：

• model：New API 中实际提供的模型名称。
• model_provider：指定当前使用的 Provider。
• base_url：New API 的 OpenAI 兼容接口地址。
• env_key：保存 API Key 的**环境变量名称**，这里不能直接填写 API Key。
• wire_api = "responses"：使用 OpenAI Responses API。

env_key = "sk-xxxxxxxx"

Missing environment variable: sk-xxxxxxxx

env_key = "NEWAPI_API_KEY"

配置 API Key¶

临时配置：

export NEWAPI_API_KEY="sk-xxxxxxxxxxxxxxxx"

然后运行：

codex

确认能够正常使用后，可以永久写入：

vi ~/.bashrc

加入：

export NEWAPI_API_KEY="sk-xxxxxxxxxxxxxxxx"

重新加载环境变量：

source ~/.bashrc

env_key = "NEWAPI_API_KEY"

测试 New API¶

Codex 使用 Responses API，因此中转服务需要支持类似：

POST /v1/responses

可以通过 curl 进行简单测试：

curl https://api.iomics.pro/v1/responses \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Reply only with OK"
  }'

如果接口正常，会返回 JSON 格式的模型结果。

多模型配置¶

config.toml 中的：

model = "gpt-5.6-sol"

只是默认模型，并不代表 Codex 只能使用这个模型。New API 中同时提供多个模型，可以启动时临时指定：

codex -m gpt-5.6-sol

或者：

codex -m Qwen3.8-27B

因此同一个 Provider 可以对应多个模型：

New API
├── gpt-5.6-sol
├── GPT 系列模型
├── Qwen 系列模型
└── 其他兼容 Responses API 的模型

使用 Profile 管理多个模型¶

如果经常在多个模型之间切换，可以在配置中创建 Profile。

例如：

[model_providers.newapi]
name = "New API"
base_url = "https://api.iomics.pro/v1"
env_key = "NEWAPI_API_KEY"
wire_api = "responses"

[profiles.gpt]
model_provider = "newapi"
model = "gpt-5.6-sol"

[profiles.qwen]
model_provider = "newapi"
model = "qwen3-coder"

然后启动时选择：

codex --profile gpt

或者：

codex --profile qwen

这种方式比较适合同时维护多个项目或者经常切换模型的场景。

启动 Codex¶

进入项目根目录：

cd ~/projects/my-project

直接运行：

codex

Codex 会读取当前目录中的项目代码，并进入交互式 Agent 界面。

如果需要指定模型：

codex -m gpt-5.6-sol

如果已经配置 Profile：

codex --profile gpt

常用启动方式¶

默认启动¶

codex

指定模型¶

codex -m gpt-5.6-sol

指定 Profile¶

codex --profile gpt

直接提交任务¶

codex "分析当前项目结构并给出优化建议"

非交互式执行¶

codex exec "检查当前项目中的测试失败原因"

推荐目录结构¶

对于 WSL 环境，建议将代码项目直接放在 Linux 文件系统中，例如：

~/projects/
├── project-a/
├── project-b/
└── project-c/

然后：

cd ~/projects/project-a
codex

相比：

/mnt/c/
/mnt/d/

Linux 文件系统在大量小文件、Git、Node.js 和 Python 环境操作中通常更加合适。

大型数据文件则可以继续保存在 Windows 磁盘、NAS 或服务器存储中。

与 HAPI 配合使用¶

如果已经安装 HAPI，可以通过 HAPI 启动 Codex：

hapi codex

建议先确认直接运行：

codex

能够正常连接 New API，再配置 HAPI。

整体调用关系为：

HAPI
  ↓
Codex
  ↓
~/.codex/config.toml
  ↓
New API
  ↓
大语言模型

这样 HAPI 不需要单独维护一份模型 API 配置，Codex 仍然统一读取自己的 Provider 和模型配置。