故障排除

針對具體問題的具體修復方案。每個條目都列出了症狀、用一句話解釋可能的原因，並提供修復方法。如果在這裡找不到您的問題，常見問題解答 可能會有所幫助，而 Discord 肯定能幫上忙。

安裝與設定

openspec: command not found

CLI 未安裝，或者您的 Shell 無法找到它。請全域安裝並檢查：

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 輔助安裝，這是預期的交接點：該提示會指示您的 AI 助手顯示 PATH 變更，而不是自行編輯您的 Shell 啟動檔案。

"Requires Node.js 20.19.0 or higher"

OpenSpec 需要 Node 20.19.0 或更高版本。請檢查您的版本並在需要時升級：

node --version

如果您使用 bun 來安裝 OpenSpec，請注意 OpenSpec 仍然 運行 在 Node 上，因此無論如何都需要在您的 PATH 中可用 Node 20.19.0+。請參閱 安裝。

openspec init 未配置我的 AI 工具

Init 會詢問要設定哪些工具。如果您跳過了您的工具或想新增其他工具，只需再次執行它，或使用非互動式形式：

openspec init --tools claude,cursor

完整的工具 ID 列表見 支援的工具。使用 --tools all 進行所有設定，使用 --tools none 跳過工具設定。

命令未顯示

如果 /opsx:propose（或您工具的等效命令）未出現或無反應，請按以下順序逐一排查。這些步驟按檢查速度從快到慢排列。

1. 您可能處於錯誤的位置。 斜線命令應在您的 AI 助手聊天視窗中使用，而非終端機中。如果您將 /opsx:propose 輸入到 Shell 中，這就是問題所在。請參閱 命令運作方式。

2. 重新生成檔案。 從專案根目錄執行：

   openspec update

   這會為每個已配置的工具重寫技能（skill）和命令檔案。

   指令檔案來自於 已安裝 的 CLI，因此過時的 CLI 會報告一切最新，而不會寫入較新的工作流程。openspec update 現在會檢查此情況並提供升級選項——如果您看到該選項，請接受。

3. 重新啟動您的助手。 大多數工具在啟動時掃描技能和命令。一個新的視窗通常就能解決問題。

4. 確認檔案存在。 對於 Claude Code，請檢查 .claude/skills/ 是否包含 openspec-* 資料夾。其他工具使用各自的資料夾，全部列於 支援的工具 中。

5. 確認您已初始化此專案。 技能是針對每個專案撰寫的。如果您克隆了倉庫或切換了資料夾，請在該處執行 openspec init（或 openspec update）。

6. 確認您的工具支援命令檔案。 Codex、CodeArts、ForgeCode、Hermes、Kimi Code、Mistral Vibe、Zed Agent 以及共享的 .agents 目標不會生成 opsx-* 命令檔案；它們改用基於技能的調用，因此 /opsx 對它們永遠不會自動完成。在 Codex 中鍵入 $openspec-propose，在 Kimi Code 中鍵入 /skill:openspec-propose，在其他工具中鍵入 /openspec-propose。共享的 .agents 目標是供應商中立的，因此 /openspec-propose 是通用形式而非保證形式——如果您的助手不響應它，請查閱其文件以了解如何調用技能。Amazon Q 確實會獲得命令檔案，但它們被載入到其提示庫（prompt library）而非斜線選單中——在那裡鍵入 @opsx-propose，而非 /opsx。每個工具的表單均列於 如何調用 中。

處理變更

"Change not found"

命令無法判斷您指的是哪個變更。請明確命名它，或檢查現有的內容：

openspec list                    # 查看活躍變更
/opsx:apply add-dark-mode        # 在聊天中命名變更

同時確認您處於正確的專案目錄中。

"No artifacts ready"

每個工件（artifact）要么已經創建，要么因等待依賴項而被阻塞。查看是什麼在阻擋：

openspec status --change <name>

然後先創建缺失的依賴項。記住順序：提案啟用規格書和設計；規格書和設計共同啟用任務。

openspec validate 報告警告或錯誤

驗證會檢查您的規格書和變更是否存在結構問題。請閱讀訊息：它會指出檔案和問題所在。

openspec validate <name>           # 驗證單一項目
openspec validate --all            # 驗證所有內容
openspec validate --all --strict   # 更嚴格的檢查，適合 CI
openspec validate --archived       # 如果歸檔的變更有未檢查的任務則失敗

常見原因包括缺少必填區段（例如沒有場景的規格書）或格式錯誤的 delta 標頭。修復檔案後重新執行。CLI 參考 記錄了輸出格式。

有一條訊息值得單獨說明：

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

MODIFIED 要求會替換整個要求區塊，因此它必須攜帶變更後保留的所有場景，而不僅是您編輯過的場景。請將 openspec/specs/<capability-path>/spec.md 中的指定場景複製回 delta 中，並保留路徑中的任何領域目錄。這通常出現在舊變更中，當其他人的變更向同一個要求添加了場景時——無論如何，歸檔都會拒絕該變更，而驗證會在您實施之前告知這一點。

