OpenClaw 完整安裝教學：Node.js 環境設定到 Telegram 串接，一篇搞定（v2026.3.x）

Posted on by Clarence

最近 OpenClaw（俗稱「龍蝦」）在 GitHub 上爆紅，star 數已超越 React，成為史上最多人追蹤的開源專案之一。這篇文章記錄我從零安裝的完整過程，包含環境準備、常見錯誤排除、Telegram 串接，適合有基本終端機操作經驗的讀者。

本文撰寫時使用版本為 v2026.3.x（stable channel），OpenClaw 更新速度極快，建議安裝後先跑 openclaw doctor 確認環境。

OpenClaw 是什麼？

OpenClaw 是一個跑在你自己電腦或伺服器上的開源 AI Agent 框架。跟 ChatGPT 最大的差別是：它不只是「回答問題」，而是能實際操作你的檔案、跑指令、讀寫 Email、串接 Telegram / Discord / LINE，讓 AI 幫你執行任務，不是只給建議。

架構上它分成兩層：

  • Gateway（閘道）：背景常駐服務，負責接收來自 Telegram 等通訊平台的訊息
  • Agent：處理邏輯的主體，呼叫 Claude / OpenAI / Gemini 等 LLM API 來執行任務

AI 的運算在雲端（你的 API Key），你的電腦只跑輕量的 Gateway 服務，資源需求不高。

事前準備

在開始之前，確認你有以下東西：

  • 一台可以長時間開著的機器（VPS、Mac Mini、或自己的主機）
  • Node.js 22 以上版本（必要條件，版本不對是最常見的安裝失敗原因）
  • 至少一個 LLM API Key（Claude API 或 OpenAI API）
  • Telegram 帳號（如果要用 Telegram 控制的話）

步驟一：確認 Node.js 版本

先確認版本，這步很多人跳過，結果裝完一堆 runtime 錯誤。

node -v

如果版本低於 22，用 nvm 升級是最乾淨的方式：

# 安裝 nvm（如果還沒有）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

# 重新載入 shell
source ~/.bashrc  # 或 ~/.zshrc

# 安裝並切換到 Node 22
nvm install 22
nvm use 22
nvm alias default 22

# 確認版本
node -v  # 應該顯示 v22.x.x

步驟二：安裝 OpenClaw

官方提供三種安裝方式，一般人用安裝腳本最省事：

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

腳本會自動偵測 Node.js 版本、安裝依賴、並啟動 onboarding 引導流程。

如果你偏好手動控制，用 npm 安裝也可以：

npm install -g openclaw@latest

安裝完成後驗證：

openclaw --version

常見安裝錯誤：sharp 相關

在 macOS 上如果有裝 Homebrew 的 libvips，可能會遇到 sharp 安裝失敗。解法：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

步驟三：執行 Onboarding 引導

安裝完後執行 onboarding，這個引導流程會幫你設定好所有核心配置：

openclaw onboard --install-daemon

引導流程會依序問你：

  1. AI 模型選擇：Claude API Key、OpenAI、GitHub Copilot 或其他 OpenAI Compatible 服務
  2. 通訊平台：Telegram Bot Token、Discord、Slack 等
  3. Skills 設定：選擇要啟用哪些技能（Gmail、Google Calendar、GitHub 等）
  4. Gateway 設定：port 18789、bind 位址

建議先選 QuickStart，把基本環境跑起來，之後再慢慢加功能。

步驟四：串接 Telegram

Telegram 是目前最穩定的控制方式。先去跟 @BotFather 建立一個 Bot，拿到 Bot Token（格式像 123456789:AAxxxxxx）。

Onboarding 時貼上 Token，引導流程會自動完成配對。如果已經跑完 onboarding 想補加，執行：

openclaw configure

找到 Telegram 設定區塊填入即可。配對完成後你會在 Telegram Bot 那邊收到訊息，或執行：

openclaw gateway status

確認 Gateway 正常運行。

步驟五：確認 Gateway 正常運作

# 查看狀態
openclaw gateway status

# 查看整體健康狀況
openclaw health

# 診斷問題（有問題必跑）
openclaw doctor

如果 Gateway 沒有自動啟動，手動啟動：

openclaw gateway start

安全設定：一定要改的預設值

這部分很多教學都跳過，但如果你有把 Gateway 對外開放，這幾個設定非常重要。

1. 把 Canvas Host 綁到 loopback

OpenClaw 的 Dashboard 介面預設 bind 0.0.0.0，代表區域網路內所有人都可以存取你的 OpenClaw 介面。找到 openclaw.json（通常在 ~/.openclaw/），加入：

{
  "gateway": {
    "bind": "loopback"
  }
}

修改後重啟 Gateway：

openclaw gateway restart

2. 設定 API 花費上限

OpenClaw 是 Agent 模式，一個任務會觸發多次 API 呼叫，Token 消耗比一般對話快得多。沒設上限的話帳單會讓你嚇一跳，在 Claude 或 OpenAI 的 Dashboard 設定每月花費上限。

3. 謹慎安裝第三方 Skills

ClawHub 技能市場上的第三方套件品質參差不齊，安裝前先看一下來源和 GitHub repo，有資安疑慮的不要裝。

讓 Gateway 開機自動啟動（Linux）

如果是跑在 Linux VPS 上，讓 Gateway 變成 systemd 服務：

openclaw gateway install

如果這個指令報錯（常見於 Ubuntu 24 的虛擬機環境），手動處理：

sudo loginctl enable-linger $USER
echo 'export XDG_RUNTIME_DIR=/run/user/$(id -u)' >> ~/.bashrc
echo 'export DBUS_SESSION_BUS_ADDRESS=unix:path=${XDG_RUNTIME_DIR}/bus' >> ~/.bashrc
source ~/.bashrc
openclaw gateway install

日後更新

OpenClaw 更新很頻繁，建議用官方內建指令更新，不要只用 npm，因為它還會同步更新 systemd/launchd 的守護程式設定：

# 停止 Gateway
openclaw gateway stop

# 更新
openclaw update --channel stable

# 重啟並確認
openclaw gateway start
openclaw --version
openclaw doctor

總結

安裝流程整理如下：

  1. 確認 Node.js >= 22
  2. curl -fsSL https://openclaw.ai/install.sh | bash
  3. openclaw onboard --install-daemon，照引導設定 API Key 和 Telegram
  4. 改 openclaw.json 把 bind 改成 loopback
  5. openclaw gateway install 設定開機自啟
  6. 在 LLM 服務商那邊設花費上限

有遇到什麼問題歡迎留言，或先跑 openclaw doctor 看看診斷結果，這個指令通常會直接告訴你哪裡有問題。

No comments yet
OpenClaw 龍蝦