1. 引言

如果你最近关注 AI 编程工具，一定听说过 OpenAI Codex。它不再只是那个藏在 ChatGPT 背后的代码模型，而是进化成了一款能直接跑在终端里的 AI 编程助手——能读懂你的仓库、自动改代码、执行命令，甚至帮你提交 PR。

但很多新手在第一次接触 Codex 时，会被一堆名词搞晕：CLI、插件、MCP、Skills、AGENTS.md……它们到底是什么？怎么装？怎么配？这篇文章就是为你准备的。

我会从零开始，带你完成 Codex 的安装、配置，并逐一讲清楚插件、MCP 和 Skills 的作用与用法。全程面向小白，跟着操作即可。

2. Codex 是什么

简单来说，Codex 是 OpenAI 推出的 AI 编程智能体。它不是一个只能补全代码的插件，而是一个能独立完成编程任务的助手：

• 能读取并理解你的整个代码仓库；
• 能自己修改多个文件；
• 能执行终端命令、运行测试；
• 能调用外部工具（通过 MCP）；
• 能按项目规范自动调整行为（通过 Skills 和 AGENTS.md）。

它有两种主要使用形态：

形态	说明	适合场景
Codex CLI	终端命令行工具	本地开发、自动化任务
IDE 插件	VS Code 等编辑器内使用	日常编码、代码审查

两者共用同一套配置体系，学会一个，另一个也就通了。

3. 安装 Codex CLI

3.1 环境要求

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

• 操作系统：macOS、Linux 或 Windows（WSL 2 推荐）
• Node.js：18.0 及以上版本
• 网络：能正常访问 OpenAI 接口

3.2 安装步骤

Codex CLI 通过 npm 分发，安装非常简单。打开终端，执行：

npm install -g @openai/codex

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

codex --version

如果能看到版本号，说明安装成功。

3.3 登录与认证

首次运行需要登录 OpenAI 账号：

codex login

执行后，终端会输出一个链接，在浏览器中打开并授权即可。登录成功后，Codex 会保存凭据，下次使用无需重复登录。

如果你使用的是公司内部代理或自定义 API 端点，可以通过环境变量配置：

export OPENAI_BASE_URL="https://your-proxy.example.com/v1"
export OPENAI_API_KEY="your-api-key"

4. 配置文件详解

Codex 的配置采用分层设计，从全局到项目逐级覆盖。理解这一层，后面的插件和 Skills 配置就顺理成章了。

4.1 配置文件位置

Codex 使用 TOML 格式的配置文件，主要有三个层级：

层级	路径	作用
全局	~/.codex/config.toml	所有项目的默认配置
项目	.codex/config.toml	当前项目的配置，覆盖全局
本地	.codex/local.toml	个人本地配置，不提交到 Git

4.2 基础配置示例

# ~/.codex/config.toml
model = "gpt-5-codex"
model_reasoning_effort = "medium"

[history]
  enabled = true

[notifications]
  enabled = true

4.3 环境变量与密钥管理

敏感信息（如 API Key）不建议直接写在配置文件里。Codex 支持从环境变量读取：

# 在配置中引用环境变量
[env]
  MY_SECRET = "{env:MY_SECRET_KEY}"

这样既保证了配置的灵活性，又避免了密钥泄露。

5. 插件机制

5.1 插件是什么

插件（Plugins）是 Codex 的扩展机制，用于增强其核心能力。通过插件，你可以：

• 接入自定义工具；
• 扩展命令；
• 定制输出格式；
• 集成第三方服务。

5.2 安装插件

Codex 插件通过 npm 包分发。在项目目录下执行：

codex plugin add <plugin-name>

例如，安装一个代码质量检查插件：

codex plugin add @codex/plugin-lint

5.3 配置插件

插件安装后，需要在配置文件中启用并配置：

# .codex/config.toml
[plugins]
  [plugins.lint]
    enabled = true
    config = { strict = true }

5.4 编写自己的插件

Codex 插件本质上是遵循特定协议的 npm 包。一个最小插件结构如下：

my-plugin/
├── package.json
├── index.js
└── README.md

index.js 中导出插件的核心逻辑：

export default {
  name: "my-plugin",
  hooks: {
    beforeTask: (ctx) => {
      console.log("任务开始前执行");
    },
    afterTask: (ctx) => {
      console.log("任务结束后执行");
    }
  }
};

6. MCP 配置

6.1 MCP 是什么

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 提出、OpenAI 等厂商共同支持的一种开放协议。它让 AI 助手能够以标准化的方式连接外部工具和数据源。

简单理解：MCP 是 AI 世界的 USB 接口。只要工具实现了 MCP 协议，Codex 就能直接调用它，无需为每个工具单独写集成代码。

6.2 MCP 能做什么

通过 MCP，Codex 可以连接：

• 数据库（PostgreSQL、MySQL 等）；
• 文件系统；
• 浏览器自动化工具；
• 设计工具（Figma）；
• 项目管理工具（Jira、Linear）；
• 搜索服务（Google、Bing）。

6.3 配置 MCP 服务器

在 config.toml 中配置 MCP 服务器：

# .codex/config.toml
[mcp_servers]
  [mcp_servers.postgres]
    command = "npx"
    args = ["-y", "@modelcontextprotocol/server-postgres"]
    env = { DATABASE_URL = "postgresql://user:pass@localhost:5432/db" }

6.4 使用 MCP 工具

配置完成后，在对话中直接让 Codex 使用对应工具即可。例如：

