OPENCLAW_2026
DOCKER_WS_
TOKEN_PAIRING_
COMPOSE_REMOTE。

// 痛み: Compose は起動していますが、ホストは動作していますopenclaw戻ってきますゲートウェイが閉じています (1008) / ペアリングが必要ですまたはログに表示されるトークンの不一致編集した後でもopenclaw.json。結果:A症状から根本原因までのマトリックス、5 段階の調整ランブック、および 3 つの引用可能なしきい値それでドッカーWebSocket ループバック、ペアリング、そして沈黙OPENCLAW_GATEWAY_TOKENオーバーライド監査可能なチェックリストになり、さらにリモート Maclaunchd とコンテナー境界線。構造: 痛み、マトリックス、5 つのステップ、構成、しきい値、FAQ、ケーススタディ、クロージャ。さらに読む:公式インストール.sh、npm / Docker / pnpm マトリックス、ゲートウェイの攻撃対象領域、移行と再ペアリング、SSH と VNC リモート Mac、計画と手助け。

Network infrastructure and connectivity

1. 痛みの分解: 間違った名前空間からのカールはあなたに嘘をつきます

(1) WS ループバックの混乱: ws://127.0.0.1:18789は正しいですホストポートが公開されているとき、ただし内部では別のコンテナそれ自体がループします。ゲートウェイがサービス名をリッスンする場合openclaw-gateway、ハードコードされた 127.0.0.1 はそれに到達しません。(2) ペアリングとトークン: pairing requiredです認可セッション問題;token mismatchです秘密の不一致;それらを混合するとランダムな編集が作成されます。(3) 環境オーバーライドファイル：シングルOPENCLAW_GATEWAY_TOKENCompose の行はマウントされたものをオーバーライドできますgateway.auth.token、「JSONを変更しましたが、何も動きませんでした」というメッセージが表示されます。(4) リモート Mac デュアル スタック: 同じポート宣言または同じ状態ディレクトリを共有する launchd plus compose では、断続的なサイレント エラーが発生します。

2. 症状マトリックス: チャネル前の認証前のトランスポートのトリアージ

信号 仮説 最初のアクション
1006/リセット 間違ったホストまたはポートの競合 からCLIと同じネットワーク名前空間、 走るnc -vz host port
1008 pairing required ペアリングが不完全 コントロール UI を開き、ペアリング コードを発行し、CLI ペア コマンドを実行します。
token mismatch 二重の真実の情報源 CLI コンテナー内で env を出力します。ボリュームJSONとの調整
不安定な成功 2 つのインスタンスが状態で競合しています docker psプラスボリュームテーブル。 1 つのゲートウェイに縮小

3. 5 ステップのランブック: ping からチャネル プローブの成功まで

  1. 名前空間の凍結: CLI がホスト、サイドカー、または CI ランナーで実行されるかどうかを文書化します。クライアントからリスナーへ 1 本の矢印を描きます。
  2. 明示的なゲートウェイベース： セットOPENCLAW_GATEWAY_URL(または文書化された同等のもの) にopenclaw-gateway:18789または公開されたホスト ポート。名前空間全体で 127.0.0.1 を想定しないでください。
  3. ペアリングゲート: ビジネス チャネルをテストする前にペアリングを完了してください。 「ペアになっていない」対「間違ったトークン」用に 2 つのチケット テンプレートを保持します。
  4. 単一トークンの信頼できる情報源：環境変数またはファイルのどちらか一方を正とし、もう一方を一致させるか削除する。
  5. チャネル プローブで受け入れる: 同じ環境から成功したプローブを 1 つ実行し、ログとスニペットの作成を変更リクエストに添付します。
# From the container that runs `openclaw` getent hosts openclaw-gateway || true nc -vz openclaw-gateway 18789 || true docker compose ps

4. network_mode: "service:openclaw-gateway" が正当な場合

デフォルト ブリッジの下で脆弱な DNS を避けるために、CLI がゲートウェイ ネットワークの名前空間を共有する必要がある場合に使用します。このコストはローカルホストのセマンティクスを混乱させます。図にしてみましょう。代替案: ホスト上で CLI を維持し、WS を 公開ホスト ポート にポイントし、TLS 終端をリバース プロキシで調整します。

# docker-compose.override.yml sketch (adapt to your release) services: openclaw-cli: network_mode: "service:openclaw-gateway" environment: OPENCLAW_GATEWAY_TOKEN: "${GATEWAY_TOKEN}" volumes: - openclaw_state:/home/node/.openclaw:ro

5.引用可能なしきい値 (実際の測定値に置き換えてください)

ディスカッション グレードの数値:

  • CLI 名前空間からの TCP 接続の成功率が 100 件のプローブで 97% を下回った場合は、機能の作業を停止し、最初に DNS、サービス名、または公開ポート を修正します。
  • 以上の値が表示された場合は、単一のペアリング ウィンドウ内の 3 つの token mismatch イベントは、そうでないことが証明されるまで、 デュアル ソース と仮定します。
  • 共有状態ディレクトリのロック待機がリモート Mac 上の p95 で 2.5 秒 を超える場合は、ボリュームを分割するか、CLI を専用のサイドカーに移動します。

