2026 年、OpenClaw をインストールまたは Docker／Compose から運用しているチームがつまずくのは、しばしば誤ったモデルルート、429 とタイムアウトの混線、フェイルオーバー順の不整合、npm グローバルとコンテナ間の環境変数の分断です。「インストールできない」ではありません。本稿は《クロスプラットフォーム導入》《Docker 本番》《アップグレードと移行》と役割を分け、実行時のマルチモデルルーティング、実行可能なフェイルオーバー、二経路の対照表、症状ベースの Gateway／CLI ログ切り分けに焦点を当てます。インストール後の症状は《doctor 切り分け》へ続けてください。
デフォルトとフォールバックのモデル、異なるプロバイダのレート制限が Gateway の背後にあると、障害はランダムに見えます。HTTP ステータスだけでなく、次の六分類をアラート項目にマッピングしてください。
export だけでコンテナに注入されていない、または compose の上書きが意図と逆。これらの痛みはアップグレードのバックアップやイメージタグとは直交します。実行時ルーティングと変更管理は別物です。リリースと当番を切り分けるために両方を読んでください。
マルチモデルは通常、複数の課金アカウントとコンプライアンス境界を意味します。セッションがモデルに明示的にスコープされていないと、過剰課金やポリシー違反のリスクがあります。ルート表を Secrets ガバナンスとあわせてレビューするコストと権限の契約として扱ってください。
「エンドポイントに届く」ことと「チェーンが健全」ことは別です。プロキシ、ファイアウォール、DNS がセッションごとに成功を分断することがあります。構造化ログとサンプリングの方が、単一のグローバルエラー率より有効です。
設定の読み込み順、環境の優先順位、再起動の境界を両方の経路で文書化しないと、「ホストは変えたがコンテナは変わっていない」が起きます。
| 次元 | npm グローバル／ローカルプロセス | Docker／Compose |
|---|---|---|
| 設定とシークレット | ユーザ設定ファイルとシェル環境が優勢 | env_file、マウント、実行時 -e を明示する必要がある |
| アップグレードとロールバック | グローバル CLI による npm パッケージの固定 | イメージタグ、ボリューム、アップグレードガイドに沿った docker compose pull の順序 |
| ヘルスチェック | systemd／launchd のプローブに合わせる | コンテナ内 curl／CLI；ネットワークスタックはホストと異なる（ループバック方針を含む） |
| よくあるミス | 複数の Node バージョンで誤ったグローバルが選ばれる | ホットリロード前提の読み取り専用マウント、再ビルド後に環境が消える |
組織全体でモデルを替えるか、キーを替えるか、egress を直すかのルールを決め、同じ SLO 文書に書きます。番号が小さいほど先に試します。
| 症状（ログ／メトリクス） | 想定原因 | 例の順序 |
|---|---|---|
| HTTP 429 または明示的なレート制限 | 枠または同時実行 | バックオフ→予備キー→同時実行を下げる→一時的なフォールバックモデル |
| タイムアウト、リセット、遅い TLS | ネットワーク経路またはリージョン egress | タイムアウト延長（上限付き）→プロキシ／DNS→近い egress |
| モデル欠如／権限なし | ID またはアカウント権限 | プロバイダコンソールを確認→ルート表を修正→無関係なフォールバックを黙って使わない |
| セッションの一部だけ成功 | キーの偏りまたはスティッキールーティングの誤り | キー別カウンタとサーキットブレーカ→セッション固定→ Gateway シャーディング |
# リクエストごとの最低限のログ項目（例）: # requestId / sessionId / provider / modelId / status / latencyMs # いずれかが欠けているなら、ルートを盲信で変える前に可観測性を足す
注意：より小さく安いモデルにダウングレードする場合、下流の自動化やレビュー手順での能力ギャップをラベル付けしてください。黙って「賢くない」出力が出ると業務インシデントになります。
2026 年もプロバイダのカタログは変わり続けます。設定をドキュメントとして持つことが口伝より優れます。ルート表とアラート閾値を同じリポジトリに置き、引き継ぎの隙を減らしてください。
Gateway が APAC と北米にあるなら、リージョン×プロバイダのヒートマップを引いてください。地域劣化はしばしばグローバル赤の前兆で、バーストレンタルの判断材料になります。
ユーザージャーニーを分解します。認証→ルーティング→モデル呼び出し→ツール副作用→セッション書き戻し。各段でrequestIdを共有すべきです。無いならモデルをいじる前にトレースを足してください。
ハイブリッド（ノート、ベアサーバ、コンテナ）では週次の最小パリティテストを実行します。同じプロンプトとルート版を三経路で比較し、遅延／エラーのばらつきが閾値を超えたらリリースを止めます。
個人端末はスリープ、不安定な WAN、監査されていない環境変数を足し、ルーティングの不具合を断続的な幽霊にします。CI、ページング、顧客 SLA が絡むなら専用計算、安定した egress、契約可能なレンタル条件が必要で、hosts の無限編集ではありません。
24/7 Gateway、バッチ自動化、ビルド／署名ホスト横の低遅延が必要なら、実行をプロ向けのマルチリージョン Mac クラウドに置く方が観測と監査がしやすいことが多いです。MACCOME はMac Mini M4／M4 Proのベアメタルを複数リージョンで柔軟な条件で提供しています。《マルチリージョンとレンタル期間のガイド》と料金をあわせてご検討ください。
パイロットでは一つのリージョンでルートとログ項目が安定するまで様子を見、その後 Gateway をワークロードと同居させてクロスリージョン推論とスロットリングを避けるか判断します。
上級チャネルを上級 Runbook から使う場合は、モデルルーティングの変更とチャネル設定の変更を別リリースにし、爆発半径を抑えます。変更チケットにルート表バージョンを添付し、ログサンプリングと監査に使います。
よくある質問
アップグレード・移行ガイドとの違いは何ですか？
アップグレード編はバックアップとロールバックを扱います。本稿は実行時ルーティングと二経路のログです。切り分けは《doctor 切り分け》へ。商業条件は《レンタル料金》と《ヘルプセンター》をご確認ください。
Docker に新しいモデル名が出ているのにトラフィックが古い—最初は何ですか？
Compose のボリュームと環境の上書きを確認し、コンテナに読み込まれた設定と Gateway ログを見ます。《Docker 本番》のヘルスチェックとあわせてください。