Codex智能体使用教程

OpenAI 开源的终端优先编码智能体（Terminal-First Coding Agent），用 Rust 构建，能读代码库、编辑多文件、执行 Shell 命令，全程在沙箱里跑。它不是一个代码补全工具，而是能在终端里独立完成项目搭建、重构、测试、修 bug 的自治智能体。

一、是什么 & 不是什么

核心定位： 你不是在"补全代码"，而是在"给一个工程师下达任务"。

二、安装

2.1 方法一：独立安装脚本（推荐，macOS / Linux）

curl -fsSL https://chatgpt.com/codex/install.sh | sh

静默安装（脚本中不交互）：

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

2.2 Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

2.3 npm（跨平台）

npm install -g @openai/codex

前提：Node.js 18+

2.4 Homebrew（macOS）

brew install --cask codex

2.5 验证安装

codex --version

三、首次运行 & 认证

codex

首次启动会弹出认证选择：

四、三种运行模式

Codex CLI 的核心是沙箱 + 审批策略组合。三种预设模式：

命令行切换

# 以 auto-edit 模式启动
codex --approval-mode auto-edit

# 全自动 exec 模式（非交互，适合 CI）
codex exec "Run npm test and fix all failing test cases"

会话内切换

在 Codex 会话中使用 /permissions 命令即可实时调整。

五、必备斜杠命令

在 Codex 会话中输入 / 唤出命令面板：

六、核心工作流

Codex 遵循一个固定的工作流程：

阅读代码库 → 制定计划 → 提议修改 → 人工确认 → 执行修改 → 验证结果
   Read   →   Plan   →  Propose  →  Confirm  →  Apply   →  Verify

实战第一步：认识项目

cd your-project
codex

在会话中发送第一条提示：

总结一下这个仓库的结构和开发流程。先不要做任何修改。

Codex 会扫描目录结构、读取关键文件，然后返回一份项目概览。这帮你验证它是否正确理解了你的项目。

渐进式信任

建议按以下节奏逐步"放权"：

第 1 步：探索任务（Suggest 模式）
    "找出项目中所有没有单元测试的公共函数"

第 2 步：单文件编辑（Suggest 模式）
    "给 fetcher.py 添加超时重试逻辑"

第 3 步：修 bug + 测试（Suggest / Auto-Edit）
    "修这个 bug，并写一个复现它的测试用例"

第 4 步：多文件重构（Auto-Edit）
    "把 data/ 目录下所有 CSV 解析逻辑统一成一个 DataLoader 类"

第 5 步：全自动 CI 任务（Full-Auto / exec）
    codex exec "跑一遍 test suite，修掉所有失败的用例"

七、配置：AGENTS.md / codex.md

在项目根目录创建 AGENTS.md（或 codex.md），Codex 每次启动会自动加载。

# AGENTS.md

## 技术栈
- Python 3.12，所有新代码使用 type hints
- 数据处理用 pandas 2.x + numpy
- 绘图用 plotly（不用 matplotlib）
- 测试用 pytest，覆盖率要求 80%+

## 编码规范
- 遵循 PEP 8，4 空格缩进
- 函数不超过 40 行
- 类不超过 200 行
- 公开 API 必须有 docstring

## 项目约定
- 数据文件放在 data/ 目录
- 图表输出到 charts/ 目录
- 配置文件统一用 YAML，放 config/
- 运行前必须激活 conda 环境

## 禁止事项
- 不要引入新的第三方依赖，除非先讨论
- 不要修改 data/ 下的原始数据文件
- 不要在代码里硬编码 API key

全局配置

全局配置在 ~/.codex/config.toml（或 config.yaml），可以设置默认模型、沙箱策略等。

# ~/.codex/config.toml
model = "gpt-5-codex"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

项目级 AGENTS.md 的优先级高于全局配置。

八、技能系统 (Skills)

Skills 是放在 ~/.codex/skills/ 下的可复用指令文件 (SKILL.md)，用 $skill-name 调用。

自定义 Skill 示例

创建 ~/.codex/skills/code-review/SKILL.md：

# Code Review Skill

当用户说 $"review" 时执行以下步骤：

1. 用 git diff 获取所有变更
2. 检查每个文件的：
   - 逻辑正确性（边界条件、空值处理）
   - 性能问题（不必要的循环、重复 I/O）
   - 安全问题（SQL 注入、XSS、密钥泄露）
