Docker

​

Docker は自分に適しているか？

• Yes: 分離された一時的なゲートウェイ環境が必要、またはローカルインストールなしのホストで OpenClaw を動かしたい。
• No: 自分のマシン上で動かしており、最速の開発ループだけが欲しい。この場合は通常のインストールフローを使ってください。
• サンドボックスに関する補足: エージェントのサンドボックス化にも Docker を使いますが、完全なゲートウェイ全体を Docker 内で動かす必要は ありません。Sandboxing を参照してください。

• コンテナ化されたゲートウェイ (Docker 内で OpenClaw 全体を実行)
• セッション単位のエージェントサンドボックス (ホスト上のゲートウェイ + Docker で分離したエージェントツール)

​

要件

• Docker Desktop (または Docker Engine) + Docker Compose v2
• イメージビルド用に最低 2 GB RAM
  • 1 GB ホストでは pnpm install が OOM kill され、exit 137 になることがあります
• イメージとログを保持できる十分なディスク容量
• VPS / 公開ホストで動かす場合は Security hardening for network exposure を確認してください
  • 特に Docker の DOCKER-USER firewall policy に注意してください

​

コンテナ化された Gateway（Docker Compose）

​

クイックスタート（推奨）

./docker-setup.sh

• ゲートウェイイメージをローカルでビルドする
  • OPENCLAW_IMAGE が設定されていれば、代わりにリモートイメージを pull します
• オンボーディングウィザードを実行する
• 任意のプロバイダー設定に関するヒントを表示する
• Docker Compose 経由でゲートウェイを起動する
• ゲートウェイトークンを生成して .env に書き込む

• OPENCLAW_IMAGE — ローカルビルドの代わりにリモートイメージを使う (例: ghcr.io/openclaw/openclaw:latest)
• OPENCLAW_DOCKER_APT_PACKAGES — ビルド時に追加の apt パッケージを入れる
• OPENCLAW_EXTENSIONS — ビルド時に extension の依存関係を事前インストールする
  • スペース区切りの extension 名を指定します。例: diagnostics-otel matrix
• OPENCLAW_EXTRA_MOUNTS — 追加のホスト bind mount を加える
• OPENCLAW_HOME_VOLUME — /home/node を named volume として永続化する
• OPENCLAW_SANDBOX — Docker ゲートウェイ用サンドボックス設定の bootstrap を有効にする
  • 明示的に truthy な値 1、true、yes、on の場合のみ有効です
• OPENCLAW_INSTALL_DOCKER_CLI — ローカルイメージビルド向けの build arg passthrough
  • 1 を指定するとイメージ内に Docker CLI を入れます
  • docker-setup.sh はローカルビルドで OPENCLAW_SANDBOX=1 の場合、自動でこれを設定します
• OPENCLAW_DOCKER_SOCKET — Docker socket path を上書きする
  • デフォルトは DOCKER_HOST=unix://... の path、そうでなければ /var/run/docker.sock
• OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 — 緊急時向け
  • CLI / オンボーディングクライアント経路で、信頼済み private network 上の ws:// target を許可します
  • デフォルトは loopback のみです
• OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 — コンテナ browser の hardening flag を無効化する
  • --disable-3d-apis、--disable-software-rasterizer、--disable-gpu を外し、WebGL / 3D 互換性が必要なときに使います
• OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 — browser フローで extension が必要なときに有効のままにする
  • 既定ではサンドボックス側の browser で extension は無効です
• OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> — Chromium の renderer process 上限を設定する
  • 0 にするとこのフラグを省略し、Chromium のデフォルト動作を使います

• ブラウザで http://127.0.0.1:18789/ を開く
• Control UI にトークンを貼り付ける（Settings → token）
• URL が再度必要ですか？ docker compose run --rm openclaw-cli dashboard --no-open を実行してください。

​

Docker ゲートウェイ用の agent sandbox を有効にする（オプトイン）

export OPENCLAW_SANDBOX=1
./docker-setup.sh

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./docker-setup.sh

• このスクリプトはサンドボックスの前提条件を満たしたあとでのみ docker.sock をマウントします。
• サンドボックスセットアップを完了できない場合、再実行時に古い / 壊れた設定が残らないよう agents.defaults.sandbox.mode を off に戻します。
• Dockerfile.sandbox がない場合は警告を出して続行します。
  • 必要なら scripts/sandbox-setup.sh で openclaw-sandbox:bookworm-slim をビルドしてください。
• ローカル以外の OPENCLAW_IMAGE を使う場合、そのイメージにはサンドボックス実行用の Docker CLI サポートがあらかじめ含まれている必要があります。

