OpenSpec

故障排除 ​

针对具体问题的具体修复方案。每条记录都会说明症状、用一句话解释可能的原因，并给出修复方法。如果这里没有你的问题，常见问题 可能会有帮助，而 Discord 则一定能帮到你。

安装与配置 ​

openspec: command not found ​

CLI 未安装，或者你的 shell 找不到它。请全局安装并检查：

bash
npm install -g @fission-ai/openspec@latest
openspec --version

如果已安装但仍然找不到，说明你的全局 npm bin 目录可能不在 PATH 中。运行 npm prefix -g 查看全局包的安装位置：在 macOS 和 Linux 上，二进制文件位于该目录的 bin/ 子目录中；在 Windows 上，它们直接位于该目录中。请确保该路径已添加到 PATH。（npm bin -g 已在 npm 9 中移除。）

如果你使用的是 AI 辅助安装，这正是预期的交接点：该提示会让你的助手向你展示 PATH 的更改方式，而不是自行编辑你的 shell 启动文件。

"Requires Node.js 20.19.0 or higher" ​

OpenSpec 需要 Node 20.19.0 或更高版本。请检查你的版本并在必要时升级：

bash
node --version

如果你使用 bun 安装 OpenSpec，请注意 OpenSpec 仍然 运行 在 Node 上，因此无论使用哪种包管理器，你的 PATH 中都需要有 Node 20.19.0+。参见 安装。

openspec init 未配置我的 AI 工具 ​

Init 会询问要配置哪些工具。如果你跳过了某个工具或想添加其他工具，只需重新运行，或使用非交互形式：

bash
openspec init --tools claude,cursor

完整的工具 ID 列表见 支持的工具。使用 --tools all 配置所有工具，使用 --tools none 跳过工具配置。

命令不显示 ​

如果 /opsx:propose（或你工具中的等效命令）没有出现或没有任何反应，请按以下列表逐一排查。顺序按检查速度从快到慢排列。

  1. 你可能在错误的位置。 斜杠命令应在 AI 助手的聊天窗口中输入，而不是在终端中。如果你在 shell 中输入了 /opsx:propose，这就是问题所在。参见 命令工作原理。

  2. 重新生成文件。 在项目根目录中运行：

    bash
    openspec update

    这将为所有已配置的工具重写 skill 和 command 文件。

    指令文件来自 已安装的 CLI，因此过时的 CLI 会报告一切正常，而不会写入更新的 workflow。openspec update 现在会检查这一点并提供升级选项——如果看到提示，请接受升级。

  3. 重启你的助手。 大多数工具在启动时扫描 skill 和 command。打开一个新窗口通常就能解决问题。

  4. 确认文件存在。 对于 Claude Code，检查 .claude/skills/ 是否包含 openspec-* 文件夹。其他工具使用各自的目录，全部列在 支持的工具 中。

  5. 确认已在此项目中初始化。 Skill 是按项目写入的。如果你克隆了仓库或切换了文件夹，请在那里运行 openspec init（或 openspec update）。

  6. 确认你的工具支持 command 文件。 Codex、CodeArts、ForgeCode、Hermes、Kimi Code、Mistral Vibe、Zed Agent 以及共享的 .agents 目标不会生成 opsx-* command 文件；它们使用基于 skill 的调用方式，因此 /opsx 永远不会为它们自动补全。在 Codex 中输入 $openspec-propose，在 Kimi Code 中输入 /skill:openspec-propose，在其余工具中输入 /openspec-propose。共享的 .agents 目标是厂商中立的，因此 /openspec-propose 是通用形式而非保证形式——如果你的助手不响应它，请查阅其文档了解如何调用 skill。Amazon Q 会生成 command 文件，但会将其加载到提示库而非斜杠菜单中——在那里输入 @opsx-propose，而不是 /opsx。每个工具的调用形式均列在 如何调用 中。

处理变更 ​

"Change not found" ​

命令无法确定你指的是哪个变更。请明确指定名称，或检查现有变更：

bash
openspec list                    # 查看活跃变更
/opsx:apply add-dark-mode        # 在聊天中指定变更名称

同时确认你在正确的项目目录中。

"No artifacts ready" ​

每个 artifact 要么已经创建，要么因等待依赖而被阻塞。查看是什么在阻塞：

bash
openspec status --change <name>

然后先创建缺失的依赖。请记住顺序：proposal 启用 specs 和 design；specs 和 design 共同启用 tasks。

openspec validate 报告警告或错误 ​

验证会检查你的 specs 和变更是否存在结构性问题。请阅读提示信息：它会指出文件名和具体问题。

bash
openspec validate <name>           # 验证单个项目
openspec validate --all            # 验证所有项目
openspec validate --all --strict   # 更严格的检查，适合 CI
openspec validate --archived       # 如果已归档的变更有未完成任务则失败

常见原因包括缺少必需的部分（如没有场景的 spec）或格式错误的 delta 标题。修复文件后重新运行。CLI 参考 记录了输出格式。

有一条消息值得特别说明：

text
MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

