OpenClaw Linux 安裝教學 2026：在 Ubuntu 上自架一隻不會斷線的 AI Agent

週五下午，客戶的後端工程師丟了一則訊息過來。OpenClaw 在他的 MacBook 上跑得很順，他想搬到公司那台閒置的 Ubuntu 伺服器，讓整組人都用得到。他照著搜到的教學做了兩個小時，卡在兩個地方：SSH 一登出，服務就沒了；設定檔怎麼改，MCP 工具都不出現在清單裡。

先講結論。在 Ubuntu 或 Debian 上把 OpenClaw 裝起來，最短路徑是一行安裝腳本加一行 onboard，十分鐘內就會看到 Control UI，這部分沒有想像中難。真正會吃掉整個下午的是後面兩件事：讓 gateway 在登出之後繼續活著（這是 systemd user service 的既有行為，跟 OpenClaw 本身無關），以及決定這隻 agent 到底能碰到哪些東西。第二件事我們建議投入的時間，比安裝本身多得多。

OpenClaw 到底是什麼？為什麼要自己架在 Linux 上？

OpenClaw 是一隻跑在自己機器上的個人 AI 助理。它的核心是一個常駐的 gateway 服務，把 LLM 接到平常已經在用的溝通管道，WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Microsoft Teams、LINE、Matrix 這些都在支援清單上。專案由 Peter Steinberger 發起，前身叫 Clawdbot，中途改名 Moltbot，最後才定名 OpenClaw。這段改名史是搜舊教學時會撞到的第一個坑，2026 年初的文章裡有不少指令還停在舊名字，照抄會直接失敗。想先補概念的話，我們在 OpenClaw 是什麼 那篇拆過它的定位與生態。

幾個數字可以說明它現在的體量：GitHub 上的 openclaw/openclaw 累積約 38 萬顆星、將近 7 萬次 commit；npm 上 openclaw 這個套件已經發布 234 個版本，最新穩定版是 2026.7.1，發布於 2026 年 7 月 13 日，也就是本文查證日的四天前。版本號走的是日期格式，更新頻率大概就是這個節奏。授權是 MIT，clone、改、商用都可以。這個專案沒有停更、沒有再改名，狀態非常健康。

那為什麼一定要 Linux？把 OpenClaw 裝在筆電上，agent 的生命週期就跟著筆電走，闔上蓋子就斷線。而它的價值恰好在常駐：半夜跑排程、隨時收 webhook、持續盯著信箱與庫存。這件事需要一台不關機、有固定網路位置、能交給 systemd 管起來的機器，Linux 伺服器天生就是幹這個的。一人 AI 工廠 那套玩法能成立，前提就是有一台隨時醒著的主機在背後撐著。

自架跟找託管服務，差別在哪？

動手之前，這台機器要準備到什麼程度？

OpenClaw 是 Node 應用，而它的 Node 版本要求卡得異常細，不是「Node 20 以上」這種寬鬆條件。這是我們看到最多人第一步就摔倒的地方。實際條件寫在套件的 engines 欄位裡：>=22.22.3 <23 || >=24.15.0 <25 || >=25.9.0，官方預設推薦 Node 24。Ubuntu 24.04 用 apt 裝到的 Node 版本並不符合這個條件，請直接改用 NodeSource 或 nvm。

關於硬體，這裡要誠實說：官方文件並沒有給出一張硬性的 RAM 與 CPU 規格表，查得到的具體數字只有兩個，一是 Docker 文件要求建置映像檔時至少 2 GB 記憶體，二是 Linux 平台文件提到 exit code 137 代表被 OOM killer 砍掉。就我們實際跑的經驗，2 核心 4 GB 的 VPS 應付單一 agent 沒有問題；但若打算同時開多隻 agent、又掛上瀏覽器類的工具，先撞到的天花板會是記憶體而不會是 CPU，規劃時把預算放在 RAM 上比較划算。

