Codex 企业级应用实战：从零搭建到项目落地的完整操作手册

快速摘要
OpenAI Codex 是当前最值得关注的 AI 编程工具之一，它不仅仅是代码补全，而是一个能独立执行任务、自动测试、全链路重构的编程 Agent。 本文将从 Codex 的安装配置讲起，深入拆解 AGENTS.md 规范文件的编写方法、MCP 服务的开发与集成、Skill 技能包的搭建流程，并通过两个真实项目——旅游攻略网站开发和企业级管理系统重构——带你掌握 Codex 在实际工程中的全流程操作。 往下看有更详细的拆解，每一步都配有操作命令和原理说明。

---

莫潇羽在实际使用 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 codex

3.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-xxxxxxxxxxxxxxxxxxxx

macOS / 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 是专门为代码任务优化训练的模型。它在 SWE-bench Verified 等编程评测上表现优异，特别擅长大规模重构、完整项目构建、Bug 调试这类复杂的工程任务。如果你的工作以代码开发为主，这个模型是最佳选择。

gpt-5.4-mini 是快速轻量版本，适合简单的编码任务和子 Agent 调用，响应速度更快，成本更低。

6.2 推理等级

除了模型选择，Codex 还提供推理等级（Reasoning Effort）的调整：

• Low（快速响应）： 推理时间短，适合简单明确的任务，Token 消耗最少
• Medium（平衡模式）： 兼顾速度和质量，日常开发推荐使用
• High（深度推理）： 推理时间长但质量最高，适合复杂的架构设计和多文件重构

6.3 在 Codex 中切换模型

进入 Codex 交互界面后，输入 /model 命令即可查看和切换当前使用的模型。你也可以在配置文件 ~/.codex/config.toml 中设定默认模型：

model = "gpt-5.3-codex"

在 IDE 插件中，输入框下方有一个模型选择器，直接下拉切换即可。

---

七、AGENTS.md：给 AI 写一本"项目说明书"

AGENTS.md 是 Codex 生态中非常重要的一个概念。简单来说，它是一份放在项目中的 Markdown 文件，告诉 Codex 这个项目的技术栈是什么、代码规范是怎样的、测试命令怎么跑、目录结构如何组织。有了这份"说明书"，Codex 生成的代码质量会显著提升，随机性大幅降低。

7.1 AGENTS.md 的放置位置

AGENTS.md 支持三个层级的配置，优先级从高到低：

全局配置（~/.codex/AGENTS.md）：对所有项目生效，适合放置通用的编码风格和个人偏好。

项目配置（项目根目录下的 AGENTS.md）：针对特定项目生效，这是最常用的方式。一个前端项目的 AGENTS.md 和一个 Java 后端项目的 AGENTS.md 内容完全不同。

子目录配置（项目子目录下的 AGENTS.md）：当一个项目包含多种技术栈（比如前端用 React、后端用 Python、脚本用 Go），可以在各子目录分别放置 AGENTS.md，实现模块化的规范管理。

7.2 自动生成 AGENTS.md

Codex 提供了一个便捷的初始化命令。切换到项目目录后执行：

codex init

Codex 会自动分析项目结构、识别技术栈、读取 package.json 或 pom.xml 等配置文件，然后生成一份量身定制的 AGENTS.md。对于一个 Vue 3 前端项目，生成的 AGENTS.md 会包含组件目录结构、构建命令（npm run dev、npm run build）、代码风格约定（ESLint 配置）、测试规范等内容。

如果生成的内容是英文的，你可以直接在 Codex 对话中说"帮我把 AGENTS.md 的内容调整为中文"，它会自动翻译并保留语义完整性。

7.3 一份高质量 AGENTS.md 应该包含什么

根据实际项目经验，一份好的 AGENTS.md 通常涵盖以下几个方面：

项目概览： 简要说明项目是什么、用了哪些核心技术栈。比如"本项目是一个基于 Vue 3 + TypeScript + Vite 的电商后台管理系统，后端通过 RESTful API 与 Spring Boot 服务通信。"这段话虽然简短，但能帮助 Codex 快速建立对项目的全局认知。

目录结构说明： 列出关键目录的用途。比如 src/components/ 存放公共组件、src/views/ 存放页面级组件、src/api/ 存放接口请求封装、src/store/ 存放状态管理。Codex 在生成新文件时会参考这个结构，把文件放到正确的位置。

构建与运行命令： 明确告诉 Codex 用什么命令安装依赖（pnpm install）、启动开发服务（pnpm dev）、构建生产版本（pnpm build）、运行测试（pnpm test）。这些命令看似简单，但不同项目用的包管理器不同（npm、yarn、pnpm），构建工具也不同（Webpack、Vite、Rollup），如果 Codex 猜错了就会出问题。

