Codex CLI 完全指南：第二章·配置体系深度解析

Codex CLI 的行为由两个核心配置文件控制：codex.yaml（项目配置）和 AGENTS.md（AI 行为指南）。理解并善用这两个文件，是从"能用"到"好用"的关键分水岭。

codex.yaml 配置文件

codex.yaml 是 Codex 的主配置文件，放在项目根目录。可以通过 codex init 生成模板，也可以从零手写。Codex 启动时会按以下优先级加载配置：

命令行参数（最高优先级）

项目级 codex.yaml

用户级 ~/.config/codex/codex.yaml

环境变量

内置默认值

基础结构

# codex.yaml
version: "1.0"

model:
  provider: openai
  model: gpt-4o
  temperature: 0.2
  max_tokens: 16000

execution:
  policy: ask
  sandbox: none

context:
  max_lines: 20000
  max_files: 100
  ignore_patterns:
    - "node_modules/"
    - "dist/"
    - "*.log"
    - ".git/"

hooks:
  pre_exec:
    - echo "即将执行命令：{{.command}}"
  post_exec:
    - echo "命令已执行完毕"

模型配置

model 节点控制 Codex 使用哪个模型以及推理参数：

model:
  provider: openai        # openai | anthropic | google | openrouter | ollama
  model: gpt-4o           # 模型标识符
  temperature: 0.2        # 0.0 ~ 2.0，越低越确定，越高越创造
  max_tokens: 16000       # 单次响应的最大 token 数
  top_p: 0.95             # 核采样参数
  frequency_penalty: 0    # -2.0 ~ 2.0，减少重复
  presence_penalty: 0     # -2.0 ~ 2.0，鼓励新话题

不同 provider 支持的 model 值：

| Provider | 推荐模型 | 特点 |
|----------|---------|------|
| openai | gpt-4o, gpt-4-turbo, o3-mini | 综合能力强 |
| anthropic | claude-sonnet-4-20250514, claude-3-5-sonnet-20241022 | 代码生成强，长上下文 |
| google | gemini-2.5-pro-preview, gemini-2.5-flash | 免费额度大 |
| openrouter | 任何支持的模型 | 一站式接入 |
| ollama | codellama:34b, deepseek-coder:33b | 完全本地，隐私安全 |

多模型回退配置：

model:
  primary:
    provider: openai
    model: gpt-4o
  fallback:
    provider: anthropic
    model: claude-sonnet-4-20250514

当主模型不可用时，Codex 自动切换到备用模型。

执行策略

execution.policy 控制 AI 执行命令时的权限级别：

execution:
  policy: ask       # always | ask | never
  sandbox: none     # none | docker | podman

always：AI 可以不经确认直接执行所有命令（高风险，仅限完全信任的沙箱环境）
ask：每次执行前弹出确认提示（默认推荐）
never：AI 仅能展示命令，不能执行

沙箱模式详解见第五章。

上下文窗口

context:
  max_lines: 20000      # 发送给模型的最大代码行数
  max_files: 100        # 发送给模型的最大文件数
  include_summary: true # 在超限时附加摘要
  truncation_strategy: smart  # smart | head | tail

truncation_strategy 的三种策略：

smart：优先保留最近修改的文件和关键路径代码
head：保留文件开头（适合了解项目结构）
tail：保留文件尾部（适合当前编写位置）

忽略规则

context:
  ignore_patterns:
    - "node_modules/"
    - "vendor/"
    - "dist/"
    - "build/"
    - "*.min.js"
    - "*.bundle.js"
    - ".next/"
    - "coverage/"
    - "__pycache__/"
    - "*.pyc"
    - "target/"
    - "bin/"
    - "obj/"
    - ".terraform/"
    - "*.lock"
    - "package-lock.json"
    - "yarn.lock"

这些文件不会被扫描和发送给模型，减少 token 消耗、加快响应速度。

AGENTS.md —— AI 行为指南

AGENTS.md 放在项目根目录，是给 AI 看的"入职手册"。它用自然语言定义 AI 在这个项目中应该遵循的规范、风格和约定。格式使用 Markdown。

为什么需要 AGENTS.md

默认情况下，Codex 会根据通用的编程知识给出建议。但每个团队、每个项目都有自己的"潜规则"——命名偏好、架构约定、测试框架选择、代码风格等。AGENTS.md 就是把这些显式化。

完整范例

以下是一个 Node.js + TypeScript 项目的 AGENTS.md 范例：

# AI 编程指导

## 项目概况
- 这是一个基于 Express + TypeScript 的后端 API 服务
- 使用 Prisma 作为 ORM，PostgreSQL 为数据库
- 测试框架为 Vitest，使用 Supertest 做集成测试
- 日志库为 Pino

## 技术栈
- Node.js 20+，TypeScript 5.4
- pnpm 作为包管理器
- 数据库迁移通过 Prisma Migrate 管理

## 代码风格
- 使用 async/await，禁止使用 .then()
- 每个函数必须有明确的返回类型声明
- 接口以 I 开头，类型以 T 开头
- 禁止 any 类型，特殊情况用 unknown
- 文件名使用 kebab-case
- 导出的函数必须有 JSDoc 注释