先把 Node 準備好：

# Ubuntu / Debian，透過 NodeSource 安裝 Node 24
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

node -v   # 需要落在 24.15.0 以上、25 以下

四條安裝路徑，該走哪一條？

路徑一：官方安裝腳本

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

# 只想先裝好，稍後再自己跑 onboarding
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

把管線直接接到 bash 這種安裝方式，資安上一直有爭議，而這篇文章後半整段都在講風險，所以這裡不便宜行事。如果這台是正式環境的機器，請先把腳本抓下來讀過再執行，這是基本動作：

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

路徑二：npm 或 pnpm 全域安裝

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

用 pnpm 的話多一個步驟。pnpm 要求明確核准帶有 build script 的套件，漏了這行會裝出一個跑不起來的殼：

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

--install-daemon 這個旗標很重要，它會順手把 gateway 註冊成系統服務，省掉稍後手動寫 unit 檔的功夫。

路徑三：Docker Compose

git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 直接用官方預先建置的映像檔，省下本機 build 所需的記憶體
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

前置條件是 Docker Engine 加上 Docker Compose v2。預先建置的映像檔會先發布到 GitHub Container Registry，Docker Hub 上的 openclaw/openclaw:latest 是鏡像站。setup.sh 會把 onboarding 一併跑完，包含詢問 provider 的 API key，並產生一組 gateway token 寫進 .env。容器內的掛載點是 /home/node/.openclaw，workspace 掛在它底下，認證設定檔則在 /home/node/.config/openclaw。如果本機記憶體不到 2 GB 又堅持自己 build，會收到 exit code 137，那是 OOM 而不是編譯錯誤，別浪費時間去查編譯訊息。

需要離線部署時，官方也留了路：

docker load -i openclaw-image.tar
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh --offline

路徑四：從原始碼建置

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm build && pnpm ui:build
pnpm link --global
openclaw onboard --install-daemon

第一次啟動，會遇到什麼？

onboard 流程會問 provider 的 API key、選模型、設定要接哪些管道。跑完之後不要急著開瀏覽器，先驗三件事：

openclaw --version
openclaw doctor
openclaw gateway status

openclaw doctor 是最值得先跑的一條，它會把 Node 版本、設定檔位置、權限、連接埠這些常見問題一次列出來，比逐項猜快得多。想看即時 log，可以讓 gateway 跑在前景：

openclaw gateway --port 18789 --verbose

接著開 Control UI。gateway 預設只綁 loopback，所以在遠端伺服器上沒辦法直接從外面連進去，這是它保護使用者的設計而不是故障。正確做法是從自己的電腦開一條 SSH 通道接過去：

# 在本機執行，把遠端的 18789 接到本機的 18789
ssh -L 18789:127.0.0.1:18789 user@your-server

然後在瀏覽器打開 http://127.0.0.1:18789/，貼上 .env 裡那組 token 就進得去了。

為什麼一登出，agent 就死了？

這是 Linux 上最多人卡住的地方，也是開頭那位工程師踩到的坑。OpenClaw 在 Linux 與 WSL2 上安裝的是 systemd 的 user service，名稱是 openclaw-gateway.service，檔案放在 ~/.config/systemd/user/ 底下。systemd 預設會在使用者登出時收掉 user service，於是 SSH 一斷，gateway 就跟著陪葬。這跟 OpenClaw 沒有關係，任何以 user service 形式常駐的東西都會這樣。

onboarding 會嘗試替你開啟 lingering，過程中可能索取 sudo 權限。如果當下跳過或沒成功，手動補上：

sudo loginctl enable-linger $USER
systemctl --user enable --now openclaw-gateway.service
systemctl --user status openclaw-gateway

如果偏好系統層級的服務，官方支援把同一份 unit 內容放到 /etc/systemd/system/ 底下管理。另外，在低階 VM 或 ARM 主機上如果覺得 CLI 反應遲鈍，官方建議補兩個環境變數，實測對冷啟動時間有感：

