OpenAI Codex CLI 实战指南：从安装到生产力，开源编程 Agent 的第一选择摘要：OpenAI 在 20

摘要：OpenAI 在 2026 年把 Codex CLI 做成了开源、多端、可深度定制的编程 Agent——90k Star、Terminal-Bench 第一、v0.139 刚发两周。本文从安装配置讲到 AGENTS.md 和 Skills 体系，再到 MCP 插件和沙箱安全模型，是一份能直接上手的手册。读完你会知道：它跟 Claude Code/Cursor 的区别在哪、什么时候该用它、以及怎么把它配成你的定制化编程搭档。

1. 背景与痛点

2026 年过半，AI 编程 Agent 的格局基本定型了。

Claude Code 靠 SWE-bench 高分和 Anthropic 的工程文化站稳了第一梯队。Cursor 用 IDE 粘性锁定了一批深度用户。GitHub Copilot 六月一号刚切了 AI Credits 计费，Reddit 上还在吵。OpenCode、Cline、Aider 这些开源选手各自守着一块地盘。

但有一个东西被很多人忽略了：OpenAI 自家的 Codex CLI 才是目前 Terminal-Bench 排名第一的编程 Agent——83.4%，压过 Claude Code（78.9%）和 Gemini CLI（70.7%）。而且它是开源的，Apache-2.0，90k Star，两周前刚发了 v0.139。

我上周才真正开始用它。之前一直觉得"不就是 OpenAI 版 Claude Code 吗，能有什么区别"——结果打脸了。Codex 的配置体系、Skills 机制和沙箱模型，跟 Claude Code 完全不是一个思路。这篇文章把我踩过的坑和学到的东西整理出来。

说实话，Codex 现在的处境有点像 2015 年的 VS Code——刚出来的时候大家觉得"不就是另一个编辑器吗"，但它的插件体系和配置灵活性最终碾压了竞品。Codex 的 AGENTS.md 标准、Profiles 系统和 Skills 机制，正在建立同样的网络效应。

另外有个背景值得留意：Codex 是纯 Rust 写的（96% Rust + 少量 Python/TS），二进制体积小，启动飞快。在树莓派上都能跑。这对资源受限的开发环境——比如嵌入式开发或者在低配 VPS 上做运维——是个不小的加分项。

2. 技术架构：Codex 跟其他 Agent 的本质区别

先别急着装。理解它的架构再动手，能省很多时间。

Codex CLI 不是"终端里的 ChatGPT"。它是一个多端编程 Agent，核心就五套系统：

graph TB
    subgraph &#34;五套核心系统&#34;
        A[config.toml<br/>配置中心] --> B[Sandbox & Approval<br/>安全沙箱]
        C[AGENTS.md<br/>项目指令] --> D[MCP<br/>外部工具连接]
        E[Skills<br/>可复用能力包] --> D
    end
    
    subgraph &#34;五个入口&#34;
        F[CLI<br/>终端] 
        G[Desktop App<br/>桌面应用]
        H[IDE Extension<br/>VS Code/Cursor]
        I[Cloud Tasks<br/>云端任务]
        J[Chrome Extension<br/>浏览器插件]
    end
    
    F --> A
    G --> A
    H --> A
    I --> A
    J --> A
    
    B --> K[OS-level Sandbox<br/>Seatbelt/Landlock/seccomp]
    C --> L[跨工具标准<br/>Cursor/Copilot/Gemini CLI 通用]
    
    style A fill:#10a37f,color:#fff
    style C fill:#ff6b35,color:#fff
    style D fill:#6366f1,color:#fff

说人话：config.toml 控制一切，从模型选择到沙箱权限都在一个文件里；AGENTS.md 是给 Agent 看的项目说明书（而且这个标准 Cursor、Copilot、Gemini CLI 都认）；MCP 连外部工具；Skills 是可复用的能力包。

跟 Claude Code 最大的区别：Claude Code 靠 .claude-plugin/plugin.json 做插件隔离，Codex 靠 config.toml 做全局配置 + requirements.toml 做管理员硬策略。前者灵活，后者可控。看你场景选。

3. 环境准备

3.1 安装

Codex 支持四种安装方式，选一个：

# 方式一：npm（跨平台推荐）
npm install -g @openai/codex

# 方式二：Homebrew（macOS）
brew install --cask codex

# 方式三：winget（Windows）
winget install OpenAI.Codex

