07. 安装 OpenAI Codex CLI

本章定位:Codex 是 OpenAI 在 2025 年发布的"终端原生"AI 编程 Agent,与 Claude Code 定位相似但生态完全不同。本章帮你装上 Codex,不是为了取代 Claude Code,而是多一个工具可选——下一章 08. Codex 与 Claude Code 使用对比 会讲两者的差异与适用场景。

🔒 安全提示:本文档所有示例中的 YOUR_API_KEY / sk-xxx 都为占位符。绝不要把真实 API Key 提交到 Git 仓库或公开文档。

一、Codex 是什么

OpenAI Codex CLI(下文简称 Codex)是 OpenAI 在 2025 年 4 月发布的命令行 AI 编程助手,与 Claude Code 同类:

维度Claude CodeCodex CLI
厂商AnthropicOpenAI
形态终端 CLI终端 CLI
默认模型Claude 系列GPT 系列(o3 / GPT-5 系列)
生态Skills / MCP / WorkflowSkills(同名,机制不同) / MCP / Workflow
官网claude.ai/codeopenai.com/codex

直观理解:Claude Code 是 Anthropic 的终端 Agent,Codex 是 OpenAI 的终端 Agent。两者解决的痛点相同——让 AI 读你电脑上的文件、改文件、跑命令——但默认接的是不同厂商的模型。

二、系统要求

项目最低要求
操作系统macOS 12+、Ubuntu 20.04+、Windows 11(WSL2 推荐)
Node.js22.0+(Codex CLI 比 Claude Code 要求略高)
内存8GB+
网络可访问 OpenAI API(国内网络需要走代理)
OpenAI 账号ChatGPT Plus/Pro/Team 订阅 或 OpenAI Platform API Key

版本说明:Codex CLI 处于快速迭代期,本章内容以 2026 年春季的稳定版本为准。运行 codex --version 后,若版本号与本文差异较大,部分命令可能变化,请到 官方文档 对照。

三、安装步骤

macOS / Linux

# 推荐:官方安装脚本
curl -fsSL https://raw.githubusercontent.com/openai/codex/main/install.sh | bash

# 或使用 npm
npm install -g @openai/codex

# 或使用 Homebrew(macOS)
brew install --cask codex

安装完成后,验证:

codex --version
# 输出形如: codex-cli 0.x.x

Windows

Codex CLI 在 Windows 上的官方支持路径是 WSL2。原生 Windows 支持仍在完善。

方式一:WSL2(推荐)

# PowerShell(管理员),如果之前没装过 WSL
wsl --install -d Ubuntu
# 重启后,在 Ubuntu 终端执行上面的 macOS/Linux 命令

方式二:Windows 原生(测试性)

# 1. 装 Node.js 22+(参考 [02. 安装与配置](./02-installation) 的 Windows 部分)
node --version    # 应输出 v22.x 或更高

# 2. 全局装 Codex
npm install -g @openai/codex

# 3. 验证
codex --version

Windows 原生常见问题:

问题解决
codex 命令找不到把 npm 全局 bin 目录加到 PATH(默认在 %AppData%\npm)
中文乱码chcp 65001 切到 UTF-8,或用 Windows Terminal
路径含空格报错把项目移到无空格路径,如 D:\projects\xxx
Git Bash 跑 Codex可以,推荐用 Git Bash 替代 cmd
沙箱/权限报错以管理员身份运行 PowerShell,或在 WSL2 里跑

想用国产大模型替代 Codex 的 OpenAI 模型 → 参考 06. ccswitch 配置国产大模型 的 OPENAI_BASE_URL 思路(Codex 也支持自定义 base URL)

四、账号与认证

首次运行 codex 会引导你登录。Codex 有两种认证方式:

方式 A:ChatGPT 订阅登录(推荐,个人用户)

codex
# 弹出浏览器,登录你的 ChatGPT 账号(Plus/Pro/Team)
# 登录后回到终端,Codex 自动续期 token

