Codex CLI 完全使用手册：OpenAI 命令行编程工具核心功能与进阶技巧详解

如果你用过 GitHub Copilot 或者在编辑器里接入过 GPT-5.5，会发现有一类场景它们都不太擅长：跨文件重构、自动跑测试、根据错误输出自我修正。这正是 Codex CLI 的设计目标——一个运行在终端里的编程代理，能读写文件、执行命令、在沙箱里迭代，直到任务完成。本文是一份系统性的 Codex CLI 使用教程，不讲概念，只讲怎么用。

安装与基础配置

Codex CLI 通过 npm 分发，Node.js 18+ 环境直接安装：

npm install -g @openai/codex
codex --version

安装后第一件事是设置 API Key。Codex 读取环境变量 OPENAI_API_KEY，推荐写进 ~/.zshrc 或 ~/.bashrc：

export OPENAI_API_KEY="sk-..."

默认模型是 GPT-5.4，如果想用旗舰级的 GPT-5.5 或者成本更低的 GPT-5.4-mini，通过 --model 参数指定：

codex --model gpt-5.5 "重构这个项目的错误处理逻辑"
codex --model gpt-5.4-mini "给所有函数补上 JSDoc 注释"

三个模型的选择逻辑很直接：复杂架构决策用 GPT-5.5，日常编码任务用 GPT-5.4，批量文档或简单重复性工作用 mini，后者成本约是旗舰的 1/8。

沙箱模式：安全执行的核心机制

Codex CLI 最值得单独讲的设计是它的审批模式（approval mode），本质上是一套分级沙箱，控制 AI 在没有人类确认的情况下能做什么。

有三个档位：

模式	文件写入	执行命令	网络访问	适用场景
suggest	仅建议	❌	❌	只看不动，代码审查
auto-edit	✅ 自动	需确认	❌	文件修改，命令手动批准
full-auto	✅ 自动	✅ 自动	可配置	CI/CD、无人值守脚本

日常开发推荐 auto-edit，它会直接修改文件但在执行 npm test 或 git commit 这类命令前暂停让你确认：

codex --approval-mode auto-edit "修复所有 TypeScript 类型错误"

full-auto 模式下，Codex 会在沙箱网络隔离环境中运行，默认禁止出站连接。需要它访问 npm registry 时，可以通过 --allowed-hosts 白名单放行：

codex --approval-mode full-auto \
  --allowed-hosts registry.npmjs.org \
  "安装依赖并跑通测试套件"

实际测试中，full-auto 在一个中型 Node.js 项目里跑完「安装依赖 → 执行测试 → 修复失败用例 → 再次验证」完整循环大约需要 4~6 轮迭代，GPT-5.5 通常比 GPT-5.4 少 1~2 轮。

文件编辑与多步骤任务执行

Codex 不是简单的代码补全，它是一个有持久上下文的编辑代理。运行时它会把当前目录的文件树和 git diff 信息注入上下文，理解你在做什么。

典型的多步骤工作流：

# 1. 在项目根目录启动（自动读取目录结构）
cd my-project
codex "把所有 REST 接口从 Express 迁移到 Fastify，保留现有路由签名"

Codex 会依次：分析现有路由文件 → 生成迁移计划 → 按文件逐个修改 → 更新 package.json 依赖 → 建议运行测试命令。整个过程它会输出每一步的操作日志，你可以随时 Ctrl+C 中断。

对于需要跨多个 session 延续的长任务，使用 --context 加载上次的会话快照：

codex --context .codex/session_abc123.json "继续上次的重构，处理剩余的 auth 模块"

.codex/ 目录下的 session 文件记录了对话历史和已完成的文件操作，方便任务中断后恢复。

有一个细节值得注意：Codex 默认只处理 git 追踪的文件，.gitignore 里的路径不会被读取或修改。这个设计防止它误动 .env 或 node_modules，但如果你想让它处理未追踪文件，需要加 --include-untracked。

进阶技巧：提示词工程与自定义指令

写给 Codex 的 prompt 和写给普通聊天模型的不一样，它执行的是任务，不是对话。几个有效果的模式：

约束输出范围：越具体越好。"重构错误处理"比"改进代码质量"执行结果稳定得多。明确告诉它目标文件、技术栈约束、不能改动的接口。

利用 AGENTS.md：在项目根目录放一个 AGENTS.md 文件，Codex 每次启动会自动读取它作为系统指令。适合写项目规范：

# 项目规范
- 使用 pnpm，不用 npm 或 yarn
- 测试框架是 Vitest，不是 Jest
- 所有异步函数必须有错误边界
- 提交前必须通过 `pnpm lint`

这等价于给每次对话预埋了 200 字的上下文，省去反复交代背景的成本。

管道用法：Codex 接受 stdin，可以把错误日志直接喂给它：

pnpm test 2>&1 | codex "根据这些测试失败信息修复代码"

或者把代码审查意见转成自动修复：

cat review_comments.txt | codex --approval-mode auto-edit "应用这些代码审查建议"

对比其他编码 CLI：Codex 的直接竞品是 Anthropic 的 Claude Code 和 Google 的 Gemini CLI。Claude Code 在长上下文理解和多文件一致性上有优势（Claude Opus 4.8 的上下文窗口更大）；Gemini CLI 与 Google 工作区集成更紧密；Codex 的优势在于与 OpenAI 生态的原生集成以及 GPT-5.5 在代码生成指标上的表现。三者的 API 接口格式差异不大，用 OpenAI 兼容的中转服务可以在同一个项目里切换测试。

---

用 Codex CLI 久了会有一个体会：它真正的价值不在于写代码有多快，而在于能把「写代码 → 跑测试 → 看报错 → 修复 → 再跑」这个循环自动化。如果你同时在跑 Claude Code 或 Gemini CLI 做横向对比，或者想用更低成本跑 GPT-5.5 / GPT-5.4，推荐看一下 XycAi 词元平台（https://www.xyc.ai）。它是 OpenAI 兼容接口，200+ 模型统一接入，GPT 和 Claude 官方模型最低到官方价 1.4 折，而且原生支持 Codex CLI / Claude Code / Gemini CLI 一键切换——改一个环境变量就能跑，不用动工作流里的其他配置。