Dockerを使用したGatewayのセットアップ

開発を進めていると、「自分のPCでは動くのに、サーバーにデプロイすると動かない」という問題に直面することがあります。環境の違いによって発生するバグは、修正に時間がかかり、開発のスピードを落とす原因になります。こうした環境の差異をなくすためにコンテナ技術は便利ですが、常に導入すべきか迷うこともあるはずです。

今回のガイドでは、Gatewayの構築においてDockerをどのように扱うべきか、その判断基準を説明します。

必要なもの

この手順を進める前に、以下の準備ができているか確認してください。

• Docker（Gatewayをコンテナ化する場合、またはDocker flowを検証する場合のみ）

クイックスタート

Dockerの使用は**任意（optional）**です。以下の2つのケースに当てはまる場合のみ、Dockerを利用してください。

1. Gatewayをコンテナ化して運用したい場合
2. Docker flowが正しく動作するか検証したい場合

これらが必要ない場合は、Dockerを使わずにセットアップを進めても問題ありません。

トラブルシューティング

ソースドキュメントに記載されている既知の問題はありません。Dockerを利用する過程で設定に迷った場合は、Dockerの使用自体が必須ではない（optionalである）点に注目してください。

結び

セットアップに関する不明点がある場合は、AI Setup Assistant を活用してください。

次のステップ

• Gateway の基本設定
• API リファレンス

開発環境のセットアップで、自分のPCがツールや依存関係で散らかってしまうのは避けたいですよね。「一度試してみたいだけなのに、ローカル環境を汚したくない」と感じることはよくあります。

また、プロジェクトごとに異なるバージョンを管理する手間や、特定のOSだけで発生する奇妙なバグに悩まされるのも、開発者なら誰もが通る道です。こうした環境構築のストレスを最小限に抑えるための選択肢として、Dockerがあります。

## 必要なもの

セットアップを始める前に、以下の準備ができているか確認してください。

- Docker Desktop（または Docker Engine） + Docker Compose v2
- イメージとログを保存するための十分なディスク容量

## クイックスタート

Dockerを使うかどうかは、あなたの現在の状況と目的に合わせて選ぶのがベストです。

### Dockerを使うべきケース
- 環境を完全に分離し、使い終わったらすぐに捨てられる Gateway 環境が欲しい場合
- ローカルマシンに何もインストールせずに、ホスト上で OpenClaw を動かしたい場合

### ローカルインストールを選ぶべきケース
- 自分のマシンで作業していて、とにかく最速の dev loop（開発サイクル）を回したい場合。この場合は、通常のインストールフローを利用してください。

このガイドでは、以下の2つのパターンをカバーしています。
- **Containerized Gateway**: Docker 内で OpenClaw の全機能を持たせる構成
- **Per-session Agent Sandbox**: ホスト側の Gateway と、Docker で分離されたエージェントツールを組み合わせる構成

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

ソースドキュメントで言及されている、よくある混乱ポイントを確認しておきましょう。

**「Sandboxing を使うには、Gateway も Docker で動かす必要がありますか？」**
いいえ、その必要はありません。エージェントの Sandboxing 機能自体は Docker を使用しますが、Gateway 本体まで Docker で動かす必要はありません。ホスト上で Gateway を動かしながら、エージェントツールだけを Docker で分離することが可能です。

詳細については [Sandboxing](/docs/gateway/sandboxing) のドキュメントを参照してください。

セットアップに関する具体的な質問がある場合は、[AI Setup Assistant](/docs/) がお答えします。

## 次のステップ

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

新しいツールを導入する際、ローカル環境が依存関係で散らかるのは避けたいですよね。特に、開発環境のセットアップに時間を取られて、本来やりたかった実装に中々辿り着けないのは、多くの開発者が経験する悩みです。

Docker を使えば、環境を汚さずに一貫性のある Gateway を素早く立ち上げることができます。依存関係のトラブルに悩まされることなく、すぐに開発をスタートしましょう。

## 必要なもの

- Docker および Docker Compose
- リポジトリのルートディレクトリでの操作権限

## クイックスタート

最も推奨される方法は、リポジトリのルートからセットアップスクリプトを実行することです。5分もかからずに完了します。