代码规范： 包括缩进风格（2 空格还是 4 空格）、引号偏好（单引号还是双引号）、分号使用、命名规则（camelCase、kebab-case）、组件编写风格（Composition API 还是 Options API）等。如果项目配置了 ESLint 或 Prettier，在 AGENTS.md 中指出对应的配置文件路径即可。

Git 提交规范： 如果团队有统一的 Commit Message 格式（比如 Conventional Commits 规范），也应该写在 AGENTS.md 中。这样 Codex 在帮你提交代码时会自动生成符合规范的提交信息。

注意事项与禁忌： 比如"不要直接修改 node_modules 中的任何文件"、"所有 API 请求必须通过 src/api/ 目录下的封装函数发起，不要在组件中直接使用 axios"、"数据库迁移必须通过 Flyway 脚本，不要手动执行 DDL"。这些"不要做什么"的约束往往比"要做什么"更重要。

7.4 AGENTS.md 的实际效果

没有 AGENTS.md 的时候，Codex 生成代码的风格和结构具有较强随机性。有了 AGENTS.md，就像给 AI 配备了一本"项目手册"——它会严格按照你定义的规范来生成代码、选择目录结构、使用特定的 API 风格。这一点在团队协作中尤其重要，能确保多人使用 Codex 时产出风格一致的代码。

从 Codex 的底层原理来看，AGENTS.md 的内容会被注入到模型的上下文中，作为 developer 角色的消息存在。模型在生成每一段代码时都会参考这些指令。根据 OpenAI 公开的 Codex Agent 循环机制文档，AGENTS.md 的内容加载遵循从项目根目录到当前工作目录的层级扫描规则，总大小默认限制在 32KB 以内。所以 AGENTS.md 要写得精炼有效，避免无关内容占用宝贵的上下文空间。

---

八、常用命令与实用技巧

掌握以下命令和技巧，能让你的 Codex 使用效率翻倍。

8.1 交互式 vs 非交互式

交互式模式是直接运行 codex 进入终端 UI，在对话框中和 Codex 持续交流。适合探索性开发、需要多轮迭代的场景。

非交互式模式（codex exec）则是一次性执行任务，适合批量处理或脚本调用：

codex exec "帮我写一个坦克大战的游戏开发需求文档，要求 500 字"

命令执行完毕后 Codex 自动退出，不会进入交互界面。这种方式特别适合集成到 CI/CD 管道中。

8.2 会话恢复

Codex 会自动保存每次对话的完整记录。如果中途退出了，可以通过以下方式找回：

codex resume           # 弹出会话选择列表
codex resume --last    # 直接恢复最近一次会话
codex resume <ID>      # 恢复指定 ID 的会话

会话 ID 保存在 ~/.codex/sessions/ 目录下，你也可以手动查找。

8.3 权限模式切换

在对话中输入 /mode 可以随时切换权限模式（Suggest / Auto Edit / Full Auto），无需退出重启。

8.4 上下文压缩

聊天时间长了之后，如果你发现 Codex 的回复质量在下降，可能是上下文窗口接近上限了。执行 /compact 命令可以压缩历史对话，释放上下文空间。当然，莫潇羽更推荐的做法是直接用 /clear 开启新对话，因为过长的上下文会分散模型的注意力。

8.5 文件引用（@ 功能）

在 Codex 对话中使用 @ 符号可以引用项目中的任何文件。比如你有一份英文的 README.md，想生成一个中文版本：

@README.md 参考这个文件，帮我生成一个 README_CN.md，内容翻译为中文

Codex 会读取被引用的文件内容，然后基于它来完成任务。这在代码分析、文件对比、内容转换等场景中非常实用。

8.6 图片分析

Codex 支持图片输入。你可以将错误截图传给 Codex，让它分析报错原因并给出修复方案：

codex -i screenshot.png "分析这张报错截图，帮我解决这个问题"

这意味着你不再需要手动从截图中复制错误信息——直接丢给 Codex，让它自己识别和处理。

8.7 联网搜索

默认情况下 Codex 不会联网。如果你需要它获取实时信息（比如查询某个 API 的最新文档），可以使用 --search 参数或在对话中触发 Web Search 功能：

codex --search "查一下今天北京的天气"

8.8 换行输入

在 CLI 的输入框中，按回车键会直接发送消息。如果需要输入多行内容，使用 Shift + Enter 换行。在 IDE 插件和桌面客户端中则不存在这个问题，可以自由换行。

8.9 查看 Token 消耗

输入 /status 可以查看当前会话的 Token 消耗量、使用的模型、API 配置、项目目录等信息，方便你监控使用量。

---

九、MCP 服务的开发与集成

MCP（Model Context Protocol，模型上下文协议）是大模型生态中一个非常重要的标准。它的作用类似于 USB 接口之于电脑——只要你的服务实现了 MCP 协议，就能被任何支持 MCP 的 AI 工具调用。Codex 原生支持 MCP，这让它具备了无限的扩展能力。

