gateway.bind=lan を有効な gateway.auth.token とセットで要求します。refusing to bind without auth、Dashboard の unauthorized、SSH では緑なのに launchd だけ赤、といった症状の多くは bind 変更と token 配線の順序逆転、または LaunchAgent が古い loopback 設定を保持したドリフトに起因します。本記事では loopback と lan の決定木、~/.openclaw/.env に置く OPENCLAW_GATEWAY_TOKEN と openclaw.json の単一情報源、六段階の本番切替、gateway.reload.mode=hybrid の熱リロード境界、gateway.controlUi.allowedOrigins、/healthz 验收、LaunchAgent ドリフトの検出までを整理します。launchd token、アップグレード後の bind とトンネル、リモート Gateway トポロジ、診断ラダー、install-daemon と併読してください。
loopback と lan：個人 SSH トンネルから Control UI 本番 bind への決定木
OpenClaw Gateway の既定は 127.0.0.1:18789 への loopback 待受です。KVMNODE クラウド Mac へ SSH し ssh -L 18789:127.0.0.1:18789 でブラウザを開く運用は、単一エンジニアの開発期に最も安全で、token なしでも doctor が通りやすい posture です。一方、社内の第二ノートから Control UI に直接接続したい、LAN 内のヘルスプローブが RFC1918 アドレスへ到達する必要がある、Tailscale サブネットルーター越しに固定 IP で叩きたい、といった要件が出た時点で gateway.bind=lan の検討が始まります。
2026 年のビルドは非 loopback bind に明示的な認証を要求します。gateway.bind だけを lan に書き換え、token を plist や .env に載せ忘れると、ログに refusing to bind without auth 相当の早期 exit が出て launchd が再起動ループに入ります。これはモデル API の障害ではなく、設定ガードが意図どおり動いている信号です。公网インターフェースへ 18789 を晒す選択は、トンネルや ACL なしでは推奨されません。クラウド事業者のセキュリティグループでポートを開く前に、アプリケーション層の token と allowedOrigins を揃えてください。
loopback 維持：一人が SSH トンネル経由で Dashboard を見るだけ。変更票にトンネルコマンドを固定。
lan + token：同一 VPC または Tailnet 内の複数クライアント、無人プローブ、Control UI の常時 URL。
トンネル優先の折衷：bind は loopback のまま Tailscale serve や SSH -L でエッジを置き、Gateway 本体は最小暴露。
避ける：token 未設定の lan、二重の手動 gateway start と plist 共存、変更後の listen アドレス未確認。
リモートクライアントだけを増やし Gateway 権威は一台に置く設計は gateway.mode remote の記事が扱います。本稿はサーバー側 Gateway 自身の bind 面に焦点を当てます。初回 onboard が未完了なら、先に 導入チェックリスト で loopback 上の healthy を取ってから lan へ進んでください。
.env と openclaw.json：OPENCLAW_GATEWAY_TOKEN の単一情報源と禁止パターン
token を対話 shell の export だけに置くと、launchd 常駐へ切り替えた瞬間に監督プロセスは空の環境で起動します。launchd token 記事 が説明する split brain と同型で、CLI が openclaw config get gateway.auth.token で値を返しても、デーモン側は別パスまたは未注入のまま unauthorized を返します。
本番推奨は ~/.openclaw/.env に OPENCLAW_GATEWAY_TOKEN= を書き、openclaw.json 側で gateway.auth.mode を明示することです。Gateway install または openclaw gateway install --force は plist が state ディレクトリと .env を読む経路を再生成します。plist の EnvironmentVariables に平文 token を重複保存するのはローテーション時に片側だけ更新されるため禁止です。PATH、OPENCLAW_STATE_DIR、必要なら node の絶対パスだけを plist に残します。
| 保管場所 | 向く用途 | launchd から見えるか | 避ける理由 |
|---|---|---|---|
| ~/.openclaw/.env | 本番 token の単一情報源 | install 後は可 | chmod 600 必須、Git 禁止 |
| openclaw.json gateway.auth | mode とメタ、または json 単独運用 | 可 | 平文を repo に commit しない |
| ~/.zshrc export | 対話デバッグのみ | 不可 | 常駐 Gateway には届かない |
| plist 平文 token | 短期トリアージ | 可 | ローテでドリフト、監査で二重管理 |
| チャット・チケット貼付 | なし | — | 漏洩と再発行コスト |
bind を lan に広げる前に、監督プロセスが token を読めることを doctor と launchctl print で証明してください。認証なしの listen 拡大は失敗する設計です。
レガシー鍵 gateway.token だけが残っている場合、新スキーマは無視し Dashboard が 401 を繰り返します。移行手順は アップグレード runbook の token 節を参照し、lan bind と同じ変更票で gateway.auth.token または .env へ統一してください。
六段階跟做：旧プロセス停止から healthz と token 付きクライアント验收まで
以下は KVMNODE 専用クラウド Mac 上で loopback から lan 本番 bind へ移行する標準順序です。各段階の stdout を変更票に添付し、ロールバックは json、.env、plist の三点セットで行います。
旧プロセスと二重 listen の掃除：lsof -nP -iTCP:18789 -sTCP:LISTEN で手動 gateway と plist の競合を解消。余分な PID は記録の上停止。
.env に token 書込：openssl rand -hex 32 等で生成し ~/.openclaw/.env に OPENCLAW_GATEWAY_TOKEN= を追加。権限 600。
openclaw.json で bind と auth：gateway.bind=lan、gateway.auth.mode を明示。allowedOrigins は後段でも可。
gateway install と LaunchAgent 验收：openclaw gateway install --force 後 launchctl print gui/$(id -u)/com.openclaw.gateway で ProgramArguments と WorkingDirectory を確認。
healthz：ホスト上で curl -sS -o /dev/null -w '%{http_code}' http://127.0.0.1:18789/healthz と LAN IP からの到達を記録。
クライアント token 验收：Control UI または CLI で Authorization ヘッダ付き接続。無 token は 401 であることを確認し、誤暴露を検知。
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH" lsof -nP -iTCP:18789 -sTCP:LISTEN openclaw config set gateway.bind lan openclaw config set gateway.auth.mode token openclaw gateway install --force openclaw gateway restart openclaw gateway status --deep curl -sS http://127.0.0.1:18789/healthz curl -sS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" http://127.0.0.1:18789/
リモートから実行する場合、上記はGateway が動くクラウド Mac 上の SSH セッションで走らせてください。ローカルノートのターミナルで config set しても、対象ホストの openclaw.json が更新されない誤バインドが起きます。openclaw gateway status --deep が duplicate unit を示す場合は、余分な LaunchAgent を bootout してから install を再実行します。
gateway.reload.mode=hybrid：熱リロードと手動再起動の分界、allowedOrigins
gateway.reload.mode=hybrid は、チャネル設定や一部 UI メタの変更をプロセス再起動なしで取り込むモードです。運用上の落とし穴は、bind・auth・listen ポート・LaunchAgent 本体の変更を hybrid で済ませようとすることです。これらはソケットの再バインドまたは plist の再読込が必要で、openclaw gateway restart または kickstart が正解です。
| 変更項目 | hybrid で足りるか | 推奨操作 | 验收 |
|---|---|---|---|
| gateway.controlUi.allowedOrigins | 多くは可 | config set 後、UI から CORS エラー消失を確認 | ブラウザ DevTools |
| チャネル webhook URL | 場合あり | channels probe | openclaw channels probe |
| gateway.bind | 不可 | restart + lsof | LISTEN が 0.0.0.0 または LAN IP |
| OPENCLAW_GATEWAY_TOKEN | 不可 | .env 更新 → restart | 旧 token で 401 |
| ProgramArguments / Node パス | 不可 | gateway install --force | launchctl print |
Control UI を別オリジンのブラウザから開く場合、gateway.controlUi.allowedOrigins に HTTPS オリジンを列挙します。トンネル経由で http://127.0.0.1:19000 を使う開発期と、本番 HTTPS ドメインは別エントリとして変更票に分け、混在させないでください。allowedOrigins だけ直しても bind が loopback のままなら、LAN クライアントは依然として到達できません。順序は bind → token → restart → origins → hybrid 可能域の確認です。
ヒント：hybrid 反映後も openclaw gateway status の RPC プローブが失敗する場合、熱リロードではなく LaunchAgent ドリフトを疑い、診断ラダー L2 の deep status へ進んでください。
高频エラー分叉、LaunchAgent ドリフト验收、六リージョンと M4 Pro 選定
refusing to bind without auth：lan 設定に対し token が .env または json に存在しない。生成と install を先に。EADDRINUSE：18789 の所有者が手動プロセス。kill 前に lsof で PID とコマンド行を保存。unauthorized：クライアント token とサーバー .env の不一致、または allowedOrigins 未登録。プローブ alone 失敗：listen アドレスと probe URL の不一致。loopback プローブを lan bind に向けたままにしない。
| LaunchAgent ドリフト信号 | 意味 | 是正 |
|---|---|---|
| which openclaw ≠ plist 先頭 | CLI とデーモンが別ビルド | PATH 固定 → install --force |
| listen が 127.0.0.1 のまま | json 更新がデーモン未反映 | restart、それでもダメなら plist 再生成 |
| token 行がログに無い | .env パスが監督環境とズレ | OPENCLAW_STATE_DIR 一致確認 |
| 二重 Label | 旧 onboard 残存 | bootout 余分 → 単一 unit |
排障順序：gateway status --deep → doctor → lsof 18789 → .env と json → install --force → クライアント token 再試行。
六リージョン：LAN bind はノード内 NIC に依存。リージョン移転時は allowedOrigins とファイアウォールを再验收。
M4 と M4 Pro：bind 変更自体は CPU 非依存。同一ホストで iOS CI と Gateway を同居しメモリ圧が高い週は M4 Pro またはプール分割。
注意：hybrid や restart を連打する前にログと doctor を読んでください。単純なポート競合を再起動ループに変えると、チャネル全体の outage 窓が広がります。
蓋閉めノート PC を Gateway ホストに据え置くと、lan bind 成功後もスリープで listen が消え、クライアント側は unauthorized やタイムアウトとして見えます。7×24 の lan 本番 bind には KVMNODE 専用クラウド Mac と launchd 常駐が実務上の定番です。bind モード、token ローテ日、plist Label、healthz 結果を同一変更票に載せられる専用ホストは、リモートチームの監査コストを下げます。SKU は 価格ページ、手順は ヘルプセンター、注文は 注文入口 をご覧ください。24 時間安定稼働 の heartbeat 節と組み合わせ、夜間プローブにも token 付き URL を使うとドリフト検知が早まります。