实战 A1：Codex 项目初始化与配置——从零搭建高效 AI 开发环境

2026年6月6日 20:10 CST Codex实战教程配置AGENTS.md工作流

实战教程系列 系列 A：A1 Codex 配置实战 ← 本文 | A2 日常开发 | A3 审查与质量 | A4 自动化 CI/CD | A5 大型项目

# Codex 项目配置实战 ## 案例1：全栈项目从零配置 - 目录结构设计 - config.toml 逐行解析 - AGENTS.md 编写框架 ## 案例2：Monorepo 分层配置 - 根级 .codex/ 全局设定 - 子包级覆盖策略 - AGENTS.md 嵌套规则 ## 案例3：团队共享配置 - 团队级 AGENTS.md 模板 - Skills 共享与复用 - 常见陷阱与解决方案

Codex 的默认配置可以让你立刻开始写代码，但要发挥它的全部潜力——尤其是在团队协作和大型项目中——需要花时间打磨配置。本文通过三个递进式案例，从个人项目到团队 Monorepo，展示如何搭建一个高效、可维护的 Codex 环境。

案例 1：从零配置 TypeScript 全栈项目

背景：你在开发一个 Next.js + Prisma + PostgreSQL 的全栈应用，项目结构如下：

myapp/
  src/
    app/          # Next.js App Router
    components/   # React 组件
    lib/          # 工具函数和 API 客户端
    server/       # 服务端逻辑
  prisma/         # 数据库 schema
  tests/          # 测试文件
  .codex/         # Codex 配置目录
    config.toml

第一步：config.toml

# .codex/config.toml

# 模型选择：日常开发用主力模型
model = "gpt-5.5"

# 推理深度：日常任务 high，复杂重构可临时调 xhigh
model_reasoning_effort = "high"

# 审查模型：用最好的模型做审查
review_model = "gpt-5.5"

# 审批策略：workspace 内自动，外部需确认
default_sandbox_mode = "workspace-write"
approval_policy = "on-request"

# 启用关键特性
[features]
goals = true          # 长任务目标追踪
multi_agent = true    # 子 Agent 协作
fast_mode = true      # 快速迭代模式

# 项目级 Shell 环境
[shell_environment_policy]
include_only = ["PATH", "HOME", "NODE_ENV", "DATABASE_URL"]

# TUI 定制
[tui]
vim_mode_default = true

[tui.keymap.composer]
submit = ["enter"]

为什么这样配：

model_reasoning_effort = "high" 是日常开发的甜点——够深但不至于过慢
review_model 独立配置确保审查质量不受主会话模型影响
include_only 限制环境变量传递，避免敏感信息泄露
vim_mode_default 对 Vim 用户的细节关怀

第二步：AGENTS.md

# MyApp Development Guidelines

## Build & Run
```bash
bun install          # 安装依赖
bun run dev          # 启动开发服务器 (localhost:3000)
bun run build        # 生产构建
bun run lint         # ESLint + Prettier
bun run typecheck    # TypeScript 类型检查
bun run test         # Vitest 单元测试
bun run test:e2e     # Playwright E2E 测试

Project Structure

src/app/ — Next.js App Router 页面和 API 路由
src/components/ — 可复用 React 组件，按功能分组
src/lib/ — 工具函数，每个文件只导出一个职责
src/server/ — 服务端逻辑，不引用客户端代码
prisma/ — 数据库 schema，修改后必须生成 migration

Code Conventions

使用 TypeScript strict mode
所有新函数必须有 JSDoc 注释
API 路由使用 zod 做输入验证
数据库查询使用 Prisma 的 typed queries
组件使用 named export，禁止 default export
异步操作统一使用 async/await，不用 raw promise

Testing Requirements

新增工具函数：必须写单元测试
新增 API 路由：必须写集成测试
新增页面组件：必须写 E2E 冒烟测试
修改 Prisma schema：必须生成 migration + 回滚方案

Review Checklist

TypeScript 类型检查通过
所有测试通过（单元 + 集成 + E2E）
新增代码有对应的测试
API 变更更新了 OpenAPI 文档
数据库变更包含 migration 和回滚


**为什么这样写**：
- 把构建/测试命令写在前头——Codex 执行任务时需要知道怎么验证
- 目录结构说明让 Codex 知道每个模块的职责边界
- 代码约定是可检查的——"禁止 default export"比"保持代码风格一致"更有用
- Review Checklist 直接对应 `/review` 的检查维度

### 第三步：验证配置

启动 Codex 后运行：

/status # 确认模型、权限、features 生效 /debug-config # 确认 config.toml 层级正确


然后做一个简单测试：

在 src/lib/ 下创建一个 formatDate 函数，接收 ISO 字符串，返回中文格式日期。写单元测试。


Codex 应该：
1. 在 `src/lib/` 下创建 `formatDate.ts`（named export）
2. 在 `tests/` 下创建对应的测试文件
3. 运行 `bun run typecheck` 和 `bun run test` 验证

---

## 案例 2：Monorepo 分层配置

**背景**：你的团队维护一个 Turborepo，包含 4 个包：

monorepo/ .codex/ config.toml # 根级全局配置 AGENTS.md # 全局项目引导 packages/ web/ # Next.js 前端 .codex/ config.toml # Web 专属配置 api/ # Go 后端 .codex/ config.toml # API 专属配置 AGENTS.md # API 专属引导 shared/ # 共享类型和工具 db/ # 数据库 migration


### 根级 `.codex/config.toml`

```toml
# 全局默认——所有子包继承
model = "gpt-5.5"
model_reasoning_effort = "high"
default_sandbox_mode = "workspace-write"