9.1 MCP 是什么？解决了什么问题？

在 MCP 出现之前，每个 AI 工具想要调用外部服务，都需要单独做适配。MCP 统一了这个接口标准：你只需要开发一个 MCP Server，就能让 Codex、Claude Code、Cursor 等所有支持 MCP 的工具都能调用它。

MCP 的通信方式有两种：一种是 STDIO（标准输入输出），通过命令行进程通信，适合本地开发；另一种是 HTTP（SSE），基于 HTTP 协议通信，适合企业级部署和远程调用。

9.2 用 Codex 开发一个 MCP 服务

最直接的方式是让 Codex 自己帮你开发 MCP 服务。比如你需要一个"内容截取"的 MCP 服务，功能是不管传入多长的文本，都按照指定参数进行截取：

帮我实现一个内容截取的 MCP 服务。这个服务功能是：不管传入文本有多长，都按照指定参数进行截取。MCP 服务开发完后，请帮我在 Codex 中配置好。

Codex 会自动完成以下步骤：

• 在项目目录下创建 MCP 服务的代码文件（通常是一个 Python 脚本）
• 基于 FastMCP 框架搭建服务实例
• 定义工具函数，包括参数描述和返回值
• 自动将服务配置写入 ~/.codex/config.toml 的 MCP 部分
• 提示你重启 Codex 会话以加载新服务

生成的 MCP 服务代码结构大致如下：

from fastmcp import FastMCP

server = FastMCP("content-truncate-mcp")

@server.tool()
def truncate_content(content: str, max_length: int) -> str:
    """截取文本内容到指定长度"""
    return content[:max_length]

if __name__ == "__main__":
    server.run()

9.3 配置和使用 MCP 服务

MCP 服务的配置存储在 ~/.codex/config.toml 中。你也可以在 IDE 插件的设置面板中查看和管理已配置的 MCP 服务。配置完成后，在 Codex 对话中使用 /mcp 命令可以查看当前已启动的 MCP 服务列表。

调用 MCP 服务时，直接用自然语言描述即可：

调用 content-truncate-mcp 处理以下文本："今天天气很好，我们去爬山吧"，保留前 6 个字

Codex 会自动识别应该调用哪个 MCP 工具，传入正确的参数，返回处理结果。

9.4 MCP 的企业级应用场景

在企业开发中，MCP 的价值非常大。你可以将公司内部的各种服务封装为 MCP Server：

• 地图查询服务：传入地名，返回经纬度和周边信息
• 天气查询服务：传入城市，返回实时天气数据
• 代码分析服务：传入代码片段，返回圈复杂度、安全漏洞等分析结果
• 数据库查询服务：传入 SQL 或自然语言描述，返回查询结果
• 文档管理服务：自动上传生成的文件到公司云存储

这些服务一旦封装为 MCP，所有团队成员的 Codex 都能直接调用，实现能力共享和标准化。

9.5 MCP 的配置细节

MCP 服务在 config.toml 中的配置格式如下：

[mcp_servers.my-service]
command = "python"
args = ["/path/to/my_mcp_server.py"]
enabled = true

其中 command 是启动 MCP 服务的命令，args 是传入的参数（通常是脚本路径），enabled 控制是否启用。如果你有多个 MCP 服务，可以在 [mcp_servers] 下添加多个子节点，每个子节点代表一个服务。

配置修改后需要重启 Codex 会话才能生效。在 IDE 插件中，你可以在设置面板中直观地查看和管理所有已配置的 MCP 服务，包括启用状态和启动命令。如果某个 MCP 服务启动失败，Codex 会在日志中给出错误提示，通常是路径错误或依赖缺失导致的。

对于企业级部署，建议将 MCP 服务容器化（Docker），通过 HTTP/SSE 方式提供服务，这样可以实现服务的集中管理和高可用部署。多个开发者共享同一组 MCP 服务，避免每个人本地都要维护一套。

---

十、Skill 技能包：让 Codex 拥有"组合技能"

Skill 是 Codex 生态中另一个核心概念。如果说 AGENTS.md 是项目级的规范说明，那 Skill 就是可复用的能力插件——装上一个 Skill，Codex 就多了一项专长。

10.1 Skill 的本质

Skill 本质上是一个遵循 Agent Skills 开放标准的目录结构。这个标准由 Anthropic 最先提出，目前已被 OpenAI、Google、Cursor 等主流 AI 工具厂商广泛支持，真正实现了"一次编写，到处运行"。

一个标准的 Skill 目录结构如下：

my-skill/
├── SKILL.md          # 必需：技能指令和元数据
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档（知识库）
└── assets/           # 可选：模板、媒体资源

其中 SKILL.md 是唯一必需的文件，它的顶部包含 YAML 格式的元数据（name 和 description），下方是具体的指令内容。Codex 通过"渐进式披露"的方式加载 Skill：启动时只读取元数据，真正需要使用某个 Skill 时才加载完整指令，这样可以节省 Token 消耗。

