OpenAI Codex CLI 2026 生产工作流实战：从终端 Agent 到团队级治理

引言：终端正在成为新的 IDE

2026 年，AI 编程工具的战场从 IDE 插件转移到了终端原生 Agent。OpenAI Codex CLI 在 2026 年 3 月重构后（基于 Rust 重写，开源在 openai/codex），已经不再是 2021 年那个简单的代码补全 API 包装，而是一个支持多代理并行、Git worktree 隔离、Skills Library 复用的终端编排引擎。

与 Cursor/Windsurf 这类 IDE 派不同，Codex CLI 的核心假设是：

优秀开发者 80% 的时间花在阅读、测试、调试和代码审查上，而不是在 IDE 里写代码。

因此 Codex CLI 把 Agent 能力拆成三条主线：

Plan 模式：先让 Agent 输出完整的执行计划，人类确认后再改代码；
Skills Library：把重复任务（如生成 API 文档、跑迁移脚本、写单测）封装成可复用 Skill；
Worktree 多代理：每个子任务在一个独立 Git worktree 中并行执行，最后合并。

本文从单兵作战讲到团队治理，给出 2026 年最务实的 Codex CLI 落地路径。

一、安装与基础配置

1.1 安装

bash

# 需要 Node.js >= 20 或直接使用官方预编译二进制
npm install -g @openai/codex

# 验证
codex --version
# codex-cli 1.2.3 (2026-06-28)

1.2 认证与模型选择

bash

# 方式一：环境变量（推荐 CI/服务器）
export OPENAI_API_KEY="sk-..."

# 方式二：本地密钥缓存
codex auth login

Codex CLI 2026 支持多模型路由：

模型	场景	成本
`gpt-5.2-codex`	复杂重构、架构设计	高
`gpt-5.1-codex`	日常功能开发	中
`gpt-4.1-codex`	单测、文档、小修复	低

配置默认模型：

bash

codex config set model gpt-5.1-codex
codex config set approval-mode suggest  # 每个动作都询问

1.3 项目级 .codex 配置

在仓库根目录创建 .codex/config.yaml：

yaml

# .codex/config.yaml
model: gpt-5.1-codex
approval_mode: suggest  # suggest | auto-edit | full-auto
max_iterations: 30
skills_dirs:
  - .codex/skills
context:
  include:
    - "README.md"
    - "docs/ARCHITECTURE.md"
    - "api/**/*.go"
  exclude:
    - "vendor/**"
    - "*.pb.go"
    - "node_modules/**"

二、AGENTS.md：把项目知识喂给 Agent

AGENTS.md 是 Codex CLI 2026 引入的项目级系统提示文件，相当于给 Agent 看的「项目 onboarding 手册」。把它放在仓库根目录，Codex 每次启动任务时自动读取。

2.1 一个生产级 AGENTS.md 模板

markdown

# AGENTS.md

## 项目概述
- 这是一个 Go + VitePress 技术博客，部署在 GitHub Pages。
- 构建命令：`vitepress build docs`
- 测试命令：`go test ./...`（scripts 目录）

## 代码规范
- Go 代码必须遵循 `gofmt` 和 `go vet`。
- Markdown 代码块必须成对出现。
- 变量命名使用驼峰，常量使用大写下划线。

## 禁止操作
- 不要删除 `.workbuddy/` 目录。
- 不要修改 `pnpm-lock.yaml`。
- 不要执行 `git push --force`。

## 测试要求
- 新增 Go 函数必须附带单元测试。
- 修改 config.mts 后必须执行 `pnpm build` 验证。

## 常用命令
- `pnpm dev`：本地预览博客（有已知错误但不影响构建）。
- `node scripts/indexnow-push.mjs`：推送 SEO。

2.2 AGENTS.md 与系统提示的关系

┌────────────────────────────────────────────┐
│           Codex CLI 上下文层级              │
├────────────────────────────────────────────┤
│ 1. 系统提示（System Prompt）                 │
│    由 OpenAI 定义，不可修改                  │
├────────────────────────────────────────────┤
│ 2. AGENTS.md（项目级）                       │
│    每个仓库独立，控制全局行为                 │
├────────────────────────────────────────────┤
│ 3. Skills（任务级）                          │
│    针对具体任务的模板和约束                   │
├────────────────────────────────────────────┤
│ 4. 用户单次指令（User Prompt）               │
│    当前任务的精确描述                         │
└────────────────────────────────────────────┘

