Codex CLI 终极教程:安装、配置、Skills、MCP、多智能体

1. Codex CLI 终极教程

学完这篇，你能把 Codex CLI 配置成一个全自动的 AI 开发工作站——从写代码、审 PR 到部署流水线，一条指令全搞定。

先问一句：你现在用的 AI 编程工具是什么？Codex？Claude Code？还是 Cursor？在评论区打个卡，看看大家都在用啥 👇

2. 准备什么

• 一台电脑（macOS / Linux / Windows WSL2）

• Node.js 18+（npm 安装方式）或 Homebrew（macOS）

• OpenAI 账号（ChatGPT Plus/Pro/Team 或 API Key 均可）

• 一个终端，建议 Warp 或 VS Code 内置终端

3. Codex CLI 是什么

一句话：OpenAI 出的终端 AI 编程代理，能读懂你的整个代码库，用自然语言写代码、改文件、跑命令。

它不是代码补全工具（那是 Copilot），而是一个能自主做决策的终端 AI 工程师。你告诉它"帮我搭一个 Go Web 服务"，它会自己创建文件、写代码、安装依赖、启动服务、修 bug，直到跑通为止。

核心数据：

• 底层模型：GPT-5 / GPT-5.5 家族，400K 上下文窗口

• 语言：用 Rust 重写（v0.125.0 起），比早期 TypeScript 版快 N 倍

• 开源：GitHub 上可查看完整源码

• 安装方式：npm / Homebrew / 二进制包

如果你用过 Claude Code，Codex CLI 就是它的直接竞品。两者的对比我们会在后面专门讲。

4. 第一步：安装

三种安装方式，选最顺手的。

方式一：npm（全平台通用）

  
    
    
    
  
  bash
npm install -g @openai/codex

装完验证：

  
    
    
    
  
  bash
codex --version
# 输出示例：@openai/codex 0.125.0

方式二：Homebrew（macOS/Linux）

  
    
    
    
  
  bash
brew install --cask codex

方式三：二进制包（离线/服务器）

从 GitHub Releases 下载对应平台包，解压后将二进制文件放到 PATH 里即可。

Windows 用户：推荐在 WSL2 里安装，原生 Windows 支持目前还是实验性的。

5. 第二步：认证

方式一：ChatGPT 账号登录（推荐）

  
    
    
    
  
  bash
codex

首次运行会自动打开浏览器，跳转到 OpenAI 授权页面。登录后凭证缓存在 ~/.codex/auth.json，后续不用重复登录。

服务器/无头环境用设备码登录：

  
    
    
    
  
  bash
codex login --device-auth

终端会显示一个验证码，在浏览器里输入即可完成授权。

方式二：API Key

  
    
    
    
  
  bash
export OPENAI_API_KEY="sk-你的API-Key"
codex

API Key 方式按用量计费，不走 ChatGPT 订阅配额。适合企业批量使用。

6. 第三步：基本用法

▸ 交互模式

进项目目录，直接敲 codex：

  
    
    
    
  
  bash
cd my-project
codex

终端变成对话界面，你可以用自然语言下指令：

  
    
    
    
  
  bash
> 帮我解释一下这个项目的代码结构
> 写一个 REST API，用 Express，连 MongoDB，加完整的错误处理
> 帮我重构这个模块，拆成三个文件
> 有 bug，用户登录后 token 没刷新，帮我找原因并修

▸ 单次执行模式

不进入交互界面，直接给任务：

  
    
    
    
  
  bash
codex "解释这个项目的架构"
codex "修复 src/utils/auth.ts 里的类型错误"

▸ 全自动模式

跳过确认步骤，让 Codex 自己干活：

  
    
    
    
  
  bash
codex --approval-mode full-auto "创建一个待办事项 App，React + TypeScript"

▸ 关键命令速查

在 Codex 会话里输入这些命令来切换设置：

7. config.toml 深度配置

Codex 的几乎所有行为都通过 ~/.codex/config.toml 控制。这是你驾驭它的核心。

▸ 配置优先级（从高到低）

1. CLI 标志（--model, --config）

2. Profile（--profile <name>）