10.2 SKILL.md 的编写要点

SKILL.md 的写法直接决定了技能能否被正确触发和高效执行。根据 Codex 官方的 skill-creator 技能中总结的最佳实践，写好 SKILL.md 需要把握几个核心原则。

description 是触发器。 Codex 在每次对话开始时都会扫描所有已安装 Skill 的元数据，靠 description 来判断"这个 Skill 和当前请求相关吗"。所以 description 必须精确描述这个 Skill 干什么、什么时候应该被触发、什么时候不应该被触发。一个好的 description 示例："用于会议纪要的智能生成。当用户提供会议对话内容或提到会议总结、会议纪要等关键词时触发。不适用于一般性的文章总结或摘要任务。"

指令要精炼。 Codex 的上下文窗口是所有 Skill 共享的。你的 Skill 占得越多，留给其他用途的就越少。官方建议 SKILL.md 的指令部分控制在 500 行以内。写指令之前问自己两个问题：AI 是不是已经知道这个了？（比如"Python 的 for 循环怎么写"——不需要教它）这段内容值不值得占用上下文空间？（一个好的代码示例往往胜过三段文字描述）

用示例代替解释。 与其花大段文字描述"输出格式应该是怎样的"，不如直接给出一个输入输出的示例。模型在理解示例方面比理解抽象描述要准确得多。

scripts 目录的妙用。 scripts 目录下的脚本在执行时不会被读入上下文窗口，这意味着零 Token 成本。所以如果某个操作比较复杂（比如文件格式转换、API 调用、数据处理），把它写成脚本放在 scripts 目录下，让 Codex 通过执行脚本来完成，而不是在 SKILL.md 中写一大段指令去教它怎么做。

10.3 实战：搭建一个会议纪要 Skill

莫潇羽以一个"会议纪要智能生成"的 Skill 为例，带你走一遍完整的搭建流程。

第一步：创建目录结构。

在项目根目录下创建以下结构：

.codex/
└── skills/
    └── meeting/
        ├── SKILL.md
        ├── scripts/
        │   └── upload.py
        └── references/
            └── finance-handbook.md

注意 .codex/skills/ 这个路径是 Codex 的官方规范，Codex 会自动扫描这个目录下的所有 Skill。

第二步：编写 SKILL.md。

---
name: meeting-summary
description: >-
  用于会议纪要的智能生成和文档自动同步。当用户提供会议对话内容或
  提到"会议总结"、"会议纪要"等关键词时，自动触发此技能。
---

# 会议总结助手

## 总结规则

作为会议总结助手，按照以下维度对会议内容进行提炼：

- 参会人员：列出所有参与讨论的人员
- 议题：本次会议讨论的核心话题
- 决定：会议达成的具体决议
- 待办事项：需要后续跟进的行动项

## 财务提醒

当会议内容涉及预算、采购、成本等财务关键词时，
自动参考 references/finance-handbook.md 中的公司财务制度，
给出合规性提醒。

## 文档同步

总结生成后，调用 scripts/upload.py 将会议纪要
上传到公司文档服务器。

第三步：编写知识库文件。

在 references/finance-handbook.md 中放入公司财务制度的相关内容，比如采购审批流程、预算上限条款、报销规范等。Codex 在处理涉及财务的会议内容时，会自动参考这份文件给出合规性提醒。

第四步：编写脚本。

在 scripts/upload.py 中实现文件上传的逻辑。Skill 中的脚本是真正被执行的程序，它弥补了大模型只能做"内容生成"的局限性——当你需要调用接口、上传文件、操作数据库时，脚本就派上用场了。

10.4 Skill 的调用方式

Skill 的调用分为两种：

显式调用： 在对话中直接提到 Skill 名称或使用 $ 符号引用：

请使用 $meeting-summary，帮我总结以下会议内容：
张经理：这次活动预算控制在 8 万以内...

隐式调用： 当你的对话内容匹配了 Skill 的 description，Codex 会自动触发对应的 Skill。比如你说"帮我总结一下刚才的会议"，Codex 识别到"会议总结"这个关键词，就会自动加载 meeting-summary Skill。

10.5 用官方工具创建 Skill

Codex 内置了一个 $skill-creator 技能，可以通过对话引导你创建新的 Skill：

/skills create 创建一个计算器 Skill，用于计算加减乘除表达式

Codex 会自动按照规范生成 SKILL.md 和相关文件。创建完成后，重启 Codex 会话即可加载新 Skill。

10.6 Skill 的存储位置

Skill 可以放在以下任何位置：

• 项目级（.codex/skills/）：只在当前项目中生效
• 用户级（~/.codex/skills/）：对当前用户的所有项目生效
• 系统级：Codex 内置的官方 Skill

高优先级的 Skill 会覆盖同名的低优先级 Skill，方便你在项目中自定义覆盖全局配置。