MODIFIED 需求会替换整个需求块，因此它必须包含变更中保留的所有场景，而不仅仅是你编辑的那些。请将 openspec/specs/<capability-path>/spec.md 中指定的场景复制回 delta 中，保留路径中的任何领域目录。这种情况通常出现在较旧的变更上——当其他人的变更向同一需求添加了场景后，归档会拒绝该变更，而验证现在会在你实施之前就指出这一点。

AI 创建了不完整或错误的 artifact ​

AI 没有足够的上下文。以下几个方法有帮助：

  • 在 openspec/config.yaml 中添加项目上下文，以便你的技术栈和约定被注入到每个请求中。参见 自定义。
  • 为每个 artifact 添加 rules:，提供仅适用于特定类型（如 specs）的指导。
  • 在提出变更时提供更详细的描述。
  • 使用扩展的 /opsx:continue 逐个创建 artifact 并逐一审查，而不是用 /opsx:ff 一次性全部完成。

归档无法完成，或警告有未完成任务 ​

归档不会因未完成任务而 阻塞，但会发出警告，因为归档通常意味着工作已完成。如果任务是有意保留的（你在提交部分变更），可以继续。否则请先完成任务。归档还会在你尚未同步时提供将 delta specs 同步到主 specs 的选项；除非有理由不同步，否则请同意。

"User force closed the prompt with 0 null" ​

某处运行了 openspec archive，但没有任何东西能回答问题——AI agent 从工具中调用它、CI 作业，或任何 stdin 已关闭的 shell。归档会要求最多三次确认，而一个无法回答的确认过去会以该原始消息失败。

使用 --yes 提前回答：

bash
openspec archive <change-name> --yes

保留你之前传递的所有标志——--skip-specs 和 --no-validate 会改变归档的行为，因此仅加 --yes 重新运行并不等同于原命令。当前版本会为你指定标志名称并打印一行 Fix: 供你粘贴。如果你本来想从列表中选择，请显式传递变更名称：选择器也需要一个答案。

如果你将归档输出重定向到文件或由工具捕获，并且 确实 通过管道传入了答案（printf 'y\n' | openspec archive …），旧版本在绘制提示时会向该捕获内容写入终端转义码——在某些环境中足以严重膨胀文件。当前版本在 stdout 不是终端时将确认提示作为纯文本读取，且无参数的 openspec archive（否则会绘制交互式变更选择器）会要求你提前传递变更名称，而不是将菜单渲染到捕获内容中。无论如何，重定向和 agent 运行都能保持干净；传递 --yes（附带变更名称）可完全跳过提示。

配置 ​

我的 config.yaml 未生效 ​

三个常见原因：

  1. 文件名错误。 必须是 openspec/config.yaml，而不是 .yml。
  2. YAML 格式无效。 使用任何 YAML 验证器检查；CLI 也会报告带行号的语法错误。
  3. 你以为需要重启。 不需要。配置更改立即生效。

"Unknown artifact ID in rules: X" ​

rules: 下的某个键与 schema 中的任何 artifact 都不匹配。对于默认的 spec-driven schema，有效的 ID 为 proposal、specs、design、tasks。要查看任何 schema 的 ID：

bash
openspec schemas --json

"Context too large" ​

context: 字段有意限制在 50KB，因为它会被注入到每个请求中。请对其进行摘要，或链接到更长的文档而不是直接粘贴。精简的上下文也能产生更好、更快的结果。

"Schema not found" ​

你引用的 schema 名称不存在。列出可用的 schema 并检查拼写：

bash
openspec schemas                    # 列出可用 schema
openspec schema which <name>        # 查看 schema 的解析来源
openspec schema init <name>         # 创建自定义 schema

参见 自定义。

从旧版工作流迁移 ​

"Legacy files detected in non-interactive mode" ​

你处于 CI 或非交互 shell 中，OpenSpec 发现了需要清理的旧文件但无法提示你。请自动批准：

bash
openspec init --force

对于 Codex，OpenSpec 可能会在 $CODEX_HOME/prompts 或 ~/.codex/prompts 中检测到旧的托管提示文件。该清理仅限于 OpenSpec 白名单中的旧版 Codex 提示文件名，且非交互式的 openspec init 仅删除其替代 .agents/skills/openspec-* skill 已存在的文件。非交互式的 openspec update 不会触碰任何旧版清理，除非你传递 --force。

迁移后命令未出现 ​

重启你的 IDE。Skill 在启动时检测。如果仍未出现，请运行 openspec update 并检查 支持的工具 中的文件位置。

我的旧 project.md 未被迁移 ​

这是有意为之。OpenSpec 不会自动删除 project.md，因为它可能包含你编写的上下文。请将有用部分移至 config.yaml 的 context: 部分，然后自行删除。迁移指南 详细介绍了此过程，包括一个你可以交给 AI 进行提炼的提示。

仍然卡住了？ ​

报告问题时，请包含你的 OpenSpec 版本（openspec --version）、Node 版本（node --version）、AI 工具，以及确切的命令和输出。这能大大加快帮助速度。