​

自動化 / CI（非対話、TTY ノイズなし）

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

​

共有ネットワークのセキュリティに関する注意（CLI + ゲートウェイ）

• ~/.openclaw/
• ~/.openclaw/workspace

​

リモートイメージを使う（ローカルビルドをスキップ）

• GitHub Container Registry package

• main — main の最新ビルド
• <version> — リリースタグのビルド（例: 2026.2.26）
• latest — 最新の安定リリースタグ

​

ベースイメージのメタデータ

• node:22-bookworm

• org.opencontainers.image.base.name=docker.io/library/node:22-bookworm
• org.opencontainers.image.base.digest=sha256:b501c082306a4f528bc4038cbf2fbb58095d583d0419a259b2114b5ac53d12e9
• org.opencontainers.image.source=https://github.com/openclaw/openclaw
• org.opencontainers.image.url=https://openclaw.ai
• org.opencontainers.image.documentation=https://docs.openclaw.ai/install/docker
• org.opencontainers.image.licenses=MIT
• org.opencontainers.image.title=OpenClaw
• org.opencontainers.image.description=OpenClaw gateway and CLI runtime container image
• org.opencontainers.image.revision=<git-sha>
• org.opencontainers.image.version=<tag-or-main>
• org.opencontainers.image.created=<rfc3339 timestamp>

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

​

シェルヘルパー（任意）

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

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

​

手動手順（Compose）

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

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

​

Control UI のトークンとペアリング（Docker）

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>

​

追加マウント（任意）

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

• macOS / Windows では、対象パスが Docker Desktop と共有されている必要があります。
• 各項目は source:target[:options] 形式で、スペース、タブ、改行を含めてはいけません。
• OPENCLAW_EXTRA_MOUNTS を編集した場合は、 追加の Compose ファイルを再生成するために docker-setup.sh を再実行してください。
• docker-compose.extra.yml は自動生成されます。手動で編集しないでください。

​

コンテナ全体の home を永続化する（任意）

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

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

• named volume 名は ^[A-Za-z0-9][A-Za-z0-9_.-]*$ に一致する必要があります。
• OPENCLAW_HOME_VOLUME を変更した場合は、 追加の Compose ファイルを再生成するために docker-setup.sh を再実行してください。
• named volume は docker volume rm <name> で削除するまで保持されます。

​

追加の apt packages をインストールする（任意）

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

• これは apt パッケージ名をスペース区切りで指定する形式です。
• OPENCLAW_DOCKER_APT_PACKAGES を変更した場合は、イメージを再ビルドするために docker-setup.sh を再実行してください。

​

extension dependencies を事前インストールする（任意）

export OPENCLAW_EXTENSIONS="diagnostics-otel matrix"
./docker-setup.sh

docker build --build-arg OPENCLAW_EXTENSIONS="diagnostics-otel matrix" .

• これは extensions/ 配下のディレクトリ名をスペース区切りで指定する形式です。
• package.json を持つ extension のみが対象です。これを持たない軽量プラグインは無視されます。
• OPENCLAW_EXTENSIONS を変更した場合は、イメージを再ビルドするために docker-setup.sh を再実行してください。

​

上級者向けのフル機能コンテナ（オプトイン）

• 実行時にシステムパッケージを追加インストールできない
• デフォルトでは Homebrew なし
• Chromium / Playwright ブラウザは同梱されない

1. ブラウザのダウンロードやツールキャッシュを保持できるよう、/home/node を永続化します。

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

2. システム依存関係をイメージに組み込みます（再現性があり、永続化されます）。

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

3. npx を使わずに Playwright ブラウザをインストールします（npm の override 競合を回避できます）。

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

4. Playwright ブラウザのダウンロードを永続化します。

• docker-compose.yml で PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright を設定する。
• OPENCLAW_HOME_VOLUME で /home/node が永続化されていることを確認するか、 OPENCLAW_EXTRA_MOUNTS で /home/node/.cache/ms-playwright をマウントする。

​

権限エラーと EACCES

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

​

より高速な再ビルド（推奨）

FROM node:22-bookworm

# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Cache dependencies unless package metadata changes
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

​

チャネルのセットアップ（任意）

docker compose run --rm openclaw-cli channels login

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

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

​

OpenAI Codex OAuth（ヘッドレス Docker）

​

Health checks

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

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

​

E2E smoke test（Docker）

scripts/e2e/onboard-docker.sh

​

QR import smoke test（Docker）

pnpm test:docker:qr