## 项目结构

src/
├── routes/ # HTTP 路由，仅负责请求/响应处理
├── services/ # 业务逻辑层
├── repositories/# 数据访问层
├── middleware/ # Express 中间件
├── utils/ # 纯工具函数
├── types/ # 类型定义
└── config/ # 配置常量

## 测试规范
- 每个 service 必须有对应的 .test.ts 文件
- 使用 describe/it 结构
- 测试覆盖率目标 80%+
- 集成测试文件以 .integration.test.ts 结尾

## 禁止事项
- 不要修改 .env 文件
- 不要提交包含 API Key 的代码
- 不要直接修改编译后的 dist/ 目录
- 不要使用 console.log——用 logger.info

AGENTS.md 的高级用法

条件指令：针对特定操作给出指导

## 当生成 SQL 查询时
- 优先使用 Prisma 查询构建器，避免原生 SQL
- 所有查询必须限制返回条数（take 参数）
- 避免 N+1 查询——使用 include 做关联查询

## 当编写测试时
- 使用 beforeEach 做统一的 mock 配置
- 数据库相关的测试使用测试专用数据库
- 测试完成后必须清理数据（afterEach / afterAll）

## 当处理错误时
- 使用自定义 AppError 类，包含 statusCode 和 message
- 不要在 catch 块中吞掉错误
- 统一用 errorHandler 中间件处理

Git 工作流指令：

## Git 提交规范
- 提交信息使用 Conventional Commits 格式
- 分支命名：feature/xxx, fix/xxx, chore/xxx
- 提交前确保测试全部通过

AGENTS.md 的作用范围

AGENTS.md 也可以放在子目录中，对子目录生效：

project/
├── AGENTS.md           # 全局生效
├── frontend/
│   └── AGENTS.md       # 仅对 frontend/ 生效，覆盖全局
├── backend/
│   └── AGENTS.md       # 仅对 backend/ 生效，覆盖全局

子目录的 AGENTS.md 会完全覆盖父级——不是合并。

用户级全局配置

~/.config/codex/codex.yaml 在所有项目中生效：

# 用户级配置
model:
  temperature: 0.3      # 我个人偏好更确定性的输出
  max_tokens: 32000     # 如果 API 支持，使用更大的上下文

execution:
  policy: ask           # 所有项目默认执行前询问

context:
  ignore_patterns:
    - "**/*.lock"
    - "**/.DS_Store"

项目级配置会覆盖用户级配置的同名字段。

环境变量

Codex 支持以下环境变量作为配置补充：

| 变量名 | 作用 | 示例 |
|--------|------|------|
| OPENAI_API_KEY | OpenAI API 密钥 | sk-... |
| ANTHROPIC_API_KEY | Anthropic API 密钥 | sk-ant-... |
| GOOGLE_API_KEY | Google AI 密钥 | AIza... |
| OPENROUTER_API_KEY | OpenRouter 密钥 | sk-or-... |
| CODEX_MODEL | 覆盖模型选择 | gpt-4o |
| CODEX_TEMPERATURE | 覆盖温度参数 | 0.5 |
| CODEX_MAX_TOKENS | 覆盖最大 token | 32000 |
| CODEX_EXEC_POLICY | 覆盖执行策略 | ask |
| HTTP_PROXY / HTTPS_PROXY | 代理设置 | http://127.0.0.1:10809 |

实际案例：为 React 项目配置 Codex

# codex.yaml
model:
  provider: openai
  model: gpt-4o
  temperature: 0.1
  max_tokens: 16000

execution:
  policy: ask

context:
  max_lines: 15000
  ignore_patterns:
    - "node_modules/"
    - "dist/"
    - ".next/"
    - "coverage/"
    - "*.css.map"

# AGENTS.md
## 项目信息
- React 18 + TypeScript + Vite
- 状态管理使用 Zustand
- 路由使用 React Router v6
- 样式方案为 Tailwind CSS + shadcn/ui 组件库

## 编码规范
- 组件使用函数式声明，禁止 class 组件
- Props 类型在组件文件内定义，命名：组件名Props
- 自定义 Hook 以 use 开头
- 每个组件放在独立目录，包含 index.tsx 和 styles.ts
- 使用 React.memo 包裹纯展示组件

配置校验

保存配置后，运行以下命令检查语法：

codex validate

会报告错误的具体位置和原因。

小结

codex.yaml 和 AGENTS.md 是 Codex CLI 的精髓所在。前者控制"如何运行"，后者定义"如何思考"。一个好的配置能让 AI 从"能写代码"进化到"能写出符合团队规范的代码"。下一章将深入模型提供商的选择与配置策略。

Codex CLI 完全指南：第二章·配置体系深度解析

codex.yaml 配置文件

基础结构

模型配置

执行策略

上下文窗口

忽略规则

AGENTS.md —— AI 行为指南

为什么需要 AGENTS.md

完整范例

AGENTS.md 的高级用法

AGENTS.md 的作用范围

用户级全局配置

环境变量

实际案例：为 React 项目配置 Codex

配置校验

小结

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客