Codex CLI 使用技巧

本文按 2026-08-29 的官方文档与本机 codex-cli 0.150.1 更新。Codex CLI 更新很快；遇到版本差异时，以 codex --help、codex <子命令> --help 和官方参考为准。

Codex CLI 不只是“在终端里聊天的 AI”。它能理解仓库、修改文件、执行本地工具、审查改动，并通过 MCP、技能、插件与 codex exec 接入日常开发和自动化流程。

这篇不重复基础安装和登录，重点讲如何把它用得可控、可复用，并且跟得上当前 CLI 的变化。

一页速查

常用入口

# 在当前仓库开启交互式会话
codex

# 带初始任务启动
codex "修复 src/utils.rs 中的编译错误，并运行相关测试"

# 在指定目录工作
codex -C packages/web "梳理这个包的入口、构建和测试方式"

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

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

# 传入图片上下文；可重复传多个 -i
codex -i error.png "分析这个报错并给出修复方案"

# 为本轮提供实时网页搜索
codex --search "查官方文档，升级这个依赖的用法"

# 单独启动一次代码审查
codex review

# 检查安装、登录、配置与运行环境
codex doctor

交互会话中最值得记住的命令

命令	用途
`/init`	为当前项目创建起始 `AGENTS.md`
`/status`	查看当前会话配置与状态
`/permissions`	查看或调整本轮权限边界
`/model`	切换模型和推理强度
`/review`	选择范围，启动只读代码审查
`/mcp`	查看当前连接的 MCP 服务
`?`	显示当前版本可用的快捷键与命令

不要把旧教程里的每个斜杠命令都当成稳定接口。CLI 会随版本增加、迁移或下线命令；不确定时，直接按 ? 或运行 codex --help。

当前常用标志

参数	用途
`-m, --model`	覆盖本轮模型
`-c, --config KEY=VALUE`	临时覆盖 TOML 配置，支持点路径
`-C, --cd DIR`	指定工作目录
`--add-dir DIR`	额外授予一个目录写入权限，可重复使用
`-i, --image FILE`	给初始提示附加一张或多张图片
`-s, --sandbox`	选择 `read-only`、`workspace-write` 或 `danger-full-access`
`-a, --ask-for-approval`	选择 `untrusted`、`on-request` 或 `never`
`--approve-for-me`	经自动审查后，以可写工作区沙箱处理审批请求
`--search`	为本轮启用实时网页搜索
`-p, --profile NAME`	叠加 `~/.codex/NAME.config.toml` 配置文件
`--oss` / `--local-provider`	使用本地开源模型提供方（LM Studio 或 Ollama）
`--strict-config`	配置中出现当前版本不认识的字段时直接报错
`--dangerously-bypass-approvals-and-sandbox`	跳过审批与沙箱；只应在外部已隔离的环境使用

codex exec 额外支持 --json、--output-schema、-o/--output-last-message、--ephemeral、--ignore-user-config 等参数；自动化前先看一次 codex exec --help，不要沿用交互模式的猜测。

推荐心智模型：六个彼此独立的层

高效使用 Codex 的关键，不是把提示词写得越来越长，而是把信息放在正确的层里：

任务层：当前目标、验收标准、允许改动的范围，写在本轮提示中。
项目规则层：稳定的团队约定和命令，写进 AGENTS.md。
配置层：模型、沙箱、审批、搜索、MCP 等默认值，放进 config.toml。
权限层：审批策略决定何时打断你；沙箱决定命令实际能访问什么。两者不是一回事。
扩展层：技能、插件与 MCP 提供可按需调用的领域流程和外部工具。
自动化层：codex exec、JSONL 事件、JSON Schema、云端任务和 CI 将可重复流程固化下来。

例如，“改完 TypeScript 后跑哪些命令”属于项目规则；“这次只改一个文件”属于任务；“允许写工作区但不碰其他目录”属于权限；“把路由提取成 JSON”才是自动化输出契约。

从安装到首个任务

macOS 和 Linux 的当前官方安装方式是独立安装脚本：

