Codex 小白入门：从安装到插件、MCP、Skills，一篇把配置讲明白

Codex 小白入门从安装到插件、MCP、Skills一篇把配置讲明白因为新手用 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你的长期偏好MemoryGmail、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 的官方入口是https://developers.openai.com/codex/app如果你想直接下载安装包也可以按系统选择macOS Apple Silicon下载Codex.dmgmacOS Intel下载Codex-latest-x64.dmgWindows通过 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?cidwebsite_cta_psimacOS 安装步骤很简单先确认自己的芯片类型。点左上角苹果图标选择“关于本机”看芯片是 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 的官方入口是https://developers.openai.com/codex/cli现在更推荐用官方 standalone installer。macOS / Linux 可以这样安装curl -fsSL https://chatgpt.com/codex/install.sh | shWindows PowerShell 可以这样安装irm https://chatgpt.com/codex/install.ps1 | iex如果你习惯用包管理器也可以选下面几种方式# npm npm install -g openai/codex # Homebrew brew install --cask codex如果你想手动下载二进制文件可以去 GitHub Releaseshttps://github.com/openai/codex/releases装好 CLI 以后先跑这几个命令codex --version codex login codex doctorcodex login用来登录账号。codex doctor用来检查本地安装、配置、认证和运行时健康状态。新手遇到“为什么不能用”“为什么工具不生效”“为什么 MCP 连接不上”时先跑它比直接猜原因靠谱。你还可以看完整命令codex --help我本机看到的常用命令包括命令用途codex启动交互式 CLIcodex exec非交互执行一次任务codex review做代码审查codex login/logout管理登录codex doctor诊断环境codex mcp管理 MCP servercodex plugin管理插件codex app启动桌面 Appcodex update更新 Codex你不用一开始全记住。小白阶段只要记住codex codex login codex doctor codex --help够用了。第二步理解AGENTS.md如果只能先学一个配置文件我建议先学AGENTS.md。它的作用很简单告诉 Codex这个项目该怎么工作。比如项目怎么启动、怎么测试、代码风格是什么、哪些目录不要乱动、提交前要跑什么命令、回答时要注意什么。你可以把它理解成“写给 AI 同事看的项目说明书”。一个最小版本可以这样写# 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. 作者ikoala 链接https://juejin.cn/post/7661983059005816858 来源稀土掘金 著作权归作者所有。商业转载请联系作者获得授权非商业转载请注明出处。这里最关键的不是写得多而是写得准。我建议你在AGENTS.md里优先放四类内容内容示例项目结构前端在哪里、后端在哪里、配置在哪里常用命令安装、启动、测试、构建编码约束不要改哪些文件、用什么风格、怎么命名验收方式什么情况下跑类型检查什么情况下跑测试有的小伙伴可能会问这些东西为什么不直接写在 prompt 里因为 prompt 是临时的AGENTS.md是长期的。你今天让 Codex 改登录明天让它改列表后天让它写测试这些任务都应该遵守同一套项目规矩。把规矩写进AGENTS.md后面就不用每次重复念一遍。第三步理解config.tomlAGENTS.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.inheritall这说明一个重要思路config.toml是长期默认值-c是本次临时覆盖。小白阶段不建议一上来改很多。你可以先理解这几个配置方向配置方向你应该怎么理解model默认使用哪个模型sandboxCodex 跑命令时能访问哪些文件approval哪些操作需要你确认MCP外部工具怎么接进来profiles给不同场景准备不同配置features开启或关闭某些实验能力举个偏保守的理解方式# ~/.codex/config.toml # 示例按你账号和当前 Codex 版本可用模型调整 model o3 # 新手建议不要急着开到最高权限。 # 真正需要全权限时再在可信项目里单独开启。 sandbox_mode workspace-write # 是否需要人工确认取决于你的使用场景。 # 日常交互可以保守一点自动化脚本可以更明确地限制。 approval_policy on-request 作者ikoala 链接https://juejin.cn/post/7661983059005816858 来源稀土掘金 著作权归作者所有。商业转载请联系作者获得授权非商业转载请注明出处。不同版本字段可能会有变化。如果你打开后发现字段名不一样不要慌先看codex --help codex doctor以及你当前 Codex 版本对应的官方文档。这里有一个很实用的经验别把新手配置成danger-full-access起步。danger-full-access很强但也意味着 Codex 执行命令时拥有非常大的文件系统权限。它适合你非常信任当前工作区、并且知道自己在做什么的场景。刚开始用的时候先用较保守的沙箱和审批策略熟悉之后再逐步放开。第四步Plugins 是什么很多人听到插件以为就是“多一个按钮”。在 Codex 里插件更像一个能力包。一个插件里可能包含一个或多个SkillsMCP server 配置App / Connector 能力脚本、资源、模板插件自己的说明和元数据你可以用命令查看插件相关能力codex plugin --help常见子命令包括codex plugin list codex plugin add plugin codex plugin remove plugin codex plugin marketplace list安装插件时命令形态大概是codex plugin add sampledebug codex plugin add sample --marketplace debug如果你使用桌面 App也可以在插件入口里搜索、安装、启用。小白阶段我不建议你一口气装一堆插件。你可以按工作流选你的场景优先考虑写代码、看 PRGitHub、Browser、Chrome写文章、报告Documents、Browser、Data Analytics做 PPTPresentations处理表格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. 作者ikoala 链接https://juejin.cn/post/7661983059005816858 来源稀土掘金 著作权归作者所有。商业转载请联系作者获得授权非商业转载请注明出处。注意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可以抓住一个判断标准凡是 Codex 需要读取外部系统、调用外部工具、访问实时数据就优先想 MCP 或 App Connector。不要让模型凭记忆回答你的私有数据。比如你问“我们项目最近哪个 PR 没过 CI”这类问题不应该让 Codex 猜也不应该让你复制粘贴一堆网页内容。更合理的方式是接 GitHub然后让 Codex 直接读取真实 PR 和检查结果。第七步Memory 记忆功能怎么用Memory很容易被误解。它不是让 Codex 记住所有事实也不是你的私人数据库。它更适合记住长期偏好和稳定习惯。适合放进 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、处理 reviewGmail搜索邮件、总结线程、提取待办、起草回复Google Drive / Docs读取文档、整理资料Figma读取设计稿、辅助设计到代码Browser打开网页、测试本地页面、截图验收Chrome使用你的 Chrome 登录状态操作网页Computer Use操作本地桌面应用这里要分清楚两个概念类型更像什么MCP标准协议接口适合工具和数据源App / Connector已授权的真实应用连接举个例子你要让 Codex 看 GitHub PR有几种可能通过 GitHub 插件通过 GitHub App / Connector通过 MCP server通过ghCLI它们不是互斥的。实际工作中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 工作系统。