本地 API 与桌面任务
最近更新:2026/11/13
桌面端自带两样自动化工具:本地 API 让这台电脑上的脚本、命令行和 AI 助手经桌面端操作设备,不用签发 token;自动化任务不写代码,把一组操作手动或定时运行。两者都只在桌面端开着并已登录时可用。
本地 API
在桌面端的「账户设置 → 自动化」里可以看到「本地 API」卡片:
- 「启用本地 API」开关,缺省打开;
- 地址,只监听本机(
http://127.0.0.1:<端口>,通常是 53070 端口); - 令牌,缺省遮住,可以显示、复制,确认后重置;
- 凭据文件
cli-auth.json的位置。
令牌在每次启动桌面端和每次重置时重新生成。本地 API 只接受本机发来、带着令牌的请求;桌面端联网校验失败、被锁定时,本地 API 也会拒绝请求。开关是灰的,说明你的角色没有「本机 API」权限。
用命令行
命令行加 --local 就会改经本地 API 执行,它自己读取凭据文件,不需要登录:
yunyoo --local devices
yunyoo --local --device env:123 observe screenshot --out a.png
yunyoo --local --device env:123 ui tap --text OK
yunyoo --local tasks list
本地 API 能操作这台电脑上本地节点里的环境,也能经桌面端操作云端节点上的环境。本地节点上的环境由这台电脑直接执行,速度更快。
用 AI 助手
yunyoo --local mcp
以本机方式提供 MCP 工具,助手的配置写法见 MCP,把参数写成 --local mcp 即可。桌面端 1.1.0 起,工具清单按你账号的权限裁剪;开关机工具 env_power 只在这种方式下提供。
其它程序
其它程序可以带令牌直接请求本地 API,例如列出设备:
curl -s -H "Authorization: Bearer $CPD_TOKEN" http://127.0.0.1:53070/api/devices
把卡片上的令牌放进环境变量 CPD_TOKEN。令牌每次启动都会变,长期运行的程序请每次从凭据文件读取。
自动化任务
在桌面端侧栏打开「自动化」,点「新建任务」:
- 填写名称,选择运行方式:「手动」或「定时」。定时用 cron 表达式,也可以选常用规则,页面会列出接下来五次的运行时间,时间按这台电脑的时区计算。
- 选择设备:选定的设备各运行一次,离线的跳过;不选时在第一台在线设备上运行(本地节点上的环境优先,其次云端节点上的环境),也可以改为在所有在线设备上运行。
- 写动作:一个 JSON 数组,每项是一个动作。可以从「插入动作」里选模板,也可以点「在查看器中录制」,在查看器工具栏打开「录制任务步骤」,把你的点按、滑动和输入录成动作。
[
{ "action": "screenshot", "args": { "localPath": "/Users/me/shots/home.png" } },
{ "action": "ui-action", "args": { "action": "tap", "point": { "x": 0.5, "y": 0.5 } } },
{ "action": "wait", "args": { "ms": 1000 } },
{ "action": "wp:app", "args": ["launch", "com.android.settings"] },
{ "action": "wp:macro", "args": ["run", "/Users/me/flows/login-smoke.yaml"], "timeoutSec": 600 }
]
- 每个动作有
action、args,可选timeoutSec(缺省 60 秒,最多 3600 秒)与continueOnError(这一步失败后是否继续,缺省不继续)。一个任务最多 200 个动作,坐标用 0 到 1 的屏幕比例。 - 本机动作:
screenshot、ui-dump、ui-action、shell、push、pull、install、wait。 wp:开头的动作由桌面端自带的命令行以本机方式执行,可用的命令有devices、observe、ui、run、file、app,桌面端 1.1.0 起还有macro;args写成参数数组,就是命令后面的参数。wp:macro用来运行流程宏;流程在某一步对不上界面时,这次运行记为失败,失败原因里写明停在第几步和原因。- 保存时会检查每个动作,写错时指出是第几个动作、哪里不对。
保存后可以在列表里「立即运行」,也可以等定时触发。「运行记录」里按时间列出每次运行的结果、来源和日志。
定时任务只在桌面端开着时运行:桌面端没开或电脑睡眠时不会运行,之后也不补跑;桌面端被锁定时到期的运行记为跳过。「账户设置 → 自动化」里的「运行定时任务」开关可以暂停全部定时任务,手动运行不受影响。同一任务在同一台设备上不会同时运行两次。
需要确认的操作与人工接管(桌面端 1.1.0 起)
经本地 API 执行的高风险操作(清除应用数据、卸载应用、执行命令,以及涉及付款、消息、账号等的操作)同样可能需要你本人批准。需要确认时,桌面端会在窗口不在前台时弹出系统通知;在「自动化」页的「确认与报告」页签里批准或拒绝。命令行和 AI 助手会等待你的决定,批准后这一步执行一次。
任务里的本机动作(如 ui-action、shell)遇到需要确认的操作时,这一步记为失败,不会等待。想让任务在这一步等你批准,把它写成 wp: 动作(如 wp:ui、wp:run),命令行会在这一步的超时时间内等待你的决定。
在查看器里接管设备时,本地 API 的操作会被拒绝,直到你在查看器顶部点「交还」。经本地 API 执行的每一步都会汇总到平台的运行记录,可以在「确认与报告」里查看;输入的文字不会上传。