systemctl --user edit openclaw-gateway.service

[Service]
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Restart=always
RestartSec=2
TimeoutStartSec=90

怎麼讓 OpenClaw 接上既有的系統？

裝起來只是讓 agent 會講話，要它真的做事，得把工具接上去，這就是 MCP 的位置。對 MCP、API、CLI 三者的分工還沒有清楚圖像的話，MCP、API 與 CLI 的差別 那篇可以先看過再回來。

這裡有一個查資料時極容易中招的陷阱，也是開頭那位工程師的第二個坑。多數第三方教學會叫人在 openclaw.json 裡加一段 mcpServers，那是 Claude Desktop 的格式，貼進 OpenClaw 不會生效，也不會報錯，工具就是安靜地不出現。OpenClaw 官方管理的路徑是巢狀的 mcp.servers：

{
  "mcp": {
    "servers": {
      "docs": {
        "url": "https://mcp.example.com",
        "transport": "streamable-http",
        "timeout": 20,
        "auth": "oauth"
      }
    }
  }
}

與其手改 JSON，用 CLI 比較不會出錯。改完設定記得重啟 gateway，工具才會被重新載入：

openclaw mcp add <name> [flags]
openclaw mcp list
openclaw mcp configure <name> [flags]
openclaw mcp unset <name>

傳輸方式有三種：stdio 會在本機開一個子行程，透過標準輸入輸出溝通，適合本地工具；SSE 與 streamable-http 走 HTTP，用來接遠端的 MCP 服務。另外提醒一個 Docker 專屬的坑，在容器裡要接本機的 LM Studio 或 Ollama，位址要寫 http://host.docker.internal:PORT，寫 127.0.0.1 只會連到容器自己。

工具接上之後，才是真正產生價值的部分。幾個我們寫過的實際場景可以參考：自動化訂單處理的 agentic workflow、WooCommerce 庫存自動同步，以及 競品資料蒐集自動化。如果之後打算讓多隻 agent 互相協作而不是單打獨鬥，A2A 協定 會是下一個該研究的主題。

自架一隻 agent，資安要守住哪幾條？

這一段我們寫得比安裝步驟還用力。一隻能執行指令、能讀檔案、能連外網、而且全天候常駐的服務，跟一般的 web app 完全不在同一個風險等級上。

先看官方自己怎麼定位。安全文件裡有一句話講得非常直白：OpenClaw 並不是一個用來隔離多個互相敵對使用者的多租戶安全邊界。它的信任模型是個人助理，預設就假設操作的人是自己。這句話的份量在於，如果打算讓全公司共用同一個 gateway，安全邊界得自己在外面補，不能指望它內建。這正是 企業級多租戶部署 要處理的題目。

好消息是預設值相當保守：gateway 預設只綁 loopback、預設要求認證、認證路徑設錯時採 fail closed 直接拒絕 WebSocket 連線，陌生人私訊也要走配對碼核准。這些預設值請不要為了一時方便就拆掉，它們是這套系統最後的護欄。以下是我們實際部署時會逐條確認的清單：

• 不要為了從外面連得到就把 gateway 綁上 0.0.0.0。要遠端存取，先用 SSH 通道，或把主機加進 Tailscale 用 Tailscale Serve，官方明確建議這個做法優於直接綁區網。
• 放在反向代理後面時，記得設定 gateway.trustedProxies，否則來源 IP 的判斷會出錯，認證邏輯跟著失準。
• 把 agent 的檔案存取限制在工作區內，設定 workspaceOnly: true。
• 需要處理不可信內容的 agent，直接關掉 exec、browser、web_fetch 這類高風險工具。
• 沒有明確需求就讓 tools.elevated 保持關閉。
• 替每隻 agent 開 Docker 沙箱，隔離工具的實際執行環境。
• 如果主機上可能跑到不可信的本地程式碼，關掉 Tailscale 的 identity header 認證。

