在 Docker 容器中安裝和執行 Clawdbot AI 助手。使用 Docker Compose 進行容器化閘道器設定。

Clawdbot Docker 概述

Docker 對於 Clawdbot 是可選的。僅當您需要容器化閘道器或驗證 Docker 流程時才使用它。

Docker 適合我嗎？

使用場景	建議
隔離的、臨時的閘道器環境	是，使用 Docker
在主機上執行 Clawdbot，無需本地安裝	是，使用 Docker
在自己的機器上執行以獲得最快的開發循環	否，使用常規安裝

注意：Agent 沙盒也使用 Docker，但不需要完整的閘道器在 Docker 中執行。

需求

Docker Desktop（或 Docker Engine）+ Docker Compose v2
足夠的磁碟空間用於映像 + 日誌

容器化閘道器（Docker Compose）

快速開始（推薦）

從專案根目錄：

./docker-setup.sh

此腳本：

建構閘道器映像
執行初始設定精靈
顯示可選的提供者設定提示
透過 Docker Compose 啟動閘道器
生成閘道器令牌並寫入 .env

可選環境變數：

變數	說明
`CLAWDBOT_DOCKER_APT_PACKAGES`	在建構期間安裝額外的 apt 套件
`CLAWDBOT_EXTRA_MOUNTS`	新增額外的主機綁定掛載
`CLAWDBOT_HOME_VOLUME`	在命名卷中持久化 /home/node

完成後：

在瀏覽器中開啟 http://127.0.0.1:18789/
將令牌貼到控制介面（設定 → 令牌）

需要再次取得令牌化 URL？

docker compose run --rm clawdbot-cli dashboard --no-open

手動流程（Compose）

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

控制介面令牌 + 配對（Docker）

如果您看到「未授權」或「已斷開連接 (1008)：需要配對」：

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

額外掛載（可選）

將額外的主機目錄掛載到容器中：

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

持久化容器 Home（可選）

在容器重建時持久化 /home/node：

export CLAWDBOT_HOME_VOLUME="clawdbot_home"
./docker-setup.sh

安裝額外套件（可選）

在映像中安裝系統套件：

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

Agent 沙盒（Docker 工具）

Clawdbot 可以使用 Docker 進行 Agent 沙盒化，將 Agent 工具隔離在容器中。

功能說明

在隔離的 Docker 容器中執行 Agent 工具（exec、browser 等）
在 Agent 之間提供安全邊界
允許每個 Agent 使用不同的沙盒配置檔案

啟用沙盒

在您的 clawdbot.json 中：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

建構沙盒映像

clawdbot sandbox build

每個 Agent 的沙盒配置檔案

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/.clawdbot/workspace",
        "sandbox": {
          "mode": "off"
        }
      },
      "untrusted": {
        "sandbox": {
          "mode": "always"
        }
      }
    }
  }
}

健康檢查

docker compose run --rm clawdbot-cli health
docker compose run --rm clawdbot-cli status

疑難排解

權限錯誤（EACCES）

如果您看到權限錯誤，請檢查掛載的目錄是否具有正確的權限。

容器無法啟動

檢查 Docker 日誌：docker compose logs clawdbot-gateway
驗證端口 18789 未被佔用
確保 Docker 有足夠的資源

令牌問題

重新生成閘道器令牌：

docker compose run --rm clawdbot-cli configure --reset-token

下一步

Clawdbot 安裝 - 其他安裝方法
Clawdbot 閘道器 - 閘道器設定
Clawdbot 設定 - 完整設定指南

Clawdbot Docker 安裝