Docker 安裝 OpenClaw 完整教學 2026：容器化部署零環境衝突，Windows / macOS / Linux 一鍵啟動
本文重點：本文完整介紹如何使用 Docker Desktop 和 Docker Compose 在 Windows、macOS、Linux 三大平台安裝 OpenClaw AI 智能體。容器化方案是目前最推薦的部署方式，能徹底解決 Node.js 版本衝突、環境污染等問題，升級和備份也更方便。所有平台操作一致，學一次全通用。
為什麼用 Docker 安裝 OpenClaw？
零環境衝突
Node.js 版本、npm 依賴全部隔離在容器內，不影響系統其他應用程式，告別「我的電腦上可以跑」的問題。
一鍵升級備份
更新只需 docker compose pull && docker compose up -d，配置資料透過 Volume 持久化，重建容器不丟資料。
跨平台一致
Windows、macOS、Linux 操作完全一致，同一份 docker-compose.yml 可以直接在所有機器上執行。
系統需求與前置準備
硬體需求（最低）
- ✓ RAM：2 GB（建議 4 GB）
- ✓ 磁碟：20 GB 可用空間
- ✓ CPU：雙核心以上
- ✓ 網路：穩定寬頻連線
作業系統支援
- ● Windows 10/11（64-bit）+ WSL2
- ● macOS 12 Monterey 以上
- ● Ubuntu 20.04/22.04/24.04
- ● Debian 11/12、CentOS Stream 9
Step 1：安裝 Docker Desktop
Windows 10/11 安裝 Docker Desktop
- 1. 前往 docker.com 下載 Docker Desktop for Windows（建議選 Intel/AMD 版）
- 2. 執行安裝程式，安裝時勾選「Use WSL 2 instead of Hyper-V」
- 3. 安裝完成後重新開機，啟動 Docker Desktop
- 4. 在系統列右下角看到 Docker 鯨魚圖示，表示啟動成功
# 在 PowerShell 或 Windows Terminal 中驗證
docker --version
docker compose version
# 預期輸出：Docker version 27.x.x、Docker Compose version v2.x.x
macOS 安裝 Docker Desktop
- 1. 到 docker.com 下載，M 系列晶片選 Apple Silicon 版，Intel Mac 選 Intel 版
- 2. 拖曳 Docker.app 到 Applications 資料夾
- 3. 第一次啟動需授權 Privileged Helper，輸入管理員密碼
- 4. 頂部選單列出現鯨魚圖示代表 Docker 正在運行
# 也可用 Homebrew 安裝
brew install --cask docker
# 驗證
docker run hello-world
Linux（Ubuntu/Debian）安裝 Docker Engine
Linux 伺服器建議安裝 Docker Engine（不需要 Desktop GUI）：
# Ubuntu / Debian 一鍵安裝腳本
curl -fsSL https://get.docker.com | sh
# 將目前用戶加入 docker 群組（避免每次都要 sudo）
sudo usermod -aG docker $USER
newgrp docker
# 驗證安裝
docker run hello-world
Step 2：準備 OpenClaw Docker Compose 配置
OpenClaw 官方提供了 Docker 部署方案，透過 docker-setup.sh 腳本或手動建立 docker-compose.yml 均可完成部署。
方法 A：使用官方一鍵腳本（macOS / Linux / WSL2）
# 下載並執行官方 Docker 設定腳本
curl -fsSL https://openclaw.ai/install.sh | bash --docker
# 或者先下載再執行（建議新手這樣做，可以先看腳本內容）
curl -fsSL https://openclaw.ai/install.sh -o install.sh
cat install.sh # 先檢查腳本內容
bash install.sh --docker
方法 B：手動建立 docker-compose.yml（全平台通用）
建立一個工作目錄，例如 ~/openclaw-docker，在裡面建立以下設定檔：
# mkdir ~/openclaw-docker && cd ~/openclaw-docker
# nano docker-compose.yml（或用任何編輯器）
version: '3.8'
services:
openclaw:
image: openclaw/openclaw:latest
container_name: openclaw
restart: unless-stopped
ports:
- "127.0.0.1:18789:18789"
volumes:
- ~/.openclaw:/root/.openclaw
- ~/clawd:/root/clawd
environment:
- NODE_ENV=production
network_mode: host # 可選：使用主機網路模式
重要：Port 18789 預設只綁定到 127.0.0.1（本機），避免直接暴露在公網。如果需要遠端存取，請搭配 VPN 或反向代理。
Step 3：啟動 OpenClaw 容器
# 進入工作目錄
cd ~/openclaw-docker
# 首次啟動（拉取映像並啟動）
docker compose up -d
# 查看容器運行狀態
docker compose ps
# 查看 OpenClaw 啟動日誌
docker compose logs -f openclaw
# 預期看到類似訊息：
# openclaw | OpenClaw v2026.x.x started
# openclaw | Listening on 127.0.0.1:18789
Step 4：初始化 OpenClaw 設定
容器啟動後，需要進行初始化設定，連結 Claude API 金鑰並設定 AI 模型：
# 進入容器內執行 onboard 設定精靈
docker compose exec openclaw openclaw onboard
# 或者使用一次性容器執行
docker compose run --rm openclaw openclaw onboard
# 設定過程中需要輸入：
# 1. Claude API 金鑰（從 console.anthropic.com 取得）
# 2. 選擇 AI 模型（建議 claude-opus-4-5 或 claude-sonnet）
# 3. 設定 Telegram Bot（可選，方便手機控制）
取得 Claude API 金鑰步驟
- 1. 前往 console.anthropic.com 登入帳號
- 2. 點擊左側「API Keys」→「Create Key」
- 3. 複製金鑰（sk-ant-api... 開頭）儲存好，只顯示一次
- 4. 確保帳號有足夠的 Credits（建議先加值 $5 測試）
台灣用戶注意：Claude API 在台灣需要穩定的境外連線才能正常使用。建議使用 VPN07 開啟後再連線，避免 API 請求失敗或延遲過高。
Step 5：常用容器管理指令
日常操作
# 啟動 / 停止 / 重啟
docker compose start
docker compose stop
docker compose restart
# 查看日誌（即時）
docker compose logs -f
# 進入容器 Shell
docker compose exec openclaw sh
升級更新
# 拉取最新映像並重建
docker compose pull
docker compose up -d --force-recreate
# 清理舊映像
docker image prune -f
# 完整備份設定
cp -r ~/.openclaw ~/.openclaw.bak
cp -r ~/clawd ~/clawd.bak
常見問題排解
❌ 問題：Windows 上 Docker 啟動失敗「WSL 2 installation is incomplete」
# 在 PowerShell（管理員）執行以下指令：
wsl --install
wsl --update
wsl --set-default-version 2
# 重啟電腦後再次啟動 Docker Desktop
❌ 問題：Synology/QNAP NAS 上 UID/GID 權限錯誤
# 先查詢目前用戶 ID
id $(whoami)
# 輸出範例：uid=1026(admin) gid=100(users)
# 在 docker-compose.yml 中加入 user 設定
services:
openclaw:
user: "1026:100" # 替換為實際的 UID:GID
# 修正目錄權限
sudo chown -R 1026:100 ~/.openclaw ~/clawd
⚠️ 問題：容器內無法連線 Claude API（Connection timeout）
這是最常見的問題，尤其在台灣、中國、部分亞洲地區，Claude API 直連不穩定甚至無法使用。
解決方案：在 docker-compose.yml 中加入代理環境變數，搭配 VPN07 使用：
environment:
- HTTP_PROXY=http://host.docker.internal:7890
- HTTPS_PROXY=http://host.docker.internal:7890
- NODE_ENV=production
# host.docker.internal 指向宿主機（Windows/macOS 自動支援）
# Linux 需要加 extra_hosts:
# - "host.docker.internal:host-gateway"
Docker Desktop vs Docker Engine 選哪個？
| 比較項目 | Docker Desktop | Docker Engine |
|---|---|---|
| 適用平台 | Windows、macOS | Linux 伺服器 |
| 圖形介面 | ✓ 有 GUI | ✗ 純命令列 |
| 資源佔用 | 較高（含 VM） | 低（原生） |
| 安裝難度 | 簡單 | 需要指令 |
| 推薦對象 | 個人開發者 | 伺服器/NAS |
進階：遠端存取 Docker 中的 OpenClaw
預設情況下，OpenClaw 的 Web 介面只能從本機（127.0.0.1）存取。如果想從手機或其他裝置存取，有以下幾種安全方案：
方案一：SSH 通道（最安全）
ssh -L 18789:localhost:18789 user@your-server-ip
在本地瀏覽器輸入 http://localhost:18789 即可存取遠端 OpenClaw
方案二：搭配 VPN07 遠端存取（台灣用戶推薦）
開啟 VPN07 後，透過 VPN 內網 IP 直接存取 OpenClaw，同時解決 Claude API 連線問題，一舉兩得。VPN07 提供 1000Mbps 千兆頻寬，讓 AI 智能體任務執行不卡頓。
Docker 跑 OpenClaw？VPN07 解決所有連線問題
運營十年老品牌 · 國際 VPN 市場領導者
OpenClaw 容器化部署後，最大挑戰是穩定存取 Claude API。VPN07 提供 1000Mbps 千兆頻寬，70+ 國家節點，讓你的 Docker 容器暢通無阻，AI 任務零延遲執行。