```bash
./docker-setup.sh

このスクリプトは以下の処理を自動で行います：

• Gateway イメージのビルド
• オンボーディング・ウィザードの実行
• プロバイダー設定のヒント表示
• Docker Compose による Gateway の起動
• Gateway トークンの生成と .env への書き込み

オプションの環境変数

ビルドや実行の挙動をカスタマイズしたい場合は、以下の環境変数が利用できます：

• OPENCLAW_DOCKER_APT_PACKAGES — ビルド中に追加の apt パッケージをインストールします
• OPENCLAW_EXTRA_MOUNTS — ホスト側のバインドマウントを追加します
• OPENCLAW_HOME_VOLUME — /home/node を名前付きボリュームで永続化します

完了後の手順：

1. ブラウザで http://127.0.0.1:18789/ を開きます。
2. 生成されたトークンを Control UI（Settings → token）に貼り付けます。
3. URL を再確認したい場合は、docker compose run --rm openclaw-cli dashboard --no-open を実行してください。

設定とワークスペースはホスト側の以下のパスに保存されます：

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

VPS（Hetzner など）で実行する場合は、Hetzner (Docker VPS) を参照してください。

手動での実行手順 (Manual flow)

スクリプトを使わずに手動で進めたい場合は、以下のコマンドを順番に実行してください。

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

OPENCLAW_EXTRA_MOUNTS や OPENCLAW_HOME_VOLUME を有効にしている場合、セットアップスクリプトによって docker-compose.extra.yml が生成されます。その場合は、コマンド実行時にこのファイルを含める必要があります。

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

便利なシェルヘルパー (ClawDock)

日々の 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

zsh の設定に追加する場合:

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

これで clawdock-start、clawdock-stop、clawdock-dashboard などのコマンドが使えるようになります。詳細は ClawDock Helper README を確認してください。

高度なカスタマイズ

追加のマウント設定

ホストのディレクトリをコンテナにマウントしたい場合は、OPENCLAW_EXTRA_MOUNTS を設定してから docker-setup.sh を実行します。

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

パッケージの追加

ビルドツールやメディアライブラリが必要な場合は、OPENCLAW_DOCKER_APT_PACKAGES を使用します。

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

パワーユーザー向けのフル機能設定

デフォルトのイメージはセキュリティを優先し、非 root の node ユーザーで動作します。Playwright ブラウザなどを利用したい場合は、以下の設定を組み合わせてください。

1. /home/node の永続化:

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

2. Playwright ブラウザのインストール:

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

Channel のセットアップ

CLI コンテナを使用して Channel を設定できます。設定後は Gateway を再起動してください。

WhatsApp (QRコード):

docker compose run --rm openclaw-cli channels login

Telegram (Bot トークン):

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

詳細は WhatsApp、Telegram、Discord のドキュメントをご覧ください。

トラブルシューティング

認証エラー・ペアリングの要求

「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 で権限エラーが出る場合は、ホスト側のマウントディレクトリの所有者を確認してください。

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

OpenAI Codex OAuth (ヘッドレス環境)

Docker などのヘッドレス環境で OAuth を使用すると、コールバック URL でエラーが表示されることがあります。その場合は、ブラウザのアドレスバーにあるリダイレクト URL 全体をコピーし、ウィザードに貼り付けてください。

ヘルスチェックとテスト

コンテナが正常に動作しているか確認するには、以下のコマンドを使用します。

ヘルスチェック:

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

E2E テスト:

scripts/e2e/onboard-docker.sh

セットアップで困ったことがあれば、AI Setup Assistant に聞いてみてください。

次のステップ

• Dashboard の使い方
• CLI デバイス管理
• WhatsApp 連携の設定
• Telegram Bot の追加

エージェントにツールを使わせるとき、ローカル環境が汚れたり、予期しない操作をされたりするのが心配になりますよね。セキュリティを保ちつつ、エージェントに自由にコードを実行させるには、適切な隔離環境が必要です。

開発者にとって、実行環境のクリーンさを保ちながら、エージェントに強力な権限を与えるのは常に頭を悩ませるポイントです。そこで役立つのが、Docker を活用した Agent Sandbox です。

必要なもの

セットアップを始める前に、以下の準備ができているか確認してください。

• Docker がインストールされ、動作していること
• OpenClaw Gateway の基本設定が完了していること
• openclaw-sandbox:bookworm-slim イメージ（提供されているスクリプトでビルド可能です）

クイックスタート

まずは最小限の構成で Sandbox を動かしてみましょう。5分ほどで完了します。

1. イメージのビルド 以下のスクリプトを実行して、ベースとなるイメージを作成します。

   scripts/sandbox-setup.sh

2. 設定の有効化 設定ファイル（JSON5）で Sandbox を有効にします。

   {
     agents: {
       defaults: {
         sandbox: {
           mode: "non-main", // non-main セッションで Sandbox を有効化
           scope: "agent",   // エージェントごとにコンテナを分離
           workspaceAccess: "none" // デフォルトの隔離設定
         }
       }
     }
   }

3. ツールの実行 これで、エージェントが実行するツールは Docker コンテナ内で隔離された状態で動作するようになります。

Agent Sandbox の仕組み

agents.defaults.sandbox を有効にすると、メイン以外のセッションで実行されるツールは Docker コンテナ内で動作します。Gateway 自体はホストマシン上で動作し続けますが、ツールの実行だけが切り離される仕組みです。

スコープと隔離レベル

隔離の単位（scope）は、ニーズに合わせて以下の 3 つから選択できます。

• "agent"（デフォルト）: エージェントごとに 1 つのコンテナとワークスペースを作成します。
• "session": セッションごとに完全に隔離します。
• "shared": 注意！ クロスセッションの隔離が無効になり、すべてのセッションで 1 つのコンテナとワークスペースを共有します。

ワークスペースへのアクセス

workspaceAccess 設定により、ホスト側のファイルをどのように扱うかを制御できます。

• "none": ~/.openclaw/sandboxes を使用し、ホストのワークスペースには触れません。
• "ro": ホストのワークスペースを /agent に読み取り専用でマウントします。write や edit などの書き込みツールは無効化されます。
• "rw": ホストのワークスペースを /workspace に読み書き可能な状態でマウントします。

詳細な設定オプション

セキュリティを強化するための「ハードニング」オプションが多数用意されています。これらは agents.defaults.sandbox.docker の下で設定可能です。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "agent",
        workspaceAccess: "none",
        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"],
      },
    },
  },
}

ツールポリシー（Allow/Deny）

ツールの利用許可は以下のルールに従います。

• deny リストにあるツールは、常に allow より優先して拒否されます。
• allow が空の場合、deny 以外のすべてのツールが使用可能です。
• allow が指定されている場合、そこに記載されたツールのみが使用可能です（deny を除く）。

コンテナのクリーンアップ（Pruning）

リソースを節約するために、古いコンテナを自動で削除する設定が可能です。

• prune.idleHours: 指定時間使われなかったコンテナを削除します。
• prune.maxAgeDays: 作成から指定日数が経過したコンテナを削除します。

ブラウザツールのサンドボックス化

ブラウザツールを Sandbox 内で動かすには、専用のイメージをビルドする必要があります。

scripts/sandbox-browser-setup.sh

このイメージは Chromium を含んでおり、headless: false の場合は Xvfb を介して動作します。

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

トラブルシューティング

よくある問題と解決策をまとめました。

• setupCommand でパッケージがインストールできない

  • デフォルトでは docker.network が "none" になっています。外部通信が必要な場合は設定を変更してください。
  • readOnlyRoot: true が設定されているとインストールに失敗します。
  • user が root である必要があります（user: "0:0" を指定するか、指定を省略してください）。

• 設定を変更したのに反映されない

  • コンテナが「ホット（最近 5 分以内に使用された）」な状態だと、自動再作成が行われないことがあります。その場合は、ログに表示される openclaw sandbox recreate ... コマンドを手動で実行してください。

最後に

Docker を活用した Sandbox 環境を構築することで、エージェントの利便性を損なうことなく、ホスト環境の安全を守ることができます。より詳細な情報は、以下のリンクも参考にしてください。

さらに詳しい設定や、個別のユースケースに合わせたアドバイスが必要な場合は、AI Setup Assistant を活用してください。

次のステップ

• Sandboxing の詳細
• マルチエージェントでの Sandbox とツール設定

---
title: "OpenClaw トラブルシューティングガイド"
description: "OpenClaw のセットアップや実行中に発生する一般的な問題と、その解決方法について解説します。"
---

開発環境のセットアップ中に予期せぬエラーに遭遇すると、作業が止まってしまいストレスを感じますよね。特に Sandbox 環境やコンテナが絡む設定は、一見正しく見えても細かな箇所の不一致で動かないことがよくあります。

スムーズに開発を再開できるよう、よくある問題と解決策をまとめました。

## 必要なもの

作業を始める前に、以下の準備ができているか確認してください。

- OpenClaw のリポジトリ
- Docker が動作する環境

## クイックスタート

まずは、最小限の手順で環境を整えましょう。

1. [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) を実行して、必要なイメージをビルドします。
2. 特定のイメージを使用する場合は、`agents.defaults.sandbox.docker.image` を設定してください。

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

### Image missing
イメージが見つからない場合は、[`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) を使用してビルドを行うか、`agents.defaults.sandbox.docker.image` に正しいイメージ名を設定してください。

### Container not running
コンテナが起動していないように見えても心配ありません。コンテナはセッションごとにオンデマンドで自動作成される仕様になっています。

### Permission errors in sandbox
Sandbox 内で権限エラーが発生する場合は、`docker.user` をマウントされたワークスペースの所有権と一致する UID:GID に設定してください。または、ワークスペースフォルダに対して chown を実行して所有権を変更してください。

### Custom tools not found
OpenClaw は `sh -lc`（ログインシェル）でコマンドを実行します。このとき `/etc/profile` が読み込まれるため、PATH がリセットされることがあります。
カスタムツールが見つからない場合は、以下のいずれかの方法を試してください。

- `docker.env.PATH` を設定し、カスタムツールのパス（例: `/custom/bin:/usr/local/share/npm-global/bin`）を先頭に追加する。
- Dockerfile 内で `/etc/profile.d/` 以下にパスを設定するスクリプトを追加する。

解決しない問題がある場合は、[AI Setup Assistant](/docs/) に相談してみてください。

## 次のステップ

- [sandbox-setup.sh を確認する](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh)
- [Docker 設定の構成ガイド](/docs/gateway/configuration-reference/)