OPENCLAW MACOS
STALE_
LAUNCHAGENT_
TOKEN.

2026.4.x 系では、新しい Gateway トークンを doctor や管理画面で配布した直後に、Telegram・各種 IM・ブラウザ UI・統合 CLI が同時に 401／unauthorized を返すケースが繰り返し観測されています。対話型シェルでは export を更新していたつもりでも、実際に Gateway を起動しているのは LaunchAgent 経由であり、OPENCLAW_GATEWAY_TOKEN が plist の EnvironmentVariables に埋め込まれたまま凍結している典型です。さらに openclaw gateway install は既存エージェントを検知すると「インストール済み」で終了し、plist を書き換えないことがあります。本稿では症状テーブル・真の設定ソースの三段比較・安全な bootout／編集／bootstrap・省略時は --force（実際のフラグは pinned CLI のヘルプに従う）・headless Mac 向け SSH チェックリスト・インシデント用ハードゲートを整理します。関連として breaking と device auth v2、Docker／WS トークン、移行と launchd 再構成、silent Gateway 診断、systemd／launchd ガイド を参照してください。

1. なぜ「全チャネル 401」と「ローカル status 緑」が同居するのか

チャネルハンドラは失敗を即ログ出ししますが、短いプローブは認証ヘッダを検証しないことがあります。zsh にだけ新トークンがあっても launchd 子プロセスは plist を継承します。ローテでサーバ側が旧シークレットを失効させれば、ブローカー経由の経路はすべて拒否されます。install コマンドの成功メッセージは「ディスク上の環境が揃った」ことを保証しません。

2. 症状と証跡のマトリクス

現象	第一候補	取るべき証跡
すべてのクライアントが同時刻に 401	実 Gateway が無効化済みトークンを保持	フェイルした 1 リクエストの本文とローテ時刻の突合
launchd のみ失敗、前景起動は成功 plist	古い OPENCLAW_GATEWAY_TOKEN	plutil -p ~/Library/LaunchAgents/*openclaw*.plist
install 後も改善なし	plist が未更新	mtime 比較、必要なら --force
リモート Mac のみ	SSH ユーザーと GUI ユーザーのドメイン差	launchctl print gui/$(id -u)

3. LaunchAgent がミスを増幅する理由

plist は宣言的インフラです。トークン文字列が一度書き込まれると、明示的に bootout して編集・再読み込みしない限り再起動後も同じ値が注入されます。ローテはミニリリースと同じ厳密さで扱い、vault→plist／compose→再起動→実チャネルでのスモークまで一連で tickets に載せるのが安全です。

4. 七歩の Runbook

Step 01：フリーズと版メモ

CLI／Gateway 版、LaunchAgent Label、ローテ時刻、同時作業者を記録。

Step 02：plist を特定

~/Library/LaunchAgents/ 配下を確認。専用ユーザで動かす運用ならその $HOME を見る。

Step 03：三ソース突合

（A）plist、（B）対話シェル（参考）、（C）vault の現行値フィンガープリント。チャットに生シークレットを貼らないこと。

Step 04：bootout → 編集 → bootstrap

公式手順のドメイン／Label で bootout し、値を更新してから再登録。

Step 05：CLI で上書きするなら force

gateway install --force 等（版依存）。受け入れ基準は plist の mtime／ハッシュが変わること。

Step 06：レイヤード検証

ログで ready → 実際のチャネル往復 → UI。二枚目の plist や Docker 側二重起動に注意。

Step 07：セキュリティ

旧トークンを vault で失効、バックアップを暗号化、可能ならキーチェーンや 0600 ファイル参照へ移行。

5. リモート Mac：SSH 十項目

Unix ユーザー一致、$HOME、launchctl print の重複 Label、ProgramArguments の実バイナリパス、移行後のデータディレクトリ、ファイアウォール、Aqua ログイン要件、ログディレクトリ権限、Docker 併用時の env 優先度（Docker 稿）、チケットにはマスク済みログのみ。

6. よくある誤解

.env だけ更新、install の緑メッセージ盲信、localhost curl のみでの合格宣言は危険です。

7. アップグレード／移行との境界

breaking では device identity と検証ポリシーが同時に動きます。doctor だけ通して plist を放置すると「半分だけ緑」になります。移行稿 と合わせ単一のシークレット配管へ収束させてください。

8. インシデントタイムライン（ローテ直後 0〜30 分）

T+0–2 分：二次 install と憶測再起動を禁止し、ラベルと版情報を固定。T+3–8 分：401 の本文と gateway 側 auth 行を突合；クライアントだけ鳴るなら別リバプロ／ポート線。T+9–15 分：plist・compose（あれば）・vault を並列照合、二ソース矛盾ならネットではなく構成。T+16–25 分：bootout→編集または force→bootstrap、ロール順序はイベント中に一つだけ。T+26–30 分：ハードゲート未達なら緑灯禁止。ラック載せ Mac は肩トンできないので、手順の文章化が MTTR を決めます。

9. 二重ゲートウェイ、ポート、リバプロの罠

手動前景と launchd 常駐が別ポートになる、TLS は新しいのに proxy_pass が旧バックエンドを指す、Docker と launchd で第三の環境が増える — いずれも「トークンは正しいのに 401」に見えます。build／version を loopback と公開 DNS の双方で取り、一致を証拠にしてください。監督者はどちらか一方に寄せるか、RFC で dual-write を義務化してください。

10. plist ↔ launchctl ↔ プロセス三角形

層	健全信号	壊れ方
ファイル	mtime が変化、plutil OK	XML 破損／権限ずれ
launchctl	print 中のパスが which と一致	消した nvm パスを参照
プロセス env	フィンガープリントが vault と一致	キーが無いのに起動——別設定を読んでいる
ログ	401 と認可拒否が同期	CPU だけ高い——まず jsonl/bootstrap を疑う

systemd の EnvironmentFile 思考をそのまま持ち込まないでください。macOS は XML に埋め込みがデフォルトで、証拠三角形が無いと遠隔ヘッドレスでは迷子になります。

11. FAQ（401 が残る枝分かれ）

Q: plist を直したのにダメ。 A: launchctl print が指す実パスか確認し、クラウド同期コピーを編んでいないか。Q: 先 revoke してから再起動？ A: 危険。ローテ順序を手順書で固定。Q: doctor は緑だが IM は死ぬ。 A: 本番メッセージ往復が唯一の合格基準。Q: 多ユーザー Mac mini？ A: Unix アカウントごとにplistを分離。

12. 結論

macOS でローテ直後に全チャネルが 401 になる主因は、ほぼ真の設定ソースの分裂です。常駐 Gateway を載せる余剰ない Apple Silicon が欲しい場合は MACGPU 料金 と Telegram（キーワード MACGPU）を参照してください。公式 CLI ヘルプが最終権威です。