Codex 进阶使用技巧

AGENTS.md - 项目级配置

在项目根目录创建 AGENTS.md 文件，可以为 Codex 提供项目特定的上下文和规则，Codex 启动时会自动读取：

# 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 CLI 支持会话的导出和恢复：

# 在交互界面中随时导出当前会话
/export session-2024-01-15.json

# 第二天继续工作时，恢复会话上下文
/load session-2024-01-15.json

# 或在启动时直接恢复上次会话
codex resume --last

# 查看所有保存的会话
ls ~/.codex/sessions/

与 VS Code 集成

Codex 官方提供了 VS Code 扩展插件，可以在 IDE 中直接使用 Codex 的功能：

1. 打开 VS Code，进入扩展市场（Cmd/Ctrl + Shift + X）
2. 搜索「Codex」或「OpenAI Codex」，安装官方插件
3. 首次使用需要登录 ChatGPT 账号
4. 在侧边栏中找到 Codex 图标，即可开始对话

VS Code 插件快捷键：
Alt + G          → 将选中的代码发送到 Codex CLI
Cmd + Shift + P  → 打开命令面板，输入 Codex 查看所有命令

💡 未订阅 ChatGPT 的用户：可以先按前面步骤配置好 CLI 的 API Key，再用免费账号登录 VS Code 插件，这样插件会复用 CLI 的模型配置（BYO 模式）。

CI/CD 集成（GitHub Actions）

Codex CLI 可以在 CI/CD 流水线中以无头模式运行：

# .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 的关键，以下是一些经过验证的技巧：

技巧一：提供足够的上下文

# 模糊的提示
"修复 bug"

# 详细的提示
"用户登录时报错 TypeError: Cannot read properties of null，
报错发生在 src/auth/login.ts 第 42 行，
这个函数负责验证 JWT token，帮我找出并修复这个问题"

技巧二：分步骤执行复杂任务

# 第一步：先让 Codex 分析，不要它直接改
"分析 src/api/ 目录的代码质量，列出主要问题，不要修改任何文件"

# 第二步：确认方案后再执行
"好，按你说的方案，先修复错误处理问题，然后我来 review"

技巧三：利用 ask 模式探索

# 用 ask 模式（只读）先了解代码库
codex -a ask "这个项目是如何处理用户认证的？梳理完整的认证流程"

# 了解清楚后，再切换到 auto-edit 进行修改
/approvals  # 切换到 auto-edit 模式

技巧四：善用否定指令

# 明确告诉 Codex 不要做什么，避免不必要的修改
"重构 utils/date.ts 中的日期格式化函数，不要修改函数签名，不要改变测试文件"

技巧五：让 Codex 先汇报再执行

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

# 确认后再开始
"计划不错，开始执行第一步"