2026 OpenClaw ヘッドレス Linux Docker：オンボード停止、pending.json と dashboard --no-open 検証ランブック

約16分で読めます · MACCOME

OpenClaw をデスクトップもブラウザもない ヘッドレス Linux VPS で Docker のみ運用していて、ウィザードや onboard が pending のまま、ローカルブラウザを開くようログが促す、または DISPLAY がなく dashboard が失敗する、といった場面では、本稿が変更チケットにそのまま貼れるヘッドレス合格ラダーになります。compose の経路と TOKEN の単一の正を一度に固定し、「Control UI を見た」をdashboard --no-open、gateway status/probe、構造化ログへ置き換えます。三 OS インストール総覧、Windows Docker トリアージ、Docker なし Linux systemd と Tunnel、Compose ペアリング 1006／1008を補い、本番のアンカーはSSH 転送の専用 Gatewayと組み合わせます。

ヘッドレス Linux Docker で OpenClaw を誤って失敗と見なしがちな六つのパターン

  1. 「ブラウザを開くことが必須」と合格を定義する：ヘッドレスではテスト設計が誤りであり Gateway の単独故障とは限りません。CLI 契約で検証します。
  2. オンボード経路と compose を二重化する：入口が二つあると pending.json や環境変数が半端に書き込まれ、pending の不安定化や TOKEN のずれが起きます（根はCompose ペアリング記事と同じです）。
  3. サイレント／ヘッドレス用スイッチの欠落：ウィザードは対話待ちのままに見え、ヘルスチェックだけが緑に見えることがあります。
  4. cgroup、グラフドライバ、既定の ulimits：小規模 VPS では OOM や fd 枯渇があり、WebSocket 1006 と取り違えられます。
  5. 企業 MITM や透明プロキシ：イメージ pull は成功しても TLS ハンドシェイクが壊れることがあります。期待する TLS とトラストストアを確認します。
  6. Windows の対処を Linux にそのまま流用する：WSL2 や Docker Desktop の前提は Linux エンジンと異なります。インストール後 doctor トリアージの「エンジン優先」の順序に従ってください。

ヘッドレスの利点は攻撃面の縮小と自動化の強化です。合格判定がブラウザクリックに依存したままでは、デスクトップの混沌を SSH セッションへ移しただけになります。Docker 本番ランブックを読むときも、イメージタグ、compose のハッシュ、TOKEN の注入先を同一チケットにそろえてください。

チームがsystemd のベアメタルとDockerの両方を持つ場合は、既定の正（どちらが CI イメージ統合でどちらが本番か）を文書化してください。混在ホストは切り分けが最も難しいクラスです。

観点 ヘッドレス Docker（本稿） Linux systemd と Tunnel（コンテナなし）
再現とアップグレード イメージタグと compose でバージョン管理が速く、ロールバックもしやすい ディストロのパッケージとユニットに依存。カスタムは深いがイメージ再現性は弱め
ヘッドレス合格 --no-open とコンテナログドライバに自然に合う journald と curl プローブ。Docker とは経路が異なる
ネットワーク名前空間 1006／1008 がブリッジや publish の組み合わせと結びつきやすい ホストスタック。問題は Tunnel と bind に寄りやすい
専用リモート Mac との組み合わせ Gateway を専用ホストへ移せば、ノートは CLI のみでもよい 結論は同じ。運用の癖が異なる
ありがちな誤用 ラベルなしで CI と本番の compose が分岐する 同一筐体で Tunnel Gateway と Docker Gateway の「正」を頭の中で二重化する
info

注：コミュニティで語られる「pending.json の silent を true にしてブロックするウィザードを飛ばす」手法は、パイプラインに焼き込む前に現行の OpenClaw ドキュメントと突き合わせてください。アップグレード後は回帰を再実行し、silent が無音ハングにならないようにします。

