Skip to content
• Anonymous

OpenClaw 完整建置指南：從安裝到進階設定一次掌握

本指南將帶您從零開始完成 OpenClaw 的安裝與設定。涵蓋 Windows/Mac/Linux 安裝、Onboarding 精靈、Gateway 管理、頻道整合，以及 Google Antigravity Auth 外掛的完整配置流程。

#OpenClaw #DevOps #AI Gateway #Tutorial #Google Antigravity

OpenClaw 是一個強大的 AI Gateway 管理工具，能夠協助開發者快速部署、監控與管理模型服務。無論您是想在本地端快速測試，或是部署到生產環境作為多通路訊息中樞，本文都將帶您一步步完成從安裝到進階配置的完整流程。

1. 環境準備 (Prerequisites)

在安裝 OpenClaw 之前，請確認您的系統已具備以下條件：

必要條件

項目版本需求
Node.js22 或更高版本
pnpm建議安裝（從原始碼建置時必須）

檢查 Node.js 版本：

node --version

可選項目

  • Docker：若您希望以容器化方式運行或執行端對端測試，可選擇安裝 Docker。

2. 安裝 OpenClaw (Installation)

OpenClaw 提供了方便的自動化安裝腳本，請根據您的作業系統選擇對應的指令。

Windows (PowerShell)

請以系統管理員身分執行 PowerShell：

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

macOS / Linux

開啟終端機執行：

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

3. Onboarding 精靈 (Onboarding Wizard)

安裝完成後，執行 Onboarding 精靈將自動引導您完成初始設定。這是最推薦的起步方式。

啟動精靈並安裝 Daemon

openclaw onboard --install-daemon

此指令會完成以下任務：

  1. 模型/認證配置：設定 Anthropic API Key、OAuth 或其他提供者，並選擇預設模型。
  2. Workspace 設定：建立代理檔案的存放位置（預設為 ~/.openclaw/workspace）。
  3. Gateway 設定：配置連接埠、綁定位址與認證模式。
  4. 頻道連接：設定 WhatsApp、Telegram、Discord、Slack 等通訊頻道。
  5. Daemon 安裝：在 macOS 安裝 LaunchAgent，在 Linux 安裝 systemd user unit，確保 Gateway 持續運行。
  6. 健康檢查：啟動 Gateway 並驗證運作狀態。
  7. Skills 安裝：安裝推薦的技能模組與可選依賴。

QuickStart vs Advanced 模式

模式特點
QuickStart使用預設值快速完成設定，適合初次使用者
Advanced完整控制每個步驟，適合進階使用者

QuickStart 模式的預設行為：

  • Gateway 連接埠：18789
  • 本地端閘道（loopback）
  • 自動產生認證 Token
  • Tailscale 曝露：關閉
  • Telegram/WhatsApp DM 預設使用 allowlist

新增多個 Agent

若您需要管理多個獨立的 Agent，可以使用：

openclaw agents add <name>

每個 Agent 會有獨立的 workspace，路徑模式為 ~/.openclaw/workspace-<agentId>。

4. Gateway 服務管理

Gateway 是 OpenClaw 的核心服務，負責處理所有訊息路由與模型調用。

檢查 Gateway 狀態

openclaw gateway status

重啟 Gateway

當您修改了設定檔或安裝了新外掛後，需要重啟 Gateway 讓變更生效：

openclaw gateway restart

在前景運行 Gateway

若需要觀察詳細日誌或除錯，可以在前景模式運行：

openclaw gateway --port 18789

開啟控制儀表板

OpenClaw 提供了一個本地端的 Web 介面 (Control UI)，讓您可視化管理路由與服務：

openclaw dashboard

儀表板預設網址為 http://127.0.0.1:18789/

5. 環境診斷與修復 (Diagnosis & Fix)

當遇到服務不穩或不明錯誤時，OpenClaw 內建了強大的診斷工具。

執行全面診斷

doctor 指令會掃描系統環境、相依套件以及設定檔路徑：

openclaw doctor

自動修復問題

若診斷結果顯示有可自動修復的錯誤（如權限問題或遺失的設定檔），加上 --fix 參數即可：

openclaw doctor --fix

快速健康檢查

如果您只需要確認 API 服務是否存活，可以使用更輕量的 health 指令：

openclaw health

6. 設定 Google Antigravity 認證

若您需要使用 Google Antigravity 模型服務，需要進行額外的組態設定與外掛啟用。

第一步：設定 Google 組態

初始化或更新 Google Cloud 相關的設定（如 Project ID、Region 等）：

openclaw configure google

第二步：啟用 Antigravity Auth 外掛

為了與 Google Antigravity 整合，必須啟用專用的認證外掛：

openclaw plugins enable google-antigravity-auth

第三步：登入認證

最後，使用指定的提供者 (provider) 進行登入，取得模型調用的存取權杖：

openclaw models auth login --provider google-antigravity

7. 通訊頻道整合 (Channels)