三、Skills Library：把重复任务变成可复用资产

Skills 是 Codex CLI 2026 最重要的组织能力。一个 Skill 是一个 YAML 文件，定义了任务目标、输入、输出、检查清单和示例。

3.1 Skill 文件结构

yaml

# .codex/skills/write-golang-article.yaml
name: write-golang-article
description: 为技术博客撰写一篇符合规范的 Golang 文章
input:
  topic: string
  word_count: number
output:
  file_path: string
  frontmatter: object
steps:
  - 搜索 docs/dev/backend/golang 目录，确认无重复主题
  - 撰写 Markdown，包含 YAML frontmatter（title/date/tags/keywords/category/description）
  - 每篇文章 2000-4000 字，附带可运行代码示例
  - 检查所有 Markdown 代码块 fence（三个反引号）是否成对出现
  - 运行 vitepress build docs 验证
example: |
  用户：写一篇关于 Go 1.27 泛型方法的文章
  输出：docs/dev/backend/golang/go-1-27-generic-methods.md

3.2 调用 Skill

bash

# 显式调用 Skill
codex run write-golang-article --topic "Go 1.27 generic methods" --word_count 3000

# 或者在自然语言指令中引用
# "用 write-golang-article skill 帮我写一篇文章"

3.3 团队 Skill 共享

建议把 .codex/skills/ 提交到 Git，并在 CI 中做 Schema 校验：

yaml

# .github/workflows/codex-skills-lint.yaml
name: Codex Skills Lint
on: [push]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate Skill Schema
        run: |
          npm install -g @openai/codex
          codex skills validate .codex/skills/

四、Plan 模式与验证闭环

4.1 Plan 模式：先规划后动手

bash

codex plan "为订单服务新增优惠券计算模块，支持满减、百分比折扣和互斥规则"

Codex 会输出类似下面的计划：

markdown

## 执行计划

1. 在 `internal/order/` 下新建 `coupon/` 包
2. 定义 `Coupon` 接口和 `FixedAmount`、`Percentage`、`Exclusive` 三种实现
3. 编写 `Apply(order Order) (Order, error)` 方法
4. 在 `api/order.go` 中增加 `/order/{id}/apply-coupon` 接口
5. 编写单元测试（覆盖率 >= 80%）
6. 运行 `go test ./internal/order/...`

预计修改 5 个文件，新增约 200 行代码。

人类确认后执行：

bash

codex apply-plan --id plan-20260702-001

4.2 验证闭环：Agent 不能跳过测试

在 .codex/config.yaml 中强制配置：

yaml

hooks:
  pre_commit:
    - "go test ./..."
    - "go vet ./..."
  post_edit:
    - "go build ./..."

Codex 每次修改文件后都会自动运行这些钩子，失败时停止并请求人工介入。

五、多代理 Worktree 工作流

Codex CLI 2026 支持把大任务拆成多个子任务，每个子任务在独立的 Git worktree 中并行执行，最后合并到主分支。这对复杂重构特别有用。

5.1 架构

main-worktree/
├── .git/                 # 原始仓库
└── src/

worktrees/
├── agent-data-migration/  # Agent A：数据库迁移
├── agent-api-refactor/    # Agent B：API 重构
└── agent-test-update/     # Agent C：测试补全

5.2 命令示例

bash

# 启动多代理任务
codex multi-agent \
  --task "重构用户服务：拆分成 auth 和 profile 两个微服务" \
  --agents 3 \
  --strategy worktree

# Codex 会自动创建 3 个 worktree，分别负责：
# - agent-1: 拆分数据库表与迁移脚本
# - agent-2: 拆分 HTTP handler 和 proto 定义
# - agent-3: 更新单元测试和集成测试

# 合并结果
codex merge --all

5.3 风险隔离

每个 worktree 都是独立的 Git 工作树，Agent 的错误不会污染主工作区。合并前必须：

bash

codex review --worktree agent-api-refactor

review 模式会让 Codex 以「代码审查者」身份逐文件检查：

是否有破坏向后兼容的变更；
测试是否覆盖新增分支；
是否有敏感信息硬编码。

六、团队治理：成本、安全与权限

6.1 成本控制

Codex CLI 按 token 计费，团队必须设置预算告警：

bash

codex config set budget.daily_usd 50
codex config set budget.alert_threshold 0.8

建议开启「模型降级」策略：

yaml