> 帮我查询数据库中最近 10 条订单记录

Codex 会自动调用配置好的 PostgreSQL MCP 工具完成查询。

6.5 常用 MCP 服务器推荐

服务器	用途	安装命令
server-filesystem	文件系统访问	npx -y @modelcontextprotocol/server-filesystem
server-postgres	PostgreSQL 数据库	npx -y @modelcontextprotocol/server-postgres
server-github	GitHub 操作	npx -y @modelcontextprotocol/server-github
server-brave-search	网页搜索	npx -y @modelcontextprotocol/server-brave-search

7. Skills 配置

7.1 Skills 是什么

Skills（技能）是 Codex 的项目级行为规范。它通过 AGENTS.md 文件定义，告诉 Codex 在特定项目中应该遵循的规则、偏好和流程。

如果说 MCP 是给 Codex 装上了"手"，那么 Skills 就是给它装上了"大脑"——让它知道在什么场景下该怎么做。

7.2 AGENTS.md 文件

AGENTS.md 是 Skills 的核心载体，放在项目根目录。Codex 每次运行时会自动读取它。

一个典型的 AGENTS.md 示例：

# 项目规范

## 代码风格
- 使用 TypeScript 编写新代码
- 遵循 ESLint 配置
- 使用 2 空格缩进

## 测试要求
- 所有新功能必须附带单元测试
- 测试文件放在 `__tests__` 目录
- 使用 Jest 作为测试框架

## 提交规范
- 提交信息使用 Conventional Commits 格式
- 提交前必须运行 `npm run lint` 和 `npm test`

7.3 编写有效的 Skills

编写 Skills 时，注意以下几点：

明确具体：不要写"写高质量代码"这种模糊要求，要写"使用 2 空格缩进"这种可执行的规则。

分门别类：按代码风格、测试、提交、架构等维度组织内容，方便 Codex 快速检索。

持续迭代：随着项目演进，及时更新 AGENTS.md，让它始终反映当前的最佳实践。

7.4 Skills 与 MCP 的配合

Skills 和 MCP 经常配合使用。例如，在 AGENTS.md 中规定：

## 数据库操作
- 所有数据库查询必须通过 PostgreSQL MCP 工具执行
- 禁止在代码中硬编码 SQL 字符串

这样 Codex 在遇到数据库相关任务时，就会自动调用 MCP 工具，而不是自己写 SQL。

8. 实战：完整配置示例

下面是一个完整的项目配置示例，综合了前面讲到的所有内容。

8.1 项目结构

my-project/
├── .codex/
│   ├── config.toml
│   └── local.toml
├── AGENTS.md
├── package.json
└── src/

8.2 项目配置

# .codex/config.toml
model = "gpt-5-codex"
model_reasoning_effort = "high"

# 插件配置
[plugins]
  [plugins.lint]
    enabled = true

# MCP 服务器配置
[mcp_servers]
  [mcp_servers.postgres]
    command = "npx"
    args = ["-y", "@modelcontextprotocol/server-postgres"]
    env = { DATABASE_URL = "{env:DATABASE_URL}" }

8.3 项目规范

# AGENTS.md

## 技术栈
- Node.js 20+
- TypeScript 5.x
- Express 4.x

## 代码规范
- 使用 2 空格缩进
- 所有接口使用 async/await
- 错误处理使用自定义 Error 类

## 测试
- 使用 Vitest
- 测试覆盖率不低于 80%
- 运行测试：`npm test`

## 数据库
- 使用 PostgreSQL MCP 工具执行查询
- 所有表必须有 created_at 和 updated_at 字段

8.4 使用流程

配置完成后，在项目目录下启动 Codex：

codex

然后直接描述任务：

> 帮我实现一个用户注册接口，包含邮箱验证

Codex 会读取 AGENTS.md 了解项目规范，调用 MCP 工具操作数据库，并按照规范生成代码。

9. 常见问题排查

9.1 安装失败

如果 npm install 失败，尝试：

# 清理 npm 缓存
npm cache clean --force

# 使用镜像源
npm install -g @openai/codex --registry=https://registry.npmmirror.com

9.2 登录失败

检查网络代理设置，确保终端能访问 OpenAI 服务。如果使用代理，设置环境变量：

export HTTPS_PROXY="http://127.0.0.1:7890"

9.3 MCP 连接失败

• 确认 MCP 服务器命令能独立运行；
• 检查环境变量是否正确传递；
• 查看 Codex 日志定位具体错误。

9.4 Skills 不生效

• 确认 AGENTS.md 在项目根目录；
• 检查文件名大小写是否正确；
• 重启 Codex 会话使其重新加载。

10. 总结

到这里，你已经掌握了 Codex 的核心配置：

• 安装：通过 npm 一键安装，codex login 完成认证；
• 配置：TOML 分层配置，从全局到项目逐级覆盖；
• 插件：npm 包扩展机制，增强核心能力；
• MCP：标准化工具接入协议，连接外部数据源和服务；
• Skills：通过 AGENTS.md 定义项目级行为规范。

这三者构成了 Codex 的完整能力体系：插件扩展能力边界，MCP 打通外部工具，Skills 规范行为方式。掌握它们，你就能让 Codex 真正成为得力的编程伙伴。

下一步，建议你从一个小项目开始，先配置好 AGENTS.md，再接入一个 MCP 服务器，逐步体验 Codex 的完整工作流。祝你玩得开心！