一、痛点引入：程序员的日常，你中了几个？

周五下午5点，产品经理甩来一个需求："这个接口加个分页，顺便把旧的日志模块重构一下。" 你打开项目，发现代码仓库几百个文件，日志模块跟业务代码纠缠不清，分页逻辑要改三个地方的DAO——改完一处，另外两处忘了同步，debug到晚上9点。又或者，你接手了一个祖传的老项目，光搞清楚项目结构就花了半天，想写个单元测试都不知道从哪入手。

我们中国开发者还面临一些额外痛点：网络环境不稳定，访问海外API经常超时；团队里有人用Mac、有人用Windows、有人用Linux，AI工具的安装配置经常踩坑；很多AI编程工具是英文界面，新手看文档一头雾水。

有没有一个工具，能直接在终端里帮你读代码、改代码、跑测试，还不用离开你最熟悉的命令行环境？

有没有一个工具，能理解你的整个项目上下文，而不是只看当前打开的那一个文件？

OpenAI 的 Codex CLI 就是来干这个的。

二、Codex CLI 是什么？

Codex CLI 是 OpenAI 官方推出的轻量级编码 Agent（智能体），它运行在你的本地终端里。注意关键词：本地——你的代码不需要上传到任何云服务器，Codex 在你的机器上直接读写文件、执行命令、运行测试。

用大白话说：它就像一个坐在你旁边的全栈程序员搭档，你告诉它要做什么，它就在终端里帮你干了——读代码、写代码、跑命令、找bug，全程你都能看到它在做什么，随时可以喊停。

需要澄清几个概念，免得混淆：

如果你想在VS Code、Cursor、Windsurf等编辑器里用Codex，可以去 OpenAI开发者页面 安装IDE插件。如果想用桌面App，运行 codex app 或访问 Codex App页面。但本文专注讲 Codex CLI——那个最纯粹、最灵活的终端版。

GitHub 地址：https://github.com/openai/codex

许可证：Apache-2.0（完全开源，可商用）

三、核心功能全览

Codex CLI 不只是帮你"自动补全代码"那么简单，它是一个完整的编码Agent系统。以下是核心能力拆解：

1. 交互式 TUI（终端用户界面）

Codex 提供了一个全屏终端界面（TUI，Terminal User Interface），基于 Ratatui 框架构建。这不是简陋的命令行问答，而是一个有颜色高亮、有会话管理、有快捷键的完整界面。你可以在里面跟Codex对话，看它一步步操作，随时打断或追加指令。

2. 三级沙箱安全机制

这是Codex最核心的安全设计。沙箱（Sandbox）就像一个"围栏"，限制Codex能做什么，防止它误操作搞坏你的系统：

• macOS 使用 Apple 原生的 Seatbelt（sandbox-exec）实现沙箱
• Linux 使用 Bubblewrap（bwrap）实现沙箱，含用户命名空间隔离、PID命名空间隔离、seccomp过滤器
• Windows 通过 WSL2 运行时有对应的沙箱策略

3. 智能审批策略

Codex 执行命令前，会根据你设置的审批策略决定是否需要你手动确认：

• untrusted（不信任）：只自动批准安全的读操作，其他一律问你——最安全但最慢
• on-request（按需）：AI自己判断什么时候需要问你，平衡了效率和安全性（推荐）
• on-failure（失败时）：沙箱内自动执行，沙箱失败了才问你——适合自动化场景
• never（从不）：从不问人，直接干——仅用于完全自动化的非交互场景

还支持细粒度审批（Granular Approval），可以按命令类别分别配置自动批准还是自动拒绝。

4. 非交互模式（codex exec）

运行 codex exec "你的指令"，Codex就进入无人值守模式——它自己干活、自己完成、自己退出，不需要你在终端看着。这非常适合：

• CI/CD 流水线中自动修bug
• 批量代码重构脚本
• 配合管道使用：echo "错误日志" | codex exec "分析这个错误的原因"

用 --ephemeral 参数可以不保存会话记录到磁盘，用完即弃。

5. MCP 协议支持（客户端+服务端）

MCP（Model Context Protocol，模型上下文协议）是AI工具之间互操作的标准协议。Codex 同时支持：

• MCP 客户端：Codex 启动时自动连接你配置的 MCP 服务器，获取额外工具能力（比如数据库查询、文档搜索等）
• MCP 服务端：运行 codex mcp-server，让其他AI Agent可以把Codex当作一个工具来调用

配置方法：在 ~/.codex/config.toml 里添加 MCP 服务器配置即可。

6. Skills 技能系统

Codex 内置了技能（Skills）体系，类似于插件。每个技能是一个文件夹，包含 SKILL.md 描述文件和相关参考文档。Codex 自带了几个实用技能，也支持自定义技能。

