AI 能見度相信旅遊（另開視窗）部落格作品集聯絡我們
免費快篩

OpenClaw 安裝教學：5 分鐘讓 AI 助理跑起來

Gary
2026/2/8

用 AI 深入探索這篇文章

點選下方平台，從消費者角度快速整理重點、追問問題與站內延伸閱讀

ChatGPTGoogle AI

OpenClaw 安裝現在不只是一道 npm 指令。2026 年官方文件已把安裝入口整理成「安裝腳本優先、npm/pnpm/bun 作為替代、Docker/Podman 留給容器化 Gateway」的路線；系統需求也從單純 Node.js 22+，調整為 Node 24 建議、Node 22.16+ 支援。這篇會用台灣讀者比較好操作的方式，整理 macOS、Linux、Windows WSL2、daemon、Docker、Gateway 安全與常見錯誤，讓你知道該選哪條路，而不是盲目複製指令。

OpenClaw 安裝前先選對路徑

OpenClaw 官方目前把安裝方式分成幾條路：一般使用者用安裝腳本最快；已經熟悉 Node.js 的人可以用 npm、pnpm 或 bun；要跑在伺服器、容器或隔離環境，才需要看 Docker、Podman、Nix、Ansible 這類部署方式。OpenClaw 官方 Install 文件

如果你只是想在自己的電腦上先把 AI 助理跑起來，建議順序是：

使用情境 建議方式 適合誰
第一次安裝、想少踩坑 官方 installer script 一般 macOS / Linux / WSL2 使用者
已經自己管理 Node 版本 npm install -g openclaw@latest 工程師、熟悉終端機的人
Windows 使用者 WSL2 優先，原生 Windows 可跑部分 CLI 流程 想要穩定使用 Linux 工具鏈的人
伺服器或容器化 Gateway Docker / Podman 需要 24 小時運作、隔離環境或部署到 VPS 的團隊

舊版教學常把 npm install -g openclaw@latest 當成唯一入口；這個指令仍然有效，但不是所有人都適合。尤其是 Node.js 版本、npm 全域路徑、daemon 權限、Gateway 綁定模式這幾件事，通常才是安裝卡住的原因。

如果你想先理解 OpenClaw 能做什麼，再決定要不要安裝，可以先看 OpenClaw 完整指南 2026；如果你的目標是把它放到伺服器長時間運作，則建議搭配 OpenClaw Docker 部署：讓 AI 助理 24 小時在線 一起讀。

系統需求：Node 24 建議，Node 22.16+ 仍支援

安裝前先確認環境，不然後面排錯會繞很久。根據 OpenClaw 官方文件，現在建議使用 Node 24；Node 22.16 以上仍在支援範圍內。官方也說安裝腳本會在需要時處理 Node 安裝，但如果你是用 npm 手動安裝，就要自己先把 Node 版本處理好。OpenClaw 官方 Node.js 文件

你可以先在終端機確認：

node -v
npm -v

建議判斷方式：

  • 顯示 v24.x.x：符合官方建議路徑。
  • 顯示 v22.16.x 或更高的 Node 22：仍屬支援路徑。
  • 低於 Node 22.16：先升級，不要急著裝 OpenClaw。
  • 沒有 node 指令：改用官方安裝腳本，或先安裝 Node.js。

macOS / Linux 使用者通常會用 nvm 管理 Node 版本：

nvm install 24
nvm use 24

如果你是 Windows 使用者，建議把 OpenClaw 裝在 WSL2 的 Ubuntu 裡，而不是一開始就挑戰原生 Windows。官方文件寫明 OpenClaw 支援原生 Windows 與 WSL2，但 WSL2 是較穩定的路徑；原生 Windows 的 CLI 流程正在改善中。OpenClaw 官方 Windows 文件

macOS、Linux、WSL2：官方安裝腳本最省事

一般第一次安裝，官方建議的最快方式是安裝腳本。macOS、Linux、WSL2 可以使用：

curl -fsSL https://openclaw.ai/install.sh | bash

這個腳本會偵測作業系統、必要時安裝 Node、安裝 OpenClaw，並啟動 onboarding。這也是為什麼新版教學不建議只寫 npm 指令：對沒有整理過 Node 環境的人來說，官方 installer 比手動裝套件更不容易卡在版本與 PATH。

如果你只想先安裝，不想立刻跑新手引導，可以用：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Windows PowerShell 的官方安裝入口則是：