---

十一、项目实战一：从零开发旅游攻略网站

理论讲了这么多，接下来通过一个真实项目把所有知识串起来。我们要用 Codex 从零开发一个旅游攻略网站，包含景点展示、筛选、详情页等功能。

11.1 准备工作：配置 GitHub

首先确保你安装了 GitHub CLI（gh 命令）并完成了认证：

# 安装 gh 命令（macOS）
brew install gh

# 登录认证
gh auth login

认证过程中 gh 会自动跳转浏览器完成 OAuth 授权，非常简单。

11.2 创建项目仓库

在 Codex 中直接通过对话创建 GitHub 项目：

使用 gh 命令创建一个名为 trip-guide 的 GitHub 项目，
包含一个 README.md，然后把项目推送到 GitHub

Codex 会依次执行：创建本地项目目录、初始化 Git 仓库、通过 gh repo create 创建远程仓库、推送初始代码。整个过程全自动。

11.3 生成需求文档

接下来让 Codex 帮你规划需求：

参考旅游攻略网站的通用功能，帮我输出一份完整的需求文档。
要求包含：中国十大热门景点数据与攻略内容、景点卡片展示、
地区和人群筛选、景点详情页（包含出行时间、到达方式等信息）、
用户登录注册功能。将需求文档保存到项目根目录。

Codex 不仅会生成功能需求，还会自动规划技术方案（前端框架选择、目录结构设计、路由规划等），输出一份非常详尽的需求文档。

11.4 一键开发

有了需求文档后，一句话启动开发：

参考需求文档进行网站开发，使用 Vue 3 + Vite 技术栈，
端口设置为 8082

Codex 会开始执行一系列操作：初始化 Vue 3 项目、安装依赖、创建页面组件、编写路由配置、填充景点数据、编写样式。整个过程可能需要几分钟到十几分钟，取决于需求复杂度。

开发完成后，Codex 会自动启动开发服务器，并且自主测试——它会检查服务是否成功启动、页面是否正常渲染，发现问题后还会自动修复。这是 Codex 区别于早期 AI 编程工具的关键能力：它具备了自动化测试和自我修正的闭环。

11.5 迭代修复

第一次生成的页面可能不完美。比如有些景点的图片加载不出来，你只需要用自然语言描述问题：

成都大熊猫繁育研究基地和杭州西湖的景点图片加载不出来，
帮我解决这个问题

Codex 会自动定位问题（比如图片链接返回 404）、寻找替代方案、修改代码、重新测试。你不需要知道代码在哪个文件的哪一行——Codex 会自己搞定。

这里有一个非常关键的能力需要强调：Codex 具备自动化验证的闭环机制。当它修改了图片链接后，会主动检查新链接是否有效、页面是否正常渲染。如果验证失败，它会继续尝试其他方案，直到问题真正解决。这种"生成-验证-修正"的循环是 Codex 与早期 AI 编程工具最根本的区别。早期工具只管生成代码，至于能不能跑、效果对不对，完全靠人工检查。而 Codex 会自己当"QA 工程师"，在交付给你之前先把关一遍。

在实际开发过程中，莫潇羽建议你养成以下工作节奏：让 Codex 先完成整体框架 → 人工检查页面效果 → 列出所有问题一次性反馈给 Codex → Codex 批量修复 → 再次检查。避免发现一个问题就修一个问题的碎片化方式，因为批量处理时 Codex 能更好地理解修改之间的关联性。

11.6 善用 AGENTS.md 提升项目质量

在开发过程中，别忘了让 Codex 为你生成 AGENTS.md。项目创建完成后执行 codex init，生成的规范文件会包含 Vue 3 的目录结构说明、组件编写规范、状态管理规则、CSS 命名约定等。后续每次修改代码时，Codex 都会参考这份规范，确保新代码和已有代码保持一致的风格。

如果你对生成的规范不满意，可以直接编辑 AGENTS.md 添加自己的要求。比如"所有组件必须使用 <script setup> 语法"、"样式使用 scoped CSS，禁止全局样式污染"、"接口请求统一在 src/api/ 目录下封装，组件内不允许直接调用 fetch 或 axios"。这些约束会显著提升代码的可维护性。

11.7 推送部署

开发完成、测试通过后，一句话完成代码推送：

帮我把项目推送到 GitHub

从项目创建到功能开发再到代码推送，全程你没有手动编辑过一行代码，全部通过对话驱动。这就是 AI 编程 Agent 带来的效率革命。

---

十二、项目实战二：企业级管理系统重构

第二个项目更贴近企业实际场景——我们要对一个已有的管理后台系统进行功能重构，涉及前端页面修改、后端接口调整和数据库字段变更。

12.1 项目背景

