OpenClaude 怎麼裝到 Windows、macOS、Linux：npm 一條指令與 Node 版本陷阱

安裝前的三個前提：Node 版本、npm 是什麼、為什麼官方兩份文件打架

很多人第一次裝 OpenClaude，卡住的不是指令背錯，而是電腦裡根本沒有能跑它的環境。OpenClaude 是用 TypeScript（JavaScript 的加強版）寫的終端機工具，得靠 Node.js 才跑得起來。把 Node 與 npm 這兩件事搞清楚，大概就能解決八成的安裝失敗。

Node 是引擎，npm 是幫你把貨搬進門的人

Node.js（簡稱 Node）是讓 JavaScript 在電腦上直接執行的環境，可以想成引擎，OpenClaude 這台車要有引擎才跑得動。打開終端機輸入 node -v，有吐出號碼就代表裝好了；沒有的話，先去官方網站下載安裝檔。npm 是 Node 安裝時一起附上的套件管理器，負責把別人寫好的工具從網路抓下來、放到正確位置。

官方給的指令 npm install -g @gitlawb/openclaude@latest 一行看起來很輕巧，實際上做了三件事：連上 npm 套件庫下載最新版、解壓縮到全域目錄、登記成一個打 openclaude 就能執行的指令。當中的 -g 代表裝給整台電腦用，不是只裝在當前資料夾，這也是偶爾會跳出權限問題的原因。裝完輸入 openclaude --version 確認版本，是官方建議的第一步。另外有一個常被漏掉的工具叫 ripgrep（指令是 rg），它是用來快速搜尋檔案內容的，系統裡沒有就要另外裝，不然部分搜尋功能會直接罷工。

官方兩份文件版本打架，該聽誰的

2026-09-06 查核時，OpenClaude 的兩份官方文件對 Node 版本寫得不一樣：GitHub 上的 README 寫需要 Node 22 以上，官方安裝文件卻寫 Node 20 或更新。這種情況不罕見，通常是改版時只更新了其中一份。判斷原則很簡單，以 README 與專案實際宣告的引擎需求為準，因為那才是程式真正會檢查的門檻。用 Node 20 硬裝，常見結果是安裝階段跳出引擎不符的警告，或是裝完執行時冒出語法錯誤。

實務上，先把 Node 升到 22 以上再安裝，可以少掉一輪來回。如果你的電腦裡還有舊專案依賴 Node 18 或 20，請用版本管理工具切換，不要直接把系統的 Node 升掉，免得舊專案跟著壞。

三個系統照做：Windows、macOS、Linux 的安裝指令與卡點

OpenClaude 的安裝指令三個系統都一樣，這對非工程師是好消息。真正會卡住人的不是指令本身，而是三個周邊細節：誰有權限把套件裝進整台機器、環境變數在你的系統上要怎麼寫、以及電腦少了 ripgrep 這個搜尋工具時怎麼補。

一條指令走完三系統，裝完先驗證版本

安裝指令是這一行，三個系統都貼同一句：npm install -g @gitlawb/openclaude@latest。預期輸出會列出新增的套件行數，結尾不該出現紅字 ERROR。裝完馬上打 openclaude --version，正常會回報 0.30.0 這類版本號。如果終端機說找不到指令，通常是 npm 的全域執行路徑沒有進到系統的 PATH，重新開一個終端機視窗多半就會好，這是最常見的第一個坑。

Node 本身怎麼裝，三個系統差比較多：Windows 到官網下載安裝檔或用 winget；macOS 用 Homebrew，指令是 brew install node；Linux 建議用 nvm 裝在使用者家目錄底下，不要動到系統套件。裝 Node 的方式選對，後面的權限問題會少掉一半。

三個最常卡住的地方：權限、環境變數、缺 ripgrep

權限：不要用 sudo 硬裝。 macOS 與 Linux 執行全域安裝時，如果跳出 EACCES 權限錯誤，網路上的老答案會叫你在指令前面加 sudo。這樣做會把套件裝在 root 名下，之後每次更新都要再 sudo 一次，檔案擁有者也會變亂。正確做法是把 npm 的全域目錄改到自己家目錄（設定 npm prefix），或直接改用 nvm，從頭到尾都不需要管理員權限。

