快速摘要
OpenAI Codex 是当前最值得关注的 AI 编程工具之一，它不仅仅是代码补全，而是一个能独立执行任务、自动测试、全链路重构的编程 Agent。 本文将从 Codex 的安装配置讲起，深入拆解 AGENTS.md 规范文件的编写方法、MCP 服务的开发与集成、Skill 技能包的搭建流程，并通过两个真实项目——旅游攻略网站开发和企业级管理系统重构——带你掌握 Codex 在实际工程中的全流程操作。往下看有更详细的拆解，每一步都配有操作命令和原理说明。
莫潇羽@源码七号站（www.fuyuan7.com）在实际使用 Codex 数月后，整理出这篇覆盖安装、配置、技巧、MCP 开发、Skill 搭建到项目实战的完整指南。无论你是有经验的开发者还是想借助 AI 工具提效的技术爱好者，这篇文章都能帮你快速上手并在企业级场景中真正用起来。
一、Codex 到底是什么？为什么说它"不只是编程工具"
Codex 是 OpenAI 官方推出的 AI 编程 Agent。如果你之前用过 Claude Code、Cursor 或 Copilot 这类工具，那对 Codex 的定位应该不会陌生。但 Codex 有几个关键差异让它在企业级场景中更值得关注。
首先，Codex 背后的模型是 GPT 系列专门针对代码任务优化的版本。从最初的 codex-1 到后来的 GPT-5-Codex，再到现在的 GPT-5.3-Codex 以及最新的 GPT-5.4，每一代模型都在代码生成、仓库级推理、自动化测试等方面做了深度训练。据 OpenAI 官方数据，GPT-5-Codex 发布后三周内就处理了超过 40 万亿个 Token，OpenAI 内部几乎所有工程师都在日常工作中使用 Codex，每周合并的 Pull Request 数量提升了 70%。
其次，Codex 是完全开源的（Apache 2.0 协议），其核心代码库 codex-rs 已用 Rust 重写，在 GitHub 上拥有超过 6.7 万颗 Star、9000 多个 Fork，社区活跃度非常高。这意味着你可以审计它的代码，可以为它贡献功能，也可以在企业内部二次开发。
第三，Codex 原生支持外接模型。你不想用 GPT 官方模型？没问题，直接通过 OpenRouter 或 Ollama 切换到任意兼容模型即可，包括 DeepSeek 这样的开源模型做私有化部署也完全可行。这一点让 Codex 在国内企业级应用中具备了更大的灵活性。
最后也是最重要的一点：Codex 不只是一个"帮你写代码"的工具，它是一个能理解项目上下文、执行 Shell 命令、运行测试、自动修复 Bug 的编程 Agent。它可以在沙箱环境中独立工作数小时，迭代实现、修复测试失败，直到交付一个可用的实现方案。
二、Codex 的四种使用形态
在正式开始安装之前，你需要先了解 Codex 提供的四种使用方式，根据自己的工作场景选择最合适的那一种。
第一种：CLI 命令行版本。 这是使用最广泛也最灵活的方式，所有操作系统都支持。通过 npm i -g @openai/codex 一行命令安装，然后在终端输入 codex 就能进入交互界面。CLI 版本的优势在于轻量、快速，配合 Shell 脚本可以实现很多自动化操作。对于习惯命令行工作流的开发者来说，这是首选。
第二种：IDE 插件版本。 如果你日常使用 VS Code、Cursor、Trae 或其他基于 VS Code 内核的编辑器，可以直接在扩展市场搜索 Codex 插件进行安装。安装完成后，编辑器侧边栏会出现一个 Codex 的对话窗口，你可以在这里和 Codex 对话、引用文件、查看修改日志。IDE 插件的好处是文件引用和代码高亮更直观，日志输出也更详细。
第三种：桌面客户端。 OpenAI 在 2026 年 3 月发布了 Codex 桌面应用，目前 Windows 和 macOS 均已支持。客户端以"线程"（Thread）的概念管理对话，每个线程相当于一个独立的工作会话。它的界面设计非常简洁，支持多 Agent 并行工作。客户端会自动同步 CLI 和 IDE 插件的会话历史和配置，所以你可以在不同终端之间无缝切换。
第四种：Cloud 云端版本。 这是一个云端的 Agent 服务，任务在隔离的容器中运行，适合并行处理多个后台任务。Cloud 版本包含在 ChatGPT Plus、Pro、Business、Enterprise 等订阅计划中。它的特点是不占用本地机器资源，支持长时间运行的复杂任务。
以上四种形态并不互斥。实际工作中，很多开发者会采用混合模式：用 CLI 做快速的本地迭代，用 Cloud 处理耗时较长的跨仓库重构，用桌面客户端管理多个并行任务。
三、安装与环境配置：一步步跑通 Codex
3.1 安装 Node.js 环境
Codex CLI 依赖 Node.js 运行时。如果你还没有安装 Node.js，前往官网 https://nodejs.org 下载对应操作系统的安装包，选择 LTS（长期支持）版本即可。安装完成后，打开终端验证：
node -v # 应显示版本号，如 v20.x.x
npm -v # 应显示 npm 版本号看到版本号输出就说明环境准备好了。
3.2 安装 Codex CLI
环境就绪后，执行一行命令完成安装：
npm i -g @openai/codex如果下载速度较慢，可以先将 npm 的镜像源切换到国内加速源：
npm config set registry https://registry.npmmirror.com切换后再执行安装命令，速度会快很多。整个安装过程通常在一两分钟内完成。
macOS 用户还可以通过 Homebrew 安装：
brew install --cask codex3.3 IDE 插件安装
打开 VS Code 或 Cursor，进入扩展（Extensions）面板，搜索 "Codex"，找到 OpenAI 官方的 Codex 插件，点击"安装"即可。安装完成后，左侧边栏会出现 Codex 的图标，点击即可打开对话窗口。
3.4 桌面客户端安装
前往 Codex 官方页面下载对应平台的安装包。Windows 版本会跳转到 Microsoft Store 下载，macOS 版本可以直接从官网获取 DMG 安装包。安装完成后打开客户端，界面非常简洁——一个输入框、一个"New Thread"按钮，就是全部了。
四、登录授权：三种方式各有适用场景
安装完成后，第一次运行 codex 命令会提示你选择授权方式。这是使用 Codex 前最关键的一步。
4.1 ChatGPT 订阅授权
如果你已经开通了 ChatGPT Plus、Pro、Business 或 Enterprise 等订阅计划，这是最省事的方式。Codex 会自动跳转浏览器完成 OAuth 认证，认证成功后所有功能直接可用。
4.2 API Key 授权（推荐）
对于个人开发者来说，使用 API Key 是性价比最高的方案。你需要在 OpenAI 官方平台（https://platform.openai.com）创建一个 API Key，然后通过环境变量注入：
Windows（CMD）：
set OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxmacOS / Linux：
export OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx如果你使用的是第三方兼容 API 服务，还需要额外设置 Base URL：
export OPENAI_BASE_URL=https://your-proxy-api.com/v1要让环境变量永久生效，可以将上面的 export 语句写入 ~/.zshrc 或 ~/.bashrc 文件中，然后执行 source ~/.zshrc 使其生效。
4.3 设备一次性授权
这种方式适合在没有浏览器的远程服务器上使用。你可以先在本地完成授权，然后将授权文件 ~/.codex/auth.json 复制到服务器的对应位置，服务器端就能直接使用 Codex 了——这个设计思路非常贴心。
4.4 授权信息管理
所有授权信息保存在 ~/.codex/auth.json 文件中。如果你需要切换授权方式（比如从订阅切换到 API Key），只需删除这个文件，重新执行 codex 命令即可重新选择。
五、沙箱环境与安全策略
第一次使用 Codex 时，系统会提示你选择沙箱（Sandbox）策略。这个设置直接关系到 Codex 能对你的本地文件系统做哪些操作，是安全使用 Codex 的基础。
Codex 提供三种权限模式：
Suggest（只读模式）： Codex 只能读取文件和分析代码，不能执行任何命令，也不能修改文件。适合纯分析场景，比如让 Codex 帮你审查代码质量、解读一段不熟悉的逻辑。
Auto Edit（默认推荐模式）： Codex 可以读取和编辑文件，但在执行 Shell 命令前会请求你的确认。这是平衡安全性和效率的最佳选择，也是莫潇羽@源码七号站在日常开发中使用最多的模式。
Full Auto（完全自动模式）： Codex 拥有完整权限，可以自动执行所有操作而无需确认。效率最高但风险也最大，建议只在你非常信任当前任务且代码已有 Git 版本管理的情况下使用。
选择默认的沙箱模式后，Codex 会花几分钟时间初始化沙箱环境。耐心等待即可，初始化完成后就能正常使用了。
沙箱的核心原理是文件系统隔离和网络访问控制。Codex 的命令执行发生在一个受限的环境中（Linux 上使用 Landlock，macOS 上使用 Seatbelt），即使 AI 生成了错误的命令，也不会对你的系统造成不可逆的影响。
六、模型选择与切换
Codex 支持多种模型，不同模型适合不同场景。理解模型选择的逻辑，能帮你在质量和成本之间找到最优解。
6.1 当前主力模型
根据 OpenAI 开发者文档，当前推荐的模型配置如下：
gpt-5.4 是 OpenAI 最新的旗舰模型，集成了 GPT-5.3-Codex 的编程能力，同时具备更强的推理、工具使用和 Agent 工作流能力。官方推荐大部分任务首选这个模型。
gpt-5.3-codex 是专门为
