第二章. Codex 命令完全解析

第二章. Codex 命令完全解析

2.1. 基础命令

2.1.1. codex

启动交互模式。

1
codex

进入交互模式后，你可以输入自然语言指令，Codex 会持续工作直到任务完成。

使用场景：

  • 需要多轮迭代的任务（如重构、调试）
  • 需要 Codex 记住上下文的任务

示例：

1
2
3
4
5
$ codex
> 帮我重构 src/auth.js，把所有的回调函数改为 async/await
[Codex 开始工作...]
> 现在给这个文件写单元测试
[Codex 继续工作...]

2.1.2. codex “任务描述”

单次执行模式。

1
codex "任务描述"

执行完任务后自动退出。

使用场景：

  • 快速生成代码片段
  • 一次性脚本
  • CI/CD 流程中的自动化任务

示例：

1
codex "给 utils/format.js 写完整的单元测试，使用 Jest"

2.1.3. codex -m <model>

截至 2026 年 1 月 18 日），

可用模型：

  • gpt-5.2-codex：（默认）最新的前沿代理编码模型，平衡了速度与能力。
  • gpt-5.1-codex-max：Codex 优化的旗舰模型，适合深度推理和复杂任务。
  • gpt-5.1-codex-mini：Codex 优化的轻量模型，更便宜、更快，适合简单指令。
  • gpt-5.2：最新的通用前沿模型，在知识广度和推理能力上有全面改进。

使用场景：

  • 深度代码审查/复杂架构设计：使用 gpt-5.1-codex-max
  • 日常开发/快速原型：使用 gpt-5.2-codex
  • 简单脚本/追求极致速度：使用 gpt-5.1-codex-mini

示例：

1
2
# 使用 gpt-5.1-codex-max 进行深度代码审查
codex -m gpt-5.1-codex-max "审查 src/ 目录，找出所有潜在的性能问题和安全漏洞"

2.1.4. codex -i <image>

由于命令行无法粘贴，所以我们只能通过指定目录使用图片作为输入，当然我们后面会推荐插件使用

1
codex -i error-screenshot.png "分析这个报错"

使用场景：

  • 分析截图中的报错信息
  • 根据设计稿生成代码
  • 分析架构图

示例：

1
2
3
4
5
# 分析报错截图
codex -i error.png "这个报错是什么原因？如何修复？"

# 根据设计稿生成代码
codex -i design.png "根据这个设计稿，用 React + Tailwind 实现这个组件"

2.2. 会话管理命令

2.2.1. /new

重置当前会话，清空上下文。

1
> /new

使用场景：

  • 当前任务完成，开始新任务
  • 上下文混乱，需要重新开始

示例：

1
2
3
4
> 帮我重构 auth.js
[任务完成]
> /new
> 现在帮我写一个全新的支付模块

2.2.2. /compact

压缩当前会话的历史记录，释放 Token 空间。

1
> /compact

使用场景：

  • Token 使用量接近上限
  • 历史记录过长，影响推理速度

工作原理：
Codex 会总结之前的对话，保留关键信息，删除冗余内容。

示例：

1
2
> /compact
✅ 已压缩历史记录，释放 5000 tokens

2.2.3. codex resume

恢复之前的会话。

1
codex resume

会显示最近的会话列表，选择一个恢复。

使用场景：

  • 继续之前未完成的任务
  • 查看之前的工作记录

示例：

1
2
3
4
5
6
$ codex resume
1. [2025-01-15 10:30] 重构 auth.js
2. [2025-01-15 09:00] 修复登录 Bug
3. [2025-01-14 16:00] 生成单元测试

选择要恢复的会话：1

2.2.4. codex resume --last

直接恢复最近的会话。

1
codex resume --last

使用场景：

  • 快速继续上一次的工作

2.3. 配置与调试命令

2.3.1. codex --profile <name>

使用指定的配置 Profile。

1
codex --profile review "审查代码"

使用场景：

  • 不同任务使用不同的配置
  • 快速切换工作模式

示例：

1
2
3
4
5
# 使用 review profile（只读模式，使用 o3 模型）
codex --profile review "审查 src/ 目录"

