使用 Docker 運行 Gateway

每次在處理部署的時候，最頭痛的就是環境配置。明明在自己電腦跑得好好的，換到另一台機器就因為少裝了某個套件或是版本不對而噴錯。如果你也遇過這種「在我電腦上明明可以跑」的窘境，通常會想找個更乾淨、更一致的方法來管理你的執行環境。

容器化技術確實能解決這些麻煩，但並不是每個專案都一定要強行加入這層複雜度。

需要準備的東西

根據源文件，你只需要準備：

Docker（僅在你決定要使用容器化方案時需要）

快速開始

在目前的設定中，Docker 是 optional 的，也就是說你可以自由選擇是否要使用，它並非運行專案的必要條件。

如果你符合以下兩種情況，建議你使用它：

你想要一個容器化的 Gateway。
你需要驗證 Docker flow 是否符合預期。

如果你沒有這些特定的需求，完全可以跳過 Docker 的部分，直接使用本地環境執行。

疑難排解

目前源文件中沒有提到關於 Docker 的特定錯誤訊息。如果你在啟動容器時遇到問題，請先確認你的 Docker 服務已經正常啟動，並且你的權限足以執行相關指令。

想要了解更多細節或遇到卡關？可以詢問我們的 AI Setup Assistant。

下一步

每次設定新開發環境，最怕的就是把自己的電腦搞得一團糟。你可能只是想快速測試一個工具，或者希望開發環境在測試完後能乾乾淨淨地消失，不留下任何殘餘檔案。

## 需要準備的東西

在開始之前，請確保你已經準備好以下環境：

- Docker Desktop (或 Docker Engine) + Docker Compose v2
- 足夠的磁碟空間，用來存放 images 與 logs

## 快速開始

這是一個簡單的二選一。我建議你根據目前的開發需求來決定：

- **是，用 Docker**：如果你想要一個隔離、用完就丟的 Gateway 環境，或者你的主機不想安裝任何在地化工具，那就選 Docker。
- **否，不用 Docker**：如果你是在自己的電腦上開發，而且追求最快的開發循環（dev loop），直接使用一般的安裝流程會更有效率。

這份指南會涵蓋以下內容：

- **Containerized Gateway**：讓完整的 OpenClaw 在 Docker 中執行。
- **Per-session Agent Sandbox**：Gateway 跑在主機上，但使用 Docker 隔離 Agent tools。

**關於 Sandboxing 的筆記**：Agent sandboxing 雖然也會用到 Docker，但這並不代表整個 Gateway 都必須在 Docker 裡執行。你可以參考 [Sandboxing](/docs/gateway/sandboxing) 了解更多細節。

想要更快速的自動化設定？直接詢問 [AI Setup Assistant](/docs/)。

## 下一步

- [Sandboxing](/docs/gateway/sandboxing)

你是不是也遇過這種情況：在本地端跑得好好的服務，一丟到伺服器就因為環境依賴搞得一團糟？或者只是想快速測試一個 Gateway，卻得手動安裝一堆 Node.js 套件和系統工具，弄得電腦環境髒兮兮？

使用 Docker 容器化部署就是為了解決這些痛點。透過 Docker Compose，你可以把整個 Gateway 環境封裝起來，無論是在自己的筆電還是雲端 VPS 上，都能保證運行環境完全一致，省去那些無謂的除錯時間。

## 需要準備的東西

在開始之前，請確保你已經準備好：
- 專案的 Repo 根目錄
- 已安裝 Docker 與 Docker Compose
- 如果是跑在 VPS 上，可以參考 [Hetzner (Docker VPS)](/docs/install/hetzner) 指南

## Quick Start (推薦方式)

這是最快路徑，只需要在 Repo 根目錄執行一個腳本：

