Codex CLI 新手教程

1 这是什么

Codex CLI 是 openai/codex 开源的一个终端编码 Agent，官方一句话定义是 "Lightweight coding agent that runs in your terminal"。它不是补全插件，也不是聊天框——它会在你的项目目录里真正地执行命令、改文件、跑测试，然后把改动以 diff 的形式摊给你看。

三个容易混淆的入口，先分清：

2 为什么需要它

在它之前，"让 AI 帮我改代码"基本靠三种凑合办法，每种都卡在同一个地方：

第二个洞察是把约定固化下来：AGENTS.md 让"这个项目怎么构建、怎么测试、哪些目录别碰"变成随仓库走的文件，Agent 每次开工前先读，而不是每一轮对话都重新猜一遍你的习惯。

3 核心流程

一次典型的 Codex 任务只有三步，中间那步是它替你干的：

4 安装

四条路，挑一条就行。独立安装脚本最省事，它会从 releases.openai.com 拉预编译二进制，装不上再自动回退到 GitHub Releases。

Windows 只有一条路：Windows 11 + WSL2，在 WSL 里按 Linux 装。原生 Windows 不在支持列表里（有独立的 Windows 沙箱文档页，但 CLI 主路径是 WSL2）。PowerShell 安装脚本为 Windows 场景提供：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

想强制走 GitHub Releases（比如公司网络拦了 releases.openai.com）：

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

从 GitHub Release 手动下载时，挑你平台那一个，解压后重命名成 codex：

更新和装是同一条命令：再跑一次安装脚本，或 codex update。

5 环境自检

装完先跑这三条，全绿再往下走：

codex --version          # 我本地实测输出：codex-cli 0.153.0
codex login status       # 看当前登录状态
codex doctor             # 一次性诊断安装、配置、鉴权、运行时健康度

6 第一次实战

别拿真实项目开刀。先建一个能删的沙盒仓库，五分钟跑通全流程。

# 1 建一个临时项目并进 git（Codex 默认要求在 git 仓库里跑）
mkdir -p ~/demo/hello-codex && cd ~/demo/hello-codex
git init

# 2 放一个有问题的文件
printf 'def add(a, b):\n    return a - b\n' > calc.py

# 3 启动交互式会话（首次会让你登录）
codex

进到 TUI 之后按顺序做：

/init                            # 让它扫一遍仓库，生成 AGENTS.md
"calc.py 里的 add 函数算错了，改对并补一个 pytest 测试，然后跑测试给我看"
/permissions                     # 想改权限边界时开这个面板
/status                          # 看当前会话的模型、目录、配置
?                                # 忘了快捷键就按问号

想让它改别处的文件（比如 monorepo 里的兄弟目录），启动时加 --add-dir；想在非 git 目录里跑，加 --skip-git-repo-check。

codex --add-dir ../shared-types
codex -C ~/other/project "看看这里的构建为什么挂了"   # -C 指定工作根目录

7 产物结构

Codex 会在你机器上留下这几类文件。搞清楚它们在哪，出问题时才知道该删哪个、该改哪个。

SKILL.md 的样子（front matter 里的 description 决定它什么时候被自动挑中，写清楚很重要）：

---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants
  to commit, organize commits, or clean up a branch before pushing.
---

1. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

8 日常怎么用

TUI 里的斜杠命令是最常用的五个：

终端外更常用的是这些子命令：

9 进阶玩法

9.1 非交互执行：codex exec

交互式 TUI 适合探索，流水线里要用 exec：一次调用、跑完就退、输出可被程序消费。

# 只读沙箱里审一段 diff，输出 JSONL 给后续脚本处理
codex exec --sandbox read-only --json "总结这个 diff 的风险点"

# 把最后一条消息写到文件，方便贴到 PR 评论里
codex exec -o /tmp/review.md "审查未提交的改动"

