尚未安裝 OpenClaw？點此查看一鍵安裝指令
curl -fsSL https://openclaw.ai/install.sh | bash
iwr -useb https://openclaw.ai/install.ps1 | iex
curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
擔心影響電腦？ClawTank 免安裝雲端運行，免除誤刪風險
Key Findings
  • OpenClaw Gateway 是整個代理系統的核心中樞，透過 WebSocket 協議在預設 Port 18789 上運行，負責任務調度、Node 管理與 LLM 請求路由[1]
  • Gateway 提供 Local 與 Remote 兩種運行模式——Local 模式僅綁定 127.0.0.1，適合個人開發；Remote 模式搭配 Token 認證，支援跨裝置與跨網路存取[3]
  • Headless 運行模式結合 systemd 或 Docker 容器化，可在無圖形介面的雲端伺服器上實現 24/7 穩定服務
  • Tailscale 提供零設定的安全 VPN 隧道，免去 Port Forwarding 與動態 DNS 的複雜性，是個人與小團隊遠端存取 Gateway 的最佳選擇[4]
  • Gateway Token 是 Remote 模式下的唯一認證機制，建議啟用自動輪替並搭配 TLS 加密傳輸，確保代理系統不被未授權存取[5]

當你第一次啟動 OpenClaw 教學，系統會自動在本機啟動一個 Gateway 服務。你可能從未意識到它的存在——它安靜地在背景運行，接收你從 CLI 或 Web UI 發送的每一條指令，協調 Node 執行任務，再將結果回傳給你。這個看似透明的元件，其實是整個 OpenClaw 代理架構的神經中樞。[1]

一旦你的需求超越「在自己的筆電上跑幾個任務」——例如你希望從手機遠端觸發代理、在雲端 VPS 上部署 24/7 自動化工作流、或讓團隊成員共享同一個 Gateway 資源——你就需要深入理解 Gateway 的模式切換、部署策略與安全設定。

本文將從 Gateway 的架構角色出發，系統性地覆蓋 Local 與 Remote 兩種模式的設定方式、Headless 雲端部署的完整流程、Tailscale 安全遠端存取、Gateway Token 認證機制，以及生產環境常見問題的排解策略。無論你是剛接觸 OpenClaw 的開發者，還是正在規劃雲端部署的 DevOps 工程師，這篇指南都能提供你所需的技術參考。

一、Gateway 是什麼？在 OpenClaw 架構中的角色

Gateway 是 OpenClaw 代理系統的統一入口點與調度核心。它以 WebSocket 伺服器的形式運行在 Port 18789 上，是所有 Node、Channel 與外部 Client 之間通訊的唯一樞紐。[1]

1.1 Gateway 在四層架構中的定位

OpenClaw 的運行架構由四個層次組成：

  • Gateway 層：系統唯一入口，以 WebSocket 伺服器形式運行在 ws://127.0.0.1:18789，接受所有外部連線並進行路由
  • Node 層：執行Agentic Workflow的處理單元，連接到 Gateway 以接收任務指派
  • Channel 層：定義代理的溝通介面（CLI、Web UI、Telegram Bot、API 等）
  • Skill 層：代理可調用的能力模組（瀏覽器控制、Shell 指令、檔案操作等）

Gateway 在這個架構中承擔的責任遠超「訊息轉發」：它維護任務佇列（Task Queue）進行排程、管理每個 Workspace 的上下文記憶與對話歷史、協調對不同 LLM 提供商的 API 請求（速率限制、金鑰路由），以及處理 Node 的連線生命週期（註冊、心跳、斷線重連）。

1.2 WebSocket 協議與 Port 18789

Gateway 選用 WebSocket 而非傳統 HTTP 作為核心通訊協議，是因為 AI 代理的工作流本質上是雙向且長時間保持連線的——Node 需要即時接收任務指派，Gateway 需要即時取得執行進度與結果。WebSocket 的全雙工特性完美匹配這個需求。[2]

