知识库

CodexCLI教程

markdown
2026年7月17日阅读约 7 分钟1,301 字

更新于 2026年7月17日

Codex CLI 完整教程：精细控制的 AI 编程助手

目录

  1. Codex CLI 是什么？
  2. 安装与配置
  3. 核心概念
  4. 斜杠命令详解
  5. 配置选项
  6. 自定义命令
  7. MCP 扩展
  8. 高级用法
  9. 对比总结

1. Codex CLI 是什么？

1.1 一句话定义

Codex CLI 是 OpenAI 推出的开源 AI 编程助手，采用 Rust 编写，以精细控制和高度可定制为核心设计哲学。

1.2 核心特点

特点 说明
高性能 Rust 编写，响应速度快
开源透明 Apache 2.0 许可证
精细控制 强调用户约束与自定义
高度可配置 自定义命令、权限模型、模型提供商
多模型支持 OpenAI、Anthropic、Google、百炼等

1.3 与 Claude Code 的区别

┌─────────────────────────────────────────────────────────────┐
│                   哲学差异                                   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Claude Code              Codex CLI                         │
│   ───────────              ─────────                         │
│   AI 主导                  用户主导                          │
│   自主接管项目              精细控制每步                      │
│   深度推理                  高度可定制                       │
│   闭源生态                  开源透明                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

1.4 统计数据

  • GitHub: 94.8k Stars | 14.1k Forks
  • 贡献者: 511 位
  • 语言: 96.5% Rust
  • 许可证: Apache-2.0

2. 安装与配置

2.1 自动安装脚本

Mac / Linux（推荐）：

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

Windows PowerShell：

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

2.2 包管理器安装

# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex

2.3 手动安装

  1. 访问 GitHub Releases
  2. 下载对应平台的二进制文件：
    • macOS Apple Silicon: codex-aarch64-apple-darwin.tar.gz
    • macOS x86: codex-x86_64-apple-darwin.tar.gz
    • Linux x86: codex-x86_64-unknown-linux-musl.tar.gz
    • Linux ARM: codex-aarch64-unknown-linux-musl.tar.gz
  3. 解压并将 codex 添加到 PATH
# 示例：Linux x86_64
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex /usr/local/bin/
chmod +x /usr/local/bin/codex

2.4 身份认证

方式一：ChatGPT 账号

codex
# 选择 "Sign in with ChatGPT"

支持的计划：

  • Plus
  • Pro
  • Business
  • Edu
  • Enterprise

方式二：API Key

# 配置 API Key
export OPENAI_API_KEY="your-api-key"

# 或在 ~/.codex/auth.json 配置

2.5 快速启动

# 启动交互式 CLI
codex

# 启动桌面应用
codex app

# 登录
codex sign-in

3. 核心概念

3.1 AGENTS.md — 项目记忆文件

与 Claude Code 的 CLAUDE.md 类似，Codex CLI 使用 AGENTS.md。

作用：

  • 定义项目技术栈
  • 设置编码规范
  • 指定构建命令
  • 提供上下文

示例：

# My Project

## 技术栈
- Node.js 18+
- Express.js
- PostgreSQL
- Docker

## 编码规范
- 4 空格缩进
- 异步函数用 async/await
- 错误处理必须有

## 构建命令
- 开发: `npm run dev`
- 测试: `npm test`
- 构建: `npm run build`

## 目录结构
- /src - 源代码
- /tests - 测试
- /docs - 文档

3.2 权限模式

Codex CLI 有三种权限级别：

模式 说明 风险
Auto 读取文件自动执行，修改需确认 低
Read Only 只读，禁止任何写入 极低
Full Access 全自动执行 高

3.3 工作流程

┌─────────────────────────────────────────────────────────────┐
│                   Codex CLI 工作流                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 启动: codex                                              │
│  2. 初始化: /init → 生成 AGENTS.md                          │
│  3. 任务: 输入需求                                           │
│  4. 执行: Codex 分析 → 建议 → 执行                          │
│  5. 审批: 按 Enter 确认修改                                   │
│  6. 完成: /exit 退出                                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

4. 斜杠命令详解

4.1 会话与流程控制

命令 功能 场景
/new 新建会话 开始无关任务
/undo 撤销上一步 Codex 改错时回退
/exit 退出程序 切换项目
/quit 退出程序 同上
/logout 登出账号 切换账号

4.2 配置与权限

命令 功能 场景
/approvals 设置权限模式 控制命令执行
/model 切换模型 按任务选模型
/status 查看 Token 使用量 监控资源
/mcp 管理 MCP 服务器 调试外部工具

4.3 上下文与记忆

命令 功能 场景
/init 生成 AGENTS.md 项目初始化
/compact 压缩对话历史 上下文过长时
/mention 添加文件到上下文 引导专注特定模块
/diff 查看 Git 变更 提交前检查

4.4 动作与高级功能

命令 功能 场景
/review 代码审查 AI 扮演 Reviewer
/skills 浏览实验性技能 探索新功能

4.5 模型切换

可用模型：

模型 特点
gpt-4o 平衡性能与速度
o1-preview 深度推理
o3 最新推理模型
claude-3-5-sonnet Anthropic 模型 
# 切换模型
/model gpt-4o

# 查看当前模型
/status

5. 配置选项

5.1 配置文件位置

  • Unix/Linux/Mac: ~/.codex/config.toml
  • Windows: %USERPROFILE%\.codex\config.toml

5.2 完整配置结构

# ~/.codex/config.toml

# 模型配置
model = "gpt-4o"
model_provider = "openai"

# 沙盒模式
sandbox_mode = "workspace-write"

