openclaw 教學 — 從安裝到接上 Telegram，以及卡住時該看哪裡

openclaw 的安裝本身只要幾分鐘。真正吃掉時間的是之後：找不到指令、裝好了但 gateway 起不來、原本正常的 Mac 睡一覺醒來就不講話了。

這些都先整理在這裡。

2026 年 7 月 30 日 · 以 v2026.7.1 驗證 · 所有指令皆取自官方文件，出處列於文末

openclaw 是什麼

一個跑在你自己機器或伺服器上的 gateway。開一個行程，它就負責把通訊軟體和 LLM agent 接起來。官方文件的說法是「session、routing 與 channel 連線的單一真實來源」，CLI、網頁介面、手機 App 全都是對著這個 gateway 說話。

CLI — openclaw …
常駐服務 — macOS 用 launchd，Linux 與 WSL2 用 systemd user service，Windows 用工作排程器
網頁控制台 — http://127.0.0.1:18789/
Docker image — ghcr.io/openclaw/openclaw:latest
周邊 App — macOS 選單列、Windows Hub、iOS 與 Android 節點

請記住 18789 這個 port。後面一半的疑難排解都跟它有關。

名字撞名了。1997 年的遊戲 Captain Claw 有一個 C++ 重製版也叫 OpenClaw。搜尋結果裡出現 SDL2 或 Box2D，那是另一個專案。

安裝前先確認

Node 版本。需要 22.22.3 以上、24.15 以上，或 25.9 以上。低於 22.22.3 不會動。

推薦版本在官方來源之間並不一致：文件站建議 Node 26，README 寫的是 24.15 以上。兩者都符合最低要求，沒有特別理由的話交給安裝腳本處理最省事。

一把模型 API key。導引精靈會問，不必自己寫進檔案。支援清單很長——Anthropic、OpenAI、Google、xAI、Bedrock、Azure、Groq、Mistral、DeepSeek、OpenRouter 等等；本地模型可以透過 Ollama、LM Studio、vLLM 跑。

也可以沿用你已經在付的訂閱（已登入的 Claude CLI、OpenAI Codex OAuth、GitHub Copilot、Gemini CLI）。但文件有提醒：沿用訂閱會消耗該方案的用量額度。如果打算全天候開著，官方建議「Anthropic API key 在費用上比較好預測」。

pnpm 只有從原始碼建置時才需要。文件明講在 repo 根目錄直接跑 npm install 是不支援的做法，因為那是 pnpm workspace。

安裝

安裝腳本（官方推薦）

會自動判斷作業系統，需要的話連 Node 一起裝。

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

Windows 在 PowerShell：

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

不想動到系統的 Node

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

npm / pnpm / bun

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

npm 12 預設會擋掉 lifecycle script，所以上面那行直接跑會失敗。

npm install -g openclaw@latest --allow-scripts openclaw

pnpm 也一樣：

pnpm add -g --allow-build=openclaw openclaw@latest

bun 裝得起來但跑不動。bun add -g openclaw@latest 會成功，然後 gateway 起不來，因為 bun 沒有 node:sqlite。要用 bun 安裝可以，執行請用 Node。

從原始碼

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

確認裝好了

openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

只要覺得哪裡怪，先跑 openclaw doctor。下面疑難排解裡的一大半它會自己抓出來。

Docker

./scripts/docker/setup.sh

Image 是 ghcr.io/openclaw/openclaw:latest，Docker Hub 上也有鏡像。基底是 node:24-bookworm-slim，PID 1 是 tini。另有 slim 以及內含 Chromium 的 latest-browser 標籤。

建置至少要 2GB 記憶體。在 1GB 的主機上 pnpm install 會被 OOM 砍掉，只留下 exit 137——不知道的話會查很久。

curl -fsS http://127.0.0.1:18789/healthz

接上 Telegram

這裡多數人會愣一下。核心內建的頻道只有 iMessage、Telegram、WebChat 三個。WhatsApp、Discord、Slack、Signal、LINE 這些全部是獨立外掛，裝完還要重啟 gateway。

在台灣要用的話，Telegram 最快：一組 token 就好，沒有 QR 流程。

對 @BotFather 送 /newbot，拿到 token。

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Telegram 不使用 openclaw channels login。那是給走 QR 的頻道用的。Token 優先序是 tokenFile > botToken > 環境變數。

WhatsApp 是兩個步驟

openclaw plugins install clawhub:@openclaw/whatsapp
openclaw channels login --channel whatsapp
openclaw pairing approve whatsapp <CODE>

登入只支援 QR（Baileys，也就是 WhatsApp Web 的方式）。容易搞混的是：QR 登入和配對核准是兩道不同的關卡。QR 是把你的 WhatsApp 帳號接上 gateway，配對核准則是決定「誰可以對 agent 說話」。做了前者不等於做了後者。