# 方式四：GitHub Releases 二进制（macOS/Linux，无需联网执行脚本）
# 先去 https://github.com/openai/codex/releases/latest 下载对应平台的 tar.gz
# 解压后把二进制文件放到 PATH 里：
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex

Windows 用户注意：Codex 在 PowerShell 下可以原生运行（有 Windows Sandbox），但某些 shell 操作在 WSL2 下更稳定。如果你 codex 之后报 'sh' is not recognized，装个 Git Bash 或切 WSL2。

安装完验证：

codex --version
# 输出类似：codex 0.139.0

3.2 认证

第一次运行 codex 会弹出浏览器让你登录。两种方式：

# 方式一：ChatGPT 账号（Plus/Pro/Business/Enterprise 都行）
codex
# → 浏览器 OAuth 认证

# 方式二：API Key（BYOK，按量付费）
echo "sk-your-key-here" | codex login --with-api-key

我用的 Plus 账号，每月 $20 包含 Codex 使用额度——ChatGPT 消息配额和 Codex 共享同一个 5 小时窗口。如果你重度用 Agent 模式，建议上 Pro。

3.3 第一个会话

cd your-project
codex

进入 TUI（终端交互界面）后，直接打字就行：

> 解释一下这个项目的结构
> 帮我写一个 REST API 的单元测试
> /model  # 切换模型

这里有个容易忽略的点：/model 可以实时切模型和推理强度。比如你觉得当前任务不需要 GPT-5.5 的深度推理，可以切到 gpt-5.4-mini + low 推理，省 token：

/model gpt-5.4-mini
/model-reasoning-effort low

或者直接用快捷键 Alt+, / Alt+. 在 TUI 里调。

4. 实战配置：从 config.toml 到 AGENTS.md

Codex 的配置有三个层级，优先级从高到低：

CLI 参数：--model gpt-5.5 --sandbox workspace-write
项目级：.codex/config.toml
用户级：~/.codex/config.toml
系统级：/etc/codex/config.toml（管理员设置，普通用户改不了）

还有一层硬的：requirements.toml——管理员用它锁定策略，用户无法覆盖。

4.1 核心配置项

我的 ~/.codex/config.toml 长这样：

# 默认模型
model = "gpt-5.5"
model_reasoning_effort = "medium"

# 沙箱模式：只允许在工作区目录内写文件
sandbox_mode = "workspace-write"

# 审批策略：操作前弹确认
approval_policy = "on-request"

# 开启联网搜索
web_search = "live"

# Shell 环境变量继承策略
[shell_environment_policy]
inherit = "core"

几个关键选项解释：

配置项	可选值	说明
`sandbox_mode`	`read-only` / `workspace-write` / `danger-full-access`	文件系统权限。生产环境别开 `danger-full-access`
`approval_policy`	`untrusted` / `on-request` / `never`	`untrusted`=每次操作都确认；`never`=全自动（慎用）
`model_reasoning_effort`	`minimal` / `low` / `medium` / `high` / `xhigh`	推理深度。越深越贵，但复杂任务值得
`web_search`	`live` / `cached`	`live` 会实时搜索，`cached` 用缓存结果

4.2 Profiles：快速切换工作模式

这是我用 Codex 最爽的功能之一。你可以给不同场景定义不同的配置预设：

[profiles.fast]
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
approval_policy = "on-request"

[profiles.careful]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"

[profiles.autopilot]
model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

切换：

codex --profile fast "把这个函数改成 async"
codex --profile careful "审查这段代码的安全性"

--profile 从 v0.134.0 开始是主选择器——旧版的 profile 配置方式已经被标记为废弃，迁移时会提示。

4.3 AGENTS.md：给 Agent 看的项目说明书

这是 Codex 最被低估的功能。AGENTS.md 是一个开放标准——你写一份，Cursor、Copilot、Gemini CLI 都能读。

放哪：

项目根目录：./AGENTS.md（项目专属）
全局：~/.codex/AGENTS.md（所有项目生效）

一个真实的 AGENTS.md 示例：

# AGENTS.md

## 项目概述
这是一个 Python 3.12 的 FastAPI 后端项目，使用 SQLAlchemy 2.0 + PostgreSQL 16。

## 编码规范
- 所有函数必须有 type hints
- 用 `ruff` 做 lint，配置在 `pyproject.toml`
- 测试用 pytest + pytest-asyncio，覆盖率要求 >80%
- 禁止使用 `print()`，用 `logging` 模块

