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

前言

最近在 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/?LinkID=135170 中的 about_Execution_Policies。
所在位置 行:1 字符:1
+ openspec-cn init
+ ~~~~~~~~~~~
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : 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 init

PowerShell 很可能会优先执行 npm 生成的 openspec-cn.ps1 文件。

但是 Windows PowerShell 默认有一套执行策略，也就是 ExecutionPolicy。如果当前策略不允许运行脚本，那么 .ps1 文件就会被拦截，于是出现：

因为在此系统上禁止运行脚本

这不是 openspec-cn 的 bug，也不是 Node.js 或 npm 一定坏了，而是 PowerShell 的安全机制在起作用。

三、先查看当前 PowerShell 执行策略

建议先执行下面的命令查看策略状态：

Get-ExecutionPolicy -List

可能会看到类似输出：

        Scope ExecutionPolicy
        ----- ---------------
MachinePolicy       Undefined
   UserPolicy       Undefined
      Process       Undefined
  CurrentUser       Undefined
 LocalMachine       Undefined

这里几个作用域的含义大致如下：

MachinePolicy：由组策略控制，优先级最高
UserPolicy：由用户组策略控制
Process：当前 PowerShell 进程有效
CurrentUser：当前 Windows 用户有效
LocalMachine：当前电脑所有用户有效

如果全是 Undefined，PowerShell 会采用系统默认策略。在很多 Windows 环境下，这个默认策略会导致 .ps1 脚本无法执行。

四、推荐解决方案：只修改当前用户执行策略

最推荐的方式是只修改当前用户作用域，不要直接改整台机器的策略。

执行下面的命令：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force

这条命令的含义是：

Scope CurrentUser：只对当前 Windows 用户生效
ExecutionPolicy RemoteSigned：本地脚本可以运行，远程下载的脚本需要可信签名
Force：不弹出确认提示

设置完成后，再次查看策略：

Get-ExecutionPolicy -List

正常情况下会看到：

        Scope ExecutionPolicy
        ----- ---------------
MachinePolicy       Undefined
   UserPolicy       Undefined
      Process       Undefined
  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-Object FullName

可能看到类似结构：

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

# 将当前用户执行策略设置为 RemoteSigned
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force

# 再次确认执行策略是否生效
Get-ExecutionPolicy -List

# 验证 openspec-cn 是否能正常运行
openspec-cn --version

# 进入你的项目目录
cd D:\person-vibecode-wordspace\codex-useopenspec-tochrome

# 为 Codex 初始化 OpenSpec
openspec-cn init --tools codex

注意：上面命令中的项目路径需要替换成你自己的实际项目路径。

九、为什么不建议直接使用 LocalMachine

网上有些教程会让你执行：

Set-ExecutionPolicy RemoteSigned

或者：

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 报未检测到工具

这不是报错，而是需要你指定目标工具。

如果你用 Codex：

openspec-cn init --tools codex

如果你用 Cursor：

openspec-cn init --tools cursor

如果你想一次生成多个工具适配：

openspec-cn init --tools codex,cursor

如果你想生成全部支持的工具配置：

openspec-cn init --tools all

4. 初始化成功后斜杠命令不能用

初始化输出中通常会提示：

重启您的 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 初始化目标工具。两个问题分开看，就不会被连续报错绕晕。