适合:已经在用 ChatGPT 个人订阅,不想额外按 token 付费。

方式 B:OpenAI Platform API Key

# 设置环境变量
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

# 启动
codex

适合:用 OpenAI 企业账号、需要计费透明、或希望按用量付费。

Windows PowerShell:

[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'YOUR_OPENAI_API_KEY', 'User')
$env:OPENAI_API_KEY = "YOUR_OPENAI_API_KEY"

想了解更多 Codex 高级用法(model 切换、sandbox、approval policy) → 参考 02-intermediate 相关章节

五、国内网络环境配置

跟 Claude Code 在国内一样,Codex 也有"默认 API 难直连"的问题。两个常见做法:

做法 1:环境变量指到代理地址

# macOS/Linux
export OPENAI_BASE_URL="https://你的代理地址"
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

# Windows PowerShell
[System.Environment]::SetEnvironmentVariable('OPENAI_BASE_URL', 'https://你的代理地址', 'User')
[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'YOUR_OPENAI_API_KEY', 'User')

做法 2:用 ccswitch 统一管理

如果你的电脑同时装了 Claude Code 和 Codex,推荐用 ccswitch 统一管理两边:

[Claude Code] ──┐
                ├── [ccswitch] ── 多个 LLM provider(Anthropic / OpenAI / DeepSeek / Qwen / ...)
[Codex CLI]   ──┘

ccswitch 支持的 provider 列表会随版本更新,以官网为准。

六、常用配置

配置文件位置:~/.codex/config.toml(用户级)或项目内 .codex/config.toml(项目级)。

用户级最小配置

# ~/.codex/config.toml
model = "gpt-5"
approval_policy = "auto-edit"
sandbox_mode = "workspace-write"

项目级配置示例(放在项目内 .codex/config.toml)

# 项目根目录下
model = "gpt-5-mini"  # 本项目用便宜模型
approval_policy = "suggest"  # 危险操作要询问

七、推荐目录结构

mkdir -p ~/projects
cd ~/projects
mkdir my-course-assistant
cd my-course-assistant
codex
# 进入交互模式,Codex 会自动识别当前目录

跟 Claude Code 一样:Codex 默认在当前目录工作。如果你有 Claude Code 项目想用 Codex 跑,目录结构无需调整——两者读的是同一份文件树。

八、IDE 集成(推荐)

Codex CLI 也提供 IDE 集成:

IDE备注
VS Code通过 Codex 扩展(在 VS Code Marketplace 搜 "Codex" 即可)
JetBrains通过 Codex 插件(在 JetBrains Marketplace 搜 "Codex")
Trae / Cursor在内置终端跑 codex CLI

完整官方文档:github.com/openai/codex 内的 docs/ 目录。

九、常见安装问题

codex: command not found

  • 检查 ~/.npm-global/bin 或 ~/.local/bin 是否在 $PATH 中
  • macOS:在 ~/.zshrc 加上 export PATH="$HOME/.npm-global/bin:$PATH"
  • Windows:把 %AppData%\npm 加到系统 PATH

登录后报 "missing scopes"

  • 检查你的 ChatGPT 订阅是否包含 Codex 访问权限
  • 部分旧订阅可能需要升级到 Plus/Pro 才能用 Codex

API Key 无效

  • 确认 Key 没有多余空格/换行
  • 确认账号余额充足
  • 国内访问可能需要配置 OPENAI_BASE_URL(详见第五节)

如果发生中文乱码【没有发生可不执行,多见于各种版本的 Linux】

终端设置 UTF-8:

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

十、与 Claude Code 共存

两个 CLI 可以装在同一台机器,互不干扰:

工具命令默认模型配置文件
Claude CodeclaudeClaude 系列~/.claude/settings.json
Codex CLIcodexGPT 系列~/.codex/config.toml

切换使用:claude 跑 Claude Code,codex 跑 Codex,项目目录共用。

下一步