3. 项目级配置（<project>/.codex/config.toml）

4. 用户级配置（~/.codex/config.toml）

5. 系统配置（/etc/codex/config.toml）

6. 内置默认值

这个优先级设计让你可以在全局设默认值，项目级做覆盖，命令行临时调整。

▸ 基础配置

# 模型配置
model = "gpt-5.3-codex"
model_reasoning_effort = "medium"    # none/low/medium/high/xhigh
model_provider = "openai"

# 审批策略
approval_policy = "on-request"       # untrusted / on-request / on-failure / never

# 沙箱模式
sandbox_mode = "workspace-write"     # read-only / workspace-write / danger-full-access

▸ 沙箱三种模式详解

这是 Codex 最容易被忽视但最重要的配置。

workspace-write 的细粒度控制：

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true              # 允许联网（装依赖需要）
writable_roots = ["/Users/you/.pyenv/shims"]  # 额外白名单目录

在这种模式下，.git/ 和 .codex/ 目录仍然只读——防止 AI 乱改你的 Git 历史。

▸ 多环境 Profile

一套配置走天下不够，不同场景用不同 Profile：

[profiles.research]
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

[profiles.development]
model = "gpt-5.4"
sandbox_mode = "workspace-write"

[profiles.ci]
model = "gpt-5.4"
sandbox_mode = "danger-full-access"
approval_policy = "never"

使用方式：

  
    
    
    
  
  bash
codex exec --profile research "分析这个项目的安全漏洞"
codex exec --profile ci "跑全量测试并修复失败用例"

▸ 多智能体配置（2026 关键特性）

Codex 支持多智能体并行工作，这是它区别于其他 AI CLI 的核心能力：

[features]
multi_agent = true

[agents]
max_threads = 6                    # 最大并发数
max_depth = 1                      # 最大嵌套深度

[agents.explorer]
description = "Read-only codebase explorer"
sandbox_mode = "read-only"

[agents.reviewer]
description = "PR reviewer: security, correctness, missing tests"
sandbox_mode = "read-only"
model_reasoning_effort = "high"

定义好后，主 Agent 会自动把读代码的任务分给 explorer，把审代码的任务分给 reviewer，自己专注做决策和写代码。

▸ 环境变量隔离

Codex 默认不继承你的全部环境变量（安全考虑），你要手动指定白名单：

shell_environment_policy.include_only = ["PATH", "HOME", "NODE_ENV", "DATABASE_URL"]

🎁 想要一份开箱即用的 config.toml 模板？ 在公众号后台私信回复 「codex配置」，我把包含 Profile、沙箱、多 Agent 的完整配置文件发你，复制到 ~/.codex/ 就能用。

8. Skills：Codex 的插件系统

Skills 是 Codex 最重要的扩展机制。类比一下：

• Codex 本身 = 一个全能工程师

• Skill = 你写给这个工程师的"标准作业程序"（SOP）

• 喊一声 /你的技能名，它自动按流程走

▸ Skill 目录结构

  
    
    
    
  
  bash
my-skill/
├── SKILL.md          # 必须：指令 + YAML 头信息
├── scripts/          # 可选：确定性辅助脚本
├── references/       # 可选：长文档（渐进式加载）
├── assets/           # 可选：模板文件
└── agents/           # 可选：该 Skill 专属的子代理配置

▸ 写一个 Skill

最小可用的 SKILL.md：

  
    
    
    
  
  markdown
---
name: pr-reviewer
description: Review pull requests for security issues, logic bugs, and missing tests. Triggered when user asks to review code.
---

## 任务

审查当前分支的改动，按以下维度检查：

1. **安全性**：是否有注入风险、敏感信息泄露、权限绕过
2. **正确性**：逻辑是否完整，边界条件是否覆盖
3. **测试**：改动的代码是否有对应的测试

## 流程

1. 运行 `git diff main...HEAD` 获取变更
2. 逐文件审查，记录发现的问题
3. 按严重程度排序输出报告

## 输出格式

• 🔴 严重：必须在合并前修复

• 🟡 建议：可后续优化

• 🟢 通过：无需修改