## 禁止事项
- 不要修改 `alembic/` 目录下的迁移文件
- 不要直接操作生产数据库
- 不要引入超过 500KB 的新依赖

## 常用命令
- 启动开发服务器：`uvicorn app.main:app --reload`
- 运行测试：`pytest -xvs`
- 数据库迁移：`alembic upgrade head`

有了这个文件，Codex 在每次会话中都会自动加载它作为上下文。你再也不用每次会话开头解释一遍项目规范。

4.4 Skills：可复用的能力包

Skills 放在两个地方：

~/.codex/skills/          # 个人全局
├── code-reviewer/
│   └── SKILL.md
├── test-generator/
│   ├── SKILL.md
│   └── references/
│       └── testing-patterns.md
└── deploy-checker/
    └── SKILL.md

.codex/skills/             # 项目级
└── api-docs-generator/
    └── SKILL.md

一个 SKILL.md 的结构：

---
name: code-reviewer
description: 对代码变更做安全审查和最佳实践检查
triggers:
  - 审查代码
  - review
  - code review
---

# 代码审查 Skill

## 检查清单
1. SQL 注入风险
2. XSS 漏洞
3. 敏感信息硬编码
4. 异常处理是否完整
5. 类型安全

## 输出格式
- 🔴 严重：必须修复
- 🟡 建议：应该修复
- 🟢 信息：可选改进

Codex 在对话中识别到关键词时自动加载对应 Skill。这个机制比 Claude Code 的 hooks 更轻量，适合中小团队快速搭建自己的 Agent 能力库。

4.5 自动化脚本：用 `codex exec` 把重复工作交给 Agent

除了交互式 TUI，Codex 还能在非交互模式下跑——这对 CI/CD 和定时任务特别有用：

# 单次执行：检查代码风格
codex exec "检查 src/ 目录下所有 Python 文件的类型注解是否完整，输出缺失列表"

# 配合 git hook：提交前自动审查
codex exec --profile careful "审查这次 git diff 中的代码变更，重点检查安全问题"

# 批量任务：给每个模块生成文档字符串
codex exec --model gpt-5.4-mini "为 src/models/ 下所有类添加 Google-style docstring"

exec 模式下 Codex 不会启动 TUI，直接在后台完成任务后退出。输出可以重定向到文件或管道给下一个命令。我把这个挂到了 pre-commit hook 里——每次 git commit 之前自动跑一遍安全检查，省了人工 review 的时间。

4.6 模型选择策略：什么时候用哪个模型

Codex 支持多个模型，但不会帮你选。用了两周总结出来的经验：

场景	推荐模型	理由
日常小修小改	`gpt-5.4-mini` + low reasoning	够用且快，token 消耗低 60%
新功能开发	`gpt-5.5` + medium reasoning	平衡质量和速度
代码审查/安全审计	`gpt-5.5` + xhigh reasoning	深度推理，值得等
批量生成（文档/测试）	`gpt-5.4-mini` + minimal reasoning	模式化任务不需要深度推理
架构设计/重构	`gpt-5.5` + high reasoning	需要理解全局上下文

一个反直觉的经验：不是所有任务都值得用最强模型。写单元测试这种模式化工作，gpt-5.4-mini 的输出质量和 gpt-5.5 差别不大，但速度快一倍、token 消耗少一半。把好钢用在刀刃上。

5. MCP 集成：连接外部世界

MCP（Model Context Protocol）是 Codex 连接外部工具的桥梁。配置在 config.toml 里：

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxx" }

[mcp_servers.postgres]
command = "docker"
args = ["run", "--rm", "-i", "mcp/postgres", "postgresql://localhost:5432/mydb"]

或者在 Codex Desktop App 里通过 GUI 的 Plugin Marketplace 一键安装——Linear、Sentry、Notion、Vercel 都有现成的。

配置完重启 Codex，MCP 工具就自动可用了。你可以在对话中直接说"查一下最近 10 个 GitHub Issue"——Codex 会调 MCP server 去拿。

安全提醒：给 MCP 连接的数据库账号只开只读权限。Agent 虽然强，但让它直接操作生产库还是太冒险了。

6. 效果对比：Codex vs Claude Code vs Cursor

用了两周的直观感受：