# Monorepo 关键：项目根标记
project_root_markers = [".git", "turbo.json"]

[features]
multi_agent = true

Web 子包 `.codex/config.toml`（覆盖）

# Web 包使用轻量模型做日常迭代
model = "gpt-5.4-mini"

# Web 包有自己的环境变量
[shell_environment_policy]
include_only = ["PATH", "HOME", "NEXT_PUBLIC_API_URL"]

API 子包 `AGENTS.md`

# API Service Guidelines
## Build & Run
```bash
go build ./...       # 编译
go test ./...        # 测试
golangci-lint run    # Lint

Conventions

所有 handler 必须有 OpenAPI 注解
数据库访问通过 sqlc 生成的类型安全查询
错误处理使用 fmt.Errorf 包装，保留调用栈
中间件按 auth → validation → handler 顺序


### AGENTS.md 嵌套规则

从 API 目录启动 Codex 时，加载顺序：
1. `monorepo/.codex/AGENTS.md`（全局规则）
2. `monorepo/packages/api/.codex/AGENTS.md`（API 专属规则，**覆盖冲突项**）

这意味着全局 AGENTS.md 写公共约定（Git 规范、通用测试标准），子包 AGENTS.md 写领域专属（Go 风格、API 设计规范）。

---

## 案例 3：团队共享配置——Skills 与 AGENTS.md 模板

**背景**：一个 8 人团队，维护 3 个微服务。需要统一的 Codex 行为标准。

### 团队级 AGENTS.md 模板

```markdown
# Team Engineering Standards
## Git Workflow
- 分支命名：feature/<ticket-id>-<short-desc>
- Commit 格式：type(scope): description
- PR 标题包含 Jira ticket ID
## Code Review 标准
- 所有 PR 必须至少 1 人 approve
- CI 全部通过后才能合并
- 安全相关变更必须 2 人 approve
## Shared Tooling
- 使用 Bun 作为包管理器
- 使用 Biome 替代 ESLint + Prettier
- 使用 Lefthook 管理 Git hooks

团队 Skills

创建一个共享的数据库迁移 skill：

.codex/skills/db-migration/SKILL.md：

---
description: Create and run database migrations safely.
---

## Steps
1. Check for existing migrations in prisma/migrations/
2. Run `bun run db:status` to see pending migrations
3. Generate migration: `bun run db:migrate -- --name <description>`
4. Generate rollback: `bun run db:migrate -- --create-only --name rollback_<description>`
5. Run tests: `bun run test`
6. If tests pass, mark migration as ready

团队任何成员在 Codex 中输入 $db-migration 即可使用标准流程。

常见陷阱

陷阱 1：config.toml 中写了 model_provider 但忘记设 model

# 错误——model 是空字符串
model_provider = "amazon-bedrock"
model = ""

# 正确
model_provider = "amazon-bedrock"
model = "us.anthropic.claude-sonnet-4-6-20250514-v1:0"

陷阱 2：AGENTS.md 写得太长

Codex 每次会话都加载 AGENTS.md 到上下文。如果文件超过 500 行，Token 消耗会显著影响长任务的效率。解决：把详细流程放到 Skills 中——Skill 的 body 只在触发时加载。

陷阱 3：Monorepo 中忘记设 project_root_markers

Codex 默认用 .git 作为项目根标记。如果你的 Monorepo 根目录没有 .git（比如用 Git submodules），需要显式设置 project_root_markers = ["turbo.json", "pnpm-workspace.yaml"]。

总结

项目类型	config.toml 策略	AGENTS.md 策略
个人项目	单文件，配 model + review_model + features	精简，重点写构建/测试命令
团队项目	项目级 config，启用 goals + multi_agent	团队标准 + 项目约定
Monorepo	根级默认 + 子包覆盖	全局通用 + 子包专属，利用嵌套覆盖
多服务	每服务独立 .codex/	每服务独立 AGENTS.md，共享 Skills

下一章：A2: Codex 日常开发工作流——从 TDD 到重构的完整链路

实操清单

创建项目级 .codex/config.toml，至少配置 model、review_model、model_reasoning_effort
编写 AGENTS.md，包含构建命令、目录结构、代码约定、测试要求、审查清单
运行 /status 和 /debug-config 验证配置生效
做一个简单测试：让 Codex 创建函数 + 写测试 + 运行验证
Monorepo 项目：为每个子包创建独立的 .codex/config.toml 和 AGENTS.md
团队项目：创建共享 Skills 目录，编写至少一个可复用 Skill
检查 AGENTS.md 长度是否超过 500 行——过长的内容拆分到 Skills 中
确认 .gitignore 中包含 .codex/logs/ 和 .codex/cache/