安裝

在您的機器上安裝 openspec CLI,以及更新與解除安裝它的方法。

安裝

在 macOS 或 Linux 上，於您的終端機中執行：

curl -fsSL https://openspec.dev/cli/install.sh | sh

在 Windows 上，於 PowerShell 中執行：

irm https://openspec.dev/cli/install.ps1 | iex

如果安裝程式印出 export PATH=... 這一行，請執行它。然後確認安裝是否成功。

透過您的 AI 助理安裝

將以下內容貼到您的 AI 聊天中：

Fetch https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md and follow it.

或者，在您的終端機中，將它以管線方式傳給 CLI 代理(以下以 Claude Code 為例)：

curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md | claude

這會擷取儲存庫根目錄下的 install.md,這是一份為任何能執行 shell 命令的代理撰寫的提示(少數 IDE 整合無法執行)。您可以預期您的助理會：

1. 如果 CLI 已存在於您的機器上，則跳過安裝，並提議以原本的安裝方式來更新它。如果原本是透過 npm 或 Homebrew 安裝，會提一次 openspec install 可切換至獨立安裝，但不會強力推銷。否則，會向您顯示上述的安裝命令，並在執行前等待您的確認。
2. 只有在您要求或安裝程式失敗時才改用 npm,並在您的 Node 版本低於 22.12.0 時停止。
3. 驗證 openspec 是否位於您的 PATH 中。
4. 說出它認為您所指的資料夾名稱，建議您目前正在對話的 AI 工具，並詢問您還使用哪些其他工具，然後在該處執行 openspec init(即專案設定步驟)。
5. 回報 init 建立了哪些內容，以及在您的工具中叫用 OpenSpec 的確切拼寫方式。

它會在任何需要特殊權限的動作前停下來，並且絕不編輯您的 shell 啟動檔案。上述的安裝命令與下方的套件管理器才是最終依據，提示只是代您執行這些命令。

這種安裝方法還很新，結果可能因所使用的模型而異。只有在您能夠自在地修正 AI 的錯誤時才使用此方法，否則建議遵循下方的標準方法。

套件管理器

這些方法會將 OpenSpec 作為 Node.js 套件安裝，因此需要 Node.js 22.12.0 或更新版本(Homebrew 和 Nix 會自帶 Node.js)。在您的終端機中：

node --version

如果輸出為 v22.12.0 或更高版本，請使用 npm 安裝：

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

如果不是，請從 nodejs.org 安裝較新的 Node,或透過您的版本管理器(nvm、fnm、asdf、volta)安裝，或者改用獨立安裝。

Homebrew

Homebrew 會在 macOS 或 Linux 上安裝 OpenSpec 及其 Node.js 相依性。在您的終端機中：

brew install openspec

此 formula 已發布於 homebrew-core,因此您不需要新增 tap。

Yarn

yarn global add 僅適用於 Yarn Classic(1.x)。新版 Yarn 已移除全域安裝功能，因此請改用 npm、pnpm 或 bun。全域 CLI 不必與您專案所用的套件管理器相同。

Bun

Bun 會安裝 OpenSpec 但不會執行它，因此您的機器上仍需要 Node(請參閱套件管理器)。若沒有 Node,每個命令都會失敗並顯示 env: node: No such file or directory。Bun 對所有 Node CLI 都是這樣處理的。

Deno

Deno 會從 npm 安裝 CLI,並需要明確指定權限旗標。在您的終端機中：

deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@latest

有些命令會啟動另一個程式,例如 openspec config edit 會開啟您的編輯器。Deno 每次執行時都會以權限提示中斷這類命令。若要讓它不再詢問，請在安裝命令中加入限定範圍的 --allow-run=<program>。

NOTE

如果 Deno 無法解析 @latest,請改為固定版本範圍:npm:@fission-ai/openspec@^1.7.0。

Nix

OpenSpec 儲存庫附有 Nix flake。請將其安裝到您的 profile 中。在您的終端機中：

nix profile install github:Fission-AI/OpenSpec

或者先執行一次性命令，而不安裝：

nix run github:Fission-AI/OpenSpec -- --version

這不會在您的 PATH 中留下任何東西，因此事後沒有安裝需要確認。

若要改為將 OpenSpec 放入專案的開發 shell,請將該 flake 新增為 input 並使用其預設套件;flake.nix 列出了各項輸出。

Nix 套件在標準位置(share/bash-completion/completions、share/fish/vendor_completions.d、 share/zsh/site-functions)附帶 Bash、Fish 和 Zsh 的自動補全腳本,因此它們會隨套件一併載入，無需執行 openspec completion install。

確認安裝是否成功

無論您使用哪種方法，請在您的終端機中執行：

openspec --version

如果輸出版本號碼，表示 CLI 已位於您的 PATH 中。每台機器只需安裝一次。

接著,設定您的專案。如果您的助理已經執行過 init,該頁面會說明它寫入了哪些內容，以及如何調整。

安裝選項

若要指定版本或資料夾，請在 sh 之前設定變數：

curl -fsSL https://openspec.dev/cli/install.sh | OPENSPEC_VERSION=v1.15.0 sh

• OPENSPEC_VERSION:要安裝的版本，例如 v1.15.0。預設為最新發布的版本。
• OPENSPEC_INSTALL_DIR:安裝目標資料夾。預設為 ~/.local/bin(Windows 為 %LOCALAPPDATA%\Programs\openspec)。

在 Windows 上，請先設定變數：

$env:OPENSPEC_VERSION = 'v1.15.0'
irm https://openspec.dev/cli/install.ps1 | iex

在 Alpine Linux 上，請在安裝前執行 apk add libstdc++ libgcc。

手動下載

每個版本發布都會為每種電腦提供一個檔案：