環境變數：Windows 的寫法跟另外兩家不一樣。想把模型指到本機的 Ollama，會用到 OpenAI 相容的位址。macOS 與 Linux 在終端機裡寫 export OPENAI_BASE_URL=http://localhost:11434/v1，但這個設定關掉視窗就消失，要長期生效得寫進 shell 的設定檔。Windows 的 PowerShell 用的是另一套語法：$env:OPENAI_BASE_URL="http://localhost:11434/v1"，同樣只生效當次，要永久保留得改用 setx。很多人卡在這裡不是打錯字，而是把 Linux 的 export 貼進了 PowerShell。另外要留神，OpenClaude 沿用了舊專案的環境變數名稱，例如 CLAUDE_CODE_USE_OPENAI。名字裡有 Claude 不代表你裝的是 Anthropic 官方工具，它是獨立社群專案，設定目錄預設放在 ~/.openclaude，不會去讀 Claude Code 的資料夾。

缺 ripgrep：讀程式碼會變慢或直接報錯。ripgrep（指令是 rg）是快速全文搜尋工具，OpenClaude 靠它掃整個專案的檔案。系統沒裝的時候，工具呼叫會失敗或改走慢速路徑。補法很單純：macOS 用 brew install ripgrep，Ubuntu 與 Debian 用 sudo apt install ripgrep，Windows 用 winget install BurntSushi.ripgrep.MSVC。裝完打 rg --version，有版本號就成功。三條路都通之後，進到專案資料夾打 openclaude 就會進入互動模式。

裝完先別下任務：驗證安裝、設定目錄放哪裡、doctor 怎麼用

安裝指令跑完、終端機沒噴紅字，很多人就急著丟一個「幫我重構整個專案」的大任務進去。這是新手最常踩的坑：程式裝好了，但環境其實少一個搜尋工具、Node 版本其實不夠、或你選的模型根本連不上。結果 agent 跑一半卡住，你以為是模型笨，其實是安裝沒驗完。這一章給你一套五分鐘能跑完的檢查順序，順便把設定檔放哪裡一次講清楚。

三個檢查步驟，順序不要顛倒

第一步看版本號。在終端機輸入 openclaude --version，正常會回一組像 0.30 開頭的號碼。如果系統回「找不到指令」，代表 npm 的全域安裝路徑沒進到系統 PATH，這是 Windows 使用者最常遇到的狀況。第二步跑 /doctor，這是內建的自我診斷指令，會把 Node 版本、設定檔位置、後端連線狀態一項一項列出來，還會直接告訴你缺什麼。像是缺 ripgrep 就照系統提示安裝，不用自己上網猜。這一步的價值在於，它把環境問題和模型問題分開，你才不會把設定錯誤誤判成 AI 不會寫程式。第三步才是確認模型連得上：用 /provider 看目前的設定檔指向哪個後端，走本機 Ollama 的話，確認 OPENAI_BASE_URL=http://localhost:11434/v1 這個位置有正常回應。三步都過了再下任務，省下的除錯時間比你想像的多。

設定檔的部分，OpenClaude 預設放在 ~/.openclaude，與 Claude Code 的 ~/.claude 完全分開，官方 README 的設定切換段落寫得很明白。這件事影響兩件事：一來，你原本 Claude Code 的登入憑證不會被拿來用，第一次啟動一定要重新設定 provider；二來，之後換電腦或做備份，只需要搬你為 OpenClaude 寫的設定檔與 skills。網路上有些教學叫你直接把整包 ~/.claude 複製過去，千萬不要，那等於把兩套不同產品的憑證混在同一個抽屜裡。

這四項檢查的順序建議照這個走：先確認版本、再跑 /doctor、接著測模型連線，最後才對設定檔位置。設定檔放對地方，之後要備份或換電腦都只搬這一個目錄。

替代方案有限公司觀點：台灣團隊安裝前該守住的三件事

