1. 为什么 Windows 上跑 Codex 总在第一步就卡住如果你在 Windows 上折腾过 Codex大概率经历过这样的场景照着某篇教程敲下第一条命令终端直接甩出一行红字——npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。然后你开始怀疑人生怀疑自己是不是装了个假 Node.js。这不是你的问题也不是 Codex 的问题而是 Windows 这套系统在安全默认值和开发者体验之间长期拉扯留下的历史包袱。PowerShell 默认的执行策略是Restricted意思是任何.ps1脚本都不许跑而 npm 在 Windows 上恰恰是通过npm.ps1这个包装脚本来调用的。于是你装好了 Node.jsnode -v能出结果但npm -v直接报错整个链路从第一步就断了。这篇内容面向的是所有在 Windows 环境下想用 Codex 的人——不管你是刚接触命令行工具的新手还是从 macOS/Linux 转过来、被 Windows 各种惊喜教育过的老手。我会把从 Node.js 环境搭建、npm 配置、Codex 安装、配置文件解析到实际使用中可能遇到的各种坑完整地讲一遍。核心关键词包括Codex、Windows、Node.js、npm、VSCode同时也会覆盖codex安装教程、codex配置文件解析、codex接入deepseek、codex国内能用吗这些大家最关心的问题。先说结论Windows 上跑 Codex 完全可行但需要你理解三件事——PowerShell 的执行策略、npm 的全局路径机制、以及 Codex 的配置文件结构。这三件事搞明白了后面基本就是一马平川。下面我按实际操作的顺序从环境准备开始一步步拆。2. Node.js 安装别用微软商店版本也别装在带空格的路径2.1 为什么安装源的选择比版本号更重要很多人装 Node.js 的第一反应是打开微软商店搜一下或者去官网随便下个 LTS 版本。这里有个容易被忽略的细节微软商店版本的 Node.js 在权限和路径管理上经常出幺蛾子尤其是涉及到全局包安装和 npm 前缀配置的时候你会发现自己明明用管理员权限开了终端npm 还是告诉你没有写入权限。我的建议很直接去 Node.js 官网下载Windows Installer (.msi)版本选 LTS长期支持分支。截至我写这篇内容的时候Node.js 20.x 和 22.x 都是稳定的 LTS 选择。为什么强调 LTS因为 Codex 依赖的一些底层包对 Node 版本有要求太老的版本比如 16.x 以下会在安装依赖时直接报引擎不兼容太新的尝鲜版又可能遇到原生模块编译失败的问题。安装路径这块有个经典坑默认路径C:\Program Files\nodejs\里带空格。大部分情况下没问题但某些工具在处理路径拼接时对空格处理不当就会导致莫名其妙的错误。如果你不嫌麻烦可以改成C:\nodejs\这种干净路径。我自己的机器上用的是D:\Program Files\nodejs\用了两年多没出过路径相关的问题所以带空格也不是绝对不行只是多一层风险。安装过程中有一个选项一定要注意Add to PATH 必须勾上。如果你忘了勾装完之后在终端里敲node -v会提示不是内部或外部命令。补救办法是手动把 Node.js 安装目录加到系统环境变量的 Path 里然后重开终端。2.2 验证安装与 npm 环境变量 Path 配置装完之后别急着往下走先做三步验证node -v npm -v where node where npm前两条看版本号是否正常输出后两条看路径是否指向你刚装的目录。如果where npm输出的路径里出现了多个结果说明你之前可能装过其他版本的 Node.js环境变量里有残留需要清理掉旧路径。关于npm环境变量path配置这里展开说一下。npm 有两类包本地包和全局包。本地包装在项目目录下的node_modules里全局包装在 npm 的全局前缀目录里。Windows 上默认的全局前缀是%APPDATA%\npm也就是C:\Users\你的用户名\AppData\Roaming\npm。这个目录必须加到系统 Path 里否则你全局安装的命令行工具比如 Codex在终端里根本找不到。验证方法很简单npm config get prefix输出的路径就是全局前缀。然后检查这个路径是否在系统环境变量的 Path 列表里。如果没有手动加上重开终端。注意修改环境变量后一定要关闭所有终端窗口重新打开已经打开的终端不会自动加载新的环境变量。这个细节看起来废话但我见过太多人改完 Path 之后在当前终端里反复试然后说改了没用。2.3 npm 全局安装和本地安装的区别以及为什么 Codex 要全局装npm全局安装和本地安装的区别是个老生常谈的话题但放到 Codex 这个场景下值得再说一次。本地安装npm install codex会把包装在当前项目的node_modules里只有在这个项目目录下才能通过npx调用。全局安装npm install -g codex会把包装到全局前缀目录并且把可执行文件链接到全局 bin 目录这样你在任何目录下都能直接用codex命令。Codex 作为一个命令行工具显然应该全局装。但全局装的前提是全局前缀目录已经正确配置在 Path 里否则装完了也调不出来。3. PowerShell 执行策略那个让 npm 报错的元凶3.1 报错信息的完整解读回到开头那个报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这条信息的每一个部分都值得拆开看。无法加载文件说明 PowerShell 找到了npm.ps1这个文件但拒绝执行它。因为在此系统上禁止运行脚本直接点明了原因——执行策略限制。PowerShell 有四种主要的执行策略执行策略含义能否跑 npmRestricted禁止所有脚本否AllSigned只允许签名脚本否除非 npm.ps1 有签名RemoteSigned本地脚本可跑远程脚本需签名是Unrestricted全部允许是Windows 客户端系统默认是Restricted服务器系统默认是RemoteSigned。所以你在 Windows 10/11 上装完 Node.js第一次跑 npm 就会撞上这堵墙。3.2 修改执行策略的正确姿势解决办法是把当前用户的执行策略改成RemoteSignedSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这里有几个细节要注意。第一-Scope CurrentUser表示只改当前用户不需要管理员权限也不会影响系统上其他用户。第二改完之后用Get-ExecutionPolicy -List确认一下你应该能看到 CurrentUser 那一行显示RemoteSigned。第三如果你用的是 VSCode 内置终端改完之后需要重启 VSCode因为终端进程是在 VSCode 启动时创建的不会自动刷新执行策略。还有一种情况你用的是公司配的电脑组策略锁死了执行策略Set-ExecutionPolicy会报被组策略覆盖之类的错误。这种时候可以试试在命令前面加cmd /c来绕过 PowerShell 脚本层直接走 cmd 的 npm.cmdcmd /c npm -v但这只是权宜之计长期用还是建议找 IT 部门放开 CurrentUser 的执行策略权限。3.3 为什么改了策略还是报错几个容易忽略的角落有时候你改了执行策略Get-ExecutionPolicy也显示RemoteSigned了但 npm 还是报同样的错。这种情况通常有几个原因一是你改的是 64 位 PowerShell 的策略但 VSCode 终端用的是 32 位版本两者策略不互通。解决办法是在 VSCode 里确认终端类型或者干脆在 VSCode 设置里把默认终端改成Command Prompt。二是你的 npm 是通过 nvm-windows 管理的nvm 会在切换 Node 版本时重新生成npm.ps1如果新生成的文件被标记为来自远程RemoteSigned 策略下依然会被拦截。这种情况可以用Unblock-File命令解除锁定Unblock-File -Path C:\Program Files\nodejs\npm.ps1三是杀毒软件在中间拦截了脚本执行。某些安全软件会把 PowerShell 脚本执行当成可疑行为静默阻止。如果你排查了一圈都没找到原因可以临时关闭杀毒软件试试确认是它的问题之后再把它加到白名单里。4. Codex 安装与配置文件解析4.1 安装命令与版本选择环境准备好之后安装 Codex 本身反而最简单npm install -g codex如果你在国内网络环境下遇到下载慢或者超时的问题可以临时切换 npm 镜像源npm config set registry https://registry.npmmirror.com装完之后验证codex --version能输出版本号就说明安装成功了。如果提示不是内部或外部命令回去检查第 2.2 节讲的全局前缀 Path 配置。关于codex安装包和codex下载有些人喜欢去官网直接下二进制包。我的建议是能用 npm 装就用 npm 装因为 npm 会自动处理依赖关系和版本兼容性手动下二进制包反而容易漏掉运行时依赖。4.2 配置文件的位置与结构codex配置文件解析是很多人卡住的地方。Codex 的配置文件通常放在用户主目录下的.codex文件夹里Windows 上的完整路径是C:\Users\你的用户名\.codex\这个目录下可能有几个文件具体取决于你安装的 Codex 版本和配置方式。常见的包括config.json、config.toml或者.env文件。配置文件的核心作用是指定 API 端点、认证信息、模型选择、超时设置这些参数。一个典型的配置文件结构大概长这样以 JSON 为例{ api_base: https://your-api-endpoint/v1, api_key: your-api-key-here, model: codex-model-name, timeout: 30000, max_tokens: 4096 }这里每个字段都有讲究。api_base是 API 端点地址如果你用的是官方服务就填官方地址如果用第三方兼容服务就填对应的地址。api_key是认证密钥注意不要把这个文件提交到 Git 仓库里。model指定默认使用的模型名称。timeout是请求超时时间单位毫秒网络不好的话可以适当调大。max_tokens控制单次响应的最大 token 数。注意配置文件的格式JSON 还是 TOML和字段名称可能随 Codex 版本变化。如果你照着某篇教程配了但报无法解析配置文件的错先确认你的 Codex 版本对应的配置格式。用codex --help或者查阅对应版本的文档可以确认。4.3 codex接入deepseek 的配置思路codex接入deepseek是最近问得比较多的一个场景。核心思路是把 Codex 的 API 端点指向 DeepSeek 提供的兼容接口然后把模型名称改成 DeepSeek 对应的模型标识。具体来说你需要做两件事第一在配置文件里把api_base改成 DeepSeek 的 API 地址。第二把api_key换成你在 DeepSeek 平台申请的密钥。第三把model字段改成 DeepSeek 支持的模型名称。配置改完之后建议先用一个简单的请求测试连通性别一上来就跑复杂任务。如果报 401 错误说明密钥不对报 404 说明端点地址写错了报超时说明网络不通需要检查代理设置。4.4 codex国内能用吗网络层面的现实问题codex国内能用吗这个问题要分两层看。如果你用的是官方服务那网络连通性取决于官方服务在你这边的可达性。如果你接的是国内可访问的第三方兼容服务比如 DeepSeek 这类那基本没有网络障碍。我的建议是优先考虑国内可直连的兼容服务延迟低、稳定性好不用折腾网络配置。如果你确实需要访问某些特定服务确保你的网络环境符合当地法律法规的要求。5. VSCode 集成让 Codex 在编辑器里跑起来5.1 VSCode 安装与基础配置vscode安装教程和vscode官方下载是高频搜索词说明很多人是从这一步开始的。VSCode 的安装本身没什么坑官网下载 Windows 版本双击安装一路下一步就行。安装时建议勾选添加到 PATH和将通过 Code 打开操作添加到 Windows 资源管理器目录上下文菜单后面用起来方便。装完之后第一件事是vscode汉化——在扩展市场搜 Chinese 安装中文语言包重启即可。第二件事是配置终端。VSCode 默认用 PowerShell 作为集成终端如果你在第 3 节已经把执行策略改好了这里应该能正常跑 npm。如果还是报错可以在 VSCode 设置里搜索terminal.integrated.defaultProfile.windows把它改成Command Prompt。5.2 在 VSCode 终端里使用 Codex 的注意事项VSCode 的集成终端和独立终端有一个关键区别环境变量的加载时机。VSCode 在启动时会读取一次系统环境变量之后你在外部修改了环境变量VSCode 不会自动感知。所以如果你在装 VSCode 之后才配置的 Node.js 环境变量VSCode 终端里可能找不到 node 和 npm。解决办法很简单完全关闭 VSCode不是最小化是退出进程然后重新打开。另一个常见问题是终端编码。Windows 中文环境下终端默认编码可能是 GBK而 Codex 输出的内容可能是 UTF-8导致中文显示乱码。可以在 VSCode 设置里把terminal.integrated.defaultEncoding改成utf8或者在终端里执行chcp 650015.3 相关插件与生态工具vscode插件生态里有几个和 Codex 配合使用的工具值得关注。比如vscode配置claude code和vscode bigmodel智谱插件这类本质上都是把 AI 编程助手集成到编辑器里。它们的配置逻辑和 Codex 类似——指定 API 端点、填密钥、选模型。如果你同时用多个 AI 编程工具建议给每个工具单独的配置文件别混在一起。我见过有人把不同工具的配置写进同一个文件结果字段冲突导致两个都用不了。codex无法加载组织设置这个报错有时候就是配置文件里混入了其他工具的字段导致的。6. 那些教程不会告诉你的踩坑实录6.1 npm 全局包卸载不干净导致的版本冲突npm卸载全局包看起来简单但实际操作中经常出问题。假设你之前装过 Codex 的旧版本现在想升级到新版本直接npm install -g codex有时候会出现新旧文件混在一起的情况导致codex --version显示的版本号和实际行为对不上。正确的升级流程是npm uninstall -g codex npm cache clean --force npm install -g codex先卸载清缓存再装。多花十几秒省去后面排查版本冲突的半小时。6.2 权限问题管理员终端不是万能药很多人遇到权限报错的第一反应是用管理员身份运行终端。这在某些场景下确实管用但 npm 的全局安装反而不建议用管理员权限。原因是用管理员权限装的全局包文件所有者是 Administrator之后你用普通用户权限运行时可能读不到这些文件。更麻烦的是某些包在安装时会根据当前用户生成配置文件管理员权限下生成的配置路径和普通用户不一样导致运行时找不到配置。我的原则是能用普通用户权限解决的就不用管理员权限。只有涉及到修改系统级配置比如系统环境变量、系统级服务时才用管理员终端。6.3 网络超时与镜像源的临时切换npm镜像源地址的切换是个双刃剑。国内镜像源下载速度快但同步有延迟某些刚发布的新版本包可能还没同步过来。如果你装 Codex 时遇到找不到指定版本的报错先试试切回官方源npm config set registry https://registry.npmjs.org装完再切回国内源。或者用npx临时指定源npm install -g codex --registryhttps://registry.npmjs.org6.4 配置文件编码问题导致的解析失败Windows 上用记事本编辑配置文件有个隐藏坑记事本默认保存为带 BOM 的 UTF-8而很多解析器不认 BOM会报配置文件格式错误。解决办法是别用记事本用 VSCode 或者 Notepad 编辑保存时选择UTF-8 无 BOM格式。这个坑特别隐蔽因为文件内容看起来完全正常但解析器就是在第一个字符处失败。我当初排查这个问题花了快一个小时最后用十六进制编辑器打开文件才发现开头多了三个字节的 BOM 标记。6.5 代理设置与 local proxy 报错cc switch local proxy failed while handling codex endpoint /responses这个报错通常和代理配置有关。Codex 在请求 API 时会读取系统的代理设置如果你之前配过代理但后来代理服务关了Codex 还是会尝试走代理然后连接失败。排查方法是检查环境变量里的HTTP_PROXY和HTTPS_PROXYecho $env:HTTP_PROXY echo $env:HTTPS_PROXY如果有值但你的代理已经不用了清掉这两个环境变量Remove-Item Env:\HTTP_PROXY Remove-Item Env:\HTTPS_PROXY或者在 Codex 的配置文件里显式指定不使用代理。7. 让 Codex 稳定运行的几个长期习惯7.1 固定 Node.js 版本别频繁切换如果你用 nvm-windows 管理多个 Node.js 版本每次切换版本都会重新生成 npm 的全局 bin 目录链接。这意味着你切换版本之后之前全局安装的 Codex 可能就找不到了需要重新安装。我的做法是选定一个稳定的 LTS 版本比如 20.x长期用这个版本不轻易切换。如果确实需要多版本共存给每个版本单独装一遍 Codex。7.2 定期清理 npm 缓存npm 的缓存目录用久了会积累大量旧版本的包文件不仅占磁盘空间还可能导致安装时用到过期的缓存。每隔一两个月跑一次npm cache verify这个命令会检查缓存的完整性并清理无效条目。如果缓存问题严重可以用npm cache clean --force彻底清空但清空后第一次安装会比较慢。7.3 配置文件版本化管理如果你在多台机器上用 Codex建议把配置文件用一个私有的 Git 仓库管理起来。注意是私有仓库因为配置文件里有 API 密钥。更好的做法是把密钥单独放在环境变量里配置文件里只放非敏感参数这样配置文件即使泄露也不会暴露密钥。具体做法是在配置文件里用占位符引用环境变量比如api_key: ${CODEX_API_KEY}然后在系统环境变量里设置CODEX_API_KEY的值。不同 Codex 版本对环境变量插值的支持程度不同具体要看对应版本的文档。7.4 日志排查的基本思路Codex 运行出问题时第一手信息在日志里。Windows 上 Codex 的日志通常放在用户主目录下的.codex/logs或者%APPDATA%\codex\logs目录里。遇到报错先看日志比在网上到处搜报错信息高效得多。日志排查的基本顺序是先看时间戳定位到出错的那次请求然后看错误级别ERROR 和 WARN 优先最后看错误信息里的关键词比如 timeout、unauthorized、not found 这些基本能判断问题方向。8. 一些零散但有用的经验关于codex官网登录入口如果你用的是需要登录的官方服务注意登录态是有有效期的。长时间不用之后重新打开 Codex可能需要重新登录。如果登录时提示无法加载组织设置通常是登录态过期或者账号权限变更导致的退出重新登录一般能解决。关于codex使用教程里经常提到的快捷键和命令我建议先把codex --help的输出完整看一遍。很多人上来就找教程其实工具自带的帮助信息是最准确的而且和你的版本完全匹配。教程可能对应的是旧版本命令已经变了。关于windows启动elasticsearch、gpustack部署模型windows这类和 Codex 间接相关的工具如果你在 Windows 上跑本地模型服务注意这些服务默认监听的端口别和 Codex 的端口冲突。常见的冲突端口包括 3000、8080、11434 这些。遇到端口被占用的报错用netstat -ano | findstr :端口号找到占用进程然后决定是换端口还是停掉那个进程。关于vscode配置c/c环境和sfml vscode 配置这类和 Codex 无关但同样在 Windows 上容易踩坑的场景核心逻辑是一样的路径别带空格、环境变量配对、终端编码统一。这三条原则适用于 Windows 上几乎所有开发工具的配置。最后说一个我自己的习惯每次在 Windows 上配置一个新工具我都会先在一个干净的 PowerShell 窗口里跑一遍最小验证流程——检查版本、检查路径、跑一个最简单的命令。这三步花不了一分钟但能提前发现 80% 的环境问题。等最小流程跑通了再去折腾配置文件、集成编辑器这些进阶操作。顺序反了的话出了问题你都不知道是环境的问题还是配置的问题。Codex 在 Windows 上的配置说到底就是和 Windows 的历史包袱打交道。PowerShell 的执行策略、npm 的路径机制、环境变量的加载时机这三座大山翻过去之后剩下的就是常规的配置文件调优了。希望这篇内容能帮你少走几个我当年走过的弯路。 
长河君 · 2026/10/9 9:39:05 · 阅读 1.2k Windows 上跑 Codex 总卡第一步？Node.js 与 npm 环境配置避坑指南
1. 为什么 Windows 上跑 Codex 总在第一步就卡住如果你在 Windows 上折腾过 Codex大概率经历过这样的场景照着某篇教程敲下第一条命令终端直接甩出一行红字——npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。然后你开始怀疑人生怀疑自己是不是装了个假 Node.js。这不是你的问题也不是 Codex 的问题而是 Windows 这套系统在安全默认值和开发者体验之间长期拉扯留下的历史包袱。PowerShell 默认的执行策略是Restricted意思是任何.ps1脚本都不许跑而 npm 在 Windows 上恰恰是通过npm.ps1这个包装脚本来调用的。于是你装好了 Node.jsnode -v能出结果但npm -v直接报错整个链路从第一步就断了。这篇内容面向的是所有在 Windows 环境下想用 Codex 的人——不管你是刚接触命令行工具的新手还是从 macOS/Linux 转过来、被 Windows 各种惊喜教育过的老手。我会把从 Node.js 环境搭建、npm 配置、Codex 安装、配置文件解析到实际使用中可能遇到的各种坑完整地讲一遍。核心关键词包括Codex、Windows、Node.js、npm、VSCode同时也会覆盖codex安装教程、codex配置文件解析、codex接入deepseek、codex国内能用吗这些大家最关心的问题。先说结论Windows 上跑 Codex 完全可行但需要你理解三件事——PowerShell 的执行策略、npm 的全局路径机制、以及 Codex 的配置文件结构。这三件事搞明白了后面基本就是一马平川。下面我按实际操作的顺序从环境准备开始一步步拆。2. Node.js 安装别用微软商店版本也别装在带空格的路径2.1 为什么安装源的选择比版本号更重要很多人装 Node.js 的第一反应是打开微软商店搜一下或者去官网随便下个 LTS 版本。这里有个容易被忽略的细节微软商店版本的 Node.js 在权限和路径管理上经常出幺蛾子尤其是涉及到全局包安装和 npm 前缀配置的时候你会发现自己明明用管理员权限开了终端npm 还是告诉你没有写入权限。我的建议很直接去 Node.js 官网下载Windows Installer (.msi)版本选 LTS长期支持分支。截至我写这篇内容的时候Node.js 20.x 和 22.x 都是稳定的 LTS 选择。为什么强调 LTS因为 Codex 依赖的一些底层包对 Node 版本有要求太老的版本比如 16.x 以下会在安装依赖时直接报引擎不兼容太新的尝鲜版又可能遇到原生模块编译失败的问题。安装路径这块有个经典坑默认路径C:\Program Files\nodejs\里带空格。大部分情况下没问题但某些工具在处理路径拼接时对空格处理不当就会导致莫名其妙的错误。如果你不嫌麻烦可以改成C:\nodejs\这种干净路径。我自己的机器上用的是D:\Program Files\nodejs\用了两年多没出过路径相关的问题所以带空格也不是绝对不行只是多一层风险。安装过程中有一个选项一定要注意Add to PATH 必须勾上。如果你忘了勾装完之后在终端里敲node -v会提示不是内部或外部命令。补救办法是手动把 Node.js 安装目录加到系统环境变量的 Path 里然后重开终端。2.2 验证安装与 npm 环境变量 Path 配置装完之后别急着往下走先做三步验证node -v npm -v where node where npm前两条看版本号是否正常输出后两条看路径是否指向你刚装的目录。如果where npm输出的路径里出现了多个结果说明你之前可能装过其他版本的 Node.js环境变量里有残留需要清理掉旧路径。关于npm环境变量path配置这里展开说一下。npm 有两类包本地包和全局包。本地包装在项目目录下的node_modules里全局包装在 npm 的全局前缀目录里。Windows 上默认的全局前缀是%APPDATA%\npm也就是C:\Users\你的用户名\AppData\Roaming\npm。这个目录必须加到系统 Path 里否则你全局安装的命令行工具比如 Codex在终端里根本找不到。验证方法很简单npm config get prefix输出的路径就是全局前缀。然后检查这个路径是否在系统环境变量的 Path 列表里。如果没有手动加上重开终端。注意修改环境变量后一定要关闭所有终端窗口重新打开已经打开的终端不会自动加载新的环境变量。这个细节看起来废话但我见过太多人改完 Path 之后在当前终端里反复试然后说改了没用。2.3 npm 全局安装和本地安装的区别以及为什么 Codex 要全局装npm全局安装和本地安装的区别是个老生常谈的话题但放到 Codex 这个场景下值得再说一次。本地安装npm install codex会把包装在当前项目的node_modules里只有在这个项目目录下才能通过npx调用。全局安装npm install -g codex会把包装到全局前缀目录并且把可执行文件链接到全局 bin 目录这样你在任何目录下都能直接用codex命令。Codex 作为一个命令行工具显然应该全局装。但全局装的前提是全局前缀目录已经正确配置在 Path 里否则装完了也调不出来。3. PowerShell 执行策略那个让 npm 报错的元凶3.1 报错信息的完整解读回到开头那个报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这条信息的每一个部分都值得拆开看。无法加载文件说明 PowerShell 找到了npm.ps1这个文件但拒绝执行它。因为在此系统上禁止运行脚本直接点明了原因——执行策略限制。PowerShell 有四种主要的执行策略执行策略含义能否跑 npmRestricted禁止所有脚本否AllSigned只允许签名脚本否除非 npm.ps1 有签名RemoteSigned本地脚本可跑远程脚本需签名是Unrestricted全部允许是Windows 客户端系统默认是Restricted服务器系统默认是RemoteSigned。所以你在 Windows 10/11 上装完 Node.js第一次跑 npm 就会撞上这堵墙。3.2 修改执行策略的正确姿势解决办法是把当前用户的执行策略改成RemoteSignedSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这里有几个细节要注意。第一-Scope CurrentUser表示只改当前用户不需要管理员权限也不会影响系统上其他用户。第二改完之后用Get-ExecutionPolicy -List确认一下你应该能看到 CurrentUser 那一行显示RemoteSigned。第三如果你用的是 VSCode 内置终端改完之后需要重启 VSCode因为终端进程是在 VSCode 启动时创建的不会自动刷新执行策略。还有一种情况你用的是公司配的电脑组策略锁死了执行策略Set-ExecutionPolicy会报被组策略覆盖之类的错误。这种时候可以试试在命令前面加cmd /c来绕过 PowerShell 脚本层直接走 cmd 的 npm.cmdcmd /c npm -v但这只是权宜之计长期用还是建议找 IT 部门放开 CurrentUser 的执行策略权限。3.3 为什么改了策略还是报错几个容易忽略的角落有时候你改了执行策略Get-ExecutionPolicy也显示RemoteSigned了但 npm 还是报同样的错。这种情况通常有几个原因一是你改的是 64 位 PowerShell 的策略但 VSCode 终端用的是 32 位版本两者策略不互通。解决办法是在 VSCode 里确认终端类型或者干脆在 VSCode 设置里把默认终端改成Command Prompt。二是你的 npm 是通过 nvm-windows 管理的nvm 会在切换 Node 版本时重新生成npm.ps1如果新生成的文件被标记为来自远程RemoteSigned 策略下依然会被拦截。这种情况可以用Unblock-File命令解除锁定Unblock-File -Path C:\Program Files\nodejs\npm.ps1三是杀毒软件在中间拦截了脚本执行。某些安全软件会把 PowerShell 脚本执行当成可疑行为静默阻止。如果你排查了一圈都没找到原因可以临时关闭杀毒软件试试确认是它的问题之后再把它加到白名单里。4. Codex 安装与配置文件解析4.1 安装命令与版本选择环境准备好之后安装 Codex 本身反而最简单npm install -g codex如果你在国内网络环境下遇到下载慢或者超时的问题可以临时切换 npm 镜像源npm config set registry https://registry.npmmirror.com装完之后验证codex --version能输出版本号就说明安装成功了。如果提示不是内部或外部命令回去检查第 2.2 节讲的全局前缀 Path 配置。关于codex安装包和codex下载有些人喜欢去官网直接下二进制包。我的建议是能用 npm 装就用 npm 装因为 npm 会自动处理依赖关系和版本兼容性手动下二进制包反而容易漏掉运行时依赖。4.2 配置文件的位置与结构codex配置文件解析是很多人卡住的地方。Codex 的配置文件通常放在用户主目录下的.codex文件夹里Windows 上的完整路径是C:\Users\你的用户名\.codex\这个目录下可能有几个文件具体取决于你安装的 Codex 版本和配置方式。常见的包括config.json、config.toml或者.env文件。配置文件的核心作用是指定 API 端点、认证信息、模型选择、超时设置这些参数。一个典型的配置文件结构大概长这样以 JSON 为例{ api_base: https://your-api-endpoint/v1, api_key: your-api-key-here, model: codex-model-name, timeout: 30000, max_tokens: 4096 }这里每个字段都有讲究。api_base是 API 端点地址如果你用的是官方服务就填官方地址如果用第三方兼容服务就填对应的地址。api_key是认证密钥注意不要把这个文件提交到 Git 仓库里。model指定默认使用的模型名称。timeout是请求超时时间单位毫秒网络不好的话可以适当调大。max_tokens控制单次响应的最大 token 数。注意配置文件的格式JSON 还是 TOML和字段名称可能随 Codex 版本变化。如果你照着某篇教程配了但报无法解析配置文件的错先确认你的 Codex 版本对应的配置格式。用codex --help或者查阅对应版本的文档可以确认。4.3 codex接入deepseek 的配置思路codex接入deepseek是最近问得比较多的一个场景。核心思路是把 Codex 的 API 端点指向 DeepSeek 提供的兼容接口然后把模型名称改成 DeepSeek 对应的模型标识。具体来说你需要做两件事第一在配置文件里把api_base改成 DeepSeek 的 API 地址。第二把api_key换成你在 DeepSeek 平台申请的密钥。第三把model字段改成 DeepSeek 支持的模型名称。配置改完之后建议先用一个简单的请求测试连通性别一上来就跑复杂任务。如果报 401 错误说明密钥不对报 404 说明端点地址写错了报超时说明网络不通需要检查代理设置。4.4 codex国内能用吗网络层面的现实问题codex国内能用吗这个问题要分两层看。如果你用的是官方服务那网络连通性取决于官方服务在你这边的可达性。如果你接的是国内可访问的第三方兼容服务比如 DeepSeek 这类那基本没有网络障碍。我的建议是优先考虑国内可直连的兼容服务延迟低、稳定性好不用折腾网络配置。如果你确实需要访问某些特定服务确保你的网络环境符合当地法律法规的要求。5. VSCode 集成让 Codex 在编辑器里跑起来5.1 VSCode 安装与基础配置vscode安装教程和vscode官方下载是高频搜索词说明很多人是从这一步开始的。VSCode 的安装本身没什么坑官网下载 Windows 版本双击安装一路下一步就行。安装时建议勾选添加到 PATH和将通过 Code 打开操作添加到 Windows 资源管理器目录上下文菜单后面用起来方便。装完之后第一件事是vscode汉化——在扩展市场搜 Chinese 安装中文语言包重启即可。第二件事是配置终端。VSCode 默认用 PowerShell 作为集成终端如果你在第 3 节已经把执行策略改好了这里应该能正常跑 npm。如果还是报错可以在 VSCode 设置里搜索terminal.integrated.defaultProfile.windows把它改成Command Prompt。5.2 在 VSCode 终端里使用 Codex 的注意事项VSCode 的集成终端和独立终端有一个关键区别环境变量的加载时机。VSCode 在启动时会读取一次系统环境变量之后你在外部修改了环境变量VSCode 不会自动感知。所以如果你在装 VSCode 之后才配置的 Node.js 环境变量VSCode 终端里可能找不到 node 和 npm。解决办法很简单完全关闭 VSCode不是最小化是退出进程然后重新打开。另一个常见问题是终端编码。Windows 中文环境下终端默认编码可能是 GBK而 Codex 输出的内容可能是 UTF-8导致中文显示乱码。可以在 VSCode 设置里把terminal.integrated.defaultEncoding改成utf8或者在终端里执行chcp 650015.3 相关插件与生态工具vscode插件生态里有几个和 Codex 配合使用的工具值得关注。比如vscode配置claude code和vscode bigmodel智谱插件这类本质上都是把 AI 编程助手集成到编辑器里。它们的配置逻辑和 Codex 类似——指定 API 端点、填密钥、选模型。如果你同时用多个 AI 编程工具建议给每个工具单独的配置文件别混在一起。我见过有人把不同工具的配置写进同一个文件结果字段冲突导致两个都用不了。codex无法加载组织设置这个报错有时候就是配置文件里混入了其他工具的字段导致的。6. 那些教程不会告诉你的踩坑实录6.1 npm 全局包卸载不干净导致的版本冲突npm卸载全局包看起来简单但实际操作中经常出问题。假设你之前装过 Codex 的旧版本现在想升级到新版本直接npm install -g codex有时候会出现新旧文件混在一起的情况导致codex --version显示的版本号和实际行为对不上。正确的升级流程是npm uninstall -g codex npm cache clean --force npm install -g codex先卸载清缓存再装。多花十几秒省去后面排查版本冲突的半小时。6.2 权限问题管理员终端不是万能药很多人遇到权限报错的第一反应是用管理员身份运行终端。这在某些场景下确实管用但 npm 的全局安装反而不建议用管理员权限。原因是用管理员权限装的全局包文件所有者是 Administrator之后你用普通用户权限运行时可能读不到这些文件。更麻烦的是某些包在安装时会根据当前用户生成配置文件管理员权限下生成的配置路径和普通用户不一样导致运行时找不到配置。我的原则是能用普通用户权限解决的就不用管理员权限。只有涉及到修改系统级配置比如系统环境变量、系统级服务时才用管理员终端。6.3 网络超时与镜像源的临时切换npm镜像源地址的切换是个双刃剑。国内镜像源下载速度快但同步有延迟某些刚发布的新版本包可能还没同步过来。如果你装 Codex 时遇到找不到指定版本的报错先试试切回官方源npm config set registry https://registry.npmjs.org装完再切回国内源。或者用npx临时指定源npm install -g codex --registryhttps://registry.npmjs.org6.4 配置文件编码问题导致的解析失败Windows 上用记事本编辑配置文件有个隐藏坑记事本默认保存为带 BOM 的 UTF-8而很多解析器不认 BOM会报配置文件格式错误。解决办法是别用记事本用 VSCode 或者 Notepad 编辑保存时选择UTF-8 无 BOM格式。这个坑特别隐蔽因为文件内容看起来完全正常但解析器就是在第一个字符处失败。我当初排查这个问题花了快一个小时最后用十六进制编辑器打开文件才发现开头多了三个字节的 BOM 标记。6.5 代理设置与 local proxy 报错cc switch local proxy failed while handling codex endpoint /responses这个报错通常和代理配置有关。Codex 在请求 API 时会读取系统的代理设置如果你之前配过代理但后来代理服务关了Codex 还是会尝试走代理然后连接失败。排查方法是检查环境变量里的HTTP_PROXY和HTTPS_PROXYecho $env:HTTP_PROXY echo $env:HTTPS_PROXY如果有值但你的代理已经不用了清掉这两个环境变量Remove-Item Env:\HTTP_PROXY Remove-Item Env:\HTTPS_PROXY或者在 Codex 的配置文件里显式指定不使用代理。7. 让 Codex 稳定运行的几个长期习惯7.1 固定 Node.js 版本别频繁切换如果你用 nvm-windows 管理多个 Node.js 版本每次切换版本都会重新生成 npm 的全局 bin 目录链接。这意味着你切换版本之后之前全局安装的 Codex 可能就找不到了需要重新安装。我的做法是选定一个稳定的 LTS 版本比如 20.x长期用这个版本不轻易切换。如果确实需要多版本共存给每个版本单独装一遍 Codex。7.2 定期清理 npm 缓存npm 的缓存目录用久了会积累大量旧版本的包文件不仅占磁盘空间还可能导致安装时用到过期的缓存。每隔一两个月跑一次npm cache verify这个命令会检查缓存的完整性并清理无效条目。如果缓存问题严重可以用npm cache clean --force彻底清空但清空后第一次安装会比较慢。7.3 配置文件版本化管理如果你在多台机器上用 Codex建议把配置文件用一个私有的 Git 仓库管理起来。注意是私有仓库因为配置文件里有 API 密钥。更好的做法是把密钥单独放在环境变量里配置文件里只放非敏感参数这样配置文件即使泄露也不会暴露密钥。具体做法是在配置文件里用占位符引用环境变量比如api_key: ${CODEX_API_KEY}然后在系统环境变量里设置CODEX_API_KEY的值。不同 Codex 版本对环境变量插值的支持程度不同具体要看对应版本的文档。7.4 日志排查的基本思路Codex 运行出问题时第一手信息在日志里。Windows 上 Codex 的日志通常放在用户主目录下的.codex/logs或者%APPDATA%\codex\logs目录里。遇到报错先看日志比在网上到处搜报错信息高效得多。日志排查的基本顺序是先看时间戳定位到出错的那次请求然后看错误级别ERROR 和 WARN 优先最后看错误信息里的关键词比如 timeout、unauthorized、not found 这些基本能判断问题方向。8. 一些零散但有用的经验关于codex官网登录入口如果你用的是需要登录的官方服务注意登录态是有有效期的。长时间不用之后重新打开 Codex可能需要重新登录。如果登录时提示无法加载组织设置通常是登录态过期或者账号权限变更导致的退出重新登录一般能解决。关于codex使用教程里经常提到的快捷键和命令我建议先把codex --help的输出完整看一遍。很多人上来就找教程其实工具自带的帮助信息是最准确的而且和你的版本完全匹配。教程可能对应的是旧版本命令已经变了。关于windows启动elasticsearch、gpustack部署模型windows这类和 Codex 间接相关的工具如果你在 Windows 上跑本地模型服务注意这些服务默认监听的端口别和 Codex 的端口冲突。常见的冲突端口包括 3000、8080、11434 这些。遇到端口被占用的报错用netstat -ano | findstr :端口号找到占用进程然后决定是换端口还是停掉那个进程。关于vscode配置c/c环境和sfml vscode 配置这类和 Codex 无关但同样在 Windows 上容易踩坑的场景核心逻辑是一样的路径别带空格、环境变量配对、终端编码统一。这三条原则适用于 Windows 上几乎所有开发工具的配置。最后说一个我自己的习惯每次在 Windows 上配置一个新工具我都会先在一个干净的 PowerShell 窗口里跑一遍最小验证流程——检查版本、检查路径、跑一个最简单的命令。这三步花不了一分钟但能提前发现 80% 的环境问题。等最小流程跑通了再去折腾配置文件、集成编辑器这些进阶操作。顺序反了的话出了问题你都不知道是环境的问题还是配置的问题。Codex 在 Windows 上的配置说到底就是和 Windows 的历史包袱打交道。PowerShell 的执行策略、npm 的路径机制、环境变量的加载时机这三座大山翻过去之后剩下的就是常规的配置文件调优了。希望这篇内容能帮你少走几个我当年走过的弯路。