OpenClaw 快速安裝指南：5 分鐘內完成環境部署

我卡住了——最快脫困的方法是什麼？

使用能看見你電腦的本地 AI agent。這比在 Discord 提問有效得多，因為大多數「卡住」的情況都是本地配置或環境問題，遠端助手沒辦法檢查。

Claude Code: https://www.anthropic.com/claude-code/
OpenAI Codex: https://openai.com/codex/

這些工具可以讀取 repo、執行命令、檢查 log，並幫你修復機器層級的設定（PATH, services, permissions, auth files）。透過 hackable (git) 安裝方式給它們完整的原始碼權限：

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

從這些命令開始（尋求幫助時請分享輸出結果）：

openclaw status
openclaw models status
openclaw doctor

推薦如何安裝與設定 OpenClaw？

Repo 推薦從原始碼執行並使用 onboarding 精靈：

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

精靈也會自動建置 UI assets。Onboarding 完成後，你通常會在 port 18789 執行 Gateway。

從原始碼安裝（貢獻者/開發者）：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
openclaw onboard

Onboarding 完成後，如何打開 Dashboard？

精靈現在會在 onboarding 後直接打開你的瀏覽器，並附上帶有 token 的 Dashboard URL，同時也會在摘要中印出完整的連結（含 token）。請保持該分頁開啟；如果沒有自動啟動，請在同一台機器上複製並貼上印出的 URL。

如何在 Localhost 或遠端驗證 Dashboard (Token)？

Localhost（同一台機器）：

打開 http://127.0.0.1:18789/
如果要求驗證，執行 openclaw dashboard 並使用帶有 token 的連結 (?token=...)

非 Localhost：

Tailscale Serve（推薦）：保持 bind loopback，執行 openclaw gateway --tailscale serve
Tailnet bind：執行 openclaw gateway --bind tailnet --token "<token>"
SSH tunnel：ssh -N -L 18789:127.0.0.1:18789 user@host

我需要什麼 Runtime？

需要 Node.js >= 22。推薦使用 pnpm。Gateway 不建議使用 Bun。

它可以在 Raspberry Pi 上執行嗎？

可以。Gateway 非常輕量 —— 文件列出 512MB-1GB RAM、1 核心以及大約 500MB 的磁碟空間，就足以供個人使用。Raspberry Pi 4 跑得動。

如果你想要更多餘裕（處理日誌、媒體或其他服務），建議使用 2GB。

提示：你可以用小型的 Pi 或 VPS 託管 Gateway，然後在你的筆電或手機上配對 nodes，來使用本地螢幕、相機或畫布。

有什麼 Raspberry Pi 安裝的小撇步嗎？

使用 64 位元 作業系統並保持 Node >= 22
優先選擇 hackable (git) 安裝方式，這樣你可以直接看到日誌並快速更新
先不要安裝 channels 或 skills，等跑順了再一個一個加上去
如果你遇到奇怪的二進位檔案問題，通常是 ARM 相容性 的狀況

畫面卡在 “wake up my friend” / onboarding 無法完成，該怎麼辦？

那個畫面取決於 Gateway 是否可以連通且已通過驗證。

重啟 Gateway：
Terminal window
```
openclaw gateway restart
```

檢查狀態與驗證：

openclaw status
openclaw models status
openclaw logs --follow

如果還是卡住，執行：
Terminal window
```
openclaw doctor
```

我可以把設定遷移到新電腦（例如 Mac mini）而不用重新設定嗎？

可以。你只需要複製 state directory 和 workspace，然後執行一次 Doctor 即可：

在新電腦上安裝 OpenClaw
從舊電腦複製 $OPENCLAW_STATE_DIR（預設路徑：~/.openclaw）
複製你的 workspace（預設路徑：~/.openclaw/workspace）
執行 openclaw doctor 並重啟 Gateway 服務

這樣就能保留你的設定、auth profiles、WhatsApp 憑證、sessions 和 memory。

我在哪裡可以看到最新版本的更新內容？

請查看 GitHub 的 changelog：https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

Stable 和 Beta 版本有什麼區別？

Stable 和 beta 是 npm dist-tags，而不是分開的程式碼分支：

latest = stable（穩定版）
beta = 用於測試的早期版本

我們會先將版本發佈到 beta 進行測試，等穩定之後，我們會將同一個版本提升為 latest。

我該如何安裝 Beta 版本？

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta

如果你想安裝可修改的開發版本 (git)：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

安裝和新手引導通常需要多久？

