Codex CLI 使用技巧

Codex CLI 不只是一个“在终端里聊天的 AI”。把它用顺手之后，它更像一个可配置、可约束、可脚本化的本地编码代理：能读写仓库、在沙箱里执行命令、调用 MCP 工具、用 AGENTS.md 沉淀规则，也能在 CI 或脚本里以 JSON 输出工作结果。

这篇不是入门教程。安装、登录、第一次提问这些内容只保留最低限度；重点放在日常高强度使用时真正影响效率和安全性的东西：审批与沙箱、配置作用域、AGENTS.md、profiles、headless 自动化、MCP 和排障。

一页速查

会话入口

# 交互式会话
codex

# 带初始提示直接开干
codex "把 src/utils.rs 里的报错修掉"

# 非交互执行一次任务，适合脚本或 CI
codex exec "为这个模块补单元测试"

# 恢复最近一次会话
codex resume --last

# 列出历史会话挑一个恢复
codex resume

# 全自动模式：失败才问 + 可写工作区
codex --full-auto "跑通 npm test"

# 指定模型与推理强度
codex -m gpt-5-codex -c model_reasoning_effort=high "review 这个 PR"

# 用某个 profile 启动
codex -p careful "重构这部分"

# 传入一张截图
codex -i error.png "这个报错怎么修"

# 登录 / 登出
codex login
codex logout

常用会话命令

命令	用途
`/init`	为仓库生成起始 `AGENTS.md`
`/model`	切换模型
`/approvals`	切换审批策略
`/status`	查看 token 消耗与成本
`/diff`	查看当前改动
`/review`	审查当前 diff 或 PR
`/compact`	压缩长会话，保留关键状态
`/undo`	回退上一步操作
`/new`	开启新会话
`/resume`	恢复历史会话
`/clear`	清空当前会话上下文
`/config`	编辑 `config.toml`
`/mcp`	查看 MCP 服务器状态
`/help`	查看命令列表
`/quit`	退出

常用 CLI 标志

参数	用途
`-m, --model`	指定模型
`-a, --ask-for-approval`	设置审批策略
`-s, --sandbox`	设置沙箱模式
`--full-auto`	等价于 `on-failure` 审批 + `workspace-write` 沙箱
`-p, --profile`	使用某个 profile
`-c, --config KEY=VALUE`	临时覆盖配置，可多次
`-i, --image`	传入图片
`--cd`	指定工作目录
`--no-project-doc`	本次不加载项目 `AGENTS.md`
`--output-last-message, -o`	把最终消息写入文件（`exec`）
`--json`	以 JSONL 输出事件流（`exec`）
`--output-schema`	要求最终输出符合 JSON Schema（`exec`）
`--dangerously-bypass-approvals-and-sandbox`	跳过所有审批与沙箱，极度危险
`--safe-mode`	禁用自定义配置启动，适合排障

配置作用域

Codex 的配置有作用域，用 TOML 写。不要把所有东西都塞进一个文件。

作用域	位置	适合放什么	是否应提交
User	`~/.codex/config.toml`	个人默认模型、审批沙箱基线、私有 MCP	否
User 指令	`~/.codex/AGENTS.md`	跨项目的个人编码习惯	否
Project	`<repo>/.codex/config.toml`	团队共享的模型、MCP、hooks	看内容
Project 指令	`<repo>/AGENTS.md`	团队约定、架构规则、命令清单	是
认证	`~/.codex/auth.json`	登录凭据，不要手写	否

加载顺序（从低到高优先级）：user config.toml → 项目级 .codex/config.toml（从 cwd 往上找，直到 git root）→ 命令行 -c 与标志。

注意：项目级配置有 denylist，不能覆盖安全敏感字段——openai_base_url、chatgpt_base_url、model_provider、model_providers、profile、profiles、notify、otel 等。这意味着仓库里的 .codex/config.toml 可以约定模型和 MCP，但不能偷偷改 API 地址或注入 profile。此外，如果目录未被信任（trust_level 不是 Trusted），项目级配置会被整体禁用。

