Codex 怎么配置？从 AGENTS.md、MCP 到 Skills 的 2026 入门指南

OpenAI 官方把 Codex 定位为“帮助你写、审、交付代码的 AI agent”，并提供 App、CLI、IDE extension、Web 等入口（OpenAI Help Center《Using Codex with your ChatGPT plan》，retrieved 2026-06-20）。如果你正在搜 Codex 怎么配置，真正要解决的通常不是“怎么问 Codex”，而是不知道 Prompt、AGENTS.md、config.toml、Skills、Plugins、MCP、Memory 分别该放什么。

这篇文章参考了《程序员成长指北》的 Codex 小白入门思路：不要把 Codex 当成一个聊天框，而要把它当成一套可配置的工作台。我们会把配置拆成 7 层，按新手可执行的顺序搭起来：先装 App 和 CLI，再写项目规则，最后才接插件、MCP、Skills 和 Memory。

关键要点

• Codex 的核心不是“写更长 prompt”，而是把不同类型的信息放到正确层级。
• 临时需求放当前对话；项目规则放 AGENTS.md；长期默认值放 ~/.codex/config.toml。
• 重复流程才值得写成 Skill；需要外部系统和实时数据时，再考虑 MCP、Apps 或插件。
• 新手不要一开始就开最高权限。先用 codex doctor、保守沙箱和人工确认跑通闭环。
• 如果你高频用 Codex，订阅、额度、Plus / Pro 计划选择也会变成工作流瓶颈。

如果你已经在用 Codex 做开发，但经常遇到“额度不够、Plus / Pro 不知道怎么选、国内支付失败”等问题，可以先把本文看完，再结合 Codex 额度重置咨询、ChatGPT Plus 充值 和 ChatGPT Pro 说明 规划自己的使用方式。

如果你还停在“国内到底能不能看到 Codex 入口”，先看 Codex 国内怎么用：账号、订阅、入口和安全检查清单，再回来配置 AGENTS.md、MCP 和 Skills。

---

Codex 怎么配置，最先要理解什么？

Codex 入门先理解 7 层配置，而不是先背命令。OpenAI Developers 的 CLI 文档说明，Codex CLI 可以在终端里检查仓库、编辑文件并运行命令（OpenAI Developers《CLI – Codex》，retrieved 2026-06-20）。这意味着它不是普通问答窗口，而是会进入你真实工作区执行任务的 agent。

你可以先记住这张“放置地图”：

实操观察：真正节省时间的不是“让 Codex 一次性回答得更聪明”，而是减少你每次开工前的重复解释。比如“这个项目用 pnpm，不要用 npm”“改 UI 后跑 typecheck”“不要直接推主分支”，这些不该每次写在 prompt 里，而该沉淀到项目规则或工作流里。

可引用摘要：Codex 新手配置的核心原则是分层：临时任务写进 prompt，项目规则写进 AGENTS.md，全局默认值写进 config.toml，重复流程写成 Skills，外部系统通过 MCP、Apps 或 Plugins 接入。这样 Codex 才会从聊天窗口变成可验证的工作台。

---

开始配置 Codex 前需要准备什么？

开始前只需要 4 件事：一个可登录的 ChatGPT / OpenAI 账号，一个本地项目目录，一个能运行终端命令的环境，以及 30–60 分钟做第一轮验证。OpenAI Help Center 说明 Codex 覆盖 Free、Go、Plus、Pro、Business、Edu、Enterprise 等计划，但用量限制和信用额度因计划而异（OpenAI Help Center《Using Codex with your ChatGPT plan》，retrieved 2026-06-20）。

建议准备清单：

• 一个你自己控制的 ChatGPT / OpenAI 账号。
• 一个不怕试错的本地项目，最好是你熟悉的仓库。
• 终端环境：macOS、Linux 或 Windows PowerShell。
• GitHub 账号：如果你后续要接 PR、Issue 或代码审查。
• 30–60 分钟：先跑通最小闭环，不要一上来装满所有插件。

