OPENCLAW 2026
POST_INSTALL_
GATEWAY_
PATH_FORCE.
npm install -g openclaw や公式スクリプトのあと、ターミナルに致命的エラーが出ていないのに openclaw ask が返らない、openclaw-gateway: command not found になる、あるいは openclaw gateway status が未登録を示す場合、最初に疑うべきはモデル障害ではなく npm グローバル prefix と PATH のずれ、Gateway 登録手順の省略、Node 22 の取り違え、リモート Mac の launchd と対話シェルの環境差です。本稿では症状—証拠—アクションのマトリクス、5 手順の初回起動 Runbook、数値ゲート、FAQ を整理し、install.sh 本番手順・LaunchAgent と token・Chrome Relay 18792・v2026.5.x 運用と併読できるよう相互参照を明示します。クリーンな対照環境として MACGPU のリモート Mac に同じ手順を複製することを推奨します。
1. 痛みの分解
1）グローバル bin が PATH に乗っていない。2）openclaw gateway install を実行していない。3）複数 Node があり、インストール時と実行時で別バイナリを参照している。4）SSH ログイン時は profile が読み込まれるが、launchd 子プロセスは最小環境である。これらを API レートリミットの前に切り分けます。加えて、インストールログに ERROR が無いことと実行時クローズドループが成立していることは等価ではありません。postinstall が資産取得で終わり、サービス登録は別コマンドに委ねられる構成では、CI の成功バッジだけを見て夜間障害が再発する例が 2026 年も散見されます。
5）権限とホームディレクトリの不一致：ユーザー A でインストールし、plist はユーザー B を指している、などの構成は「ファイルは存在するのに常に起動失敗」という難解な症状を生みます。6）企業プロキシや TLS 検査によりバイナリ検証が遅延し、初回実行で初めて失敗が表面化するケースでは、npm ミラーと例外ポリシーを運用表に固定する必要があります。7）共有自動化アカウントで複数ジョブが並列にグローバル npm を叩くと、短時間で which の結果が揺れる競合が起きます。メンテナンス窓では直列化とロックファイルを徹底してください。
2. 症状マトリクス
| 兆候 | 第一疑い | 証拠 |
|---|---|---|
| command not found | PATH | which openclaw、npm prefix -g |
| gateway status が未インストール | 登録欠落 | install --force 前後比較 |
| 対話 OK／launchd NG | plist 環境 | EnvironmentVariables |
| リモートのみ再現 | 非ログインシェル | ssh -t と profile 差分 |
3. 五手順 Runbook
Step 1 ランタイム三元固定
node -v（22+）、which node の絶対パスを記録します。
Step 2 prefix と PATH
npm config get prefix を確認し、zshrc 等へ bin を追加。sudo npm は避けます。
Step 3 Gateway 明示登録
メンテナンス窓で openclaw gateway install、必要なら --force。token 記事と LaunchAgent の変数を揃えます。
Step 4 ポートとヘルス意味
ループバックと SSH 転送を分離し、Chrome Relay 稿の 18792 探針と照合します。
Step 5 コールド再起動とログ切り出し
完全停止後に再起動し、install／register／first-ask の時間窓で openclaw logs を分割添付します。
4. 三道ゲート
A: which openclaw-gateway が非空。B: openclaw gateway status が健全になるまで本番トラフィックを切らない。C: 非対話 launchd のコールドスタートが通るまでノート PC トンネルのみに依存しない。B 通過後は、あえて全 SSH セッションを閉じ、人手の export PATH が無い状態でも再検証することが望ましいです。
5. ケーススタディ
「npm は成功、昼の SSH は動くが夜間だけ全滅」→plist に ~/.npm-global/bin が無かった。
2026 年 5 月、リモート Mac mini で 24/7 運用していたチームは、昼間の対話シェルでは nvm が PATH を補完していたため誤認し、夜間の launchd では古いシステム Node が選ばれ Gateway が起動しないまま API キーを三回ローテーションしていました。Node 22 の絶対パスを plist に固定し、openclaw gateway install --force と channels probe を実施後、初回トークンまで安定しました。v2026.5.x の記事が示すように、上層のプラグインや TTS 分離は健全な基底があって初めて意味を持ちます。
6. 産業動向
2026 年のエージェントスタックは CLI／Gateway／プラグインが独立バージョンで出荷されます。単一の npm 成功はクローズドループを保証しません。Windows や Linux の検証環境も有用ですが、ブラウザツールチェーンとデスクトップセッションを含む再現実験では変数が増えます。比較対照として Apple Silicon のリモート専用ノードを一本化すると、議論が「未登録か／ネットワークか」に素早く収束します。ハード増設より先に、監査可能なチェックリストとコールドスタート証跡を揃える方が ROI が高いです。
Windows や Linux に Gateway を置く構成も可能ですが、グラフィックスや一部チャネルドライバと絡む検証では macOS 対照面の変数が少ない場面が残ります。結論はブランド崇拝ではなく、再現性とログの一貫性に基づきます。運用負荷を下げたい場合は MACGPU リモート Mac をレンタルし、本 Runbook をリリーステンプレートへ焼き込むのが現実的です。
7. 数値閾値
健全 gateway status までのコールドスタートが 90 秒 を超えたらディスク／スキャナをレビュー。ローカルループの初回 ask が 25 秒 を超えて無応答なら Gateway を先に疑う。同一窓で gateway install --force を 2 回超えたら人手 diff。plist の PATH 重要エントリが 3 未満はデフォルト不合格とみなす、を運用表に明文化してください。さらに、読み取り専用ボリュームやネットワークマウント上にログを置くと「成功ログのあと即クラッシュ」が起き得ます。共有自動化ユーザーには独立した npm prefix とホームを割り当て、並列ジョブでのグローバル上書きを禁止してください。
8. FAQ
doctor が緑でも which は？必須です。token_mismatch との違いは？401 系を先に token 記事へ、プロセス不在は本稿で。sudo npm？非推奨です。Relay が赤で gateway が緑？Chrome Relay 記事へ。 install.sh と npm の混在？二重メタデータのリスクが高いので一方に統一し、変更票に明記してください。