​

lan と loopback の違い（Docker Compose）

• lan（既定値）: ホストのブラウザとホスト CLI から、公開されたゲートウェイポートへ到達できます。
• loopback: コンテナの network namespace 内にいるプロセスだけが ゲートウェイへ直接到達できます。ホストへ公開されたポート経由のアクセスは失敗する場合があります。

docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

​

注意

• ゲートウェイの bind はコンテナ利用向けに既定で lan です（OPENCLAW_GATEWAY_BIND）。
• Dockerfile の CMD は --allow-unconfigured を使います。マウントされた設定で gateway.mode が local でなくても起動します。ガードを強制したい場合は CMD を上書きしてください。
• ゲートウェイコンテナがセッション情報の正本です（~/.openclaw/agents/<agentId>/sessions/）。

​

ストレージモデル

• 永続化されるホスト側データ: Docker Compose は OPENCLAW_CONFIG_DIR を /home/node/.openclaw に、OPENCLAW_WORKSPACE_DIR を /home/node/.openclaw/workspace に bind mount するため、これらのパスはコンテナを置き換えても保持されます。
• 一時的なサンドボックス tmpfs: agents.defaults.sandbox が有効な場合、サンドボックスコンテナは /tmp、/var/tmp、/run に tmpfs を使います。これらのマウントはトップレベルの Compose スタックとは別で、サンドボックスコンテナとともに消えます。
• ディスク増加しやすい箇所: media/、agents/<agentId>/sessions/sessions.json、transcript JSONL ファイル、cron/runs/*.jsonl、および /tmp/openclaw/（または設定した logging.file）配下のローテートログに注意してください。Docker 外で macOS アプリも実行している場合、そのサービスログは別管理で、~/.openclaw/logs/gateway.log、~/.openclaw/logs/gateway.err.log、/tmp/openclaw/openclaw-gateway.log に出力されます。

​

Agent Sandbox（ホスト上のゲートウェイ + Docker ツール）

​

概要

• 既定の scope は "agent"（agent ごとに 1 つのコンテナ + ワークスペース）
• セッション単位で分離したい場合は scope に "session" を使います
• scope ごとのワークスペースフォルダを /workspace にマウントします
• 必要に応じて agent workspace access（agents.defaults.sandbox.workspaceAccess）を設定できます
• ツールポリシーは allow/deny 方式で、deny が優先されます
• 受信メディアは、ツールから読めるようアクティブなサンドボックスワークスペース（media/inbound/*）へコピーされます（workspaceAccess: "rw" の場合は agent ワークスペースに入ります）

​

Agent ごとのサンドボックスプロファイル（multi-agent）

• フルアクセス（個人用 agent）
• 読み取り専用ツール + 読み取り専用ワークスペース（家族用 / 業務用 agent）
• filesystem / shell ツールなし（公開 agent）

​

デフォルト動作

• イメージ: openclaw-sandbox:bookworm-slim
• agent ごとに 1 つのコンテナ
• Agent workspace access: workspaceAccess: "none"（既定値）では ~/.openclaw/sandboxes を使います
  • "ro" ではサンドボックスワークスペースを /workspace のままにし、agent workspace を /agent へ読み取り専用でマウントします（write / edit / apply_patch は無効）
  • "rw" では agent workspace を /workspace へ読み書き可能でマウントします
• 自動削除: アイドル状態が 24 時間超、または作成から 7 日超
• ネットワーク: 既定値は none（外向き通信が必要な場合のみ明示的にオプトイン）
  • host はブロックされます。
  • container:<id> も既定でブロックされます（namespace join のリスクがあるため）。
• 既定で許可: exec, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• 既定で拒否: browser, canvas, nodes, cron, discord, gateway

​

サンドボックスを有効にする

• 既定の docker.network は "none"（外向き通信なし）です。
• docker.network: "host" はブロックされます。
• docker.network: "container:<id>" はデフォルトでブロックされます。
• 緊急時のみの上書き設定: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true
• readOnlyRoot: true ではパッケージインストールを実行できません。
• apt-get を使うには user が root である必要があります（user を省略するか、user: "0:0" を設定します）。 OpenClaw は setupCommand（または Docker 設定）が変わると自動的にコンテナを再作成しますが、 コンテナが直近で使用されていた（約 5 分以内）場合は除きます。稼働中のコンテナでは、 正確な openclaw sandbox recreate ... コマンドを含む警告が表示されます。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        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, // 0 disables idle pruning
          maxAgeDays: 7, // 0 disables max-age pruning
        },
      },
    },
  },
  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"],
      },
    },
  },
}

​

既定のサンドボックスイメージをビルドする

scripts/sandbox-setup.sh

​

共通サンドボックスイメージ（任意）

scripts/sandbox-common-setup.sh

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

​

サンドボックス用ブラウザイメージ

scripts/sandbox-browser-setup.sh

• Headful（Xvfb）は headless より bot blocking を受けにくくなります。
• agents.defaults.sandbox.browser.headless=true を設定すれば、引き続き headless を使えます。
• フルデスクトップ環境（GNOME など）は不要で、表示は Xvfb が提供します。
• ブラウザコンテナは、グローバルな bridge ではなく、専用の Docker network（openclaw-sandbox-browser）を既定で使います。
• 必要に応じて agents.defaults.sandbox.browser.cdpSourceRange を使い、コンテナ境界での CDP ingress を CIDR で制限できます（例: 172.21.0.1/32）。
• noVNC のオブザーバーアクセスは既定でパスワード保護されます。OpenClaw は短時間だけ有効な observer token URL を提供し、パスワードは URL query ではなく URL fragment に保持されるローカル bootstrap page を返します。
• ブラウザコンテナの起動時既定値は、共有環境やコンテナワークロード向けに保守的に設定されており、次のフラグを含みます。
  • --remote-debugging-address=127.0.0.1
  • --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
  • --user-data-dir=${HOME}/.chrome
  • --no-first-run
  • --no-default-browser-check
  • --disable-3d-apis
  • --disable-software-rasterizer
  • --disable-gpu
  • --disable-dev-shm-usage
  • --disable-background-networking
  • --disable-features=TranslateUI
  • --disable-breakpad
  • --disable-crash-reporter
  • --metrics-recording-only
  • --renderer-process-limit=2
  • --no-zygote
  • --disable-extensions
  • agents.defaults.sandbox.browser.noSandbox が設定されている場合は、--no-sandbox と --disable-setuid-sandbox も追加されます。
  • 上記 3 つの graphics hardening フラグは任意です。ワークロードで WebGL / 3D が必要な場合は、OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 を設定して --disable-3d-apis, --disable-software-rasterizer, --disable-gpu なしで実行してください。
  • extension の挙動は --disable-extensions で制御され、extension 依存のページや extension を多用するワークフローでは OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 により無効化 （つまり extension を有効化）できます。
  • --renderer-process-limit=2 も OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT で設定できます。ブラウザ並列数の調整が必要な場合は 0 にして、Chromium に 既定の process limit を選ばせることもできます。

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

{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-openclaw-browser" } },
    },
  },
}

• サンドボックス用ブラウザ制御 URL（browser ツール用）
• noVNC URL（有効かつ headless=false の場合）

​

カスタムサンドボックスイメージ

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-openclaw-sbx" } },
    },
  },
}

​

ツールポリシー（allow/deny）

• deny は allow に優先します。
• allow が空の場合: deny を除くすべてのツールが利用可能です。
• allow が空でない場合: allow にあるツールだけが利用可能です（deny を除く）。

​

自動削除ポリシー

• prune.idleHours: X 時間使われていないコンテナを削除（0 = 無効）
• prune.maxAgeDays: X 日より古いコンテナを削除（0 = 無効）

• 稼働中のセッションは維持しつつ、有効期間を制限する: idleHours: 24, maxAgeDays: 7
• 自動削除を一切行わない: idleHours: 0, maxAgeDays: 0

​

セキュリティに関する注意

• 強い隔離が適用されるのは tools のみです（exec / read / write / edit / apply_patch）。
• browser / camera / canvas のような host-only ツールは既定でブロックされます。
• サンドボックスで browser を許可すると 隔離が崩れます（browser はホスト上で実行されます）。

​

トラブルシューティング

• イメージがない: scripts/sandbox-setup.sh でビルドするか、agents.defaults.sandbox.docker.image を設定してください。
• コンテナが起動していない: 必要になった時点で、セッションごとに自動作成されます。
• サンドボックスで権限エラーが出る: docker.user を マウントしたワークスペースの所有権に一致する UID:GID へ設定する （またはワークスペースフォルダを chown する）。
• カスタムツールが見つからない: OpenClaw は sh -lc（login shell）でコマンドを実行するため、 /etc/profile を読み込んで PATH をリセットすることがあります。docker.env.PATH を設定して カスタムツールのパス（例: /custom/bin:/usr/local/share/npm-global/bin）を前置するか、 Dockerfile で /etc/profile.d/ 配下にスクリプトを追加してください。