很多开发者在使用 Codex 时，最常犯的错误就是把所有规则都写在 Prompt 里。

这不仅浪费 Token，还会因为上下文污染导致 AI 输出不稳定。

其实，Codex 并不是一个简单的聊天框，而是一个高度可定制的智能工作台。

通过合理配置，你可以让它深度融入你的本地开发流。

本文将为你彻底梳理 Codex 的多层配置体系，带你从零开始完成安装、配置、插件、Skills、MCP 及记忆系统的搭建。

---

一、 Codex 的“七层配置”地图

在正式动手之前，我们先用一张图看懂 Codex 的配置结构。

不同层级的配置，决定了 Codex 在不同范围内的行为表现：

简单来说，它们的职责划分如下：

• 当前对话（Prompt）：决定单次任务的具体要求。
• 项目级规则（AGENTS.md）：存放该项目长期遵守的编码规范、构建命令与测试流程。
• 全局默认设置（config.toml）：控制 Codex 本身的运行参数，如默认模型、沙箱权限。
• 标准工作流（Skills）：封装好的、可复用的任务步骤。
• 外部接口（Plugins）：连接外部系统与工具的通道。
• 数据网关（MCP）：通过标准协议引入实时数据源。
• 长期偏好（Memory）：记录你的个人习惯与角色设定。

把规则放在正确的位置，Codex 才能真正成为懂你项目的“AI 队友”。

---

二、 快速安装与环境初始化

Codex 提供了桌面客户端（Desktop App）与命令行工具（CLI）。

对于开发者，建议采用 Desktop App + CLI 的组合方式。

1. 安装 Codex Desktop App

桌面端适合进行可视化插件管理、连接器授权以及多线程对话管理。

https://persistent.oaistatic.com/codex-app-prod/Codex.dmg

https://persistent.oaistatic.com/codex-app-prod/Codex-latest-x64.dmg

https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi

• macOS (Apple Silicon)：
• macOS (Intel)：
• Windows：

安装完成后，启动 App 并按照提示完成账号登录即可。

2. 安装 Codex CLI

CLI 工具是终端提效的核心。你可以使用官方的一键脚本进行安装。

macOS / Linux 安装命令：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows PowerShell 安装命令：

irm https://chatgpt.com/codex/install.ps1 | iex

如果你习惯使用包管理器，也可以通过以下方式安装：

# 使用 npm 安装
npm install -g @openai/codex

# 使用 Homebrew 安装
brew install --cask codex

3. 初始化与登录配置

安装完成后，在终端依次执行以下命令进行环境检查与登录：

# 查看当前版本
codex --version

# 登录账号
codex login

# 诊断本地环境健康度
codex doctor

codex doctor 是一个非常实用的命令。

当遇到插件不生效、MCP 连不上等异常情况时，优先运行它来排查本地环境问题。

在进行本地开发环境配置或网络环境配置时，我们经常需要灵活切换模型服务。本文使用 iThinkAPI 作为演示环境，它支持标准的 OpenAI Compatible API 配置方式。在实际配置过程中，我们主要需要关注 API Key、Base URL 以及模型名称的设置，以便于进行多模型集成测试与 Token 消耗分析。

Base URL：https://token.ithinkai.cn/v1
API Key：YOUR_API_KEY
Model：以服务文档为准，最新模型  gpt-5.5, claude-opus-4-8,
gpt-image-2 模型都有几乎在 0.05¥/图，支持 2k,4k

第二步：挑选模型与确定分组

在使用之前，请先确认您想使用的模型及其对应的线路。

1.模型广场：点击顶部导航栏的 “模型广场”。

2. 搜索模型：在搜索框中输入关键词（如 gpt, claude, image 等）查找模型。

3. 确定模型分组（线路选择）：

什么是分组？ 每个分组代表一条不同的调用线路。由于接入了多种资源，同一模型在不同分组下价格和质量不同。

---

第三步：创建 API 令牌 (Key)

这是最关键的一步，你需要生成一个 Key，并为其绑定你选中的分组。

1.进入控制台：点击顶部导航栏的 “控制台”。

2.令牌管理：在左侧菜单栏选择 “令牌管理” -> “添加令牌”。

3.配置令牌信息：

分组：重要！ 这里必须勾选你在第二步中看中的分组（例如想用最便宜的线路，就选 default）。

4.获取 Key：提交后回到列表，点击令牌旁边的复制图标，获取以 sk- 开头的字符串。

三、 项目级规则约束：AGENTS.md 的深度实践

AGENTS.md 是项目级配置的核心。

它存放在项目的根目录下，专门用来告诉 Codex “在这个项目里该如何工作”。

一个标准且实用的 AGENTS.md 模板如下：

# AGENTS.md

## Project Overview
这是一个基于 Next.js 14 (App Router) 的前端项目。
核心业务逻辑位于 `src/app`，公共组件位于 `src/components`。

## Common Commands
- 安装依赖: `pnpm install`
- 启动开发服务: `pnpm dev`
- 类型检查: `pnpm typecheck`
- 运行测试: `pnpm test`

## Coding Rules
- 优先使用 Tailwind CSS 进行样式编写。
- 组件必须使用 TypeScript 进行类型约束，禁止使用 `any`。
- 修改代码时，仅针对目标文件进行最小化改动，严禁重写无关文件。

## Verification
在交付任务前，必须执行以下验证：
- 涉及 UI 改动，必须运行 `pnpm typecheck` 确保无编译错误。
- 涉及逻辑改动，必须运行 `pnpm test` 确保单测通过。