OpenClaw 支援多種通訊頻道，讓您的 AI Agent 能透過不同平台與使用者互動。

內建支援頻道

頻道說明
WhatsApp最熱門的整合，使用 Baileys 函式庫，需要 QR 碼配對
Telegram透過 grammY 函式庫的 Bot API，支援群組
DiscordDiscord Bot API + Gateway，支援伺服器、頻道與私訊
Slack使用 Bolt SDK，支援 Workspace 應用程式
Google Chat透過 HTTP webhook 的 Google Chat API 應用程式
Signal使用 signal-cli，注重隱私的選項
BlueBubbles推薦的 iMessage 整合，使用 BlueBubbles macOS 伺服器 REST API
WebChatGateway 內建的 WebSocket 聊天介面

外掛頻道（需另外安裝）

  • Feishu / Lark
  • Mattermost
  • Microsoft Teams
  • LINE
  • Nextcloud Talk
  • Matrix
  • Nostr
  • Tlon (Urbit)
  • Twitch
  • Zalo

連接頻道

使用以下指令登入並連接頻道：

openclaw channels login

8. 裝置管理與配對審核 (Devices & Pairing)

為了確保安全性，OpenClaw 採用了嚴格的審核機制。當新的裝置（如 Mac App）或通訊頻道使用者嘗試連接時，您需要手動進行審核。

裝置審核 (Devices)

當您首次從桌面應用程式連接到自建的 Gateway 時，Gateway 會收到一個連線請求。

  • 列出連線裝置：查看目前嘗試連接或已連線的裝置清單及其 Device ID。

    openclaw devices list

  • 核准裝置：使用清單中的 ID 核准該裝置連線。

    openclaw devices approve <device-id>

頻道配對審核 (Pairing)

在某些頻道（如 Telegram 或 WhatsApp）中，當陌生人傳送訊息給 Agent 時，系統會要求配對碼。

  • 核准配對：當使用者在通訊軟體上取得配對碼後，您可以在終端機執行： 
    openclaw pairing approve <channel> <code>
    例如：openclaw pairing approve telegram 123456。這會將該使用者加入白名單中。

9. 重要檔案與目錄結構

了解 OpenClaw 的檔案結構有助於進階配置與故障排除。

主要目錄

路徑用途
~/.openclaw/openclaw.json主要設定檔（JSON/JSON5 格式）
~/.openclaw/workspaceAgent 工作區（skills、prompts、memories）

憑證存放位置

項目路徑
WhatsApp~/.openclaw/credentials/whatsapp/<accountId>/creds.json
Telegram Bot Token設定檔或 channels.telegram.tokenFile
Discord Bot Token環境變數
Slack Tokens環境變數（channels.slack.*）
配對白名單~/.openclaw/credentials/<channel>-allowFrom.json
模型認證檔~/.openclaw/agents/<agentId>/agent/auth-profiles.json

建議：將 ~/.openclaw/workspace 目錄設為私人 Git 儲存庫，方便版本控制與備份。

10. Linux systemd 服務設定

若您在 Linux 環境運行 OpenClaw，可以使用 systemd 來管理 Gateway 服務。

啟用使用者服務持久化

確保 Gateway 在使用者未登入時仍能運行：

sudo loginctl enable-linger $USER

Onboarding 精靈會自動建立 systemd user unit，您也可以手動檢查：

systemctl --user status openclaw-gateway

11. 更新 OpenClaw（不破壞現有設定）

為了讓更新過程更順利，請遵循以下原則：

  1. 保持個人設定獨立：將您的自訂 prompts 與設定放在 ~/.openclaw/ 目錄，而非 openclaw 專案目錄內。

  2. 從原始碼更新：

    git pull
pnpm install  # 當 lockfile 變更時

  3. 持續使用開發模式（若從原始碼運行）：

    pnpm gateway:watch

常用指令速查表

情境指令
環境診斷openclaw doctor
自動修復openclaw doctor --fix
健康檢查openclaw health
重啟 Gatewayopenclaw gateway restart
檢查狀態openclaw gateway status
開啟儀表板openclaw dashboard
啟用外掛openclaw plugins enable <plugin-name>
模型認證openclaw models auth login --provider <provider>
模型列表openclaw model list
模型設定openclaw model set <model-name>
裝置列表openclaw devices list
核准裝置openclaw devices approve <device-id>
核准配對openclaw pairing approve <channel> <code>
頻道登入openclaw channels login
新增 Agentopenclaw agents add <name>

延伸閱讀

結語

至此，您已經完成 OpenClaw 從安裝到進階配置的完整學習。無論是本地開發測試，或是部署為生產環境的 AI Gateway，OpenClaw 都提供了靈活且強大的工具集。

建議您定期使用 openclaw doctor 檢查環境健康度，並善用 openclaw dashboard 來監控請求流量與效能。如果在使用過程中遇到問題，社群與官方文件都是極佳的求助資源。

祝您開發順利！🚀