Back to Details

agent-desktop-macos

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

agent-desktop on macOS

macOS 上的 agent-desktop

Read the core skill first (
agent-desktop skills get desktop
) for the observe, act, verify loop. This skill covers only what is different on macOS. Symptoms and fixes are in references/troubleshooting.md.
先阅读核心 skill（
agent-desktop skills get desktop
），了解 observe（观察）、act（操作）、verify（验证）循环。本 skill 仅涵盖 macOS 上存在差异的部分。症状和修复方法见 references/troubleshooting.md。

Requirements

环境要求

  • macOS 13 or later, Intel or Apple Silicon.
  • Accessibility permission for the app that launches agent-desktop (Terminal, iTerm2, Warp, VS Code, Codex). macOS 27 and later name this list Device Control and Data Access. If System Settings lists the 
    agent-desktop
    binary separately, grant it too.
  • Screen Recording permission, only for 
    screenshot
    and for 
    session start --screenshots
    artifacts.
  • Automation permission for System Events, only where a command reports it missing.
  • macOS 13 或更高版本，支持 Intel 或 Apple Silicon。
  • 为启动 agent-desktop 的应用（Terminal、iTerm2、Warp、VS Code、Codex）授予 Accessibility 权限。在 macOS 27 及更高版本中，macOS 将此列表命名为 Device Control and Data Access。如果 System Settings 中单独列出了 
    agent-desktop
    二进制文件，也请为其授予权限。
  • 授予 Screen Recording 权限；仅在使用 
    screenshot
    或 
    session start --screenshots
    生成产物（artifacts）时需要。
  • 为 System Events 授予 Automation 权限，但仅在命令报告缺少该权限时需要。

First contact

首次使用

  1. Run 
    agent-desktop permissions
    .
  2. If a permission is denied, run 
    agent-desktop permissions --guide
    . It opens the correct System Settings page with a panel that shows the user which app to drag into the list. The user confirms with Touch ID or a password, and the panel moves to the next missing permission by itself. The command returns at once with 
    "guide": "started"
    , 
    "already_running"
    or 
    "not_needed"
    . 
    agent-desktop permissions --request
    shows the system prompts instead.
  3. If the guide cannot run, open System Settings > Privacy & Security > Accessibility (Device Control and Data Access on macOS 27 and later). Add the launching app and turn it on.
  4. Run 
    agent-desktop permissions
    to confirm 
    granted
    . The next agent-desktop call sees a new grant, so the launching app does not need a restart.
  5. Run 
    agent-desktop snapshot -i
    to confirm. It reads the focused app. 
    snapshot --app Finder -i
    returns 
    WINDOW_NOT_FOUND
    when Finder has no open window.
permissions
does not prompt. 
permissions --request
can prompt, including for Automation. 
permissions --guide
does not prompt and covers Accessibility and Screen Recording only. Automation reports 
unknown
when macOS would need to prompt.
  1. 运行 
    agent-desktop permissions
    。
  2. 如果某项权限被拒绝，运行 
    agent-desktop permissions --guide
    。它会打开正确的 System Settings 页面，并显示一个面板，告知用户需要将哪个应用拖入列表。用户通过 Touch ID 或密码确认后，面板会自动移至下一项缺失的权限。该命令会立即返回 
    "guide": "started"
    、
    "already_running"
    或 
    "not_needed"
    。
    agent-desktop permissions --request
    则会显示系统权限提示。
  3. 如果无法运行该指南，请打开 System Settings > Privacy & Security > Accessibility（macOS 27 及更高版本为 Device Control and Data Access）。添加启动 agent-desktop 的应用并开启权限。
  4. 运行 
    agent-desktop permissions
    ，确认状态为 
    granted
    。下一次调用 agent-desktop 时即可看到新授予的权限，因此无需重启用于启动它的应用。
  5. 运行 
    agent-desktop snapshot -i
    进行确认。它会读取当前获得焦点的应用。
    snapshot --app Finder -i
    在 Finder 没有打开任何窗口时会返回 
    WINDOW_NOT_FOUND
    。
permissions
不会弹出权限提示。
permissions --request
可以弹出提示，包括 Automation 权限。
permissions --guide
不会弹出提示，且仅涵盖 Accessibility 和 Screen Recording 权限。如果 macOS 需要弹出提示，Automation 的状态会报告为 
unknown
。

What differs on macOS

macOS 上的差异

