2026年版 OpenClaw インストール後
Doctor、Gateway 健全性、macOS/Linux/WSL2 の対処

約 15 分で読めます · MACCOME

OpenClaw のインストールガイドを終えたのに、「CLI は動くが Gateway が死んでいる」「モデルがタイムアウトする」「WSL2 でデーモンが常駐しない」といった状態が続く場合、必要なのはインストール手順の写経ではなく、インストール後の検証と症状ベースの切り分けです。本稿は三プラットフォームのインストール、Docker 本番、Secrets／PDF などの高度ガイドと線を引き、症状マトリクス、6 ステップの手順書、運用で効く指標が 3 つに絞って述べ、WSL2 とネイティブ Linux／macOS の違いも整理します。

インストール済み ≠ 健全：切り分けの 5 つの落とし穴

長寿命の Gateway、モデルの外向き通信、ローカルデーモンを組み合わせたシステムは、「部品ごとには問題なさそう」なのに失敗しがちです。オンコールでは、一度きりの設定ミスと断続的なネットワークや電源ポリシーも切り分けてください。表に進む前に、次の 5 点で認識を揃えます。

  1. 「インストール成功」を「サービス健全」と混同する： パッケージは入ったがサービスが登録されていない、待ち受けがない、ヘルスチェックが落ちる—自動化は依然として不安定です。
  2. API キーと外向き通信を混ぜる： 有効なキーでも、企業プロキシや地域ブロックの裏ではタイムアウトとして見え、401 にならないことがあります。
  3. Gateway のバインドアドレスを無視する： localhost のみやコンテナ内のみのリスナーは、他プロセスからのアクセス経路を変えます。
  4. WSL2 をネイティブ Windows と取り違える： DrvFS と ext4 では I/O や inotify が変わり、パスは同じでも挙動が異なります。
  5. ログの最後の 1 行だけを読む： モデル、Gateway、デーモンのレイヤーでタイムスタンプを揃えてから原因を探してください。

症状マトリクス：まず分類する

オンコールでは表を使います。CLI のコマンド名は、インストールした OpenClaw のバージョンに合わせてください。深掘りの前に doctor または同等のチェックを優先します。

見える症状想定される方向性まず試すこと
プロセスがすぐ終了するNode のバージョン、権限、カレントディレクトリ公式の Node 基準に合わせる；doctor を実行；インストールユーザーとデータディレクトリの権限を確認する
Gateway のポートが無反応バインドアドレス、ポート競合、ファイアウォールリスナーを確認する；ローカルで curl によりヘルスを確認する；ホストと上流のセキュリティグループを確認する
モデルのタイムアウトやストリーム切断外向き通信、DNS、プロキシ、リージョン、クォータ最小リクエストで試す；プロキシを迂回する；クォータとエンドポイントのリージョンを確認する
WSL2 のみで素の Linux は問題ないファイルシステム性能、仮想ネットワーク、systemd の穴リポジトリは WSL の ext4 側に置く；ドライブをまたぐ巨大なツリーは避ける；systemd／ユーザーセッションの方針を検証する
スリープやアップデートのあとに失敗するノート PC の電源ポリシーとデーモン復旧電源設定；GUI セッションとともにデーモンが死ぬか；専用ホストが必要か
bash
# インストール後の確認（CLI の名称は環境に合わせてください）
openclaw doctor
curl -fsS "http://127.0.0.1:${OPENCLAW_GATEWAY_PORT:-PORT}/health" || true
warning

WSL2： /mnt/c 上での重いビルドやファイルウォッチャーは、Linux のファイルシステムに比べて遅く、イベントを取りこぼすことがあります。長時間動かす Gateway はリポジトリとデータを WSL の Linux ボリューム側に置き、systemd／セッションのライフサイクルは別途検証してください。

インストール後の 6 ステップ手順書

手順は Docker のヘルスチェックの規律を踏まえつつ、ベアメタルやハイブリッドにも当てはまります。受け入れ基準はいずれも再現可能であるべきです。

  1. バージョンの三つ組を固定する： OpenClaw のバージョン、Node のメジャー、OS のパッチレベル—アップグレード時はまとめて見直す。
  2. doctor を実行する： 警告を設定・ネットワーク・権限のバケツに分けてから潰す。
  3. 最小のモデル呼び出し： 最小のプロンプトとタイムアウトで、認証・クォータ・ネットワークの失敗を切り分ける。
  4. Gateway のリスナーと健全性： ループバックのプローブを通してからプロセス間テストへ；プロキシはホスト／パスプレフィックスと揃える。
  5. デーモンのライフサイクル： launchd、systemd、Windows サービス、ログイン項目—再接続後の復旧を確認する。
  6. 症状インデックスを維持する： 頻出のエラー文字列を社内 Wiki の修正へリンクする。

変更チケット用の 3 つの指標

ドキュメントの代替にはなりませんが、レビューとオンコールの言葉を揃えられます。

  1. Node／ランタイムの境界： サポートする Node のメジャーと LTS のみ、という方針—アプリの不具合を追う前に Node を下げる。
  2. ヘルスチェックの定義： HTTP 200 だけでは ready ではない—プローブのパス、タイムアウト、モデル依存を文書化する。
  3. ログの既定： Gateway とクライアントのレベル、パス、ローテーション—長期の debug でディスクを埋めない。

「自分のノート PC では動く」が本番 Gateway ではない理由

スリープ、アップデート、権限ダイアログが長寿命プロセスを中断します。WSL2 とネイティブ Windows ではネットワークの差もさらに開きます。OpenClaw の Gateway をチームが頼れるものにするなら、観測可能な専用の Apple Silicon ホストの方が、ローカルでの場当たり修正を重ねるより有利なことが多いです。

MACCOME は、安定した Gateway と自動化向けに複数リージョンのベアメタルリモート Mac を提供しています。インストールと Docker のガイドのあとでも、スリープとデーモン復旧がまだ痛むなら、ヘルプセンターから始め、料金とリージョンを揃えてください。

短期のノート PC 上のデバッグでは、この 6 ステップのチェックリストとヘルスチェックのスクリプト化まで進めてください。CI や 24/7 のエージェントが絡むなら、ローカルにパッチを積み増すより、専用のリモート Mac への移行を検討する価値があります。

よくある質問

インストールガイドにコマンドは載っているのに、なぜ本稿があるのですか？

三プラットフォームのインストールガイドは「どう入れるか」、本稿は「健全性の証明と症状の切り分け」です。

Docker 本番の記事と重複しませんか？

しません。Docker 本番の手順書はイメージと Compose に焦点を当て、本稿はインストール後のチェック、プローブ、WSL2／ネイティブの差です。

高度な Secrets の記事を先に読むべきですか？

ガバナンスは高度な手順書にあります。モデルがまだ失敗するなら、まず本稿のマトリクスを使い、そのあとローテーションと監査に戻ってください。安定したホスト面についてはレンタル料金も参照してください。