尚未安裝 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
Key Findings
  • OpenClaw Gateway 預設監聽 Port 18789，透過 WebSocket 協定在 ws://127.0.0.1:18789 提供服務[1]
  • Gateway 的所有狀態管理都可透過 CLI 完成：openclaw gateway status、openclaw gateway restart、openclaw gateway install --force[2]
  • 非本機存取（Remote 模式）必須配置 Token 認證，否則會觸發 refusing to bind gateway without auth 錯誤[3]
  • 根據 CrowdStrike 調查，網路上有超過 42,000 個公開暴露的 OpenClaw 實例，93.4% 存在認證繞過漏洞——Token 管理至關重要[6]

一、Gateway 是什麼？一分鐘搞懂

如果你在搜尋「openclaw gateway」或「openclaw gateway start」，你大概已經安裝了 OpenClaw，但對 Gateway 的角色還有點模糊。簡單來說：Gateway 是 OpenClaw 的控制中心——它負責接收來自各通訊平台（Telegram、LINE、Discord 等）的訊息、分派給 AI 代理處理、管理所有連線與認證[1]。

MIT Technology Review 在 2025 年初將 AI Agent 定義為「能夠自主執行多步驟任務的 AI 系統」[9]。OpenClaw 的 Gateway 就是讓這種自主性得以運作的基礎設施：沒有 Gateway，代理無法接收指令、無法連接外部服務、也無法持久運行。

你可以把 Gateway 想成一台「AI 代理的總機」——所有訊息進來都先經過它，它決定該交給哪個代理處理、用哪個 AI 模型、套用哪些安全規則。

二、Gateway 命令完整速查表

以下是你日常操作最常用的 Gateway CLI 指令。建議收藏本頁——根據 OpenClaw 官方文件[2]，這些指令涵蓋了 95% 以上的 Gateway 管理場景。

2.1 狀態查詢

指令功能說明
openclaw gateway status查看 Gateway 運行狀態顯示 Runtime 狀態（running/stopped）、Port、PID
openclaw gateway status --jsonJSON 格式輸出適合腳本自動化解析
openclaw gateway status --deep深度健康檢查額外檢查 WebSocket 連線、Channel 狀態
openclaw status整體狀態概覽同時顯示 Gateway、Node、Channel 狀態
openclaw status --deep完整深度診斷所有元件的詳細健康報告
openclaw health健康端點檢查快速確認 Gateway 是否回應

2.2 啟動與停止

指令功能說明
openclaw gateway --port 18789前景啟動 Gateway預設 Port 18789，適合除錯（Ctrl+C 停止）
openclaw gateway install --force安裝/重裝系統服務設定 systemd（Linux）或 launchd（macOS）背景服務
openclaw gateway restart重啟 Gateway 服務套用設定變更後常用

注意：OpenClaw Gateway 沒有獨立的 gateway start 或 gateway stop 子命令。啟動方式是直接執行 openclaw gateway（前景）或透過 openclaw gateway install --force 安裝為系統服務自動管理[1]。要停止服務，在 Linux 上使用 systemctl stop openclaw-gateway，macOS 上使用 launchctl unload。

2.3 診斷與除錯

指令功能說明
openclaw doctor自動診斷系統問題檢查設定、權限、連線等常見問題[2]
openclaw doctor --generate-gateway-token產生安全的 Gateway Token自動寫入 openclaw.json
openclaw logs --follow即時串流日誌類似 tail -f，即時觀察 Gateway 運作
openclaw security audit安全性稽核掃描已知安全風險[3]
openclaw security audit --deep深度安全掃描額外檢查認證設定、Token 強度、暴露端口
openclaw security audit --fix自動修復安全問題嘗試自動修正偵測到的安全問題

2.4 設定管理

指令功能範例
openclaw config get <key>讀取設定值openclaw config get gateway.port
openclaw config set <key> <value>修改設定值openclaw config set gateway.port 28789
openclaw config unset <key>移除設定openclaw config unset gateway.auth.token
openclaw configure互動式設定精靈適合初次設定或大幅調整
openclaw onboard --install-daemon完整初始化設定認證、Gateway、Channel 並安裝背景服務[5]

三、Port 設定：解決 90% 的啟動問題

在 GSC 搜尋資料中，「openclaw gateway default port」和「openclaw gateway port」合計超過 2,000 次曝光——這是使用者最常遇到的疑問之一。

3.1 預設 Port：18789

