agent-desktop-macos

macOS の agent-desktop

観察、操作、検証のループについては、最初にコアスキル（agent-desktop skills get desktop）をお読みください。このスキルでは、macOS 固有の違いのみを扱います。症状と解決策については、references/troubleshooting.md をご覧ください。

要件

• macOS 13 以降。Intel または Apple Silicon に対応しています。
• agent-desktop を起動するアプリ（Terminal、iTerm2、Warp、VS Code、Codex）にアクセシビリティ権限が必要です。macOS 27 以降では、このリストの名前が「デバイスコントロールとデータアクセス」になります。システム設定に agent-desktop バイナリが個別に表示される場合は、それにも権限を付与してください。
• 画面収録権限が必要なのは、screenshot と session start --screenshots のアーティファクトを使用する場合のみです。
• コマンドが不足していると報告した場合に限り、システムイベントのオートメーション権限が必要です。

初回の確認

1. agent-desktop permissions を実行します。
2. 権限が拒否されている場合は、agent-desktop permissions --guide を実行します。ユーザーにリストへ追加するアプリを示すパネルとともに、適切なシステム設定ページが開きます。ユーザーが Touch ID またはパスワードで確認すると、パネルは次に不足している権限へ自動的に進みます。このコマンドは "guide": "started"、"already_running"、または "not_needed" を返してすぐに終了します。代わりに agent-desktop permissions --request を実行すると、システムの確認ダイアログが表示されます。
3. ガイドを実行できない場合は、「システム設定」>「プライバシーとセキュリティ」>「アクセシビリティ」（macOS 27 以降では「デバイスコントロールとデータアクセス」）を開きます。起動元のアプリを追加して、有効にしてください。
4. agent-desktop permissions を実行し、granted と表示されることを確認します。次の agent-desktop の呼び出しで新しい権限が認識されるため、起動元のアプリを再起動する必要はありません。
5. 確認のため、agent-desktop snapshot -i を実行します。フォーカスされているアプリを読み取ります。Finder に開いているウィンドウがない場合、snapshot --app Finder -i は WINDOW_NOT_FOUND を返します。

permissions は確認ダイアログを表示しません。permissions --request は、オートメーションを含む確認ダイアログを表示する場合があります。permissions --guide は確認ダイアログを表示せず、アクセシビリティと画面収録のみを対象とします。macOS で確認ダイアログの表示が必要な場合、オートメーションの状態は unknown と報告されます。

macOS で異なる点

ヘッド付き操作では物理操作が優先されます。click、right-click、type、clear、scroll が対象です。Core は ref のウィンドウに正確にフォーカスします。その後、アダプターが確認済みの位置に実際のクリック、キー、またはホイールイベントを送信します。expand、collapse、set-value、select、toggle、check、uncheck、focus、scroll-to は --headed の場合もセマンティック操作のままです。ダブルクリック、トリプルクリック、hover、drag には --headed が必要です。--xy による生の入力では、フォーカスは変わりません。

結果は観察して判断してください。 AX の戻りコードは、操作が反映されたことを証明するものではありません。Finder は何もしない AXConfirm に対して成功を返します。スナップショットをもう一度取得するか、get と is を使って結果を確認してください。

サーフェス。 File、Edit、View メニュー、およびメニューバーアプリ（ステータス項目）には --surface menubar を使います。メニュー、シート、アラート、ポップオーバーが開いている間は、その背後にあるウィンドウツリーの ref は対象として不適切です。

メニュー。 ヘッドレス時の right-click は AXShowMenu を使います。メニューが開いたものの、アプリが retry: unsafe を伴う APP_UNRESPONSIVE を返した場合は、再試行しないでください。--surface menu を使ってメニューを調べてください。コンボボックスやメニューボタンには、select @ref "Option" を使います。select には、メニューが閉じた状態から開く状態への遷移が必要なため、開いているメニューは先に閉じてください。

通知センター。 通知コマンドは、コアの commands-system リファレンスに記載されたルールに従って、アクセシビリティ経由で通知センターを操作します。agent-desktop が通知センターを開いた場合は、操作後に通知センターを閉じ、以前のアプリのフォーカスを復元します。スタックの位置は変わるため、通知を閉じる操作やアクションでは、--expected-app と --expected-title の両方を指定してください。一覧表示する前に消えてしまうバナーには、wait --notification --app "App" を使います。

Chromium と Electron。 agent-desktop は必要に応じて、Chromium レンダラーのウェブアクセシビリティを自動的に有効にします。実行中のアプリが複雑な場合は、snapshot --skeleton -i --compact を使ってから、--root @ref で詳細を確認してください。

識別方法。 launch は表示名（"System Settings"）またはバンドル ID（com.apple.systempreferences）を受け付けます。他のコマンドには、--app で表示名を指定します。w-4521 などのウィンドウ ID は、そのウィンドウが存続する限り有効です。list-windows で確認してください。

キー。 主修飾キーは cmd です。例：press cmd+c、press cmd+s。cmd+q、cmd+shift+q、cmd+alt+esc、ctrl+cmd+q、cmd+shift+delete などの終了ショートカットは、--force を指定しない限り POLICY_DENIED を返します。アプリを終了するには、close-app を使います。句読点キーは、記号（, . / ; ' [ ] \ - = `）または名前（comma、period、slash、semicolon、quote、leftbracket、rightbracket、backslash、minus、equal、grave）を使ってキーの組み合わせを指定できます。それぞれ、アクティブなキーボードレイアウトでその文字を入力するキーとして送信されるため、ANSI キーボードでも JIS キーボードでも press cmd+, で設定が開きます。

カーソルオーバーレイ。 cursor-overlay enable は、クリックが透過するウィンドウにエージェントのカーソルを描画します。OS のポインターを動かしたり、アプリをアクティブにしたりすることはありません。macOS のモーションと画像に関する制限は、コアの commands-system リファレンスに記載されています。

次のステップ

コマンドが失敗した場合は、references/troubleshooting.md で該当する症状を確認してください。