macOSでのGatewayライフサイクル管理

バックグラウンドで動作するツールを管理するのは、意外と面倒なものです。いつの間にかプロセスが落ちていたり、PCを再起動するたびに手動で立ち上げ直したりするのは、開発のリズムを乱す原因になります。

こうした手間を省き、バックグラウンドプロセスを意識せずに開発に集中できる状態が理想的です。macOS版のアプリでは、このプロセス管理をスマートに行う仕組みを取り入れています。

必要なもの

• macOS アプリ
• openclaw CLI（外部ツール）
• ターミナル操作の基礎知識

クイックスタート

macOS アプリは、デフォルトで launchd を使用して Gateway を管理します。アプリが Gateway を子プロセスとして直接生成することはありません。

1. 接続の確認: アプリはまず、設定されたポートですでに動作している Gateway への接続を試みます。
2. 自動起動: 接続できない場合、外部の openclaw CLI を介して launchd サービスを有効にします。
3. プロセスの維持: これにより、ログイン時の自動起動やクラッシュ時の自動再起動が実行されます。
4. ログの確認: ログは launchd の Gateway ログパスに書き込まれます（Debug Settings で確認可能です）。

手動で操作が必要な場合は、以下のコマンドを使用してください。

# Gatewayの再起動
launchctl kickstart -k gui/$UID/bot.molt.gateway

# Gatewayの停止
launchctl bootout gui/$UID/bot.molt.gateway

※ プロファイルを使用している場合は、ラベルを bot.molt.<profile> に置き換えてください。

トラブルシューティング

署名のない開発ビルドで起動しない

scripts/restart-mac.sh --no-sign を使用して署名なしのビルドを行うと、launchd が署名のないバイナリを参照するのを防ぐために ~/.openclaw/disable-launchagent が作成されます。

解決策: 手動でリセットするには、以下のコマンドを実行してください。

rm ~/.openclaw/disable-launchagent

なお、署名ありの状態で scripts/restart-mac.sh を実行すれば、この設定は自動的に解除されます。

launchd を使用したくない

アプリに launchd を管理させたくない場合は、--attach-only（または --no-launchd）フラグを付けてアプリを起動してください。

解決策: このフラグを使用すると ~/.openclaw/disable-launchagent が設定され、アプリは既存の Gateway へのアタッチのみを行うようになります。この挙動は Debug Settings からも切り替え可能です。

なぜ launchd を使うのか

私たちは、以下の理由から launchd による管理を推奨しています。

• ログイン時の自動起動ができること
• 再起動や KeepAlive の仕組みが組み込まれていること
• ログの出力先が予測可能であること
• プロセスの監視が標準化されていること

現在、アプリが直接 Gateway を起動する「子プロセスモード」は使用されていません。UI とより密接に連携させる必要がある場合は、ターミナルから手動で Gateway を実行してください。

Remote mode について

Remote mode では、ローカルの Gateway は起動しません。アプリはリモートホストへの SSH トンネルを作成し、そのトンネルを経由して接続します。

詳細な設定や不明な点がある場合は、AI Setup Assistant を活用してください。

次のステップ

• CLI リファレンス
• Debug Settings の使い方