預設 Port 18789 位於 IANA 已登記埠範圍（1024–49151），與常見服務較不易衝突。Gateway 同時在該 Port 上提供 HTTP 端點，用於健康檢查（/health）、狀態查詢（/status）與 REST API 存取。

你可以隨時使用以下指令確認 Gateway 的運行狀態：

# 查看 Gateway 運行狀態
openclaw gateway status

# 預期輸出
# Gateway Status: running
# Mode: local
# Address: ws://127.0.0.1:18789
# Uptime: 2h 15m 32s
# Connected Nodes: 1
# Active Tasks: 0
# Queued Tasks: 0

若 Gateway 未在運行，openclaw gateway status 會回傳 Gateway Status: stopped，你可以手動啟動它：

# 手動啟動 Gateway
openclaw gateway start

# 手動停止 Gateway
openclaw gateway stop

# 重啟 Gateway
openclaw gateway restart

二、Local vs Remote 模式：差異與選擇

OpenClaw Gateway 提供兩種核心運行模式，對應兩種截然不同的使用場景。理解它們的差異是正確部署的第一步。[3]

2.1 Local 模式

綁定地址：127.0.0.1:18789（僅本機回環介面）

Local 模式是安裝後的預設狀態。Gateway 只接受來自同一台機器的連線，外部網路完全無法存取。這是最安全的配置，因為攻擊面被限制在本機作業系統層級。[5]

適用場景：

  • 個人開發與探索——在自己的筆電上體驗 OpenClaw 功能
  • 本地自動化任務——讓代理操作你當前機器上的瀏覽器、檔案系統、終端機
  • 敏感環境——LLM API 金鑰與 Workspace 資料都不會離開本機

局限：

  • 關閉電腦或休眠時，Gateway 中斷，所有進行中的任務失敗
  • 無法從手機、平板或其他裝置發送指令
  • 不支援 Cron Job 觸發的 24/7 自動化工作流（除非機器永不休眠）

2.2 Remote 模式

綁定地址：0.0.0.0:18789（所有網路介面）或指定介面

Remote 模式允許來自任何網路的連線。啟用後，Gateway 會要求設定 Token 認證，防止未授權存取。[4]

適用場景：

  • 跨裝置存取——從手機、平板或其他電腦發送指令給桌機上的代理
  • 雲端部署——在 VPS 或雲端虛擬機上運行 24/7 Gateway
  • 團隊共用——多位使用者連接到同一個 Gateway，共享代理資源
  • IoT 與邊緣場景——樹莓派或嵌入式裝置上的 Node 連接到遠端 Gateway

局限：

  • 必須妥善設定 Token 認證，否則任何知道你 IP 的人都能存取你的代理[7]
  • 建議搭配 TLS（HTTPS/WSS）加密傳輸，防止 Token 在網路傳輸中被攔截
  • 需要考慮防火牆、NAT 與網路拓撲等額外的基礎設施複雜度

2.3 模式比較速查表

面向 Local 模式 Remote 模式
綁定地址 127.0.0.1 0.0.0.0 或指定介面
認證要求 無（本機已隔離） Gateway Token 必填
外部存取 不允許 允許（需認證）
TLS 建議 不需要 強烈建議
適用規模 單人單機 多人多裝置
初始設定難度 零設定 中等

三、Local 模式設定

Local 模式是最簡單的起點。如果你是全新安裝 OpenClaw，Gateway 預設就在 Local 模式下運行——你甚至不需要做任何額外設定。[2]

3.1 確認目前模式

# 查看目前 Gateway 模式
openclaw config get gateway.mode

# 預期輸出
# gateway.mode = "local"

3.2 明確設定為 Local 模式

如果你曾經切換過模式，或想要確保目前在 Local 模式下運行：

# 將 Gateway 設定為 Local 模式
openclaw config set gateway.mode local

# 重啟 Gateway 使設定生效
openclaw gateway restart

3.3 驗證 Gateway 監聽地址