目前仓库中的技能示例：

• babysit-pr：自动照看PR（Pull Request），审核代码变更
• codex-bug：Bug分析和修复
• remote-tests：远程测试执行
• test-tui：TUI测试

7. AGENTS.md 项目上下文

类似 .editorconfig 或 .gitignore，Codex 支持在项目根目录放一个 AGENTS.md 文件，用来给AI提供项目级别的指引——比如"本项目的代码风格是X""测试跑 npm test""不要修改 utils/legacy 目录"。Codex 会自动读取并遵循这些指引。

8. Guardian 安全策略引擎

Codex 内置了一个安全策略引擎叫 Guardian，会在AI执行高危操作前进行风险评估，涵盖：

• 数据外泄风险：防止代码/密钥被发送到外部不可信服务器
• 凭证探测：防止AI过度访问系统中的密钥、Token
• 持久性安全削弱：防止AI修改安全配置导致系统暴露
• 破坏性操作：防止 rm -rf、git reset --hard 等不可逆操作

高风险操作会被自动拒绝，即使用户授权了"高"也不行。

9. 通知系统

Codex 完成一个回合后可以触发系统通知。macOS 支持通过 terminal-notifier 发送桌面通知；Windows Terminal 下自动回退到原生 Toast 通知。再也不用盯着终端等它干完了——去倒杯茶，做好了会通知你。

10. 协作模式与多Agent

Codex 支持多种协作模式（Collaboration Modes），包括默认模式、执行模式、结对编程模式、计划模式等。还支持分层Agent——主Agent可以派生子Agent处理子任务，子任务完成后再汇整结果。配置中可以设最大并发线程数（maxthreads）和最大嵌套深度（maxdepth）。

四、手把手安装配置（分平台详解）

系统要求

重要提醒：Windows 用户必须通过 WSL2（Windows Subsystem for Linux 2）来使用 Codex，不支持直接在 Windows 原生命令行运行。

macOS 安装

方式一：Homebrew（最推荐）

# 一行命令搞定
brew install --cask codex

方式二：npm

# 需要先装好 Node.js（建议 v22+）
npm install -g @openai/codex

方式三：下载预编译二进制

去 GitHub Releases 页面下载：

• Apple Silicon（M1/M2/M3/M4芯片）：下载 codex-aarch64-apple-darwin.tar.gz
• Intel 芯片（老款Mac）：下载 codex-x86_64-apple-darwin.tar.gz

解压后重命名为 codex，放到 PATH 目录下即可。

Linux 安装

方式一：npm

npm install -g @openai/codex

方式二：下载预编译二进制

从 GitHub Releases 下载：

• x8664（大多数PC和服务器）：codex-x8664-unknown-linux-musl.tar.gz
• ARM64（树莓派等ARM设备）：codex-aarch64-unknown-linux-musl.tar.gz

解压、重命名、放入 PATH。

Linux 额外注意：Codex 默认使用 Bubblewrap 沙箱。多数发行版已自带 bwrap，如果没有，Codex 会在启动时给出警告并回退到内置的 vendored 版本。也可以用以下命令安装：

# Ubuntu/Debian
sudo apt install bubblewrap

# Fedora
sudo dnf install bubblewrap

# Arch
sudo pacman -S bubblewrap

Windows 安装（WSL2）

# 1. 确保已安装 WSL2
wsl --install

# 2. 进入 WSL2 环境
wsl

# 3. 安装 Node.js（推荐用 nvm）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22

# 4. 安装 Codex
npm install -g @openai/codex

从源码编译安装（极客专属）

# 克隆代码
git clone https://github.com/openai/codex.git
cd codex/codex-rs

# 安装 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustup component add rustfmt clippy

# 安装辅助工具
cargo install just
cargo install --locked cargo-nextest  # 可选

# 编译
cargo build

# 启动测试
cargo run --bin codex -- "向我解释这个代码库"

认证配置

安装完成后，第一次运行 codex，会提示你登录认证。有两种方式：

方式一：ChatGPT 账号登录（推荐）

运行 codex，选择 Sign in with ChatGPT。如果你有 ChatGPT Plus、Pro、Business、Edu 或 Enterprise 订阅，可以直接用，不需要额外付费。对中国用户来说，你需要能访问 OpenAI 的网络环境（懂的都懂，建议用稳定的企业级代理）。

方式二：API Key

如果你用 API Key，需要额外配置。参考 API Key 认证文档。

基本步骤：

1. 去 OpenAI API Keys 创建一个 Key
2. 运行 codex 选择 API Key 登录
3. 输入你的 Key

API Key 的凭证存储方式可在配置中选择：file（文件存储）、keyring（系统钥匙串）、auto（优先钥匙串）、ephemeral（仅内存）。

基础配置文件