如果你在国内遇到订阅付款问题，可以先看 ChatGPT Plus 国内充值实战指南。代充值解决的是订阅和支付问题，不等于保证所有地区、所有账号、所有时间都看到完全相同的 Codex 功能入口。

---

第一步：怎么安装 Codex App 和 CLI？

第一步的目标是让你同时拥有图形入口和终端入口。OpenAI Developers 的 App 文档说明，Codex App 支持 macOS 和 Windows；CLI 文档提供 macOS / Linux standalone installer、Windows PowerShell、npm、Homebrew 等安装方式（OpenAI Developers《App – Codex》《CLI – Codex》，retrieved 2026-06-20）。

如果你是新手，我建议用 Codex App + Codex CLI 这套组合：App 适合看线程、插件和连接器；CLI 适合进入项目目录，让 Codex 读代码、改文件、跑命令。

macOS / Linux 安装 CLI

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

Windows PowerShell 安装 CLI

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

npm 或 Homebrew 安装

npm install -g @openai/codex
brew install --cask codex

安全提醒：curl | sh 和 irm | iex 都是在本机直接执行远程脚本。只从官方文档给出的 chatgpt.com/codex/ 域名复制命令；如果你是在第三方教程里看到命令，先回到 OpenAI 官方 CLI 文档核对，不要执行被改写过的安装脚本。

装完先跑这 4 个命令：

codex --version
codex login
codex doctor
codex --help

截至 2026-06-20，npm registry 显示 @openai/codex latest 版本为 0.141.0（npm registry《@openai/codex latest》，retrieved 2026-06-20）。版本会快速变化，所以不要把网上教程里的具体版本号当成永久答案；以你本机的 codex --help 和官方文档为准。

验证方式：能成功登录，codex doctor 没有阻塞性错误，codex --help 能看到可用命令，就算第一步跑通。

---

第二步：AGENTS.md 应该怎么写？

第二步的目标是让 Codex 懂你的项目规矩。OpenAI Codex 文档导航中把 AGENTS.md 单独列为指南入口（OpenAI Developers《CLI – Codex》，retrieved 2026-06-20），因为它承担的是“项目级长期规则”，不是一次性 prompt。

最小可用版本可以这样写：

# AGENTS.md

## Project overview

This is a Next.js project. The main app lives in `app/`.

## Common commands

- Install dependencies: `pnpm install`
- Start dev server: `pnpm dev`
- Run typecheck: `pnpm typecheck`
- Run tests: `pnpm test`
- Build: `pnpm build`

## Working rules

- Read existing code before editing.
- Keep changes focused on the requested task.
- Do not rewrite unrelated files.
- Follow existing naming and style.
- Ask before adding new dependencies.

## Verification

Before saying the task is complete:

- UI changes: run `pnpm typecheck`.
- Logic changes: run related tests.
- If a command was not run, say why.

AGENTS.md 不需要写成散文。它应该像“给 AI 同事的执行手册”：项目结构、常用命令、禁止事项、验收方式，越可执行越好。

经验提醒：我们在做 GPT-Plus.AI 页面和博客内容时，最有用的规则不是宏大的品牌愿景，而是“不要直接改 main”“交付前说明哪些检查跑过”“充值类页面不能承诺 100% 无风险”。这些规则写进项目说明后，Codex 才不需要每次被重新提醒。

验证方式：在项目根目录打开 Codex，问它“先根据 AGENTS.md 总结这个项目的工作规则，不要改文件”。如果它能正确复述关键命令、边界和验收方式，说明这层配置生效。

---

第三步：config.toml 应该怎么设置？

第三步的目标是设置长期默认值，而不是把每次任务都写长。Codex CLI 文档展示了 -c 临时覆盖配置的用法，也说明 CLI 能读取配置、沙箱和运行策略相关设置（OpenAI Developers《CLI – Codex》，retrieved 2026-06-20）。新手阶段先保守，不要一上来追求全权限自动化。