安裝： 2-5 分鐘
新手引導： 5-15 分鐘，取決於你配置了多少個 channel 和 model

安裝程式卡住了？如何獲取更多回饋？

使用 verbose output 重新執行安裝程式：

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

Windows 安裝顯示「git not found」或「openclaw not recognized」

1) npm error spawn git / git not found

安裝 Git for Windows 並確保 git 已加入你的 PATH
關閉並重新開啟 PowerShell，然後重新執行安裝程式

2) 安裝後無法辨識 openclaw

你的 npm global bin 資料夾不在 PATH 中
檢查路徑：npm config get prefix
確保 <prefix>\bin 在 PATH 中

如果你想要最順暢的 Windows 設定體驗，建議使用 WSL2 而不是原生 Windows。

如何在 Linux 上安裝 OpenClaw？

按照 Linux 指南操作，然後執行新手引導精靈：

Linux 快速路徑 + service 安裝：Linux
完整教學：Getting Started

如何在 VPS 上安裝 OpenClaw？

任何 Linux VPS 都可以。在伺服器上安裝後，再透過 SSH 或 Tailscale 連接到 Gateway。

教學指南：Hetzner, Fly.io, exe.dev

我可以叫 OpenClaw 自己更新嗎？

簡單來說：可以，但不建議。更新流程可能會重啟 Gateway（這會導致目前的連線 session 中斷），可能需要乾淨的 git checkout，而且還會跳出確認提示。比較保險的做法是：由操作者直接在 shell 執行更新。

openclaw update
openclaw update status
openclaw update --channel stable|beta|dev

新手引導精靈實際上會做什麼？

openclaw onboard 會引導你完成：

Model/auth 設定（Anthropic setup-token, OpenAI Codex OAuth, API keys, local models）
Workspace 位置與引導檔案
Gateway 設定（bind/port/auth/tailscale）
Providers（WhatsApp, Telegram, Discord, Signal, iMessage）
Daemon 安裝（macOS 使用 LaunchAgent；Linux/WSL2 使用 systemd user unit）
Health checks 與 skills 選擇

我需要訂閱 Claude 或 OpenAI 才能執行嗎？

不需要。你可以使用 API keys（Anthropic/OpenAI 或其他）來執行 OpenClaw，或是使用 local-only models 讓資料留在你的裝置上。訂閱方案只是驗證這些 provider 的其中一種選配方式。

我可以在沒有 API key 的情況下使用 Claude Max 訂閱嗎？

可以。你可以使用 setup-token 代替 API key 來進行驗證。這就是訂閱方案的使用路徑。

Anthropic 的 setup-token 驗證是如何運作的？

claude setup-token 會透過 Claude Code CLI 產生一串 token 字串（這在網頁版 Console 是找不到的）。你可以在任何機器上執行這個指令。在設定精靈中選擇 Anthropic token (paste setup-token)，或是直接執行以下指令貼上：

openclaw models auth paste-token --provider anthropic

我在哪裡可以找到 Anthropic setup-token？

它不在 Anthropic Console 裡面。setup-token 是由 Claude Code CLI 產生的：

claude setup-token

複製指令輸出的 token，然後在設定精靈中選擇 Anthropic token (paste setup-token)。

為什麼我會看到 Anthropic 傳回 `HTTP 429: rate_limit_error`？

這代表你的 Anthropic 配額或速率限制 (rate limit) 在目前的時間視窗內已經耗盡了。如果你使用的是 Claude 訂閱，請等待重置或考慮升級方案。如果你使用的是 Anthropic API key，請到 Anthropic Console 檢查你的用量與帳單狀態。

小撇步：你可以設定 fallback model，這樣當某個供應商遇到 rate limit 時，OpenClaw 依然能保持運作。

是否支援 AWS Bedrock？

支援。你可以透過 pi-ai 的 Amazon Bedrock (Converse) provider 進行 manual config。你必須在 Gateway 主機上提供 AWS 憑證與 region，並在你的 models 設定中新增一個 Bedrock provider 項目。

Codex 的驗證機制如何運作？

OpenClaw 透過 OAuth (ChatGPT 登入) 支援 OpenAI Code (Codex)。設定精靈可以執行 OAuth 流程，並在合適的時候將預設模型設定為 openai-codex/gpt-5.2。

如何設定 Gemini CLI OAuth？

Gemini CLI 使用 plugin auth flow：

openclaw plugins enable google-gemini-cli-auth
openclaw models auth login --provider google-gemini-cli --set-default

本地模型適合用來進行一般對話嗎？