iwr -useb https://openclaw.ai/install.ps1 | iex

不過，對多數台灣公司內部導入來說，我們仍會把 Windows 使用者引導到 WSL2：一方面 Linux 工具鏈相容性更穩定，另一方面之後如果要接 Docker、伺服器、排程或自動化腳本，也比較不會在 Windows 權限與路徑格式之間來回踩坑。

已經會管理 Node：用 npm 安裝仍然可以

如果你已經知道自己的 Node 版本符合要求，也能處理 npm 全域安裝路徑，npm 安裝仍是乾淨直接的做法：

npm install -g openclaw@latest
openclaw onboard --install-daemon

第一行把 OpenClaw CLI 裝成全域指令；第二行跑 onboarding，並安裝 daemon。官方文件也列出 pnpm 與 bun 方式，但要注意：pnpm 對帶有 build script 的 package 需要額外批准；bun 可以用於全域 CLI 安裝，但 Gateway runtime 官方仍建議使用 Node。OpenClaw 官方 npm、pnpm、bun 安裝說明

安裝後請不要直接假設成功，先跑三個檢查：

openclaw --version
openclaw doctor
openclaw gateway status

這三個指令的用途不同：

  • openclaw --version：確認 CLI 能被系統找到。
  • openclaw doctor：檢查設定與常見問題。
  • openclaw gateway status：確認 Gateway 是否正常運作。

如果你之前看過舊版教學，只記得 Node.js 22+，這裡要更新一下：現在文章建議跟著官方文件寫成「Node 24 建議、Node 22.16+ 支援」。這個差異看起來小，但對企業環境很重要，因為 IT 管理者通常需要知道推薦 runtime 與最低支援版本不是同一件事。

daemon 與 Gateway：安裝後真正要確認的是常駐服務

OpenClaw 不是只有 CLI；你要讓 AI 助理穩定收訊息、接渠道、跑背景任務，Gateway 與 daemon 才是核心。官方文件說明，openclaw onboard --install-daemon 或 openclaw gateway install 會依平台建立常駐啟動方式：macOS 走 LaunchAgent；Linux / WSL2 走 systemd user service；原生 Windows 優先使用 Scheduled Task，不行時再退回使用者 Startup 資料夾登入項。OpenClaw 官方 Install 文件的 daemon 說明

可以這樣驗證：

openclaw gateway status
openclaw doctor

如果 Gateway 沒有正常啟動，先不要急著重裝。通常應該先看：

  • Node 版本是否符合官方需求。
  • ~/.openclaw/openclaw.json 是否有格式錯誤。
  • daemon 是否讀得到 API key 或 auth profile。
  • Gateway 是否被錯誤設定成對外綁定。
  • 使用 Docker 或 WSL2 時，host 與 container / Linux 子系統的 localhost 是否搞混。

對企業導入來說，這裡也是「測試玩具」與「可營運 AI 助理」的分界。只要會跑 openclaw 不代表可以放進公司流程；你還要知道服務怎麼重啟、怎麼看健康狀態、怎麼保護 token，以及誰可以傳訊息給這個 agent。

如果你正在評估企業場景，可以延伸看 用 OpenClaw 打造 24 小時 AI 客服機器人 與 我讓 AI 開始接管我的公司運作了（本文會持續更新進度），先把「安裝成功」轉成可營運的流程設計。

Docker 與 Podman：不是本機入門必需品

Docker 很常被誤解成 OpenClaw 必備條件。官方 Docker 文件寫得很清楚：Docker 是 optional，適合需要容器化 Gateway、一次性隔離環境，或不想在 host 直接安裝 OpenClaw 的情境；如果你只是在自己電腦上追求最快開發回路，應該使用一般安裝流程。OpenClaw 官方 Docker 文件

Docker 路徑要注意幾件事：

  • 需要 Docker Desktop 或 Docker Engine，加上 Docker Compose v2。
  • 官方文件提到 image build 至少需要 2 GB RAM；1 GB 主機可能在 pnpm install 時被 OOM kill，出現 exit 137。
  • Docker setup 會產生 Gateway token 並寫入 .env。
  • Control UI 預設可透過 http://127.0.0.1:18789/ 開啟，並使用 shared secret。
  • 在 Docker 裡，127.0.0.1 指的是 container 自己；要連 host 上的本地模型服務，通常要看官方 Docker 文件對 host local providers 的設定。