建议：

团队约定放 AGENTS.md 和 .codex/config.toml（模型、MCP）。
个人习惯放 ~/.codex/AGENTS.md 和 ~/.codex/config.toml。
密钥、本机路径放环境变量或 ~/.codex/config.toml，不要进仓库。
不要手写 auth.json，用 codex login。

记忆系统：AGENTS.md

`AGENTS.md` 放规则，不放流水账

AGENTS.md 是 Codex 的长期记忆，作用类似 CLAUDE.md。它应该放稳定的规则，而不是会过期的流水账。

好的内容：

# 本项目约定

- 用 pnpm，不要用 npm 或 yarn。
- 所有提交走 conventional commits。
- 改动 src/ 后必须跑 pnpm lint 和 pnpm test。
- 数据库迁移在 migrations/，正序执行，不要手写 SQL 跳过。
- API 响应统一用 Result<T, E>，不要裸抛异常。

不好的内容：

# 今天的任务

- 正在修 #1234
- 昨天把 login 改了
- 待会要重构 cart

规则是“下次还会成立”的约束；流水账是“做完就过期”的状态。把后者放进对话，前者放进 AGENTS.md。

分层 AGENTS.md

Codex 会把多个 AGENTS.md 合并进上下文，顺序是从项目根到当前目录：

~/.codex/AGENTS.md          # 个人全局习惯
<repo>/AGENTS.md            # 项目级约定
<repo>/src/AGENTS.md        # 子目录规则
<repo>/src/api/AGENTS.md    # 更细的规则

合并规则：

先确定项目根——从 cwd 往上走，直到遇到 project_root_markers（默认 .git）。
收集从项目根到 cwd 路径上所有 AGENTS.md，按从上到下的顺序拼接。
不越过项目根，全局 ~/.codex/AGENTS.md 排在所有项目指令之前。
冲突时，更深的 AGENTS.md 优先级更高；但你当场的对话指令永远高于 AGENTS.md。

利用这点可以把规则放得贴近代码：src/api/AGENTS.md 写接口层的约定，src/db/AGENTS.md 写迁移与查询规则，互不干扰，且只在 Codex 工作到对应目录时才生效。

另外，AGENTS.override.md 会覆盖同名 AGENTS.md，适合放本机临时指令而不污染主文件。

写好 AGENTS.md 的几条原则

命令清单比自然语言有效：写“跑 pnpm test:unit”比写“记得跑单元测试”更不容易被误解。
说清“不要做什么”：负面约束（“不要直接改 generated/”）比正面引导更省 token。
指路而非抄录：与其把架构抄进 AGENTS.md，不如写“架构图见 docs/architecture.md，先读它”。
保持短：AGENTS.md 每次会话都进上下文，越长越贵越容易淹没重点。

审批与沙箱

这是 Codex 区别于多数终端代理的核心设计：审批和沙箱是两条独立的轴。审批决定“要不要问你”，沙箱决定“操作能改什么、能不能联网”。

双轴模型

	审批策略 (`approval_policy`)	沙箱模式 (`sandbox_mode`)
控制什么	哪些操作需要你确认	操作能访问的文件与网络
典型值	`untrusted` / `on-failure` / `on-request` / `never`	`read-only` / `workspace-write` / `danger-full-access`
默认	`untrusted`	`read-only`

默认组合（untrusted + read-only）是最保守的：每步都问，且不能改文件。这是故意的——在你不熟悉仓库时不会出事。

审批策略

策略	含义	适合
`untrusted`	每个命令、每次写都问	不熟的仓库、危险操作
`on-failure`	命令在沙箱里跑，失败时才问；写操作仍需批准	日常开发，配合 `workspace-write`
`on-request`	只有模型主动请求时才问	信任的、范围明确的任务
`never`	从不问，全自动	必须配合强沙箱或外部隔离

沙箱模式

