Codex CLI

Codex CLI 快速入门

一句话卖点:OpenAI 的终端 AI 编程 Agent —— 在命令行里说一句话,AI 帮你写代码、修 Bug、跑测试,直到任务完成。

这是什么?适合谁?

Codex CLI 是 OpenAI 于 2026 年 4 月开源、2026 年 6 月发布 1.0 稳定版的终端 AI 编程 Agent,主仓库 openai/codex,Apache-2.0 协议。它与 GitHub Copilot Tab 补全、Cursor 嵌入式 AI 的区别是:Codex CLI 是一个真正的 Agent —— 它能理解你的需求、阅读代码库、执行命令、修改文件、运行测试,直到把任务完成。

它跟 Claude Code 几乎同时发布、是 2026 年 AI 编程 CLI 最热门的两个选择。Codex CLI 的差异化优势:

• 多模型后端:支持 OpenAI(官方推荐)、Anthropic Claude、Google Gemini、DeepSeek 等;
• 沙箱执行:代码运行在受限沙箱里,默认禁止网络外联、禁止写入系统目录;
• Git 原生集成:自动感知 git 状态、diff、commit 风格;
• AGPL 友好的开源:与闭源商用工具不同,Codex CLI 完全开源可审计;
• 可二次开发:Rust 实现的 CLI + Node.js SDK,可以嵌入到自己的工具链里。

适合谁?一是全栈开发者,想让 AI 处理重复性编码任务(CRUD、测试、重构);二是技术 Leader,想快速验证技术方案或生成原型;三是开源贡献者,想快速理解陌生代码库并提交 PR;四是AI 编程研究者,想对比不同 CLI Agent 的设计哲学。

不适合:编程初学者(需要能看懂 AI 生成的代码)、需要 GUI 的开发者(用 Cursor 或 Windsurf)、纯 Windows cmd 用户(建议装 WSL2)。

准备工作

1. 环境:macOS / Linux 原生支持,Windows 需 WSL2;
2. Node.js:≥ 18;
3. 安装:npm install -g @openai/codex 或 brew install openai/tap/codex;
4. API Key:至少一个模型提供商的 API Key(OpenAI 推荐,也支持 Anthropic / Google / DeepSeek / 通义千问 / 智谱);
5. 前置知识:命令行基础、Git 基本操作、对自己的项目有「能 review 改动」的能力。

3 步快速上手

第 1 步:安装并配置

# 方式 1:npm 全局安装
npm install -g @openai/codex

# 方式 2:macOS Homebrew
brew install openai/tap/codex

# 验证安装
codex --version

设置 API Key 和默认模型:

export OPENAI_API_KEY="sk-xxx"

# 切换模型后端(默认是 o4-mini,工程任务推荐)
codex config set model openai/o4-mini

# 用 Anthropic 后端
codex config set model anthropic/claude-sonnet-4-20250514
export ANTHROPIC_API_KEY="sk-ant-xxx"

第 2 步:进入项目并启动

cd my-project

# 完整模式(默认):Agent 可读写文件、执行命令
codex

# 只读模式:Agent 只读代码、回答问题、不改文件 — 适合探索陌生代码库
codex --read-only

第 3 步:用自然语言提出任务

> 给 src/api.py 的所有 Express 路由加上请求日志,记录每个请求的路径、耗时和状态码

Codex 会自动:

1. 读取 src/api.py 理解代码结构;
2. 规划 改动方案(添加中间件);
3. 修改 文件(用 patch 方式);
4. 运行 测试(npm test)验证不破坏现有功能;
5. 汇报 改动清单和测试结果。

你看完 diff 按 Enter 接受或拒绝,或输入具体修改意见让 Codex 继续调整。

初级用法

• 任务式交互:对 Codex 说一段自然语言描述,Codex 自己拆解、执行、汇报;
• 单文件改写:codex edit src/foo.py — 把所有 var 换成 const(实验性,部分版本支持);
• 代码审查:codex review 用一个独立会话审视刚生成或某条 commit 的改动;
• 测试驱动:让 Codex 先写测试再写实现 — 显著降低幻觉代码率;
• 沙箱调整:codex --sandbox workspace-only(只允许读写当前目录,默认),--sandbox danger-full-access(关闭沙箱,慎用);
• 指定文件:codex apply — 给 src/foo.py 加单元测试(只对指定文件操作)。