OpenClaw Gateway 的預設 WebSocket 端口是 18789[1]。安裝完成後，Control UI（Dashboard）在 http://127.0.0.1:18789 可以直接存取。

3.2 如何修改 Port

方法一：CLI 修改（推薦）

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

# 確認修改成功
openclaw config get gateway.port

# 重啟服務套用變更
openclaw gateway restart

方法二：直接編輯 openclaw.json

設定檔位於 ~/.openclaw/openclaw.json（JSON5 格式）[1]：

{
  gateway: {
    port: 28789,
    bind: "loopback"
  }
}

方法三：臨時指定 Port（不修改設定檔）

# ★ 前景啟動並指定 Port ★
openclaw gateway --port 28789

3.3 Port 衝突（EADDRINUSE）排解

如果看到 EADDRINUSE 或 another gateway instance is already listening 錯誤[2]，表示 Port 被佔用：

# ★ 找出佔用 Port 18789 的程序 ★
# macOS / Linux
sudo lsof -i :18789

# 終止佔用程序（替換 PID）
kill -9 <PID>

# 或直接換用其他 Port
openclaw config set gateway.port 28789
openclaw gateway restart

四、Token 認證管理

Token 是 Gateway 安全性的核心。CrowdStrike 的研究發現，公開暴露且缺乏認證的 OpenClaw 實例高達 42,000 個[6]，其中 93.4% 存在認證繞過漏洞。The Hacker News 也報導了 CVE-2026-25253 漏洞[8]——攻擊者可透過跨站 WebSocket 劫持取得完整控制權。這讓 Token 管理成為生死攸關的設定。

4.1 產生 Token

# ★ 自動產生並寫入安全的隨機 Token ★
openclaw doctor --generate-gateway-token

# 手動設定 Token
openclaw config set gateway.auth.token "your-long-random-token-here"

# 驗證 Token 已設定
openclaw config get gateway.auth.token

4.2 Gateway 認證模式

OpenClaw 支援三種認證模式[3]：

模式設定值適用場景
Token 認證gateway.auth.mode: "token"推薦。Bearer Token 驗證，適合大部分部署
密碼認證gateway.auth.mode: "password"設定 OPENCLAW_GATEWAY_PASSWORD 環境變數
信任代理gateway.auth.mode: "trusted-proxy"搭配反向代理（Nginx/Caddy）的身分識別

完整 Token 認證設定範例：