模式	文件	网络	适合
`read-only`	只读	禁用	探索、问答、审查
`workspace-write`	只能写工作区	默认禁用	日常改代码
`danger-full-access`	任意位置	开放	容器/VM 内的全自动，本机慎用

workspace-write 默认不联网。如果任务需要装依赖、拉数据，要在配置里显式放开：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

放开网络意味着模型可以访问任何域名，请只在对任务必要时才开。

`--full-auto`：日常全自动的甜点档

1	`codex --full-auto "跑通测试并修掉失败"`

它等价于 --ask-for-approval on-failure --sandbox workspace-write：命令在可写工作区里跑，只在失败时打断你，写操作自动放行。这是“在本地放心让它干活”的常用组合，但仍然没有网络、不能写出工作区。要联网或全自由，得显式提升沙箱。

信任与项目级配置

项目级 .codex/config.toml 默认不被信任。第一次在一个仓库启用项目配置时，需要把信任级别设为 Trusted：

1
2
3

# <repo>/.codex/config.toml
[projects."/Users/you/myrepo"]
trust_level = "Trusted"

未信任目录里的项目配置会被整体忽略——这是防止克隆一个恶意仓库后，其中的 .codex/config.toml 自动放宽你的安全策略。

模型与推理强度

任务	模型	推理强度
快速问答、小改	`gpt-5-mini`	`low`
日常编码	`gpt-5-codex`	`medium`
难调试、架构改动	`gpt-5-codex`	`high`
大范围重构、迁移	`gpt-5`	`high`

推理强度（model_reasoning_effort）取值 minimal / low / medium / high。强度越高越慢越贵，但在难问题上更稳。临时切换不需要改配置：

1	`codex -m gpt-5-codex -c model_reasoning_effort=high "为什么这个并发测试会偶发死锁"`

经验：先用 medium 跑，卡住再升 high，比一开始就拉满更省。minimal 适合“格式化这段输出”这种几乎不需要想的杂活。

Profiles：按场景切换配置

同一个 config.toml 里可以定义多个 profile，每个 profile 覆盖若干字段，用 -p 切换：

model = "gpt-5-codex"
model_reasoning_effort = "medium"
approval_policy = "on-failure"
sandbox_mode = "workspace-write"

[profiles.review]
model = "gpt-5-codex"
model_reasoning_effort = "high"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.quick]
model = "gpt-5-mini"
model_reasoning_effort = "low"

1 2	`codex -p review "审查这次改动，找潜在的竞态" codex -p quick "把这个函数加个 docstring"`

profile 适合放“同一台机器、不同心意”的预设：审查时只读 + 高推理，杂活时小模型 + 低推理。注意项目级配置不能定义或切换 profile（在 denylist 里），profile 是个人/全局层面的。

上下文控制

让 Codex 先画地图

在陌生仓库里，第一句话不要让它改代码，让它先摸清结构：

1	`先不要改任何文件。读 README、package.json 和目录结构，告诉我这个项目的模块划分、入口在哪、测试怎么跑。列完我们再决定下一步。`

先有地图再施工，能避免它凭文件名猜架构、改错地方。

控制上下文膨胀

长会话会累积大量文件内容，拖慢又拖贵。几个杠杆：

/status        # 看 token 占用，心里有数
/compact       # 压缩历史，保留关键结论与未完成任务
/clear         # 换任务时清空，避免上一个任务污染
/new           # 直接开新会话，比 clear 更彻底

判断标准：当 /status 显示占用过半、且模型开始“忘记”早期约定时，就该 /compact 或 /new 了。新任务优先 /new 而不是在老会话里继续——上下文越干净，回答越准。

项目文档控制

有时你不想让项目 AGENTS.md 干扰本次判断（比如在别人的仓库里临时实验）：

1	`codex --no-project-doc "只看这个文件，回答我的问题"`

MCP

MCP 让 Codex 接外部工具：数据库、文档、浏览器、内部 API。在 config.toml 里声明。