常见位置是：

~/.codex/config.toml

一个偏保守的新手模板可以这样理解：

# ~/.codex/config.toml

# 按你账号当前可用模型调整，不要照抄旧教程。
model = "o3"

# 新手先让 Codex 只能写当前工作区。
sandbox_mode = "workspace-write"

# 涉及敏感操作时让 Codex 先问你。
approval_policy = "on-request"

这里最重要的是边界意识。danger-full-access 看起来省事，但它让 Codex 拥有很大的本地权限。刚入门时，更好的路线是先用保守沙箱跑通任务，再按项目可信度逐步放开。

验证方式：改完后跑：

codex doctor
codex --help

如果字段不被识别，不要硬套教程。Codex 迭代很快，字段名和支持范围可能变化，优先看当前版本输出。

---

第四步：插件和 App 应该先接哪个？

第四步的目标是让 Codex 接触一个真实工作流。OpenAI Developers 的 App 文档强调，Codex App 可以选择项目并在本地工作；Codex 文档体系也把 GitHub、Slack、Linear、Plugins 等集成作为独立主题（OpenAI Developers《App – Codex》，retrieved 2026-06-20）。对新手来说，一次只接一个最常用入口最稳。

你可以按工作场景选：

不要把插件当“越多越强”的装饰品。插件的价值在于：Codex 能读取真实材料、调用真实工具、交付真实产物。

读写分界很关键：读取 PR、总结文档、打开网页通常风险较低；发送邮件、提交表单、删除文件、发布文章、改权限、付款等操作属于外部副作用，一定要让 Codex 先停下来给你确认。

---

第五步：什么时候用 Skills、MCP 和 Memory？

第五步的目标是把重复流程、外部系统和长期偏好分清楚。MCP 官方文档把 Model Context Protocol 解释为连接 AI 应用和外部系统的开放标准，类似“AI 应用的 USB-C 接口”（Model Context Protocol《What is MCP?》，retrieved 2026-06-20）。但不是所有东西都该用 MCP。

什么时候写 Skill？

当某类任务每周都会重复，而且步骤基本固定，就值得写成 Skill。

例如：

• 写 SEO 博客：选题 → 搜索意图 → 大纲 → 初稿 → 内链 → SEO 检查。
• 审 PR：看需求 → 看 diff → 查测试 → 找风险 → 输出 findings。
• 发版检查：看变更 → 跑构建 → 查环境变量 → 写发布说明。

Skill 不是 prompt 模板，而是“做事 SOP”。好的 Skill 要说明：什么时候触发、按什么步骤做、用什么工具、最后怎么验收。

什么时候接 MCP？

当 Codex 需要读外部系统或实时数据，就考虑 MCP。

例如：

• 查 GitHub PR 当前 CI 是否通过。
• 读数据库里的业务指标。
• 查文档系统里的团队知识库。
• 打开浏览器检查页面。
• 调用内部工具或搜索服务。

MCP 不应该替代常识。需要外部事实时，让 Codex 读取真实来源；不要让模型凭记忆回答你的私有数据。

什么时候用 Memory？

Memory 只适合长期偏好，不适合机密和实时事实。

适合记：

• “我喜欢中文实战风格，少空话。”
• “回答时先给结论，再给证据。”
• “我经常做 AI 工具站 SEO。”

不适合记：

• 密码、token、API key。
• 今天某个 PR 的状态。
• 临时订单号或一次性任务要求。
• 很快过期的新闻和版本信息。

可引用摘要：Skills 管重复流程，MCP 管外部系统，Memory 管长期偏好。项目启动命令和代码规则放 AGENTS.md，模型、沙箱和审批策略放 config.toml。把这些层级混在 prompt 里，会让 Codex 每次都从零理解你的工作方式。

---

新手最容易踩哪些坑？