Codex 的配置文件位于 ~/.codex/config.toml（TOML格式，比JSON更易读写）。一个最小可用的配置示例：

# ~/.codex/config.toml

# 沙箱模式：read-only / workspace-write / danger-full-access
sandbox_mode = "workspace-write"

# 审批策略：untrusted / on-request / on-failure / never
approval_policy = "on-request"

# MCP 服务器配置（可选）
[mcp_servers.my-server]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

配置中还支持特性开关、Profile（多配置方案）、自定义CA证书、分析数据收集开关等高级选项。完整的配置参考见 OpenAI 配置文档。

五、三种使用方法（从简单到进阶）

方法一：交互式对话（入门必用）

直接在终端运行：

codex

进入全屏TUI界面后，你可以在底部的输入框里输入指令。Codex 会读取当前目录的代码，理解项目上下文，然后执行你要求的操作。

常用指令示例：

# 在项目目录下启动
cd my-project
codex

# 输入框中输入：
"帮我看看 src/utils.py 里有没有 bug"

"给 UserController 加一个分页查询接口"

"重构 log 模块，把日志输出统一用 structlog"

"运行测试并修复失败的用例"

快捷键：

• Ctrl+C：中止当前操作（连按两次退出）
• Ctrl+D：退出 Codex
• 遇到审批提示时，按回车确认或输入拒绝

指定沙箱模式运行：

# 只读模式，Codex 只能看不能改
codex --sandbox read-only

# 工作区写入模式，Codex 可以改当前项目文件
codex --sandbox workspace-write

# 完全访问模式（谨慎使用！）
codex --sandbox danger-full-access

直接传入提示词：

codex "解释一下这个项目的架构"

方法二：非交互式执行（自动化利器）

使用 codex exec 可以让 Codex 在无人值守下运行：

# 基本用法
codex exec "把所有 console.log 语句替换成 proper logging"

# 配合管道使用
git diff HEAD~1 | codex exec "总结这次的代码变更"

# 不保存会话记录（用完即弃）
codex exec --ephemeral "跑一下测试看看有没有问题"

# 把错误日志喂给Codex分析
npm test 2>&1 | codex exec "分析测试失败原因并给出修复建议"

非交互模式的输出直接打印到终端，方便你重定向到文件或管道到下一个命令。默认日志级别是 error，可通过 RUST_LOG 环境变量调整：

RUST_LOG=debug codex exec "详细分析这段代码的性能瓶颈"

方法三：MCP 集成 + 多Agent协作（进阶玩法）

连接 MCP 服务器扩展能力：

在 ~/.codex/config.toml 中配置 MCP 服务器：

# 连接一个文件系统 MCP 服务器
[mcp_servers.files]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

# 连接一个数据库 MCP 服务器（示例）
[mcp_servers.database]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
``

也可以用命令行管理 MCP 服务器：

添加 MCP 服务器

codex mcp add my-server npx -y @modelcontextprotocol/server-filesystem /path

列出已配置的 MCP 服务器

codex mcp list

查看 MCP 服务器详情

codex mcp get my-server

删除 MCP 服务器

codex mcp remove my-server

**把 Codex 变成其他 Agent 的工具：**

启动 MCP 服务端，让其他AI可以调用Codex

codex mcp-server

用 MCP Inspector 调试

npx @modelcontextprotocol/inspector codex mcp-server

**分层 Agent（派生子任务）：**

在 `config.toml` 中配置 Agent 角色：

[agents.test-runner] description = "专门负责运行和分析测试的Agent" nickname_candidates = ["tester", "runner"]

[agents.code-reviewer] description = "专门负责代码审查的Agent" nickname_candidates = ["reviewer", "auditor"]

全局Agent配置

maxthreads = 4 # 最多4个子Agent并发 maxdepth = 3 # 嵌套最多3层 jobmaxruntime_seconds = 300 # 每个子任务最多跑5分钟

---

## 六、实际使用场景表格