对比维度	Codex CLI	Claude Code	Cursor
Terminal-Bench	83.4% (#1)	78.9% (#2)	模型依赖
开源协议	Apache-2.0	仓库开源，工具闭源	闭源
GitHub Stars	90.1k	131k	N/A
安装方式	npm/brew/winget/脚本	npm/brew/winget/脚本	IDE 下载
配置体系	config.toml + Profiles	.claude-plugin/plugin.json	Settings UI
Skills 机制	✅ SKILL.md 文件	✅ Hooks + Plugins	❌
AGENTS.md	✅ 原生 + 跨工具标准	✅ 部分支持	✅
沙箱安全	Seatbelt/Landlock/seccomp	基础文件系统限制	IDE 沙箱
价格	ChatGPT Plus $20/月起	Claude Pro $17/月起	$20/月起
BYOK	✅ API Key	✅ API Key	❌
Windows 原生	✅ PowerShell 沙箱	✅ WSL/原生	✅
最佳场景	终端重度用户、开源项目	复杂推理、长上下文	IDE 深度绑定用户

说点个人感受：

Codex CLI 的最强项是配置灵活度和Profiles 系统。同样的项目，早上用 fast profile 快速改 bug，下午用 careful profile 做架构审查——不需要改任何配置，一个参数搞定。这个 Claude Code 目前做不到。

但 Claude Code 在长上下文复杂推理上确实更强——SWE-bench Verified 88.6% vs Codex 模型依赖，Anthropic 在 Agent 可靠性上的工程投入肉眼可见。

Cursor 的优势是零配置——装完就能用，对不想折腾配置的开发者友好。但如果你需要定制 Agent 行为、写项目级指令、或者把 Agent 集成到 CI/CD 里，Codex 或 Claude Code 才是正解。

7. 踩坑记录

用了两周，炸了几次，记录一下：

坑 1：Windows PowerShell 下 shell 命令不兼容

症状：

'sh' is not recognized as an internal or external command

Codex 内部某些操作会调 sh。Windows 原生 PowerShell 没有这个。解决方案：装 Git Bash 后重启终端，或者在 WSL2 里跑 Codex。官方文档也说了"Windows support has historically been experimental"——2026 年好多了，但 WSL2 还是最稳的选择。

坑 2：API Key 模式下额度消耗远超预期

ChatGPT Plus 用户注意：Codex 的消息和 ChatGPT 网页版共享同一个 5 小时配额窗口。如果你在网页端问了 50 个问题，再切回 Codex，额度可能已经用掉大半。Pro 用户的配额宽裕很多，重度 Agent 使用建议上 Pro。

坑 3：`danger-full-access` 沙箱模式

别开。真的别开。Codex 在 danger-full-access 模式下可以删你的 /etc、改你的 .bashrc、卸载你的系统包。虽然审批策略能拦住大部分危险操作，但万一你设了 approval_policy = "never" + danger-full-access——那就是裸奔。生产环境永远用 workspace-write。

坑 4：MCP Server 环境变量不生效

在 config.toml 里配了 env = { KEY = "value" }，但 Codex 启动后读不到。排查发现是 ~/.codex/config.toml 里有一个语法错误（多了一个逗号）导致整个 [mcp_servers] 段被跳过。用 codex doctor 可以诊断：

codex doctor
# 输出会列出 MCP server 的连接状态、环境变量、Git 状态等

8. 总结与展望

Codex CLI 不是"另一个 Claude Code 替代品"。它的核心差异在于：

配置即代码：config.toml + Profiles + requirements.toml 三层体系，既能个人灵活配置，也能团队统一管控
AGENTS.md 标准：一次编写，Codex / Cursor / Copilot / Gemini CLI 通用——这是目前唯一被多个主流 Agent 工具共同支持的项目指令标准
开源 + Apache-2.0：意味着你可以 fork、改、集成到自己的工具链里，没有任何法律风险
OpenAI 模型全家桶：GPT-5.5 的 400K 上下文窗口 + 终端原生体验，结合 Codex 的沙箱安全模型，是目前最平衡的开源编程 Agent

展望几个方向：

Codex Cloud Tasks 还在 beta，但已经能看到"提交 diff 回来"的端到端流程——未来可能变成 CI/CD 里的一个标准步骤
AGENTS.md 生态 一旦成熟，项目切换 Agent 工具的成本将降到零
Skills 市场 如果 OpenAI 真的推起来，会像 VS Code 插件生态一样，成为护城河

你用哪个编程 Agent？Codex、Claude Code 还是 Cursor？最让你抓狂的坑是什么——评论区聊聊，我整理到后续文章里。

OpenAI Codex CLI 实战指南：从安装到生产力，开源编程 Agent 的第一选择