初始化嚮導設定

無論透過 Microsoft Store、Desktop 還是 Docker Compose 安裝，首次開啟 HagiCode 的 Web 介面時都會進入 初始化嚮導。完成它之後，您會擁有一個可用的預設 Hagicoder 和至少一個專案，可以直接開始第一次會話。

它與 Desktop 的首次使用引導不同

Desktop 首次啟動時的「首次使用引導」（選擇語言、確認法律文件、下載 Hagicode Server）發生在 Web 介面出現之前，見 Desktop 安裝。本頁說明的是之後在 Web 介面裡出現的初始化嚮導。

開始之前

請先確認：

已安裝並登入至少一個 Agent CLI。嚮導只會列出執行 Hagicode Server 的這台機器上已偵測到的 CLI，沒有偵測到時無法繼續建立 Hagicoder。支援的 CLI 與安裝方式見 AI Agent CLI 安裝。
Desktop / Store 使用者：已依安裝指南安裝 Node.js 24+ 與 Git。
Docker 使用者：已在 Docker Compose Builder 中設定好 API 供應商與 Token。
準備好一個要接入的本機儲存庫或工作目錄：步驟 3 會讓您登記它。

嚮導總覽

嚮導由 4 個步驟組成，左側導覽會顯示目前進度：

步驟	目標	完成標誌
1. 基礎設定	選擇介面語言與主題	點擊「下一步：設定 Hagicoder」
2. 設定 Hagicoder	選擇 CLI 與模型，建立預設 Hagicoder	點擊「確認並建立 Hagicoder」，或已有可用的 Agent
3. 建立專案	至少建立一個專案	專案步驟顯示「已完成」
4. 社群導覽	了解社群入口	點擊「開始使用 HagiCode」

步驟 1：基礎設定

目標：確定介面語言和主題。

在「選擇介面語言」中選一種語言。這只會切換介面文字，不會改變 Hagicoder 的語言風格。
在「選擇主題」中選一套主題。目前提供「春季亮色」和「春季暗色」。
點擊「下一步：設定 Hagicoder」。

步驟 2：設定 Hagicoder

目標：建立預設 Agent，名字固定為 Hagicoder。

如果系統已經存在 Agent，這一步會提示「已偵測到現有 Agents」，直接沿用現有編組即可。否則：

選擇您最常用的 AgentCLI：下拉清單只顯示本機已偵測到的 CLI。如果提示沒有偵測到可用的 CLI，請先依 AI Agent CLI 安裝完成安裝與登入，再回來重新整理。
選擇您最常用的模型：
- 選擇現有模板：重複使用該 CLI 下已有的模型模板，可依名稱或模型 ID 搜尋。
- 輸入自訂模型：手動輸入模型名稱，例如 gpt-5.5、glm-5.1、claude-opus-4-7，建立時會自動重複使用或新建對應模板。
（選用）點擊「測試可用性」：向所選 CLI 與模型送出一次 ping-pong 驗證，確認模型能回傳 pong。測試結果只對目前的 CLI 與模型組合有效，修改後需要重新測試；建立 Hagicoder 並不要求測試通過。
（選用）點擊「換一組」 更換預設形象，頭像會從圖庫隨機抽取。
點擊「確認並建立 Hagicoder」。建立成功後，它會被加入應急隊，所選 CLI 與模型會寫入它的預設設定。

支援哪些 CLI

嚮導裡能選的 CLI 取決於本機已安裝並被偵測到的 Agent CLI，不限於某一種。完整的支援範圍與安裝方式以 AI Agent CLI 安裝為準；其中 Hermes、Gemini、DeepAgents 需要先完成手動安裝或驗證。

常見問題

清單裡沒有我的 CLI：確認它已安裝並在執行 Hagicode Server 的環境中可用；Desktop 使用者請重新啟動 Desktop 以重新整理 PATH。
可用性測試失敗：常見原因包括 CLI 尚未登入、權杖無效，或模型名稱不被該 CLI 支援。請先在終端機裡用該 CLI 跑一次最小對話，確認它本身可用。
加入應急隊失敗：頁面會提供「重試加入應急隊」，重試即可。

步驟 3：建立專案

目標：至少登記一個專案，讓後續會話有可讀的工作目錄。嚮導會先偵測是否已經有本機專案：已有時顯示目前專案摘要，沒有時需要先登記一個。

在「登記一個本地項目」中填寫專案名稱、資料夾路徑，以及選填的專案描述。欄位與路徑驗證和主介面的「新建項目」對話方塊完全一致。
點擊「創建並繼續」進入下一步；如果想留在本步驟繼續新增，點擊「僅建立項目」。
已經有專案時，可以直接點擊「繼續進入社區」，也可以「再創建一個項目」，或返回基礎設定。

想先用範例專案體驗？

嚮導裡只提供登記本機專案。「示範項目」位於主介面「新建項目」對話方塊的「示範項目」頁籤：它會自動克隆並註冊官方 MonoSpecs Demo 儲存庫，預設路徑為 data/repos/monospecs-demo，實際目錄以執行階段的資料目錄（DataDir）設定為準。此方式需要 Git，並且能連線到 GitHub。

常見問題