6。 3 つのレイヤーで openclaw ログを読み取る

最初にトランスポート ラインをフィルタリングし、次に認証とペアリング、次にチャネル固有のラインをフィルタリングします。説明のみではなく、3 つのスクリーンショットをチケットに添付してください。公式の install.sh 記事と合わせて読む場合は、インストールの順序とネットワークの調整を 2 つの別個の受け入れゲートとして扱ってください。

レイヤ 質問 パス例
L1 トランスポート WS ハンドシェイクは成功しましたか? 不明な点はありません1006/1008
L2 認証 トークンとペアリングは一致していますか? ペアリング後に不正なループはありません
L3 チャネル チャネルはオンラインですか? channels probe は解釈可能な状態を返します

7。リモート Mac: ポートとボリュームに関する launchd と Docker の比較

ポート 18789 の所有者、状態がバインド マウントか名前付きボリュームか、アップグレード中にどのユニットが最初に停止するかを文書化します。 SSH 対 VNC ガイドと組み合わせて、インタラクティブな VNC 編集を無人作成ロールから分離します。

8. FAQ

extra_hosts はすべてを解決しますか? 時々ありますが、根本原因が二重トークン ソースである場合、extra_hosts は障害モードを再シャッフルするだけです。

ゲートウェイを 0.0.0.0 にバインドしますか? まず、攻撃対象領域の記事をお読みください。一般公開はデフォルトの回答ではありません。

install.sh フローと競合しますか? いいえ - install.sh はベースライン順序を確立します。この記事では、Docker ネットワーキングと認証の調整に焦点を当てます。

9.ケーススタディ: ログにはリッスンと記録され、CLI は依然として 1008

2026 年の頻繁な障害モードは、開発者が ws://127.0.0.1 を使用してコンテナ B で CLI を実行している間に、ゲートウェイがコンテナ A でリッスンしていることです。紙の上では明らかですが、マルチリポジトリ設定ではコストがかかります。 README の先頭に「openclaw を実行する名前空間」という文を追加し、ランナー コンテナーからプローブを実行する CI スモークを追加します。

2 番目のクラスは、オーバーライド ファイルの OPENCLAW_GATEWAY_TOKEN 行で忘れられます。環境またはファイルの規律を選択し、トークン環境差分の PR チェックリスト項目を追加します。

Time Machine または同期ソフトウェアが状態ディレクトリをミラーリングすると、3 番目のクラスがリモート Mac に発生し、ゴースト 2 番目のゲートウェイが作成されます。状態ディレクトリを非同期としてマークするか、専用のリモート ノードに統合します。

移行記事を組み合わせて、「マシン移行」ドリルと「構成再構築」ドリルを分離します。これらを混在させると、ロールバックの話が混乱します。

Docker は、自動的な簡素化ではなく、より強い制約の下で反復可能な配信です。実稼働準備が完了していることを主張する前に、compose、env print、NC 出力、および 3 層のログ スニペットを添付します。

10. n8n と Webhook Ingress

n8n がスタックにコールバックするとき、HTTP Ingress の所有者は WS トークンの所有者と一致する必要があります。個別のタイトルを使用して、WS 1008 チケットから HTTP 502 調査を分割します。

11.アップグレード規則: 最初に単一のゲートウェイ

互換リリース中は、HA を再度有効にする前に 1 つのゲートウェイと 1 つの CLI に縮小します。半分アップグレードされたボリュームでは、半分一貫したスキーマが生成されます。医師の出力を変更記録に添付します。

12.結論: Docker は再現性を証明し、リモート Mac は SLO を実行します

(1) 制限: CLI 名前空間を文書化しないと、Docker のトラブルシューティングは飛躍的に増大します。デュアル トークン ソースにより、構成編集がランダムに感じられます。

(2) リモート Mac プールが役立つ理由: 専用ホストは、開発者のラップトップから離れた構成バージョン、ボリューム、ヘルス チェックを固定します。

(3) MACGPU 適合: ラップトップ サーバーの代わりに、調整されたリモート Mac ゲートウェイの低摩擦トライアルが必要な場合は、MACGPU がレンタル可能なノードとパブリック ヘルプを提供します。エントリーポイント。以下の CTA は、ログインせずにプランにリンクします。

(4) 最終ゲート: 成功した channels probe と compose/env/token のアラインメントの証拠がなければ、運用準備が整っていると主張しないでください。

13。インストール マトリックスと install.sh へのリンク

install.sh がまだ緑色になっていない場合は、最初にその記事をお読みください。緑色でも Docker が失敗した場合は、ここで L1 マトリックスから再起動します。 3 つのスタック マトリックスは、CLI がホストに属するかサイドカーに属するかを決定するのに役立ちます。

