Docker / Compose 上で OpenClaw Gateway を動かすチームが最も時間を溶かすのは、イメージの pull ではなく、再起動・アップグレード・docker compose down でペアリングや設定が消えることや、Skills ディレクトリが読み取り専用で公式トラブルシュートのネットワーク項目と噛み合わない Permission denied の連発です。本稿は Docker ネットワーク切り分け、インストール後の doctor 切り分け、Docker 本番と Gateway 運用、無人リモート Mac 運用と役割分担します。ボリューム／権限の落とし穴六つ、永続対象とアンチパターンの表二枚、症状→コマンド→修正のマトリクス、コピペ用 inspect スニペット、六ステップの手順、ダッシュボード向け指標三つをまとめます。切り分け順は まずボリュームと UID/GID、次にネットワークとリバースプロキシです。
イメージは不変のテンプレートです。書き込み可能レイヤー、anonymous ボリューム、永続化されていないパスにだけ書かれた状態は消えます。以下のシグナルを変更チケットに記録し、Compose の改訂やイメージタグと同じ行でレビューしてください。
down -v やクリーンアップで「git は変えていないのに」ペアリングキャッシュが消えます。user を調整せずに Compose を流用するのは典型失敗です。:ro にすると、上流例が想定するトークンキャッシュやローカル状態が書けません。再起動まで気づかないこともあります。docker commit は魅力的に見えますが、タグ変更でそのレイヤーは捨てられます。本番では避けてください。ネットワーク切り分けでは CLI が不安定に成功するのに再起動後は必ず失敗する場合は、network_mode やプロキシに触る前に、名前付きボリュームが想定ディスクに載り、プロセスユーザーが Skills に書けるかをここで確認し直してください。
サブパスはイメージとドキュメントに従います。表が問うのは 三つの設計問い：コンテナライフサイクルを越えて残るか、バックアップが要るか、共有の読み取り専用でよいかです。README とオンコール手順書に答えを残してください。
| 分類 | 永続化の典型内容 | 推奨パターン | アンチパターン |
|---|---|---|---|
| 設定とシークレット素材 | Gateway エンドポイント、プロバイダ選択、チャネルトークンのパス | ホスト bind または名前付きボリューム。実行ユーザーに合わせた権限 | イメージに焼き込む。同期ツールが掃除する配下に置く |
| ランタイムとペアリング | デバイスペアリングとセッション復元の状態 | 専用の bind サブツリー。アップグレード前に tar | Compose に文書化されていない anonymous ボリューム。単一の prune で全消去 |
| Skills／拡張 | チーム所有のスキルファイルとスクリプト | リポジトリ横に bind。CI と本番でパスを一致 | ランタイムキャッシュが書ける必要があるのに :ro。UID が書けない |
| ログとバッファ | 大きなログ、エクスポート | 別ボリュームまたはローテーション付きホストパス | 書き込みレイヤーを埋めて OOM や想定外の読み取り専用 FS にする |
確認中は 同じシェルセッションでイメージ ID、Compose プロジェクト名、ボリューム名をログに残し、ロールバックを簡単にしてください。本番運用のリリースチェックリストも再利用します。
| 症状 | 最初に確認 | 典型的な修正 | まだダメなら |
|---|---|---|---|
docker compose up のたびに新規インストールのようだ | docker inspect の Mounts と期待ホストパス。最近の -v 掃除 | 明示的 bind または名前付きボリューム。down で -v を使うか文書化 | 正しい Compose プロジェクトディレクトリにいるか確認 |
| Skills が無視される／書き込み失敗 | コンテナ内 id とホスト ls -ln の所有者 | user、chmod、Dockerfile／entrypoint で UID を揃える | マウントが :ro でないか確認 |
| 権限エラーが連続 | Linux の SELinux／AppArmor。macOS の Docker Desktop ファイル共有 | Linux：セキュリティ基準に沿ってラベルや :z を評価。macOS：ファイル共有にパス追加 | ディスク全体の読み取り専用を切り分けてからネットワークに戻る |
| イメージ更新後に半端に動く | 設定スキーマ変更。古いデータディレクトリがまだマウントされている | リリースノートに従い、アップグレード前にバックアップ | 破壊的変更を openclaw doctor で照合 |
# 1) マウントは期待するホストパスに載っているか？（コンテナ名は置換）
docker inspect -f '{{ json .Mounts }}' <container> | jq .
# 2) コンテナ内の実行ユーザー（ホスト所有者と比較）
docker exec -it <container> id
# 3) Compose プロジェクトとボリューム（anonymous のドリフト回避）
docker compose ls
docker volume ls | grep <project>
# 4) アップグレード前の bind バックアップ例（パスはチーム規約に合わせる）
tar czf openclaw-state-$(date +%Y%m%d).tgz ./openclaw-data/
補足：リモート Mac 上の Docker Desktop では、bind は多くの場合ユーザーホーム配下に収まります。Linux クラウドホストでは user 行と権限モデルが異なることがあります。「手元のノートで動いた」が「プールされたホストでも動く」とは限りません。
down -v が壊すものを明記します。openclaw doctor とチャネルプローブを実行し、偽陰性を避けます。Permission denied／EACCES をフィルタし、Gateway アップグレードと相関すれば多くはマウント側の問題です。リモート Mac 運用の記事のディスク・ログ指標と並べてください。ボリューム問題は CPU スパイクの前に、ディスク肥大や読み取り専用マウントとして現れがちです。
多くのチームが 2025〜2026 年に Gateway と Skills を同一ホストツリーに置きます。ログ専用サブツリーにクォタがないと、ログが bind を埋めて設定書き込みを阻むことがあります。コンテナを作り直し続ける前にローテーションかボリューム分割をしてください。
docker compose restart と down／up も区別してください。前者は宣言されたボリュームを多くの場合保持し、後者はクリーンフラグ次第でデータの行方が変わります。運用では動詞のチートシートを共有してください。
単一ユーザーのノートの権限は、自動ログインのプールされたリモートホストとは異なります。スリープ、同期ユーティリティ、手動の bind 編集が「昨日は動いた」を再現不能にします。OpenClaw を 24/7 の制御面として運用するには 契約されたパス、巻き戻し可能なアップグレード、監査可能な権限が必要です。
個人機材での学習ループは問題ありませんが、本番コストはページャと死んだチャネルとして現れます。安定マウントのない短命スクラッチコンテナはアップグレード時に失敗領域を増やします。常時オン、バックアップ向き、持ち運びやすい Gateway が必要なチームは、個人 Docker の無限調整より、Apple Silicon ベアメタルとマルチリージョン選択のプロ用 Mac クラウドに早く収束しがちです。MACCOME は地域横断の Mac mini M4 / M4 Pro レンタルと公開ヘルプを提供しています。ヘルプセンターと料金から始め、リージョン別のチェックアウトを選んでください。
ロールアウトのコツ：チャネルとモデルを配線する前に、本番と同じホスト種別（Docker Desktop か Linux）で表2の確認を走らせ、「ローカルでは動くがクラウドでは失敗する」UID とパスのズレを避けます。
Kubernetes も併用する場合、Pod は Compose より頻繁に入れ替わります。PVC に載っていないものはローリング更新で消えます。明示的永続化の原則は同じで、kubectl describe pvc とマウントマニフェストで検証してください。
FAQ
Docker ネットワーク切り分けの記事と何が違いますか？
ネットワークは接続性と名前空間を扱い、本稿はディスク上のデータと書き込み可否を扱います。インストールの入口は三プラットフォーム導入ガイドを参照してください。接続と料金：ヘルプセンターとレンタル料金です。
doctor とボリューム、どちらを先にしますか？
まずボリュームと権限、その後 doctor です。コンテナを作り直し続けると偽陽性になります。WSL2 の詳細はインストール後 doctor の記事にあります。
リモート Mac 運用の記事とどう組み合わせますか？
そちらは launchd／systemd、ログ、ハング切り分けを扱い、本稿は Docker の永続性と書き込み可否を扱います。どちらも同一の変更レビューとオンコール索引に入れてください。