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 "这个项目是如何处理用户认证的？梳理完整的认证流程"

# 理解清楚后，切换到可编辑模式
/approvals

技巧四：用否定指令划定边界

告诉 Codex 不要碰什么，和告诉它要做什么同等重要。

尤其是涉及多个相关文件的重构任务，边界不清容易产生不必要的连带修改。

实例

# 明确划定不要修改的范围
codex "重构 utils/date.ts 中的日期格式化函数，不要修改函数签名，不要改变测试文件"

技巧五：先要计划，再开始执行

对于没有把握的任务，先让 Codex 列出它打算怎么做。

这一步几乎不花时间，但能让你在早期发现方向偏差，避免在错误路径上走太远。

# 先要计划
codex "你打算怎么实现这个功能？先列出步骤，不要执行"

# 确认计划合理后再推进
codex "计划没问题，开始执行第一步"

小结

这五个方向覆盖了从「项目配置」到「日常操作」再到「自动化」的完整路径。

刚开始不需要全部用上，建议按顺序来：先写好 AGENTS.md 让 Codex 理解你的项目，再逐步把它融入 VS Code 工作流和 CI/CD 流程。

提示词技巧在日常使用中慢慢积累，比一次性记住更有效。

返回顶部

菜鸟教程