放到 ~/.codex/skills/pr-reviewer/ 目录，Codex 会自动发现它。

▸ Skill 安装和管理

从社区安装：

  
    
    
    
  
  bash
# 从 GitHub 安装
codex plugin marketplace add https://github.com/user/skill-repo

# 浏览已安装
codex plugin marketplace list

# 更新
codex plugin marketplace upgrade skill-name

▸ 社区热门 Skill 包

几个值得关注的社区项目：

• Skill Olympus（98 个 Skill + 49 个 Agent）：覆盖从设计到部署的完整 SaaS 流水线

• Awesome Codex Skills（50+ 个）：Notion、Linear、Slack、Sentry 集成

• codex-skills（50+ 个）：TDD、Issue 驱动的开发、CI 监控

搜索关键词 awesome codex skills github 可以看到更多。

9. Hooks：生命周期自动化

Hooks 让你在 Codex 的关键生命周期节点注入自定义脚本。

▸ 支持的 Hook 事件

▸ 配置文件

Hooks 定义在 .codex/hooks.json：

  
    
    
    
  
  json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "bash -c 'cp ${CODEX_FILE_PATH} /tmp/backup/$(date +%s)_$(basename ${CODEX_FILE_PATH})'",
        "description": "写文件前自动备份"
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "node ~/.codex/scripts/collect-session-memory.js",
        "description": "会话结束时收集关键信息到记忆系统"
      }
    ]
  }
}

▸ 实用 Hook 场景

场景一：自动备份

Codex 每次写文件前，自动备份原文件到临时目录。如果改坏了一键恢复。

场景二：安全拦截

PreToolUse 拦截所有 rm -rf 和 git push --force 命令，弹二次确认。

场景三：跨 CLI 记忆同步

会话结束时，把本次的关键发现写到 MEMORY.md，下次 Claude Code 和 Codex CLI 都能读到。

10. MCP：让 Codex 和任何工具对话

MCP（Model Context Protocol）是 Codex 连接外部世界的通用协议。2026 年 4 月起，Codex 内置了 MCP 服务器。

▸ Codex 作为 MCP 服务器

把 Codex 变成其他 AI 工具的工具：

  
    
    
    
  
  bash
codex mcp-server

这行命令启动一个 stdio MCP 服务器，任何 MCP 兼容的客户端（Claude Code、Cursor、VS Code）都能调用 Codex 来写代码。

这意味着：你可以用 Claude Code 做项目规划，然后让它调用 Codex 来执行代码编写——两个最强的 AI 各干自己最擅长的事。

▸ 给 Codex 装上 MCP 工具

反过来，你也可以给 Codex 扩展外部工具能力。在 config.toml 里配置：

[mcp_servers.playwright]
command = "npx"
args = ["-y", "@anthropic-ai/mcp-server-playwright"]

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@anthropic-ai/mcp-server-filesystem", "/path/to/allowed/dir"]

配置完后，Codex 就能操作浏览器做端到端测试，或者访问指定目录外的文件。

▸ 社区 MCP 桥接方案

一些值得关注的 MCP 桥接包：

• codex-mcp-bridge：把 Codex 暴露为 MCP 工具，支持并发队列管理、自动模型切换

• codex-dobby-mcp：支持异步后台任务、多 Agent 评审并行

• mcp-codex-dev：TDD 流程自动化、实时进度监控

11. 自动化流水线实战

理论知识够多了。下面是三种实际可跑的自动化流水线。

▸ 流水线一：代码审查自动化

  
    
    
    
  
  bash
#!/bin/bash
# pre-push-review.sh —— push 前自动审查

echo ">> 获取变更..."
git diff origin/main...HEAD > /tmp/changes.diff

echo ">> Codex 安全审查..."
codex exec --profile ci --sandbox read-only \
  "审查 /tmp/changes.diff 的安全问题，按严重程度排序，输出 JSON"

echo ">> Codex 逻辑审查..."
codex exec --profile ci --sandbox read-only \
  "审查 /tmp/changes.diff 的逻辑正确性和边界条件"

echo ">> 审查完成，查看报告后再 push"

