Codex智能体使用教程

fengchengwu2012

21人浏览 · 2026-06-22 10:19:52

fengchengwu2012 · 2026-06-22 10:19:52 发布

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

一、是什么 & 不是什么

	Codex CLI	GitHub Copilot	Claude Code
形态	终端命令行工具	IDE 插件	终端命令行工具
能力层级	项目级多文件编辑	行级/函数级补全	项目级多文件编辑
是否可执行命令	✅ 沙箱内执行	❌	✅
开源	✅	❌	❌
语言	Rust	TypeScript	TypeScript
模型	GPT-5 / Codex 系列	GPT-4o	Claude 4 系列

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

二、安装

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

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

方式	说明
ChatGPT 账号登录（推荐）	打开浏览器 OAuth 登录，包含在 ChatGPT Plus / Pro / Business 套餐中
API Key	`export OPENAI_API_KEY=sk-xxxxxxxx` 后启动

四、三种运行模式

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

模式	文件编辑	Shell 命令	适用场景
Suggest（建议）	每次提醒确认	每次提醒确认	🔰 新手、初次探索项目
Auto-Edit（自动编辑）	自动执行	每次提醒确认	信任代码、频繁重构
Full-Auto（全自动）	自动执行	自动执行	🚀 CI/CD、非交互式

命令行切换

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

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

会话内切换

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

五、必备斜杠命令

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

命令	功能
`/model`	切换模型（如 `gpt-5-codex`、`gpt-5-mini`、`gpt-5-nano`）
`/permissions`	调整沙箱模式和审批策略
`/init`	为当前项目生成 `AGENTS.md` 规范文件
`/review`	启动独立审查智能体，审查当前修改
`/status`	查看当前模型、用量限额、运行模式
`/new`	开启新对话线程（清空上下文）
`/clear`	清空当前会话上下文
`/plugins`	打开插件市场
`/skills`	列出可用技能
`/mcp`	管理 MCP 服务器连接
`/memories`	管理持久化记忆
`/diff`	查看当前会话所有变更
`/undo`	撤销上次操作
`/help`	帮助信息

六、核心工作流

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 浏览和安装。常见插件：

插件	功能
GitHub	管理 Issues、PR、Actions
CircleCI	触发流水线、查看构建状态
Linear	管理工单和 sprint
Figma	读取设计稿、生成组件
PostgreSQL	直接连接数据库查询
Slack	发送通知、查询消息

十、自动化 & 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	Claude Code
开发方	OpenAI	Anthropic
底层模型	GPT-5-Codex / Codex 系列	Claude 4 系列
开源	✅ GitHub: openai/codex	❌
语言	Rust（性能高）	TypeScript
安装	二进制 / npm / brew	npm
沙箱	✅ 内置，默认开启	⚠️ 依赖系统权限
审批策略	三级可配（Suggest/Auto-Edit/Full-Auto）	允许/拒绝/始终允许
项目配置	AGENTS.md / codex.md	CLAUDE.md
插件系统	✅ 插件市场	⚠️ MCP + hooks
CI/CD 集成	✅ `codex exec` 专为自动化设计	⚠️ 可通过管道使用
记忆功能	✅ `/memories`	✅ 文件型记忆
多模型切换	✅ `/model` 随时切换	❌ 固定模型
context 窗口	取决于模型	200K tokens
价格	包含在 ChatGPT 套餐内	包含在 Claude 套餐内

选择建议

选 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
↑/↓                 # 历史命令

十六、参考资源

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

https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

Sem 语义 Git 工具深度解析：AI Agent 代码理解的“新原语“与 2.3 倍准确率提升

它让 AI Agent 不再"看行"，而是"看实体"。如果你在构建 AI 代码审查流程：Sem 是必须品，不是奢侈品。2.3 倍的准确率提升意味着显著减少人工复核的工作量。如果你在用 Claude Code 或 Codex：通过 MCP 集成 Sem，让 Agent 的代码理解能力上一个台阶。如果你是工具开发者：Sem 的"实体级版本控制"范式值得关注。未来的 AI 编程工具很可能都会采用类似的思

AI编程社区

2026深度决策指南｜Work模式 vs Composer实测对比：中文vibe coding到底该怎么选

两款vibe coding工具各有所长，Cursor Composer胜在长对话上下文记忆和沉浸式对话界面，更适合标准书面指令开发；而TRAE Work模式（原 SOLO 模式）完全贴合国内开发者真实编码习惯，中文口语理解力、初版代码完整性、迭代稳定性全面更适配本土vibe coding场景。中文环境下，vibe coding最大的风险不是代码写得慢，而是AI听不懂口语需求，漏掉核心业务逻辑。