1. 引言：Codex 是什么

Codex 是 OpenAI 推出的 AI 编程助手，它基于大语言模型，能够理解自然语言指令并直接操作代码仓库，完成代码编写、修改、调试、重构等任务。与传统的代码补全工具不同，Codex 更像一个「能听懂人话的结对程序员」，你可以用中文直接告诉它「帮我写一个用户登录接口」，它会自动读取项目结构、编写代码、运行测试，甚至帮你修复报错。

对于刚接触 Codex 的小白来说，最大的困惑往往不是「它能做什么」，而是「怎么把它跑起来」。本文将从零开始，手把手带你完成 Codex 的安装、配置、插件扩展、MCP 接入和 Skills 编写，每一步都配有可复制的实战代码。

2. 环境准备与安装

2.1 前置要求

在开始安装之前，请确认你的电脑满足以下条件：

• 操作系统：Windows 10/11、macOS 12+ 或主流 Linux 发行版。
• Node.js：版本 18.0 或更高（推荐使用 LTS 版本）。
• Git：用于代码仓库操作。
• OpenAI API Key：需要有效的 API 访问权限。

检查 Node.js 和 Git 是否已安装，可以在终端执行以下命令：

node -v
npm -v
git --version

如果提示「command not found」，请先到对应官网下载安装。

2.2 安装 Codex CLI

Codex 的官方命令行工具通过 npm 发布，安装命令非常简单：

npm install -g @openai/codex

安装完成后，验证是否成功：

codex --version

如果能看到版本号输出，说明安装成功。接下来需要配置 API Key：

codex login

按照提示粘贴你的 API Key 即可。也可以直接通过环境变量配置：

export OPENAI_API_KEY="sk-你的密钥"

在 Windows PowerShell 中，使用以下命令：

$env:OPENAI_API_KEY="sk-你的密钥"

2.3 首次运行测试

创建一个测试目录，并让 Codex 帮你写一个简单的 Python 脚本：

mkdir codex-test
cd codex-test
codex "写一个 Python 脚本，打印 1 到 10 的平方"

Codex 会自动创建文件并输出结果。如果一切正常，你会看到它生成的代码和运行日志。

3. 核心配置文件详解

3.1 配置文件位置

Codex 的全局配置文件位于用户主目录下：

~/.codex/config.toml

在 Windows 上路径为：

C:\Users\你的用户名\.codex\config.toml

如果文件不存在，可以手动创建。下面是一个最基础的配置示例：

# Codex 全局配置
model = "gpt-4o"
temperature = 0.2
max_tokens = 4096
[approval_policy]
auto: 自动执行所有命令
on_request: 每次请求用户确认
never: 从不自动执行
mode = "on_request"
[history]
enabled = true
max_messages = 100

3.2 项目级配置

除了全局配置，Codex 还支持在项目根目录创建 .codex/config.toml，实现项目级定制。项目配置会覆盖全局配置中的同名项：

# 项目级配置示例
model = "gpt-4o-mini"
[instructions]
项目专属指令，Codex 每次都会参考
project_context = """
这是一个电商后端项目，使用 Python FastAPI 框架。
数据库使用 PostgreSQL，ORM 使用 SQLAlchemy。
代码风格遵循 PEP 8。
"""

3.3 常用配置项速查表

配置项	说明	默认值
model	使用的模型名称	gpt-4o
temperature	采样温度，越低越保守	0.2
max_tokens	单次响应最大 token 数	4096
approval_policy.mode	命令执行审批策略	on_request
history.enabled	是否保存对话历史	true
history.max_messages	历史消息保留条数	100

4. 插件系统实战

4.1 插件机制原理

Codex 的插件系统允许你扩展它的能力。插件本质上是一个遵循特定接口的 JavaScript 模块，Codex 会在特定生命周期事件中调用插件暴露的函数。插件可以用于：

• 自定义命令处理逻辑
• 接入内部工具链
• 增强代码分析能力
• 定制输出格式

4.2 编写第一个插件

在项目目录下创建 .codex/plugins/my-plugin.js：