可以把这段脚本挂在 .codex/hooks.json 的 PreToolUse 里，也可以单独跑。

▸ 流水线二：全自动 Bug 修复 + 测试

  
    
    
    
  
  bash
#!/bin/bash
# auto-fix.sh —— 修 bug + 跑测试 + 生成报告

BUG_DESC="$1"

echo ">> Codex 定位问题..."
codex exec --profile development \
  "分析这个 bug：${BUG_DESC}。定位相关代码，给出根因。"

echo ">> Codex 生成修复..."
codex exec --approval-mode full-auto \
  "修复 ${BUG_DESC}。遵循现有代码风格，添加必要的测试。"

echo ">> 运行测试..."
npm test

echo ">> Codex 生成修复报告..."
codex exec --sandbox read-only \
  "总结本次修复：改了什么、为什么这么改、潜在风险。输出 Markdown。"

▸ 流水线三：Claude Code + Codex 联合作战

这是目前比较前沿的玩法——让两个 CLI 协作：

  
    
    
    
  
  bash
Claude Code（规划者）
  │
  ├── 分析需求 → 输出设计方案
  ├── 拆分任务 → 分配给 Codex 执行
  │
  └── Codex CLI（执行者）← 通过 MCP 调用
       ├── 创建项目脚手架
       ├── 实现具体功能
       └── 编写测试用例

Claude Code（验收者）
  │
  ├── 审查 Codex 的产物
  ├── 跑集成测试
  └── 输出最终报告

实操步骤：

1. 终端 A 启动 Codex MCP 服务器：codex mcp-server

2. 终端 B 配置 Claude Code 的 MCP，指向 Codex 的 stdio 管道

3. 在 Claude Code 里说：“分析这个项目需求，设计架构，然后通过 Codex 实现”

具体 Claude Code 的 MCP 配置（mcp.json）：

  
    
    
    
  
  json
{
  "mcpServers": {
    "codex": {
      "command": "codex",
      "args": ["mcp-server"]
    }
  }
}

▸ 流水线四：GitHub Actions CI 集成

  
    
    
    
  
  yaml
# .github/workflows/codex-review.yml
name: Codex PR Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Codex Security Review
        run: |
          codex exec --profile ci --sandbox read-only \
            "审查 PR #${{ github.event.pull_request.number }} 的改动：
            1. 安全漏洞
            2. 性能退化
            3. 破坏性变更
            输出 Markdown 格式报告到 review-report.md"

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('review-report.md', 'utf8');
            github.rest.issues.createComment({
              ...context.repo,
              issue_number: context.issue.number,
              body: report
            });

12. 五个实战案例剖析

▸ 案例一：零基础搭全栈应用

需求：“我要一个博客系统，React 前端 + Go 后端 + PostgreSQL”

操作：

  
    
    
    
  
  bash
codex --approval-mode full-auto \
  "创建一个博客系统：
  - 前端：React + TypeScript + Tailwind
  - 后端：Go + Gin 框架
  - 数据库：PostgreSQL
  - 功能：文章的增删改查、用户认证、Markdown 编辑器
  - 包含 Docker Compose 部署配置"

Codex 做了什么：自动创建项目结构、生成前后端代码、写 Dockerfile、配置数据库连接、初始化 Git 仓库。20 分钟跑通整个应用。

为什么要全自动模式：这种脚手架级别的任务，每次确认 50 次太累了。全自动的信任成本远低于手动确认的时间成本。

▸ 案例二：遗留代码重构

需求：“这个 2 万行的 utils.py 需要拆成 5 个模块”

操作：

  
    
    
    
  
  bash
codex exec --profile development \
  "分析 src/utils.py 的函数依赖关系，提出拆分方案：
  1. 按功能域分组
  2. 标记循环依赖
  3. 给出拆分后的 import 关系
  先出方案，我确认后再动手改。"

为什么要用 read-only 先分析：重构最大的风险不是改错代码，而是改了之后所有 import 都断了。先让 AI 出方案，你确认依赖关系没问题，再让它动手。

▸ 案例三：跨语言迁移

