Codex完整实操手册：覆盖安装、沙箱权限、Skills与MCP协议的11大模块

一、Codex 产品概述

1.1 产品形态

Codex 目前拥有 4 种形态：Siri 端、终端、网页端插件、独立 APP。其中独立 APP 是功能最强大的形态，也是本次课程重点推荐的核心使用方式。

1.2 同类工具对比

当前 AI 编程工具主流为三巨头：Cursor、Claude Code、Codex，三者各有侧重，建议都掌握以适配不同公司的开发环境。

价格对比

• Codex API 价格更低，是性价比首选。
• Claude Code、Cursor 的订阅成本相对更高。

稳定性对比

• Claude Code 存在限速、封号问题。
• Codex 没有明显的限速、封号问题，降智感知也不明显（因使用场景不同，个体会有差异）。

能力侧重对比

• Claude Code：更偏向逻辑正确性、代码结构与功能实现，更受后端开发者偏好。
• Codex：更注重 UI 细节、色彩搭配、动画效果与操作提示，更受前端、APP 开发者偏好。

1.3 学习建议

建议同时熟悉三款主流工具，以适配不同企业的账号与工具规范。本教程聚焦 Codex 的深度使用，对零基础的开发入门者也比较友好。

二、前置准备：安装前置软件

2.1 先决条件总览

安装 Codex 前需要先安装三款基础工具：

• Git：所有 AI 开发工具与 Agent 的通用依赖，用于代码协同与版本管理。
• Node.js：用于安装项目依赖包。
• VS Code：不是强制必需品，但强烈推荐安装。Codex 本身不提供代码编辑功能，AI 生成代码后的细节修改需要依赖传统开发工具，VS Code 是首选集成编辑器。

2.2 Git 安装

• 官方下载地址：https://git-scm.com/?hl=zh-cn
• 安装方式：傻瓜式安装，全程点击「下一步」即可。
• 安装包也可以从课程资料包获取，适合网络环境不佳的用户。

2.3 Node.js 安装

• 官方下载地址：https://nodejs.org/zh-cn
• 支持 Windows、macOS、Linux 系统，根据自身系统下载对应版本。
• Codex 对 Node.js 版本没有特殊要求，直接安装最新版即可。
• 验证安装：按下 Win+R 输入 cmd 打开命令行，执行 node -v，输出版本号即安装成功。

2.4 VS Code 安装与中文配置

• 官方下载地址：https://code.visualstudio.com/
• 安装方式：傻瓜式安装，可以自定义安装盘符；C 盘空间充足时建议安装在 C 盘，盘符对运行速度没有显著差异。
• 中文语言包配置：
  • 点击左侧扩展栏（四个方块图标），搜索 Chinese (Simplified)。
  • 安装语言包后，点击右下角弹出的重启按钮，重启后界面就切换为中文。

三、Codex 安装与基本使用

3.1 安装步骤

• 官方地址：https://openai.com/zh-Hans-CN/codex/
• 提供 Windows 与 macOS 两个版本，根据系统自动匹配下载。
• 下载得到的是下载器而非完整安装包，运行后通过微软商店完成下载安装，安装包约 400MB，耐心等待即可。
• 网络要求：访问官网、安装及使用 Codex 全程需要科学上网。

3.2 界面概览

• 左侧：工具栏，包含新对话、搜索、插件、自动化、项目列表等。
• 中间：对话窗口，用于输入指令与查看执行结果。
• 顶部：标准菜单栏，与常规桌面软件一致。
• 软件默认英文，启动后会自动根据系统语言切换为中文。

3.3 沙箱设置

首次打开 Codex 时会出现「设置沙箱」按钮，点击后自动完成配置即可。沙箱是 Codex 权限管理的核心机制，后续权限章节会详细讲解。

3.4 创建工作空间

• 可以创建多个本地文件夹作为独立工作空间（项目），实现多项目环境隔离。
• 添加方式：
  • 直接将本地文件夹拖拽到左侧项目栏。
  • 点击「添加新项目」选择本地文件夹。

3.5 多任务并行特性

Codex 的核心优势之一是支持同时开启多个任务，任务列表的管理也很友好：

• 每个任务有明确的状态标识：进行中（转圈加载）、等待批准（需要人工授权操作）、已完成（蓝色小点标记）。
• 多任务并行执行互不干扰，可以显著提升工作效率。
• 新建对话快捷键：Windows Ctrl+N，macOS Command+N。

