Codex 进阶使用技巧
完成基础安装和第一次对话之后，Codex 真正的价值在于将其嵌入日常开发工作流。
本文覆盖五个进阶方向：项目配置、会话管理、编辑器集成、CI/CD 自动化和提示词技巧，帮助你让 Codex 理解你的项目、记住你的约定、在流水线里自动干活。
一、用 AGENTS.md 给 Codex 写"入职文档"
AGENTS.md 是写给 Codex 的项目说明书，放在项目根目录，每次启动时自动加载，整个会话期间持续生效。
为什么需要它
Codex 默认对你的项目一无所知。
它不知道你用的是 App Router 还是 Pages Router，不知道数据库操作要统一走哪个文件，也不知道哪些文件是碰不得的。
如果每次对话都要重新交代背景，效率会非常低，而且容易出错。
AGENTS.md 让这些信息一次写入、持续生效，省去重复交代的麻烦。
写什么内容
一份有效的 AGENTS.md 通常包含四类信息：项目概述、技术栈、重要约定和禁止事项。
以下是一个完整的示例：
# AGENTS.md
## 项目概述
这是一个基于 Next.js 14 + Prisma + PostgreSQL 的 SaaS 应用。
使用 App Router，不使用 Pages Router。
## 技术栈
- 前端：Next.js 14, React 18, TailwindCSS, shadcn/ui
- 后端：Next.js API Routes, Prisma ORM
- 数据库：PostgreSQL 15
- 认证：NextAuth.js
## 重要约定
- 所有数据库操作必须通过 lib/db.ts 中的 prisma 实例
- API 路由错误统一用 lib/api-error.ts 处理
- 环境变量在 .env.local 中，参考 .env.example
## 禁止事项
- 不要修改 prisma/schema.prisma，除非我明确要求
- 不要删除任何现有测试
- 生产环境的 .env 文件不要碰「禁止事项」这一节尤其重要。Codex 在执行任务时会主动推断哪些文件需要修改，没有明确边界的情况下，它可能动到你不希望它碰的地方。把红线写清楚，比出问题后再补救要省事得多。
配置的层级结构
AGENTS.md 支持三层嵌套，优先级从低到高排列。
越靠近当前目录的文件优先级越高。同一目录下，AGENTS.override.md 存在时，同级的 AGENTS.md 会被跳过。
| 层级 | 路径 | 作用范围 | 优先级 |
|---|---|---|---|
| 全局层 | ~/.codex/AGENTS.md | 跨项目通用约定 | 低 |
| 项目层 | repo/AGENTS.md | 仓库级规范 | 中 |
| 覆写层 | repo/services/payments/AGENTS.override.md | 子目录特殊规则 | 高 |
全局层适合写那些在所有项目里都成立的约定，例如：
# ~/.codex/AGENTS.md
## 全局约定
- 安装依赖时优先使用 pnpm
- 修改 JavaScript 文件后始终运行 npm test
- 新增生产依赖前先请求确认配置完成后，可以用以下命令验证加载是否正确：
codex --ask-for-approval never "Summarize the current instructions."二、会话管理：跨天延续大型任务
会话管理功能允许你把当前对话状态导出到文件，下次直接恢复，不需要重新铺垫背景。
问题背景
Codex 的上下文窗口是有限的。
处理一个跨越多个文件、需要分阶段推进的大型任务时，如果中途关掉终端或者切换到别的事情，再回来时上下文就断了——Codex 不记得之前讨论过什么、做过哪些决策。
导出会话可以解决这个问题，让你在任意时间点恢复到之前的对话状态。
基本用法
以下是与会话管理相关的常用命令：
实例
# 在对话中途随时导出当前会话
/export session-2024-01-15.json
# 下次继续时恢复
/load session-2024-01-15.json
# 直接恢复最近一次会话（最常用）
codex resume --last
# 查看所有已保存的会话
ls ~/.codex/sessions/什么时候该导出
不需要每次对话都导出。以下几种情况值得保存：
| 场景 | 说明 |
|---|---|
| 跨天进行的多阶段任务 | 任务分多天进行，且中间有明确的阶段划分，保存后下次可以直接从上次断点继续 |
| 重要的架构决策 | 和 Codex 讨论出了一个重要的架构决策，后续任务需要基于这个决策继续推进 |
| 复杂的调试过程 | 调试复杂 bug，已经排除了若干方向，不想下次从头再来 |
三、与 VS Code 集成
Codex 官方提供 VS Code 扩展，安装后可以在编辑器内直接发起对话，不用切换到终端。
安装与登录
安装步骤如下：
第一步，打开扩展市场（Cmd/Ctrl + Shift + X）。
第二步，搜索「Codex」或「OpenAI Codex」，安装官方插件。
第三步，首次使用需要登录 ChatGPT 账号。
第四步，侧边栏出现 Codex 图标后即可使用。
安装完成后，可以使用以下快捷键快速操作：
| 快捷键 | 功能 |
|---|---|
| Alt + G | 将选中代码发送到 Codex，带上当前文件上下文 |
| Cmd + Shift + P | 打开命令面板，输入 "Codex" 查看全部可用命令 |
BYO 模式（未订阅 ChatGPT 的用户）
如果你已经在 CLI 里配置了自己的 API Key（Anthropic、OpenAI 或其他兼容提供商），可以用免费 ChatGPT 账号登录 VS Code 插件。
插件会自动复用 CLI 的模型配置，不强制使用 ChatGPT Plus。
| 适用场景 | 说明 |
|---|---|
| 已有 API Key 但不想额外订阅 ChatGPT | 直接使用自己的 API Key，无需额外付费订阅 |
| 希望 VS Code 和 CLI 使用一致的模型 | 插件自动复用 CLI 配置，两端体验完全一致 |
四、CI/CD 集成
Codex CLI 支持以无头模式运行，不需要人工交互，适合接入自动化流程。
Codex 在流水线里能做什么
以下是无头模式下 Codex 在 CI/CD 中的常见用途：
| 用途 | 说明 | 典型触发时机 |
|---|---|---|
| 自动更新 CHANGELOG | 每次合并主分支后自动根据提交记录更新 CHANGELOG.md | 合并到 main 分支后 |
| 生成 API 文档 | 根据代码变更自动生成或同步 API 文档 | 代码推送后 |
| 自动代码审查 | 在 PR 流水线里自动跑代码审查并留下注释 | PR 创建或更新时 |
GitHub Actions 示例
以下工作流在每次推送到 main 分支时，自动让 Codex 根据最新提交更新 CHANGELOG.md：
实例
# 文件路径：.github/workflows/codex-changelog.yml
name: Auto Update Changelog
on:
push:
branches: [main]
jobs:
update-changelog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install Codex CLI
run: npm install -g @openai/codex
- name: Run Codex Task
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
CODEX_QUIET_MODE: 1
run: |
codex exec --full-auto "根据最新 commits 更新 CHANGELOG.md"
- name: Commit changes
run: |
git config --local user.email 'action@github.com'
git add CHANGELOG.md
git commit -m 'chore: update changelog [skip ci]'
git push配置中有两个关键点需要特别注意：
| 配置项 | 作用 | 说明 |
|---|---|---|
| CODEX_QUIET_MODE: 1 | 抑制交互式输出 | 避免流水线因等待交互输入而卡住 |
| --full-auto | 无头模式运行 | 让 Codex 在无人值守的情况下直接执行，不等待确认 |
在 CI 里使用时，建议在项目根目录的 AGENTS.md 里明确限定 Codex 在自动模式下允许修改的文件范围，防止因提示词理解偏差导致意外改动。
五、提示词技巧
Codex 的输出质量很大程度上取决于你怎么提问。
以下五条技巧针对新用户最常遇到的问题，每条都配有具体示例。
技巧一：给出足够的上下文
Codex 没有读心术。「修复 bug」这种指令会让它瞎猜，结果往往不是你想要的。
以下是对比示例：
| 不推荐写法 | 推荐写法 |
|---|---|
| 「修复 bug」 | 「用户登录时报错 TypeError: Cannot read properties of null，报错发生在 src/auth/login.ts 第 42 行，这个函数负责验证 JWT token，帮我找出并修复这个问题」 |
有效上下文包含三个要素：
| 要素 | 说明 | 示例 |
|---|---|---|
| 具体现象 | 报错信息或具体表现 | TypeError: Cannot read properties of null |
| 涉及位置 | 文件和行号 | src/auth/login.ts 第 42 行 |
| 代码职责 | 这段代码原本的功能 | 验证 JWT token |
技巧二：复杂任务分两步走
对改动范围较大的任务，先让 Codex 分析和列出方案，确认没问题再执行。
一步到位看起来更快，但遇到方向偏差时代价更大。
实例
# 第一步：只分析，不修改
codex "分析 src/api/ 目录的代码质量，列出主要问题，不要修改任何文件"
# 第二步：确认方案后再执行
codex "好，按你说的方案，先处理错误处理问题，其他的我来 review 后再说"技巧三：用 ask 模式先摸清代码库
ask 模式是只读模式，适合在动手之前先理解现有代码的结构和逻辑。
搞清楚再改，比改完再回头理解要省时间。
实例
# ask 模式不会触发任何文件修改
codex -a ask "这个项目是如何处理用户认证的？梳理完整的认证流程"理解清楚后，退出当前会话，重新以可编辑模式启动：
# 可编辑模式（需要确认）
codex -a auto
# 全自动执行（谨慎使用）
codex -a full-auto推荐工作流：
ask
↓
理解代码结构
↓
确定修改方案
↓
重新启动 Codex
↓
进入可编辑模式
↓
执行修改注意：CLI 中已不再支持使用
/approvals在运行过程中切换权限模式，需要在启动时通过-a参数指定。桌面客户端仍支持会话内切换。
技巧四：用否定指令划定边界
告诉 Codex 不要碰什么，和告诉它要做什么同等重要。
尤其是涉及多个相关文件的重构任务，边界不清容易产生不必要的连带修改。
实例
# 明确划定不要修改的范围
codex "重构 utils/date.ts 中的日期格式化函数，不要修改函数签名，不要改变测试文件"技巧五：先要计划，再开始执行
对于没有把握的任务，先让 Codex 列出它打算怎么做。
这一步几乎不花时间，但能让你在早期发现方向偏差，避免在错误路径上走太远。
# 先要计划
codex "你打算怎么实现这个功能？先列出步骤，不要执行"
# 确认计划合理后再推进
codex "计划没问题，开始执行第一步"小结
这五个方向覆盖了从「项目配置」到「日常操作」再到「自动化」的完整路径。
刚开始不需要全部用上，建议按顺序来：先写好 AGENTS.md 让 Codex 理解你的项目，再逐步把它融入 VS Code 工作流和 CI/CD 流程。
提示词技巧在日常使用中慢慢积累，比一次性记住更有效。
AI 思考中...