新手最容易踩的坑不是命令打错，而是把所有信息都塞进 prompt。OpenAI Codex 既有 App、CLI、IDE、Web 等入口，又有配置、权限、集成、Skills、MCP 等层级（OpenAI Developers《Codex | OpenAI Developers》，retrieved 2026-06-20）。层级不分清，后面排错会非常痛苦。

坑 1：AGENTS.md 写成项目宣传稿

错误写法是讲愿景、讲背景、讲品牌故事。正确写法是写命令、目录、边界和验收方式。Codex 执行任务时，需要的是可操作信息。

坑 2：一开始就开最高权限

最高权限适合你非常信任的工作区，不适合新手默认配置。先让 Codex 在工作区内写文件，涉及外部副作用时要求确认。

坑 3：MCP 配完不验证

能 list 出来只是第一步。还要验证认证、网络、权限、server 本身是否正常。建议每接一个 MCP，就用一个最小真实任务测试。

坑 4：插件装太多

插件多不等于工作流强。你真正需要的是“每天都能减少一次重复操作”的能力。写代码先接 GitHub 或 IDE；写文章先接 Browser 或文档工具。

坑 5：把 Memory 当数据库

Memory 不是事实库。项目状态、订单状态、PR 状态、新闻变化，都应该从真实系统读取。Memory 只记稳定偏好和长期习惯。

坑 6：不区分读取和写入

读取资料通常风险低，写入真实系统风险高。删除文件、发消息、提交表单、发版、付款这些动作，都应该停下来确认。

---

Codex 和 ChatGPT Plus / Pro 应该怎么选？

如果你只是每周做几次聚焦开发任务，Plus 往往够用；如果你高频用 Codex 做长任务、并行任务或重度开发，Pro 的更高限制更值得评估。OpenAI Developers 的 Codex Pricing 页面把 Plus 描述为“每周几个聚焦 coding sessions”，并把 Pro 描述为比 Plus 高 5x 或 20x 的 rate limits（OpenAI Developers《Pricing – Codex》，retrieved 2026-06-20）。

简单判断：

如果你当前的问题是“Codex 本周额度用完，但还有开发任务要继续”，可以看 Codex 额度重置咨询。如果你还没开 Plus，可以看 ChatGPT Plus 充值；如果你已经明确需要更高限制，再看 ChatGPT Pro。

注意：代充值或额度咨询解决的是支付、订阅或当前活动规则相关的问题，不等于保证功能入口、地区可见性、账号 rollout 完全一致。涉及 GitHub、私有代码、账号权限时，账号控制权应该始终留在你自己手里。

---

小白应该按什么顺序配置 Codex？

最稳的路线不是“一次学完所有概念”，而是每一步都能验证。OpenAI CLI 文档建议安装后运行 Codex 并登录，App 文档也要求选择项目后开始本地工作（OpenAI Developers《CLI – Codex》《App – Codex》，retrieved 2026-06-20）。所以配置顺序应该服务于“能验证”，而不是“看起来完整”。

建议按这个顺序来：

1. 安装 Codex App 和 CLI：能打开 App，CLI 能 codex --version。
2. 登录账号：用 codex login 或 App 登录。
3. 跑健康检查：用 codex doctor 先排除环境问题。
4. 在项目根目录写 AGENTS.md：只写项目结构、命令、边界、验收。
5. 设置保守的 config.toml：先用工作区写权限和人工确认。
6. 接一个最常用插件或 App：GitHub、Browser、IDE extension 先选一个。
7. 重复任务再写 Skill：不要为一次性任务写 Skill。
8. 需要外部实时数据再接 MCP：接一个测一个，不批量堆。
9. 长期偏好再放 Memory：不放密钥，不放临时事实。

配置原则：这套顺序的关键是“每一步都有回滚点”。如果你一口气装十几个插件、配五个 MCP、改一堆全局权限，后面出错时根本不知道是哪一层坏了。小白阶段，定位能力比配置完整度更重要。