3.6 对话项目归属

• 对话窗口可以选择归属的项目，生成的代码会直接写入对应的项目文件夹。
• 选择「不使用项目」时，对话会归类到通用的「对话」区域，不关联任何本地项目目录。

四、功能模块详解

4.1 搜索历史对话

• 入口：左侧搜索按钮，或快捷键 Ctrl+G。
• 能力：仅支持搜索对话标题，无法搜索对话正文内容。
• 使用技巧：配合「对话重命名」功能，用关键词标注重点对话，便于后续检索。

4.2 对话重命名

• 操作：双击左侧对话列表中的对话条目，即可修改标题。
• 作用：自定义标识重点对话，提升历史检索效率。

4.3 对话归档

• 作用：清理冗余对话，保持主列表整洁，归档后对话会从主列表移除。
• 操作：点击对话右侧的归档按钮，确认后完成归档。
• 恢复路径：左下角「设置」→「已归档对话」，点击「取消归档」即可恢复。

4.4 权限管理（沙箱机制）

Codex 的权限控制围绕沙箱展开，将当前项目文件夹作为沙箱边界，通过底层操作系统功能实现权限隔离（不是模型层面的限制），安全性更高。对话框下方有一个下拉菜单，可以切换三种权限模式：

4.4.1 默认权限

• 权限范围：仅对沙箱（当前项目文件夹）内的文件拥有读写权限。
• 限制：
  • 不能修改沙箱外的任何系统文件。
  • 云端模式下禁止联网，无法执行 npm install 等下载依赖、访问外网的操作。
• 提权机制：当 Codex 需要访问沙箱外文件或联网时，会触发提权（Escalate），需要人工审核批准后才可继续执行。

4.4.2 自动审查

• 机制：调用专用小模型对提权操作进行安全审查，区分风险等级。
  • 低风险操作：自动放行，无需人工确认。
  • 高风险操作（如删除文件）：仍需人工审核。
• 优势：大幅减少频繁授权的繁琐操作，同时保留安全底线，是推荐日常使用的权限模式。

4.4.3 完全访问权限

• 权限：无视沙箱限制，可以读写电脑任意文件、执行联网命令，拥有完整的系统操作权限。
• 风险：属于高危操作，会显著增加数据丢失、泄露与异常行为的风险，开启前需要谨慎评估。
• 开启时会弹出风险确认弹窗，需要手动二次确认后方可启用。

对比补充：Claude Code 的沙箱需要主动设置，默认没有沙箱概念，配置繁琐；Codex 的沙箱默认启用，体验更友好。

4.5 上下文使用量管理

• 位置：对话窗口下方的背景信息窗口进度条。
• 作用：显示历史对话占用的模型上下文空间（单位：k token）。
• 自动机制：上下文超过上限时，Codex 会自动压缩对话历史，释放可用空间。
• 手动压缩：输入 /压缩 可手动触发上下文压缩。
• 最佳实践：清空优于压缩。过多的历史会话会干扰模型的专注力、增加 Token 消耗，新任务建议开启全新对话，而不是在原有对话中延续。

4.6 模型选择

对话框下方可以调整模型参数，包含智能强度、模型版本、速度三个维度。

4.6.1 智能强度

根据任务复杂度选择模型思考深度，分为低、中、高、超高四档，默认中档。简单任务用中档即可，复杂任务可切换至高或超高。

4.6.2 模型版本

• 默认使用最新版 GPT-5.5，可以切换为 GPT-5.4、GPT-5.4 mini、GPT-5.3、Codex 5.2 等版本。
• 建议：优先使用最新模型，综合能力更优。

4.6.3 速度模式

• 标准模式：常规 Token 消耗。
• 快速模式：生成速度提升，但 Token 消耗是标准模式的 1.5 倍。
• 可以根据额度余量与需求紧急程度灵活选择。

4.7 剩余额度

• 查看路径：左下角「设置」→「剩余额度」。
• 限额规则：包含 5 小时限额 与 周限额 两个维度，任意一个达到上限都无法继续使用；两个限额都有固定的重置周期。
• 额度耗尽解决方案：等待周期重置，或切换到其他模型版本。
• 订阅档位：Pro 版有多个档位（8 美元、20 美元、100 美元等），日常使用 8 美元档位就够用，重度使用可选 20 美元档位，整体价格低于 Claude Code。

4.8 添加参考资料

