Docker

Dockerは任意です。分離された使い捨てのGateway環境、またはローカルインストールがないホストで使用します。すでに自分のマシンで開発している場合は、代わりに通常のインストールフローを使用してください。

デフォルトのサンドボックスバックエンドは、agents.defaults.sandbox が有効な場合にDockerを使用しますが、サンドボックス化はデフォルトでオフであり、Gateway自体をDockerで実行する必要はありません。SSHおよびOpenShellサンドボックスバックエンドも利用できます。サンドボックス化を参照してください。

前提条件

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

コンテナ化されたGateway

./scripts/docker/setup.sh

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

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

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

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

# WhatsApp (QR)docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker 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-daemondocker 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

環境変数

scripts/docker/setup.sh が受け付ける任意の変数（Gatewayコンテナについては docker-compose.yml が直接受け付ける変数）:

公式イメージにはHomebrewは含まれません。オンボーディング中、OpenClawは brew のないLinuxコンテナ内で、brew専用のSkill依存関係インストーラーを非表示にします。これらの依存関係はカスタムイメージで提供するか、手動でインストールしてください。Debianパッケージ化された依存関係には OPENCLAW_IMAGE_APT_PACKAGES を、Python依存関係には OPENCLAW_IMAGE_PIP_PACKAGES を使用してください（ビルド時に python3 -m pip install --break-system-packages を実行するため、バージョンを固定し、信頼できるインデックスのみを使用してください）。

Dockerが ResourceExhausted、cannot allocate memory を報告する、または tsdown 中に中止する場合は、Dockerビルダーのメモリ制限を増やすか、より小さい明示的なヒープで再試行してください:

OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096

パッケージ化されたイメージに対してバンドル済みPluginソースをテストするには、1つの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ポートは不要です。ローカルでビルドしたイメージにバンドル済みエクスポーターを含めるには:

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

公式の事前ビルド済みイメージにはすでに diagnostics-otel が含まれています。削除した場合のみ、自分で clawhub:@openclaw/diagnostics-otel をインストールしてください。エクスポートを有効にするには、設定で 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   # livenesscurl -fsS http://127.0.0.1:18789/readyz     # readiness

イメージに組み込まれた HEALTHCHECK は /healthz にpingします。失敗が繰り返されると、コンテナは unhealthy とマークされ、オーケストレーターが再起動または置換できるようになります。

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

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

LAN vs loopback

scripts/docker/setup.sh はデフォルトで OPENCLAW_GATEWAY_BIND=lan を設定するため、Dockerポート公開により、ホスト上の http://127.0.0.1:18789 が動作します。

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

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

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

同梱のセットアップは、これらの URL を LM Studio/Ollama オンボーディングのデフォルトとして使用し、docker-compose.yml は Linux Docker Engine 上で host.docker.internal をホスト Gateway にマッピングします (Docker Desktop は macOS/Windows で同じエイリアスを提供します)。ホストサービスは Docker が到達できるアドレスで待ち受ける必要があります。

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

独自の Compose ファイルまたは docker run を使用していますか？ 同じマッピングを自分で追加してください。例: --add-host=host.docker.internal:host-gateway。

Docker の Claude CLI バックエンド

公式イメージには Claude Code は事前インストールされていません。コンテナの node ユーザー内でインストールしてログインし、そのコンテナホームを永続化して、イメージのアップグレードでバイナリや認証状態が消えないようにします。

新規インストールでは、セットアップを実行する前に永続的な /home/node ボリュームを有効にします。

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

既存のインストールでは、まずスタックを停止し、現在の .env 値を再読み込みします。セットアップスクリプトは常に現在のシェルとデフォルトから .env を書き換え、ファイルを自分では読み取りません。

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

.env にシェルで source できない値が含まれている場合は、依存している値を先に手動で再 export してください (OPENCLAW_IMAGE、ポート、バインドモード、カスタムパス、OPENCLAW_EXTRA_MOUNTS、sandbox、skip-onboarding)。生成された overlay は openclaw-gateway と openclaw-cli の両方にホームボリュームをマウントします。残りのコマンドはその overlay で実行してください (使用している場合は docker-compose.override.yml を先に指定します)。

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

ネイティブインストーラーは claude を /home/node/.local/bin/claude に書き込みます。OpenClaw にそのパスを指定します。

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

同じ永続化されたホームからログインして検証します。

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

その後、同梱の claude-cli バックエンドを使用します。

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "Say hello from Docker Claude CLI"

OPENCLAW_HOME_VOLUME は、/home/node/.local/bin と /home/node/.local/share/claude にあるネイティブインストールに加え、/home/node/.claude と /home/node/.claude.json にある Claude Code の設定/認証を永続化します。/home/node/.openclaw だけを永続化しても不十分です。ホームボリュームではなく OPENCLAW_EXTRA_MOUNTS を使用する場合は、これらすべての Claude パスを両方のサービスにマウントしてください。