# .codex/config.yaml
routing:
  default_model: gpt-5.1-codex
  fallback:
    - model: gpt-4.1-codex
      when: "task_lines_of_code < 50"

6.2 安全红线

风险	防护措施
Agent 执行危险命令	approval-mode 至少为 `suggest`
代码泄露给模型	配置 `context.exclude` 过滤敏感文件
密钥硬编码	提交前强制 `gitleaks` 扫描
生成代码许可证污染	禁止直接复制训练数据，要求原创实现

在 CI 中加入密钥扫描：

yaml

- name: Secret Scan
  run: |
    docker run --rm -v "$PWD:/path" zricethezav/gitleaks:latest detect --source /path --verbose

6.3 权限模型

建议把仓库成员分成三级：

L1 开发者：只能在自己的 feature worktree 使用 Codex，合并需人工 review；
L2 维护者：可以运行 codex apply-plan，但禁止 full-auto 模式；
L3 架构师：可以配置全局 .codex/config.yaml 和 Skills。

七、与 Cursor/Windsurf 的选型建议

维度	Codex CLI	Cursor	Windsurf
入口	终端	IDE	IDE
上下文	AGENTS.md + Skills	.cursorrules + Composer	Memories
多代理	Worktree 原生	较弱	Cascade
适合场景	后台服务、脚本、DevOps	全栈开发、UI 实现	快速原型
团队治理	强（YAML 配置 + CI）	中	弱

如果你是后端/DevOps/工具链开发者，Codex CLI 的终端原生和 CI 集成能力会更顺手；如果你是前端/全栈开发者，Cursor 的 IDE 体验仍然更完整。

八、总结

OpenAI Codex CLI 2026 已经把 AI 编程从「辅助写代码」推进到「可治理的 Agent 工作流」。对于技术团队：

个人：用 AGENTS.md 减少重复沟通成本，用 Plan 模式避免 Agent 乱改代码；
团队：用 Skills Library 沉淀最佳实践，用 Worktree 多代理处理复杂重构；
组织：用 .codex/config.yaml + CI 钩子守住安全、成本和代码质量红线。

建议先用 Codex CLI 接手一个低风险任务（如单测补全、文档生成、Lint 修复），跑通完整闭环后再扩大使用范围。

OpenAI Codex CLI 2026 生产工作流实战：从终端 Agent 到团队级治理 ​

引言：终端正在成为新的 IDE ​

一、安装与基础配置 ​

1.1 安装 ​

1.2 认证与模型选择 ​

1.3 项目级 .codex 配置 ​

二、AGENTS.md：把项目知识喂给 Agent ​

2.1 一个生产级 AGENTS.md 模板 ​

2.2 AGENTS.md 与系统提示的关系 ​

三、Skills Library：把重复任务变成可复用资产 ​

3.1 Skill 文件结构 ​

3.2 调用 Skill ​

3.3 团队 Skill 共享 ​

四、Plan 模式与验证闭环 ​

4.1 Plan 模式：先规划后动手 ​

4.2 验证闭环：Agent 不能跳过测试 ​

五、多代理 Worktree 工作流 ​

5.1 架构 ​

5.2 命令示例 ​

5.3 风险隔离 ​

六、团队治理：成本、安全与权限 ​

6.1 成本控制 ​

6.2 安全红线 ​

6.3 权限模型 ​

七、与 Cursor/Windsurf 的选型建议 ​

八、总结 ​

参考资料 ​

OpenAI Codex CLI 2026 生产工作流实战：从终端 Agent 到团队级治理

引言：终端正在成为新的 IDE

一、安装与基础配置

1.1 安装

1.2 认证与模型选择

1.3 项目级 .codex 配置

二、AGENTS.md：把项目知识喂给 Agent

2.1 一个生产级 AGENTS.md 模板

2.2 AGENTS.md 与系统提示的关系

三、Skills Library：把重复任务变成可复用资产

3.1 Skill 文件结构

3.2 调用 Skill

3.3 团队 Skill 共享

四、Plan 模式与验证闭环

4.1 Plan 模式：先规划后动手

4.2 验证闭环：Agent 不能跳过测试

五、多代理 Worktree 工作流

5.1 架构

5.2 命令示例

5.3 风险隔离

六、团队治理：成本、安全与权限

6.1 成本控制

6.2 安全红线

6.3 权限模型

七、与 Cursor/Windsurf 的选型建议

八、总结

参考资料