• 入口：输入框左侧的「+」按钮。
• 支持上传图片、文件作为参考，补充提示词信息。
• 也可以直接复制粘贴图片或文件到对话窗口，效果一致。

五、控制与引导（Steer）

5.1 功能作用

Steer（掌舵 / 引导）是 Codex 的核心能力之一：当发现 AI 执行方向偏离需求、理解错误时，可以随时人工干预，中断当前执行并修正方向，避免无效运算。

5.2 操作方式

• AI 执行过程中，直接在输入框输入修正指令。
• 点击消息旁的「引导」按钮，Codex 会立即暂停当前任务，按照新的修正指令继续执行。
• 如果不点击「引导」，新指令会进入队列，等待当前任务完成后再按顺序执行。

5.3 跟进行为设置

• 设置路径：左下角「设置」→「常规」→「跟进行为」。
• 两种默认模式：
  • 排队：默认模式，新指令自动加入队列，按顺序执行。适合多任务批量下发，无需值守。
  • 引导：新指令默认直接中断当前任务，立即执行修正。
• 快捷键：按 Ctrl+Enter 发送消息，可以对单条消息执行与默认模式相反的操作。
• 建议：保持默认「排队」模式，需要干预时手动点击「引导」即可，兼顾灵活性与批量处理能力。

六、计划模式

6.1 普通模式 vs 计划模式

• 普通模式：输入需求后，AI 直接开始编写代码、执行操作。
• 计划模式：AI 先澄清问题、生成详细的执行计划，用户确认计划无误后，AI 才开始实际执行。

6.2 开启与使用流程

• 点击输入框左侧「+」，选择「计划模式」。
• 输入需求后，Codex 会生成包含实施步骤、假设条件、验证标准的完整计划。
• 确认计划：选择「是，实施此计划」开始执行；选择「否，请告知 Codex 如何调整」可以修改计划，直到满意后再执行。

6.3 批注模式

在右侧内置浏览器预览页面时，可以使用批注模式实现可视化精准修改：

• 点击浏览器中的「注释」按钮，框选页面区域并输入修改需求。
• 发送后，Codex 会精准针对标注区域进行调整。

6.4 最佳使用场景

计划模式适合多步骤、高复杂度的任务，推荐在以下场景使用：

• 首次从零搭建项目
• 重大重构（框架迁移、技术栈升级）
• 复杂 Bug 修复
• 多步骤长流程任务

简单代码修改可以直接使用普通模式，提升效率。

七、代码管理

7.1 基础说明

Codex 并非传统 IDE，本身不提供代码编辑功能，这也是需要安装 VS Code 的核心原因。代码的精细编辑、调试仍需配合专业编辑器完成。

7.2 外部编辑器集成

• 快速打开：项目右上角点击编辑器图标，可以直接用默认编辑器打开项目代码。
• 兼容范围：自动识别本机已安装的开发工具，如 VS Code、Cursor、IntelliJ IDEA 等。
• 设置默认编辑器：左下角「设置」→「常规」→「默认打开目标」，可以选择默认的打开程序。

7.3 方案一：Git + 分叉功能实现版本回滚

通过 Git 版本管理配合 Codex 的「对话分叉」功能，可以实现对话历史与代码版本的双重回滚。

7.3.1 初始化 Git 仓库

在对话中发送指令：

把项目初始化成一个 git 工程，注意排除不需要的文件

Codex 会自动完成：

• 创建 .gitignore 文件，排除依赖目录、构建产物、环境变量、IDE 配置等不需要入库的文件。
• 执行 git init 初始化仓库。
• 完成初始提交。

7.3.2 推送代码到远程仓库（Gitee 示例）

• 在 Gitee 创建空仓库，复制仓库 HTTPS 地址。
• 在 Codex 中发送指令：将当前项目推送到 Gitee 上。
• 当 Codex 提示需要仓库地址时，粘贴复制的仓库地址，Codex 会自动配置远程仓库并完成推送。
• 后续代码修改后，发送 提交代码到 gitee 即可自动完成提交与推送。

7.3.3 对话分叉（派生）

• 作用：回滚对话历史，从某个历史节点派生出新的对话分支，不影响原有对话。
• 操作：点击历史消息下方的「分叉」按钮，选择「派生到本地」，即可生成一个新的对话窗口，继承该节点之前的所有上下文。
• 注意：分叉仅回滚对话历史，不会自动回滚代码文件。

7.3.4 代码版本回滚

