OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

macOS companion app

macOS 上の Gateway

OpenClaw.app には Node や Gateway ランタイムはバンドルされていません。macOS アプリは 外部の openclaw CLI インストールを必要とし、Gateway を 子プロセスとして起動せず、ユーザーごとの launchd サービスを管理して Gateway の 実行を維持します（または、すでに実行中のローカル Gateway に接続します）。

自動セットアップ

新しい Mac では、オンボーディング中に This Mac を選択します。アプリは Gateway ウィザードの前に、署名済みのバンドルされたインストーラースクリプトを実行します。 このスクリプトは、ユーザー領域の Node ランタイムと対応する openclaw CLI を ~/.openclaw 配下にインストールしてから、ユーザーごとの launchd サービスを インストールして起動します。この手順では Terminal、Homebrew、管理者アクセスは 必要ありません。

アプリにバンドルされるのはインストーラースクリプトのみで、Node や Gateway の ペイロードは含まれません。セットアップでランタイムと対応する OpenClaw パッケージを ダウンロードするには、インターネット接続が必要です。

手動復旧

手動インストールには Node 24.15+ を推奨します。Node 22.22.3+ も使用できます。 openclaw をグローバルにインストールします。

bash
npm install -g openclaw@<version>

自動セットアップに失敗した後は、Retry setup を使用します。それでも失敗する場合は、 上記のコマンドで CLI を手動インストールしてから、オンボーディングで Check again を選択します。

Launchd（LaunchAgent としての Gateway）

ラベル: デフォルトプロファイルでは ai.openclaw.gateway、名前付きプロファイルでは ai.openclaw.<profile>。

Plist の場所（ユーザーごと）: ~/Library/LaunchAgents/ai.openclaw.gateway.plist （または ai.openclaw.<profile>.plist）。

ローカルモードでは、macOS アプリがデフォルトプロファイルの LaunchAgent の インストールと更新を管理します。CLI から直接インストールすることもできます: openclaw gateway install （名前付きプロファイルは OPENCLAW_PROFILE 環境変数で選択します）。

動作:

  • 「OpenClaw Active」で LaunchAgent を有効化または無効化します。
  • アプリを終了しても Gateway は停止しません（launchd が実行を維持します）。
  • 設定されたポートですでに Gateway が実行されている場合、アプリは 新しい Gateway を起動せず、その Gateway に接続します。

ログ:

  • launchd の標準出力: ~/Library/Logs/openclaw/gateway.log（プロファイルでは gateway-<profile>.log）
  • launchd の標準エラー出力: 抑制
  • ホストで EADDRINUSE が繰り返し発生するループや高速な再起動が 発生する場合は、重複する ai.openclaw.gateway / ai.openclaw.node LaunchAgent と、 Gateway のトラブルシューティングにある launchd マーカーの回避策を確認してください。

バージョン互換性

macOS アプリは Gateway のバージョンを自身のバージョンと照合します。既存の CLI が 見つからないか互換性がない場合、オンボーディングによって管理対象セットアップが 自動的に実行されます。インストールを再実行するには Retry setup を使用し、 外部 CLI の修復後は Check again を使用します。

macOS の状態ディレクトリ

OpenClaw の状態は、同期されないローカルディスクに保存してください。iCloud Drive や その他のクラウド同期フォルダーは避けてください。同期の遅延やファイルロックが、 セッション、認証情報、Gateway の状態に影響する可能性があります。

上書きが必要な場合に限り、OPENCLAW_STATE_DIR にローカルパスを設定します。 openclaw doctor は、一般的なクラウド同期対象の状態パスについて警告し、 ローカルストレージへ戻すことを推奨します。 環境変数と Doctorを参照してください。

アプリ接続のデバッグ

ソースチェックアウトから macOS デバッグ CLI を使用して、アプリと同じ Gateway WebSocket ハンドシェイクおよび検出ロジックを実行します。

bash
cd apps/macosswift run openclaw-mac connect --jsonswift run openclaw-mac discover --timeout 3000 --json

connect は --url、--token、--timeout、--probe、--json を受け付けます（クライアント ID の上書きも可能です。完全な一覧は --help を指定して実行してください）。 discover は --timeout、--json、--include-local を受け付けます。 CLI の検出とアプリ側の接続の問題を切り分ける必要がある場合は、検出結果を openclaw gateway discover --json と比較してください。

スモークチェック

bash
openclaw --version OPENCLAW_SKIP_CHANNELS=1 \OPENCLAW_SKIP_CANVAS_HOST=1 \openclaw gateway --port 18999 --bind loopback

次に実行します。

bash
openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000

関連項目

Was this useful?
On this page

On this page