| 场景 | 你想做什么 | Codex 怎么做 | 推荐沙箱模式 |
|---|---|---|---|
| 代码审查 | 审查同事的PR，找出潜在问题 | `codex --sandbox read-only "审查 git diff 的变更，找出安全隐患和代码风格问题"` | `read-only` |
| Bug修复 | 测试报了个bug，不知道怎么改 | `codex "找到导致用户登录失败的bug并修复"` | `workspace-write` |
| 代码重构 | 老项目变量命名混乱，想统一 | `codex "把 src/ 下所有下划线命名的变量改成驼峰命名"` | `workspace-write` |
| 写单元测试 | 核心模块没测试，想补上 | `codex "给 src/auth.ts 写完整的单元测试，使用 Jest 框架"` | `workspace-write` |
| 文档生成 | 代码写了，文档没写 | `codex --sandbox read-only "给 src/api/ 下所有接口生成 JSDoc 注释和 README 文档"` | `read-only` |
| 技术栈迁移 | 项目从JS迁移到TypeScript | `codex "把 src/ 下的 .js 文件逐个迁移为 TypeScript，添加类型声明"` | `workspace-write` |
| CI集成 | 自动化流水线中修bug | `codex exec "分析失败日志并尝试修复" --ephemeral` | `danger-full-access`（容器内） |
| Git操作 | 创建分支、提交、提PR | `codex "创建 feature/login-refactor 分支，提交当前变更，推送到远程"`
（需 Git 2.23+） | `workspace-write` |
| 学习项目 | 刚接手祖传项目，看不懂 | `codex --sandbox read-only "解释这个项目的整体架构和数据流"` | `read-only` |
| 性能优化 | 接口响应慢，想找瓶颈 | `codex --sandbox read-only "分析 src/api/ 的性能瓶颈，给出优化建议"` | `read-only` |

---

## 七、同类工具对比

| 特性 | **Codex CLI** | **Claude Code** | **Cursor** | **GitHub Copilot CLI** |
|---|---|---|---|---|
| 开发商 | OpenAI | Anthropic | Cursor Inc. | GitHub/Microsoft |
| 运行方式 | 本地终端Agent | 本地终端Agent | IDE内集成 | 终端命令建议 |
| 底层模型 | GPT系列(o3/o4-mini等) | Claude Sonnet/Opus | 多模型可选 | GPT系列 |
| 项目级理解 | 支持（AGENTS.md） | 支持（CLAUDE.md） | 支持（.cursorrules） | 有限 |
| 沙箱安全 | 三级沙箱+Guardian | 有权限控制 | IDE内沙箱 | 无特殊沙箱 |
| MCP协议 | 客户端+服务端 | 客户端 | 部分支持 | 不支持 |
| 非交互模式 | 支持（codex exec） | 支持（claude -p） | 不支持 | 不支持 |
| 多Agent协作 | 支持分层Agent | 支持（子Agent） | 不支持 | 不支持 |
| Skill/插件系统 | 支持 | 支持（Tools） | 支持（Extensions） | 不支持 |
| 代码执行 | 本地执行+审批 | 本地执行+审批 | 本地执行 | 本地执行 |
| 开源 | 是（Apache-2.0） | 否 | 否 | 否 |
| 免费使用 | 需ChatGPT订阅或API | 需API Key | 订阅制 | 需订阅 |
| 中国网络 | 需代理访问OpenAI | 需代理访问Anthropic | 需代理 | 需代理 |

**简单总结**：
- **Codex CLI** 和 **Claude Code** 是同一赛道——都是终端级AI编程Agent，功能最全面，适合重度命令行用户
- **Cursor** 更适合喜欢在编辑器里写代码的开发者，界面友好但不如CLI灵活
- **GitHub Copilot CLI** 更像命令建议器，不是完整的Agent
- Codex CLI 最大优势：开源免费、沙箱安全最严格、MCP双向支持、多Agent协作
- Claude Code 最大优势：Claude模型代码能力强，生态成熟
- 对于中国开发者，网络是所有海外工具的共同难题，建议准备稳定的代理

---

## 八、小结

OpenAI Codex CLI 不是一个简单的代码补全工具，它是一个完整的**终端AI编程Agent**——在你本地运行，能读能写能执行，还有严格的沙箱安全机制保你平安。

**适合谁用？**
- 命令行重度用户、Vim/Neovim党、Tmux用户——Codex CLI 就是为你准备的
- 需要自动化代码处理的CI/CD工程师——`codex exec` 非交互模式太好用了
- 想要项目级AI助手的技术负责人——AGENTS.md + Skills 让AI真正理解你的项目
- 重视代码安全的团队——三级沙箱 + Guardian + 细粒度审批，比让AI直接跑安全多了

**不太适合谁？**
- 习惯了IDE内操作、不想碰终端的开发者——建议用Codex IDE插件
- 网络环境不稳定、没有OpenAI访问条件的用户——这是所有OpenAI产品的通用门槛

**一句话总结**：如果你是那种打开电脑第一件事就是开终端的人，Codex CLI 值得一试。它免费、开源、安全，而且真的能帮你干活——不是那种只会写 `console.log("hello")` 的玩具。

---

**项目地址**：[https://github.com/openai/codex](https://github.com/openai/codex)

**官方文档**：[https://developers.openai.com/codex](https://developers.openai.com/codex)

**安装命令**：`npm i -g @openai/codex` 或 `brew install --cask codex`

---

*本文由龙岗AI社区（longgang.ai）原创，转载请注明出处。*
*技术交流欢迎加入龙岗AI社区，关注中国开发者的AI实践。*