14.可観測性: 構成プロジェクトごとにブラスト半径に注釈を付けます

複数の構成プロジェクトがホストを共有する場合、どのプロジェクトがポート 18789 を所有し、どのプロジェクトが Webhook Ingress を所有しているかをラベル付けします。オンコールでは、Slack 履歴を grep する代わりに、そのマップを含む単一のページを開く必要があります。

15.セキュリティ上の注意: 環境内のトークンとシークレット ファイル

環境変数はプロセス リストとクラッシュ ダンプに表示されます。脅威モデルがそれを禁止している場合は、正しいボリューム権限を持つシークレット ファイルを優先し、環境の重複を削除してください。バインド アドレスとリバース プロキシについては、ゲートウェイの攻撃対象領域ガイドに準拠します。

16. CI パリティ: GitHub Actions

で失敗した名前空間を再現する多くのチームは、ラップトップ上でのみ OpenClaw の問題を再現します。同じ作成プロジェクトを構築し、docker compose run --rm openclaw-cli openclaw channels probe を実行するジョブを追加して、マージ前に WS URL の回帰を捕捉します。画像を賢明にキャッシュしますが、セキュリティ パッチが適用されるとタグを更新します。 CI ランナーが Docker サービス名を解決できない場合は、実稼働障害モードを隠す 127.0.0.1 に暗黙的にフォールバックするのではなく、その制限を明示的に文書化してください。

17.リバース プロキシと WebSocket アップグレード ヘッダー

TLS が nginx または Caddy で終了する場合、アップグレード ヘッダー、アイドル タイムアウト、およびバッファリング設定を確認します。 WebSocket フレームをバッファリングするプロキシは、負荷がかかるとランダムに 1006 が閉じられるように見えることがあります。 OpenClaw ログと一緒にプロキシ アクセス ログをキャプチャし、タイムスタンプを関連付けます。 Gateway が Docker 内でプレーン HTTP のままである間にホスト上の TLS を終了する場合は、新入社員が OPENCLAW_GATEWAY_URL で二重暗号化や間違ったスキームを再導入しないように、その図をリポジトリに保存してください。

18. オンコール用のランブック引き継ぎテンプレート

以下をインシデント テンプレートに貼り付けます: プロジェクト名、イメージ タグ、失敗した名前空間から見た WS URL、OPENCLAW_ 変数の env grep の出力、gateway.auth.token のボリューム パスの出力、nc の結果、レベルでフィルターされたゲートウェイ ログの最後の 20 行を作成します。法律や調達によってクラウド GPU がブロックされている場合でも、文書化されたリモート Mac プールは、資本を購入せずに常時稼働のエージェントに安定した Apple Silicon 容量を追加する実用的な方法であり続けます。

19. CLI イメージとゲートウェイ イメージ間のバージョン スキュー

CLI とゲートウェイを異なるイメージ タグに分割することは有効ですが、リリース ノートがそのマトリックスを明示的にサポートしている場合に限ります。ゲートウェイ ビルドが理解できないハンドシェイク フィールドを CLI が追加すると、ネットワークのバグに似た不透明な切断が発生します。インシデント中に両方の画像を同じリリース トレインに固定し、二等分します。フローティング タグだけでなく、インシデント ドキュメントにダイジェストを記録します。リモートの Mac フリートの場合は、毎週のダイジェスト チェックを自動化して、エンジニアが機能の作業に集中している間にドリフトが静かに蓄積されないようにします。

20. 文書化負債は運用上の負債である

127.0.0.1 セマンティクスの再検出に費やされる 1 時間は、プロンプトやツールの改善に費やされない 1 時間になります。 1 ページのトポロジに一度投資し、README、Runbook、オンボーディングからリンクします。幹部が OpenClaw が本番環境に対応しているかどうかを尋ねた場合は、口頭で保証するのではなく、プローブ ログと作成ダイジェストを渡してください。リモート Mac のレンタルによって優れたドキュメントが不要になるわけではありませんが、実際に運用されているものと一致する正規のスタックをホストする安定した場所が提供されます。

21. インシデント後のレビュープロンプト

ゲートウェイ インシデントをクローズした後、次の 5 つの質問に書面で回答します。CLI を開始したネームスペース、最終的にトークンを保持したファイルまたは環境変数、トークン編集前にペアリングが試行されたかどうか、パス上にプロキシが存在したかどうか、停止中にどの構成ダイジェストがライブであったか。回答が 1 つでも欠けていると、通常、次の四半期に別の症状文字列でインシデントが繰り返されることを意味します。

最後に、リモート ホスト上の macOS のマイナー アップグレードをスタックのセムバー バンプとして扱います。各アップグレード ウィンドウの後に、フリートが再び正常であると宣言する前に、プローブと NC チェックを再実行します。