AI 創建了不完整或錯誤的工件

AI 缺乏足夠的上下文。以下幾個調整有助於改善：

• 在 openspec/config.yaml 中添加專案上下文，以便將您的技術堆疊和慣例注入到每個請求中。請參閱 自訂。
• 為每個工件添加 rules: 以提供僅適用於特定類型（例如規格書）的指導。
• 在提出變更時提供更詳細的描述。
• 使用擴充的 /opsx:continue 一次創建一個工件並審查每個工件，而不是使用 /opsx:ff 一次性完成所有操作。

歸檔無法完成，或警告有不完整的任務

歸檔不會 阻塞 在不完整任務上，但它會發出警告，因為歸檔通常意味著工作已完成。如果任務是有意留存的（例如您正在提交部分變更），請繼續執行。否則，請先完成任務。如果您尚未同步，歸檔還將提供將您的 delta 規格書同步到主規格書的選項；除非有理由不這樣做，否則請同意。

"User force closed the prompt with 0 null"

某處執行了 openspec archive，但沒有任何東西可以回答問題——例如 AI 代理從工具中調用它、CI 作業，或任何 stdin 關閉的 Shell。歸檔最多會詢問三次確認，而無法回答的問題過去會以該原始訊息失敗。

傳遞 --yes 以提前回答：

openspec archive <change-name> --yes

保留您原本傳遞的任何標誌——--skip-specs 和 --no-validate 會改變歸檔的行為，因此單純的 --yes 重新執行並非相同的命令。當前版本會為您命名該標誌，並列印一行您可以貼上的 Fix: 行。如果您打算從列表中選擇，請明確傳遞變更名稱：選擇器也需要一個答案。

如果您改為將歸檔的輸出重定向到檔案或由工具捕獲，並且 確實 管道傳遞了一個答案（printf 'y\n' | openspec archive …），舊版本在繪製提示時會將終端機轉義碼寫入該捕獲內容中——在某些環境中足以嚴重膨脹檔案大小。當前版本在 stdout 不是終端機時會將確認提示讀取為純文字，而無需參數的 openspec archive（否則會繪製互動式變更選擇器）會要求您提前傳遞變更名稱，而不是將選單渲染到捕獲內容中。無論哪種方式，重定向和代理執行保持乾淨；傳遞 --yes（帶有變更名稱）會完全跳過提示。

配置

我的 config.yaml 未被應用

三個常見的嫌疑對象：

1. 檔名錯誤。 它必須是 openspec/config.yaml，而非 .yml。
2. YAML 無效。 通過任何 YAML 驗證器運行它；CLI 也會報告帶行號的語法錯誤。
3. 您預期需要重新啟動。 您不需要。配置更改立即生效。

"Unknown artifact ID in rules: X"

rules: 下的金鑰與模式中的任何工件都不匹配。對於默認的 spec-driven 模式，有效的 ID 為 proposal、specs、design、tasks。要查看任何模式的 ID：

openspec schemas --json

"Context too large"

context: 欄位限制為 50KB，這是出於故意設計的，因為它會被注入到每個請求中。請總結它，或鏈接到更長的文檔，而不是粘貼它們。精簡的上下文也能產生更好、更快的結果。

"Schema not found"

您引用的模式名稱不存在。列出可用的內容並檢查拼寫：

openspec schemas                    # 列出可用模式
openspec schema which <name>        # 查看模式解析來源
openspec schema init <name>         # 創建自訂模式

請參閱 自訂。

從舊工作流程遷移

"Legacy files detected in non-interactive mode"

您處於 CI 或非互動式 Shell 中，OpenSpec 發現了需要清理的舊檔案，但無法提示您。請自動批准：

openspec init --force

對於 Codex，OpenSpec 可能會檢測到 $CODEX_HOME/prompts 或 ~/.codex/prompts 中的舊受管理提示檔案。該清理僅限於 OpenSpec 允許清單中的舊版 Codex 提示檔名，且非互動式 openspec init 僅移除那些存在對應替換 .agents/skills/openspec-* 技能的檔案。非互動式 openspec update 會保留所有舊版清理 untouched，除非您傳遞 --force。

遷移後命令未出現

重新啟動您的 IDE。技能在啟動時被檢測。如果它們仍未出現，請執行 openspec update 並檢查 支援的工具 中的檔案位置。

我的舊 project.md 未遷移

這是故意的。OpenSpec 不會自動刪除 project.md，因為它可能包含您編寫的上下文。將有用的部分移動到 config.yaml 的 context: 區段中，然後自行刪除它。遷移指南 逐步介紹了此過程，包括一個您可以交給 AI 進行提煉的提示。

仍卡住？

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• 從您的終端機： openspec feedback "what went wrong" 會為您開啟一個 Issue。

當您報告問題時，請包含您的 OpenSpec 版本（openspec --version）、Node 版本（node --version）、您的 AI 工具，以及確切的命令和輸出。這會讓協助更快。