3. 输出分级报告：
   - 🔴 必须修复
   - 🟡 建议改进
   - 🟢 风格建议

在 Codex 会话中使用：

$review

内置 Skill 示例

# 运行测试驱动开发循环
$tdd "实现一个 LRU 缓存"

# 生成变更日志
$changelog

# 生成 commit message
$commit

九、插件系统 (Plugins)

通过 /plugins 浏览和安装。常见插件：

十、自动化 & CI/CD

exec 模式（非交互式）

# 单次任务
codex exec "用 pytest 跑所有测试，修复失败的用例并解释原因"

# 管道输入
cat error.log | codex -- "分析这些错误日志，给出修复方案"

# 指定模型 + 全自动
codex exec --model gpt-5-codex --approval-mode full-auto -- \
  "重构 src/auth.py：拆分成 auth_service.py + token_utils.py，保持所有测试通过"

恢复会话

# 恢复上次会话
codex resume --last

# 列出历史会话
codex sessions list

# 恢复指定会话
codex resume --id <session-id>

GitHub Actions 集成示例

name: Codex Auto-Fix
on:
  issues:
    types: [opened]

jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Codex fix
        run: |
          codex exec --approval-mode full-auto -- \
            "根据 issue #${{ github.event.issue.number }} 的描述修复代码"
      - name: Create PR
        uses: peter-evans/create-pull-request@v6

十一、实战演示

场景：用 Codex CLI 给 Python 项目加一个 API 端点

cd bond_monitor
codex

在会话中输入：

我需要给这个债券监控项目加一个 REST API：

1. 用 FastAPI 新建 api.py，提供以下端点：
   - GET /bonds —— 返回所有债券数据
   - GET /bonds/{code} —— 返回单个债券详情
   - POST /bonds/refresh —— 触发数据刷新

2. 数据来源是现有的 data/ 目录下的 CSV 文件

3. 添加 requirements.txt 列出 FastAPI 和 uvicorn

4. 给每个端点写 pytest 测试（test_api.py）

Codex 的执行过程：

📖 阅读 bond_monitor/ 项目结构...
📖 分析 data/ 目录数据格式...
📖 理解现有代码结构...

📋 计划：
1. 新建 api.py —— FastAPI 应用 + 3 个端点
2. 新建 test_api.py —— 5 个测试用例
3. 更新 requirements.txt —— 追加 fastapi, uvicorn

✏️ 创建 api.py
    [+] 添加 /bonds GET 端点
    [+] 添加 /bonds/{code} GET 端点
    [+] 添加 /bonds/refresh POST 端点

✏️ 创建 test_api.py
    [+] test_get_all_bonds
    [+] test_get_bond_by_code
    [+] test_get_bond_not_found
    [+] test_refresh_bonds
    [+] test_refresh_bonds_error

✏️ 更新 requirements.txt
    [+] fastapi>=0.110.0
    [+] uvicorn>=0.29.0

🔍 验证：运行 pytest test_api.py
   5 passed ✅

场景：重构现有代码

把 fetcher.py 里的 HTTP 请求逻辑拆成一个独立的 HttpClient 类。
要求：
- 支持超时、重试、自定义 User-Agent
- 不影响现有调用方
- 写单元测试
- 完成后用 /review 检查一遍

场景：数据处理 & 可视化

分析 data/ 目录下所有 CSV 的债券收益率数据：
1. 计算每只债券的 7 日/30 日收益率变化
2. 找出收益率波动最大的 Top 10
3. 用 plotly 生成一张交互式散点图
4. 图表保存到 charts/ 目录

十二、Codex CLI vs Claude Code

选择建议

• 选 Codex CLI：你已有 ChatGPT 套餐、需要开源可审计、CI/CD 自动化、频繁模型切换
• 选 Claude Code：你需要超长上下文（分析大型代码库）、偏好 Claude 的代码风格、已有 Claude 订阅

十三、最佳实践

1. 始终用 Git

# 每次使用 Codex 前
git checkout -b codex/feature-name
git add -A && git commit -m "checkpoint before codex"

# 用完检查 diff
git diff

2. 给任务定义"完成标准"

❌ "重构 auth 模块"
✅ "重构 auth 模块：拆成 3 个文件，保持所有 12 个测试通过，新增 3 个边界测试"

