2026 OpenClaw 公式 Docker：`docker-setup.sh`、GHCR、Control UI（18789）Runbook

約 13 分で読めます · MACCOME

対象：公式 Docker 手順を読んでも、ローカルビルドのタイムアウト、GHCR の pull 失敗、18789 のポート衝突、Skills を止めるボリューム権限の間を行き来し、clone から Control UI まで一本の順序がないエンジニア。成果：docker-setup.sh と任意の OPENCLAW_IMAGE に統一し、Docker 本番、Docker ネットワーク、ボリューム／権限と分担する。構成：六つの落とし穴、表、六ステップ Runbook、分診表、三 KPI、まとめ。

ドキュメント通りでも Docker 経路で壊れる理由

公式フローは Docker Engine・Compose・ディスク・出口が揃う前提です。npm グローバルや別 checkout の compose と混ぜると「OpenClaw が壊れた」に見えます。2025–2026 で多い六つ：

  1. ソースビルドと GHCR pull を分けていない： 弱い CI 回線で docker build を強いる一方、OPENCLAW_IMAGE に切り替えない。
  2. 18789 に古いコンテナが残る： 前の compose 試行を止めず、新しい docker-setup.sh が Control UI をバインドできない。
  3. ボリュームの UID/GID 不一致： コンテナユーザーとホストの ~/.openclaw 権限—Skills／状態の書き込みは失敗するのに UI は「無反応」に見える。
  4. ペアリングをイメージ問題と誤読： WebSocket／token は ペアリング／token の記事—compose pull の無限ループではない。
  5. 社内プロキシが npm は通すが ghcr.io を遮断： ミラーまたはホスト名の許可；診断の型は npm インストール Runbook と同系。
  6. 複数 checkout が env／ボリュームを共有： 混在ディレクトリから古い token が残ることがある。

表 1：ローカルビルド対 OPENCLAW_IMAGE（GHCR）

変更チケットでは主経路を一つ選び、もう一方のロールバックを文書化—口頭の混線を避ける。

観点デフォルトのソースビルドOPENCLAW_IMAGE で GHCR を pull
向く場面Dockerfile の独自編集、ビルドキャッシュ調査、ghcr 出口がないUI まで最短、帯域制約、イメージはキャッシュしてリポは薄い CI
前提十分な CPU／RAM；レイヤキャッシュ用の GB 級の余裕ghcr.io または社内ミラーに到達；裸の latest だけでなくタグを pin
リスクビルドタイムアウト、キャッシュ肥大、CPU 競合認証／レート、タグのドリフト、バイナリとの設定ずれ
ロールバック事前ビルドイメージへ切替、データボリュームのパスは同じ前の digest へ戻すかソースビルドへ；compose 変更をログに残す
info

注： アップストリームは変わります。以下はリポジトリ直下に docker-setup.sh がある checkout を想定—fork が違えばコミットとスクリプトパスを記録してください。

六ステップ Runbook：clone から 18789 の Control UI まで

  1. Docker の事前確認： docker version と Compose v2；レイヤ／ボリューム用ディスク（本番のリソース表と揃える）。
  2. clone してリポジトリルートへ： docker-setup.sh が実行可能か（必要なら chmod +x）。
  3. （任意）事前ビルドイメージ： export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest—本番では digest か安定タグを pin、タグだけ追いかけない。
  4. スクリプト実行： ./docker-setup.sh；ログに pull／build と compose up が出て、すぐ非ゼロ終了しないこと。
  5. Control UI を開く： http://127.0.0.1:18789（リビジョンでポートが変わればそのビルドに従う）；接続拒否ではなくページが載ること。
  6. 最短の検証： UI か CLI のヘルスチェック；ペアリングはアプリ設定を変える前に ペアリング／token の手順へ。
bash
# GHCR の事前ビルドを優先（タグはポリシーに合わせて置換）
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

# 成功後、Control UI が載るはず（例：ポート 18789）
# open http://127.0.0.1:18789

表 2：症状 → 確認（分診の順）

上から順に。イメージ・ネットワーク・ボリュームを同時に変えない。

症状まず確認併読
ビルドタイムアウト／OOMOPENCLAW_IMAGE へ切替；buildkit の並列を抑える；キャッシュ整理Docker 本番（リソース）
pull で 401/403/TLSghcr.io のプロキシ許可；社内ミラー—npm レジストリだけではないNpm インストール Runbook（プロキシ）
address already in use :18789docker ps で古いコンテナ；古い compose を止めるかドキュメント通りにポート変更Docker ネットワーク
ボリューム書き込みで permission deniedホスト UID/GID とコンテナユーザー；名前付き／bind の違いボリューム／Skills チェックリスト
UI は開くがチャンネルが無音モデル／チャンネル層を切り分け；その後 token／WS コードペアリング／token

変更チケットとダッシュボード向け三 KPI

  1. イメージの同一性： 可能なら レジストリ＋タグ＋ digest をログに—「latest を使った」だけにしない；ロールバックは digest で。
  2. Control UI の到達性： HTTP 200／ページタイトル／ヘルスチェックを、「コンテナプロセスがある」と分けて真偽値化。
  3. ボリューム契約： ホストの ~/.openclaw（またはチームパス）を compose のマウントに対応づけ；アップグレード前後でサイズと権限をスナップショット。

アップストリームのリリースノートと矛盾したらアップストリームを正とする；本稿はエンジニアリング上のチェックポイントです。

ノート試行が本番 Gateway になりにくい理由

スリープ、断片化したディスク、Docker Desktop の残骸は、専用 CPU・安定した出口・監査可能なボリューム・token の境界と衝突します。digest を pin せず、ボリューム契約もヘルスチェックもない短命コンテナは、本番トラフィックで最初に落ちます。

安定した Apple Silicon で Gateway を長期運用するチームは、この最短ループのあと、多地域と柔軟なレンタル期間の MACCOME クラウド Mac が向きます—公開のレンタル料金とヘルプセンターを、Docker 本番とペアリング記事と併せて確認してください。

パイロット：専用リモートホストで六ステップをすべて実行し、digest とボリュームのスナップショットを記録してから、月次／四半期の条件と監視を決める。

FAQ

本稿と Docker 本番、どちらを先に？

初めて UI まで通す経路は本 Runbook；変更窓、ロールバック、監視は本番へ。料金：Mac mini レンタル料金。

OPENCLAW_IMAGE は npm グローバル CLI と衝突する？

衝突はポート・環境変数・データディレクトリに集まる；ホストあたり主 Gateway は一つ。移行の順序：npm インストール Runbook。

18789 を公開インターネットに晒していい？

手前にリバースプロキシと TLS—0.0.0.0 に盲目的にバインドせず、本番／リバプロ記事のセキュリティ節を読む。ヘルプ：クラウド Mac サポートとヘルプセンター。