Windows 11 使用 openspec-cn 初始化 Codex 项目失败？PowerShell 执行策略报错完整解决教程

Windows 11 使用 openspec-cn 初始化 Codex 项目失败PowerShell 执行策略报错完整解决教程文章目录Windows 11 使用 openspec-cn 初始化 Codex 项目失败PowerShell 执行策略报错完整解决教程前言一、问题现象二、为什么会出现这个问题三、先查看当前 PowerShell 执行策略四、推荐解决方案只修改当前用户执行策略五、验证 openspec-cn 是否恢复正常六、继续初始化 OpenSpec 项目七、初始化后会生成哪些目录八、完整操作命令汇总九、为什么不建议直接使用 LocalMachine十、如果公司电脑不允许修改执行策略怎么办十一、PowerShell 输出中文乱码怎么办十二、常见问题排查1. 执行 openspec-cn 仍然提示无法加载 ps12. 设置了 RemoteSigned 还是不行3. init 报未检测到工具4. 初始化成功后斜杠命令不能用5. 是否需要管理员权限十三、最终验证清单十四、本文总结前言最近在 Windows 11 上使用openspec-cn初始化项目时很多人会遇到一个非常典型的问题命令明明已经安装好了但一执行就报红而且错误信息里出现了无法加载文件、PSSecurityException、UnauthorizedAccess等字样。例如执行下面的命令openspec-cn init结果 PowerShell 直接报错openspec-cn : 无法加载文件 C:\Users\evan\AppData\Roaming\npm\openspec-cn.ps1因为在此系统上禁止运行脚本。 有关详细信息请参阅 https://go.microsoft.com/fwlink/?LinkID135170 中的 about_Execution_Policies。 所在位置 行:1 字符:1openspec-cn init~~~~~~~~~~~CategoryInfo : SecurityError:(:)[],PSSecurityExceptionFullyQualifiedErrorId : UnauthorizedAccess这类问题看起来像是openspec-cn安装失败或者 npm 环境异常但实际上大多数情况下并不是工具本身的问题而是 Windows PowerShell 的执行策略阻止了.ps1脚本运行。本文会从报错原因、修复方式、初始化 Codex 项目、验证结果、常见坑位几个方面完整讲清楚。照着做基本可以一次解决。一、问题现象当前环境大致如下系统Windows 11 终端Windows PowerShell 工具openspec-cn 项目目录D:\person-vibecode-wordspace\codex-useopenspec-tochrome在项目目录中执行openspec-cn init或者查看版本openspec-cn--version都会出现类似下面的报错openspec-cn : 无法加载文件 C:\Users\evan\AppData\Roaming\npm\openspec-cn.ps1因为在此系统上禁止运行脚本。关键错误信息是这几段无法加载文件 openspec-cn.ps1 因为在此系统上禁止运行脚本 PSSecurityException UnauthorizedAccess只要你看到这些关键词基本就可以判断这是 PowerShell 执行策略限制导致的脚本拦截问题。二、为什么会出现这个问题在 Windows 上通过 npm 全局安装的命令行工具通常会在 npm 全局目录下生成几个启动脚本。以openspec-cn为例可能会生成类似这些文件openspec-cn openspec-cn.cmd openspec-cn.ps1当你在 PowerShell 中输入openspec-cn initPowerShell 很可能会优先执行 npm 生成的openspec-cn.ps1文件。但是 Windows PowerShell 默认有一套执行策略也就是ExecutionPolicy。如果当前策略不允许运行脚本那么.ps1文件就会被拦截于是出现因为在此系统上禁止运行脚本这不是openspec-cn的 bug也不是 Node.js 或 npm 一定坏了而是 PowerShell 的安全机制在起作用。三、先查看当前 PowerShell 执行策略建议先执行下面的命令查看策略状态Get-ExecutionPolicy-List可能会看到类似输出Scope ExecutionPolicy--------------------MachinePolicy Undefined UserPolicy UndefinedProcessUndefined CurrentUser Undefined LocalMachine Undefined这里几个作用域的含义大致如下MachinePolicy由组策略控制优先级最高 UserPolicy由用户组策略控制 Process当前 PowerShell 进程有效 CurrentUser当前 Windows 用户有效 LocalMachine当前电脑所有用户有效如果全是UndefinedPowerShell 会采用系统默认策略。在很多 Windows 环境下这个默认策略会导致.ps1脚本无法执行。四、推荐解决方案只修改当前用户执行策略最推荐的方式是只修改当前用户作用域不要直接改整台机器的策略。执行下面的命令Set-ExecutionPolicy-Scope CurrentUser-ExecutionPolicy RemoteSigned-Force这条命令的含义是Scope CurrentUser只对当前 Windows 用户生效 ExecutionPolicy RemoteSigned本地脚本可以运行远程下载的脚本需要可信签名 Force不弹出确认提示设置完成后再次查看策略Get-ExecutionPolicy-List正常情况下会看到Scope ExecutionPolicy--------------------MachinePolicy Undefined UserPolicy UndefinedProcessUndefined CurrentUser RemoteSigned LocalMachine Undefined重点是这一行CurrentUser RemoteSigned这说明当前用户的 PowerShell 执行策略已经修改成功。五、验证 openspec-cn 是否恢复正常执行版本命令openspec-cn--version如果返回类似结果1.4.1说明openspec-cn已经可以正常运行。如果这一步正常就代表最初的.ps1脚本拦截问题已经解决。六、继续初始化 OpenSpec 项目接下来回到项目目录例如cd D:\person-vibecode-wordspace\codex-useopenspec-tochrome再次执行初始化openspec-cn init这时可能还会遇到另一个错误错误未检测到工具且未提供 --tools 参数。有效工具 amazon-q antigravity auggie bob claude cline codex ... 请使用 --tools all、--tools none 或 --tools claude,cursor,...这个错误和 PowerShell 执行策略已经不是一回事了。它的意思是openspec-cn不知道你要为哪个 AI 编程工具生成适配文件所以需要你通过--tools参数明确指定。如果你当前使用的是 Codex可以执行openspec-cn init--tools codex执行成功后会看到类似输出正在创建 OpenSpec 结构... OpenSpec 结构已创建 OpenSpec 设置完成 已创建Codex 5 个技能和 5 个命令在 .codex/ 中 配置已跳过 (非交互模式) 开始使用 开始您的第一个变更/opsx:propose 您的想法 重启您的 IDE 以使斜杠命令生效。 正在配置 Codex... Codex 配置完成到这里OpenSpec 和 Codex 的初始化就完成了。七、初始化后会生成哪些目录执行成功后项目目录中一般会多出这些内容.codex openspec其中.codex目录用于存放 Codex 相关的技能和命令openspec目录用于存放 OpenSpec 的规范、变更和归档内容。可以用下面的命令查看Get-ChildItem-Force示例结果Name Mode--------.codex d-----openspec d-----也可以查看更深层级Get-ChildItem-Force-Recurse-Depth 2|Select-ObjectFullName可能看到类似结构D:\person-vibecode-wordspace\codex-useopenspec-tochrome\.codex D:\person-vibecode-wordspace\codex-useopenspec-tochrome\.codex\skills D:\person-vibecode-wordspace\codex-useopenspec-tochrome\.codex\skills\openspec-apply-change D:\person-vibecode-wordspace\codex-useopenspec-tochrome\.codex\skills\openspec-archive-change D:\person-vibecode-wordspace\codex-useopenspec-tochrome\.codex\skills\openspec-explore D:\person-vibecode-wordspace\codex-useopenspec-tochrome\.codex\skills\openspec-propose D:\person-vibecode-wordspace\codex-useopenspec-tochrome\.codex\skills\openspec-sync-specs D:\person-vibecode-wordspace\codex-useopenspec-tochrome\openspec D:\person-vibecode-wordspace\codex-useopenspec-tochrome\openspec\changes D:\person-vibecode-wordspace\codex-useopenspec-tochrome\openspec\changes\archive D:\person-vibecode-wordspace\codex-useopenspec-tochrome\openspec\specs八、完整操作命令汇总如果你只想快速解决可以按顺序执行下面这组命令。# 查看当前 PowerShell 执行策略Get-ExecutionPolicy-List# 将当前用户执行策略设置为 RemoteSignedSet-ExecutionPolicy-Scope CurrentUser-ExecutionPolicy RemoteSigned-Force# 再次确认执行策略是否生效Get-ExecutionPolicy-List# 验证 openspec-cn 是否能正常运行openspec-cn--version# 进入你的项目目录cd D:\person-vibecode-wordspace\codex-useopenspec-tochrome# 为 Codex 初始化 OpenSpecopenspec-cn init--tools codex注意上面命令中的项目路径需要替换成你自己的实际项目路径。九、为什么不建议直接使用 LocalMachine网上有些教程会让你执行Set-ExecutionPolicyRemoteSigned或者Set-ExecutionPolicy-Scope LocalMachine-ExecutionPolicy RemoteSigned这类写法不是一定不行但它会影响整台电脑上的所有用户而且通常需要管理员权限。对于普通开发场景只需要让当前用户能够正常运行 npm 生成的 PowerShell 启动脚本即可所以更推荐Set-ExecutionPolicy-Scope CurrentUser-ExecutionPolicy RemoteSigned-Force这样影响范围更小也更适合个人开发机。十、如果公司电脑不允许修改执行策略怎么办有些公司电脑会通过组策略锁定 PowerShell 执行策略。如果你执行后发现MachinePolicy或UserPolicy不是Undefined例如MachinePolicy Restricted那么说明策略可能被管理员统一管控。此时你强行修改CurrentUser也不一定生效因为组策略优先级更高。你可以先查看Get-ExecutionPolicy-List如果确实是公司策略限制可以考虑这些方案1. 联系管理员放开当前用户的脚本执行权限 2. 使用 cmd.exe 执行对应的 .cmd 启动脚本 3. 使用 Git Bash、Windows Terminal 中的其他 shell 4. 使用 npx 或 node 直接调用包入口绕开 PowerShell 的 .ps1 启动脚本如果只是个人电脑通常设置CurrentUser RemoteSigned就足够了。十一、PowerShell 输出中文乱码怎么办有时命令实际成功了但 PowerShell 中查看 Markdown 或中文文件时出现乱码。这通常是控制台编码显示问题不一定是文件内容坏了。例如普通读取Get-Content.\log.md-Raw可能显示异常。可以改用 UTF-8 方式读取Get-Content.\log.md-Raw-Encoding UTF8如果 UTF-8 读取正常就说明文件本身没有问题。十二、常见问题排查1. 执行 openspec-cn 仍然提示无法加载 ps1先确认执行策略是否真的生效Get-ExecutionPolicy-List重点看CurrentUser RemoteSigned如果没有这一行重新执行Set-ExecutionPolicy-Scope CurrentUser-ExecutionPolicy RemoteSigned-Force然后关闭当前 PowerShell再重新打开一个新窗口测试。2. 设置了 RemoteSigned 还是不行检查是否存在更高优先级策略Get-ExecutionPolicy-List如果MachinePolicy或UserPolicy被设置了说明可能被组策略管控需要联系管理员或者换用其他 shell。3. init 报未检测到工具这不是报错而是需要你指定目标工具。如果你用 Codexopenspec-cn init--tools codex如果你用 Cursoropenspec-cn init--tools cursor如果你想一次生成多个工具适配openspec-cn init--tools codex,cursor如果你想生成全部支持的工具配置openspec-cn init--tools all4. 初始化成功后斜杠命令不能用初始化输出中通常会提示重启您的 IDE 以使斜杠命令生效。所以初始化完成后建议重启 Codex、编辑器或相关 IDE再测试类似命令/opsx:propose 您的想法5. 是否需要管理员权限如果使用推荐命令Set-ExecutionPolicy-Scope CurrentUser-ExecutionPolicy RemoteSigned-Force通常不需要管理员权限因为它只修改当前用户作用域。如果你修改的是LocalMachine则通常需要管理员权限。十三、最终验证清单完成修复后可以按下面清单确认1. openspec-cn --version 可以正常返回版本号 2. Get-ExecutionPolicy -List 中 CurrentUser 为 RemoteSigned 3. openspec-cn init --tools codex 执行成功 4. 项目目录下生成 .codex 目录 5. 项目目录下生成 openspec 目录 6. 重启 IDE 后可以看到或使用 OpenSpec 相关命令只要这些都满足就说明环境已经配置完成。十四、本文总结Windows 11 上执行openspec-cn init报错无法加载文件 openspec-cn.ps1因为在此系统上禁止运行脚本核心原因是 PowerShell 执行策略阻止了 npm 生成的.ps1脚本。推荐解决命令是Set-ExecutionPolicy-Scope CurrentUser-ExecutionPolicy RemoteSigned-Force然后验证openspec-cn--version如果你使用 Codex再执行openspec-cn init--tools codex完成后重启 IDE让 OpenSpec 的 Codex 命令生效。这套流程的关键点是先解决 PowerShell 脚本执行权限再指定--tools初始化目标工具。两个问题分开看就不会被连续报错绕晕。