Bonjour / mDNS

Docker ブリッジネットワークは通常、Bonjour/mDNS マルチキャスト (224.0.0.251:5353) を安定して転送しません。OPENCLAW_DISABLE_BONJOUR が未設定の場合、同梱の Bonjour Plugin はコンテナ内で実行されていることを検出すると LAN 広告を自動的に無効化するため、ブリッジが破棄するマルチキャストを再試行してクラッシュループすることはありません。検出結果に関係なく強制的にオフにするには OPENCLAW_DISABLE_BONJOUR=1 を設定し、強制的にオンにするには 0 を設定します (ホストネットワーク、macvlan、または mDNS マルチキャストが機能することが分かっている別のネットワークでのみ)。

それ以外の Docker ホストでは、公開された Gateway URL、Tailscale、または広域 DNS-SD を使用してください。注意点とトラブルシューティングについては Bonjour 検出 を参照してください。

ストレージと永続化

Docker Compose は OPENCLAW_CONFIG_DIR を /home/node/.openclaw に、OPENCLAW_WORKSPACE_DIR を /home/node/.openclaw/workspace に、OPENCLAW_AUTH_PROFILE_SECRET_DIR を /home/node/.config/openclaw にバインドマウントするため、これらのパスはコンテナの置き換え後も残ります。変数が未設定の場合、docker-compose.yml は ${HOME} 配下にフォールバックし、HOME 自体がない場合は /tmp にフォールバックするため、素の環境でも docker compose up が空のソースボリューム指定を出力することはありません。

そのマウントされた設定ディレクトリには以下が含まれます。

• 挙動設定用の openclaw.json

• 保存済みプロバイダー OAuth/API キー認証用の agents/<agentId>/agent/auth-profiles.json

• OPENCLAW_GATEWAY_TOKEN などの env ベースのランタイムシークレット用の .env

  auth-profile シークレットディレクトリは、OAuth に裏付けられた認証プロファイルのトークンマテリアル用ローカル暗号化キーを保存します。Docker ホスト状態と一緒に保持しますが、OPENCLAW_CONFIG_DIR とは分離してください。

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

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

  ディスク増加のホットスポット: media/、セッション JSONL ファイル、共有 SQLite 状態データベース、インストール済み Plugin のパッケージルート、/tmp/openclaw/ 配下のローテーションファイルログ。

  シェルヘルパー（任意）

  日常的なコマンドを短くするには、ClawDock をインストールします。

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

  古い scripts/shell-helpers/clawdock-helpers.sh パスからインストールしていた場合は、上のコマンドを再実行して、ローカルヘルパーが現在の場所を追跡するようにしてください。その後、clawdock-start、clawdock-stop、clawdock-dashboard などを使用します（完全な一覧は clawdock-help を実行してください）。

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

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

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

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

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

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

VPS で実行しますか？

バイナリのベイク、永続化、更新を含む共有 VM デプロイ手順については、Hetzner (Docker VPS) と Docker VM ランタイムを参照してください。

エージェントサンドボックス

Docker バックエンドで agents.defaults.sandbox が有効な場合、gateway 自体はホスト上に残したまま、Gateway はエージェントツール実行（シェル、ファイルの読み書きなど）を分離された Docker コンテナー内で実行します。これにより、Gateway 全体をコンテナー化せずに、信頼されていない、またはマルチテナントのエージェントセッションの周囲に強固な壁を作ります。

サンドボックスのスコープは、エージェント単位（デフォルト）、セッション単位、または共有にできます。各スコープには /workspace にマウントされた専用ワークスペースが割り当てられます。許可/拒否のツールポリシー、ネットワーク分離、リソース制限、ブラウザーコンテナーも設定できます。

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

• サンドボックス化 -- 完全なサンドボックスリファレンス
• OpenShell -- サンドボックスコンテナーへの対話型シェルアクセス
• マルチエージェントサンドボックスとツール -- エージェント単位のオーバーライド

クイック有効化

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

デフォルトのサンドボックスイメージをビルドします（ソースチェックアウトから）。

scripts/sandbox-setup.sh

ソースチェックアウトなしで npm インストールを使用する場合は、インラインの docker build コマンドについて サンドボックス化 § イメージとセットアップを参照してください。

トラブルシューティング

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker 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

関連

• インストール概要 — すべてのインストール方法
• Podman — Docker の代替となる Podman
• ClawDock — Docker Compose コミュニティセットアップ
• 更新 — OpenClaw を最新の状態に保つ
• 設定 — インストール後の gateway 設定