設定完成後，確認 Gateway 確實只綁定在本機回環介面：

# 查看 Gateway 狀態
openclaw gateway status

# 用系統工具確認 Port 綁定（macOS / Linux）
lsof -i :18789

# 預期看到綁定在 127.0.0.1:18789
# COMMAND   PID     USER   FD   TYPE  SIZE/OFF NODE NAME
# openclaw  12345   user   8u   IPv4  0t0      TCP  127.0.0.1:18789 (LISTEN)

3.4 自訂 Port

預設 Port 18789 在大多數情況下不會衝突。但如果你的環境中有其他服務佔用了這個 Port，可以修改：

# 修改 Gateway Port
openclaw config set gateway.port 28789

# 重啟後生效
openclaw gateway restart

# 確認新 Port
openclaw gateway status
# Gateway Status: running
# Mode: local
# Address: ws://127.0.0.1:28789

修改 Port 後，所有透過 CLI 互動的操作會自動偵測新的 Port。但如果你使用外部工具（如自訂腳本或 API Client）連接 Gateway，需要同步更新連線地址。

3.5 openclaw.json 中的 Gateway 設定區塊

上述 CLI 指令的效果等同於修改 ~/.openclaw/openclaw.json 中的對應欄位：

// ~/.openclaw/openclaw.json（Gateway 相關設定）
{
  "gateway": {
    "mode": "local",           // "local" 或 "remote"
    "port": 18789,             // Gateway 監聽埠
    "host": "127.0.0.1",       // Local 模式自動設為 127.0.0.1
    "websocket_path": "/ws",   // WebSocket 端點路徑
    "auto_start": true,        // 啟動 OpenClaw 時自動啟動 Gateway
    "log_level": "info"        // 日誌等級：debug, info, warn, error
  }
}

建議：優先使用 openclaw config set CLI 指令修改設定，它會自動處理格式驗證與相依性檢查，避免手動編輯 JSON 時的語法錯誤。[3]

四、Remote 模式設定

Remote 模式是將 OpenClaw Gateway 暴露到網路的關鍵步驟。無論你的目標是跨裝置存取、雲端部署還是團隊協作，都需要經過以下設定流程。[4]

4.1 啟用 Remote 模式

# 切換到 Remote 模式
openclaw config set gateway.mode remote

# 系統會提示你設定 Gateway Token（首次切換時）
# > Remote mode requires a gateway token for authentication.
# > Run 'openclaw doctor --generate-gateway-token' to create one.

4.2 產生並設定 Gateway Token

Gateway Token 是 Remote 模式下的唯一認證憑證。所有連接到 Gateway 的 Client 與 Node 都必須在連線時提供這個 Token。[5]

# 產生新的 Gateway Token
openclaw doctor --generate-gateway-token

# 輸出範例
# Generated gateway token: ogt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
# Token has been saved to your configuration.
#
# To connect from another device, use:
#   openclaw config set gateway.url wss://YOUR_IP:18789/ws
#   openclaw config set gateway.token ogt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

4.3 設定遠端 URL

在需要連接到遠端 Gateway 的客戶端機器上，設定 Gateway 的 URL 與 Token：

# 在遠端客戶端上設定（例如你的手機或另一台電腦）
openclaw config set gateway.url wss://your-server-ip:18789/ws
openclaw config set gateway.token ogt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

# 測試連線
openclaw gateway health
# Gateway healthy: wss://your-server-ip:18789/ws
# Authentication: OK

4.4 雲端部署時的 Remote 設定

若 Gateway 部署在雲端 VPS（如 AWS EC2、GCP Compute Engine、Linode、DigitalOcean），建議搭配反向代理與 TLS：

# 在雲端伺服器上
openclaw config set gateway.mode remote
openclaw config set gateway.host 127.0.0.1    # Gateway 仍綁定本機
openclaw config set gateway.port 18789
openclaw doctor --generate-gateway-token

