OpenAI Codex CLI 使用教程

约 1388 字大约 5 分钟

AICodexCLI

2026-04-02

简介

Codex CLI 是 OpenAI 开源的终端编程 Agent，基于 Apache-2.0 协议。它能在本地终端中结合 ChatGPT 级别的推理能力，执行代码、操作文件、管理项目——一切操作都在版本控制下进行。

核心特性：

本地沙盒执行，安全可控
多模态输入（文本、截图、示意图）
支持 MCP 协议扩展
灵活的审批模式（从手动到全自动）
支持 OpenAI、Azure、Ollama 等多种模型提供商

Codex CLI 最初为 TypeScript/Node.js 实现，后已用 Rust 重写，当前版本为 v0.118.0+。

安装

npm（推荐）

npm install -g @openai/codex
# 或
pnpm add -g @openai/codex

Homebrew（macOS）

brew install --cask codex

二进制下载

从 GitHub Releases 下载对应平台的二进制文件：

macOS Apple Silicon: codex-aarch64-apple-darwin.tar.gz
macOS x86_64: codex-x86_64-apple-darwin.tar.gz
Linux x86_64: codex-x86_64-unknown-linux-musl.tar.gz
Linux arm64: codex-aarch64-unknown-linux-musl.tar.gz

从源码构建

git clone https://github.com/openai/codex.git
cd codex/codex-rs
cargo build --release

系统要求

macOS 12+ / Ubuntu 20.04+ / Windows 11（WSL2）
Git 2.23+（推荐）
4 GB RAM（推荐 8 GB）

认证配置

方式一：ChatGPT 登录（推荐）

直接运行 codex，选择 "Sign in with ChatGPT"，通过设备码流程登录。需要 Plus/Pro/Team/Edu/Enterprise 订阅。

方式二：API Key

# 环境变量
export OPENAI_API_KEY="sk-xxx"

# 或在项目根目录创建 .env 文件
echo "OPENAI_API_KEY=sk-xxx" > .env

配置文件

配置文件位于 ~/.codex/config.toml：

# 默认模型
model = "o4-mini"

# 审批模式
approval_policy = "on-request"

# 沙盒模式
sandbox_mode = "workspace-write"

# 推理力度
model_reasoning_effort = "medium"

# 自定义指令
developer_instructions = "Always write tests for new functions"

# 完成时发送桌面通知
notify = "terminal-notifier -message 'Codex done'"

自定义模型提供商

Codex CLI 支持 OpenAI 之外的模型：

# 使用本地 Ollama
[model_providers.ollama]
base_url = "http://localhost:11434/v1"
model = "codellama"

# 使用 Azure OpenAI
[model_providers.azure]
base_url = "https://your-resource.openai.azure.com"
model = "gpt-4.1"

基本用法

交互模式（TUI）

# 启动交互式会话
codex

# 带初始提示启动
codex "修复 src/utils.ts 中的 lint 错误"

非交互模式

适用于 CI/CD 或脚本化场景：

# 无头执行
codex exec "更新 CHANGELOG"

# 管道输入
cat error.log | codex exec "分析这个错误日志并给出修复建议"

# 静默模式
CODEX_QUIET_MODE=1 codex exec "生成单元测试"

常用 CLI 参数

参数	缩写	说明
`--model`	`-m`	指定模型（如 `gpt-4.1`、`o3`）
`--approval-mode`	`-a`	设置审批模式
`--quiet`	`-q`	静默/非交互模式
`--json`		JSON 格式输出
`--notify`		启用桌面通知
`-c key=value`		内联覆盖配置项

审批模式

Codex CLI 提供了从保守到激进的多种审批策略：

模式	自动执行	需要审批	适用场景
Suggest（默认）	只读的安全命令	所有文件写入和 shell 命令	初次使用、学习阶段
On Request	由模型判断是否需要审批	模型认为需要确认的操作	日常开发
Full Auto	读写文件 + 执行命令	无需审批	信任场景、快速原型

# 使用建议模式（最安全）
codex -a suggest "重构 Dashboard 组件"

# 全自动模式
codex -a full-auto "创建一个 todo-list 应用"

注意

Full Auto 模式下，所有命令在网络隔离环境中运行，写入限制在当前工作目录内。建议在 Git 仓库中使用，以便随时回退。

沙盒机制

Codex CLI 的核心安全特性之一是沙盒执行：

macOS：使用 Apple Seatbelt（sandbox-exec），命令在只读隔离环境中运行，仅 $PWD、$TMPDIR、~/.codex 可写，出站网络完全阻断
Linux：使用 Bubblewrap（bwrap）沙盒，也支持 Docker 容器化沙盒

三种沙盒级别：

read-only：只读访问，最安全
workspace-write：允许写入工作目录（默认）
danger-full-access：完全访问，谨慎使用

AGENTS.md 项目指令

类似于 Claude Code 的 CLAUDE.md，Codex CLI 使用 AGENTS.md 来存储项目级指令。

<!-- AGENTS.md -->
## 项目规范
- 使用 TypeScript strict 模式
- 所有函数必须有 JSDoc 注释
- 测试覆盖率不低于 80%

层级加载顺序（优先级从低到高）：

全局指令：~/.codex/instructions.md
仓库根目录：AGENTS.md
子目录：各子目录下的 AGENTS.md

常用场景示例

# 代码重构
codex "将 Dashboard 组件重构为 React Hooks"

# 生成数据库迁移
codex "生成添加 users 表的 SQL 迁移文件"

# 编写单元测试
codex "为 utils/date.ts 编写单元测试"

# 批量重命名
codex "使用 git mv 将所有 *.jpeg 重命名为 *.jpg"

# 代码审查
codex "审查这个仓库，提出 3 个高价值的 PR 建议"

# 安全审计
codex "扫描漏洞并生成安全审查报告"

# CI/CD 中使用
codex -a full-auto --quiet "更新 CHANGELOG 并准备下一个版本"

交互模式斜杠命令

在交互式 TUI 中可使用的内置命令：

命令	说明
`/copy`	复制上一条回复到剪贴板
`/resume <name>`	恢复之前的会话
`/agent`	切换 Agent 模式
`/review`	代码审查模式
`/apps`	管理应用/连接器

GitHub Action 集成

OpenAI 提供了官方的 codex-action，可在 CI/CD 中使用：

# .github/workflows/codex.yml
name: Codex Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: "审查这个 PR 的代码变更，指出潜在问题"

与 Claude Code 的差异

关于 Codex CLI 与 Claude Code 的详细对比，请参阅 Claude Code vs Codex。

核心差异速览：

维度	Codex CLI	Claude Code
实现语言	Rust	TypeScript
沙盒	系统级沙盒（Seatbelt/bwrap）	权限审批模型
项目指令	AGENTS.md	CLAUDE.md
默认模型	o4-mini	Claude Sonnet/Opus
多模型支持	是（Ollama/Azure/自定义）	有限（Anthropic 模型）

Claude Code

OpenAI

Qwen Code