which openclaw から首条メッセージまでの七段階、クラウド Mac 特有の PATH とログの落とし穴、M4 試走と M4 Pro 常駐の選定を整理します。公式 install-daemon、18789 二系統、launchd token、診断ラダー、ヘッドレス SSH と併読してください。
2026 Setup Wizard が Retry し続ける：変更票に貼れる四類型の根因
Setup Wizard は macOS アプリ側がグローバル openclaw CLI と launchd 上の Gateway プロセスの起動完了をポーリングします。クラウド Mac では「インストールログは緑、ウィザードだけ赤」が最頻で、チームは API キーやモデル名を入れ替えて時間を失いがちです。実際にはウィザードが叩くコマンドは対話シェルと同じ PATH を持たず、launchctl kickstart が既に exit 1 の plist を再起動できない、別ユーザーや旧ジョブが 18789 を握っている、plist に PATH や OPENCLAW_STATE_DIR が無い、の四つに収束します。
CLI とデーモンのバージョン整合を飛ばすと、ウィザードは「起動待ち」表示のままバイナリ不一致で即死した子プロセスを見続けます。18789 附着の場合は「ready」と誤認しつつ別インスタンスに繋がることもあります。排障の第一分岐は常にウィザードの Retry ボタンではなく SSH の七段階チェックリストです。
PATH に CLI が無い：インストールは ~/.npm-global 等に成功したが、login シェルと launchd の EnvironmentVariables が未同期。ウィザードは openclaw: command not found をタイムアウトに見せます。
起動済み failed のまま Retry：launchctl print で LastExitStatus が非ゼロなのに UI は待機。doctor を先に通し plist を直します。
18789 占有：旧 Gateway、CI スクリプト、二重 install のいずれか。lsof -nP -iTCP:18789 で所有者を確定します。
launchd 環境変数欠落：対話 SSH では echo $PATH が正しくても plist は /usr/bin:/bin のみ。ProgramArguments を絶対パス化するか plist に PATH を明示します。
Screen Sharing と SSH の手順混在：ウィザードは GUI セッションのキーチェーンを要求する一方、修復は SSH で行い、トークン状態がずれます。token 専文へ分岐します。
受け入れ票には Retry 回数ではなく、七段階の各コマンド出力のハッシュまたは貼付、doctor 終了コード、18789 の LISTEN 行、初回 handshake のタイムスタンプを残してください。これにより「ウィザードを何度押したか」という無意味なメトリクスから脱却できます。
ウィザード必須か CLI 完結か：クラウド Mac での二択マトリクス
公式の 2026 年パスは「macOS アプリが体験と初回ペアリング、Gateway 実体はグローバル CLI」です。KVMNODE では Screen Sharing を短時間だけ開き、残りは SSH と Runbook で固定化するチームが多いです。下表は変更設計時にそのまま Wiki に貼れます。
| 経路 | 向いている場面 | ウィザード Retry との関係 |
|---|---|---|
| CLI + doctor + install-daemon | ヘッドレス運用、Terraform 後の初回、CI 用専用ユーザ | ウィザードを開かず七段階で Ready を定義可能 |
| macOS アプリ Setup Wizard | 初回チャネル QR、GUI トークン、非エンジニアの受け入れ | 裏で CLI が未就绪だと Retry のみ増える |
| ハイブリッド（推奨） | SSH で七段階合格後、一度だけ Screen Sharing でウィザード確認 | Retry は UI バグではなく未合格のシグナルとして扱う |
ウィザードの Retry は「もう一度待て」ではなく「launchd の真実がまだ揃っていない」というアラートです。
ヘッドレス SSHで Node 22 と PREFIX を先に固定し、install-daemonで plist の単一真実源を作ってからアプリを起動すると、Retry ループはほぼ消えます。逆にアプリだけ先に開くと、インストール成功の錯覚のまま何時間も Retry するケースが残ります。
コマンドブロック：PATH・18789・launchd ログを一画面で揃える
七段階のうち前半はこのブロックで一気に取れます。ログは /tmp/openclaw を優先し、診断ラダーの L1/L2 にマップします。TZ はノードのローカル時間で統一し、六リージョン横断のインシデントでも時刻比較が狂わないようにします。
node -v which openclaw openclaw --version openclaw gateway status openclaw doctor launchctl print gui/$(id -u)/ai.openclaw.gateway 2>/dev/null | head -40 lsof -nP -iTCP:18789 -sTCP:LISTEN tail -n 80 /tmp/openclaw/openclaw-gateway.log 2>/dev/null
ヒント：doctor が PATH 修正を提案したら、対話シェルの ~/.zprofile だけでなく LaunchAgent の EnvironmentVariables か ProgramArguments の絶対パスも同じメンテナンス窗で更新してください。片方だけ直すと Retry が再発します。
gateway status が JSON で healthy でもウィザードが失敗する場合は、アプリプロセスのサンドボックスが別ユーザーのソケットを見ていないパターンがあります。専用クラウド Mac ではOpenClaw と CI を同一ログインユーザに載せない方が、18789 とキーチェンの境界が明確になります。共有が必要なら 同プール隔離のラベル規約を先に適用してください。
七段階跟做：Gateway did not become ready を変更票で閉じる
Node 22 と CLI の存在確認：node -v、which openclaw、openclaw --version を変更票に貼付。22 未満なら install.sh または組織 mirror で先に揃えます。
対話 PATH と launchd PATH の差分記録：echo $PATH と plist の EnvironmentVariables を並記。差分があれば絶対パス化を選択します。
doctor を非対話で実行：提案されたマイグレーションを適用し、終了コードと標準出力全文を保存します。失敗時はウィザードを閉じ、token 専文へ分岐します。
gateway stop と 18789 の解放：openclaw gateway stop 後に lsof で LISTEN が消えたことを確認。残る PID は旧 install の残骸です。
install-daemon または kickstart：公式 plist パスに合わせ再インストールし、launchctl print で LastExitStatus が 0 になるまで待ちます。
gateway status とログの時刻整合：status の uptime と /tmp/openclaw ログの最新行が同じ起動イベントを指すことを確認します。
ウィザードまたは CLI で首条メッセージ：Screen Sharing で一度だけウィザードを通すか、CLI で probe を実行。成功 ID を受け入れ票に記録します。
七段階が同一ノードで再現可能になったら、ウィザードの Retry ボタンはもう使いません。別リージョンへ移す場合も、手順は同じでデータ面だけ変えるのが 2026 年のベストプラクティスです。近区 M4 で七段階が通れば機種変更は不要で、通らないが memory pressure と並列 xcodebuild が同時にあるなら M4 Pro またはプール分割を検討します。
クラウド Mac 特有の落とし穴として、bastion 経由 SSH の ForceCommand が PATH を削るケース、初回ログインの macOS セットアップ未完了で Screen Sharing が開けないケース、六リージョンでログがローカルディスクのみに残り中央集約されないケースがあります。いずれもウィザード Retry の表面症状は同じなので、七段階出力を S3 やチケットに必ず添付する運用が効きます。
可引用データと M4 試走対 M4 Pro 常駐：ウィザード以外で閉じる条件
ウィザード待ち時間はしばしば 60〜120 秒のポーリングですが、裏で launchd が 3 秒で落ちていると Retry は無限に見えます。以下は変更票の「技術データ」欄にそのまま書ける値です。
デフォルト Gateway ポート：18789（TCP LISTEN）。二系統 install 時は附着か新規起動かを gateway status で明示します。
Node 下限：2026 公式経路は 22 系。20 系のままでは doctor が警告しウィザードが ready にならないことがあります。
ヘルスプローブ間隔：運用では 60 秒 cron と gateway status を併用し、Retry より先にアラートします。cron プローブ参照。
| プロファイル | 近区 M4 試走 | 遠区 M4 Pro 常駐 |
|---|---|---|
| 初回ウィザード＋単一 Gateway | 十分 | 過剰なことが多い |
| ウィザード＋夜間 CI＋channels プローブ | 16GB は要注意 | 推奨 |
| Retry が PATH のみで七段階再現 | 機種変更不要 | 機種変更不要 |
注意：個人 Mac を唯一の Gateway ホストにすると、スリープと PATH ドリフトでウィザード Retry が再発します。7×24 の launchd 真実源が必要なら専用クラウドノードが適しています。
ノート PC 常駐の弱点は、予測不能なスリープ、ユーザー切替によるキーチェーン不一致、npm グローバルの偶発上書きです。ウィザードはそれらを「Gateway 未就绪」に畳み込みます。監査可能な Setup 完了と Agent 常駐を契約に落とすなら、KVMNODE Mac mini クラウドレンタルが実務上の定番です。六リージョンから試走し、合格後に M4 Pro へ昇格する流れも同一 Runbook で再現できます。注文は 注文入口、手順は ヘルプセンター、SKU は 価格ページ をご覧ください。