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/codexHomebrew(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 模型) |