ヘッドレス六段ランブック：イメージが pull できるところから gateway probe が緑になるまで

  1. 単一の入口経路を固定する：compose のみ、または公式 docker-setup のみを選び、もう一方は参照専用とします。
  2. エンジンとディスクを検証する：docker info、Docker データルートの空き容量、ulimit -n。極小 VPS では機能より先に swap や同時実行上限を調整します。
  3. オンボード／pending を扱う：ドキュメント化されたヘッドレス用スイッチを適用します。変更後はpending 関連ファイルのハッシュを CI ログへ出力し、監査証跡にします。
  4. Gateway を起動し CLI のみで確認する：openclaw gateway status → openclaw gateway probe（利用できる場合）→ openclaw dashboard --no-open。「ブラウザで見ただけ」を唯一の合格信号にしないでください。
  5. doctor を実行し免除を登録する：インストール後 doctor トリアージと項目を揃えます。免除にはオーナーと期限が必要です。
  6. 回帰を足す：コンテナ再ビルド後も同じスクリプトが 10 分以内に通ること。失敗時は compose のハッシュとイメージ digest を添えてインシデントを切ります。
bash
# 例: CLI のみの確認（compose のサービス名は環境に合わせて調整）
docker compose ps
docker compose logs -f --tail=200 openclaw-gateway

openclaw gateway status || true
openclaw dashboard --no-open || true
openclaw doctor --yes || true

SLO やオンコールメモ向けの三指標（ SKU に合わせて調整）

  • 初回プローブ成功までのコールドスタート（G2P）：compose up -d から最初の成功した gateway probe までの中央値（分）。イメージタグが変わっていないのに週次で 40% 超の悪化なら、モデルを疑う前にディスクと fd を確認します。
  • ヘッドレスホストでのブラウザ依存ステップ：目標はゼロです。DISPLAY を要する新ステップは製品化へ戻すか、開発専用 compose プロファイルへ隔離します。
  • 二重 Gateway 事象：18789 の二重 bind や TOKEN 二源アラートを数えます。二週間連続でゼロでないなら、TOKEN 二源の記事に沿ってアーキテクチャレビューを検討します。

なぜ「軽量デスクトップと VNC」や「運よくなるまで onboard を再試行」は 2026 年には割に合わないか

軽量デスクトップはパッチ面とセッション監査コストを広げます。公開 VNC は古典的な高リスクパターンです。無限に onboard を叩くと、フィールドの漂移が自動化ではなく手順の暗記の裏に隠れます。

CI と整合した監査可能な Gateway を 7×24で必要としつつ、ヘッドレス Linux は端の試行や短期 PoCに最適なとき、権威ある Gateway をドキュメント化された SSH 転送または tailnet 方針を伴う専用 Apple Silicon リモート Macへ置く方が、小規模 VPS の cgroup 限界と長く戦うより合理的なことが多いです。MACCOME は六地域で Mac mini（M4／M4 Pro）を柔軟なリースで提供しています。コミット前に公開のノードとリースのガイドでトポロジーを見積もってください。

締め：ヘッドレス合格はチャットではなく DOCKER_GATEWAY.md に属する

納品物にはcompose の版、イメージ digest、silent／pending 方針、CLI 出力サンプル、「ブラウザ不要」の明示を含めます。二台目のヘッドレスボックスで再生できない手順は、ドキュメントとして未完成です。

Windows Docker トリアージと比較するときは、ラダーは同じでホストとエンジンが異なることを忘れないでください。Docker Desktop のログパスと Linux エンジンのパスを混ぜないでください。

FAQ

ヘッドレスサーバーでオンボードが pending のままです。デスクトップ環境が必要ですか。

通常は不要です。ヘッドレス用スイッチと CLI 合格で進め、pending.json のフィールドはドキュメントと突き合わせてください。専用ノードでの本番 Gateway はレンタル料金とヘルプセンターを参照してください。

Linux Docker と systemd+Tunnel は同一マシンで共存できますか。

技術的には可能ですが、環境を分けずに運ぶと二重 Gateway／二重 TOKEN の正が起きやすいです。既定を文書化してください。Tunnel ランブックと Compose ペアリング記事も併読してください。