OpenAI Codex CLI 深度拆解：从安装到沙箱隔离的完整指南
OpenAI 官方开源的编码 Agent，能自主读写代码、执行命令、创建 PR。本文从环境部署到沙箱架构，带你一文看懂 Codex CLI 的构造逻辑。
一、Codex CLI 是什么？
Codex CLI 是 OpenAI 官方开源的命令行 AI 编码助手。它不是一个聊天机器人，而是一个能自主读写代码、执行 shell 命令、创建 Pull Request 的完整编码 Agent。
核心特点：
– 自主执行：不仅能建议代码，还能直接执行命令、创建文件、提交代码
– 沙箱隔离：三种安全模式，从只读到完全访问
– 多模型支持：GPT-5.5 / GPT-5.4 / o4-mini 等
– 项目上下文：自动读取 AGENTS.md / CLAUDE.md 等项目规则
– 非交互模式：可嵌入 CI/CD 管道和自动化工作流
GitHub Stars：40k+（开源 MIT 协议）
二、环境部署
2.1 系统要求
| 组件 | 要求 |
|---|---|
| Node.js | 22+ |
| OS | macOS / Linux |
| OpenAI API Key | 必需 |
| Docker | 可选（沙箱模式需要） |
2.2 安装
# npm 全局安装
npm install -g @openai/codex
# 或 pnpm
pnpm add -g @openai/codex
# 验证
codex --version
2.3 配置 API Key
# 方式一：环境变量
export OPENAI_API_KEY="sk-..."
# 方式二：配置文件
# ~/.codex/config.toml
[models]
default = "gpt-5.5"
2.4 目录结构
~/.codex/
├── config.toml # 主配置文件
├── instructions.md # 全局指令（类似 AGENTS.md）
└── skills/ # 技能目录
项目目录/
├── AGENTS.md # Codex 读取的项目规则
├── CLAUDE.md # 兼容 Claude Code 规则
├── codex.json # 项目级配置
└── src/ # 代码
三、核心架构
3.1 架构图
┌─────────────────────────────────────────────────┐
│ 用户交互层 │
│ ┌──────────────┐ ┌──────────────────────┐ │
│ │ 交互模式 │ │ 非交互模式 (-p) │ │
│ │ codex chat │ │ codex -p "fix bug" │ │
│ └──────┬───────┘ └──────────┬───────────┘ │
│ └──────────┬──────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Agent Loop │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ │
│ │ │ 上下文 │→│ LLM推理 │→│ 工具执行 │ │ │
│ │ │ 组装 │ │ (GPT-5) │ │ (读/写/执行) │ │ │
│ │ └─────────┘ └─────────┘ └─────────────┘ │ │
│ │ ↑ │ │ │
│ │ └─────────────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 沙箱层 │ │
│ │ ┌───────────┐ ┌────────────┐ │ │
│ │ │ read-only │ │ workspace │ full-access │ │
│ │ └───────────┘ └────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
3.2 Agent Loop
Codex 的核心是一个自主循环：
1. 读取用户指令 / 项目上下文
2. 组装 prompt（系统指令 + 项目规则 + 历史对话）
3. 调用 LLM（GPT-5.5 等）
4. 解析 LLM 输出的工具调用
5. 在沙箱中执行工具（读文件/写文件/执行命令）
6. 将执行结果反馈给 LLM
7. 重复 3-6 直到任务完成或用户中断
关键区别：Codex 的 Agent Loop 是完全自主的——用户给一个目标，Codex 自行规划步骤并执行，不需要逐步确认（取决于 approval-policy）。
3.3 交互模式 vs 非交互模式
| 模式 | 命令 | 用途 |
|---|---|---|
| 交互模式 | codex |
实时对话，逐步引导 |
| 非交互模式 | codex -p "fix bug" |
自动化，CI/CD 管道 |
| Quiet 模式 | codex -q |
最少输出，仅最终结果 |
四、沙箱隔离（核心卖点）
Codex 的沙箱设计是其最大亮点，解决了”AI Agent 乱执行命令”的核心安全问题。
4.1 三种沙箱模式
| 模式 | 文件权限 | 命令权限 | 适用场景 |
|---|---|---|---|
| read-only | 只读 | 仅白名单命令 | 代码审查、分析 |
| workspace-write | 仅工作区可写 | 受限命令 | 日常开发（推荐） |
| danger-full-access | 完全访问 | 无限制 | 信任环境、CI |
# 只读模式（最安全）
codex --sandbox read-only "review this code"
# 工作区写入模式（推荐）
codex --sandbox workspace-write "fix the bug"
# 完全访问模式（危险！）
codex --sandbox danger-full-access "deploy to production"
4.2 沙箱实现
┌─────────────────────────────────────────┐
│ Codex Agent │
│ │ │
│ ┌───────┴───────┐ │
│ │ 沙箱管理器 │ │
│ └───────┬───────┘ │
│ ┌───────────┼───────────┐ │
│ │ │ │ │
│ ┌──┴──┐ ┌───┴───┐ ┌──┴──────┐ │
│ │Docker│ │Rootless│ │ 无沙箱 │ │
│ │容器 │ │ 容器 │ │(danger) │ │
│ └──────┘ └───────┘ └─────────┘ │
│ │
│ Docker 不可用时的回退： │
│ → 使用文件系统权限限制 │
│ → 限制可执行命令白名单 │
└─────────────────────────────────────────┘
沙箱执行流程：
1. Agent 请求执行命令
2. 沙箱管理器检查当前策略
3. 根据策略决定：允许/拒绝/需审批
4. 在隔离环境中执行（Docker 容器或受限文件系统）
5. 返回执行结果
4.3 命令白名单
read-only 模式允许的命令：
– cat, head, tail, ls, find, grep, wc
– git status, git log, git diff, git show
– node -e, python -c（只读执行）
workspace-write 模式额外允许：
– git add, git commit, git push
– npm install, pip install
– 文件创建/修改（仅工作区内）
五、Approval Policy（审批策略）
审批策略控制 Agent 执行命令时是否需要用户确认：
| 策略 | 行为 | 适用场景 |
|---|---|---|
| untrusted | 所有命令都需确认 | 首次使用、不信任的代码 |
| on-failure | 仅失败时确认 | 日常开发 |
| on-request | 仅 Agent 请求确认 | 熟悉项目 |
| never | 从不确认 | CI/CD 自动化 |
# 默认策略：untrusted（最安全）
codex --approval-policy untrusted "fix bug"
# 熟悉项目后可放宽
codex --approval-policy on-failure "add tests"
# CI/CD 中完全自动
codex --approval-policy never -p "run tests and fix failures"
六、项目上下文注入
Codex 会自动读取项目中的规则文件：
| 文件 | 作用 | 优先级 |
|---|---|---|
AGENTS.md |
Codex 原生规则 | 最高 |
CLAUDE.md |
兼容 Claude Code 规则 | 次之 |
codex.json |
项目级配置 | 配置 |
~/.codex/instructions.md |
全局指令 | 全局 |
AGENTS.md 示例：
# Project Rules
## Testing
- Run tests with: `npm test`
- Test framework: Jest
- Always write tests before fixing bugs
## Code Style
- TypeScript strict mode
- Use async/await, no .then()
- No any types
七、工作流实战
7.1 Bug 修复
codex -p "Fix the TypeError in src/parser.ts line 42"
--sandbox workspace-write
--approval-policy on-failure
7.2 创建 PR
codex -p "Add input validation to the login form and create a PR"
--sandbox workspace-write
--approval-policy never
7.3 代码审查
codex -p "Review the last commit for security issues"
--sandbox read-only
7.4 批量重构
codex -p "Rename all 'user_id' to 'userId' across the codebase"
--sandbox workspace-write
--approval-policy on-request
7.5 CI/CD 集成
# GitHub Actions
- name: Auto-fix lint errors
run: |
codex -p "Fix all ESLint errors"
--sandbox workspace-write
--approval-policy never
--model o4-mini
八、与同类框架对比
| 特性 | Codex CLI | Claude Code | Hermes | OpenClaw |
|---|---|---|---|---|
| 定位 | 编码 Agent | 编码 Agent | 通用 Agent | 个人助手 |
| 开源 | ✅ MIT | ❌ | ✅ | ✅ |
| 沙箱 | ✅ 三级隔离 | ⚠️ 有限 | ✅ | ✅ Docker |
| 通讯渠道 | ❌ 终端 | ❌ IDE | ✅ Telegram/QQ | ✅ 20+ |
| 模型 | GPT 系列 | Claude 系列 | 任意模型 | 任意模型 |
| 非交互 | ✅ -p 模式 | ✅ -p 模式 | ✅ cron | ✅ |
| Cron | ❌ | ❌ | ✅ | ✅ |
| 技能系统 | ✅ skills/ | ❌ | ✅ SKILL.md | ✅ ClawHub |
| 项目规则 | AGENTS.md | CLAUDE.md | AGENTS.md | AGENTS.md |
九、总结
Codex CLI 的核心价值在于：
- 安全第一：三级沙箱 + 四级审批，从架构层面解决 AI Agent 安全问题
- 自主执行：不是建议工具，是执行工具——直接改代码、提交 PR
- CI 友好：-p 模式 + never 策略，完美嵌入自动化管道
- OpenAI 官方：模型+工具一体化，深度优化
适用场景：日常编码、批量重构、CI/CD 自动修复、代码审查。
不适用：通讯助手、多渠道交互、定时任务——这些是 Hermes/OpenClaw 的领地。
参考链接
本文基于 Codex CLI 源码和官方文档整理，如有更新请以官方文档为准。