Podman 則偏向 rootless container 與 Linux / systemd 使用者服務情境。官方 Podman 文件描述的是：Gateway 跑在 rootless Podman container，host 上的 openclaw CLI 作為 control plane，狀態預設保存在 ~/.openclaw。OpenClaw 官方 Podman 文件

如果你是第一次安裝 OpenClaw，不建議一開始就把 Docker、Podman、WSL2、Gateway 遠端連線全部混在一起。先在本機把 CLI 與 Gateway 跑通，再決定是否升級成容器化部署，比較容易定位問題。

Gateway 安全設定：不要把 0.0.0.0 當成方便開關

OpenClaw 的 Gateway 牽涉模型金鑰、訊息渠道、工具權限與可能的本機檔案操作，所以安全設定不能只當附錄。官方安全文件明確提醒：gateway.bind: "loopback" 是預設本機連線；非 loopback 綁定，例如 lan、tailnet、custom，都會擴大攻擊面，必須搭配 Gateway auth 與防火牆。也不要把 Gateway 以未授權方式暴露在 0.0.0.0。OpenClaw 官方 Gateway Security 文件

比較保守的本機設定思路是：

{
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: { mode: "token", token: "replace-with-long-random-token" }
  }
}

實務上請記住三件事：

  • 本機測試用 loopback，不要為了「手機也連得到」就直接開 LAN 或 0.0.0.0。
  • 要遠端使用，優先看 Tailscale Serve、trusted proxy 或官方遠端 Gateway 文件，不要自己亂開 port forwarding。
  • token、API key、OAuth token、channel bot token 都不該貼到公開 issue、聊天群或截圖裡。

如果你已經把 Gateway 暴露到 LAN 或 public host，至少要回頭做一次 openclaw doctor，並檢查 Gateway auth、allowed origins、防火牆與 channel allowlist。OpenClaw 的能力越接近「可以代你操作電腦」，安全邊界就越不能用 demo 心態處理。

模型驗證與 Anthropic 設定：API key 最穩，Claude CLI 可重用

安裝 OpenClaw 只是第一步；要讓 AI 助理真的回應，還需要模型 provider 的憑證。官方 authentication 文件建議，長時間運作的 Gateway host 以 API key 最可預期；如果使用 Anthropic，OpenClaw 也支援重用同一台 host 上的 Claude CLI login。OpenClaw 官方 Gateway Authentication 文件

最保守的做法是把 provider API key 放在 Gateway host，daemon 可讀取的位置，例如 ~/.openclaw/.env：

cat >> ~/.openclaw/.env <<'EOF'
<PROVIDER>_API_KEY=***
EOF

openclaw models status
openclaw doctor

如果你想走 Claude CLI 重用路徑，官方文件列出的流程是先在 gateway host 登入 Claude，再讓 OpenClaw 使用 anthropic 的 cli method：

claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

這裡不要把「可以重用 Claude CLI」理解成不用管理安全。對長期在線的公司助理來說，API key 仍然比較容易控管帳務、輪替與權限；OAuth 或 CLI 重用比較適合已經清楚知道帳號邊界與主機信任模型的人。

常見錯誤排除：先查版本、PATH、Gateway，再重裝

很多 OpenClaw 安裝問題，不需要一開始就移除重裝。依官方文件與實務經驗，可以照這個順序排查。

command not found: openclaw

這通常是 npm 全域 bin 路徑沒有進 PATH。先看：

node -v
npm prefix -g
echo "$PATH"

如果 $(npm prefix -g)/bin 不在 PATH，加入 shell 啟動檔，例如 ~/.zshrc 或 ~/.bashrc：

export PATH="$(npm prefix -g)/bin:$PATH"

重開終端機後再試：

openclaw --version

Node 版本不符

如果 npm 安裝時出現 engine 或語法相關錯誤，先不要跳過警告。請回到 Node 版本檢查，使用 Node 24 或至少 Node 22.16+。如果環境很亂，通常官方 installer 或 nvm 會比手動改系統 Node 來得乾淨。

Gateway status 不正常

先跑：

openclaw doctor
openclaw gateway status

如果是設定檔格式或 schema 問題，官方 configuration 文件提到 Gateway 會拒絕啟動；此時 openclaw doctor 會比盲目重裝更有用。OpenClaw 官方 Configuration 文件

Docker 裡連不到本機模型