我们以若依（RuoYi）为例，这是国内广泛使用的一套开源管理系统。前端基于 Vue，后端基于 Java Spring Boot，数据库使用 MySQL。它提供了用户管理、角色管理、菜单管理、部门管理等标准功能，很多企业基于它二次开发 OA 系统、ERP 系统等。

12.2 环境准备

重构之前需要先把项目跑起来：

• 安装 JDK 17，确保 java -version 能正常输出
• 安装并启动 MySQL 数据库，导入若依的初始化 SQL 脚本
• 安装并启动 Redis（默认端口 6379）
• 启动后端服务（Spring Boot 应用，默认端口 8080）
• 进入前端目录，执行 npm install 安装依赖，然后 npm run dev 启动前端开发服务器

两端都启动后，浏览器访问 http://localhost:80 就能看到登录页面了。

12.3 全链路重构实战

现在假设我们有两个重构需求：

需求一：修改页面标签——将用户管理页面中的"用户名称"标签修改为"用户昵称"。

这个需求很简单，但体现了 Codex 定位代码的能力。你不需要知道这个标签在哪个 Vue 文件的哪一行，只需要在 Codex 中这样说：

在若依 UI 的用户管理页面中，将"用户名称"这个 label 修改为"用户昵称"

Codex 会自动搜索项目文件、定位到对应的 Vue 组件、修改 label 文案，整个过程几秒钟完成。

需求二：新增数据库字段——在用户表中新增"家庭住址"字段，同时前后端都要支持这个字段的查询和编辑。

这是一个典型的全链路需求，涉及数据库、后端接口和前端页面的同步修改。把需求和表结构告诉 Codex：

用户表新增"家庭住址"（home_address）字段，varchar(200)。
用户管理页面也要增加这个字段的查询和编辑功能。
请帮我修改前端和后端代码，并生成数据库变更 SQL。
当前用户表结构如下：
[粘贴表结构]

Codex 会完成以下全部工作：

• 生成 ALTER TABLE SQL 语句，添加新字段
• 修改 Java 实体类，添加 homeAddress 属性
• 修改 MyBatis 的 Mapper XML，在查询和插入语句中加入新字段
• 修改前端 Vue 组件，在表单和列表中添加"家庭住址"的输入框和展示列
• 修改前端搜索条件，支持按家庭住址筛选
• 生成完整的数据库初始化脚本（确保新环境部署时也包含这个字段）

最关键的是，Codex 还会自动进行后端编译验证（确保新字段不会引入 Java 映射错误）和前端构建检查。你拿到的是一套经过初步验证的、可以直接使用的代码修改。

12.4 执行数据库变更

Codex 生成的 SQL 需要你手动在数据库中执行（出于安全考虑，数据库操作不应该让 AI 自动执行）。将 SQL 复制到数据库管理工具中执行后，重启前后端服务，刷新页面就能看到新增的"家庭住址"字段了——查询、编辑、筛选功能一应俱全。

整个重构过程，你没有手动改过一行代码，没有手动查找过一个文件。这就是 Codex 在企业级重构中的威力：它理解项目的完整上下文，能在前端、后端、数据库之间自动协调修改，并且带有自验证能力。

12.5 重构的正确姿势

通过这个实战案例，莫潇羽总结出几条企业级系统重构的实践经验：

需求描述要精确。 "帮我优化一下用户管理"这种模糊的需求，Codex 很难给出精确的实现。你需要具体到"在用户表中新增一个 varchar(200) 类型的 home_address 字段，前端用户管理页面的表单中增加家庭住址输入框，列表中增加家庭住址展示列，支持按家庭住址关键词模糊搜索"。需求越具体，结果越准确。

给 Codex 足够的上下文。 当你要求 Codex 修改数据库相关的功能时，把现有的表结构贴给它看；当你要求修改接口时，把接口文档或 Swagger 定义贴给它看。上下文越充分，Codex 就越不容易产生"幻觉"（编造不存在的字段或方法）。

分步骤推进复杂需求。 如果一次性提出太多修改需求，Codex 可能会在某些细节上出错。建议将大需求拆分成若干独立的小需求，每完成一个就验证一个。比如先做数据库字段的增删改，验证通过后再做后端接口的适配，最后做前端页面的调整。

Git 版本管理是安全网。 在让 Codex 做任何修改之前，确保当前代码已经提交到 Git。万一 Codex 的修改引入了问题，你可以随时 git checkout 回退到之前的状态。Codex 本身也支持 /diff 命令，可以查看当前会话中所有文件的修改差异。

保留原始文件备份。 对于企业级系统的重构，建议在 Codex 修改前先 Fork 一份分支。在分支上让 Codex 工作，确认没问题后再合并到主分支。这符合企业级开发的 GitFlow 工作流规范。

---

十三、进阶配置与调优

13.1 config.toml 详解

Codex 的所有配置都存储在 ~/.codex/config.toml 文件中。你可以在这里设置默认模型、API Key、MCP 服务、Skill 路径、网络参数等。以下是一些常用配置项：