# 审批策略
approval_policy = "on-request"

# 网络搜索
web_search = "disabled"

# 自动压缩
auto_compact = true

5.3 认证配置

// ~/.codex/auth.json
{
  "openai": {
    "api_key": "your-openai-key"
  },
  "anthropic": {
    "api_key": "your-anthropic-key"
  },
  "dashscope": {
    "api_key": "your-dashscope-key"
  }
}

5.4 支持的模型提供商

提供商 模型示例
OpenAI GPT-4o, O1, O3, GPT-4.1
Anthropic Claude 3.5 Sonnet, Claude 4
Google Gemini 2.0, Gemini 2.5
百炼 (DashScope) qwen-max, qwen-plus
OpenRouter 多种开源模型
Groq Llama 系列
Azure OpenAI GPT-4o, O1

5.5 百炼 (阿里云) 配置示例

# ~/.codex/config.toml
model = "qwen-max"
model_provider = "dashscope"

// ~/.codex/auth.json
{
  "dashscope": {
    "api_key": "your-dashscope-api-key"
  }
}

6. 自定义命令

6.1 创建自定义命令

命令目录: ~/.codex/prompts/

命名规则: Markdown 文件名（不含扩展名）即为命令 ID

6.2 示例：安全审计命令

创建 ~/.codex/prompts/security-audit.md:

# Security Audit

对当前项目进行安全审计：

1. 搜索硬编码密码/密钥
2. 检查 SQL 注入风险
3. 检查 XSS 风险
4. 检查依赖漏洞
5. 生成安全报告

使用: 重启 Codex 后，输入 /security-audit

6.3 示例：自动修复流程

创建 ~/.codex/prompts/fix-and-test.md:

# Fix and Test Workflow

自动化修复测试流程：

1. 运行测试，捕获失败
2. 分析失败原因
3. 修复问题代码
4. 再次运行测试
5. 确保全部通过
6. 提交代码

6.4 命令参数支持

使用 $NAME 占位符：

# Review PR $PR_NUMBER

1. 运行: gh pr view $PR_NUMBER
2. 分析代码变更
3. 提供审查意见

6.5 项目级命令

在项目目录创建 .codex/prompts/ 目录，命令会自动带有 project: 前缀。

7. MCP 扩展

7.1 MCP 支持

Codex CLI 支持 Model Context Protocol，可连接外部工具。

7.2 MCP 配置

# ~/.codex/config.toml

[[mcp_servers]]
name = "filesystem"
type = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "./"]

[[mcp_servers]]
name = "github"
type = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "your-token" }

7.3 常用 MCP 服务器

服务器 功能
@modelcontextprotocol/server-filesystem 文件操作
@modelcontextprotocol/server-github GitHub API
@modelcontextprotocol/server-slack Slack 消息
@modelcontextprotocol/server-brave-search 网页搜索

8. 高级用法

8.1 非交互模式

# 单次提示
codex -p "explain this code"

# JSON 输出
codex -p "explain this code" -f json

# 指定目录
codex -p "explain this code" -c /path/to/project

8.2 管道操作

# 分析日志
tail -100 app.log | codex -p "find errors"

# 批量处理
ls *.js | codex -p "add JSDoc comments"

8.3 CI/CD 集成

# GitHub Actions
- name: Code Review
  run: |
    codex -p "review the changes in this PR"

8.4 IDE 集成

Codex CLI 支持 VS Code / Cursor / Windsurf 等编辑器。

安装插件：

  1. 打开 IDE 插件市场
  2. 搜索 "Codex"
  3. 安装官方插件

9. 对比总结

9.1 横向对比

维度 Claude Code Codex CLI OpenCode
公司 Anthropic OpenAI 开源社区
语言 Node.js Rust Go
开源 ❌ ✅ Apache 2.0 ✅ MIT
核心哲学 深度推理 精细控制 简洁高效
记忆文件 CLAUDE.md AGENTS.md 无固定
自定义命令 Skills Markdown 自定义命令
多代理 ✅ ❌ ❌
定时任务 ✅ ❌ ❌
记忆文件格式 Markdown Markdown 无
MCP 支持 ✅ ✅ ✅

9.2 选型建议

场景 推荐工具
需要 Claude 模型 + 深度推理 Claude Code
需要自定义工作流 + 极客体验 Codex CLI
需要轻量 + 多模型支持 OpenCode
需要完整 AI 工程方法论 Claude Code + Superpowers

9.3 各自优势

Claude Code 优势：

  • 深度推理能力
  • 多端协作
  • 定时任务
  • 子代理团队

Codex CLI 优势：

  • 开源透明
  • 高度可定制
  • 自定义命令强大
  • Rust 性能

OpenCode 优势：

  • 轻量快速
  • 多模型支持
  • TUI 体验好
  • MCP 原生支持

9.4 官方资源

附录：常见问题

Q1: 安装失败？

Linux/Mac: 确保有 curl 和必要权限

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

Windows: 使用 PowerShell（非 CMD）

irm https://chatgpt.com/codex/install.ps1 | iex

Q2: 认证失败？

检查 API Key 配置：

# 检查环境变量
echo $OPENAI_API_KEY

# 或检查配置文件
cat ~/.codex/auth.json

Q3: 如何切换模型？

# 在 Codex 中
/model gpt-4o

# 或修改配置
# ~/.codex/config.toml
model = "gpt-4o"

Q4: 自定义命令不生效？

  1. 重启 Codex CLI
  2. 检查文件位置：~/.codex/prompts/
  3. 检查文件格式：.md 扩展名

本教程基于 Codex CLI 官方文档编写，最后更新于 2026 年 7 月。