# 从 stdin 喂提示词；配合 --cd 指定仓库
git diff | codex exec --cd ~/code/my-app - "解释这次改动会影响哪些调用方"

# 结构化输出：给它一个 JSON Schema，让它按格式答
codex exec --output-schema ./schema.json "列出所有公开函数及其参数"

CI 里常用的几个附加参数：--json（JSONL 事件流）、-o（最后消息落盘）、--ephemeral（不落会话文件）、--skip-git-repo-check（非 git 目录也能跑）、--strict-config（config.toml 有它不认识的字段就报错，防拼写错误）。

exec 默认日志级别是 RUST_LOG=error 且直接打在终端里；TUI 想看明文日志要显式开：

codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log

9.2 代码审查：codex review

codex review --uncommitted          # 审 staged / unstaged / untracked 改动
codex review --base main            # 对比基线分支（PR 风格）
codex review --commit abc1234       # 审某个 commit 引入的改动

9.3 会话管理：resume / fork / archive

codex resume --last                       # 接着最近一次会话
codex resume --all                        # 列出所有会话（不限当前目录）
codex fork --last                         # 从最近一次分叉出一条新分支重来
codex resume --include-non-interactive    # 把 exec 跑过的也算进来
codex archive <会话名或 id>                # 归档；delete 是彻底删除

9.4 接外部系统：MCP

MCP（Model Context Protocol）是 Codex 连外部工具的标准方式：Codex 是 host，内部连接是 client，外部系统（Figma、Linear、GitHub、内部知识库）是 server。server 可以暴露 tools（动作）、resources（数据）、prompts（模板）。

codex mcp list                       # 看已配置的服务器
codex mcp add --url https://example.com/mcp
codex mcp get <name>
codex mcp remove <name>

9.5 把重复流程变成技能：Skills

一个技能 = 一个 SKILL.md，可带 scripts/、references/、assets/。Codex 用渐进披露加载：先只拿 name + description 做发现，选中了才读 SKILL.md，真正需要时才读 references 或跑 scripts——所以技能再多也不会一上来撑爆上下文。

放全局（~/.agents/skills）还是仓库（.agents/skills），取决于这个流程是"你个人的习惯"还是"团队的规矩"。技能是编写格式，plugin 是分发单元：要跨团队发就把技能打包成 plugin。

9.6 其余好用的开关

codex -c model="o3" -c 'sandbox_permissions=["disk-full-read-access"]'
codex -c shell_environment_policy.inherit=all
codex --enable hooks

10 不止于此

名字叫 CLI，但它能待的地方不止终端：

11 沙箱与审批：先把边界定好

这是用 Codex 之前最该花两分钟搞懂的一节。两个维度各自独立：

能碰什么（-s, --sandbox）

什么时候问你（-a, --ask-for-approval）

还有两个明确标着危险的开关，看名字就该知道用途：

• --approve-for-me：把审批请求转交给自动审查，配合 workspace-write 沙箱使用。
• --dangerously-bypass-approvals-and-sandbox：跳过一切确认且不沙箱化。文档原话是 EXTREMELY DANGEROUS，只该用在已经外部沙箱化的环境里。

# 日常推荐组合：项目内放开写，越界才问我
codex -s workspace-write -a on-request

# CI 里的审查任务：只读 + 不打断
codex exec --sandbox read-only -a never "审查这个 diff"

12 FAQ / 踩坑

13 开源与贡献政策

许可证是 Apache-2.0，商用没问题。但有一条和其他开源项目很不一样，值得提前知道：

想自己改代码自己用，可以从源码构建（Rust 工具链）：

git clone https://github.com/openai/codex.git
cd codex/codex-rs
cargo build
cargo run --bin codex -- "explain this codebase to me"

完整构建流程（rustfmt、clippy、just、dotslash、nextest 等）见仓库 docs/install.md。仓库还提供 DotSlash 文件，可以在源码控制里锁定所有人用同一个版本的二进制。

14 参考链接