3. AGENTS.md 的粒度控制

# ❌ 太啰嗦 —— 占用过多 context
- 第 1 条...（300 条规则）

# ✅ 精炼 + 外链
- 遵循《Python 编码规范》（详见 docs/style-guide.md）
- 核心原则：type hints、pytest、不引入新依赖

4. 适时清空上下文

会话过长会导致上下文膨胀、响应变慢。用 /new 开新线程，用 /clear 重置。

5. 使用 /review 做独立审查

# 完成修改后
/review

# 或者直接：
codex exec "审查当前分支的所有改动，给出安全性和性能评估"

6. 管道 + exec 的组合拳

# 用 git log 喂给 Codex 写 changelog
git log --oneline HEAD~10 | codex -- "根据这些 commit 写一份 changelog，分组为 Feature / Fix / Refactor"

# 用 lint 结果喂给 Codex 修复
flake8 src/ | codex exec "修复这所有 lint 错误"

7. 分步执行，逐步验证

❌ 一个 prompt 干所有事
   "重建整个前端，改用 React + TypeScript + Tailwind"

✅ 分步推进
   1. "分析当前前端架构，总结组件树"
   2. "把 Button 组件改成 TypeScript"
   3. "跑测试，看有没有破坏性变更"
   4. 重复步骤 2-3，逐个迁移

十四、常见问题

Q1：Codex CLI 收费吗？

CLI 工具本身开源免费。消耗的是你 ChatGPT 套餐里的额度（或 API 调用费）。

Q2：能在公司项目中使用吗？

可以。Business / Enterprise 版 ChatGPT 提供数据隐私保障。注意沙箱权限设置，敏感项目建议用 Suggest 模式。

Q3：代码质量怎么样？

代码质量和 prompt 质量成正比。描述越具体、约束越清晰，输出越好。用 /review 做二次验证。

Q4：和 Cursor / Copilot 怎么选？

• Copilot：日常编码时的行级补全
• Cursor：IDE 内更深入的 AI 交互
• Codex CLI：终端里的项目级自动化任务
  三者互补，不冲突。

Q5：如何更新？

# 独立安装脚本
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm
npm update -g @openai/codex

# Homebrew
brew upgrade codex

Q6：Windows 支持如何？

有独立的 PowerShell 安装脚本。WSL2 下体验更好，可以直接用 Linux 安装方式。

Q7：如何接入其他模型（Anthropic / Gemini）？

通过 AI Gateway 中转，Codex CLI 支持配置自定义 API endpoint。详见 Multi-Model Gateway Setup。

十五、速查表

# ── 安装 ──────────────────────────────
curl -fsSL https://chatgpt.com/codex/install.sh | sh   # macOS/Linux 安装
powershell -c "irm https://chatgpt.com/codex/install.ps1 | iex"  # Windows 安装
npm install -g @openai/codex                            # npm 安装

# ── 启动 ──────────────────────────────
codex                                                   # 交互式启动
codex --approval-mode auto-edit                         # 自动编辑模式
codex --approval-mode full-auto                         # 全自动模式
codex exec "任务描述"                                    # 非交互式执行
codex resume --last                                     # 恢复上次会话

# ── 会话内命令 ────────────────────────
/model              # 切换模型
/permissions        # 调整权限/沙箱设置
/init               # 生成 AGENTS.md
/review             # 启动审查智能体
/status             # 查看状态
/new                # 新会话
/clear              # 清空上下文
/diff               # 查看变更
/undo               # 撤销操作
/plugins            # 插件市场
/skills             # 技能列表
/mcp                # MCP 服务器管理
/help               # 帮助

# ── 快捷键 ────────────────────────────
Ctrl+C              # 中断当前操作
Ctrl+D              # 退出 Codex
↑/↓                 # 历史命令

十六、参考资源

• Codex CLI GitHub 仓库
• OpenAI Codex CLI 官方文档
• SitePoint 终端编程智能体教程 (2026)
• Codex CLI 备忘录 (社区)
• Warp 终端 Codex 集成指南
• 多模型 Gateway 配置指南
• CircleCI + Codex 实战
• 阿里云 Codex 入门教程（中文）

最后更新： 2026-06-22
笔记整理： Claude Code
参考来源： OpenAI 官方文档、GitHub openai/codex、SitePoint、Warp、CircleCI、阿里云开发者社区