# 使用 fast profile（快速模式，使用 gpt-5-codex）
codex --profile fast "生成一个 TODO 应用"

2.3.2. codex --sandbox

指定沙箱模式。

1
codex --sandbox read-only "分析代码"

可用模式：

  • read-only：只读
  • workspace-write：可写当前目录
  • danger-full-access：完全访问（危险）

使用场景：

  • 代码审查使用 read-only
  • 日常开发使用 workspace-write
  • Docker 容器内使用 danger-full-access

2.3.3. /doctor

检查 Codex 环境是否正常。

1
> /doctor

会检查：

  • Node.js 版本
  • Git 状态
  • MCP 服务器连接
  • 网络连接

使用场景：

  • Codex 行为异常时排查问题

示例输出：

1
2
3
4
✅ Node.js: v20.10.0
✅ Git: 已初始化
⚠️ MCP Server 'postgres': 连接失败
✅ 网络: 正常

2.4. MCP 与 Skills 命令

2.4.1. codex mcp add

添加 MCP 服务器。

1
codex mcp add <name> -- <command>

使用场景：

  • 连接外部工具（数据库、API、IDE）

示例：

1
2
3
4
5
# 添加文件系统访问
codex mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/project

# 添加 PostgreSQL 访问
codex mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgres://user:pass@localhost:5432/db

2.4.2. /mcp

查看当前连接的 MCP 服务器。

1
> /mcp

示例输出：

1
2
3
4
5
6
7
8
✅ Active Servers:
  - filesystem: /Users/prorise/project
  - postgres: localhost:5432/mydb

🛠️ Available Tools:
  - read_file
  - write_file
  - query_db

2.4.3. /skills

查看当前项目可用的 Skills。

1
> /skills

示例输出：

1
2
3
4
📚 Available Skills:
  - unit-test-gen: 生成单元测试
  - code-review: 代码审查
  - refactor: 重构代码

2.4.4. @skill-name

调用指定的 Skill。

1
> @unit-test-gen auth.js

使用场景：

  • 强制使用特定的 Skill
  • 避免 Codex 自动选择错误的 Skill

2.5. 云端命令

2.5.1. codex cloud exec

在云端执行任务。

1
codex cloud exec "任务描述"

使用场景：

  • 本地算力不足
  • 需要长时间运行的任务
  • 需要特定环境（如 GPU）

示例：

1
2
# 在云端运行全量测试
codex cloud exec "运行所有 E2E 测试"

2.5.2. codex cloud list

查看云端任务状态。

1
codex cloud list

示例输出：

1
2
3
4
📋 Cloud Tasks:
  1. [运行中] 重构 src/ 目录 (50% 完成)
  2. [已完成] 生成单元测试
  3. [失败] 修复 Bug

2.5.3. codex apply <task-id>

将云端任务的代码变更应用到本地。

1
codex apply <task-id>

使用场景：

  • 云端任务完成后，拉取代码

示例：

1
2
3
4
5
$ codex cloud list
1. [已完成] 重构 src/ 目录

$ codex apply 1
✅ 已应用 23 个文件的变更

2.6. 高级命令

2.6.1. codex exec

执行命令并返回结构化输出。

1
codex exec "任务描述" --output-schema schema.json -o output.json

使用场景：

  • CI/CD 流程中需要结构化输出
  • 需要将 Codex 的输出传递给其他工具

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 定义 Schema
cat > schema.json <<EOF
{
  "type": "object",
  "properties": {
    "vulnerabilities": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "file": { "type": "string" },
          "line": { "type": "number" },
          "severity": { "type": "string" }
        }
      }
    }
  }
}
EOF

# 执行扫描
codex exec "扫描 src/ 目录的安全漏洞" \
  --output-schema schema.json \
  -o vulnerabilities.json

允许 Codex 搜索网络。

1
codex --search "任务描述"

使用场景：

  • 需要查询最新的文档或 API
  • 需要搜索 Stack Overflow

示例：

1
codex --search "如何在 Next.js 14 中使用 Server Actions？给出完整示例"