// 自定义 Codex 插件示例
module.exports = {
  name: "my-plugin",
  version: "1.0.0",
// 在 Codex 启动时调用
async onInit(context) {
console.log("[my-plugin] Codex 初始化完成");
context.registerCommand("hello", async (args) => {
return 你好，${args.name || "Codex"}！;
});
},
// 在每次生成代码前调用
async beforeGenerate(context, prompt) {
console.log("[my-plugin] 收到生成请求:", prompt.slice(0, 50));
return prompt;
},
// 在生成完成后调用
async afterGenerate(context, result) {
console.log("[my-plugin] 生成完成，代码长度:", result.length);
return result;
}
};

4.3 注册并启用插件

在 .codex/config.toml 中注册插件：

[plugins]
enabled = ["my-plugin"]
[plugins.my-plugin]
path = "./.codex/plugins/my-plugin.js"
enabled = true

重启 Codex 后，插件会自动加载。你可以通过以下命令测试插件是否生效：

codex "调用 hello 命令，name 为 小白"

5. MCP 接入指南

5.1 MCP 是什么

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 提出的一种开放协议，用于让 AI 模型与外部工具、数据源进行标准化交互。Codex 支持 MCP，这意味着你可以通过 MCP 让 Codex 连接数据库、调用内部 API、读取监控系统数据等。

MCP 的核心价值在于：一次接入，多处复用。同一个 MCP 服务可以被不同的 AI 工具共享。

5.2 配置 MCP 服务

在 ~/.codex/config.toml 中添加 MCP 配置：

[mcp_servers]
# 连接一个本地 MCP 服务
[ mcp_servers.local-tools ]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
env = { DEBUG = "false" }
连接一个远程 MCP 服务
[mcp_servers.remote-api]
url = "https://mcp.example.com/sse"
headers = { Authorization = "Bearer your-token" }

5.3 实战：接入文件系统 MCP

文件系统 MCP 服务允许 Codex 以标准化的方式读写本地文件。配置完成后，你可以这样使用：

codex "使用文件系统工具，列出 /tmp 目录下的所有文件"

Codex 会通过 MCP 协议调用文件系统服务，返回目录列表。你也可以让它读取特定文件内容：

codex "读取 /tmp/notes.txt 的内容，并总结要点"

5.4 实战：接入数据库 MCP

假设你有一个 MySQL 数据库 MCP 服务，配置如下：

[mcp_servers.mysql]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-mysql", "--host", "localhost", "--port", "3306", "--user", "root", "--password", "123456", "--database", "test_db"]

配置完成后，你可以让 Codex 直接查询数据库：

codex "查询 test_db 中 users 表的前 5 条记录"

6. Skills 技能包开发

6.1 Skills 概念

Skills 是 Codex 的「技能包」，它把一组特定的提示词、代码模板和工具调用封装成一个可复用的能力单元。比如你可以创建一个「代码审查」Skill，让 Codex 每次都用统一的规范审查代码。

Skills 与插件的区别在于：插件偏重程序化逻辑，Skills 偏重提示词和流程模板。

6.2 创建第一个 Skill

在 ~/.codex/skills/ 目录下创建技能文件夹：

mkdir -p ~/.codex/skills/code-review

创建 SKILL.md 文件，定义技能的行为：

---
name: code-review
description: 对指定代码文件进行全面的代码审查，输出结构化报告
version: 1.0.0
---
代码审查技能
当用户要求进行代码审查时，按照以下流程执行：
审查步骤
读取目标文件内容
检查代码风格是否符合项目规范
分析潜在 bug 和安全隐患
评估代码性能和可维护性
输出结构化审查报告
输出格式
审查报告必须包含以下部分：
问题摘要：按严重程度排序的问题列表
代码风格：风格问题及修改建议
安全性：安全漏洞及修复方案
性能：性能瓶颈及优化建议
改进建议：整体改进方向

6.3 使用 Skill

创建完成后，重启 Codex，然后这样使用技能：

codex "使用 code-review 技能审查 src/main.py"

Codex 会读取 SKILL.md，按照其中定义的流程执行审查，并输出结构化报告。