1	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`

安装后进入 Git 仓库，运行 codex，按提示选择 ChatGPT 登录或其他可用登录方式。更新 CLI 可重复执行同一安装命令，也可先查看 codex update --help。首次使用陌生项目时，不要立刻要求它改代码：

先不要改文件。阅读 README、项目配置和目录结构，告诉我：
1. 入口在哪里；
2. 模块如何划分；
3. 测试与检查命令是什么；
4. 实现这个需求最小会影响哪些文件。
列完后停止，等我确认。

先画地图，再实施。它能显著减少“猜错架构、顺手改多处”的问题。

配置：位置、优先级与 profile

当前 Codex 使用 TOML 配置。常见位置如下：

位置	用途
`~/.codex/config.toml`	个人默认模型、权限和本机 MCP
`<repo>/.codex/config.toml`	可信项目的共享配置
`<repo>/<subdir>/.codex/config.toml`	子目录的更具体配置
`~/.codex/<name>.config.toml`	用 `-p <name>` 叠加的个人 profile
`~/.codex/AGENTS.md`	全局工作习惯
`<repo>/AGENTS.md`	项目规则与团队约定

优先级从高到低是：命令行标志与 -c 覆盖 → 从项目根到当前目录的可信 .codex/config.toml → -p 选择的 profile 文件 → 用户配置 → 系统配置 → 内置默认值。

这里有两个容易踩的坑：

profile 不再推荐写成单个配置文件里的 [profiles.xxx] 表。 当前 -p review 会叠加 ~/.codex/review.config.toml。
项目配置只会在信任项目后加载。 不受信任的项目会跳过项目级 .codex/ 配置、hooks 与规则；不要为图方便而盲目信任刚克隆的仓库。

可作为起点的个人配置

# ~/.codex/config.toml
model = "gpt-5.6"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

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

审查场景单独建一个 profile：

# ~/.codex/review.config.toml
model_reasoning_effort = "high"
approval_policy = "never"
sandbox_mode = "read-only"
review_model = "gpt-5.6"

1	`codex -p review`

这里的 never + read-only 意味着审查不会因命令审批反复中断，同时沙箱仍禁止写文件；它不是“全权限”。模型、可用推理档位和账号权限会变化，日常可在 /model 中选择可用项，或用 codex -m <model> 临时覆盖。

临时覆盖比复制配置更适合试验

codex \
  -c 'model_reasoning_effort="high"' \
  -c 'web_search="live"' \
  "解释这个依赖升级的兼容性风险"

-c 的值按 TOML 解析，因此字符串要带引号。准备升级 CLI 或清理历史配置时，用 --strict-config 及早发现失效字段：

1	`codex --strict-config "只检查当前配置是否能正常加载"`

AGENTS.md：持久规则，不是工作日志

Codex 会在开始工作前读取指令文件。它先读取全局 ~/.codex/AGENTS.override.md，若不存在则读取 ~/.codex/AGENTS.md；随后从项目根一路走到当前目录。每个目录最多取一个文件，优先级为：

1	`AGENTS.override.md > AGENTS.md > project_doc_fallback_filenames 中的备用名称`

文件按“根目录 → 当前目录”拼接，因此越靠近当前目录的规则覆盖越早出现的规则。合并后的默认上限为 32 KiB；指令不要写成百科全书。

适合放入 AGENTS.md 的内容是长期稳定、可执行、可验证的约定：

# 项目约定

- 使用 pnpm；不要使用 npm 或 yarn。
- 改动 `src/` 后依次运行 `pnpm lint` 与 `pnpm test`。
- 不要直接编辑 `generated/`；修改生成源后运行 `pnpm codegen`。
- 新增 API 时更新 `docs/api/`，并为失败路径补测试。

不适合放进去的是“今天修哪个 issue”“上次改了什么”这类会过期的工作日志。临时规则放进本轮对话；局部服务的规则放到对应子目录；需要短期替换某一目录规则时才用同目录的 AGENTS.override.md。

/init 可以生成起点，但生成后仍要人工删掉泛泛而谈的内容，补上真实命令、边界和验收标准。

审批、沙箱与网络：先分清谁管什么

审批策略控制“执行命令前是否需要人确认”；沙箱控制“即便执行了，命令能访问什么”。建议把它们当成两道独立的门。

维度	可选值	作用
审批	`untrusted`、`on-request`、`never`	控制 Codex 何时暂停请求确认
沙箱	`read-only`、`workspace-write`、`danger-full-access`	控制命令的文件与环境访问范围
搜索	`cached`、`indexed`、`live`、`disabled`	控制网页搜索的来源与新鲜度

实用组合

场景	建议
阅读、方案讨论、代码审查	`-s read-only -a never`
普通本地改动	`-s workspace-write -a on-request`
需要当前资料	在前一组合上加 `--search`
外部已隔离的自动化环境	视隔离强度决定是否使用 `--dangerously-bypass-approvals-and-sandbox`

workspace-write 不是“整台机器可写”：它只允许主工作区和显式 --add-dir 添加的目录。danger-full-access 则会放弃这条隔离边界。后者只适合容器、虚拟机等外部已经充分隔离的环境，不能把它当作日常提速选项。

# 只读分析
codex -s read-only -a never "审查当前未提交改动，只报告问题"

# 给 monorepo 的另一个目录额外写入权限
codex -C services/api --add-dir packages/shared \
  "实现 API 和 shared 类型的同步修改"

网页搜索默认是缓存模式；--search 切到实时搜索。实时网页内容可能包含提示注入，因此即便搜索结果看起来可信，也应把其中的命令、下载链接和配置当作外部输入来审视。

图片、网页、会话与云端任务

当前 CLI 的上下文入口比“纯文本对话”更完整：

# 图片：报错截图、设计稿、架构图都可作为初始上下文
codex -i ui-reference.png -i browser-error.png \
  "对比设计稿与现状，定位页面布局问题"

# 恢复或分叉历史工作
codex resume --last
codex fork --last

# 查看并使用云端任务（实验性）
codex cloud list
codex cloud exec "在云端分析这个任务并给出改动"
codex cloud status <task-id>
codex cloud diff <task-id>
codex cloud apply <task-id>

codex cloud 仍标为实验性。把它理解为“在终端提交、查看并应用云端任务结果”，而不是默认替代本地会话。应用云端 diff 前照常检查差异和测试结果。

MCP、技能与插件：三种扩展不要混为一谈

能力	解决的问题	典型形态
MCP	连接工具与外部上下文	文档服务、数据库、浏览器、设计工具
技能	固化一个任务的操作手册	发布检查、迁移审核、事故复盘
插件	打包并分发技能、MCP 与可选界面	团队工具或第三方集成

用 CLI 管理 MCP

# 添加本地 stdio MCP
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 查看、读取或移除配置
codex mcp list
codex mcp get context7
codex mcp remove context7

# 对 OAuth MCP 登录
codex mcp login <server-name>

也可以直接编辑 config.toml：

[mcp_servers.docs]
command = "docs-server"
args = ["--stdio"]
cwd = "/path/to/server"
env_vars = ["DOCS_TOKEN"]

[mcp_servers.remote_docs]
url = "https://mcp.example.com/mcp"

stdio MCP 可设置 command、args、cwd、env 和 env_vars；HTTP MCP 支持 Bearer Token 与 OAuth。机密信息优先通过环境变量传递，不要把 token 写进准备提交的项目配置。交互会话中的 /mcp 可查看实际连接状态。

技能要写成“何时使用、需要什么前置条件、按什么步骤、如何验收”的短操作手册；AGENTS.md 则只放始终成立的规则。插件管理使用 codex plugin --help，安装、来源与权限应先核对再启用。

用 `codex exec` 让自动化有契约

codex exec 是非交互模式，适合脚本、CI 和可重复任务。最有价值的不是让它“自动干活”，而是让输入、输出和审计方式可预测。

普通执行与最终输出文件

1 2	`codex exec -o pr-description.md \ "读取当前 git diff，生成简洁的 PR 描述和测试说明"`

-o 只写入代理的最后一条消息，适合后续作为 PR 评论、变更说明或报告输入。

JSONL 事件流

1	`codex exec --json "检查当前模块的测试缺口" > events.jsonl`

--json 会把事件输出为 JSONL，方便脚本记录工具调用和最终结果。它适合审计与程序处理；普通人工阅读仍优先保留简洁的最终消息文件。

结构化最终答案

codex exec \
  --output-schema endpoints.schema.json \
  -o endpoints.json \
  "读取 src/ 下的路由，输出 path、method、handler 三个字段"

--output-schema 约束最终回答的 JSON 形状。它不能替代人工校验，也不会自动保证提取内容正确；但能让下游脚本不必依赖自然语言格式。

自动化安全边界

# 临时任务，不保留本地会话记录
codex exec --ephemeral -s read-only -a never \
  "检查许可证文件是否符合仓库规则"

# 排查用户配置干扰时，不加载个人 config.toml
codex exec --ignore-user-config "输出本项目的构建命令"

不要因为在 CI 就默认启用 --yolo。CI 权限往往比开发机更广，尤其存在部署密钥时。先缩小工作目录、使用只读或工作区写入沙箱、限制 token 与环境变量暴露范围，再考虑是否需要更高权限。

代码审查：先报告，再决定是否修改

Codex 当前支持交互式 /review 和非交互 codex review。它们的共同原则是：审查过程只报告按优先级排列的问题，不修改工作区。

# 进入只读审查会话
codex -p review
# 在会话中输入 /review，选择未提交改动、提交或基线分支

# 或使用非交互入口
codex review --help

高质量审查提示应限定范围与标准：

审查当前 diff，只报告可操作的问题。
重点检查：
1. 公共 API 改动是否同步更新调用方；
2. 错误是否被吞掉；
3. 新增分支是否有测试；
4. 并发、资源释放和安全边界是否退化。
每个问题说明位置、影响和复现条件；不需要泛泛表扬。

先让它给出发现，再要求修复真正成立的问题。这样能把“审查判断”和“实现改动”分开，也更容易逐项验证。

日常工作流：用范围和验收条件约束代理

小改动

目标：修复 {问题}。
范围：只允许修改 {文件或目录}；不要改 lockfile 和 generated/。
验收：补一条覆盖该问题的测试，运行 {命令}。
先说明你准备修改的文件和原因；确认后再开始。

重构

重构 {模块}，行为必须保持不变。
先列出受影响文件、每个文件的改动目的和验证命令，等待确认。
实施时每次只做一个可回退的原子改动，并运行相关测试。
不要顺手格式化或修改无关代码。

陌生仓库或大型仓库

1 2	`# 从更小的目录启动，天然限制关注范围 codex -C services/auth "只分析这个服务的依赖、入口和测试"`