台灣中小企業的疑問很固定：能不能不要綁一家雲、程式碼能不能不要出國、團隊已會的終端機指令手感能不能留下來。OpenClaude 主打同一套工作流、後面換模型，正好對上這三件事。但多數人裝完才發現收不了尾，卡住的不是安裝指令，而是動手前沒決定的三件事。

先在本機跑通，再談雲端金鑰與資料邊界

建議順序是先在單機用本機模型（例如 Ollama）走一遍流程，含讀取專案、下一個小任務、看它產生的差異。這一步不需要雲端金鑰，程式碼也不離開公司網路。跑順了再接既有金鑰，出錯時才能分辨是工具設定還是後端與金鑰的問題，不必兩邊同時猜。官方推薦清單裡有多個合作廠商提供的雲端閘道，走這些閘道代表程式碼片段會經過第三方；地端需求強的團隊要主動把後端指回自架的本機模型，別把「可以接」誤會成「預設就該走那裡」。

它在團隊裡的位置：先當個人實驗工具

專案 LICENSE 自己寫明：底層衍生程式仍屬 Anthropic 著作權，本專案沒有 Anthropic 授權散布其專有原始碼，使用者與貢獻者應自行評估法律立場。實務上意思很單純：先以個人或小組實驗名義試，別直接列進公司正式產線工具清單，等內部有人用順了再談擴大。台灣團隊缺的不是又一個更快的命令列工具，而是一條能對內交代清楚的落地順序，所以我們排成三步：先證明它在本機跑得動，再談金鑰；金鑰要接，就把資料流向寫成一頁文件，寫清楚用哪些後端、碰哪些目錄、誰有權限；第三步才決定它是個人助理還是小組共用工具。授權自述還沒有更明確答案前，不建議當正式產線預設，也不建議用「合法替代 Claude Code」對內溝通。

常見問題與下一步：三個台灣讀者最常問的安裝疑問

安裝會卡住，多半不是你不熟終端機，而是版本、名稱或網路來源其中一個對不上。以下把我們在台灣客戶現場最常被追問的三件事講清楚，卡住的時候可以照著一項一項排。

三個最常被追問的問題

Q：npm 上名字很像，怎麼確認裝到對的那一套？
市面上有一個叫 openclaudia 的專案，做的是另一件事，搜尋時很容易點錯。認明兩個東西就好：npm 套件名稱是 @gitlawb/openclaude（撰文時最新版 0.30.0），官方網址是 openclaude.gitlawb.com。裝完執行 openclaude --version，看得到版本號就代表裝對了。另外提醒，環境變數名稱沿用了舊專案寫法，看到 CLAUDE_CODE_USE_OPENAI=1 不用緊張，那只是命名沒改，不代表你要去買 Anthropic 的付費服務。

Q：一定要連外部雲端嗎？我想讓程式碼留在自己的機器。
不用。只接本機模型也能跑完整流程，最單純的做法是接 Ollama，把 OPENAI_BASE_URL 指到 http://localhost:11434/v1 再加模型名稱，程式碼就不會離開你的電腦。本機模型記得留足夠的上下文長度，官方對 Ollama 預設就要 32768，設太小會讀不完專案檔案。官方有列幾家合作閘道，那是其中一種選項，不是唯一路徑。

Q：它跟 Claude Code 的關係是什麼？公司用會不會有授權問題？
專案自己在 LICENSE 裡寫明，底層衍生程式仍屬 Anthropic 著作權，這個專案沒有取得 Anthropic 授權去散布對方的專有原始碼，使用者與貢獻者要自行評估。我們不對合法性下結論，只建議別把它當成公司正式產線的唯一預設，尤其是有法務或資安審查流程的環境。先在一台開發機用本機模型跑通讀碼與改碼流程，確認手感和流程真的合用，再考慮接上既有的雲端金鑰，同時把金鑰範圍與資料邊界寫清楚。

安裝過程卡住，或想找人一起把落地順序排出來，歡迎透過 替代方案有限公司 官網與我們聯絡，把遇到的錯誤訊息一起帶上，我們可以直接幫你看是哪一關沒過。

📩 有任何問題或需要協助，歡迎聯絡我們：[email protected]