在無頭或遠端主機上，把 QR 送到手機其實很麻煩。文件提醒終端機 QR 或截圖「可能在傳送途中就過期」。打算 SSH 進 VPS 設定的話請先想好這一段。

設定檔

~/.openclaw/openclaw.json，格式是 JSON5（可以寫註解、可以留尾逗號，key 也不必加引號）。

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

`~/.openclaw/workspace`	agent 的工作目錄
`~/.openclaw/state/openclaw.sqlite`	gateway 狀態
`~/.openclaw/agents/<id>/agent/openclaw-agent.sqlite`	session 紀錄
`~/.openclaw/agents/<id>/agent/auth-profiles.json`	憑證

手動編輯有兩件事要注意。一，不能只寫你改的那一段，必須寫出完整的 JSON5。二，內容不合法時 gateway 不會退回預設值啟動，而是完全不啟動。所以一個不相干的拼字錯誤看起來就像「openclaw 壞了」。

文件明確要求不要把 API key 直接寫死在這個檔案裡。

記憶就是檔案

Agent 的記憶是 workspace 裡的 Markdown，在新 session 的第一輪以 Project Context 注入：AGENTS.md（操作指示與記憶）、SOUL.md（人格）、IDENTITY.md、USER.md、MEMORY.md（只有放在 workspace 根目錄才會當成長期記憶）、BOOTSTRAP.md（只跑一次，跑完自己刪掉）。

出問題時

`openclaw: command not found`

文件講得很直接：「幾乎一定是 PATH 問題」。npm 的 global bin 沒進 PATH。

npm config get prefix

把那底下的 bin 加進 PATH。Windows 通常在 %AppData%\npm。

裝好了但 gateway 起不來

如果是用 bun 裝的，原因就在這（沒有 node:sqlite）。改用 Node 重裝。

`EADDRINUSE`，或 gateway 一直重啟

18789 被別的東西占用了，或者你有兩份服務定義。用不同方式裝兩次時，launchd job 或 systemd unit 很容易重複。兩邊都要檢查。

更新後頻道不見了

plugin load failed: dependency tree corrupted; run openclaw doctor --fix

照字面跑就好。

服務控制指令沒反應

安裝變成雙頭：PATH 上殘留的舊執行檔在動新的設定。把舊的找出來刪掉。

macOS 上過一陣子就無聲停擺

這個最難查，因為完全沒有錯誤訊息。Power Nap 或維護睡眠期間 Wi-Fi 斷了又回來，卡在 launchd 的重啟閘門就再也沒起來。三件事要一起做：

升級到高於 2026.5.26 的版本
sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0
架一個外部 watchdog——別讓你只能靠「它安靜了」來察覺

Docker 建置以 `exit 137` 結束

記憶體不足。請在 2GB 以上的主機建置。

Raspberry Pi

Pi 5，或 RAM 2GB 以上的 Pi 4，並使用 64 位元系統。文件寫明 Pi Zero 2 W（512MB）不建議。

安全性預設值

openclaw 的文件在這一段寫得相當坦白，在你把任何東西對外開放之前值得讀一遍。

Gateway 預設只有一位可信任的操作者。原文是：它「並不是讓多個彼此敵對的使用者共用同一個 agent 或 gateway 的安全邊界」。如果你原本打算把一個 gateway 開放給一群人用，那超出了它的設計範圍。

Prompt injection 被明列為尚未解決。文件寫著系統提示的護欄只是「軟性指引；真正的強制來自工具政策、執行核准、沙箱與頻道白名單」，並且「威脅來自內容本身，不只是寄件者」——agent 讀到的網頁、郵件、附件全都算。

預設值偏保守，建議就這樣放著。dmPolicy: "pairing" 之下，陌生寄件者的訊息不會被處理，只會收到一組配對碼（一小時後失效）。

openclaw security audit --deep

如果「單人使用」這個形狀不合用

上面全部都建立在 openclaw 的前提之上：一個人、一個 gateway、一個住在你原本就在用的通訊軟體裡的 agent。這是好設計，很多情況下也是對的選擇。

開始不合用，通常是在你想把多個人和多個 agent放進同一個地方的時候。那個通訊軟體同時要承載人和人之間的對話，而 gateway 的文件自己就寫明它不是使用者之間的邊界。

UFO 是為了第二種情況做的：AI agent 不是你召喚的機器人，而是和人並列的頻道成員；每個 agent 跑在你自己配對過的機器上；另外有 agent 看不到的純人類頻道。相對地也有放棄的東西——UFO 無法自架。openclaw 最擅長的那件事，我們做不到。

出處

本頁內容全部取自 openclaw 官方文件與 GitHub repo，於 2026 年 7 月 30 日以 v2026.7.1 為準查證。官方來源彼此矛盾之處（例如推薦的 Node 版本），本頁不擇一，而是照實寫出矛盾。

與 openclaw 專案沒有任何關聯。內容如有錯誤或過時，請告訴我們，我們會修正。