配置 stdio MCP

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.docs]
command = "docs-server"
args = ["--stdio"]
cwd = "/path/to/server"
env = { STATIC = "yes" }
env_vars = ["DOCS_TOKEN"]   # 从环境继承，不把明文写进配置

配置 HTTP MCP

1 2	`[mcp_servers.weather] url = "https://mcp.example.com/weather"`

作用域与排障

MCP 配置同样分层：user config.toml 与项目 .codex/config.toml 都可以声明，子代理会继承上层 MCP。排障三步：

# 1. 在会话里看 MCP 是否连上、工具是否注册
/mcp

# 2. 用 safe-mode 排除自定义配置干扰
codex --safe-mode

# 3. 单独跑 MCP server，看它本身能不能起
npx -y @upstash/context7-mcp

常见坑：env 里写明文密钥进仓库、server 启动慢导致超时、HTTP MCP 需要鉴权头却没配。密钥一律走 env_vars 从环境继承。

Headless 与脚本化

codex exec 是自动化的核心：非交互、可结构化输出，适合 CI 和脚本。

普通执行

1	`codex exec "把 lint 报错全部修掉"`

退出码反映任务是否成功，适合在脚本里 && 串起来。

JSON 事件流

1	`codex exec --json "重构这个模块" > events.jsonl`

每行一个 JSON 事件（思考、工具调用、命令输出、最终消息），便于程序解析和审计。

结构化输出

要求最终结果符合 JSON Schema，并写到文件：

codex exec \
  --output-schema endpoints.schema.json \
  -o endpoints.json \
  "读取 src/ 下所有路由，提取成 {path, method, handler} 列表"

--output-schema 约束模型最终回答的形状，-o 把最终消息单独落盘。这把“让 AI 提取数据”变成了可信赖的管道环节。

CI 里的建议

# CI 里全自动 + 落最终消息
codex exec --full-auto -o pr-comment.md "根据 git diff 生成 PR 描述"

# 极度信任的隔离环境（容器/VM）才用 yolo
codex exec --dangerously-bypass-approvals-and-sandbox "部署脚本"

CI 里原则：能用沙箱就别 yolo。--full-auto 已经能跑通绝大多数改代码的任务；--dangerously-bypass-approvals-and-sandbox（别名 --yolo）只在容器等外部已隔离的环境用，且要限定可写范围。

Hooks

Hooks 让你在工具调用前后插入自定义逻辑：格式化、拦截危险命令、记日志。和 Claude Code 类似，Codex 的 hooks 在 config.toml 里配置。

关键安全机制：hook 信任。首次使用某个 hook 源需要建立信任，避免恶意仓库的 hook 被自动执行。在已经 vet 过 hook 来源的自动化里，可以显式跳过：

1	`codex exec --dangerously-bypass-hook-trust "..."`

典型用途是“写文件后自动跑 formatter”“拦截 rm -rf 之类命令”。本机可信的 hook 放 ~/.codex/config.toml，团队共享的放项目级但要注意信任门槛。

Skills

Skill 是一段“何时用、怎么用”的 markdown 指南，放在 ~/.codex/skills/<name>/SKILL.md 或项目 .codex/skills/。模型在判断出当前任务匹配某个 skill 时会读取并按其流程执行。

适合固化成 skill 的是有固定步骤的重复流程：发版检查清单、迁移审查、新接口接入、事故复盘。和 AGENTS.md 的区别：AGENTS.md 是“始终成立的规则”，skill 是“特定任务的操作手册”，按需加载、不常驻上下文。

写 skill 时把“前置条件 → 步骤 → 验收标准”写清楚，比堆自然语言描述更有效。

代码审查模式

本地 diff 审查

/review

让 Codex 审查当前未提交的改动。配合只读沙箱 + 高推理的 profile 效果最好：

1
2
3

codex -p review
# 进入后
/review

好的审查提示