需求：“把 Python 的数据处理脚本翻译成 Rust，要求性能提升 10 倍以上”

操作：

  
    
    
    
  
  bash
codex exec \
  "将 scripts/data_pipeline.py 翻译成 Rust：
  1. 保持逻辑完全一致
  2. 使用 rayon 做并行处理
  3. 输出中有性能对比的 benchmark 测试
  4. 写一个 Python 兼容的 FFI 接口"

坑点：跨语言迁移不要指望一次成功。让 Codex 先生成初版，然后重点审查：内存管理是否正确、错误处理是否完整、浮点精度是否一致。这三个是跨语言迁移最容易出问题的地方。

▸ 案例四：自动化技术文档生成

需求：“整个项目的 API 文档自动生成”

操作：

  
    
    
    
  
  bash
codex exec --sandbox read-only \
  "扫描所有 API 路由文件，生成 OpenAPI 3.0 规范文档：
  1. 从代码注释和类型定义中提取参数说明
  2. 生成请求/响应示例
  3. 标注认证要求
  4. 输出 swagger.json 和可读的 Markdown"

效果：200 个 API 端点，15 分钟生成完。人工写至少 2 天。

▸ 案例五：第三方 API 集成

需求：“对接 Stripe 支付，含 Webhook 处理、退款逻辑”

操作：

  
    
    
    
  
  bash
codex exec \
  "帮我对接 Stripe 支付：
  1. 先去 Stripe 官方文档理解最新 API
  2. 实现：创建支付会话、处理 Webhook、退款
  3. 包含幂等性处理和错误重试
  4. 写 3 个测试场景：正常支付、支付失败、部分退款"

Codex 的 Web 搜索能力在这里发挥作用——它会自己去 Stripe 文档查最新的 API 用法，而不是凭训练数据写过时的代码。

13. Codex CLI vs Claude Code 对比

很多人纠结选哪个。直说了——成年人不用选，但评论区肯定要吵一架。

看完下面的对比，来评论区站队：你用的是 Codex 派 还是 Claude 派？还是两个都要的 "我全都要"派？👇

选 Codex CLI 的场景： • 需要多 Agent 并行处理大项目

• 在意开源，想自己定制

• 重度使用 MCP 做复杂集成

• 团队使用，需要严格的沙箱控制

选 Claude Code 的场景： • 个人开发，追求开箱即用

• 需要丰富的 Hooks 做全链路自动化

• 写作/内容创作类任务（Claude 的语言能力更强）

• 已投入 Anthropic 生态

最佳实践：两个都用。 Claude Code 做规划和审核，Codex CLI 做执行。通过 MCP 桥接，各取所长。

14. 常见坑和解决方案

1. codex: command not found

npm 全局 bin 目录不在 PATH 里。运行 npm config get prefix 查看路径，把它加到 PATH。

2. 自定义 API 代理不生效

检查 ~/.codex/config.toml 中的 model_provider 是否正确配置。代理地址必须是 OpenAI 协议兼容的。

3. Windows 兼容问题

原生 Windows 支持目前不稳定，建议用 WSL2。在 WSL 里安装 Ubuntu，然后在 Ubuntu 里装 Codex。

4. 沙箱报"Permission denied"

如果在 workspace-write 模式下需要操作工作区外的文件，在 config.toml 里把路径加到 writable_roots。

5. MCP 服务器连接超时

MCP 客户端默认超时约 120 秒。长任务用异步模式（start_run → get_run），或者增加 MCP 超时配置。

6. /goal 任务卡住

新版 /goal 有定时器机制，会一直尝试直到完成。如果真卡住了，用 /status 查看配额是否耗尽。

▸ 📌 三个动作，选一个：

1. 评论区聊聊：你用 Codex 踩过什么坑？或者有什么骚操作？分享出来，大家一起学。

2. 私信领配置：后台回复 「codex配置」，我把开箱即用的 config.toml 模板发你。

3. 转发给同事：如果你团队还在纠结选哪个 CLI 工具，把这篇文章甩给他。

📮 关注「AI信号实验室」，追踪前沿信号，动手实验每一个新能力。