1. 先搞清楚 Codex 到底是个什么东西1.1 它不是一个“装完就能写代码”的魔法按钮很多人第一次听到 Codex脑子里浮现的画面是装好之后对着屏幕说一句“帮我写个商城”然后代码就自动铺满整个项目。这个预期不能说完全错但它至少漏掉了中间百分之八十的过程。Codex 本质上是一个代码智能体Agent。你给它一个目标它会自己拆解任务、读取项目文件、修改代码、运行命令、查看报错、再回头改循环往复直到任务完成或者卡住。它和普通代码补全工具最大的区别在于补全工具只会在你打字的时候猜你下一行想写什么而 Codex 是拿着你的整个项目在干活。那它到底能做什么我自己的使用场景大概分三类从零搭骨架给一个需求描述让它生成项目结构、基础配置文件、入口代码。在已有项目里改东西比如“把所有的接口请求从 axios 换成 fetch”它会自己去找文件、改代码、处理引用。排查和修复把报错信息丢给它它会去读相关文件、定位问题、给出修复方案并直接改。适合谁来学如果你是完全没碰过命令行、没装过 Node.js、不知道什么是环境变量那这篇教程就是写给你的。如果你已经会用 Git、写过几个小项目那你可以跳过前面的安装部分直接看后面的 Agent 配置和实战技巧。1.2 Codex、CLI、IDE 这三个词到底是什么关系热搜词里反复出现 Codex、CLI、IDE 这三个词很多人搞不清楚它们之间的关系。我用一个生活化的类比来解释把 Codex 想象成一个装修师傅。CLI 是你和师傅沟通的对讲机IDE 是师傅干活的施工现场。你可以只用对讲机指挥师傅干活纯 CLI 模式也可以让师傅直接在你的施工现场里操作IDE 集成模式。具体来说Codex CLI一个命令行工具你在终端里输入指令它来执行。适合习惯终端操作的人也适合在服务器上使用。IDE 集成在 VS Code、PyCharm 等编辑器里安装插件Codex 直接读取你当前打开的项目你可以在编辑器里和它对话。Agent 模式Codex 作为智能体自主运行你给一个高层目标它自己决定怎么做。这三种模式不是互斥的你可以根据任务类型灵活切换。我个人的习惯是小改动用 IDE 集成大任务用 CLI 的 Agent 模式。1.3 学之前需要具备什么基础说实话Codex 的上手门槛比很多人想象的要低但也不是零。你需要具备的最低基础是会用终端执行基本命令cd、ls、mkdir 这些电脑上装了 Node.js后面会讲怎么装有一个代码编辑器VS Code 就行能看懂基本的报错信息看不懂也没关系Codex 会帮你看如果你连 Node.js 是什么都不知道别慌下一节我从头讲。但如果你连“文件路径”这个概念都不太清楚建议先花半小时了解一下操作系统的文件系统基础不然后面会比较痛苦。提示不要跳过基础环境准备直接去装 Codex我见过太多人因为 Node.js 版本不对、npm 源没配好卡在安装环节一两个小时最后以为是 Codex 本身有问题。2. 安装前的环境准备把地基打牢2.1 Node.js 安装版本选对少走弯路Codex CLI 是基于 Node.js 运行的所以第一步是装 Node.js。这里有一个关键点版本不能太低。根据我的实测Node.js 18 以下的版本会出现各种奇怪的兼容问题建议直接上 Node.js 20 LTS 或更高。安装步骤以 Windows 为例打开 Node.js 官网下载 LTS 版本的安装包.msi 文件。双击安装一路下一步注意勾选“Add to PATH”这个选项。安装完成后打开终端WinR 输入 cmd 或者用 PowerShell输入node -v和npm -v能看到版本号就说明装好了。Mac 用户更简单如果你装了 Homebrew一行命令搞定brew install node20装完之后同样用node -v验证。这里有一个很多人踩过的坑如果你之前装过旧版本的 Node.js一定要先卸载干净再装新版本。Windows 上残留的 PATH 配置会导致终端调用到旧版本的 node出现“明明装了新版本但 node -v 显示的还是旧的”这种情况。解决办法是去“环境变量”里把旧的 Node.js 路径删掉或者用 nvmNode Version Manager来管理多版本。nvm 是我强烈推荐的工具它可以让你在同一台电脑上切换不同版本的 Node.js# Mac/Linux 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装并使用 Node.js 20 nvm install 20 nvm use 20Windows 用户可以用 nvm-windows去 GitHub 上下载安装包即可。2.2 Git 安装与配置不只是为了版本控制Git 对 Codex 来说不只是版本控制工具它是 Codex 理解项目结构的重要依赖。很多 Codex 的功能比如查看文件变更、回滚修改都依赖 Git。Windows 安装 Git 的步骤去 Git 官网下载安装包。安装过程中有几个关键选项需要注意默认编辑器选 VS Code如果你装了的话不选 Vim不然会很难受。PATH 环境选“Git from the command line and also from 3rd-party software”。换行符处理选“Checkout Windows-style, commit Unix-style line endings”。安装完成后打开终端配置用户名和邮箱git config --global user.name 你的名字 git config --global user.email 你的邮箱Mac 用户通常自带 Git但版本可能比较旧建议用 Homebrew 更新一下brew install git配置完成后用git --version验证。注意Git 的用户名和邮箱不是随便填的它们会出现在你每一次代码提交的记录里。如果你打算把代码推到公开仓库建议用你常用的用户名和邮箱。2.3 终端环境的选择与配置Codex CLI 需要在终端里运行所以选一个顺手的终端很重要。Windows推荐 Windows Terminal微软商店免费下载比自带的 cmd 好用太多。如果你想要更好的体验可以装 WSL2Windows Subsystem for Linux在 Linux 环境里跑 Codex 会更顺畅。Mac自带的 Terminal 就够用追求颜值和功能可以装 iTerm2。Linux默认终端就行没什么好挑的。终端配置方面有几个小设置能显著提升使用体验字体大小调到 14-16px长时间看终端不累。配色方案选一个对比度高的主题推荐 Dracula 或 One Dark。快捷键把新建标签页、切换标签页的快捷键设成你顺手的组合。这些看起来是小事但 Codex 的很多操作是在终端里完成的终端用着不舒服会直接影响你的使用频率和效率。2.4 网络环境与 npm 源配置npm 默认的源在国内访问速度可能不太理想建议换成国内镜像源npm config set registry https://registry.npmmirror.com设置完之后可以用npm config get registry确认一下。如果你在公司内网环境下可能需要配置代理才能访问外部资源。这个具体怎么配得看你们公司的网络策略一般来说npm config set proxy http://你的代理地址:端口 npm config set https-proxy http://你的代理地址:端口配完之后如果 npm 安装还是有问题可以试试npm cache clean --force清一下缓存再重试。3. Codex 安装全流程从下载到跑通第一条指令3.1 Codex CLI 安装三种方式任选Codex CLI 的安装方式主要有三种我按推荐程度排序方式一npm 全局安装最推荐npm install -g openai/codex这是最标准的方式装完之后在终端任何位置都能直接用codex命令。方式二npx 直接运行免安装npx openai/codex这种方式不需要全局安装每次运行会临时下载最新版本。适合偶尔用一次的场景但每次启动会慢一些。方式三从源码构建适合开发者git clone https://github.com/openai/codex.git cd codex npm install npm run build npm link这种方式适合你想改 Codex 源码或者参与贡献的情况。普通用户不需要走这条路。安装完成后输入codex --version验证。如果能看到版本号说明安装成功。如果提示“command not found”大概率是 npm 全局路径没有加到 PATH 里。Windows 上 npm 全局包的路径通常是C:\Users\你的用户名\AppData\Roaming\npm你需要把这个路径加到系统环境变量里。Mac/Linux 通常是/usr/local/bin或~/.npm-global/bin。3.2 首次启动与认证配置第一次运行codex命令时它会引导你完成认证配置。根据你使用的服务不同配置方式也不一样。如果你使用的是官方服务通常会要求你登录账号或者输入 API Key。API Key 的获取方式是在对应平台的控制台里生成生成后复制粘贴到终端提示的位置即可。如果你使用的是自建服务或者第三方兼容接口需要配置 API Base URL 和 API Key。这些信息通常写在配置文件里Codex 的配置文件默认在~/.codex/config.jsonMac/Linux或%USERPROFILE%\.codex\config.jsonWindows。一个典型的配置文件长这样{ apiKey: 你的API密钥, baseUrl: 你的接口地址, model: 使用的模型名称 }注意API Key 是敏感信息不要把它提交到 Git 仓库里。建议把配置文件加到.gitignore中或者用环境变量的方式传入。3.3 跑通第一条指令验证安装是否成功安装和配置完成后我们来跑一条最简单的指令验证一下。打开终端进入一个空目录输入codex 创建一个 hello.txt 文件里面写上 Hello Codex如果一切正常Codex 会分析你的指令然后创建一个 hello.txt 文件。你可以用cat hello.txt查看内容。这条指令虽然简单但它验证了整条链路CLI 能启动、认证能通过、模型能响应、文件操作能执行。如果这一步卡住了后面的都不用继续先把这个问题解决。常见的卡住原因和解决办法问题现象可能原因解决办法提示认证失败API Key 错误或过期重新生成 API Key 并更新配置提示连接超时网络问题或接口地址错误检查网络连接和 baseUrl 配置提示模型不存在模型名称写错确认模型名称拼写正确命令无响应进程卡死CtrlC 终止后重试检查是否有残留进程3.4 IDE 集成在 VS Code 里使用 Codex如果你更习惯在编辑器里工作可以把 Codex 集成到 VS Code 中。安装步骤打开 VS Code进入扩展面板CtrlShiftX。搜索“Codex”相关的扩展。点击安装安装完成后重启 VS Code。在设置里配置 API Key 和接口地址。安装完成后你可以通过命令面板CtrlShiftP调用 Codex 的各种功能也可以在侧边栏打开 Codex 的对话面板。IDE 集成的优势在于Codex 能直接读取你当前打开的项目文件你不需要在终端里手动指定文件路径。对于在已有项目里做修改的场景这种方式效率更高。PyCharm 用户也有类似的插件可用安装方式大同小异在插件市场搜索安装即可。4. Codex 核心功能与常用命令详解4.1 常用 CLI 命令速查Codex CLI 提供了一系列命令来管理会话和配置下面这几个是我日常用得最多的命令作用使用场景/compact压缩当前会话的上下文对话太长导致响应变慢时/model切换使用的模型需要在不同模型间对比效果时/resume恢复之前的会话中断后想继续之前的任务/clear清空当前会话想重新开始一个全新任务时/help查看帮助信息忘记命令时/compact这个命令特别值得说一下。Codex 的对话是有上下文长度限制的当你和它聊了很多轮之后上下文会变得越来越长响应速度会下降甚至可能超出限制。/compact会把之前的对话内容压缩成摘要保留关键信息释放上下文空间。我一般在对话超过二十轮之后就会用一次。/resume也很实用。比如你昨天让 Codex 帮你改一个功能改到一半下班了今天想继续。直接用/resume就能恢复昨天的会话Codex 还记得之前的上下文。4.2 Agent 模式让 Codex 自己干活Agent 模式是 Codex 最强大的功能也是最需要技巧的部分。在这个模式下你给 Codex 一个目标它会自己规划步骤、执行操作、检查结果。启动 Agent 模式的方式很简单在指令前加上相应的标志即可。但关键在于怎么给指令。我总结了一个给 Agent 下指令的模板目标用一句话说清楚你要什么 约束有什么限制条件比如不能用某个库、必须兼容某个版本 验收标准怎么判断任务完成了举个例子不要说“帮我优化一下代码”而要说目标把 src/utils/request.js 里的 axios 请求改成 fetch 约束保持原有的错误处理逻辑不变不要引入新的依赖 验收标准所有调用 request 的地方都能正常工作npm run test 通过这样 Codex 就知道自己要做什么、不能做什么、做到什么程度算完。Agent 执行过程中它会自己决定读哪些文件、改哪些代码、运行什么命令。你可以实时看到它的操作步骤如果发现方向不对可以随时打断。4.3 会话管理与上下文控制Codex 的会话管理是一个容易被忽视但非常重要的技能。很多人用 Codex 效率低就是因为不会管理会话。几个核心原则一个任务一个会话不要把不相关的任务混在同一个会话里会污染上下文。及时清理任务完成后用/clear清空开始新任务。善用/compact长对话定期压缩保持响应速度。保存重要会话如果某个会话的上下文很有价值可以用/resume随时恢复。上下文控制还有一个技巧在指令里明确指定文件范围。比如“只修改 src/components/Header.jsx 这个文件”而不是让 Codex 自己去猜。这样可以减少它读取无关文件的时间也能降低改错文件的风险。4.4 模型切换与参数调优Codex 支持切换不同的模型不同模型在速度、质量、成本上各有差异。/model命令可以查看当前可用的模型列表并切换。选择模型的经验法则简单任务改个变量名、加个注释用速度快的小模型。中等任务写一个函数、改一个模块用平衡型模型。复杂任务架构设计、多文件重构用能力最强的大模型。除了模型选择还有一些参数可以调优。比如温度参数控制输出的随机性低温度适合需要精确输出的场景如代码生成高温度适合需要创意的场景如写文档。这些参数通常在配置文件里设置。5. 实战用 Codex 完成一个完整任务5.1 任务定义从需求到可执行指令我们用一个具体的任务来走一遍完整流程。假设你要做一个简单的命令行待办事项工具Todo CLI功能包括添加待办、查看待办列表、标记完成、删除待办。首先把这个需求转化成 Codex 能理解的指令目标创建一个 Node.js 命令行待办事项工具 功能 1. 支持 add 命令添加待办事项 2. 支持 list 命令查看所有待办 3. 支持 done 命令标记完成为 4. 支持 delete 命令删除待办 5. 数据存储在本地 JSON 文件中 约束不依赖任何第三方 npm 包只用 Node.js 内置模块 验收标准每个命令都能正常工作数据能持久化保存这条指令包含了目标、功能列表、约束条件和验收标准Codex 拿到之后就能开始干活了。5.2 执行过程Codex 是怎么一步步做的启动 Codex 并输入上面的指令后它会按照自己的规划执行。根据我的观察它通常会这样做初始化项目创建 package.json设置项目基本信息。创建入口文件生成 index.js 或 cli.js处理命令行参数解析。实现各个命令逐个实现 add、list、done、delete 的逻辑。实现数据存储写读写 JSON 文件的工具函数。测试验证运行几条命令测试功能是否正常。整个过程你可以在终端里实时看到。Codex 每执行一步会输出它的思考和操作你可以随时介入。如果它某一步做错了比如把数据文件放错了位置你可以直接说“数据文件应该放在项目根目录的 data 文件夹里”它会立即调整。5.3 结果验证与迭代修改Codex 完成初版之后你需要自己验证一下。运行几条命令node index.js add 买牛奶 node index.js add 写周报 node index.js list node index.js done 1 node index.js list node index.js delete 2 node index.js list检查输出是否符合预期。如果发现问题把具体的错误现象告诉 Codex让它修复。迭代修改的时候尽量把问题描述得具体。不要说“list 命令有问题”而要说“list 命令输出的待办事项没有显示完成状态已完成的应该有个标记”。描述越具体Codex 修复得越准确。5.4 代码审查与质量把控Codex 生成的代码不一定是最优的你需要做基本的审查。我通常会检查这几个方面错误处理有没有处理文件不存在、JSON 解析失败等异常情况。边界条件空列表、不存在的 ID、重复添加等情况有没有处理。代码风格命名是否清晰、函数是否过长、有没有明显的重复代码。安全性有没有直接执行用户输入、有没有路径穿越风险。发现问题后可以直接让 Codex 修改。比如“给所有文件操作加上 try-catch出错时输出友好的错误信息”。提示不要盲目信任 Codex 生成的代码尤其是涉及文件操作、网络请求、用户输入处理的部分。它可能会忽略一些安全边界需要你把关。6. 常见问题与排查技巧实录6.1 安装类问题装不上、找不到命令问题一npm install 报错 EACCES 或权限不足这是最常见的安装问题尤其在 Mac/Linux 上。原因是 npm 全局目录需要管理员权限。解决办法不推荐用 sudo# 创建用户级的 npm 全局目录 mkdir ~/.npm-global npm config set prefix ~/.npm-global # 把路径加到 shell 配置里 echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrcWindows 上遇到权限问题用管理员身份打开终端再安装。问题二安装成功但提示 command not found说明 npm 全局路径没加到 PATH 里。用npm config get prefix查看全局路径然后手动把这个路径加到系统环境变量。问题三Node.js 版本不兼容Codex 对 Node.js 版本有要求太低会报错。用node -v检查版本低于 18 的建议升级。6.2 运行类问题启动失败、无法连接问题一启动时报错“无法加载组织设置”这个通常和认证配置有关。检查配置文件里的 API Key 和 baseUrl 是否正确确认账号状态是否正常。问题二提示“无法发送消息”可能是网络问题也可能是会话上下文超限了。先试试/compact压缩上下文如果还不行就/clear重开会话。问题三Agent 沙盒更新提示Codex 的 Agent 模式运行在沙盒环境中有时候会提示需要更新沙盒。按照提示操作即可通常是自动完成的。问题四本地代理切换失败如果你配置了本地代理可能会遇到代理切换失败的情况。检查代理配置是否正确端口是否被占用。实在不行就先关掉代理用直连方式试试。6.3 使用类问题响应慢、结果不对问题一响应越来越慢上下文太长了。用/compact压缩或者/clear重开。问题二Codex 改错了文件在指令里明确指定文件范围不要让它自己猜。如果已经改错了用 Git 回滚git checkout -- 文件名。问题三生成的代码跑不起来把具体的报错信息贴给 Codex让它自己排查。通常它能根据报错定位到问题。问题四Agent 陷入死循环有时候 Agent 会反复尝试同一个操作一直失败一直重试。这时候手动打断CtrlC然后给它更明确的指令或者换一种方式描述问题。6.4 避坑清单与最佳实践根据我自己的使用经验整理了一份避坑清单不要在生产环境直接让 Codex 操作先在测试环境验证确认没问题再上生产。重要操作前先提交 Git这样出问题了可以随时回滚。指令要具体模糊的指令得到模糊的结果具体的指令得到具体的结果。定期清理会话不要让一个会话跑太久上下文污染会影响判断。审查生成的代码尤其是安全相关的部分不要盲目信任。保持 Codex 更新新版本通常会修复已知问题、提升稳定性。配置文件备份API Key 和个性化配置建议备份换电脑时直接复制过去。注意如果你在团队中使用 Codex建议统一配置文件格式和模型选择避免每个人用不同的配置导致协作时出现不一致。7. 进阶方向从会用 to 用好7.1 自定义指令与工作流配置Codex 支持自定义指令你可以把常用的任务模板、项目规范、代码风格要求写进配置文件里这样每次启动都会自动加载。比如你可以创建一个codex.md文件放在项目根目录里面写上# 项目规范 - 使用 ES Module 语法 - 缩进用 2 个空格 - 函数命名用 camelCase - 提交信息用中文Codex 在操作这个项目时会自动读取这些规范生成的代码就会符合你的要求。7.2 多 Agent 协作与任务拆分对于复杂任务可以让多个 Codex 会话分工协作。比如一个会话负责前端一个会话负责后端一个会话负责测试。每个会话专注于自己的领域最后再整合。这种方式的优势是每个 Agent 的上下文更聚焦不容易被无关信息干扰。但需要注意接口约定前后端的接口格式要提前定义好不然整合的时候会很痛苦。7.3 与 CI/CD 流程的集成思路Codex 可以集成到 CI/CD 流程中比如在代码提交时自动运行 Codex 做代码审查或者在构建失败时自动让 Codex 分析日志并给出修复建议。具体的集成方式取决于你使用的 CI/CD 平台。核心思路是把 Codex 当作一个可以编程调用的服务通过 API 的方式在流水线的特定环节触发。这部分内容比较进阶建议先把基础用法用熟了再考虑。我自己的经验是基础用法能解决百分之八十的日常需求剩下的百分之二十再考虑用进阶方案。7.4 持续学习与社区资源Codex 这个领域变化很快新功能、新用法层出不穷。保持学习的方式有几种关注官方文档的更新日志新版本通常会带来新能力。加入相关的技术社区看看别人是怎么用的。自己多试很多技巧是在实际使用中摸索出来的。我个人的习惯是每周花半小时看看有没有新东西遇到好用的技巧就记下来慢慢就形成自己的工具箱了。最后分享一个我自己的体会Codex 这类工具的价值不在于它替你写了多少代码而在于它帮你省下了多少“查文档、找文件、改来改去”的时间。把省下来的时间用在真正需要思考的地方——架构设计、需求分析、技术选型——这才是用好 Codex 的关键。