# 默认模型
model = "gpt-5.3-codex"

# 推理等级：low / medium / high
reasoning_effort = "medium"

# 默认权限模式：suggest / auto-edit / full-auto
approval_mode = "auto-edit"

# 网络调优
[network]
max_retries = 3           # 请求最大重试次数
idle_timeout = 300        # 空闲超时时间（秒）

你也可以通过对话让 Codex 帮你修改配置，不需要手动编辑文件。

13.2 多 Profile 管理

如果你在不同项目中使用不同的模型或 API Key，可以通过 Profile 功能管理多套配置：

codex --profile work     # 使用 work 配置启动
codex --profile personal # 使用 personal 配置启动

不同 Profile 的配置互不干扰。

13.3 Ollama 本地模型支持

如果你希望完全本地化运行，不依赖任何云端 API，Codex 支持通过 Ollama 连接本地部署的开源模型：

codex --oss  # 使用本地 Ollama 模型

前提是你已经安装了 Ollama 并下载了模型（如 DeepSeek Coder、CodeLlama 等）。这种方式适合对数据安全要求极高的企业内部环境。

13.4 子 Agent（Subagent）工作流

Codex 支持子 Agent 工作流，允许你在一个主任务中并行派生多个子任务。比如你在重构一个大型项目时，可以让主 Agent 负责整体协调，同时派生子 Agent 分别处理前端组件重构、后端接口适配和数据库迁移脚本编写。

子 Agent 的配置在 config.toml 的 [agents] 部分。需要注意的是，每个子 Agent 都有独立的模型调用和工具执行，因此子 Agent 工作流会消耗更多 Token。Codex 不会自动发起子 Agent，只有你在对话中明确要求"并行处理"或"分开执行"时才会触发。

在桌面客户端中，子 Agent 的体验更加直观——你可以同时看到多个 Agent 的工作进度，每个 Agent 在独立的面板中运行，互不干扰。这种"多 Agent 协同"的模式在处理大规模项目时效率提升非常明显。

13.5 Hooks 系统

Codex 的 Hooks 系统允许你在特定事件发生时自动执行自定义操作。比如 user_prompt Hook 可以在用户输入发送给模型之前进行拦截或增强。企业团队可以利用这个机制实现审计日志记录（记录所有与 Codex 的交互内容）、策略合规检查（拦截不符合安全策略的操作请求）、上下文自动注入（自动在每次请求中附加团队规范信息）等功能。

Hooks 的设计让 Codex 不仅仅是一个开发者的个人工具，更可以成为企业工程化流程中的一个可控节点。

---

十四、Codex 与同类工具的对比思考

在 AI 编程工具领域，Codex 并非唯一的选择。Claude Code 是 Anthropic 推出的终端优先编程工具，在理解仓库全局上下文方面表现优异；Cursor 是将 AI 深度集成到编辑器中的代表；GitHub Copilot 则在自动补全领域拥有最大的用户基数。

根据莫潇羽的实际使用体验，这几个工具各有特点。Codex 在指令遵循方面做得比较好，生成的代码更倾向于精确执行你的要求，不会过度"自由发挥"。它的开源特性和灵活的模型切换能力在企业场景中也是明显的优势。Claude Code 在代码整体质量上可能略高一些，特别是在复杂架构设计方面。但具体到不同的项目、不同的需求，表现会有差异——大模型本身就存在一定的随机性。

从技术架构层面来看，这些工具的差异主要体现在三个维度。第一是模型能力，这决定了代码生成的质量上限。Codex 使用 GPT 系列模型，Claude Code 使用 Claude 系列模型，Cursor 支持多种模型切换。不同模型在不同编程语言和任务类型上各有优势，很难说谁"绝对最强"。第二是工具集成，即 Agent 能调用哪些工具来辅助编程。Codex 的沙箱机制、MCP 支持、Skill 系统在这方面做得比较完善。第三是用户体验，包括响应速度、界面设计、多终端协同等。Codex 提供了 CLI、IDE 插件、桌面客户端和云端服务四种形态，覆盖面最广。

最务实的建议是：不要纠结哪个工具"绝对最好"，关键是它能不能解决你的实际问题。如果它能帮你高质量地完成任务、提升效率，那对你来说就是最合适的工具。条件允许的话，建议多个工具结合使用，取各家之长。比如用 Codex 做项目级的重构和自动化任务，用 Cursor 做日常的编码和调试，这种组合方式在很多团队中已经成为常态。

14.1 关于 API 使用成本的说明

对于 API Key 方式使用 Codex 的开发者来说，了解不同模型的定价有助于控制成本。GPT-5 系列的 mini 版本 Token 价格非常低，适合任务明确、复杂度不高的场景。如果你要做复杂的推理和编程任务，就需要使用 GPT-5.3-Codex 或 GPT-5.4 这样的高端模型，Token 价格会相应提高。

