Docker

Docker は任意です。コンテナ化された Gateway が必要な場合、または Docker フローを検証したい場合にのみ使用してください。

# Docker は自分に適していますか？

• はい: 分離された使い捨ての Gateway 環境が必要な場合、またはローカルインストールなしのホストで OpenClaw を実行したい場合。
• いいえ: 自分のマシンで実行していて、最速の開発ループだけが必要な場合。代わりに通常のインストールフローを使用してください。
• サンドボックス化の注記: デフォルトのサンドボックスバックエンドは、サンドボックス化が有効な場合に Docker を使用しますが、サンドボックス化はデフォルトでオフであり、Gateway 全体を Docker で実行する必要はありません。SSH と OpenShell のサンドボックスバックエンドも利用できます。サンドボックス化を参照してください。

# 前提条件

• Docker Desktop（または Docker Engine）+ Docker Compose v2
• イメージビルド用に少なくとも 2 GB の RAM（1 GB のホストでは pnpm install が OOM により終了 137 で強制終了される場合があります）
• イメージとログに十分なディスク容量
• VPS/公開ホストで実行する場合は、特に Docker の DOCKER-USER ファイアウォールポリシーについて、 ネットワーク公開のためのセキュリティ強化を確認してください。

# コンテナ化された Gateway

./scripts/docker/setup.sh

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

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

# WhatsApp (QR)
docker compose run --rm openclaw-cli channels login

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

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

# 手動フロー

セットアップスクリプトを使用せずに各手順を自分で実行したい場合:

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'
docker compose up -d openclaw-gateway

# 環境変数

セットアップスクリプトは次の任意の環境変数を受け付けます。

メンテナーは、1 つのPluginソースディレクトリをパッケージ化されたソースパスの上にマウントすることで、 パッケージ化されたイメージに対してバンドル済みPluginソースをテストできます。例: OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro。 そのマウントされたソースディレクトリは、同じPlugin ID に対応するコンパイル済みの /app/dist/extensions/synology-chat バンドルを上書きします。

# 可観測性

OpenTelemetry エクスポートは、Gateway コンテナから OTLP コレクターへのアウトバウンド通信です。公開済み Docker ポートは必要ありません。イメージを ローカルでビルドし、バンドル済み OpenTelemetry エクスポーターをイメージ内で利用可能にしたい場合は、 そのランタイム依存関係を含めます。

export OPENCLAW_EXTENSIONS="diagnostics-otel"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"
export OTEL_SERVICE_NAME="openclaw-gateway"
./scripts/docker/setup.sh

エクスポートを有効にする前に、パッケージ化された Docker インストールでは、 ClawHub から公式の @openclaw/diagnostics-otel Pluginをインストールしてください。 カスタムのソースビルドイメージでも、OPENCLAW_EXTENSIONS=diagnostics-otel でローカルPluginソースを含めることができます。エクスポートを有効にするには、設定で diagnostics-otel Pluginを許可して有効化し、 diagnostics.otel.enabled=true を設定するか、OpenTelemetry エクスポートの設定例を使用してください。コレクター認証ヘッダーは Docker 環境変数ではなく、diagnostics.otel.headers で設定します。

Prometheus メトリクスは、すでに公開されている Gateway ポートを使用します。 clawhub:@openclaw/diagnostics-prometheus をインストールし、 diagnostics-prometheus Pluginを有効にしてから、次をスクレイプします。

http://<gateway-host>:18789/api/diagnostics/prometheus

このルートは Gateway 認証で保護されています。別の公開 /metrics ポートや、認証されていないリバースプロキシパスを公開しないでください。 Prometheus メトリクスを参照してください。

# ヘルスチェック

コンテナプローブエンドポイント（認証不要）:

curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness

Docker イメージには、/healthz に ping する組み込みの HEALTHCHECK が含まれています。 チェックが失敗し続けると、Docker はコンテナを unhealthy としてマークし、 オーケストレーションシステムが再起動または置換できるようになります。

認証付きの詳細ヘルススナップショット:

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

# LAN とループバック

scripts/docker/setup.sh はデフォルトで OPENCLAW_GATEWAY_BIND=lan に設定するため、 Docker ポート公開で http://127.0.0.1:18789 へのホストアクセスが機能します。

• lan（デフォルト）: ホストブラウザーとホスト CLI が公開された Gateway ポートに到達できます。
• loopback: コンテナネットワーク名前空間内のプロセスだけが Gateway に直接到達できます。

# ホストローカルプロバイダー

OpenClaw が Docker 内で実行される場合、コンテナ内の 127.0.0.1 は ホストマシンではなくコンテナ自体です。ホスト上で実行される AI プロバイダーには host.docker.internal を使用してください。

バンドル済み Docker セットアップは、これらのホスト URL を LM Studio と Ollama の オンボーディングデフォルトとして使用し、docker-compose.yml は Linux Docker Engine 用に host.docker.internal を Docker のホストゲートウェイにマップします。Docker Desktop は macOS と Windows で同じホスト名をすでに提供しています。

ホストサービスは、Docker から到達可能なアドレスでも待ち受ける必要があります。