• 在 VS Code 的源代码管理面板，找到目标版本的提交，复制提交哈希（Commit Hash）。
• 在 Codex 中发送指令：把代码回退到 [提交哈希]。
• Codex 执行代码回滚后，可以发送 仓库与本地保持一致，将回滚后的版本同步推送到远程仓库。

7.4 方案二：Git Worktree 并行开发

7.4.1 工作树原理

Git Worktree 本质是利用 Git 创建新分支，并将分支代码完整复制到一个新的文件夹中，这个新文件夹就是一个 Worktree。

• 优势：主文件夹与分支文件夹可以并行工作，各自修改代码互不干扰，完成后可以轻松合并到主分支。
• 适用场景：同时进行多个功能开发、多任务并行修改。

7.4.2 创建永久工作树

在左侧项目栏右键点击项目，选择「创建永久工作树」，可以创建多个工作树分支，分别对应不同的开发任务。

7.4.3 并行修改与合并

• 在不同工作树中开启独立对话，同时执行不同的修改任务。
• 任务完成后，在对应工作树的对话中发送 合并到主分支，Codex 会自动完成分支合并。
• 合并完成后，可以右键移除不再需要的工作树分支。

八、记忆系统

8.1 背景与价值

开启新对话意味着进入全新上下文，AI 会丢失之前的项目记忆与交互历史。项目复杂后，每次重新描述背景、让 AI 重读代码非常低效。记忆系统的作用是让 AI 在新对话中也能保留项目认知、用户偏好与工作约定，大幅减少重复沟通成本。

8.2 方案一：项目级 AGENTS.md

8.2.1 生效方式

在项目根目录创建 AGENTS.md 文件，Codex 会自动读取该文件内容，并将其作为上下文带入所有当前项目下的对话。

• 仅对当前项目生效，不同项目可配置不同的规则。
• 如果读取不生效，重启 Codex 即可。

8.2.2 自动生成 AGENTS.md

手动编写成本较高，可以通过指令让 Codex 自动生成：

通读当前项目，把你学到的关于项目的信息保存到 AGENTS.md 文件里。用中文，格式要清晰。

生成内容通常包含：用户使用习惯、代码规范、测试命令、构建命令、禁止触碰的文件、依赖与脚本说明等。

8.2.3 编写规范

适合写入的内容：

• 项目使用的包管理器、测试命令、构建命令。
• 修改代码后必须执行的验证步骤。
• 禁止触碰的目录、密钥文件、生成文件或外部系统。
• 团队约定的代码风格、提交前检查规则。
• 不同目录的特殊执行规则。

不适合写入的内容：

• 大段产品背景、历史会议纪要。
• 完整 API 文档、频繁变动的任务列表。
• 密钥、账号、Token 等敏感凭证。
• 可通过命令自动发现的信息（如完整文件树）。

8.3 方案二：全局自定义指令

8.3.1 设置路径

设置路径：左下角「设置」→「常规」→「全局自定义指令」。

8.3.2 特点

与项目级 AGENTS.md 不同，全局自定义指令对所有项目生效，适合放置通用偏好与工作约定，例如：

• 修改 JS 文件后必须运行 npm test。
• 安装依赖优先使用 pnpm。
• 添加新的生产依赖前先询问确认。

8.3.3 文件位置

设置项背后的配置文件通常位于 ~/.codex/ 目录下，可以手动编辑或备份，便于跨设备同步。

九、插件与自动化

9.1 插件系统

9.1.1 插件概念

Codex 支持通过插件扩展能力，连接第三方服务（如 GitHub、Gmail、Notion 等），让 AI 可以在对话中直接调用外部工具。

9.1.2 安装与授权

• 点击左侧「插件」进入插件市场。
• 找到目标插件，点击「+」安装。
• 第三方服务插件（如 GitHub、Gmail）需要登录对应账号进行授权后才可使用。

9.1.3 示例：GitHub + Gmail 插件联动

场景：自动获取 GitHub 热门项目并通过邮件发送报告。

• 安装 GitHub 插件与 Gmail 插件并完成授权。
• 对话中输入指令：/github 给我看一下本周关于 AI Agent 一个月内 star 数前 10 的开源项目，然后通过 Gmail 发送给我。
• Codex 会自动调用 GitHub 插件检索数据，整理成榜单后调用 Gmail 插件发送到绑定邮箱。

9.2 自动化功能

9.2.1 自动化概念