在实际使用中，有几个降低成本的技巧：保持对话简洁，不要在一个会话中积累过多的历史消息；及时使用 /compact 或 /clear 管理上下文；对于简单任务使用 mini 模型；将推理等级设为 medium 而非 high。这些做法可以在不明显影响质量的前提下，显著降低 Token 消耗。

---

十五、写给入门者的几点建议

如果你是第一次接触 AI 编程工具，以下几点建议能帮你更快上手：

先把环境搞好。 CLI 安装 + API Key 配置是最基础的，确保 codex 命令能正常运行。然后再根据需要安装 IDE 插件或桌面客户端。环境配置看似简单，但很多人卡在网络问题上——如果 npm 下载慢就换源，如果 API 连接超时就检查网络代理设置。把这些基础设施问题先解决掉，后面的使用才会顺畅。

从小任务开始。 不要一上来就让 Codex 帮你做大型项目重构。先从简单的开始——写一个排序算法、生成一段 README、修改一个页面标签——建立起对 Codex 能力边界的直觉。你会发现它在某些任务上表现惊人，在某些任务上可能需要多轮引导。了解这些"脾气"之后，你才能更有效地使用它。

学会写好提示词。 Codex 的输出质量和你的输入质量直接相关。需求描述越清晰、越具体，生成的代码质量就越高。模糊的需求会得到模糊的结果。一个好的提示词应该包含：你要做什么（功能描述）、用什么技术做（技术栈约束）、有什么特殊要求（性能、兼容性等）。比如"帮我写一个 Node.js 脚本，读取 data.csv 文件中的销售数据，按月份汇总后生成柱状图，使用 Chart.js 库，输出为 HTML 文件"就比"帮我分析数据"好得多。

一定要 Review。 不管你是专业开发者还是零基础用户，AI 生成的代码都应该被检查。专业开发者可以直接审查代码质量；非专业用户至少要测试功能是否符合预期。你也可以让 Codex 自己做一遍 Code Review——输入"帮我检查一下刚才生成的代码有没有安全漏洞和性能问题"，它会给出相当专业的审查意见。

善用 AGENTS.md 和 Skill。 这两个机制是提升 Codex 输出质量的关键杠杆。花时间把项目规范和常用能力沉淀下来，后续每次使用都会受益。把它想象成你在培养一个新入职的同事——你给他的入职手册越详细，他上手就越快，犯错就越少。

中文完全可用。 虽然用英文提问的效果可能略好，但目前 Codex 对中文的理解准确性已经非常高，日常使用中文完全没问题。不过有一点需要注意：命令行环境有时候会出现中文乱码的情况，这通常是终端编码设置的问题（默认使用了 GBK 而非 UTF-8）。如果遇到乱码，可以在提示词中加一句"请确保使用 UTF-8 编码"，或者在系统层面将终端编码切换为 UTF-8。

养成看日志的习惯。 Codex 在执行每一步操作时都会输出详细的日志，包括它读取了哪些文件、执行了什么命令、做了什么判断。这些日志是你理解 Codex 工作逻辑的窗口。花时间看懂这些日志，你会对 AI 编程工具的工作原理建立起更深的理解，从而更好地引导它工作。

不要把 Codex 局限在编程场景。 虽然 Codex 的核心能力是写代码，但它同样可以帮你做本地文件管理、数据分析报告、Excel 处理、内容生成、PDF 解析等工作。它本质上是一个能执行命令、操作文件系统的 AI 助手，编程只是它能力的一个子集。

---

总结

Codex 从最初的代码补全工具，已经进化为一个完整的编程 Agent 平台。它能理解项目上下文、执行命令、运行测试、自动修复问题，并通过 AGENTS.md、MCP、Skill 等机制实现了高度的可定制化。在企业级应用中，Codex 真正的价值不在于替代开发者写代码，而在于将重复性的工程工作自动化，让开发者把精力集中在架构设计和业务逻辑上。

回顾本文的核心内容，我们走过了这样一条路线：从理解 Codex 的定位和四种使用形态，到完成安装、授权和沙箱配置；从掌握模型选择和常用命令，到深入 AGENTS.md 规范编写的最佳实践；从 MCP 服务的开发集成到 Skill 技能包的搭建流程；最后通过旅游攻略网站的从零开发和企业级管理系统的全链路重构，验证了所有知识点在实际项目中的应用。

如果你把文中提到的每个环节都实际操作一遍，你对 Codex 的掌握程度将远超大多数只停留在"试了试"阶段的使用者。AI 编程工具的学习曲线不陡峭，但需要你投入时间去实践、去踩坑、去摸索出适合自己的工作流。

本文由莫潇羽原创撰写，转载请注明出处。希望这篇深度指南能帮你在 Codex 的使用上少走弯路、快速上手。如果你在实践过程中遇到问题，欢迎来交流讨论。