高级玩法

• 集成 GitHub PR 工作流:Codex CLI 可作为 CI 步骤跑,自动给 PR 加单元测试、文档、迁移脚本;
• 多模型协作:用便宜模型(deepseek-chat)做初稿,用强模型(o3)做 review,平衡成本和质量;
• 自定义 System Prompt:.codex/instructions.md 里写项目级约定(命名规范、不改动的目录、首选库),所有会话遵守;
• Hook 集成:.codex/hooks/*.sh 在 session 开始/结束/任务完成时跑自定义脚本(发 Slack 通知、更新看板);
• Embed 到 CI:codex "为这个 PR 加 CHANGELOG 条目" < pr-diff.txt > CHANGELOG.md;
• 多 Agent 协作:对 Codex 说「先让一个 Agent 找出性能瓶颈,再让另一个 Agent 修」,Codex 内部会拆分任务;
• 自定义沙箱网络:开发环境允许 Codex 临时访问测试 API(--network test-only 配置,具体看官方文档)。

小技巧

1. 任务描述要明确文件 + 验收标准:「给 src/api.py 加日志中间件,记录 method/path/status/duration,通过现有测试」比「加点日志」完成率高得多;
2. 先用 —read-only 探索陌生项目:不破坏代码情况下让 Codex 解释架构,然后再针对性改;
3. 大型任务拆分:不要一次让 Codex 加「整个用户系统」,拆成「加 User 模型 → 加注册路由 → 加登录路由 → 加 JWT 中间件」;
4. 配合 Git 工作流:让 Codex 在 git worktree 里改,验证通过后合并主分支,出问题可一键回滚;
5. 用 dry-run 预览:codex apply --dry-run < task.md 在正式改动前看 Codex 计划做什么;
6. 设置 token 预算:codex config set max-budget-usd 1.0,防止 Agent 失控烧钱;
7. 善用 —search:在大型 monorepo 里先 codex --search "帮我找认证相关代码" 定位再改动,事半功倍。

常见踩坑

踩坑 1:Codex 修改了不该改的文件

• 症状:Codex 修改了配置文件 / .lock 文件 / 第三方目录
• 原因:任务描述不够精确,或代码库结构复杂
• 解决:① 任务里明确指定文件路径;② 用 .codexignore 排除不需要修改的目录(类似 gitignore)

踩坑 2:API 费用失控

• 症状:一次任务消耗数十万 token,账单几百美元
• 原因:Codex 需要读取大量代码上下文,Agent 推理会产生多次 LLM 调用
• 解决:① 用便宜模型(DeepSeek/o4-mini)做初稿,强模型做 review;② 用 codex apply --dry-run 预览;③ 拆分任务别一次让 Agent 处理全仓库

踩坑 3:生成的代码有隐藏 Bug

• 症状:测试通过但生产环境报错
• 原因:Codex 对复杂业务逻辑理解有限,生成的代码看着对但有边界 case 问题
• 解决:① 要求 Codex 在生成时运行测试(必须运行 npm test,失败则修复);② 用 codex review 让另一个模型审查;③ 人工 review diff 再合并

踩坑 4:Windows 原生不支持

• 症状:codex 命令在 PowerShell 里报路径错误或 API 404
• 原因:Codex CLI 不原生支持 Windows,虽然可以通过 Git Bash 部分工作,但稳定性差
• 解决:装 WSL2,在 WSL2 里跑 Codex CLI,这是官方推荐方式

踩坑 5:沙箱阻止了需要的网络请求

• 症状:Codex 装依赖时失败报 permission denied
• 原因:沙箱默认禁止网络外联,防止 Agent 跑路
• 解决:codex --sandbox workspace-only --network on 允许特定网络访问;或在 .codex/config.toml 配白名单

踩坑 6:Agent 陷入重复循环

• 症状:Codex 一直修同一个测试不退出
• 原因:测试或 prompt 设计有歧义
• 解决:在指令里加「修复最多 3 次,仍失败则停下来汇报问题」;设置 codex config set max-iterations 10

常见问题 FAQ

Q1: Codex CLI 是免费的吗?

A: Codex CLI 本身是 Apache-2.0 开源免费。但用它需要付费访问 LLM API:OpenAI 用户用 ChatGPT Plus($20/月起)或 API 付费(按 token 计费,Codex CLI 推荐用 o4-mini、约 $1.1/$4.4 每百万 token);用 DeepSeek 后端可低至 $0.14/$0.28 每百万 token;订阅 Claude Pro/Gemini Advanced 也可以用对应模型的 API。

Q2: Codex CLI 和 Claude Code 怎么选?

A: 两者功能高度重叠。区别:① 后端模型:Codex 默认 OpenAI、Claude Code 默认 Anthropic,两个底层模型都很强;② 生态:Codex 与 ChatGPT 桌面 App 集成更深,Claude Code 与 Claude.ai web 同步;③ 开源:Codex CLI 完全 Apache-2.0 开源,Claude Code 部分闭源;④ 功能:Claude Code 的 Sub-agent / Task 工具略强,Codex CLI 的沙箱和 Git 集成略强。建议两个都装,根据任务切后端模型。

Q3: Codex CLI 能生成 PR 吗?

A: 能,常见两种方式:① Code 在 git 分支上做改动,你 git push 后开 PR;② 直接让 Codex 用 gh CLI 开 PR:codex "为当前改动开 PR,标题是 feat: 加请求日志"。后者依赖 GitHub CLI 认证。

Q4: 在大型 monorepo 里 Codex 慢怎么办?

A: 三个手段:① 用 --search / 让 Codex 先 grep 定位再改,而不是读全仓库;② 拆分任务,只让 Codex 处理一个 service;③ 配置 .codexignore 排除 node_modules vendor dist 等大目录。

Q5: Codex CLI 安全吗?会不会把我的密钥发到网上?

A: 默认安全:① 沙箱禁止网络外联,本地模型调用 OpenAI 时脱敏处理;② 所有改动通过 patch,不会悄悄 commit;③ 你可以 --read-only 跑只读会话。但 — 不要把 OPENAI_API_KEY 等密钥贴在 prompt 里,Codex 是基于 LLM 的,prompt 里出现的密钥会随请求发到 LLM 提供商(他们有 retention 策略,但风险不为零)。用 env var 注入。

Q6: Codex CLI 能跑在 CI 里吗?

A: 可以。GitHub Actions / GitLab CI 里直接 npm i -g @openai/codex && codex --non-interactive "为 diff 加单元测试"。注意:① 用 --non-interactive 避免卡在交互;② 给 GitHub Action 注入 OPENAI_API_KEY 密文;③ 配合 --max-budget-usd 防止失控。

进阶学习建议

Codex CLI 是 2026 年最年轻的 AI 编程 Agent 之一,虽然功能丰富,但上手曲线比 Cursor / Copilot 略陡。建议分四阶段:

• 第 1 阶段:基础对话(2~3 天):本节 3 步上手 + 简单改文件 + --read-only 探索代码。这阶段结束时你应该能熟练用 Codex 改小 bug、加测试、写文档;
• 第 2 阶段:项目级配置(1 周):写 .codex/instructions.md、.codexignore、自定义 hook、把 Codex 嵌入团队的 PR 流程;
• 第 3 阶段:多模型策略(1~2 周):理解什么时候用什么模型 — 探索用 o4-mini / DeepSeek,生产级 PR 用 o3 / Claude Opus,复杂重构用 GPT-5;学会读 token 账单、调 prompt 减少无效调用;
• 第 4 阶段:Agent 系统(持续):学习 Codex CLI 内部架构(sandbox / hooks / sessions),用 Rust 二次开发或基于 Code SDK 构建自定义 Agent。

学习资源优先级:① 官方 README:每个版本更新看 GitHub releases,API 变化最快;② openai/codex 仓库 examples:有大量工作流模板;③ Andrew Ng / Harrison Chase 的 Agent 教程:理解 Agent 概念;④ LangChain Academy:对比学习 Agent 编排思想;⑤ 社区 Discord 和 HN:Codex CLI 是 2026 年新工具,很多实战经验在社区。

最佳实践:① 把 Codex 当「团队里新来的 senior engineer」 — 任务明确、要求验证、人工 review;② 不要把整个项目喂给 Codex,先 grep 定位再改;③ 给 Codex 时间,慢思考的 prompt 比快思考 prompt 质量高 2-3 倍。

参考链接

• Codex CLI GitHub
• OpenAI Codex 官方文档
• Codex CLI 快速入门
• Codex CLI 配置参考
• Codex CLI Hooks 文档

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测