定期稽核，不要等出事才看：

openclaw security audit --deep

萬一真的出事，官方給的處理順序是先止血再輪替：第一步把綁定改回 loopback 或關掉對外通道，第二步輪替所有憑證，包含 gateway token、provider API key、各管道的憑證，第三步回頭翻 session 的對話紀錄，確認有沒有被指使做過什麼。順序不要顛倒，先關門再換鎖。

再往上一層，權限模型與資料外洩防護是另一個完整的題目，企業 AI agent 的權限控管與 DLP 和 agent 護欄設計 這兩篇補得比較完整。另外，如果這隻 agent 之後要回頭爬自家網站，把網站準備好給 AI agent 讀 能讓它省下大量無謂的解析力氣。

裝不起來的時候，先看哪裡？

照經驗，八成的問題落在下面這幾類：

• 服務起不來：先看日誌，journalctl --user -u openclaw-gateway，再確認 unit 檔存不存在於 ~/.config/systemd/user/openclaw-gateway.service。
• exit code 137：這是 OOM，不是程式壞掉。加記憶體、加 swap，或降低併發。Linux 上 OpenClaw 會刻意讓短命的子行程優先被 OOM killer 挑中，用來保護長命的 gateway 連線，所以看到子行程被砍掉不一定是災難。
• 啟動就被擋：十之八九是 Node 版本，node -v 對一次上面那張表。
• 服務沒被註冊：補跑 openclaw gateway install。
• 登出就斷：lingering 沒開，回去看上一節。
• Control UI 連不上：確認 SSH 通道有開，而且沒有誤把綁定改掉。
• headless 伺服器上 Canvas 不出現：這是正常的，Canvas 需要桌面版的伴隨程式才會被 advertise，純伺服器環境本來就不會有。
• AppImage 跑不動：缺 libfuse2，Ubuntu 24.04 以後要裝的套件名是 libfuse2t64。

三條萬用的排查指令：

openclaw doctor
systemctl --user status openclaw-gateway
journalctl --user -u openclaw-gateway -f

資料來源

本文查證於 2026 年 7 月 17 日，版本號、Node 需求與指令均以當日官方 repo、官方文件與 npm registry 的實際內容為準。OpenClaw 的更新速度極快，套件至今已發布 234 個版本，動手之前建議再對一次官方文件。

• openclaw/openclaw 官方 GitHub repository
• OpenClaw 官方安裝文件
• OpenClaw Docker 安裝文件
• OpenClaw Linux 平台文件
• OpenClaw Linux server 部署文件
• OpenClaw Gateway 安全性文件
• OpenClaw MCP CLI 文件
• npm registry：openclaw 套件版本與 engines 欄位

延伸閱讀

• OpenClaw 是什麼？2026 年這隻 AI agent 為何爆紅
• OpenClaw 企業級部署與多租戶架構指南
• MCP、API 與 CLI 的差別，一次講清楚
• 企業 AI agent 的權限控管與資料外洩防護

一台機器跑起來之後，才是真正的工程

照著上面走完，裝一台自己用的 OpenClaw，一個下午綽綽有餘。但我們在客戶端反覆看到的是另一種難題：機器裝好了，接下來呢？誰可以用、能碰哪些系統、什麼動作需要誰批准、三個月後有人問起某筆異動，查得到紀錄嗎？單機自架不需要回答這些問題，公司規模的部署每一條都得回答，而且多半還要接上手上既有的 ERP、CRM 或電商後台，那些系統通常沒有現成的 MCP server 等著。

浪花科技做的就是後面這一段。如果 OpenClaw 已經在測試機上跑起來了，想討論怎麼讓它落進團隊的實際流程，可以看看我們的 AI 自動化開發服務，或直接跟我們聊聊手邊的情境。