通过配置 AGENTS.md，Codex 在读取项目上下文时会自动加载这些规则。

你无需在每次对话中重复强调“不要用 any”或“记得用 pnpm”，AI 会自动遵守这些约定。

---

四、 全局运行控制：config.toml 参数详解

config.toml 决定了 Codex 在你本地系统中的行为边界与默认参数。

其默认配置文件通常位于：~/.codex/config.toml。

以下是常用配置项的详细解析：

| 配置项 | 说明 | 推荐设置 | | :--- | :--- | :--- | | model | 默认调用的基座模型 | o3（根据当前可用版本调整） | | sandbox_mode | 沙箱安全级别，限制 Codex 访问本地文件的权限 | workspace-write（仅允许写入当前工作区） | | approval_policy | 敏感操作（如执行终端命令）的审批策略 | on-request（每次执行前需人工确认） |

一个安全的初始配置示例：

# ~/.codex/config.toml

model = "o3"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

避坑提示：刚入门时，切忌将 sandbox_mode 直接设为最高权限。

保持 on-request 的审批策略，可以让每一次敏感命令的执行都在你的掌控之中，避免误删本地文件。

---

五、 插件（Plugins）与技能（Skills）的差异化配置

很多人容易混淆 Plugins 与 Skills 的界限。

简单来说：Plugins 是能力扩展，Skills 是流程封装。

1. Plugins（插件）

插件为 Codex 提供了与外部应用交互的能力，例如操作浏览器、读取 GitHub PR 等。

你可以通过命令行管理插件：

# 列出已安装插件
codex plugin list

# 从市场安装指定插件
codex plugin add github

2. Skills（技能）

技能是存放在 ~/.codex/skills/ 目录下的 Markdown 文件。

它定义了某一类特定任务的标准作业程序（SOP）。

例如，你可以创建一个名为 code-review.md 的 Skill：

---
name: code-review
description: 用于在代码合并前进行质量审查。
---

# Code Review Workflow

1. 检查修改的文件列表，重点关注逻辑变更。
2. 评估代码是否符合项目的类型安全规范。
3. 检查是否存在潜在的内存泄漏或性能隐患。
4. 给出具体的修改建议，并附带代码示例。

当你在对话中触发“审查代码”相关任务时，Codex 会自动加载这个 Skill 模板，按既定步骤执行。

---

六、 连接外部世界：MCP 极简上手

MCP（Model Context Protocol）是连接外部数据源的标准协议。

通过 MCP，你可以让 Codex 实时读取数据库、查询团队知识库或检索 API 文档。

常用 MCP 管理命令

# 查看当前配置的 MCP 服务
codex mcp list

# 引入一个基于 HTTP 的 MCP 服务
codex mcp add dev-docs --url https://developers.openai.com/mcp

# 引入一个本地运行的 MCP 服务
codex mcp add local-db-helper -- node db-server.js

实战建议：不要让 AI 凭空记忆你的私有数据。

如果需要分析数据库表结构，最优雅的方式是配置一个只读的数据库 MCP 服务，让 Codex 实时查询，而不是手动复制 DDL 语句。

---

七、 长期记忆（Memory）与 App 连接器

1. 记忆功能（Memory）

Memory 适合存储你的长期偏好，而非具体项目的数据。

• 适合放入 Memory：“我习惯使用 TypeScript 进行开发”、“回答时请保持简洁，直接给出代码”。
• 不适合放入 Memory：API Key、临时任务需求、具体的项目路径（这些应分别放入环境变量、Prompt 和 AGENTS.md 中）。

2. App 连接器

App 连接器允许 Codex 在获得授权后，直接与你日常使用的生产力工具（如 Gmail、GitHub、Figma）进行交互。

在配置连接器时，请遵循“读写分离”的安全原则：

• 允许自动读取邮件、PR 状态和设计稿。
• 对于发送邮件、合并 PR、修改云端配置等写操作，必须设置为“手动确认”。

---

八、 避坑指南与排错 SOP

在配置和使用 Codex 的过程中，难免会遇到各种异常。

你可以按照以下流程图进行快速排查：

常见问题与排错方法

1. 命令行提示权限不足（Permission Denied）

• 原因：沙箱模式限制了文件写入。
• 解决：检查 config.toml 中的 sandbox_mode。如果是特定受信任项目，可在当前目录的 AGENTS.md 中声明所需权限，或在启动时通过命令行临时授权：

    codex -c 'sandbox_permissions=["disk-full-read-access"]'

2. MCP 服务连接失败

1. 运行 codex doctor 查看服务连接状态。 2. 确保本地 node/python 脚本路径正确，且依赖已安装。

• 原因：本地服务未启动或网络配置错误。
• 解决：

3. 规则未生效

• 原因：AGENTS.md 命名错误或未放置在项目根目录下。
• 解决：确保文件名完全一致（大小写敏感），且终端执行 codex 命令时处于该文件所在的目录下。

---

九、 总结

理清了 Codex 的配置层级，你会发现它其实非常严谨。

新手入门，建议按照以下步骤逐步搭建你的工作流：

1. 完成安装，运行 codex doctor 确保环境健康。
2. 在当前开发的项目根目录下，配置一个基础的 AGENTS.md。
3. 保持 config.toml 的默认安全限制，熟悉后再逐步放开。
4. 根据高频任务，提炼并编写一到两个特定的 Skill。

把规则和工具放在正确的位置，让 AI 真正融入你的开发节奏。