OpenAI Codex新手入门教程 安装配置AGENTS.md与MCP全流程详解
本文关于 Codex 的基础教程，给大家从安装、配置、插件、Skills、MCP、记忆、连接 App 这些东西一次讲清楚。因为新手用 Codex 最大的问题，往往不是不会提问，而是不知道 Codex 的“几层配置”分别管什么。你可能已经装好了 Codex，也能让它改代码、写文章、解释报错，但一看到 config.toml、AGENTS.md、MCP、Plugins、Skills、Memory，脑子里马上变成一团线。
接下来我们按一个小白真正上手的顺序来：先装起来，再让 Codex 懂你的项目，然后一点点接上插件、MCP、Skills、记忆和 App。
先说明一下：Codex 更新很快。本文写作时，我本机验证的 CLI 版本是 codex-cli 0.140.0-alpha.2，时间是 2026 年 6 月 14 日。具体命令以你本机的 codex –help 和官方文档为准。本文重点讲方法和配置思路，命令只是帮你建立第一套可运行的骨架。
先记住一句话
Codex 不是只有一个聊天框。更准确地说，它像一个可以被你配置的工作台：
| 你要解决的问题 | 应该放在哪里 |
|---|---|
| 这一次任务的要求 | 当前对话 / prompt |
| 这个项目长期遵守的规则 | AGENTS.md |
| 你的全局默认设置 | ~/.codex/config.toml |
| 某类任务的标准流程 | Skills |
| 一组打包好的能力 | Plugins |
| 外部系统和工具接口 | MCP servers |
| 你的长期偏好 | Memory |
| Gmail、GitHub、Chrome 这类真实应用 | Apps / Connectors |
很多新手一开始容易犯的错，是把所有东西都塞进 prompt。比如你每次都对 Codex 说：“请先阅读项目结构，遵守我们的代码规范，运行测试，不要乱改文件，写完给我总结。”这当然能用，但很累。更好的方式是把长期规则沉淀到 AGENTS.md，把默认行为放到 config.toml，把重复工作流写成 Skill，把外部能力交给 MCP 和插件。这样 Codex 才会从“一个会回答问题的窗口”，变成“一个适合你工作流的助手”。
一、先把 Codex 装起来
Codex 现在有几种常见使用方式。
| 入口 | 更适合谁 | 你可以怎么理解 |
|---|---|---|
| Codex CLI | 程序员、经常在终端工作的人 | 在项目目录里直接让 Codex 读代码、改代码、跑命令 |
| Codex Desktop App | 想用图形界面、插件、连接 App 的人 | 更像一个完整工作台 |
| IDE 扩展 | 长时间待在编辑器里的人 | 让 Codex 跟你的代码编辑环境贴近 |
| Cloud / Web 任务 | 想把任务交给云端跑的人 | 适合并行处理或长任务 |
如果你是小白，我建议从 Codex Desktop App + CLI 这套组合开始。桌面 App 适合看插件、连接 App、管理线程；CLI 适合进入具体项目干活。
1. Codex Desktop App 怎么安装
桌面 App 的官方入口是：打开站点
如果你想直接下载安装包，也可以按系统选择：
- macOS Apple Silicon：下载 Codex.dmg；
- macOS Intel：下载 Codex-latest-x64.dmg；
- Windows：通过 Microsoft App Installer 安装。
对应直达地址如下：
macOS Apple Silicon: https://persistent.oaistatic.com/codex-app-prod/Codex.dmg macOS Intel: https://persistent.oaistatic.com/codex-app-prod/Codex-latest-x64.dmg Windows: https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi
macOS 安装步骤很简单：
- 先确认自己的芯片类型。点左上角苹果图标，选择“关于本机”，看芯片是 Apple Silicon 还是 Intel；
- 下载对应的 .dmg 文件；
- 双击打开安装包，把 Codex 拖到 Applications / 应用程序；
- 打开 Codex App，按提示登录 OpenAI 账号；
- 如果 macOS 提示安全确认，在系统设置里允许打开。
Windows 安装步骤也类似：
- 打开 Windows 下载地址；
- 按 Microsoft Store / App Installer 的提示安装；
- 安装完成后启动 Codex；
- 登录 OpenAI 账号。
- 在 App 里检查插件、连接器和本地工作区权限。
如果你已经装了 CLI，也可以在终端里运行：
codex app
这个命令会启动 Codex Desktop App。如果本机还没装 App，它会引导你去安装。
2. Codex CLI 怎么安装
CLI 的官方入口：打开站点
现在更推荐用官方 standalone installer。
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
如果你想手动下载二进制文件，可以去 GitHub Releases：打开站点
装好 CLI 以后，先跑这几个命令：
codex --version codex login codex doctor
codex login 用来登录账号。codex doctor 用来检查本地安装、配置、认证和运行时健康状态。新手遇到“为什么不能用”“为什么工具不生效”“为什么 MCP 连接不上”时，先跑它，比直接猜原因靠谱。你还可以看完整命令：
codex --help
我本机看到的常用命令包括：
| 命令 | 用途 |
|---|---|
| codex | 启动交互式 CLI |
| codex exec | 非交互执行一次任务 |
| codex review | 做代码审查 |
| codex login / logout | 管理登录 |
| codex doctor | 诊断环境 |
| codex mcp | 管理 MCP server |
| codex plugin | 管理插件 |
| codex app | 启动桌面 App |
| codex update | 更新 Codex |
你不用一开始全记住。小白阶段只要记住：
codex codex login codex doctor codex --help
够用了。
二、理解 AGENTS.md
如果只能先学一个配置文件，我建议先学 AGENTS.md。它的作用很简单：告诉 Codex，这个项目该怎么工作。比如项目怎么启动、怎么测试、代码风格是什么、哪些目录不要乱动、提交前要跑什么命令、回答时要注意什么。你可以把它理解成“写给 AI 同事看的项目说明书”。程序员必备 AGENTS.md 配置指南 规避 AI 编码修改乱象，学习 agent.md 看这篇一个最小版本可以这样写：
# AGENTS.md ## Project overview This is a Next.js project. The main app is in `apps/web`. ## Common commands - Install dependencies: `pnpm install` - Start dev server: `pnpm dev` - Run typecheck: `pnpm typecheck` - Run tests: `pnpm test` ## Coding rules - Follow existing file structure and naming style. - Prefer small, focused changes. - Do not rewrite unrelated files. - Do not add new dependencies unless necessary. ## Verification Before saying the task is complete, run the relevant check: - UI changes: run `pnpm typecheck` - Logic changes: run related tests - Large changes: run `pnpm test` If a command was not run, say it clearly.
这里最关键的不是写得多，而是写得准。我建议你在 AGENTS.md 里优先放四类内容：
| 内容 | 示例 |
|---|---|
| 项目结构 | 前端在哪里、后端在哪里、配置在哪里 |
| 常用命令 | 安装、启动、测试、构建 |
| 编码约束 | 不要改哪些文件、用什么风格、怎么命名 |
| 验收方式 | 什么情况下跑类型检查，什么情况下跑测试 |
有的小伙伴可能会问：这些东西为什么不直接写在 prompt 里？因为 prompt 是临时的，AGENTS.md 是长期的。你今天让 Codex 改登录，明天让它改列表，后天让它写测试，这些任务都应该遵守同一套项目规矩。把规矩写进 AGENTS.md，后面就不用每次重复念一遍。
三、理解 config.toml
AGENTS.md 管“项目规矩”，config.toml 管“Codex 自己怎么运行”。最常见的位置是：
~/.codex/config.toml
它通常用来配置模型、沙箱、审批策略、MCP、profile、环境变量策略等内容。你也可以临时覆盖配置。比如 CLI 帮助里可以看到这种写法：
codex -c model=\"o3\" codex -c 'sandbox_permissions=[\"disk-full-read-access\"]' codex -c shell_environment_policy.inherit=all
这说明一个重要思路：config.toml 是长期默认值，-c 是本次临时覆盖。小白阶段，不建议一上来改很多。你可以先理解这几个配置方向：
| 配置方向 | 你应该怎么理解 |
|---|---|
| model | 默认使用哪个模型 |
| sandbox | Codex 跑命令时能访问哪些文件 |
| approval | 哪些操作需要你确认 |
| MCP | 外部工具怎么接进来 |
| profiles | 给不同场景准备不同配置 |
| features | 开启或关闭某些实验能力 |
举个偏保守的理解方式：
# ~/.codex/config.toml # 示例：按你账号和当前 Codex 版本可用模型调整 model = "o3" # 新手建议不要急着开到最高权限。 # 真正需要全权限时，再在可信项目里单独开启。 sandbox_mode = "workspace-write" # 是否需要人工确认，取决于你的使用场景。 # 日常交互可以保守一点，自动化脚本可以更明确地限制。 approval_policy = "on-request"
不同版本字段可能会有变化。如果你打开后发现字段名不一样，不要慌，先看：
codex --help codex doctor
以及你当前 Codex 版本对应的官方文档。这里有一个很实用的经验：别把新手配置成 danger-full-access 起步。danger-full-access 很强，但也意味着 Codex 执行命令时拥有非常大的文件系统权限。它适合你非常信任当前工作区、并且知道自己在做什么的场景。刚开始用的时候，先用较保守的沙箱和审批策略，熟悉之后再逐步放开。
四、Plugins 是什么？
很多人听到插件，以为就是“多一个按钮”。在 Codex 里，插件更像一个能力包。一个插件里可能包含：
- 一个或多个 Skills；
- MCP server 配置；
- App / Connector 能力；
- 脚本、资源、模板；
- 插件自己的说明和元数据。
你可以用命令查看插件相关能力：
codex plugin --help
常见子命令包括：
codex plugin list codex plugin add <plugin> codex plugin remove <plugin> codex plugin marketplace list
安装插件时，命令形态大概是：
codex plugin add sample@debug codex plugin add sample --marketplace debug
小白阶段，我不建议你一口气装一堆插件。你可以按工作流选：
| 你的场景 | 优先考虑 |
|---|---|
| 写代码、看 PR | GitHub、Browser、Chrome |
| 写文章、报告 | Documents、Browser、Data Analytics |
| 做 PPT | Presentations |
| 处理表格 | Spreadsheets |
| 做产品和界面 | Product Design、Figma、Browser |
| 操作网页或桌面 | Chrome、Computer Use |
插件的价值，不是“看起来很高级”，而是让 Codex 能接触真实材料、调用真实工具、交付真实文件。比如你装了 GitHub 相关插件后，它不只是告诉你“应该怎么 review”，而是可以读取 PR、看评论、查 CI、给出修改建议。你装了 Presentations，它不只是写 PPT 文案，而是能生成真正的演示稿文件。这就是插件和普通 prompt 的差别。
五、Skills 是什么？
Skills 很适合小白理解成：把一套固定做事方法写成文件。比如你经常写公众号文章，每次都要经历：
- 定选题；
- 查资料；
- 搭大纲；
- 写初稿；
- 做配图；
- 预览；
- 改节奏。
如果每次都在 prompt 里说一遍，很麻烦。你可以把这套流程写成一个 SKILL.md，以后只要任务匹配，Codex 就能按这个方法走。Codex 的 Skills 的位置在 ，注意是在这里~/.codex/skills
一个 Skill 通常长这样：
--- name: ai-article-writer description: Use when writing long-form AI technical articles. --- # AI Article Writer ## Workflow 1. Clarify the target reader and article angle. 2. Collect reliable references. 3. Propose title options and outline. 4. Draft the article in Markdown. 5. Add diagrams when useful. 6. Render a local preview. 7. Review readability before final delivery.
注意，Skill 不是单纯的 prompt 模板。它更像一套“操作规程”。好的 Skill 会告诉 Codex：
| 要素 | 说明 |
|---|---|
| 什么时候使用 | description 写清楚触发场景 |
| 怎么做 | 明确步骤 |
| 用哪些资料 | 引用相关参考文件 |
| 用哪些脚本 | 复用已有脚本，而不是每次重写 |
| 怎么验收 | 最后检查什么 |
那 Skill 和 AGENTS.md 有什么区别？很简单：
| 文件 | 适合放什么 |
|---|---|
| AGENTS.md | 这个项目长期遵守的规则 |
| SKILL.md | 某一类任务的标准做法 |
比如“这个项目用 pnpm，不要用 npm”，应该放 AGENTS.md。比如“写公众号文章前必须先做选题定位，再写大纲”，应该放 Skill。
六、MCP 是什么？
MCP 全称是 Model Context Protocol。你可以先不用记英文，只要记住它解决的问题：让 Codex 通过标准协议连接外部工具和数据源。比如：
| MCP 能连接什么 | 典型用途 |
|---|---|
| GitHub | 读取 PR、Issue、文件、CI |
| 数据库 | 查询业务数据 |
| 文档系统 | 读取团队知识库 |
| 浏览器 | 打开页面、检查 UI |
| 搜索服务 | 查找外部资料 |
| 内部系统 | 调用你们自己的工具 |
在 CLI 里可以用：
codex mcp --help
我本机看到的常用子命令包括：
codex mcp list codex mcp get <name> codex mcp add <name> --url <url> codex mcp add <name> -- <command> codex mcp remove <name> codex mcp login <name> codex mcp logout <name>
添加 MCP server 有两种常见方式。第一种是 HTTP 方式：
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
第二种是本地命令方式：
codex mcp add my-tool -- node server.js
如果需要环境变量，也可以看到类似这种形式：
codex mcp add my-tool --env API_KEY=$MY_TOOL_API_KEY -- node server.js
实际使用时，不建议把真实密钥直接写在命令里。更好的方式是放在环境变量中，或者使用 Codex / MCP 支持的安全配置方式。
如果以上 cli 你都不喜欢，也可以通过 codex 桌面端安装和使用 mcp：
在这里可以看到你安装的 MCP 并增加 MCP 小白理解 MCP，可以抓住一个判断标准：凡是 Codex 需要读取外部系统、调用外部工具、访问实时数据，就优先想 MCP 或 App Connector。不要让模型凭记忆回答你的私有数据。比如你问：“我们项目最近哪个 PR 没过 CI？”这类问题不应该让 Codex 猜，也不应该让你复制粘贴一堆网页内容。更合理的方式是接 GitHub，然后让 Codex 直接读取真实 PR 和检查结果。
七、Memory 记忆功能怎么用？
Memory 很容易被误解。它不是让 Codex 记住所有事实，也不是你的私人数据库。它更适合记住长期偏好和稳定习惯。如何开启 Memory？仍然从设置进入，选择个性划，然后开启记忆，开启记忆后你会发现你在 chatgpt 中的对话也会包含你的习惯记忆等。
适合放进 Memory 的内容：
| 适合记 | 示例 |
|---|---|
| 写作偏好 | 我喜欢中文技术文章，风格实战、少空话 |
| 常用工作方式 | 修改代码后要跑 typecheck |
| 长期称呼偏好 | 回答我时用中文 |
| 稳定背景 | 我经常写公众号 AI 工具文章 |
不适合放进 Memory 的内容：
| 不适合记 | 原因 |
|---|---|
| 密码、token、密钥 | 安全风险太高 |
| 今天的新闻 | 很快过期 |
| 某个 PR 当前状态 | 应该从 GitHub 实时读取 |
| 临时任务要求 | 放当前对话就够了 |
一句话：Memory 记偏好，不记事实；记习惯，不记机密。如果你希望 Codex 长期记住“我写文章喜欢实战风格”，放 Memory 很合适。如果你希望 Codex 知道“这个项目怎么启动”，放 AGENTS.md 更合适。如果你希望 Codex 知道“GitHub 上这个 PR 当前是否通过 CI”，那应该接 GitHub App 或 MCP。
八、怎么连接 App，让 Codex 真正操作起来
Codex 的强大，不只是能写答案，而是能连接真实工具。常见 App / Connector 包括：
| App / Connector | 能做什么 |
|---|---|
| GitHub | 读仓库、看 PR、查 Issue、处理 review |
| Gmail | 搜索邮件、总结线程、提取待办、起草回复 |
| Google Drive / Docs | 读取文档、整理资料 |
| Figma | 读取设计稿、辅助设计到代码 |
| Browser | 打开网页、测试本地页面、截图验收 |
| Chrome | 使用你的 Chrome 登录状态操作网页 |
| Computer Use | 操作本地桌面应用 |
这里要分清楚两个概念：
| 类型 | 更像什么 |
|---|---|
| MCP | 标准协议接口，适合工具和数据源 |
| App / Connector | 已授权的真实应用连接 |
举个例子，你要让 Codex 看 GitHub PR，有几种可能：
- 通过 GitHub 插件；
- 通过 GitHub App / Connector；
- 通过 MCP server；
- 通过 gh CLI。
它们不是互斥的。实际工作中，Codex 往往会优先使用当前环境里已经可用、权限合适、最稳定的入口。小白阶段，你只要记住一个安全原则：读取可以更自动，写入必须谨慎。 比如读取 PR、总结邮件、打开网页，一般风险较低。但发送邮件、提交表单、删除文件、发布文章、改权限、付款、发消息，这些动作一定要让 Codex 先停下来给你确认。把 AI 当成有人监督的助手，而不是完全放飞的机器人。
小白第一次配置，按这个顺序来
别一开始就追求“全配满”。更好的顺序是：
你可以按下面这套路线走：
- 安装 Codex，完成登录；
- 运行 codex doctor，确认环境正常；
- 在项目根目录写一个简单的 AGENTS.md；
- 只改必要的 config.toml，先别开太多高权限；
- 先接一个最常用的插件，比如 GitHub 或 Browser；
- 如果你经常重复某类任务，再写 Skill；
- 需要外部数据时，再配置 MCP；
- 最后再考虑把长期偏好放进 Memory。
这套顺序的好处是，你每一步都能验证。很多人一上来装十几个插件、配五六个 MCP、写一大堆全局规则，最后出问题时根本不知道是哪一层坏了。小白阶段最重要的不是炫技，而是能定位问题。
给你一套基础配置模板
下面这套模板可以作为起点，不建议无脑复制到所有项目里，但你可以按自己的项目改。
1. 项目根目录 AGENTS.md
# AGENTS.md ## Project overview Briefly describe what this project does and where the main code lives. ## Common commands - Install: `pnpm install` - Dev: `pnpm dev` - Typecheck: `pnpm typecheck` - Test: `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 marking work complete: - Run the most relevant check. - If checks cannot run, explain why. - Do not claim tests passed unless they were actually run.
2. 全局 config.toml
# ~/.codex/config.toml # Pick the model you normally want Codex to use. # 示例：按你账号和当前 Codex 版本可用模型调整 model = "o3" # Conservative default for local coding work. sandbox_mode = "workspace-write" # Let Codex ask when it needs permission for sensitive operations. approval_policy = "on-request" # You can add MCP servers below when needed. # [mcp_servers.example] # command = "node" # args = ["server.js"]
如果你的 Codex 版本提示字段不识别，先不要硬改，跑：
codex doctor codex --help
再根据当前版本调整。
3. 一个最小 Skill 模板
--- name: project-review description: Use when reviewing a feature implementation before merge. --- # Project Review ## Workflow 1. Read the requirement or issue. 2. Inspect changed files. 3. Look for bugs, regressions, missing tests, and risky assumptions. 4. Run or recommend relevant verification commands. 5. Report findings first, then summarize. ## Output - Findings with file references. - Test gaps. - Suggested next steps.
4. MCP 添加命令模板
# HTTP MCP server codex mcp add <name> --url <server-url> # Local stdio MCP server codex mcp add <name> -- <command> <args> # Check configured MCP servers codex mcp list
这里最重要的是 <name> 要起得清楚，比如 github、docs、postgres-readonly，不要叫 test1、abc。后面排查问题时，清楚的名字会救命。
常见坑
1. 把 AGENTS.md 写成散文
AGENTS.md 不是给人看的项目宣传稿，而是给 Codex 执行任务时用的操作说明。少写愿景，多写命令、约束和验收方式。
2. 一开始就开最高权限
新手刚开始不要追求“无确认自动跑完”。AI 工具越能操作真实系统，越要有边界。先用保守权限跑通工作流，再根据需要放开。
3. MCP 配好了但忘了验证
配完 MCP 后，先跑：
codex mcp list codex doctor
能列出来只是第一步，真正任务里能不能调用，还要看认证、网络、权限和 server 本身是否正常。
4. 插件装太多
插件不是越多越好。你真正需要的是工作流。如果你每天都写代码，先把 GitHub、Browser 这类接好。如果你每天写文章，先把 Documents、Browser、图片生成或预览流程跑通。装一堆不用的插件，只会让你更困惑。
5. 把 Memory 当事实库
Memory 适合记偏好，不适合记实时事实。项目状态、PR 状态、数据库数据、新闻变化，都应该从真实来源读取。
6. 不区分“读”和“写”
让 Codex 读取资料、总结内容、检查页面，风险通常较低。让 Codex 发送邮件、发布文章、删除文件、提交表单、改权限，风险就高很多。涉及外部副作用的动作，最好都让它先停下来确认。
总结
如果你刚开始用 Codex，我建议先别急着研究所有高级配置。第一周只做三件事：
- 每个项目补一个 AGENTS.md；
- 学会用 codex doctor 排查问题；
- 只接一个你最需要的插件或 App。
等你发现某个任务每周都在重复，比如写文章、review PR、整理周报、做 PPT、查数据，再把它沉淀成 Skill 或插件工作流。
Codex 真正厉害的地方，不是你一次 prompt 写得多华丽，而是你能把自己的工作方式一点点沉淀下来。
今天写进 AGENTS.md 的项目规则，明天接上的 GitHub，后天固化成 Skill 的写作流程，都会让它越来越像你的工作台。
对小白来说，最好的入门路线不是“学完所有概念再开始用”，而是先跑起来，再把反复出现的问题放到正确的位置。
这篇文章你如果只记住一张图，就记住前面的七层配置地图：
临时需求放对话，项目规则放 AGENTS.md，运行默认值放 config.toml，重复流程放 Skills，外部能力交给 Plugins、MCP 和 Apps，个人偏好再放进 Memory。把这几层分清楚，Codex 就不再是一堆陌生名词，而是一套你能慢慢搭起来的 AI 工作系统。
以上关于OpenAI Codex新手入门教程 安装配置AGENTS.md与MCP全流程详解的文章就介绍到这了，更多相关内容请搜索码云笔记以前的文章或继续浏览下面的相关文章，希望大家以后多多支持码云笔记。
微信
支付宝如若内容造成侵权/违法违规/事实不符，请将相关资料发送至 admin@mybj123.com 进行投诉反馈，一经查实，立即处理！
重要：如软件存在付费、会员、充值等，均属软件开发者或所属公司行为，与本站无关，网友需自行判断
码云笔记 » OpenAI Codex新手入门教程 安装配置AGENTS.md与MCP全流程详解
