什么是 Codex

Codex 是 OpenAI 推出的 AI 编码工具，可以把任务委托给云端或本地的编码代理来执行。支持 CLI 命令行、VS Code 插件、Cursor 插件等使用方式。

官网：https://openai.com/zh-Hans-CN/codex/

系统要求

  • Node.js 22+
  • 支持 macOS / Linux / Windows

安装

任选一种方式：

npm（通用）：

npm i -g @openai/codex
codex --version

Homebrew（macOS 推荐）：

brew update
brew install codex
codex --version

配置

1. 获取 API Key

如果你有 OpenAI Plus 会员，可以直接登录使用，跳过此步。

否则需要一个第三方 API 中转平台，注册后在「令牌管理」页面复制 sk-xxxx 格式的 API Key。

2. 编写配置文件

Codex 启动时读取 ~/.codex/config.toml，不存在就新建：

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

写入以下配置：

model_provider = "custom"
model = "gpt-5"
model_reasoning_effort = "low"  # minimal / low / medium(默认) / high

[model_providers.custom]
name = "Custom API"
base_url = "https://your-api-endpoint.com/v1"
env_key = "CODEX_API_KEY"
wire_api = "chat"
query_params = {}
request_max_retries = 4
stream_max_retries = 10

[profiles.custom]
model_provider = "custom"
model = "gpt-5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
根据你的 API 平台修改 baseurl，envkey 是环境变量名。

3. 设置环境变量

Windows：

# 永久（推荐）
setx CODEX_API_KEY "sk-xxxxxx"

# 临时
set CODEX_API_KEY=sk-xxxxxx

macOS / Linux：

# zsh（macOS 默认）
echo 'export CODEX_API_KEY="sk-xxxxxx"' >> ~/.zshrc
source ~/.zshrc

# bash
echo 'export CODEX_API_KEY="sk-xxxxxx"' >> ~/.bashrc
source ~/.bashrc

验证：

# Windows CMD
echo %CODEX_API_KEY%

# macOS/Linux
echo $CODEX_API_KEY

显示 sk-xxxxxx 即成功。

使用

CLI 命令行

# 直接提问
codex "你好"

# 指定 provider
codex --profile custom "帮我写一个排序算法"

VS Code 插件

配置好后完全退出 VS Code 重新启动才能生效。

高级用法

CI/CD 集成

在 GitHub Actions 中无头运行：

- name: Update changelog via Codex
  run: |
    npm install -g @openai/codex
    export CODEX_API_KEY="${{ secrets.CODEX_KEY }}"
    codex exec --full-auto "update CHANGELOG for next release"

MCP 服务器

在 config.toml 中配置 MCP 扩展：

[mcp_servers.server-name]
command = "npx"
args = ["-y", "mcp-server"]
env = { "API_KEY" = "value" }

参考