holaOS 本機安裝實作：一行指令裝完，或照官方五步自己來（2026-09 實查）

holaOS 是本機優先的代理工作區，可以讓 Claude Code、Codex 與它自己的代理共用同一份記憶與工具。這篇把官方 README 的安裝段落整理成可以照做的流程，查核日 2026-09-07。

一、先決定走哪一條路

官方 README 列了三種使用方式：

如果你只是想用，下載桌面應用就好，不必看下面。 以下是自架路線。

二、最快的路：一行安裝

官方提供的全新機器啟動指令（支援 macOS、Linux、WSL）：

curl -fsSL https://raw.githubusercontent.com/holaboss-ai/holaOS/refs/heads/main/scripts/install.sh | bash -s -- --launch

動手前的提醒：這是「把遠端腳本直接餵給 shell 執行」的寫法，方便但代表你完全信任該來源。謹慎的做法是先把 install.sh 下載下來讀一遍再執行——尤其這支腳本會安裝 Node、複製 repo、建立環境檔。這是通則，不是針對 holaOS。

--launch 參數代表裝完直接啟動；不加就只完成安裝。

三、手動安裝：官方的五個步驟

README 明說「你多半不需要這一段，因為一行安裝跑的是同一套設定」，手動路線適合想逐步檢查的人。

先確認前置條件：

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

repo 在根目錄用 .nvmrc 釘住 Node 版本；如果你已經在用 nvm，在 repo 根目錄跑 nvm use 就會自動採用。nvm 是選用的，不是必要條件。

然後五步：

1. 從 repo 根目錄安裝桌面端相依套件：

   npm run desktop:install
   

2. 建立你的本機環境檔：

   cp apps/desktop/.env.example apps/desktop/.env
   

   正式路徑是 apps/desktop/.env。 README 特別註明：舊版的 desktop/.env 目前仍被接受，但新安裝請一律用 apps/desktop/.env。這是最容易踩錯的一步——照舊教學走會放錯位置。
3. 準備本機執行期套件：

   npm run desktop:prepare-runtime:local
   

4. （選用）啟動前先做一次型別檢查驗證：

   npm run desktop:typecheck
   

5. 以開發模式啟動桌面應用：

   npm run desktop:dev
   

   官方說明 predev 掛勾會自動驗證環境、重建原生模組，並確認已有暫存的執行期套件。

四、兩種 runtime 準備方式，用途不同

README 列了兩條，很多人會搞混：

• npm run desktop:prepare-runtime:local — 從本機程式碼建置。當你正在修改 runtime 程式碼時用這個。
• npm run desktop:prepare-runtime — 抓取最新的已發布 runtime。當你想拿一個已知的正式版本來驗證桌面端時用這個。

簡單記：自己改東西用 local，要對照官方版本用另一個。

五、把安裝交給你的 AI 代理跑

這是 README 裡很實用的一段：如果你在用 Codex、Claude Code、Cursor、Windsurf 或其他編碼代理，官方直接給了一段可以整段貼過去的交辦指令，內容大意是：

執行 holaOS 的安裝腳本；缺 git 與 Node.js 24.14.1／npm 就先裝；把 repo 複製或更新到 ~/holaboss-ai（除非我另外指定 --dir）；跑 desktop:install；必要時由 apps/desktop/.env.example 建立 apps/desktop/.env；跑 desktop:prepare-runtime:local 與 desktop:typecheck；只有在我加上 --launch 時才跑 desktop:dev。如果 Electron 開不起來，停在驗證步驟並告訴我下一個手動步驟。

這段交辦寫得比多數專案好，值得學起來的兩個地方：明確指定 Node 版本號，以及明確規定失敗時要停下來回報，而不是自己亂試。

詳細的啟動流程官方放在 repo 內的 INSTALL.md runbook。

六、授權：這一段一定要自己看

README 的 OSS Release Notes 寫得很清楚：

License: modified Apache 2.0 with additional commercial-distribution and branding conditions.

也就是修改版 Apache 2.0，附帶額外的商業散布與品牌條件。這解釋了為什麼 GitHub API 的授權欄位回傳 NOASSERTION——它不是標準授權，自動偵測認不出來。

實務上的意思是：個人自架幾乎不會有問題，但如果你打算包進商業產品、對外散布、或用它的品牌，請先逐條讀過 LICENSE 檔案。 不要因為看到「Apache 2.0」幾個字就當作標準 Apache 授權。

另外，安全性問題官方要求私下回報到 admin@holaboss.ai，不要開公開 issue。

七、裝完之後先做的事

依 README 描述的架構，第一次啟動建議按這個順序摸：

1. 先接一個整合（Gmail、Notion、Slack、GitHub 或 Linear 都是一鍵 OAuth），確認核准流程是你能接受的——每個動作都要你同意。
2. 打開記憶資料夾看一眼。記憶是本機的純文字檔，能讀能改，這是它跟其他代理最大的差別。
3. 再決定要不要接第二個代理。共用記憶的價值要有兩個代理才看得出來。

想先了解這個專案的背景與數據，見 holaOS 半年衝到 1.1 萬顆星是什麼來頭。

本文依據 holaOS 官方 README 於 2026-09-07 直讀整理，所有指令均為官方文件原文。安裝細節可能隨版本變動，請以 repo 內的 INSTALL.md 為準；授權條款請自行閱讀 LICENSE 檔案。相關代理工具方案價格見 Claude 工具頁。