```bash
./docker-setup.sh

這個腳本會幫你完成所有髒活：

建置 Gateway 映像檔 (Image)
執行設定精靈 (Onboarding wizard)
顯示選用的 Provider 設定提示
透過 Docker Compose 啟動 Gateway
自動產生 Gateway token 並寫入 .env

你可以使用的選用環境變數：

OPENCLAW_DOCKER_APT_PACKAGES — 在建置時安裝額外的 apt 套件
OPENCLAW_EXTRA_MOUNTS — 新增額外的 Host 綁定掛載 (Bind mounts)
OPENCLAW_HOME_VOLUME — 將 /home/node 持久化儲存在具名磁碟卷 (Named volume) 中

執行完畢後：

在瀏覽器打開 http://127.0.0.1:18789/。
將 token 貼進 Control UI（Settings → token）。
如果需要再次取得 URL，執行：docker compose run --rm openclaw-cli dashboard --no-open。

系統會將設定與 Workspace 寫在 Host 的這些路徑：

~/.openclaw/
~/.openclaw/workspace

Shell Helpers (選用)

如果你想要更輕鬆地管理 Docker，可以安裝 ClawDock 工具：

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

加入你的 Shell 設定檔 (以 zsh 為例)：

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

之後你就可以直接用 clawdock-start, clawdock-stop, clawdock-dashboard 等指令。輸入 clawdock-help 可以查看完整清單。更多細節請看 ClawDock Helper README。

Manual flow (手動流程)

如果你偏好手動操作 Compose，步驟如下：

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

注意：請在 Repo 根目錄執行 docker compose。如果你啟用了 OPENCLAW_EXTRA_MOUNTS 或 OPENCLAW_HOME_VOLUME，設定腳本會產生 docker-compose.extra.yml。在其他地方執行時記得包含它：

docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

進階配置與持久化

額外掛載目錄 (Extra mounts)

如果你想把 Host 的其他目錄掛載進容器，可以在執行 docker-setup.sh 前設定 OPENCLAW_EXTRA_MOUNTS。這接受以逗號分隔的 Docker bind mounts 列表。

範例：

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

持久化整個容器 Home 目錄

如果你希望 /home/node 在容器重建後依然保留資料，請設定 OPENCLAW_HOME_VOLUME 使用具名磁碟卷。

範例：

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

安裝額外 apt 套件

需要在映像檔內內建系統套件（如 ffmpeg）？

範例：

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

Power-user / 全功能容器設定

預設的 Docker 映像檔是以安全性優先設計，使用非 root 的 node 使用者執行。這意味著預設沒有 Homebrew，也沒有內建 Chromium。如果你需要更強大的功能，請參考以下組合：

持久化 /home/node 以保留工具快取。

將系統依賴打進映像檔：

export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh

不安裝 npx 直接安裝 Playwright 瀏覽器（避免 npm 衝突）：

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

持久化 Playwright 下載內容：
- 在 docker-compose.yml 設定 PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright。
- 確保 /home/node 已持久化。

Channel 設定

使用 CLI 容器來設定通訊渠道，完成後視需求重啟 Gateway。

WhatsApp (掃碼):

docker compose run --rm openclaw-cli channels login

Telegram (Bot token):

docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

Discord (Bot token):

docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

詳細文件請參考：WhatsApp, Telegram, Discord。

疑難排解

Control UI token 與配對問題

如果你看到 “unauthorized” 或 “disconnected (1008): pairing required”，請重新取得連結並核准裝置：

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

更多細節：Dashboard, Devices。

權限錯誤 (EACCES)

映像檔以 node 使用者 (uid 1000) 執行。如果你在 /home/node/.openclaw 看到權限錯誤，請確保 Host 上的目錄擁有者正確：

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

OpenAI Codex OAuth (Headless Docker)

在 Docker 環境下，OAuth 回調可能會顯示瀏覽器錯誤。請複製你最後停留的完整重新導向 URL，並將其貼回設定精靈中即可完成驗證。

健康檢查

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

如果你在部署過程中遇到任何問題，歡迎使用 AI Setup Assistant 獲取即時協助。

What’s Next:

寫程式最怕 Agent 跑一跑把你的主機檔案弄亂，或是執行了不該執行的指令。讓 LLM 直接在你的主機上執行代碼風險很高，這就是為什麼我們需要一個安全的「沙盒」環境。

透過 Agent Sandbox，你可以把工具執行過程鎖在 Docker 容器裡。Gateway 依然跑在你的主機上，但所有工具的操作都會被嚴格隔離，既安全又好管理。

需要準備的東西

在開始設定之前，請確保你已經準備好：

已安裝 Docker 並正常運作
OpenClaw Gateway 環境
基礎的 JSON 配置修改能力

快速開始

想在 5 分鐘內跑起來？照著這幾步做：

建立預設沙盒鏡像：在終端機執行腳本，這會建立 openclaw-sandbox:bookworm-slim：
Terminal window
```
scripts/sandbox-setup.sh
```

啟用 Sandbox：在你的設定檔中將 agents.defaults.sandbox.mode 設定為 "non-main"：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "agent"
      }
    }
  }
}

重啟 Gateway：現在除了主 Session 外，其他的工具執行都會在隔離的 Docker 容器中進行。

深入了解 Sandbox 機制

當 agents.defaults.sandbox 啟用後，非主 Session 的工具會在 Docker 容器內執行。

隔離層級 (Scope)

你可以決定隔離的嚴密程度：

scope: "agent"（預設）：每個 Agent 擁有獨立的容器與 workspace。
scope: "session"：每個 Session 都有專屬的隔離環境。
scope: "shared"：所有 Session 共用同一個容器，這會停用跨 Session 的隔離功能，請謹慎使用。

檔案存取權限

容器內的 workspace 掛載在 /workspace。你可以透過 workspaceAccess 調整 Agent 對主機檔案的存取：

"none"（預設）：使用 ~/.openclaw/sandboxes 作為獨立空間。
"ro"：唯讀模式。主機 workspace 掛載在 /agent，且會停用 write、edit、apply_patch 等工具。
"rw"：讀寫模式。主機 workspace 直接掛載到容器的 /workspace。

此外，傳入的媒體檔案會自動複製到當前沙盒的 media/inbound/* 目錄，讓工具可以讀取。

多 Agent 設定 (Multi-agent)

如果你有多個 Agent 路由，可以針對不同對象設定不同的權限等級：

個人 Agent：給予 Full access。
家庭/工作 Agent：設定唯讀工具與唯讀 workspace。
公開 Agent：完全停用檔案系統或 Shell 工具。

具體範例可以參考 Multi-Agent Sandbox & Tools。

詳細配置參考

這是一份完整的配置範例，包含了網路、記憶體限制以及工具白名單：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24, // 閒置多久後移除容器
          maxAgeDays: 7, // 容器最長壽命
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

工具權限邏輯

deny 的優先級高於 allow。
如果 allow 是空的：除了 deny 列表外的所有工具都可用。
如果 allow 有內容：只有在 allow 列表內且不在 deny 列表內的工具才可用。

特殊鏡像建置

除了標準鏡像，你也可以根據需求建置其他版本：

常用工具鏡像 (Common Image)

如果你需要 Node, Go, Rust 等開發環境：

scripts/sandbox-common-setup.sh

並在配置中將 image 改為 openclaw-sandbox-common:bookworm-slim。

瀏覽器鏡像 (Browser Image)

要在沙盒內執行 browser 工具：

scripts/sandbox-browser-setup.sh

這會建立包含 Chromium 與 noVNC 的環境。記得在配置中啟用：

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

注意：在沙盒內啟用 browser 會打破隔離性，因為瀏覽器實際上是在主機環境運作（或與主機有較多互動）。

疑難排解

1. 無法在 setupCommand 安裝套件？

檢查 docker.network 是否為 "none"。如果是，容器無法連網下載套件。
檢查 readOnlyRoot 是否為 true。這會阻止寫入系統目錄。
確保 user 具有 root 權限（例如設定為 "0:0"）。

2. 設定改了但容器沒更新？ OpenClaw 會在 setupCommand 或 Docker 設定變更時自動重建容器。但如果容器在過去 5 分鐘內剛被使用過（Hot container），系統會跳過自動重建並在日誌顯示警告。你可以根據日誌提供的 openclaw sandbox recreate ... 指令手動強制重建。

3. 檔案無法寫入？ 如果你使用了 workspaceAccess: "ro"，系統會自動停用所有具備寫入功能的工具。請確認你的權限需求。

還有設定上的疑問嗎？可以詢問 AI Setup Assistant。

What’s Next

你是不是也遇過這種狀況？明明代碼邏輯都寫對了，但環境一跑起來就噴出一堆 Docker 報錯，或是自定義的工具怎麼調用都找不到。處理 Sandbox 環境最煩人的就是這些碎事，讓你沒辦法專心在開發 AI Agent 上。

這篇文章整理了你在使用 OpenClaw 時最常遇到的幾個坑，幫你省下在 GitHub Issues 翻找的時間。

需要準備的東西

在開始排查之前，請確保你已經準備好以下內容：

已安裝 Docker 並具備運行權限
專案根目錄下的 scripts/sandbox-setup.sh 腳本
OpenClaw 的設定檔（用於調整 agents.defaults）

快速開始

如果你遇到 Sandbox 無法正常運作，請先嘗試這兩個最快的修復路徑：

重新建置鏡像：直接執行腳本來確保基礎環境完整：
Terminal window
```
bash scripts/sandbox-setup.sh
```
檢查設定檔：確認你的 agents.defaults.sandbox.docker.image 指向了正確的鏡像名稱。

疑難排解

這裡彙整了開發者最常回饋的幾個問題與具體解法：

找不到 Image

如果你看到 Image missing 的錯誤，通常是因為本地還沒有建置好所需的鏡像。

解法 1：執行 scripts/sandbox-setup.sh 進行手動建置。
解法 2：在設定中明確指定 agents.defaults.sandbox.docker.image 的值。

Container 沒有在運行

有時候你會發現 Docker 容器列表裡沒有看到運行的 Sandbox，這其實是正常的。OpenClaw 會根據每個 Session 的需求（on demand）自動建立容器，不需要手動去啟動它。

Sandbox 權限錯誤

如果你遇到權限拒絕（Permission errors），通常是因為容器內的用戶與你掛載的 Workspace 目錄權限不匹配。

解法 1：將 docker.user 設定為與你掛載目錄擁有者一致的 UID:GID。
解法 2：直接對你的 Workspace 資料夾執行 chown 修改權限，讓容器內的用戶可以讀寫。

找不到 Custom Tools

這是一個比較隱蔽的坑。因為 OpenClaw 是透過 sh -lc（login shell）來執行指令，這會加載 /etc/profile 並可能重置你的 PATH 變數。

解法 1：在 docker.env.PATH 中把你的工具路徑擺在最前面（例如：/custom/bin:/usr/local/share/npm-global/bin）。
解法 2：在你的 Dockerfile 中，將設定路徑的腳本放在 /etc/profile.d/ 目錄下。

如果你嘗試了以上方法還是搞不定，可以問問我們的 AI Setup Assistant。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。