大家有没有这种感觉网页聊天里的AI不管聊得多好一旦要真正落盘改代码它就隔了一层。你在对话框里描述需求它给你一段代码你复制回去运行报错了再复制回来一来一回效率很低。我在过去几个项目里反复折腾AI编程工具最后固定下来的是Codex CLI这个跑在终端里的AI Agent。它不属于IDE插件也不是网页对话框而是直接在项目目录里干活——你告诉它需求它自己去读代码、写文件、执行命令、看报错、再修整个闭环都在命令行里完成。这篇文章把Windows Node这套环境下的完整上手路径写出来从环境准备、安装登录到跑通第一个任务、调节配置最后盘点Windows下我踩过的坑。适合两类人一是已经在用终端写代码、想把日常杂活交给AI的开发者二是刚接触AI Agent、想从网页聊天切到命令行实操的人。1. 为什么是它终端里的AI Agent到底解决了谁的痛点1.1 聊天式AI和Agent的区别不在聪明在有手有脚传统的AI编程辅助本质是问答式的。你问一句它答一段主体还是人人负责理解、人负责动手、人负责验证。这在查函数用法、写小段算法的时候确实够用一旦需求跨多个文件、涉及环境依赖、需要反复试运行问答式的效率瓶颈就出来了——上下文要被你手动搬运报错信息要靠你手动喂回去。Codex CLI这类Agent最大的不同是它能自己动手。它可以在工作目录里查看文件列表、读取文件内容、修改文件、执行shell命令。你把需求说清楚它自己规划步骤自己写代码自己跑甚至看到一个报错之后自己回去改代码再跑。这个循环很像一个新人开发者在干活看一眼代码改一处跑一下报错就再改。只不过它的阅读速度和修改速度比人快得多。我做项目时最常用的场景是准备测试数据、批量重命名、补注释、写脚本处理脏数据。这些活得写代码但又不值得认真当一个功能来做。以前我都是自己写个一次性的Node脚本用完就删现在直接开个Codex会话用自然语言描述需求它把脚本写出来、跑完、我验一下结果完事。省掉的是从脑子里翻译成代码的时间。1.2 它和IDE插件的边界也不一样很多人会问IDE里不也有AI插件吗为什么非要CLI我的体感是IDE插件的优势在于贴身——它看着你当前打开的文件适合补全、解释、小范围重构。但它很少主动跑命令也不会站在整个项目的角度去改多个散落文件。CLI型Agent的优势是宽和自动化它可以同时操作几十个文件适合批量重构、批量生成。它可以执行命令比如安装依赖、跑测试、启动服务然后根据输出来判断下一步。它可以被脚本调用、可以非交互式执行适合把AI塞进自动化流程里。所以我现在的习惯是在IDE里写代码时用补全类AI遇到跨文件改造跑通一个流程处理一堆脏数据这类任务切到终端开Codex。两者不冲突甚至互补。1.3 什么人应该先忍住别装也说句劝退的话。Codex CLI要求你至少看得懂终端的基本操作cd进目录、看报错、理解路径。如果你从没在命令行里运行过Node脚本建议先去补二十分钟基础否则Agent做了什么你完全无感出了问题也没法判断是该修提示词还是该修环境。它不是一个帮你跳过学习的工具而是一个帮你省掉重复劳动的工具——这两者有本质区别。2. 开工前检查单Windows Node 环境最容易出事的三个位置2.1 Node版本过低过新都会卡在安装环节Codex CLI本质是一个npm包所以最基础的条件是Node.js环境。官方要求Node 20以上我建议直接上22 LTS。为什么是LTS而不是最新版因为npm生态里有些依赖对奇数版本、对刚发布的新版本兼容性不够稳用LTS能少碰很多我这明明没问题为什么装不上的诡异情况。Windows下管理Node版本我推荐nvm-windows它和macOS/Linux上的nvm用法几乎一致。安装好之后两条命令nvm install 22 nvm use 22装完务必确认一下当前版本node -v npm -v这一步看起来糙但真的能挡掉不少问题。我见过好几个朋友说Codex安装时报引擎版本不匹配结果一查node还是14.x。如果你之前为了其他项目装过老版本Node且没有用版本管理器那建议这次直接上nvm-windows重管。2.2 终端选不对后面跑命令各种别扭Windows默认的cmd和老版PowerShell 5.0在跑现代CLI工具时有两个典型毛病一是字符编码经常出现乱码尤其是中文环境二是对某些命令的解析方式和Unix shell不一致。我的建议是装Windows Terminal然后把默认shell设为PowerShell 7或者直接装Git Bash使用。原因很简单Codex CLI的命令行交互界面有颜色、有动态刷新的状态Windows Terminal对这类ANSI转义的支持比老终端好很多PowerShell 7和Git Bash对UTF-8和路径符号的处理也更接近其他系统。这不影响Codex判断文件但影响你的阅读体验以及会话过程中手动输入指令的顺畅度。如果你打算长期用顺手把终端编码切到UTF-8chcp 65001这个命令只对当前窗口生效下次开终端要重新执行。介意的话可以在PowerShell profile里加一行或者直接在Windows Terminal的配置文件里把默认编码改掉。2.3 Git是隐藏依赖别等Agent要提交时才装Codex CLI在运行时会大量调用git来查看文件变更、生成diff、甚至帮你提交代码。它不是可选依赖而是实际工作流的一部分。如果你机器上还没装git先装好并且配置好用户信息git config --global user.name your-name git config --global user.email your-email这两行配置不然后面Agent帮你git commit的时候会直接报错那时候你还得切出会话去配。我习惯在每个准备交给Agent处理的项目里先git init一次这样它每一步改动我都能用git diff回溯心里有底。别小看这个习惯——AI写代码偶尔会自由发挥得很远有git的话随时能回滚没有的话只能手动删改。另外如果你打算用WSL下的Linux环境跑后面第4章会讲到本地沙箱模式为什么依赖它那在WSL里也要装Node和git别只装Windows版本。我见过最尴尬的局面是Windows里一切就绪切到WSL后node都不存在然后在那折腾半天环境变量。所以选定一条路就走到底别混着来。3. 安装、登录、第一条指令30分钟跑通最小闭环3.1 一条npm命令装好版本校验别跳过环境就绪后安装本身简单到离谱。在终端执行npm install -g openai/codex安装完成后第一步永远是用版本命令验证codex --version能正常打印版本号说明核心安装没问题。如果这一步报错基本只有两个原因Node版本不对、或者npm全局目录不在PATH里。后者在Windows上偶尔出现解决方法是把npm全局安装目录通常在%APPDATA%\npm加到系统的Path环境变量里然后重启终端。npm下载慢的问题我给一个通用解法把registry切到国内公共镜像下载速度会立竿见影。这个配置对后续所有npm包都生效不算什么偏门操作npm config set registry https://registry.npmmirror.com装完之后不用急着改回来日常没有影响。3.2 codex login十几秒的授权决定你会不会中途断档安装包本身不包含身份需要登录一次账号。执行codex login终端会显示一条授权链接并在浏览器中打开登录页。你登录自己的Codex账号确认授权然后终端会自动确认成功。整个过程大概几十秒。这里有两个Windows下常见的小问题第一浏览器没自动弹出来。不用慌把终端里的链接手动复制到任意浏览器里打开完成授权即可授权结果会回传。第二登录状态有时会因为账号token过期而失效表现是执行任务到一半突然提示需要重新授权。这不常见但遇到了重新跑一次codex login就行。我的建议是别在头一天晚上写好的长任务上刷存在感开始大任务前先确认登录状态有效。登录之后用户目录下会生成一个隐藏目录.codex里面存放着认证信息和配置文件。Windows下路径是C:\Users\你的用户名\.codex\。后面调整配置、写项目手册都是在这个目录里操作。3.3 用codex init建立一个项目使用说明书这是很多人会忽略的一步。在项目目录下执行codex init它会在当前目录生成一个AGENTS.md文件。这个文件的作用是给AI Agent看的项目手册——项目是做什么的、用什么框架、构建命令是什么、有没有不能动的目录。Codex每次在这个目录里工作时都会优先读这个文件来理解项目背景。我的建议是不要让它保持默认空模板而是手动维护几行信息比如本项目是Express老项目入口在src/index.js测试用vitestnode_modules不要动。你写的越清楚Agent后续自主干活越少瞎猜。这个文件有点像你给实习生写的第一天入职培训文档投入很小省下的沟通成本很大。3.4 第一条指令先让它看看这个项目最小闭环的验证方式很简单在一个项目目录里让Codex先只观察、不动手。交互模式启动codex进入对话后输入请列出当前目录的结构并说明这个项目大概在做什么。不要修改任何文件。如果你用的是codex exec一次性执行模式也可以这样codex exec 请列出当前目录的结构并说明这个项目大概在做什么。不要修改任何文件。Codex会自己调用命令读取目录然后给你一份总结。第一次跑通这个流程意味着安装、登录、上下文读取、响应生成这条链路全部正常。之后就可以开始真正干活了。4. 它怎么读懂并操作你的电脑Codex CLI的运行机制拆解4.1 核心循环观察、思考、行动、验证然后循环理解Codex CLI抓一条主线就够了它是一个循环。它拿到你的自然语言指令后先把目标拆成若干步骤然后反复做四件事——观察当前状态、思考下一步操作、调用一个工具执行、根据结果判断是否完成或需要调整。这个循环在终端里的表现是它会一条条显示当前正在做什么查看某个文件、执行某个命令、修改某段代码。你可以看着它一步步推进而不是一次性甩给你一个结果。这个过程透明性很强也给了你在中途干预的机会——看到方向不对直接打断并纠正比等它跑完再返工效率高很多。它在代码里实际操作的类型基本覆盖了四种读取类查看文件、列目录、修改类写文件、批量替换、执行类跑shell命令、安装依赖、跑测试、以及搜索类在项目里按关键词找文件。说白了你自己在终端里能做的事情它都能通过调用工具完成。4.2 工作区边界它眼里只有当前项目别指望它管全局Codex CLI不是接管你整个电脑的AI它的视野和行动范围默认限制在当前工作目录。你从哪个目录启动codex它就围绕哪个目录工作。这个设计一方面是为了安全避免它随便读你桌面上的私人文件另一方面也是为了让上下文更聚焦不让无关文件干扰判断。在项目根目录里它可以自由查看所有子目录和文件除非你的配置文件里设了exclude排除项。我强烈建议在大项目里配置排除node_modules、dist、.git这类又大又没用的目录。否则Agent扫描文件列表时可能会慢也可能在读文件时把一些自动生成的代码当成业务逻辑来分析导致理解偏差。4.3 计划和审批为什么我不建议一上来就全自动Codex CLI在执行操作前有审批机制尤其是执行命令和修改文件时会等待你确认。这个机制决定了它在你的机器上是有边界的执行者而不是失控的自动机。实际使用中有一个授权行为模式的选择常见的有让Agent全自动执行、让它先把计划列出来等你批准、或者只在出现错误时向你确认。我强烈建议第一次使用时选先计划后执行的模式。你可以通过启动时的参数或配置来控制比如在交互中输入计划模式或者首次执行时明确要求先给出计划不要执行。这个习惯能帮你快速理解Agent的思考方式它打算先看哪个文件打算用什么方案有没有理解偏。等你对它的风格熟悉了再逐步放开授权级别不迟。4.4 云端执行与本地执行两种运行模式的取舍Codex CLI有两条执行路径。一种是云上执行模式AI在远程沙箱里分析代码、运行命令然后把结果同步回本地目录。好处是你本机不需要装很多依赖环境更干净缺点是网络请求来回有一定延迟而且如果你本地环境的差异会影响结果比如依赖只在本地装过它可能跑通了但你没跑通。另一种是本地沙箱模式AI直接在本机执行命令和修改文件更像一个真人在你的终端里操作。好处是和工作区实际环境完全一致适合跑构建、跑测试这类依赖本地环境的操作缺点是在Windows原生环境下完整的沙箱隔离能力受限通常需要借助WSL或容器来获得可靠的本地沙箱隔离。我的建议是日常改代码、写脚本、批量处理文件用云端模式没问题一旦涉及跑构建、跑测试、起服务、看运行结果优先切到本地模式。这也是为什么我在第2章强调WSL可装可不装但真高频使用后大概率会需要。5. 首个实战让Codex把一个乱糟糟的下载目录整理成规整分类理论说完了来一个完整的实战。这个案例我选得很日常整理一个乱糟糟的下载目录。它不涉及复杂的业务逻辑但足够展示Agent工作的完整闭环理解需求、制定计划、写代码、运行、遇到报错、自我修复、验证结果。5.1 准备实验场地我先创建一个模拟目录里面放了几类文件扮演下载文件夹mkdir codex-demo cd codex-demo mkdir data # 在data目录下放一些文件几张图片、几个文档、两个压缩包文件命名故意造得乱一点比如photo1.jpg、微信图片_20250101.png、项目说明final(2).docx、报告数据.xlsx、backup-2024.zip、temp.zip——什么都混在一起。目标也很明确按扩展名分类图片、文档、压缩包分门别类放进独立的子目录文件名统一加上当天日期前缀原文件不能被删除只能移动。5.2 给Codex下达需求先要计划启动交互模式输入请扫描当前项目下的data目录。这个目录里混了很多种类型的文件请写一个Node脚本把它们按类型移动进不同的子目录图片jpg/png/gif放到images文档docx/pdf/txt/xlsx放到docs压缩包zip/rar/7z放到archives。移动后的文件名加上当天日期前缀例如2025-01-08_photo1.jpg。要先给出你的执行计划不要直接改动文件。注意我特意在最后加了先给出执行计划不要直接改动文件。这是第一次使用时的安全操作先看它准备怎么干再放行。Codex给出的计划基本是先列目录确认文件清单然后写脚本遍历文件用正则或扩展名判断类型用fs.rename移动文件并测试运行。它还会提一句移动前先对每个文件确认扩展名这个细节说明它确实先看了目录里有哪些文件而不是凭空想方案。5.3 批准执行然后它踩了一个经典的Windows坑我确认计划后说按这个方案执行。Codex开始写脚本、运行。第一次运行报错了。错误信息很眼熟Error: EXDEV: cross-device link not permitted, rename C:\...\data\photo1.jpg - D:\...\images\2025-01-08_photo1.jpg这不是它代码写错了而是Windows文件系统的特性如果源文件和目标目录不在同一个磁盘分区C盘和D盘fs.rename不能直接跨盘符移动文件。如果你用过Node写文件操作工具这个坑大概率也遇到过。Codex看到报错后没有停下来等我来处理。它自动读取了报错信息判断是跨盘符问题然后把方案改成先复制文件到目标目录再删除原文件的方式重试。第二次运行成功data目录下的文件被整理到位控制台打印出每个文件移动前后的路径。5.4 校验结果并复盘这个过程中发生了什么我手动打开目录检查images、docs、archives三个文件夹出现文件各归其位文件名带上了日期前缀。原文件没有丢失脚本没有误删格式完整。这个案例真正值得注意的不是Codex会写脚本——脚本本身不复杂。而是它展现出了一种完整的工作方式它不是一次性甩给你一个你应该这样写的答案然后让你自己去跑而是自己推进了看目录、写脚本、运行、识别报错、修复方案、重跑、验证这一整个闭环。你的角色从执行者变成了审批者。你只需要在它每次请求批准时判断这个操作是否安全、方向是否对剩下的重复劳动它包了。5.5 复盘我作为使用者做了什么关键判断我不是全程躺着。在它运行报错后我本来想提示它换个分区试试但发现它已经在自我修复了于是闭嘴等结果。如果它连续修两次还不行我才会介入给出方向。这就是人机协作该有的节奏AI负责执行人负责判断边界和方向。它每次请求执行命令时我会扫一眼将要执行的命令——有没有rm -rf、有没有超出工作目录的路径、有没有明显离谱的权限操作。确认没问题就放行。信任是逐步建立的别一开始就全自动也别永远不敢放权。6. 从偶尔能用到日常顺手配置与提示词调教跑通第一个任务后你大概率会希望它更像自己的工具而不是通用的AI。这一章聊怎么调教。调教分两个层面配置文件层面的持久化设置以及会话中提示词层面的沟通技巧。6.1 config.toml你的持久化偏好清单Codex的主要配置文件是.codex目录下的config.toml。Windows下路径为C:\Users\你的用户名\.codex\config.toml。没有就手动创建。我常用的几个配置项整理如下配置项作用我推荐的设置model指定使用的模型标识保持默认即可值以你账号可用的模型为准sandbox_mode运行模式云端或本地沙箱默认云端需要本地跑构建时切换本地auto_approve_behavior自动审批行为新手阶段设为先出计划熟练后再放宽include额外让Agent读取的路径保持默认即可exclude排除不扫描的目录必须加入node_modules、dist、.git环境变量让Agent在运行命令时继承的额外环境按项目需要填写其中exclude是要重点关注的一项。在一个大型前端项目里node_modules动辄十万个文件不排除掉的话Agent每次列目录都慢半拍还有可能把依赖库里的代码当成项目代码来分析。排除后它的上下文干净很多回答质量和速度都会上去。6.2 AGENTS.md把你项目的潜规则写在明面上我在第3章提过codex init生成的AGENTS.md这里展开讲。它本质上是给Agent读的项目说明书。你不在场时它靠这个文件来判断什么能做、什么不能做。我维护这个文件的大致模板是项目简介两三句话说明项目是做什么的。常用命令启动命令、测试命令、构建命令直接写成可复制的形式。目录约定哪些目录存放源码、哪些是构建产物、哪些千万别删。代码风格分号还是无分号单引号还是双引号缩进几格。明确禁区比如不要修改package.json版本号不要动数据库迁移文件。写这个文件的技巧是把自己平时在群里跟同事反复叮嘱的话全写进去。Agent和同事的区别是同事问一次就记住了Agent可能每次干活前都要靠这个文件补记忆。所以越具体越好宁可啰嗦不要留白。6.3 提示词的四件套话术在会话里给Agent下达任务时我总结了一个四件套结构基本不出错背景这个项目是什么相关文件在哪。目标你要它最终交付什么。约束什么不能碰、什么必须保留、有没有兼容性要求。验收标准怎么算做好比如跑npm test全部通过。举例对比一下。差的提示词帮我优化一下这个下载功能。——它不知道优化到什么程度也不知道哪些方面不能动。好的提示词这个项目在src/utils/download.js里有一个下载逻辑目前并发下载10个文件时偶尔超时。请引入p-limit做并发控制把并发数限制在5保持现有函数签名不变确保调用方不用改代码。完成后跑一下npm test确认没破坏现有功能。后者它基本一次就能正确完成。前者它会犹豫然后问你一堆问题。在命令行交互模式下也能追问但一来一回多花时间。不如一开始就说清楚。6.4 多轮纠错怎么让它从错误里自己爬出来Agent会犯错但犯错后的处理方式和人协作很类似把错误信息贴回去让它分析。你不需要自己看懂报错只需要告诉它运行报错了输出在下面你分析一下原因然后修复。它会自己定位到报错那行判断是环境问题、代码问题还是依赖问题。这里有个小技巧如果它在同一个问题上连续失败两次以上不要继续让它自己撞墙了。这时应该主动补充上下文比如这个函数是从第三方库里引入的不是自己写的别去改那个库或者这台机器上npm install需要额外参数。很多情况下它失败不是因为能力不够而是因为它缺少一个只有你知道的上下文信息。你把这个信息补给它问题往往立刻解决。6.5 MCP让Agent长出新的器官Codex支持通过MCPModel Context Protocol扩展能力。你可以把它理解为给Agent接入新的工具接口比如接一个数据库操作接口它能直接查表看数据接到浏览器工具它能操作网页接到某个内部API的SDK它能直接调接口测试。配置方式是在config.toml里声明mcp_servers指定启动命令和参数。如果你没有明确需求这个功能可以先放一放。我的建议是先用一个月纯命令行版本搞清楚它的工作习惯再考虑接MCP。一上来就接一堆扩展容易让你分不清能力边界到底在哪出问题也不知道是核心功能还是扩展的锅。7. Windows下踩坑实录这些问题我修了很久最后是Windows环境下的常见问题汇总。这一部分是我实际使用中花时间最多的地方写出来帮你少绕路。7.1 安装时报engine相关错误现象npm install -g openai/codex报错提示要求Node版本高于某个值。原因机器上的Node版本太旧。解法用nvm-windows切换到22 LTS。不要手动去改包内的engine字段那是在制造更大的坑。7.2 PowerShell执行策略拦住了脚本执行现象Codex在本地模式下尝试跑脚本时被PowerShell的ExecutionPolicy拦下来。原因Windows PowerShell默认执行策略偏向保守禁止运行未经签名的脚本。解法在PowerShell里查看执行策略必要时调整为当前用户可运行本地脚本Get-ExecutionPolicy -List Set-ExecutionPolicy -Scope CurrentUser RemoteSigned如果你用的是Git Bash这个坑一般不会碰到。这也是我推荐用Windows Terminal配PowerShell 7或Git Bash的原因之一。7.3 终端中文乱码现象Codex输出的中文、或者脚本打印的中文日志在终端里显示成乱码。原因老式终端默认按GBK代码页936解码而大部分现代工具输出UTF-8。解法切到Windows Terminal执行chcp 65001切换UTF-8代码页。如果用小众终端模拟器去它的设置里找编码选项强制UTF-8。这个问题不影响Agent实际逻辑但影响阅读也影响你复制报错信息复制出来是乱码喂回给Agent它也看不懂。7.4 本地沙箱模式启动失败现象尝试使用本地沙箱模式时Codex提示当前环境不支持或需要额外组件。原因Windows原生环境对OS级别沙箱隔离的支持较弱不像Linux那样有成熟的内建沙箱机制。解法两条路。一是安装WSL在WSL里的Linux环境启用本地沙箱模式二是不开本地沙箱继续用默认的云端执行模式。除非你频繁需要在本地跑构建和测试否则默认云端模式完全够用。7.5 跨盘符移动文件的EXDEV错误现象Agent写的文件移动脚本报EXDEV: cross-device link not permitted。原因Windows下不同磁盘分区之间fs.rename等基于同一文件系统设计的操作不能直接用。解法这是代码层面的问题直接让Agent改成复制到目标位置后再删除原文件。如果它没自动意识到你可以把这句错误信息贴给它加一句注意这是Windows跨盘符问题它马上就能修正。7.6 大项目扫描慢上下文越混越乱现象在大型前端项目里Agent列目录很慢有时还会答非所问把依赖代码当业务逻辑分析。原因没有排除node_modules等大目录Agent扫描文件列表时被无用信息淹没。解法在config.toml的exclude里加node_modules、dist、.git、coverage等目录。改完配置后重启Codex会话体感上快了不是一点半点。7.7 授权状态失效任务跑到一半中断现象长任务执行到中途终端提示需要重新登录授权。原因账号登录凭证过期。解法重新跑codex login。建议在开始一个长任务前先确认登录状态或者在配置里了解清楚凭证的有效期机制这一点不同账号策略可能不同。至少要有心理准备别在大任务跑到最后一步时被登录打断。7.8 让Agent读不到某些文件现象Agent说找不到某个文件但文件明明就在项目里。原因可能是被exclude规则排除了也可能是当前工作目录不对。解法先看当前会话启动时所在的目录路径再看配置文件里的exclude有没有把该目录排除掉。排查顺序是先确定工作目录、再查配置、最后才是问Agent你是不是看漏了。大部分情况不是它看漏是上下文边界没设对。最后再补一句实际体会用Codex CLI跑了这段时间我最深的感受是它的价值不在于AI能写多少代码而在于把从想法到落盘之间的距离压缩到了极致。以前我有个小需求想一下实现思路、写代码、调试、验证至少半小时现在同样是半小时我可以让Agent同时做三四件事我只负责验收。我现在的固定流程是进入项目目录、写AGENTS.md、让它先出计划、批准执行、有问题贴回给它的报错提示。这套流程跑顺之后它已经不只是工具更像一个随叫随到、不会抱怨、指哪打哪的虚拟同事。如果你刚开始用我这篇里最想让你记住的一句话是不要急着把所有权限交给它。先让它多汇报、多请示你多观察几次它的工作方式再决定哪些环节可以放权。安全边界这种东西宁可保守一点后面再放开也不迟。