OpenClaw のゲートウェイは共有シークレットで RPC クライアントを認証する。macOS では実際にはそのシークレットが3 つの経路を通る：ディスク上の openclaw.json ツリー、設定を書き換えうるmacOS App のウィザード、ヘッドレスセッションに変数を注入するLaunchAgent の環境ブロック。いずれかの層が食い違うと、オペレーターは幽霊を追う：openclaw status は健康でもメニューバーアプリは切断を示す。本文は2 つのマトリクス、8 ステップのロールアウト、7 ステップの HowTo シーケンスを与え、Mac mini M4 のゲートウェイホストが「直った」と「401 Unauthorized」の間で振れ止まらせる。
出発点：トークン認証と launchd ドリフト。エージェントセッションの外で ゲートウェイ再起動を維持。ベースライン：インストールとデプロイ。ヘルス：doctor と診断。アカウント：ヘルプ。ホスト追加：料金。
「トークン分裂」を叫ぶ症状、「壊れたモデル」ではない
- 分裂人格：CLI は成功するがメニューバーアプリはセットアップでループする。
- 再起動後だけ 401：loginwindow セッションに env がなくファイルのトークンは正しい。
- アップグレード後 401：App がマイナー更新で JSON を書き換えたが launchd は古い変数をまだエクスポートしている。
- 断続的成功：リロード中に 2 つのゲートウェイプロセスが異なる設定で短時間競合する。
マトリクス A：各クライアントがどこから資格情報を読むか
| クライアント | プライマリソース | よくあるドリフト | 安定化 |
|---|---|---|---|
| SSH 越しの CLI | ユーザーホームの openclaw.json |
サービスユーザーと管理者で $HOME が異なる |
編集前は常にサービスアカウントに sudo |
| macOS App | サンドボックス化された設定＋ JSON マージ | 「ゲートウェイなし」検出後のウィザード上書き | 変更管理で App バージョンをピン留め。ファイルが正規になってから App を開く |
| launchd ゲートウェイ | Plist EnvironmentVariables と作業ディレクトリのファイル | 古い OPENCLAW_GATEWAY_TOKEN の export |
両方を原子更新する単一ライタースクリプト |
| 自動化エージェント | 親シェルから継承した env | ツールサンドボックスが env を剥ぐとトークン欠落 | ツールマニフェストで明示的な設定パスフラグ |
マトリクス B：ロールアウトリスクと緩和
| 変更 | ブラスト半径 | 緩和 |
|---|---|---|
| 月次トークンローテーション | クライアントがリロードするまでの全チャネル | 旧＋新を 15 分間デュアルライトし 401 率を監視 |
| ゲートウェイユーザーを移動 | 絶対パスと plist ラベル | シンボリックリンクを再作成。リカバリー記事の --force パターンで再インストール |
| 第 2 リージョンホスト追加 | オペレーターが間違ったホストにトークンを貼る | ボルト内でホストごとのシークレット名。クリップボードマクロの再利用はしない |
| 非 loopback バインドを有効化 | より厳格な認証要件 | ゲートウェイレート制限 の許可リストとペア |
数値ガードレール
- ローテーション重複：ディスクに新トークンを公開した後、旧トークンは少なくとも 900 秒有効のままにする。
- 等価チェック：本番ゲートウェイで plist env とファイルトークンを 6 時間ごとに自動 diff。
- インシデント予算：401 率が 5 分間 RPC の 1% を超えたら App アップグレードを自動凍結。
GUI のヒント：macOS のプライバシプロンプトが無人トークン書き込みをブロックする場合、一度 VNC で承認し、その後は SSH のみのメンテに戻す。
8 つのロールアウトステップ
- 所有権宣言：各ホストの正規トークンファイルパス。
- launchd と争うシェルから重複 export を削除。
- バックアップパス付きで JSON＋plist を 1 トランザクションで原子更新するスクリプト。
- 層間でハッシュが異なればデプロイ失敗する CI 風チェックを追加。
- CMDB 行にゲートウェイの semver の横へ App バージョンピンを文書化。
- 毎回のアップグレード後に doctor を実行してから「healthy」と宣言。
- オンコール教育：401 ログをまず設定ドリフト、次にモデル障害として読む。
- 単一ライターで合意できないチームは、本番とラボを別の NodeMac Mac mini M4 に分割。
FAQ
トークンをキーチェーンに置く方が良いか？
すべてのコンシューマが一貫してサポートするならそうできることが多い。混合スタックは通常まずファイル＋plist を同期し、その後移行する。
チームメンバーのラップトップは？
本番トークンをラップトップで再利用しない。短命の dev トークンと分離ゲートウェイホストで、カフェからの誤った本番 RPC を防ぐ。
launchd はシェルプロファイルを継承するか？
しない。だからこそ再起動後に plist またはゲートウェイが読むファイルへコピーするまでトークンが「消える」のだ。
トークン衛生は地味なハードウェアを好む：NodeMac の専用 Mac mini M4 は常時オンゲートウェイに Apple Silicon の余裕、開発者ラップトップと同一のネイティブ macOS 挙動、GUI 同意が自動化をブロックするときの SSH プラス VNC を与える。香港・日本・韓国・シンガポール・アメリカのノードでユーザーの隣にゲートウェイを置きつつ、共有ラップトップからシークレットを外せる。購入ではなくレンタルなら「本番ゲートウェイ」と「ラボゲートウェイ」を安く分離でき、トークンローテーションが政治闘争にならない。ホストを分けるときは リージョン別料金 から。