macOS Developer Setup

このガイドでは、OpenClaw macOSアプリケーションをソースからビルドして実行するために必要な手順を説明します。

前提条件

アプリをビルドする前に、以下がインストールされていることを確認してください:

  1. Xcode 26.2+: Swift開発に必要。
  2. Node.js 22+ & pnpm: Gateway、CLI、パッケージングスクリプトに必要。

1. 依存関係をインストール

プロジェクト全体の依存関係をインストール:

pnpm install

2. アプリをビルドしてパッケージ化

macOSアプリをビルドしてdist/OpenClaw.appにパッケージ化するには、以下を実行:

./scripts/package-mac-app.sh

Apple Developer ID証明書を持っていない場合、スクリプトは自動的にad-hoc signing（-）を使用します。

dev実行モード、署名フラグ、Team IDトラブルシューティングについては、macOSアプリREADMEを参照してください: https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

注: Ad-hoc署名アプリはセキュリティプロンプトをトリガーする場合があります。アプリが「Abort trap 6」で即座にクラッシュする場合は、Troubleshootingセクションを参照してください。

3. CLIをインストール

macOSアプリはバックグラウンドタスクを管理するためにグローバルなopenclaw CLIインストールを期待します。

インストール方法（推奨）:

  1. OpenClawアプリを開きます。
  2. General設定タブに移動します。
  3. **「Install CLI」**をクリックします。

または、手動でインストール:

npm install -g openclaw@<version>

トラブルシューティング

ビルド失敗: ツールチェーンまたはSDKの不一致

macOSアプリビルドは、最新のmacOS SDKとSwift 6.2ツールチェーンを期待します。

システム依存関係（必須）:

  • Software Updateで利用可能な最新macOSバージョン（Xcode 26.2 SDKsに必要）
  • Xcode 26.2（Swift 6.2ツールチェーン）

チェック:

xcodebuild -version
xcrun swift --version

バージョンが一致しない場合は、macOS/Xcodeを更新してビルドを再実行してください。

権限許可時にアプリがクラッシュ

Speech RecognitionまたはMicrophoneアクセスを許可しようとしたときにアプリがクラッシュする場合、TCC cacheの破損または署名の不一致が原因である可能性があります。

修正:

  1. TCC権限をリセット: 
    tccutil reset All bot.molt.mac.debug
  2. それでも失敗する場合は、scripts/package-mac-app.shでBUNDLE_IDを一時的に変更して、macOSから「クリーンスレート」を強制します。

Gateway「Starting...」が無期限に続く

Gatewayステータスが「Starting...」のままの場合、ゾンビプロセスがポートを保持しているか確認:

openclaw gateway status
openclaw gateway stop

# LaunchAgentを使用していない場合（devモード/手動実行）、リスナーを見つける:
lsof -nP -iTCP:18789 -sTCP:LISTEN

手動実行がポートを保持している場合、そのプロセスを停止します（Ctrl+C）。最後の手段として、上記で見つけたPIDをkillします。

← ドキュメントに戻る