Codex 支持创建定时自动化任务，让 AI 按周期自动执行固定的工作流，无需人工值守。

9.2.2 创建定时自动化

例如在对话中输入：

把上述任务做成自动化，每周五下午 5 点半，都发邮件给我

Codex 会自动把这条工作流保存为定时任务，按周期自动执行。

9.2.3 自动化管理

• 入口：左侧「自动化」面板，可以查看所有已创建的定时任务。
• 可编辑项：运行环境、所属项目、执行周期、模型版本、推理强度。
• 操作：支持立即运行测试、编辑修改、删除自动化任务。
• 优化建议：周期性重复任务建议选择成本较低的模型版本，节省额度。

十、Skills 技能系统

10.1 Skills 简介

Skills 是 Codex 提供的「技能包」机制，把一组预置指令、工具与最佳实践打包成一个可复用的能力，通过 / 命令调用。Skills 体系让 Codex 的能力可以根据场景灵活扩展，而无需修改主程序。

10.2 三种使用方式

10.2.1 官方 Skills

Codex 自带一批官方 Skills，覆盖常见开发场景。

示例：PDF Skill

• 功能：生成 PDF 文件。
• 使用方式：对话中输入 /PDF Skill 在当前目录下，给我创建一个 PDF，把我所有的对话历史都放进去。
• 效果：自动在项目目录生成包含对话历史的 PDF 文件，支持中文渲染与自动分页。

10.2.2 第三方 Skills

安装步骤：

• 下载第三方 Skill 压缩包并解压。
• 在项目根目录创建 .codex/skills 文件夹。
• 将解压后的 Skill 文件放入该目录。
• 重启 Codex 或重新加载项目后，即可在对话中通过 / 调用。

示例：归藏 PPT Skill

• 功能：生成精美 PPT，支持多种设计主题。
• 使用方式：/guizang-ppt-skill 根据以下材料生成 PPT：文化科技公司商业计划书，AI+赋能闭环生态服务平台……
• 输出：生成可交互的 HTML 格式 PPT，支持动画与多主题样式。

10.2.3 自定义 Skills

除了使用官方与第三方 Skills，还可以基于项目需求自定义 Skill，把团队内部的工作流沉淀为可复用的命令。Skill 文件通常放在项目的 .codex/skills 目录下，按照官方约定的格式编写即可。

10.3 管理入口

所有 Skills（官方 + 第三方 + 自定义）都可以在 Codex 的 Skills 管理面板统一查看、启用、停用与更新。建议在团队内部建立 Skills 共享机制，把高频工作流沉淀为团队级能力。

十一、MCP 模型上下文协议

11.1 MCP 概述

MCP（Model Context Protocol，模型上下文协议）是一个开放协议标准，让 AI 模型可以与外部工具、数据源、服务进行标准化通信。Codex 原生支持 MCP，相当于给 AI 装上了一个「万能接口」，可以接入任何遵循 MCP 规范的服务。

11.2 接入方式分类

Codex 支持两种 MCP 接入方式：

• STDIO 本地模式：本地运行 MCP 服务程序，通过标准输入输出通信。
• 流式 HTTP 远程模式：连接远程 MCP 服务，无需本地安装服务，配置更简单。

11.3 示例：接入 GitHub MCP

11.3.1 应用场景

通过 GitHub MCP，可以让 Codex 直接读取 GitHub 上的 Issue、PR、代码仓库等内容，无需手动复制粘贴。

11.3.2 远程模式配置步骤

• 点击左下角「设置」→「MCP 服务器」→「添加服务器」。
• 选择「流式 HTTP」模式。
• 填写服务器名称，例如 mcp_servers_github。
• 填写 URL：https://api.githubcopilot.com/mcp/。
• 填写 Bearer 令牌（GitHub Personal Access Token）。
• 保存配置，重启 Codex 后生效。

11.3.3 GitHub Token 申请

• 登录 GitHub，进入「Settings」→「Developer settings」→「Personal access tokens」。
• 创建新的经典 Token，设置过期时间，勾选需要的权限范围。
• 生成后复制 Token，填入 Codex 配置中即可。

11.3.4 功能验证

配置完成后，可以用一条指令验证 MCP 是否生效，例如：

使用 github 的 MCP 帮我看一下我 github 项目最近的 5 个 Issue，按优先级排序

如果 Codex 正确返回了 Issue 列表，说明 MCP 已经成功接入。