Headed is physical first for 
click
, 
right-click
, 
type
, 
clear
and 
scroll
. Core focuses the exact window of the ref. The adapter then sends a real click, key or wheel event to the verified point. 
expand
, 
collapse
, 
set-value
, 
select
, 
toggle
, 
check
, 
uncheck
, 
focus
and 
scroll-to
stay semantic under 
--headed
. Double-click, triple-click, 
hover
and 
drag
need 
--headed
. Raw 
--xy
input never changes focus.
Judge delivery by observation. AX return codes do not prove an effect. Finder returns success from an 
AXConfirm
that does nothing. Snapshot again or use 
get
and 
is
to check the result.
Surfaces. Use 
--surface menubar
for File, Edit and View menus and for menu bar apps (status items). While a menu, sheet, alert or popover is open, refs from the window tree behind it are the wrong target.
Menus. 
right-click
headless uses 
AXShowMenu
. If the menu opened but the app returned 
APP_UNRESPONSIVE
with 
retry: unsafe
, do not retry. Inspect the menu with 
--surface menu
. For combo boxes and menu buttons, use 
select @ref "Option"
. 
select
needs a closed-to-open menu transition, so dismiss any open menu first.
Notification Center. The notification commands drive Notification Center through accessibility, with the rules in the core 
commands-system
reference. When agent-desktop opens the center, it closes it afterwards and restores the previous app focus. Pass both 
--expected-app
and 
--expected-title
on a single dismiss or action, because the stack shifts. Use 
wait --notification --app "App"
for banners that vanish before you list them.
Chromium and Electron. agent-desktop switches on the web accessibility of a Chromium renderer automatically when it needs it. For a dense running app, use 
snapshot --skeleton -i --compact
, then drill with 
--root @ref
.
Identity. 
launch
accepts a display name (
"System Settings"
) or a bundle ID (
com.apple.systempreferences
). Other commands take the display name through 
--app
. Window IDs such as 
w-4521
stay valid for the life of the window. Find them with 
list-windows
.
Keys. The primary modifier is 
cmd
: 
press cmd+c
, 
press cmd+s
. Quit shortcuts such as 
cmd+q
, 
cmd+shift+q
, 
cmd+alt+esc
, 
ctrl+cmd+q
and 
cmd+shift+delete
return 
POLICY_DENIED
unless you pass 
--force
. To quit an app, use 
close-app
. Punctuation keys work in combos, as the symbol (
,
.
/
;
'
[
]
\
-
=
`
) or by name (
comma
, 
period
, 
slash
, 
semicolon
, 
quote
, 
leftbracket
, 
rightbracket
, 
backslash
, 
minus
, 
equal
, 
grave
). Each one is sent with the key that types it in the active keyboard layout, so 
press cmd+,
opens Settings on ANSI and JIS keyboards alike.
Cursor overlay. 
cursor-overlay enable
draws the agent cursor in a click-through window. It never moves the OS pointer or activates an app. The macOS motion and image limits are in the core 
commands-system
reference.
Headed 以物理操作为先。 对于 
click
、
right-click
、
type
、
clear
和 
scroll
，headed 模式会优先执行物理操作。Core 会将焦点置于 ref 对应的准确窗口，随后 Adapter 将真实的点击、按键或滚轮事件发送到已验证的位置。在 
--headed
下，
expand
、
collapse
、
set-value
、
select
、
toggle
、
check
、
uncheck
、
focus
和 
scroll-to
仍保持语义化操作。
double-click
、
triple-click
、
hover
和 
drag
需要使用 
--headed
。直接使用 
--xy
输入时，焦点绝不会改变。
通过观察判断操作是否送达。 AX 返回码不能证明操作已生效。Finder 的 
AXConfirm
即使未执行任何操作，也会返回成功。请再次 snapshot，或使用 
get
和 
is
检查结果。
界面层（Surfaces）。 对于 File、Edit 和 View 菜单以及菜单栏应用（状态项），使用 
--surface menubar
。当 menu、sheet、alert 或 popover 处于打开状态时，来自后方窗口树中的 ref 是错误的操作目标。
菜单（Menus）。 headless 模式下的 
right-click
使用 
AXShowMenu
。如果菜单已经打开，但应用返回 
APP_UNRESPONSIVE
且带有 
retry: unsafe
，不要重试。使用 
--surface menu
检查菜单。对于组合框（combo box）和菜单按钮（menu button），使用 
select @ref "Option"
。
select
需要菜单经历一次从关闭到打开的状态转换，因此请先关闭任何已打开的菜单。
Notification Center。 notification 命令通过 Accessibility 控制 Notification Center，并遵循核心 
commands-system
reference 中的规则。agent-desktop 打开通知中心后，会将其关闭并恢复之前的应用焦点。由于界面栈会发生变化，请在单次 dismiss 或 action 操作中同时传入 
--expected-app
和 
--expected-title
。对于在列出之前就会消失的横幅通知，使用 
wait --notification --app "App"
。
Chromium 与 Electron。 agent-desktop 会在需要时自动开启 Chromium renderer 的 web accessibility。对于界面内容密集且正在运行的应用，使用 
snapshot --skeleton -i --compact
，然后使用 
--root @ref
逐层定位。
标识（Identity）。 
launch
接受显示名称（
"System Settings"
）或 bundle ID（
com.apple.systempreferences
）。其他命令通过 
--app
传入显示名称。窗口 ID（如 
w-4521
）在窗口生命周期内始终有效。可使用 
list-windows
查找这些 ID。
按键（Keys）。 主修饰键是 
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
）。每个标点都会通过当前活动键盘布局中能够输入该符号的按键发送，因此 
press cmd+,
在 ANSI 和 JIS 键盘上都能打开 Settings。
光标叠加层（Cursor overlay）。 
cursor-overlay enable
会在 click-through 窗口中绘制 agent cursor。它绝不会移动 OS pointer，也不会激活应用。macOS 的 motion 和 image 限制见核心 
commands-system
reference。

Next step

下一步

When a command fails, find the symptom in references/troubleshooting.md.
命令执行失败时，请在 references/troubleshooting.md 中查找对应症状。