{
  gateway: {
    auth: {
      mode: "token",
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

官方文件明確警告：「Gateway HTTP bearer auth 實質上是全權限的操作者存取。將憑證視為完整存取的密鑰來保護。」[3]

4.3 環境變數管理

與其在 openclaw.json 中明文存放 Token，官方建議使用環境變數[1]：

# ★ 在 ~/.openclaw/.env 中設定 ★
OPENCLAW_GATEWAY_TOKEN=your-secure-random-token
OPENCLAW_GATEWAY_PASSWORD=your-backup-password

OpenClaw 的環境變數優先順序：

  1. 父程序的環境變數
  2. 當前目錄的 .env 檔案
  3. ~/.openclaw/.env（全域備援）

五、Local 與 Remote 模式

這是 Gateway 設定中最容易混淆的部分——也是 gateway start blocked 錯誤的頭號元兇[2]。

5.1 Local 模式（預設）

Gateway 只接受本機連線（127.0.0.1），不需要認證：

# ★ 啟用 Local 模式 ★
openclaw config set gateway.mode local
openclaw config set gateway.bind loopback

適合場景：個人開發、單機使用、初學者入門。

5.2 Remote 模式

讓外部設備（手機、其他電腦）連入 Gateway。必須先設定 Token，否則 Gateway 會拒絕啟動[3]：

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

# 設定 Token（必要步驟！）
openclaw doctor --generate-gateway-token

# 綁定到所有網路介面（而非只有 loopback）
openclaw config set gateway.bind 0.0.0.0

# 重啟套用
openclaw gateway restart

安全警告：綁定到 0.0.0.0 代表任何能觸及你機器的裝置都能嘗試連線。官方強烈建議搭配防火牆規則或使用 Tailscale 建立 VPN 隧道[4]。Harvard Business Review 在 2024 年底的文章中指出，AI Agent 的安全部署是企業採用的最大障礙之一[10]——OpenClaw 的 Remote 模式設定正是這個問題的縮影。

5.3 SSH Tunnel（安全遠端存取）

不想把 Gateway 暴露在公網？用 SSH Tunnel 是最安全的方案[4]：

# ★ 建立 SSH Tunnel ★
ssh -N -L 18789:127.0.0.1:18789 user@your-server

# Gateway 保持 loopback 綁定，透過 SSH 轉發安全存取
# 本機可直接存取 http://127.0.0.1:18789

六、常見錯誤速查

以下整理自 OpenClaw 官方疑難排解文件[2]，涵蓋最常見的 Gateway 錯誤訊息與修復方式：

錯誤訊息原因修復方式
Gateway start blocked: set gateway.mode=localLocal 模式未啟用openclaw config set gateway.mode local
refusing to bind gateway without auth非 loopback 綁定但未設定認證設定 gateway.auth.token 或改用 loopback
EADDRINUSE / another gateway instancePort 被佔用lsof -i :18789 找出並終止程序
gateway service missing系統服務未安裝openclaw gateway install --force
AUTH_TOKEN_MISMATCHToken 不符或過期重新生成：openclaw doctor --generate-gateway-token
Runtime: stoppedGateway 已停止運行檢查日誌：openclaw logs --follow 找出停止原因

6.1 標準除錯流程

遇到任何 Gateway 問題，依序執行以下三條指令[2]：

# ★ 標準三步除錯法 ★

# 1. 查看當前狀態
openclaw gateway status

# 2. 看 log 找線索
openclaw logs --follow

# 3. 自動診斷
openclaw doctor

七、openclaw.json 完整設定範例

以下是一份涵蓋所有 Gateway 相關設定的完整 openclaw.json 範例[1]：

{
  // Gateway 核心設定
  gateway: {
    mode: "local",           // "local" 或 "remote"
    port: 18789,             // WebSocket 監聽端口
    bind: "loopback",        // "loopback" 或 "0.0.0.0"

    // 認證（Remote 模式必填）
    auth: {
      mode: "token",         // "token", "password", "trusted-proxy"
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    },

    // 設定檔熱重載
    reload: {
      mode: "hybrid"         // "hybrid", "hot", "restart", "off"
    },

    // Remote 連線（當此機器作為客戶端連到遠端 Gateway）
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "remote-token"
    }
  }
}

八、進階：systemd 服務管理（Linux）

在 Linux 伺服器上，OpenClaw Gateway 通常以 systemd 服務的形式背景運行[4]：

# ★ systemd 服務管理 ★

# 安裝為系統服務
openclaw gateway install --force

# 查看服務狀態
systemctl status openclaw-gateway

# 手動啟動 / 停止 / 重啟
systemctl start openclaw-gateway
systemctl stop openclaw-gateway
systemctl restart openclaw-gateway

# 查看服務日誌
journalctl -u openclaw-gateway -f

九、安全性自查清單

CNBC 報導指出，OpenClaw 的爆紅伴隨著嚴重的安全爭議[7]。以下是 Gateway 上線前的安全檢查清單（基於官方安全文件[3]）：

檢查項目指令期望值
Gateway 認證已設定openclaw config get gateway.auth.modetoken 或 password
綁定位址安全openclaw config get gateway.bindloopback（除非確實需要 Remote）
設定檔權限正確ls -la ~/.openclaw/openclaw.json-rw-------（600）
目錄權限正確ls -ld ~/.openclaw/drwx------（700）
安全稽核通過openclaw security audit --deep無 critical 等級發現
日誌敏感資料已遮蔽openclaw config get logging.redactSensitivetools（預設）

常見問題 FAQ

Q: OpenClaw Gateway 的預設 Port 是什麼？

A: 18789。Control UI 可透過 http://127.0.0.1:18789 存取。如需修改，使用 openclaw config set gateway.port <新 Port>[1]。

Q: 出現「gateway start blocked」怎麼辦？

A: 執行 openclaw config set gateway.mode local 啟用 Local 模式。如果要用 Remote 模式，必須先設定 gateway.auth.token[2]。

Q: 如何安全地從手機遠端控制 OpenClaw？

A: 推薦使用 SSH Tunnel（ssh -N -L 18789:127.0.0.1:18789 user@host）或 Tailscale VPN[4]。避免直接將 Gateway 暴露在公網。

Q: Token 忘記了怎麼辦？

A: 用 openclaw config get gateway.auth.token 查看現有 Token，或執行 openclaw doctor --generate-gateway-token 重新產生[3]。

Q: Gateway 可以同時在多台機器上運行嗎？

A: 官方建議每台主機只運行一個 Gateway 實例。多台機器場景應使用 Remote 模式，讓一台機器當主控、其他機器作為客戶端連入[4]。