审查当前 diff，重点看：
1. 有没有改了公共 API 但没改调用方
2. 错误处理是否被吞掉
3. 有没有引入新的并发问题
4. 测试是否覆盖了新增分支
不要夸代码，只列问题和风险等级。

“不要夸代码”很关键——默认模型爱说好话，明确要风险就能拿到有用反馈。

审查要分两轮

第一轮让它列问题，不要直接让它改；拿到清单后，人工挑出真问题，再逐条让它修。一轮“审查 + 修改”容易让它把真问题和误报一起“修”掉，引入新问题。

大仓库工作流

从启动位置控制范围

# 在子目录启动，上下文天然收窄
cd monorepo/services/auth && codex "只看这个服务"

# 用 --cd 临时指定
codex --cd monorepo/packages/ui "重构这个包"

配合分层 AGENTS.md，Codex 会优先用当前目录的规则，避免被整个 monorepo 的上下文淹没。

先让它列改动面

1	`先不要改文件。读相关代码，列出你打算改哪些文件、每个文件改什么、为什么。等我确认再动手。`

这等价于一个轻量的计划模式：先对齐改动面，避免它改出一堆意料之外的文件。

让探索和实现分离

1	`这是探索阶段：只读、只问、只列方案，不改文件。`

确认方案后，再开新会话或明确说“现在开始实现”。探索阶段塞进上下文的大量代码，在实现阶段往往是噪声。

提示词模板

架构探索

先不要改任何文件。
1. 读 README 和入口文件，画模块依赖关系。
2. 标出数据流：请求从哪进、经过哪些模块、写到哪。
3. 列三个最可能踩坑的地方。
输出一份简短笔记，然后停下等我。

小步实现

目标：{...}
约束：只改 {文件}，不动 {其他}。
步骤：
1. 先写测试（会失败）。
2. 实现到测试通过。
3. 跑全量测试。
每步完成后停下，告诉我结果，等我确认再下一步。

重构

重构 {模块}，目标：{...}。
要求：
- 行为不变，测试不能改、必须一直绿。
- 每次只做一个原子改动，跑一次测试。
- 不要顺手改无关代码。
先列出改动计划，确认后再执行。

迁移

把 {旧模式} 迁移到 {新模式}。
1. 先列出所有受影响的文件。
2. 按文件逐个迁移，每个文件迁完跑测试。
3. 最后删除旧模式的工具代码。
不要一次性全改。

常见故障排查

Codex 不遵守 `AGENTS.md`

确认文件名是 AGENTS.md（大写），在项目根或当前目录。
确认你在项目根之内（project_root_markers 默认 .git），否则不会向上找。
用 /status 或对话里问“你当前加载了哪些 AGENTS.md”确认它读到了。
冲突时更深的 AGENTS.md 赢，检查上层是否覆盖了你的规则。

项目级配置不生效

目录未信任：在 user config.toml 里把该项目的 trust_level 设为 Trusted。
字段在 denylist 里（profiles、model_provider 等）：项目级无权改，移到 user 配置。
用 --safe-mode 排除是不是配置互相覆盖。

MCP 不出现

/mcp 看状态，看 server 是否启动失败。
单独跑 server 命令，确认它能起来。
检查 command/args 路径、env_vars 是否在当前 shell 里有值。
HTTP MCP 检查鉴权与网络。

会话越来越笨

/status 看 token 占用，过半就该 /compact。
换任务用 /new，不要在老会话里继续。
探索阶段的大量代码读取，在实现阶段用 /new 清掉。

它想改太多文件

开口先让它列改动面，确认后再动手。
审批策略降到 untrusted 或 on-failure，每个写操作都过一遍。
在 AGENTS.md 里写明“不要改 generated/、不要动 lockfile”等负面约束。

它反复跑昂贵命令

沙箱设 read-only，逼它先读再想，而不是反复跑命令试错。
在提示里加“先用现有信息推理，必要时再跑命令”。
on-failure 审批下，失败的命令会停下来问你，正好截断循环。