2026 OpenClaw ネイティブ macOS：公式アプリと CLI、OPENCLAW_STATE_DIR、TCC、LaunchAgent と二重 Gateway Runbook

読了の目安 約14分 · MACCOME

概要（スニペット向け）：本稿は Docker コンテナより前に現れるネイティブ macOS の事実だけを扱います。公式パッケージアプリまたは openclaw CLI を前提に、OPENCLAW_STATE_DIR を iCloud 同期下のフォルダから外すこと、透明性・同意・プライバシー（TCC）でアクセシビリティ・自動化（AppleEvents）・画面収録などを明示的に許可すること、そしてLaunchAgent 管理と手動の openclaw gateway start が衝突して二重リスナーになる問題を避けることに焦点を当てます。openclaw doctor と openclaw gateway status で検証し、ローカル権威 Gateway とリモート権威 Gateway のオペレーション差を説明できる状態を目標とします。三 OS インストール概要および Docker 本番 Gateway Runbook と冗長にならないよう役割分担します。

Docker／三 OS の記事とは別チェックリストが必要な六つの理由

  1. iCloud が「デスクトップと書類」を同期すると inode レイヤの挙動が揺らぎます。UNIX ドメインソケットやロックに敏感な状態は、コンテナとは別の不定期失敗を生みます。
  2. TCC はバイナリ単位です。ターミナル経由の openclaw とバンドルアプリのヘルパーは別主体で、パスが変われば再許可が必要になります。
  3. アクセシビリティ許可だけでは自動化ブリッジが止まります。AppleScript／OSA が止まったように見える事象につながります。
  4. 画面収録は別枠です。ピクセル経路だけが静音で待つケースがあります。
  5. launchd と手動親プロセスが二重化するとトークンの分裂やポート競合が起きます。
  6. ノートパソコンの睡眠は可用性関数です。権威ゲートウェイとしての SLA を壊します。

クロスプラットフォーム設計は インストール & デプロイガイド と インストール後 doctor／WSL2 近傍トラブルシュート が基準になります。Compose 側は Docker 本番 Runbook を優先してください。地域とリース試算は マルチリージョン Mac mini 契約ガイド と併読します。

OPENCLAW_STATE_DIR：ローカル APFS に固定します

/usr/local/var/openclaw や /opt/openclaw/state など、管理者が所有するローカルボリュームを推奨します。Mobile Documents 配下やクラウド同期クライアントの仮想フォルダは避けてください。複数ユーザーで同一ディレクトリを共有する設計も、ロックとローテーションで壊れやすいので禁止か明示的クラスタのみにしてください。

最初の 15 分：兆候トリアージ表

各行にオーナーを一人割り当て、ロールバック手順を一文に収めます。

兆候 ありがちな根 安定化アクション
ペアリングが再起動だけで復帰する 同期ボリュームまたは二親プロセス ディスクをローカルに移し、スケジューラは一種類のみ
UI 自動化スタック TCC の自動化／アクセシビリティ欠落 システム設定から該当バイナリを再承認
キャプチャが返らない 画面収録未許可 許可後に親プロセスを再起動
アドレスイン-use LaunchAgent と手動起動の競合 テスト plist を bootout、または対話のみモードへ統一
夜間のみ失敗 スリープと省電力ネットワーク 権威ホストを常時オン遠隔 Mac に移す
warning

二重スケジューラ禁止が安全です：本番が launchd なら手動 gateway は短命のデバッグ専用とし、bootout 手順を Runbook に併記します。

TCC で実際に触る項目

アクセシビリティ、アクセス権の自動化（AppleEvents）、画面収録が主戦場です。音声入力スキルを使うならマイクも別途許可してください。メジャー OS／パッケージ更新のたびに 10 分の再確認ラインを運用カレンダーへ入れます。

LaunchAgent と手動 gateway start

無人運用ホストには LaunchAgent が向きます。開発者ワークステーションだけを対象にするなら対話のみの方がログが読みやすいです。launchctl print gui/$uid/<label> で実体を確認し、幽霊プロセスと戦わないようにします。

ローカル Gateway とリモート Gateway の決定的差分

ローカルは反復が速い一方、スリープと VPN と会議 Wi-Fi に弱くなります。リモートは固定電源と固定 egress に権威状態を載せられるため、地域別レンタルとの相性が良いです。OPENCLAW_STATE_DIR の実ディスク所有者をサービスカタログに書き込みます。

七ステップのネイティブ macOS Runbook

  1. チャネルと pin を統一します。
  2. ローカルディレクトリと POSIX 所有者を決めます。
  3. TCC を一度通過し証跡を残します。
  4. 権威ホスト宣言（どちらのマシンが正か）を文書化します。
  5. LaunchAgent と手動のどちらを正とするかを固定します。
  6. 単一親 PID でスモーク接続します。
  7. doctor／gateway status を変更票に貼ってから本番配線へ進みます。

Compose と責務が重なるときは必ず記事単位で分割し、doctor フィールドだけを並べないでください。

bash
#!/usr/bin/env bash
set -euo pipefail
export OPENCLAW_STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/Library/Application Support/OpenClawState-local}"
umask 077
mkdir -p "$OPENCLAW_STATE_DIR"
echo "OPENCLAW_STATE_DIR=$OPENCLAW_STATE_DIR"
command -v openclaw >/dev/null && openclaw doctor || echo "doctor: PATH に CLI なし"
openclaw gateway status 2>/dev/null || echo "gateway: 応答なし（停止中ならよい）"
launchctl print "gui/$(id -u)" 2>/dev/null | grep -i openclaw || echo "launchd: openclaw ラベル未検出"

ダッシュボードへ載せる三つの計測

  • 再起動から初回正常 gateway status までの秒数。
  • df で状態ディレクトリがローカル APFS と証明できること。
  • 定常状態で親ゲートウェイ PID が単一であること。

ノート単体での 24/7 運用が崩れやすい理由とリモート Mac の勝ち筋

ノートは人間優先設計であり、権威自動化とは相性が悪いことが多いです。シンガポール／東京／ソウル／香港／米国沿岸に常時オン Mac mini を置くと LaunchAgent と TCC が安定します。契約ガイド で RTT を踏まえた配置を確認してください。

締め：チケット分類ルールを分けます

TCC とパス問題はネイティブ Runbook に、コンテナ_DIGEST とブリッジは Compose Runbook に分けます。変更の締めに openclaw doctor を再走し、ログを semver と一緒に保管します。

FAQ

本番 Gateway は Docker 統一です。LaunchAgent の知識は必要ですか。

はい、GUI とノートによる一次接続はまだ原生で完結することがあります。launchd と Compose の境界を説明できると二重ゲートウェイ事故を削れます。

常時 Gateway を載せる Mac を借りたいときはどこを読みますか。

レンタル料金でまずノード試算をしてください。請求詳細や導線の質問は ヘルプセンターへ回します。