验证方式：让 Codex 在一个测试项目里完成一个小任务，比如“读取项目结构，生成一份不改文件的技术摘要”。如果它能遵守 AGENTS、不开危险权限、不编造测试结果，你再逐步增加写文件、接 GitHub 或跑命令的权限。

---

常见问题

Codex 怎么配置最小可用版是什么？

最小可用版只需要 3 层：安装并登录 Codex CLI，给项目写一个可执行的 AGENTS.md，再用保守的 ~/.codex/config.toml 控制沙箱和审批。等 codex doctor 与一个只读测试任务通过后，再逐步增加 Codex MCP、Codex Skills 或插件。

Codex 一定要 ChatGPT Plus 才能用吗？

不一定。OpenAI Help Center 说明 Codex 覆盖 Free、Go、Plus、Pro、Business、Edu、Enterprise 等计划，但不同计划的用量限制和 credit 选项不同（OpenAI Help Center《Using Codex with your ChatGPT plan》，retrieved 2026-06-20）。如果你只是体验，可以先用当前账号测试；如果频繁开发，再评估 Plus 或 Pro。

AGENTS.md 和 config.toml 有什么区别？

AGENTS.md 管项目规则，比如项目结构、命令、代码风格、验收方式；config.toml 管 Codex 自己怎么运行，比如模型、沙箱、审批策略和环境策略。一个是“这个项目怎么做事”，一个是“Codex 默认怎么运行”。

Skills 和 Plugins 有什么区别？

Skill 更像某类任务的 SOP，例如写博客、审 PR、发版检查。Plugin 更像打包能力，里面可能包含 Skills、MCP 配置、脚本、资源或连接器。新手先用现成插件跑通真实工作流，等重复流程稳定后再写自己的 Skill。

MCP 是不是越多越好？

不是。MCP 的价值是让 Codex 读取外部系统和调用真实工具。只有当任务需要 GitHub、数据库、文档、浏览器或内部系统时才接。每新增一个 MCP，都要单独验证认证、权限、网络和最小任务。

Codex 配置里可以放 API Key 或密码吗？

不要把密钥、密码、token 放进普通文章、prompt、Memory 或公开配置示例。需要密钥时，优先用环境变量、密钥管理工具或 Codex / MCP 支持的安全配置方式。涉及私有仓库和业务数据时，账号控制权要留在自己手里。

---

最后应该怎么理解 Codex 配置？

Codex 入门的关键不是背更多命令，而是建立配置分层：临时需求放对话，项目规则放 AGENTS.md，运行默认值放 config.toml，重复流程放 Skills，外部系统交给 MCP、Apps 和 Plugins，长期偏好再放 Memory。

如果你今天只做一件事，就给常用项目补一个可执行的 AGENTS.md，再跑一次 codex doctor。等这个最小闭环稳定后，再考虑插件、MCP 和 Skills。

如果你的瓶颈不是配置，而是 Codex 额度、Plus / Pro 订阅或国内支付，可以继续看：

• Codex 额度重置咨询
• ChatGPT Plus 充值
• ChatGPT Plus 订阅服务
• ChatGPT Pro 说明

---

Sources

• 程序员成长指北，《Codex 小白入门：从安装到插件、MCP、Skills，一篇把配置讲明白》, retrieved 2026-06-20
• OpenAI Developers, “Codex | OpenAI Developers”, retrieved 2026-06-20
• OpenAI Developers, “App – Codex”, retrieved 2026-06-20
• OpenAI Developers, “CLI – Codex”, retrieved 2026-06-20
• OpenAI Developers, “Pricing – Codex”, retrieved 2026-06-20
• OpenAI Help Center, “Using Codex with your ChatGPT plan”, retrieved 2026-06-20
• npm registry, “@openai/codex latest”, retrieved 2026-06-20
• Model Context Protocol, “What is the Model Context Protocol (MCP)?”, retrieved 2026-06-20