電腦	檔案
Mac(Apple 晶片)	openspec-darwin-arm64.tar.gz
Mac(Intel)	openspec-darwin-x64.tar.gz
Linux(arm64)	openspec-linux-arm64.tar.gz
Linux(x64)	openspec-linux-x64.tar.gz
Alpine(arm64)	openspec-linux-arm64-musl.tar.gz
Alpine(x64)	openspec-linux-x64-musl.tar.gz
Windows(arm64)	openspec-windows-arm64.zip
Windows(x64)	openspec-windows-x64.zip

1. 從最新版本發布下載您的檔案。檔案會在版本發布後幾分鐘內附加。如果您的檔案尚未列出，請稍候並重新整理，或改從上一個版本發布取得。
2. 解壓縮該檔案。在您的終端機中:tar -xzf openspec-darwin-arm64.tar.gz。在 Windows 上，以滑鼠右鍵按一下 .zip 檔案，然後選擇「全部解壓縮」。
3. 在 macOS 上,在您解壓縮後的資料夾中執行 xattr -d com.apple.quarantine openspec。macOS 會封鎖透過瀏覽器下載的檔案，直到您執行此操作為止。
4. 將 openspec 移動到 PATH 中的資料夾,例如 ~/.local/bin。在 Windows 上,將 openspec.exe 移動到使用者 PATH 中的資料夾,例如 %LOCALAPPDATA%\Programs\openspec。

驗證下載檔案

若要確認檔案確實是由 OpenSpec 的發布工作流程所建置，請使用 GitHub CLI 執行以下命令：

gh attestation verify openspec-darwin-arm64.tar.gz --repo Fission-AI/OpenSpec

如果檔案不是由該工作流程建置，此命令會失敗。安裝命令本身已會依據該版本發布的 SHA256SUMS 檢查每次下載，因此此步驟為選用。

從 npm 切換到獨立安裝

切換為選用；npm 仍可繼續運作。您的設定與專案都會沿用，只有程式本身會改變。

1. 安裝獨立副本。在您的終端機中：

openspec install

它會安裝獨立版的 openspec,並印出用來移除您 npm 或 Homebrew 副本的命令。

2. 移除舊副本。舊副本通常位於您 PATH 的較前面位置，因此在它被移除之前，系統仍會持續執行它。請執行步驟 1 所印出的命令，例如：

npm uninstall -g @fission-ai/openspec

3. 確認目前執行的是哪個副本。開啟新的終端機：

openspec version

它應該會印出 OpenSpec <version> (standalone)。如果它顯示的是套件管理器名稱，表示另一個副本仍在您的 PATH 中:which -a openspec(Windows 為 where.exe openspec)會列出所有副本，請移除其他副本。

不需要重新初始化任何專案。若要切換回去，請刪除該檔案，然後再次執行 npm 安裝命令。

更新

在您的終端機中，於每個您執行過 init 的專案裡執行：

openspec update

當有較新的 CLI 發布時,openspec update 會告知您,並可為您安裝;該升級在每台機器上只需執行一次。每次執行都會重新整理專案產生的 skills 與命令,這些內容從不會自行更新。已是最新狀態的專案會印出 ✓ All 2 tool(s) up to date (v1.7.0)。

WARNING

使用獨立安裝時，請執行 openspec install 原地取代您現有的副本;openspec update 會在有較新版本時告知您。在 Homebrew 上，請執行 brew upgrade openspec。在 Deno 上，請加上 -f 重新執行 Deno 安裝;若沒有 -f,它不會覆寫已安裝的命令。在 Nix 上，請使用 nix profile upgrade openspec。

NOTE

npm 全域安裝隸屬於單一 Node 安裝。使用 nvm 切換 Node 版本時，openspec 命令並不會跟著切換過去，因此請在新版本下重新安裝。

解除安裝

若要解除安裝 OpenSpec,請依序完成下列步驟；這些步驟都不會更動您的原始碼。您也可以將您的代理指向本節，讓它代為處理移除作業。

1. 移除 shell 自動補全(如果您有設定的話)，請趁 CLI 仍可運作時執行。在您的終端機中：

openspec completion uninstall

2. 移除 CLI。若是獨立安裝，請刪除 ~/.local/bin/openspec(Windows 為 %LOCALAPPDATA%\Programs\openspec,並將該資料夾從您的使用者 PATH 中移除)。若是 npm,請在您的終端機中執行：

npm uninstall -g @fission-ai/openspec

在 Homebrew 上：執行 brew uninstall openspec。在 Deno 上：執行 deno uninstall --global openspec。在 Nix 上：執行 nix profile remove openspec。您的 shell 應該不再能找到 openspec。

3. 刪除剩餘內容，或將其保留。

• 產生的代理檔案：每個專案中 .claude/ 或 .agents/ 等目錄下的 openspec-* skills 與 opsx 命令。支援的工具列出了各工具的路徑;MiniMax Code 將 skills 存放在 ~/.minimax/skills。
• 舊版本的殘留內容:CLAUDE.md 或 AGENTS.md 中的標記區塊(刪除區塊，保留檔案)，以及 ~/.codex/prompts 中的 opsx-*.md 提示檔。
• openspec/ 資料夾：請先暫停想想。specs/ 和 changes/archive/ 是您對這套系統的紀錄，是沒有 OpenSpec 也能順利閱讀的純 Markdown。
• 每台機器的狀態:~/.config/openspec/ 中的設定與遙測 ID;~/.local/share/openspec/ 中的 schema 覆寫、store 註冊資訊，以及獨立安裝的內建 schema(binary-schemas/)(Windows 為 %APPDATA%\openspec 與 %LOCALAPPDATA%\openspec)。註冊資訊只是指標；它們所指向的 store 儲存庫不會受到任何影響。