OpenClaw OpenClaw
← 返回首頁
Docker Docker Compose OpenClaw 容器化部署

OpenClaw Docker 安裝教學 完整容器化部署指南

使用 Docker Compose 部署 OpenClaw AI 助手，隔離主機環境，一鍵啟動，適合有 Linux 伺服器的進階用戶。

閱讀時間 約 20 分鐘 2026 年 4 月更新 Linux / macOS

前置準備

軟體要求：確保伺服器上已安裝 Docker 和 Docker Compose：

Shell
# 檢查 Docker 版本
docker --version

# 檢查 Docker Compose 版本
docker compose version

提示

如果尚未安裝，可以參考 Docker 官方安裝指南。

Step 1

建立目錄結構

Bash
# 建立主目錄
mkdir -p /data/openclaw

# 建立 OpenClaw 配置和工作區目錄
mkdir -p /data/openclaw/.openclaw/workspace

# 設定正確的所有權
# UID 1000 是容器內 node 用戶的 UID，確保容器有讀寫權限
sudo chown -R 1000:1000 /data/openclaw/.openclaw

為什麼是 1000:1000？

OpenClaw 官方映像使用 node 用戶運行（UID 1000）。如果宿主機目錄權限不匹配，容器內將無法寫入配置，導致啟動失敗。

Step 2

產生 Token

Bash
# 產生 256 位（32 位元組）隨機 token
openssl rand -hex 32
# 範例輸出: a1b2c3d4e5f6...
Step 3

建立環境變數檔案

Bash
cat > /data/openclaw/.env <<'EOF'
# ========================================
# 映像配置
# ========================================
OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest

# ========================================
# 安全配置
# ========================================
# Gateway 認證 Token，請替換為步驟 2 產生的值
OPENCLAW_GATEWAY_TOKEN=<你的隨機token>

# Gateway 綁定模式
# - lan: 監聽所有區域網路介面（0.0.0.0）
# - local: 僅監聽本地回環（127.0.0.1）
OPENCLAW_GATEWAY_BIND=lan

# ========================================
# 時區配置
# ========================================
OPENCLAW_TZ=Asia/Taipei

# ========================================
# 目錄配置
# ========================================
# 配置檔案儲存目錄
OPENCLAW_CONFIG_DIR=/data/openclaw/.openclaw
# Agent 工作區目錄
OPENCLAW_WORKSPACE_DIR=/data/openclaw/.openclaw/workspace

# ========================================
# 連接埠配置
# ========================================
# Gateway WebSocket 連接埠
OPENCLAW_GATEWAY_PORT=18789
# Bridge Server 連接埠
OPENCLAW_BRIDGE_PORT=18790
EOF
Step 4

建立 Docker Compose 配置檔

YAML
cat > /data/openclaw/docker-compose.yml <<'EOF'
services:
# ========================================
# Gateway 服務
# ========================================
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE}
    container_name: openclaw-gateway
    environment:
      HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
      TZ: ${OPENCLAW_TZ:-UTC}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
    init: true
    restart: unless-stopped
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND:-lan}",
        "--port",
        "18789",
      ]
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))",
        ]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s

# ========================================
# CLI 管理容器
# ========================================
  openclaw-cli:
    image: ${OPENCLAW_IMAGE}
    container_name: openclaw-cli
    network_mode: "service:openclaw-gateway"
    cap_drop:
      - NET_RAW
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true
    environment:
      HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
      BROWSER: echo
      TZ: ${OPENCLAW_TZ:-UTC}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    stdin_open: true
    tty: true
    init: true
    entrypoint: ["node", "dist/index.js"]
    depends_on:
      - openclaw-gateway
EOF
Step 5

初始化配置

Bash
cd /data/openclaw

# 運行初始化精靈
docker compose run --rm openclaw-cli onboard

5.1　配置 allowedOrigins

提示

由於使用了 OPENCLAW_GATEWAY_BIND=lan，需要在配置檔中明確允許的存取來源（CORS）。

Bash
# 使用文字編輯器修改配置檔
vim /data/openclaw/.openclaw/openclaw.json

在 gateway 配置中添加：

JSON
{
  "gateway": {
    "controlUi": {
      "allowedOrigins": ["http://127.0.0.1:18789"]
    }
  }
}
Step 6

啟動服務

Bash
# 啟動 Gateway 服務
docker compose up -d openclaw-gateway

# 查看服務狀態
docker compose ps

# 查看日誌（如果啟動失敗）
docker compose logs -f openclaw-gateway
Step 7

配置 SSH 隧道與控制面板存取

7.1　建立 SSH 隧道

Bash
# 基本語法
ssh -N -L 本地連接埠:目標主機:目標連接埠 用戶名@伺服器IP

# 範例：將本地 18789 連接埠轉發到伺服器的 127.0.0.1:18789
ssh -N -L 18789:127.0.0.1:18789 用戶名@伺服器IP

SSH 參數說明

參數 說明
-N 不執行遠端命令，僅做連接埠轉發
-L 本地連接埠轉發
18789:127.0.0.1:18789 本地連接埠:遠端主機:遠端連接埠

使用金鑰認證（推薦）：

Bash
ssh -N -i ~/.ssh/your_key -L 18789:127.0.0.1:18789 用戶名@伺服器IP

7.2　存取控制面板

提示

SSH 隧道建立後，在本地瀏覽器開啟：http://127.0.0.1:18789，輸入之前產生的 OPENCLAW_GATEWAY_TOKEN 登入。

7.3　設備配對

注意

首次登入時，會遇到 pairing required 錯誤。這是 OpenClaw 的安全機制，需要手動批准連線請求。

Bash
# 查看待處理的配對請求
docker compose exec openclaw-gateway openclaw devices list

# 批准最新的待處理請求
docker compose exec openclaw-gateway openclaw devices approve --latest

設備管理命令

命令 作用
devices list 列出所有待處理和已配對的設備
devices approve <id> 批准特定的配對請求
devices approve --latest 批准最新的待處理請求
devices remove <id> 移除已配對的設備
devices clear --yes 清除所有配對（危險！）

提示

批准後，重新整理瀏覽器即可正常登入控制面板。

← 返回首頁