Codex 会火起来不是因为它又多了一个聊天入口而是它把你从一个只会回话的对话框变成了一个真正能操作终端、修改文件、执行命令的编程智能体。这套教程以当前版本的 Codex CLI 为例重点讲三个最值得先理解的能力计划模式、记忆系统、MCP。它们分别解决“动手前不思考”“跨会话总失忆”“只能聊不能干”的问题。如果你是第一次接触命令行建议从第 1 章顺着看如果已经会装 Node.js、Git可以直接跳到第 3 章如果只是想解决 MCP 工具注册不上先看第 6.4 节。这篇内容不会面面俱到地复述官方文档我会按实际落地顺序把环境准备、安装登录、功能使用、常见报错和排查路径一次讲完。1. 要装的不是“一个软件”而是一套终端工作流1.1 Codex 解决的三个实际问题很多人第一次打开 Codex会期待它像 ChatGPT 网页版一样输入文字然后看输出。但 Codex 的定位不太一样它更像一个住在终端里的智能体能读取你的项目结构、查看文件内容、执行命令然后基于真实环境给出改动。这里最直接的价值有三个不用再把错误信息复制到聊天框再手动把改好的代码粘贴回来。它能跑测试、查日志、改文件名、做 Git 操作不需要你一步步告诉它命令。它能把“分析-修改-验证”串成一条流程而不是只给你一段静态代码。换句话说Codex 解决的不是“帮我写一段函数”而是“帮我把这个项目按我的要求改好并确认没改坏”。1.2 计划模式、记忆系统、MCP 分别解决什么问题这三样东西经常被放在一起但很多人理解得比较模糊。计划模式解决的是“动手前先想清楚”。Codex 可以先产出一份改动方案不碰你的文件。你看完方案确认没问题再让它进执行模式。对刚接触 AI 写代码的人来说这一步是保命项。记忆系统解决的是“换一个会话后它还记得你的规矩”。比如你的项目用 pnpm、代码风格不允许分号、测试命令必须是npm run test:unit。这些信息如果每次都要重新写一遍很累放进记忆文件Codex 每次启动都会读到。MCP 解决的是“它只能读文本但拿不到项目外面的信息”。通过 MCPCodex 可以调用文件系统、浏览器、Figma 设计稿、数据库、联网搜索等外部工具相当于给它接上不同能力的“手”。1.3 常见误区Codex 不是普通代码补全插件我经常看到有人把 Codex 和 IDE 里的代码补全插件比较然后说它不够快。这不是一个东西。补全插件预测你下一个字符Codex 是接收一个任务、分析多个文件、执行命令、然后向你报告结果。还有人会把 Codex 和 ChatGPT 网页版里的“代码解释器”搞混。网页版擅长小范围分析但通常不能连续操作你本地的工程目录。Codex 的优势在于工作目录真实可见改的就是你本机的文件所以它的上下文更接近一个开发者的现场。理解这个差异后你再去看安装步骤和参数配置就会清楚每个环节在为什么服务。2. 安装前置环境Node.js、Git、WSL 这些到底要不要装2.1 为什么先要准备 Node.js 和 npmCodex CLI 最常见的安装方式是通过 npm 全局安装。npm 是 Node.js 自带的包管理器所以第一步通常是安装 Node.js。如果你机器上已经有 Node.js先用命令确认版本node -v npm -v如果输出的是类似v18.12.0、9.6.7这样的内容说明环境基本可用。如果提示command not found就需要先去 Node.js 官网下载安装包或者用系统包管理器安装。这里要注意一个点不要只看有没有装还要看版本够不够新。Codex 这类工具对 Node.js 版本有基础要求版本太老会出现安装成功但跑不起来的情况。常见要求是 Node 18 或更高具体以当前安装页的说明为准。2.2 Git 也要提前装好很多人觉得 Git 只是用来提交代码的Codex 未必需要。实际上Codex 在项目里经常要读取 Git 状态、判断文件改动、执行git diff或git log。如果项目本身是 Git 仓库而机器上没有 Git很多流程会卡住。另外不少 MCP Server 也是通过npx拉取的甚至有些服务配置依赖 Git 命令。建议先把 Git 装好并确认git --version能正常输出。装完之后如果第一次使用 Git建议先配置用户名和邮箱git config --global user.name Your Name git config --global user.email youexample.com不配置也能用 Codex但以后提交代码时会遇到身份校验问题提前写好省事。2.3 Windows 用户建议先确认 WSLWindows 下跑 Codex 有两种常见方式直接在 Windows 终端跑或者在 WSL 里跑。如果你只是想快速体验Windows 终端通常够用。但如果你的项目运行环境依赖 Linux比如很多 Python、Docker、Shell 脚本建议优先在 WSL 里操作。WSL 的好处是目录风格、命令行为、权限模型都更接近服务器环境Codex 执行命令时不容易出现“Windows 能跑、Linux 跑不了”的偏差。查看 WSL 状态wsl --status wsl --list --verbose如果没安装 WSL或者提示没有已安装的分发版需要先完成 WSL 安装。这个过程不复杂但比较耗时建议放在环境准备阶段做不要等 Codex 报错再回来补。2.4 一套环境自检清单我每次在新机器上配置开发环境都会先做一轮自检。下面这张表可以帮你判断“现在能不能开始装 Codex”。检查项命令通过标准Node.jsnode -v输出版本号建议 18 或更高npmnpm -v输出版本号Gitgit --version输出类似 2.x 版本WSLWindowswsl --status有默认分发版且能启动终端能否访问 npmnpm config get registry输出 registry 地址如果registry输出的是一个不常见的私有地址后面安装 Codex 时可能超时需要根据你的网络环境决定是否调整。2.5 安装完成后优先重启终端很多新手在安装完 Node.js 或 Git 后直接在旧终端里跑命令还是提示找不到。这不是安装失败而是 PATH 环境变量没有重新加载。最简单的方法是把终端窗口全部关掉重新开一个。如果重启终端仍然提示command not found再检查安装路径是否真的进入了 PATH。这一步不解决后面所有命令都会受阻。3. Codex CLI 安装与登录从空目录跑通第一句“你好”3.1 用 npm 安装 Codex CLI环境准备好之后安装 Codex 的命令通常很简单npm install -g openai/codex输入命令后npm 会从 registry 拉取包。安装完成后验证是否成功codex --version如果输出了一个版本号说明 CLI 本体已经装好。这里我要强调一下安装成功和真正能跑是两回事。很多人到codex --version这里很顺利但进入会话后就报错。所以验证步骤不要只停留在--version一定至少跑一次真实会话。3.2 登录与鉴权先确认你的账号或 API KeyCodex 需要鉴权才能调用模型。常见方式有两种使用 ChatGPT 账号登录通过浏览器完成授权。配置 API Key让 CLI 通过接口鉴权。登录命令通常是codex login如果使用 API Key一般需要把它配置到环境变量里然后在 Codex 的配置文件里指定。具体变量名以当前版本为准常见的是OPENAI_API_KEY。这里不建议直接在当前终端里明文导出 Key尤其不要在截图或博客里展示完整 Key。可以先把 Key 写入本地环境变量文件再让终端读取。3.3 最小可运行验证问一个与当前目录有关的问题我建议第一次运行不要问“帮我写个贪吃蛇”这种大而全的问题而是切到一个空目录问一个能立刻看到结果的小任务mkdir -p ~/codex-demo cd ~/codex-demo codex 告诉我当前目录里有哪些文件以及这个目录的绝对路径如果 Codex 能正确回答说明它已经能读取工作目录、调用基础命令、返回结果。这就是最基础的“跑通”。如果一上来就让它生成一个全栈项目一旦报错你可能分不清是网络问题、鉴权问题、模型问题还是项目环境问题。3.4 常见错误找不到 codex cli binary / 命令不存在很多报错文本里会出现unable to locate the codex cli binary这类描述。这个错误通常不是 Codex 本身坏了而是调用方找不到 Codex CLI 的路径。常见场景有三种你在 IDE 扩展、聊天客户端或自动化工具里配置了 Codex但工具所在进程的 PATH 里没有 CLI。npm install -g安装的全局目录不在系统 PATH 中。你安装了多个版本的 Node.js全局路径发生了切换。排查顺序建议这样在正常终端里运行which codex确认 CLI 路径。运行npm prefix -g看看全局包安装到了哪个目录。确认该目录是否在 PATH 中。如果是 IDE 扩展报错看扩展设置里有没有 CLI 路径配置项手动填上which codex的输出。不要一上来就卸载重装。这类问题大概率是路径没对上重装解决不了。4. 计划模式先让 Codex 思考再让它动手4.1 为什么不要一上来就让它直接改Codex 的执行能力很强但强不等于安全。如果它直接修改文件可能一次性改动十几个文件而你还没看清方案。等项目跑不起来再回头追溯是哪一步改错的成本非常高。计划模式就是为了解决这个问题。它让 Codex 先基于当前项目状态做分析产出一份“准备怎么做”的方案然后停下来等你确认。我自己使用时的原则是修改文件数量达到三个以上或者会新增依赖、改动目录结构、影响启动流程时一律先进计划模式。4.2 怎么进入计划模式在 Codex 会话中通常可以直接使用/plan命令进入计划模式或者在提问时明确说“先不要改代码先给我一份改动计划”。一个比较稳妥的提示词模板请先不要修改任何文件也不要执行写操作。分析当前项目结构然后给出一份计划计划里必须包含 1. 涉及的文件路径 2. 每个文件的改动点 3. 改动顺序 4. 如何验证改动是否正确 5. 可能的风险如果 Codex 开始输出文件修改内容说明它可能已经离开计划模式。你可以马上中断再用上面的提示词重新约束。4.3 计划模式擅长和不擅长的事情计划模式适合复杂需求拆分、重构方案设计、新增功能前的技术评估。它不适合写一句话总结、查询变量定义这类轻量任务。计划也不是越详细越好。如果一个任务只需要改一行配置还强行写五段计划反而浪费时间。我的判断标准是改动是否涉及多个文件、是否有执行风险、是否会影响项目行为。三者有一项成立就值得走一遍计划模式。4.4 怎么判断一份计划靠不靠谱除了看整体思路更关键的是看细节。一份可执行的计划应该包含具体文件路径而不是笼统的“修改相关配置”。具体命令而不是“运行测试”。验证方式能落到某个测试用例或某个检查点。回滚方案改坏了至少知道怎么恢复。如果计划里全是“优化代码结构”“提升可维护性”这种正确但无法验证的话说明它还没有真正理解项目。你可以让它把计划细化或者换一种提示方式。5. 记忆系统让 Codex 记住项目规范而不是每次重新说5.1 记忆系统到底存在哪里Codex 的记忆系统没有做成不可见的黑盒它通常依赖项目目录下的说明文件。最常见的是在项目根目录放一个AGENTS.md文件让 Codex 进入项目时自动读取。这个文件的作用相当于给这个项目写了一份“给 AI 的入职手册”。Codex 会在处理任务前读到里面的内容然后在上下文里持续参考。除了项目级记忆通常还有用户级或全局记忆。全局记忆适合放一些所有项目通用的偏好比如“我习惯用双引号”“提交信息用中文”“不要删除未被引用的文件”。项目级记忆则放这个项目独有的规则。5.2 哪些内容适合写进 AGENTS.md不是所有内容都值得写。写得太长Codex 读取时会占用上下文反而影响处理速度。建议优先写以下内容分类示例技术栈React TypeScript Vite包管理器用 pnpm目录约定src/components只放 UI 组件src/api只放接口请求常用命令开发启动npm run dev类型检查npm run typecheck代码风格组件使用函数组件不写 Class样式使用 CSS Modules明确禁止不要删除某个legacy目录不要在main分支直接提交提交规范commit message 用中文前缀如fix:、feat:写完AGENTS.md后我会新建一个会话问 Codex“当前项目有哪些开发规范”看它能不能准确说出来。如果它能答上来说明记忆文件已经被正确读取。5.3 记忆系统和 Prompt 的区别Prompt 是临时的会话结束就没了。记忆系统是持久的每次新会话都会自动加载。很多人容易犯的错是把很长的背景说明写在每次对话里。比如每次都用“我们是一个电商项目前端用 Vue 3后端是 Go数据库是 MySQL……”开头。这些内容放进记忆文件后就不用重复了。反过来一次性的任务上下文不适合写进记忆。比如“我今天要修复支付回调超时问题”这类信息是当前任务的一部分放进 AGENTS.md 反而会让后续会话误以为它需要一直关注支付问题。5.4 Agent Skill 和 MCP 有什么区别这个词近来容易被混淆。我的理解是Agent Skill 是一套操作方法论MCP 是连接外部工具的标准接口。举例来说如果你希望 Codex 能写端到端测试你可以给它一个 Skill里面包含“先启动测试环境、再通过 Playwright 打开页面、记录失败截图、输出测试报告”这样的步骤。而 Playwright MCP Server 负责的是提供浏览器控制能力让 Codex 真正能打开页面、点击元素、读取 DOM。一个解决“怎么做”一个解决“用什么工具”。实际使用中两者可以配合Skill 告诉 Codex 做事流程MCP 给它执行流程时需要的工具。6. MCP 接入给 Codex 装工具而不是让它只聊代码6.1 MCP 是什么为什么值得配MCP 全称是 Model Context Protocol是一种让 AI 模型与外部工具进行标准通信的协议。Codex 通过 MCP Client 连接各种 MCP Server每个 Server 暴露一组工具能力。没有 MCP 时Codex 的“手”很有限主要靠文件读写和终端命令。接入 MCP 后它可以扩展出很多能力比如打开浏览器、读取设计稿、操作数据库、访问远程 API。这也是为什么很多教程强调 MCP它决定了 Codex 能从一个“终端助手”升级成“工程自动化入口”。6.2 常见的 MCP Server 有哪些适用场景选 MCP 不是越多越好而是看你的使用场景。以下是几类常见的 MCP 对应能做的事MCP Server典型用途Filesystem提供更精确的文件访问能力跨目录读写Playwright控制浏览器做自动化测试、抓取页面信息Figma读取设计稿中的图层、样式、组件信息联网搜索让 Codex 获取项目外的最新信息数据库查看表结构、执行只读查询、定位数据问题自定义脚本 MCP把公司内部命令封装成工具暴露给 Codex从实用角度讲先配一个文件系统 MCP 或 Playwright MCP比一次配五六个更稳妥。因为 MCP 越多Codex 需要理解的工具描述也越多容易出现“工具注册不上”或者“调用时选错工具”的情况。6.3 配置 MCP 的步骤和 .mcp 文件MCP 的配置通常分为全局配置和项目级配置。全局配置放在你的用户目录下适用于所有项目项目级配置放在项目里只对当前项目生效。不少项目会使用.mcp.json来声明项目需要的 MCP Server。这个文件的好处是跟着仓库走团队成员拉下来就能用同一套 MCP 配置。一个示意配置长这样{ mcpServers: { playwright: { command: npx, args: [-y, playwright/mcplatest] } } }如果你的客户端使用config.toml风格的配置那么大概会写[mcp_servers.playwright] command npx args [-y, playwright/mcplatest]要注意工具名、参数、版本号都可能随版本变化。我一般不会直接复制网上配置而是先去对应 MCP Server 的官方仓库确认启动命令。毕竟路径和参数写错Codex 会直接提示工具注册失败。6.4 MCP 工具注册不上的排查顺序“MCP 工具注册不上”是我看到最多的报错之一比如 Figma MCP 在 Codex 里总是注册不上。遇到这类问题不要先怀疑 Codex按顺序排查先确认 MCP Server 能否独立启动。在终端直接执行配置里的 command 和 args看有没有报错。检查依赖是否安装。很多 MCP Server 通过npx启动第一次运行会下载包网络不稳定会导致失败。检查配置里的路径和名称。尤其是 Windows 下命令路径可能带反斜杠JSON 里需要转义。检查权限。Figma MCP 需要 API Token文件系统 MCP 需要目录访问权限。检查客户端是否重新加载了配置。有的配置修改后必须重启会话甚至重启整个应用。看日志。Codex 或 MCP Server 的控制台日志里通常会写明是“找不到命令”“链接失败”还是“鉴权失败”。还有一个细节如果一个 MCP Server 需要监听固定端口你要确认端口没有被其他进程占用。启动失败不会马上在 Codex 里显示而是在 MCP Server 自己的启动日志里。6.5 为什么不要一次接太多 MCP每接入一个 MCP ServerCodex 就要在每次请求时把工具列表发给模型。工具太多会占用上下文窗口还可能让模型在多个相似工具之间选错。例如你同时接了文件系统 MCP、Git MCP、数据库 MCP让 Codex“查看项目里的数据库配置”它可能打开文件系统工具读取了配置文件也可能直接用数据库 MCP 查了表结构。二者差别很大。我建议按任务划分这周主要做自动化测试就只保留 Playwright MCP下周要起新项目再临时加文件系统或脚手架相关 MCP。用到哪个开哪个不用就关。7. 把 Codex 接进自己的模型或项目常见自定义配置7.1 为什么有人要把 Codex 接到其他模型服务Codex 默认使用的模型是 OpenAI 官方服务但有些开发场景会需要切换模型团队内部使用了兼容 OpenAI 协议的其他模型服务。想尝试 DeepSeek 等不同模型在编码任务上的表现。有私有化部署的大模型接口希望 Codex 统一连接。这些做法本质上都是通过配置 Base URL 和模型名让 Codex 把请求发到特定服务。前提是该服务提供兼容的 API。7.2 通用配置字段base_url、env_key、modelCodex 的自定义模型配置通常在配置文件里完成。我不建议完全照搬网上的完整配置因为不同版本字段会有差异但大体会涉及几个字段base_url接口服务地址。env_key从哪个环境变量读取 API Key。model使用的模型名称。provider模型提供方标识。一个示意配置可能长这样[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY [model_profiles.codex_deepseek] provider deepseek model deepseek-chat如果是在接 DeepSeek去 DeepSeek 开放平台创建 API Key然后配置到环境变量里最后在 Codex 配置里选择对应 provider 和模型名。注意具体字段名要以你安装的 Codex 版本为准。你可以用类似codex --help或配置文件的注释信息快速确认不要假设所有版本都一样。7.3 第三方模型接入的典型流程我自己的验证顺序是先在 API 服务方后台确认可用模型列表。用 curl 或官方 SDK 直接调用一次接口确认 API Key 有效。再把它配置到 Codex。最后用一句“解释一下当前目录的 package.json”来验证而不是一上来就跑复杂任务。先单独验证 Model Provider 的接口可以隔离问题。如果 Provider 本身就调不通Codex 侧怎么调都不会成功。7.4 模型不支持、端点报错的排查顺序我见过很多类似“某个模型名在当前服务里不支持”的报错原因通常不是 Codex 装错了而是模型名或服务配置不对。排查顺序看模型名是否准确。注意大小写、连字符、版本后缀。看当前 Provider 是否支持这个模型。DeepSeek 的服务支持哪些模型以它的文档为准。看 API Key 是否有权限。有的 Key 只允许访问默认模型不能访问新的实验模型。看base_url是否正确。地址末尾是否需要/v1不同服务要求不同。看环境变量是否被 Codex 正确读取。有时你设置了变量但终端没有重新加载。如果错误文本里出现本地连接失败、端点无法处理请求之类的提示先检查请求真正发到了哪个地址再检查网络和证书配置。不要一碰到“端点无法处理”就去改代码逻辑先确认请求有没有到目标服务。这是很多配置问题的根源。7.5 多项目配置不同项目用不同模型和 MCP当你开始多项目并行全局配置就会不够用。一个项目可能要接 Figma MCP另一个项目需要接数据库 MCP还有一个项目想用第三方模型。常见的做法是全局配置放通用模型信息。项目级配置放当前项目特有的 MCP 和模型。在项目根目录维护.mcp.json让项目成员共享工具配置。必要时为不同项目建立不同的 Codex 会话或工作目录。这样不会出现“A 项目配的 MCP 干扰了 B 项目”的情况。8. 从“能跑”到“能用”落地顺序和排查清单8.1 建议的落地顺序如果你刚把 Codex 装好我建议不要一次性把计划模式、记忆系统、MCP 全配齐而是按下面顺序推进先跑通一个最小会话能读取当前目录回答简单问题。在空项目里试一次计划模式不修改任何文件只让它出方案。新建一个AGENTS.md写入三到五条项目规则重启会话验证记忆是否生效。接入一个最常用的 MCP比如 Playwright 或文件系统跑通一次工具调用。再考虑切换第三方模型或多模型配置。这个顺序的核心逻辑是每一步都建立在下一步可验证的基础上。如果你连最小会话都没跑通接 MCP 只会让你分不清是 MCP 的问题还是基础环境的问题。8.2 一套可以贴在工位上的排查清单下面这张表是我平时会优先看的排查路径不一定覆盖所有细节但能解决大多数“装完不会用”的问题。现象第一件事大概率原因command not found重开终端查看 PATHnpm 全局路径没配置找不到 codex cli binary运行which codex调用方 PATH 不一致登录失败检查 API Key / 登录状态鉴权信息过期或错误会话一直转圈看是否模型请求未返回网络、模型名、接口地址计划模式里改了文件确认是否真的退出计划模式提示约束没生效AGENTS.md 不生效确认文件名和路径文件放错位置或拼写错误MCP 工具没出现先独立启动 MCP Server依赖缺失或配置错误模型不支持查当前 Provider 的模型列表模型名不在服务支持范围内请求报错地址不对查看实际请求 URLBase URL 配置错误遇到问题先定位“是哪一层出了问题”再去找解决方案。不要看到报错就删掉重装。8.3 什么时候不要用 CodexCodex 再强也不是所有场景都适合。我建议下面几类情况保持谨慎无测试覆盖的遗留代码大批量重构。Codex 可能改得很快但你没测试兜底很难判断它有没有改坏。包含大量敏感信息的项目。比如权限系统、支付系统、密钥管理AI 生成代码前需要更严格的 review。需要精确到像素、细致交互的产品页面。Codex 更适合结构化代码而不是纯视觉调优。依赖编译环境极其复杂的项目。Codex 可以写代码但完整复现编译环境仍然需要你自己维护。在适合的边界内使用它才是一个提效工具而不是“什么都让它来”的万能入口。8.4 我的最终建议这两年我使用 AI 编码工具最大的感受是工具本身进步很快限制你使用效果的反而是你对流程的理解。Codex 的计划模式、记忆系统、MCP每一个单独拆开都不难。难的是把它们组合成一条稳定流程。我会建议你先用“最小项目”把整条链路跑通一遍哪怕只是把 README 重写、让 Codex 记住你的格式化命令、再给它接一个浏览器 MCP。这个流程一旦稳定后面再放到真实项目里你就知道改哪里、看哪里、避开哪里。踩过几次坑之后你会发现很多问题不是工具能力不够而是前置环境、路径、权限和输入材料没有处理干净。先把根扎稳再让 Codex 跑起来它会比你想的可靠得多。
