安裝指南

HagiCode 提供三種安裝方式。先依使用情境選一條路徑，再確認這條路徑需要的前置條件，最後進入對應的安裝頁。

選擇安裝方式

你的情境	建議方式
Windows 個人本機使用	Microsoft Store 安裝
macOS / Linux 個人本機使用，或 Windows 無法使用商店	Desktop 安裝
伺服器、NAS、團隊共用，或需要環境隔離	Docker Compose 安裝

Microsoft Store 安裝Windows 預設建議的入口，透過官方商店完成安裝與後續更新。

Desktop 安裝圖形化安裝與管理流程。適合 macOS / Linux，以及需要手動下載安裝套件的 Windows 使用者。

Docker Compose 安裝適合需要環境隔離、統一部署或團隊協作的情境。

安裝前準備

不同路徑需要的前置條件不同：

安裝方式	Node.js	Git
Microsoft Store / Desktop	需自行安裝 24 或更高版本	需自行安裝
Docker Compose	主機無需安裝	主機無需安裝

Desktop 不再內建 Node.js

Desktop 只內建執行 HagiCode Server 所需的 .NET 執行階段，不再提供 Node.js。它會在系統 PATH 中尋找 node 與 npm，並把 Agent CLI 等託管套件安裝到你本機 npm 的全域目錄。請在首次啟動 Desktop 之前先裝好 Node.js 24 或更高版本，詳見 安裝 Node.js。

安裝 Git

Desktop 會在啟動時偵測 node、npm 與 git，主介面「新建項目」對話框裡的「示範項目」也需要透過 Git 克隆官方範例儲存庫。請依你的系統選擇一種方式安裝：

• Windows：執行 winget install --id Git.Git -e，或從 git-scm.com 下載安裝程式。
• macOS：執行 xcode-select --install，或使用 Homebrew 執行 brew install git。
• Debian / Ubuntu：執行 sudo apt-get install -y git。
• Fedora：執行 sudo dnf install -y git。

安裝完成後重新開啟終端機，確認指令可用：

node --version
npm --version
git --version

裝好之後再啟動 Desktop

Desktop 在啟動時讀取系統 PATH。如果你是在 Desktop 已經開啟的情況下才安裝 Node.js 或 Git，請完全結束並重新啟動 Desktop。

Agent CLI

HagiCode 透過本機已安裝並完成登入的 Agent CLI 運作。初始化嚮導只會列出本機已偵測到的 CLI，所以請在進入嚮導之前至少裝好並登入一個。目前支援的 CLI、安裝方式與官方入口，統一維護在 AI Agent CLI 安裝。

相關軟體安裝

安裝 Node.js準備 Node.js 24+ 與 npm，Desktop 與大多數 Agent CLI 都依賴它。

OpenSpec 介紹前往 OpenSpec 獨立文件站，了解安裝方式、核心概念與規範驅動工作流程。

安裝 AI Agent CLI查看目前支援的 Agent CLI，區分一鍵安裝與手動安裝 / 驗證。

下一步

1. 依上表選擇安裝方式，並先完成前置條件。
2. 完成安裝並首次啟動，隨後依 初始化嚮導設定 建立預設 Hagicoder 與第一個專案。
3. 想了解 OpenSpec 提案流程，可閱讀 OpenSpec 介紹 與 建立提案會話。