OpenAI Codex CLI

Codex CLI 是 OpenAI 推出的开源终端编程代理，用 Rust 编写，Apache 2.0 许可证。它把 OpenAI 的编码模型、文件编辑、命令执行、沙箱和审批机制放到同一个终端工作流里。

GitHub: github.com/openai/codex

核心特点

• Rust 编写 — 性能极高，启动快
• 完全开源 — Apache 2.0，可审计、可修改
• 沙箱优先 — 支持按工作区、网络、系统权限分层控制
• 多模型支持 — 可使用 OpenAI 当前推荐的 Codex / GPT 编码模型
• AGENTS.md — 用轻量项目文件描述仓库规范
• 非交互执行 — codex exec 适合 CI、脚本和批处理

安装

Codex CLI 的安装方式会随平台更新。常见方式是：

npm i -g @openai/codex

Homebrew（macOS）

brew install --cask codex

也可以按官方 README 使用最新推荐的安装脚本或包管理器命令。

登录与认证

export OPENAI_API_KEY="sk-xxxxx"

或在 ~/.codex/config.toml 中配置：

[auth]
api_key = "sk-xxxxx"

如果你有支持 Codex 的 ChatGPT 订阅或企业账号，也可以按 CLI 引导使用账号登录。团队环境建议优先使用组织统一的账号、API key 或 OIDC/secret 管理，不要把 key 写进仓库。

基本使用

交互模式

codex

进入后直接用自然语言描述任务。

带指令启动

codex "修复测试中的错误"

全自动模式

codex --full-auto "运行所有测试并修复失败的"

全自动模式适合隔离环境或可信仓库。生产仓库里仍建议保留审批和测试门禁。

CI/非交互模式

codex exec "生成 changelog"

恢复上次会话

codex resume --last

权限模式

Codex CLI 的核心不是“让模型随便跑”，而是通过 sandbox 与 approval mode 控制它能做什么：

沙箱机制

这是 Codex CLI 最大的技术亮点：

macOS

使用 Apple Seatbelt 机制（sandbox-exec），动态生成沙箱策略文件，限制文件访问和网络。

Linux

三层防护：

• Landlock — 文件系统限制
• seccomp — 系统调用过滤
• Bubblewrap (bwrap) — 文件系统命名空间隔离

默认建议是：网络默认收紧，写权限限定在工作区内；如果任务确实需要联网、安装依赖或访问外部路径，再显式放开。

AGENTS.md

类似 Claude Code 的 CLAUDE.md，Codex 使用 AGENTS.md 文件：

# 项目规范
- 使用 TypeScript strict mode
- 测试用 Vitest
- 提交信息用英文

# 编码风格
- 函数式优于面向对象
- 优先使用 const

建议把它写得像“项目交接卡”：

• 项目怎么启动、测试、构建
• 代码风格和命名规范
• 哪些目录不能乱动
• commit / PR 边界
• 安全规则，比如不提交密钥、不直接改生产配置

子目录可以有自己的 AGENTS.md，用于覆盖局部规范。

独特功能

Web 搜索与外部资料

Codex 可以在支持的环境中使用 Web 搜索或外部资料能力。处理新框架、新 API、最新错误时，建议明确要求它查官方文档，而不是只靠模型记忆。

图片输入

codex "根据这个截图实现 UI"
# 然后粘贴或拖入截图

MCP 支持

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

[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

并行 Agent

可以用多个 Codex 会话或多个 Git worktree 并行探索不同方案。多人/多 agent 协作时，务必让每个分支只做一件事，避免最后 merge 时互相踩代码。

模型切换

在交互模式中可以按 CLI 当前支持的命令切换模型。不要把模型名写死成过时版本，优先用 OpenAI 当前推荐的编码模型：

/model

文件搜索

输入 @ 进行模糊文件搜索。

注入指令

Codex 运行过程中按 Enter 可以注入新指令，不需要等它完成。

支持的模型

具体模型列表会随 OpenAI 平台和 Codex 版本变化，不建议在团队文档里硬编码某个短期版本号。

更稳的写法是：

真正上线前要看三件事：能不能稳定改文件、能不能跑测试、失败时能不能恢复。