通常不建議。OpenClaw 需要大的 context 與強大的安全性；小模型容易發生截斷或洩漏。如果你一定要這麼做，請在本地（LM Studio）執行你能跑得動的最大 MiniMax M2.1 版本。

強烈警告：較小或經過量化的模型會增加 prompt-injection 的風險。

我一定要買 Mac Mini 才能安裝嗎？

不用。OpenClaw 可以跑在 macOS 或 Linux（Windows 的話可以用 WSL2）。Mac mini 只是其中一個選項 —— 有些人會買一台來當作全天候運作的主機，但用小型 VPS、家用伺服器或 Raspberry Pi 等級的小盒子也沒問題。

你只有在需要 macOS 專屬工具時才需要 Mac。如果是為了 iMessage，建議使用 BlueBubbles。

我需要 Mac mini 才能支援 iMessage 嗎？

你需要 一台登入了 Messages 的 macOS 裝置。它不一定要是 Mac mini —— 任何 Mac 都可以。建議使用 BlueBubbles 來處理 iMessage。

我可以使用 Bun 嗎？

不建議使用 Bun。我們發現它會出現 runtime 的 bug，特別是在處理 WhatsApp 和 Telegram 的時候。為了確保 Gateway 穩定，請使用 Node。

Telegram：`allowFrom` 該填什麼？

channels.telegram.allowFrom 填的是發送訊息者的 Telegram 使用者 ID（建議使用數字 ID）或是 @username。這不是機器人的使用者名稱。

尋找你 ID 的方法：

私訊你的機器人，然後執行 openclaw logs --follow 並查看 from.id
呼叫 https://api.telegram.org/bot<bot_token>/getUpdates 並查看 message.from.id

多人可以透過不同的 OpenClaw 實例共用同一個 WhatsApp 號碼嗎？

可以，透過 multi-agent routing 就能做到。將每個傳送者的 WhatsApp DM 綁定到不同的 agentId，這樣每個人都會有自己獨立的 workspace 和 session store。

我可以同時執行「快速聊天」agent 和「Opus 寫程式」agent 嗎？

沒問題。使用 multi-agent routing：為每個 agent 設定各自的預設模型，然後將 inbound routes 綁定到對應的 agent 即可。

可修改的 (git) 安裝與 npm 安裝有什麼區別？

Hackable (git) install： 完整的原始碼檢出（checkout），可以隨意修改，最適合貢獻者。你在本地執行 build，並可以自行修補程式碼或文件。
npm install： 全域 CLI 安裝，不需要 repo，最適合「只想直接執行」的人。更新會透過 npm dist-tags 發佈。

之後可以切換 npm 和 git 安裝嗎？

可以。安裝另一種版本後，執行 Doctor 讓 Gateway 服務指向新的進入點（entrypoint）。這 不會刪除你的資料 —— 它只會更改 OpenClaw 程式碼的安裝方式。

我應該在筆電還是 VPS 上執行 Gateway？

如果你想要 24/7 的可靠性，請使用 VPS。 如果你追求最低的操作門檻，而且不介意電腦休眠或重啟，在本地執行也可以。

筆電 (本地 Gateway)

優點：沒有伺服器成本、直接存取本地檔案
缺點：休眠或網路斷線會導致斷連、系統更新或重啟會中斷執行

VPS / 雲端

優點：全天候在線、網路環境穩定
缺點：通常以 headless 模式執行（需透過螢幕截圖查看）、只能遠端存取檔案

在專用機器上執行 OpenClaw 有多重要？

這不是強制要求的，但為了可靠性和環境隔離，我建議這麼做。

專用主機 (VPS/Mac mini/Pi)： 全天候在線，遇到的干擾更少
共用筆電/桌機： 用於測試或在電腦前主動使用時完全沒問題

VPS 的最低配置要求和推薦作業系統是什麼？

OpenClaw 非常輕量：

絕對最低要求： 1 vCPU 與 1GB RAM
推薦配置： 1-2 vCPU, 2GB RAM 或更多

作業系統：請使用 Ubuntu LTS（或任何現代的 Debian/Ubuntu 版本）。

我可以在 VM 中執行 OpenClaw 嗎？要求是什麼？

可以。把 VM 視同 VPS 即可：它需要保持開啟、可被連線，並為 Gateway 和你啟用的任何 channel 提供充足的 RAM。

絕對最低要求： 1 vCPU, 1GB RAM
推薦配置： 2GB RAM 或更多

如果你使用 Windows，WSL2 是最簡單的 VM 風格設定方式。

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。