lms server start --port 1234 --bind 0.0.0.0
OLLAMA_HOST=0.0.0.0:11434 ollama serve

独自の Compose ファイルまたは docker run コマンドを使用する場合は、 たとえば --add-host=host.docker.internal:host-gateway のように、 同じホストマッピングを自分で追加してください。

# Bonjour / mDNS

Docker ブリッジネットワークは通常、Bonjour/mDNS マルチキャスト （224.0.0.251:5353）を安定して転送しません。そのため、バンドル済み Compose セットアップでは デフォルトで OPENCLAW_DISABLE_BONJOUR=1 に設定され、ブリッジがマルチキャストトラフィックを落としたときに Gateway がクラッシュループしたり、アドバタイズを繰り返し再起動したりしないようにしています。

Docker ホストには、公開された Gateway URL、Tailscale、または広域 DNS-SD を使用してください。 OPENCLAW_DISABLE_BONJOUR=0 を設定するのは、ホストネットワーク、macvlan、 または mDNS マルチキャストが機能することが分かっている別のネットワークで実行する場合だけです。

注意点とトラブルシューティングについては、Bonjour 検出を参照してください。

# ストレージと永続化

Docker Compose は OPENCLAW_CONFIG_DIR を /home/node/.openclaw に、 OPENCLAW_WORKSPACE_DIR を /home/node/.openclaw/workspace にバインドマウントするため、 これらのパスはコンテナ置換後も残ります。どちらかの変数が未設定の場合、バンドル済みの docker-compose.yml は ${HOME}/.openclaw（ワークスペースマウントには ${HOME}/.openclaw/workspace）にフォールバックし、HOME 自体もない場合は /tmp/.openclaw にフォールバックします。これにより、最小環境で docker compose up が ソースが空のボリューム仕様を出力するのを防ぎます。

そのマウントされた設定ディレクトリに OpenClaw が保持するもの:

• 動作設定用の openclaw.json
• 保存されたプロバイダーの OAuth/API キー認証用の agents/<agentId>/agent/auth-profiles.json
• OPENCLAW_GATEWAY_TOKEN など、環境変数由来のランタイムシークレット用の .env

インストール済みのダウンロード可能なPluginは、マウントされた OpenClaw ホーム配下にパッケージ状態を保存するため、Pluginインストール記録とパッケージルートは コンテナ置換後も残ります。Gateway 起動時に、バンドル済みPluginの依存関係ツリーは生成されません。

VM デプロイでの完全な永続化の詳細については、 Docker VM ランタイム - 何がどこに永続化されるかを参照してください。

ディスク増加のホットスポット: /tmp/openclaw/ 配下の media/、セッション JSONL ファイル、 cron/runs/*.jsonl、インストール済み Plugin パッケージルート、ローテーションされるファイルログを監視します。

# シェルヘルパー (任意)

日常的な Docker 管理を簡単にするには、ClawDock をインストールします。

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

古い scripts/shell-helpers/clawdock-helpers.sh raw パスから ClawDock をインストールしていた場合は、上のインストールコマンドを再実行して、ローカルのヘルパーファイルが新しい場所を追跡するようにしてください。

その後、clawdock-start、clawdock-stop、clawdock-dashboard などを使用します。すべてのコマンドについては clawdock-help を実行してください。 完全なヘルパーガイドは ClawDock を参照してください。

export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

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

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

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

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
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"]

# VPS で実行しますか？

バイナリの焼き込み、永続化、更新を含む共有 VM デプロイ手順については、Hetzner (Docker VPS) と Docker VM Runtime を参照してください。

# Agent sandbox

Docker バックエンドで agents.defaults.sandbox を有効にすると、Gateway 自体はホスト上に残したまま、Gateway は agent tool 実行 (shell、ファイル読み書きなど) を分離された Docker コンテナ内で実行します。これにより、Gateway 全体をコンテナ化せずに、信頼できない agent セッションやマルチテナントの agent セッションの周囲に堅い壁を設けられます。

sandbox のスコープは、agent ごと (デフォルト)、セッションごと、または共有にできます。各スコープには /workspace にマウントされる専用のワークスペースがあります。allow/deny tool ポリシー、ネットワーク分離、リソース制限、ブラウザ コンテナも設定できます。

完全な設定、イメージ、セキュリティメモ、マルチエージェントプロファイルについては、次を参照してください。

• Sandboxing -- 完全な sandbox リファレンス
• OpenShell -- sandbox コンテナへの対話型 shell アクセス
• Multi-Agent Sandbox and Tools -- agent ごとの上書き

# クイック有効化

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}

デフォルトの sandbox イメージをビルドします (ソース checkout から):

scripts/sandbox-setup.sh

ソース checkout のない npm インストールでは、インラインの docker build コマンドについて Sandboxing § Images and setup を参照してください。

# トラブルシューティング

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>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

# 関連

• Install Overview — すべてのインストール方法
• Podman — Docker の代替としての Podman
• ClawDock — Docker Compose コミュニティセットアップ
• Updating — OpenClaw を最新に保つ
• Configuration — インストール後の Gateway 設定