為什麼選擇 Docker？
在 Docker 中運行 OpenClaw 相較於裸機安裝提供了三大優勢：
- 1.安全隔離：代理在一個對主機系統存取有限的容器內運行。如果惡意技能或提示注入嘗試存取你的檔案，容器邊界會限制影響範圍。
- 2.可重現性：相同的 Docker 映像在任何機器上都以相同方式運行——你的筆電、VPS 或 Raspberry Pi。
- 3.輕鬆清理：想要重新開始？移除容器然後啟動一個新的。沒有殘留檔案，沒有損壞的 Node.js 安裝。
前置條件
- •Docker Desktop（macOS/Windows）或 Docker Engine（Linux）
- •Docker Compose v2（Docker Desktop 已包含）
- •至少 2 GB 記憶體可供容器使用
- •一個 AI API 金鑰（Anthropic、OpenAI 或其他支援的供應商）
快速開始
選項 A：官方 Docker Compose（推薦）
複製 OpenClaw repository 並使用內建的 Docker 設定：
bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
執行設定腳本，它會建立必要的目錄和配置：
bash
bash docker-setup.sh
- •
~/.openclaw/——配置、SOUL.md、API 金鑰 - •
~/openclaw/workspace/——代理可存取的檔案
在容器內執行初始設定精靈：
bash
docker compose run --rm openclaw-cli onboard
依照提示設定你的 API 金鑰並連接聊天平台。然後啟動閘道器：
bash
docker compose up -d openclaw-gateway
你的代理現在在背景運行了。
選項 B：預建映像
如果你不想複製整個 repository，使用官方的預建映像：
bash
docker run -d \
--name openclaw \
--restart unless-stopped \
-v ~/.openclaw:/root/.openclaw \
-v ~/openclaw/workspace:/root/workspace \
-p 3000:3000 \
ghcr.io/openclaw/openclaw:latest
Docker Compose 參考
以下是用於正式環境的帶註解 docker-compose.yml：
yaml
version: "3.8"
services:
openclaw-gateway:
image: ghcr.io/openclaw/openclaw:latest
container_name: openclaw
restart: unless-stopped
ports:
- "3000:3000" # Web UI
volumes:
- ~/.openclaw:/root/.openclaw # Config and data
- ~/openclaw/workspace:/root/workspace # Agent workspace
environment:
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- OPENAI_API_KEY=${OPENAI_API_KEY}
- TZ=Asia/Shanghai # Set your timezone
mem_limit: 2g # Prevent runaway memory usage
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
在同一目錄中建立一個 .env 檔案，填入你的 API 金鑰：
bash
ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx
環境變數
| 變數 | 必要 | 說明 |
|---|---|---|
ANTHROPIC_API_KEY | 是* | Claude API 金鑰 |
OPENAI_API_KEY | 否 | GPT API 金鑰（如使用 OpenAI） |
OPENCLAW_PORT | 否 | Web UI 連接埠（預設：3000） |
OPENCLAW_HOME | 否 | 容器內的資料目錄 |
TZ | 否 | 排程任務的時區 |
*至少需要一個 AI 供應商金鑰。
管理你的容器
bash
# 查看日誌
docker logs -f openclaw
# 停止代理
docker compose stop
# 啟動代理
docker compose up -d
# 配置變更後重啟
docker compose restart
# 更新到最新版本
docker compose pull
docker compose up -d
# 進入容器 shell
docker exec -it openclaw bash
# 在容器內執行 CLI 指令
docker exec openclaw openclaw skill list
docker exec openclaw openclaw status
安全強化
限制檔案系統存取
只掛載你的代理實際需要的目錄。避免掛載整個家目錄：
yaml
volumes:
- ~/.openclaw:/root/.openclaw:rw # Config (read-write)
- ~/documents:/root/docs:ro # Documents (read-only)
網路隔離
如果你的代理不需要存取區域網路服務，限制其網路：
yaml
networks:
openclaw-net:
driver: bridge
internal: false # Set to true to block all external access
唯讀根檔案系統
為了最大安全性，將根檔案系統設為唯讀，只允許寫入特定路徑：
yaml
read_only: true
tmpfs:
- /tmp
- /run
更新
OpenClaw 頻繁發布更新。要更新你的 Docker 部署：
bash
docker compose pull # 拉取最新映像
docker compose up -d # 用新映像重建容器
docker image prune -f # 清理舊映像
你的配置和資料保存在掛載的磁碟區中，因此更新不會破壞資料。
疑難排解
容器立即崩潰：用 docker logs openclaw 檢查日誌。常見原因：缺少 API 金鑰、記憶體不足或連接埠衝突。
WhatsApp QR 碼不顯示：以互動模式執行初始設定：docker compose run --rm openclaw-cli onboard。QR 碼需要支援渲染的終端機。
掛載磁碟區的權限錯誤：確保主機目錄存在且由你的使用者擁有：mkdir -p ~/.openclaw ~/openclaw/workspace。
記憶體使用過高：在 docker-compose.yml 中設定 mem_limit: 2g 以防止容器消耗過多記憶體。