6.4 实战：开发一个「API 文档生成」Skill

再创建一个实用的 Skill，用于自动生成 API 文档：

mkdir -p ~/.codex/skills/api-doc

创建 SKILL.md：

---
name: api-doc
description: 根据代码自动生成 API 接口文档
version: 1.0.0
---
API 文档生成技能
当用户要求生成 API 文档时，执行以下步骤：
流程
扫描项目中的路由定义文件
提取每个接口的路径、方法、参数
分析请求和响应数据结构
生成 Markdown 格式的 API 文档
文档模板
每个接口必须包含：
接口路径和方法
功能描述
请求参数表（参数名、类型、必填、说明）
响应示例
错误码说明

使用方式：

codex "使用 api-doc 技能为当前项目生成 API 文档"

7. 综合实战：搭建一个完整的开发工作流

7.1 场景描述

假设你正在开发一个 Python Flask 项目，希望 Codex 能帮你完成从代码生成到测试的全流程。我们将结合插件、MCP 和 Skills 搭建一个完整的工作流。

7.2 项目初始化

首先让 Codex 初始化项目结构：

mkdir flask-demo
cd flask-demo
codex "初始化一个 Flask 项目，包含 app.py、requirements.txt 和 README.md"

7.3 配置项目级 Skills

在项目目录创建 .codex/skills/，添加一个「测试生成」技能：

---
name: gen-test
description: 为指定模块自动生成单元测试
version: 1.0.0
---
单元测试生成技能
流程
读取目标模块源码
分析函数和类的输入输出
使用 pytest 编写单元测试
运行测试并修复失败用例
测试规范
测试文件放在 tests/ 目录
测试函数以 test_ 开头
每个函数至少一个正常用例和一个边界用例

7.4 完整工作流演示

现在，你可以用一条指令完成整个开发循环：

codex "使用 gen-test 技能为 app.py 生成单元测试，然后运行测试并修复所有失败"

Codex 会依次执行：读取源码、生成测试、运行测试、分析失败原因、修复代码、再次运行，直到测试全部通过。

7.5 结合 MCP 的进阶用法

如果项目需要操作数据库，可以结合 MCP 让 Codex 自动完成数据验证：

codex "运行测试后，使用 mysql MCP 工具检查测试数据是否正确写入数据库"

8. 常见问题与排查

8.1 安装失败

如果 npm install 失败，尝试以下方案：

# 清理 npm 缓存
npm cache clean --force
# 使用国内镜像
npm install -g @openai/codex --registry=https://registry.npmmirror.com

8.2 认证失败

如果提示认证失败，检查 API Key 是否正确，并确认环境变量已生效：

echo $OPENAI_API_KEY

8.3 插件不生效

插件不生效时，按以下顺序排查：

• 确认插件文件路径是否正确
• 确认 config.toml 中插件已启用
• 查看 Codex 启动日志是否有报错
• 尝试重启 Codex

8.4 MCP 连接失败

MCP 连接失败时，检查服务是否启动、端口是否正确、认证信息是否有效。可以在终端手动启动 MCP 服务验证：

npx -y @modelcontextprotocol/server-filesystem /tmp

9. 总结与进阶建议

本文从零开始，带你完成了 Codex 的安装、配置、插件开发、MCP 接入和 Skills 编写。核心要点总结如下：

• 安装：通过 npm 全局安装，配置 API Key 即可使用。
• 配置：全局配置在 ~/.codex/config.toml，项目配置在 .codex/config.toml。
• 插件：用 JavaScript 编写，通过生命周期钩子扩展能力。
• MCP：标准化协议，让 Codex 连接任意外部工具和数据源。
• Skills：用 Markdown 定义技能流程，实现可复用的工作流。

进阶学习建议：

• 阅读 Codex 官方文档，了解全部配置项。
• 尝试编写更复杂的插件，接入公司内部系统。
• 将常用的开发流程沉淀为 Skills，提升团队效率。
• 关注 MCP 生态，探索更多可接入的工具和服务。

Codex 的能力远不止于此，随着你不断实践和探索，它会成为你开发工作中不可或缺的得力助手。