配合嵌套 AGENTS.md，局部规则会在该目录优先出现。对跨目录改动，明确写出允许的目录，必要时用 --add-dir 显式授权，不要依赖“它应该知道”。

常见排障

命令或参数和教程对不上

codex --version
codex --help
codex exec --help
codex doctor

先看本机版本的帮助。CLI 迭代快，网络文章、旧截图和历史配置都可能滞后。

配置突然不生效

运行 codex --strict-config，先排除字段已失效或拼写错误。
确认项目是否已信任；不受信任时项目 .codex/ 配置、hooks 和规则会被跳过。
复查优先级：命令行 -c、更深目录的项目配置、profile 都可能覆盖用户配置。
用 codex exec --ignore-user-config 对比，判断是否是个人配置造成干扰。

`AGENTS.md` 没被遵守

文件要位于 Codex home、项目根或从项目根到当前目录的路径上。
同一目录中 AGENTS.override.md 会替代 AGENTS.md。
指令有默认总大小上限；保持短小、可执行，必要时拆到子目录。
在会话开头要求它“列出已加载的指令来源和关键规则”，先验证上下文再开始改动。

MCP 不可用

1
2
3

codex mcp list
codex mcp get <server-name>
codex mcp --help

确认服务的命令、路径、环境变量和 OAuth 登录状态；随后在交互会话中用 /mcp 查看该会话是否实际连上。不要把密钥打印到终端日志，也不要以为“写进配置文件”就代表服务能够启动。

它读取了错误范围或想改太多文件

从目标子目录用 -C 启动。
提示中写明“先列改动面，确认后再写”。
用 read-only 完成探索和设计，再切换到 workspace-write 实现。
把“不要改 generated/、不要改 lockfile”写为明确的负面约束。