在 container 內，127.0.0.1 指的是 container，不是你的 macOS / Windows / Linux host。官方 Docker 文件對 LM Studio、Ollama 這類 host local providers 有特別說明；遇到這種問題，請優先查 Docker 文件，不要直接把 Gateway 端口對外打開。

WSL2 網路與 Windows 防火牆問題

官方 Windows 文件說明，WSL 有自己的虛擬網路。如果你要讓其他機器連到 WSL 裡的服務，需要處理 Windows portproxy 與防火牆；但如果只是本機使用，優先保持 local，不要一開始就開 LAN。這也是我們建議新手先在 WSL2 內完成基本安裝與驗證，再處理對外連線的原因。

更新與移除：用官方指令，不要只刪資料夾

OpenClaw 更新建議使用：

openclaw update

官方 updating 文件說這個指令會偵測安裝類型、抓取最新版本、執行 openclaw doctor，並重啟 Gateway。若你想先看會做什麼，可以用：

openclaw update --dry-run
openclaw update status --json

如果你是手動 npm 更新，請記得 managed Gateway 正在跑的情況下，更新後要重啟 Gateway：

npm i -g openclaw@latest
openclaw doctor
openclaw gateway restart

移除則不要只刪 npm package。官方 uninstall 文件建議優先使用：

openclaw uninstall

需要自動化或非互動流程時，可用：

openclaw uninstall --all --yes --non-interactive
npx -y openclaw uninstall --all --yes --non-interactive

手動移除通常包含停止 Gateway、移除 launchd / systemd / Windows task、刪除 state/config，再移除 CLI。這些步驟要照順序做，否則容易出現 CLI 不見了，但背景服務還在跑的狀況。OpenClaw 官方 Install 文件中的 Updating 說明 OpenClaw 官方 Install 文件中的 Uninstall 說明

安裝完成後，下一步該做什麼

OpenClaw 裝好之後，建議不要急著把所有工具權限打開。比較穩的路線是：

  1. 用 openclaw doctor 確認環境健康。
  2. 用 openclaw models status 確認模型憑證可用。
  3. 先在本機與 AI 助理對話，測試它是否理解你的工作目錄與任務。
  4. 再逐步串接 Telegram、LINE、Discord 或公司內部渠道；如果你想把 OpenClaw 放進內容流程，可參考 拿Openclaw 串接Threads自動發文：從工具到觀點的實戰分享。
  5. 如果要 24 小時運作，再評估 Docker、VPS、Tailscale 與安全設定。

好事發生在導入 AI agent 時，通常不會把「安裝成功」當成專案完成。真正重要的是：誰能觸發 agent、它能碰哪些檔案、能不能執行命令、錯誤怎麼追、成本怎麼控、權限怎麼回收。這些問題比安裝指令更接近企業能不能放心使用 AI 助理。

延伸閱讀可以從這幾篇開始：

OpenClaw 安裝常見問題

OpenClaw 一定要用 Docker 嗎？

不用。官方 Docker 文件明確把 Docker 定位為 optional，適合容器化 Gateway、隔離環境或部署到不想直接安裝 OpenClaw 的 host。本機入門優先用官方 installer 或 npm 安裝即可。

Windows 可以直接安裝 OpenClaw 嗎？

官方文件寫明支援原生 Windows 與 WSL2，但 WSL2 是更穩定的路徑。若你只是要穩定使用 OpenClaw，建議先在 WSL2 的 Ubuntu 裡安裝；原生 Windows 可再依官方文件確認目前支援的 CLI 與 daemon 流程。

openclaw onboard --install-daemon 是做什麼？

它會跑新手引導並安裝常駐服務。依官方說明，macOS 使用 LaunchAgent，Linux / WSL2 使用 systemd user service，原生 Windows 優先使用 Scheduled Task。

安裝後輸入 openclaw 卻找不到指令怎麼辦？

先檢查 node -v、npm prefix -g、echo "$PATH"。如果 npm 的全域 bin 目錄沒有放進 PATH，把 $(npm prefix -g)/bin 加到 ~/.zshrc 或 ~/.bashrc，重開終端機後再試。

Gateway 可以綁定 0.0.0.0 嗎？

不要把它當成方便開關。官方安全文件提醒，非 loopback 綁定會擴大攻擊面；未授權暴露在 0.0.0.0 是高風險做法。需要遠端連線時，應搭配 token/password、trusted proxy、Tailscale 或防火牆等正式安全設計。

←Back to Blog