# 由 Nginx 或 Caddy 在前端處理 TLS 與認證轉發
# 客戶端連線地址為：wss://gateway.yourdomain.com/ws

重要安全原則：即使在 Remote 模式下，也不建議讓 Gateway 直接監聽 0.0.0.0 並暴露在公網。正確的架構是 Gateway 繼續綁定 127.0.0.1，由 Nginx/Caddy 反向代理在前端接受外部 TLS 連線，再透過本機回環轉發至 Gateway。[7]

4.5 完整的 openclaw.json Remote 設定範例

// ~/.openclaw/openclaw.json（Remote 模式完整設定）
{
  "gateway": {
    "mode": "remote",
    "port": 18789,
    "host": "127.0.0.1",
    "websocket_path": "/ws",
    "auto_start": true,
    "log_level": "info",
    "token": "ogt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "allowed_origins": [
      "https://gateway.yourdomain.com",
      "https://app.yourdomain.com"
    ],
    "rate_limit": {
      "enabled": true,
      "max_requests_per_minute": 120,
      "max_connections": 50
    }
  }
}

五、Headless 運行：在無圖形介面環境中部署 Gateway

OpenClaw 的預設啟動流程會嘗試初始化 GUI 元件（系統托盤圖示、通知視窗等）。在沒有桌面環境的 Linux 伺服器或 Docker 容器中，這會導致啟動失敗。Headless 模式跳過所有 GUI 初始化，僅啟動 Gateway 核心服務。[6]

5.1 基本 Headless 啟動

# 方式一：前台運行（推薦用於 screen/tmux）
openclaw gateway run

# 方式二：環境變數
export OPENCLAW_HEADLESS=true
openclaw gateway run

# 方式三：寫入設定檔後啟動
openclaw config set gateway.headless true
openclaw gateway run

5.2 使用 screen/tmux 持久化

在 SSH 連線中啟動的進程會隨 SSH 斷開而終止。最簡單的持久化方案是 screen 或 tmux：

# 使用 screen
screen -S openclaw-gw
OPENCLAW_HEADLESS=true openclaw gateway run
# 按 Ctrl+A 然後按 D 分離
# 之後重新連接：screen -r openclaw-gw

# 使用 tmux（更推薦）
tmux new-session -d -s openclaw -n gateway
tmux send-keys -t openclaw:gateway \
'OPENCLAW_HEADLESS=true openclaw gateway run' Enter

# 新增日誌監控視窗
tmux new-window -t openclaw -n logs
tmux send-keys -t openclaw:logs \
'tail -f ~/.openclaw/logs/gateway.log' Enter

# 重新連接：tmux attach -t openclaw

5.3 systemd 服務設定（生產環境推薦）

對於需要開機自動啟動、自動重啟與系統日誌整合的生產環境，systemd 是標準選擇：

# /etc/systemd/system/openclaw-gateway.service

[Unit]
Description=OpenClaw Gateway Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=openclaw
Group=openclaw
WorkingDirectory=/opt/openclaw
Environment="OPENCLAW_HEADLESS=true"
Environment="OPENCLAW_GATEWAY_HOST=127.0.0.1"
Environment="OPENCLAW_GATEWAY_PORT=18789"
Environment="OPENCLAW_LOG_LEVEL=info"
EnvironmentFile=-/opt/openclaw/.env
ExecStart=/usr/local/bin/openclaw gateway run
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw-gateway

# 安全加固
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/openclaw/data /opt/openclaw/logs

# 資源限制
LimitNOFILE=65536
LimitNPROC=4096

[Install]
WantedBy=multi-user.target
# 建立專用系統使用者
sudo useradd -r -s /usr/sbin/nologin -d /opt/openclaw openclaw
sudo mkdir -p /opt/openclaw/{data,logs,config}
sudo chown -R openclaw:openclaw /opt/openclaw

# 啟用並啟動服務
sudo systemctl daemon-reload
sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway

# 查看狀態與日誌
sudo systemctl status openclaw-gateway
sudo journalctl -u openclaw-gateway -f

5.4 Docker 容器化部署

Docker 提供環境隔離與版本管理的優勢，是雲端部署的主流方案：

# Dockerfile
FROM python:3.11-slim-bookworm

RUN apt-get update && apt-get install -y --no-install-recommends \
curl git ca-certificates && rm -rf /var/lib/apt/lists/*

RUN groupadd -r openclaw && useradd -r -g openclaw -d /app openclaw
WORKDIR /app

RUN pip install --no-cache-dir openclaw

RUN mkdir -p /app/data /app/logs && chown -R openclaw:openclaw /app
USER openclaw

ENV OPENCLAW_HEADLESS=true \
OPENCLAW_GATEWAY_HOST=0.0.0.0 \
OPENCLAW_GATEWAY_PORT=18789 \
OPENCLAW_DATA_DIR=/app/data \
OPENCLAW_LOG_DIR=/app/logs

EXPOSE 18789

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
CMD curl -f http://localhost:18789/health || exit 1

CMD ["openclaw", "gateway", "start", "--headless"]
# docker-compose.yml
version: '3.8'

services:
openclaw-gateway:
  build: .
  container_name: openclaw-gw
  restart: unless-stopped
  env_file:
    - .env.gateway
  volumes:
    - openclaw-data:/app/data
    - openclaw-logs:/app/logs
  expose:
    - "18789"
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
    interval: 30s
    timeout: 10s
    retries: 3

nginx:
  image: nginx:1.25-alpine
  container_name: openclaw-nginx
  restart: unless-stopped
  ports:
    - "443:443"
    - "80:80"
  volumes:
    - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    - /etc/letsencrypt:/etc/letsencrypt:ro
  depends_on:
    openclaw-gateway:
      condition: service_healthy

volumes:
openclaw-data:
openclaw-logs:
# 建置並啟動
docker compose up -d --build

# 查看日誌
docker compose logs -f openclaw-gateway

# 重啟 Gateway
docker compose restart openclaw-gateway

# 進入容器除錯
docker compose exec openclaw-gateway /bin/bash

六、Tailscale 遠端存取：零設定安全 VPN

傳統的遠端存取方式（Port Forwarding、動態 DNS、自簽憑證）對個人開發者來說過於繁瑣，且容易出錯。Tailscale 提供了一個極簡的替代方案：安裝即用的 WireGuard VPN 隧道，讓你的所有裝置彷彿在同一個區域網路中。[4]

6.1 為什麼選擇 Tailscale

  • 零 Port Forwarding：不需要在路由器上開放任何埠，Gateway 可以繼續安全地綁定 127.0.0.1
  • 自動加密：基於 WireGuard 的端對端加密，無需手動設定 TLS
  • NAT 穿透：即使雙方都在 NAT 後面，Tailscale 也能建立直連
  • MagicDNS：每台裝置自動取得 hostname.tailnet-name.ts.net 的 DNS 名稱

6.2 設定流程

# 步驟一：在 Gateway 伺服器上安裝 Tailscale
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# 步驟二：確認 Tailscale IP
tailscale ip -4
# 例如：100.64.0.1

# 步驟三：設定 Gateway 監聽 Tailscale 介面
openclaw config set gateway.mode remote
openclaw config set gateway.host 100.64.0.1
openclaw doctor --generate-gateway-token
openclaw gateway restart

# 步驟四：在客戶端裝置安裝 Tailscale 並連線
# （macOS / Windows / iOS / AndAI ROI 評估d 都支援）
sudo tailscale up

# 步驟五：在客戶端設定 Gateway 連線
openclaw config set gateway.url ws://my-server.tailnet-name.ts.net:18789/ws
openclaw config set gateway.token ogt_your_token_here

# 測試連線
openclaw gateway health

6.3 Tailscale ACL 存取控制

Tailscale 的 ACL（Access Control List）讓你精確控制哪些裝置可以存取 Gateway：

// tailscale ACL policy（在 Tailscale Admin Console 設定）
{
"acls": [
  {
    "action": "accept",
    "src": ["tag:openclaw-client"],
    "dst": ["tag:openclaw-gateway:18789"]
  }
],
"tagOwners": {
  "tag:openclaw-gateway": ["autogroup:admin"],
  "tag:openclaw-client": ["autogroup:admin"]
}
}

6.4 Tailscale Funnel（進階：公開分享）

如果你需要讓沒有安裝 Tailscale 的外部使用者存取你的 Gateway（例如向客戶展示 Demo），可以使用 Tailscale Funnel 暫時公開：

# 暫時將 Gateway 公開到 Internet（自動 HTTPS）
tailscale funnel 18789

# 外部使用者可透過以下地址存取
# https://my-server.tailnet-name.ts.net/

# 關閉 Funnel
tailscale funnel --reset

注意：Funnel 會將你的 Gateway 暴露在公網。即使有 Tailscale 的 HTTPS 加密，也務必確保 Gateway Token 已設定，防止未授權存取。[8]

七、Gateway Token 安全性

Gateway Token 是 Remote 模式下保護你整台電腦的最後一道防線。OpenClaw 代理擁有執行 Shell 指令、操作檔案系統、控制瀏覽器的能力——這意味著任何取得你 Gateway Token 的人，理論上可以對你的機器做任何事。[5][7]

7.1 Token 的產生與格式

# 產生新 Token
openclaw doctor --generate-gateway-token

# Token 格式：ogt_ 前綴 + 32 字元隨機字串
# 例如：ogt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

# 手動指定 Token（不建議，除非有特殊需求）
openclaw config set gateway.token "your-custom-token-here"

7.2 Token 輪替（Rotation）

定期更換 Token 是安全最佳實踐，尤其在以下情境：

  • 團隊成員離職或更換裝置
  • 懷疑 Token 已外洩
  • 定期安全稽核要求（建議每 90 天輪替一次）
# 重新產生 Token（舊 Token 立即失效）
openclaw doctor --generate-gateway-token --force

# 所有已連線的 Client 與 Node 會被強制斷開
# 需要在各客戶端上更新新 Token
openclaw config set gateway.token ogt_new_token_here

7.3 安全最佳實踐

  • 永遠不要將 Token 寫入 Git 倉庫、聊天記錄或郵件。使用環境變數或密碼管理工具傳遞
  • 搭配 TLS：Token 以明文形式在 WebSocket 握手中傳送。如果沒有 TLS，網路上的任何中間節點都可以攔截 Token
  • 限制存取來源：在 openclaw.json 中設定 allowed_origins，只允許特定網域的連線
  • 監控異常連線：定期檢查 Gateway 日誌中的認證失敗記錄，偵測暴力破解嘗試
# 查看最近的認證失敗記錄
openclaw logs --follow --limit 100

# 設定認證失敗鎖定（連續 5 次失敗後封鎖來源 IP 15 分鐘）
openclaw config set gateway.security.max_auth_failures 5
openclaw config set gateway.security.lockout_duration_minutes 15

7.4 環境變數管理 Token

在自動化部署中，Token 應透過環境變數注入，而非寫入設定檔：

# .env.gateway（不要提交到版本控制）
OPENCLAW_GATEWAY_TOKEN=ogt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# 在 systemd 中使用
EnvironmentFile=/opt/openclaw/.env.gateway

# 在 Docker Compose 中使用
env_file:
- .env.gateway

# 確保 .env.gateway 的檔案權限
chmod 600 /opt/openclaw/.env.gateway
chown openclaw:openclaw /opt/openclaw/.env.gateway

八、常見問題與疑難排解

以下整理了部署 OpenClaw Gateway 時最常遇到的問題與解決方案。[3]

8.1 Port 衝突

症狀：Gateway 啟動失敗，日誌顯示 Address already in use: 0.0.0.0:18789

# 檢查誰佔用了 Port 18789
sudo lsof -i :18789
# 或
sudo ss -tlnp | grep 18789

# 常見原因：上一個 Gateway 進程未正常退出
# 解決方案一：終止佔用進程
sudo kill -9 $(lsof -t -i :18789)

# 解決方案二：換用其他 Port
openclaw config set gateway.port 28789
openclaw gateway restart

8.2 Remote 模式連線失敗

症狀：客戶端無法連線到遠端 Gateway，顯示 Connection refused 或 Connection timed out

# 排查步驟一：確認 Gateway 正在運行
openclaw gateway status

# 排查步驟二：確認 Gateway 監聽地址
ss -tlnp | grep 18789
# 若顯示 127.0.0.1:18789，表示 Gateway 只接受本機連線
# 需要搭配反向代理或 Tailscale

# 排查步驟三：確認防火牆規則
sudo ufw status
sudo iptables -L -n | grep 18789

# 排查步驟四：測試網路連通性
# 在客戶端執行
curl -v http://your-server-ip:18789/health
# 或（若使用反向代理）
curl -v https://gateway.yourdomain.com/health

# 排查步驟五：確認 Token 是否正確
openclaw config get gateway.token

8.3 WebSocket 連線中斷

症狀：任務執行中途斷開，日誌顯示 WebSocket connection closed unexpectedly

# 最常見原因：反向代理的 Timeout 設定太短

# Nginx 修正：增加 proxy_read_timeout
# /etc/nginx/conf.d/openclaw.conf
location /ws {
  proxy_pass http://127.0.0.1:18789;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_read_timeout 3600s;    # 至少 1 小時
  proxy_send_timeout 3600s;
  proxy_connect_timeout 30s;
}

# Gateway 端修正：調整心跳間隔
openclaw config set gateway.websocket.ping_interval 30
openclaw config set gateway.websocket.ping_timeout 10

8.4 Headless 啟動失敗

症狀：在無 GUI 伺服器上啟動時顯示 cannot open display 或 Gtk initialization failed

# 使用前台模式運行（無需 GUI）
openclaw gateway run

# 或設定環境變數
export OPENCLAW_HEADLESS=true
export DISPLAY=    # 清除 DISPLAY 變數

# 確認 Node.js 版本（需要 22+）
node --version

# 確認 OpenClaw 已正確安裝
openclaw --version

8.5 Gateway 狀態查詢指令速查

# 完整狀態報告
openclaw gateway status --deep

# JSON 格式輸出（便於腳本處理）
openclaw gateway status --json

# 健康檢查（適合用於監控系統）
openclaw gateway health
curl -s http://127.0.0.1:18789/health | python3 -m json.tool

九、雲端部署架構建議

根據團隊規模與可靠性需求，以下提供三種雲端部署架構的建議。

9.1 個人 / 小型專案：VPS + Caddy

最低成本、最少維護負擔的部署方式。適合個人開發者或 1-3 人小團隊。

# 架構拓撲
[客戶端裝置] --wss--> [Caddy :443] --> [Gateway :18789] --> [LLM APIs]

# Caddyfile（自動 TLS）
gateway.yourdomain.com {
reverse_proxy /ws localhost:18789 {
  header_up Upgrade {http.upgrade}
  header_up Connection "Upgrade"
  transport http {
    read_timeout 1h
    write_timeout 1h
  }
}
reverse_proxy localhost:18789
}

# VPS 建議規格：2 vCPU / 4 GB RAM / 40 GB SSD
# 月成本：約 $5-$20 USD（Linode、DigitalOcean、Vultr）

9.2 中型團隊：Docker Compose + Nginx + 監控

適合 5-20 人團隊，需要正式的監控與日誌基礎設施。

# 架構拓撲
[多個客戶端] --wss--> [Nginx :443]
                          |
                    [Gateway :18789]
                          |
              +-----------+-----------+
              |           |           |
          [Prometheus] [Grafana]  [Loki]

# 部署指令
docker compose -f docker-compose.yml \
-f docker-compose.monitoring.yml up -d

9.3 生產環境 Checklist

在將 Gateway 推送到生產環境之前，請逐項確認：[7][8]

安全

  • Gateway Token 已設定且強度足夠
  • TLS 1.2+ 已啟用（使用 Let's Encrypt 或其他 CA）
  • Gateway 不直接暴露在公網（透過反向代理存取）
  • 防火牆已封鎖 Port 18789 的外部直接存取
  • LLM API 金鑰存儲在環境變數或 Secret Manager 中
  • Gateway 以非 root 使用者運行
  • 定期輪替 Gateway Token（建議每 90 天）

可靠性

  • systemd 或 Docker 設定自動重啟（Restart=always）
  • 健康檢查端點（/health）已配置並接入監控
  • 日誌輸出至持久化存儲（非容器內部）
  • 自動備份 Workspace 資料（每日 + 保留 30 天）

效能

  • Linux 核心調優：net.core.somaxconn = 65535
  • 文件描述符限制：LimitNOFILE=65536
  • WebSocket Timeout 與最長任務時間對齊
  • 反向代理的 Keepalive 與 Buffer 設定已最佳化

資源規劃

規模 並行任務 CPU 記憶體 存儲
個人 1-3 2 vCPU 4 GB 20 GB SSD
小團隊 5-10 4 vCPU 8 GB 50 GB SSD
企業 20+ 8+ vCPU 16+ GB 200 GB NVMe

9.4 自動備份腳本

#!/bin/bash
# /opt/scripts/backup-openclaw.sh
set -euo pipefail

BACKUP_DIR="/backups/openclaw"
DATE=$(date +%Y%m%d-%H%M%S)
RETENTION_DAYS=30

mkdir -p "$BACKUP_DIR"

# 備份 Workspace 資料
tar czf "$BACKUP_DIR/workspace-$DATE.tar.gz" \
/opt/openclaw/data/

# 備份設定（排除敏感的 .env 檔案）
tar czf "$BACKUP_DIR/config-$DATE.tar.gz" \
/opt/openclaw/config/

# 清理舊備份
find "$BACKUP_DIR" -name "*.tar.gz" \
-mtime +$RETENTION_DAYS -delete

echo "[$(date)] Backup completed: workspace-$DATE.tar.gz"
# 加入 Cron 每日凌晨 2 點備份
echo "0 2 * * * /opt/scripts/backup-openclaw.sh >> /var/log/openclaw-backup.log 2>&1" \
| sudo crontab -u openclaw -

結語

OpenClaw Gateway 從 Local 到 Remote 模式的切換，本質上是一個從「個人工具」到「基礎設施」的觀念轉變。在 Local 模式下，Gateway 是你筆電上一個安靜的背景服務；在 Remote 模式下，它成為需要認真對待的網路服務——需要認證、加密、監控、備份與災難恢復計畫。

本文覆蓋的部署路徑可以總結為三個進階階段：

  • 第一階段：Local 模式 + 預設設定 → 零設定即可使用，適合探索與學習
  • 第二階段：Remote 模式 + Tailscale → 跨裝置安全存取，無需複雜的網路設定
  • 第三階段：雲端 VPS + Docker + Nginx/Caddy + TLS → 生產等級的 24/7 部署

選擇哪個階段取決於你的具體需求。一個個人開發者的自動化助手，Tailscale 方案可能就是最佳解；一個服務企業用戶的代理平台，才需要完整的 Docker + 反向代理 + 監控堆疊。[6]

隨著 OpenClaw 社群的持續發展，[2] Gateway 的功能也在快速演進。建議密切關注官方文件中關於叢集協調、多 Gateway 同步與 Zero-Trust 安全模型等新功能的更新——這些將決定 OpenClaw 從個人生產力工具走向企業級 AI 代理平台的關鍵路徑。[1]