用 Python 调 iOS 免越狱脚本开放接口对接步骤与参数本文讲的是 iPhone 的免越狱、免签名自动化不需要越狱也不需要给应用签名。示例环境为中控端程序 真机涉及坐标、等待、重试这些工程细节适合做移动端自动化或测试的同学参考。那次半夜的手动点击一个做跨境电商的团队客服系统里有个「订单异常」告警。出现问题件的时候他们要到手机 App 上把那个订单重新提交一次。问题在于告警是系统发出来的手机操作却得人来做。半夜来一条就得有人爬起来点一下。他们想的是能不能让客服系统自己去点。这就是开放接口存在的意义——中控自己不知道什么时候该干活但外部系统知道。把设备操作变成 HTTP 调用之后任何会发请求的程序都能驱动手机iPhone自动化 这件事也就从守着中控点变成了发一个请求。一、先想清楚什么时候才需要这么接开放接口不是默认选择先判断一下你的场景。适合走接口的三种情况触发方在中控之外—— 订单系统、告警系统、你的后台它们知道什么时候该做什么中控不知道调度节奏由你自己控制—— 你想用自己的调度器、自己的重试策略而不是中控的定时任务结果要落进自己的系统—— 执行完的状态要写回你的数据库而不是停在中控的执行历史里不需要走接口的情况定时跑一段固定脚本中控自己的定时任务就够了。为了显得自动化而多加一层接口维护成本反而更高。判断标准一句话如果中控自己就能决定什么时候做什么就不用接口如果这个决定来自别的系统就需要。二、接口长什么样三件事定下来剩下都是填空。这套 API接口 没有 SDK也不需要 SDK——就是普通的 HTTP 调用用 iOS自动化脚本 的团队拿现成的请求库就能接。地址 中控所在电脑的地址 8019端口。本机调用是http://127.0.0.1:8019从别的机器调就换成那台电脑的内网 IP。方法 HTTP POSTContent-Type: application/json参数放在请求体里。返回约定 返回 JSON看code字段——0 代表成功其它值代表失败失败原因在msg里。这个约定值得在最开始就封装掉。官方示例里的写法是这样importrequests BASEhttp://127.0.0.1:8019defopenapi_post(path,bodyNone):rrequests.post(f{BASE}{path},jsonbodyor{},timeout30)r.raise_for_status()datar.json()ifdata.get(code)!0:raiseRuntimeError(data.get(msg)ordata)returndata后面所有调用都走这个函数。Python 只依赖requestsNode.js 18 自带fetch不用装东西。三、第一步拿到 deviceId所有设备相关的接口都要deviceId所以第一步永远是查设备列表devicesopenapi_post(/openapi/deviceList,{deviceId:,groupId:})print(devices)注意两个参数的含义deviceId传空字符串表示不按设备过滤groupId传空表示不按分组过滤。想只取某一组的设备就把groupId填上。一个容易混的点deviceId和别名不是一回事。 别称是你自己在中控里起的、给人看的名字接口调用必须用deviceId。所以从列表接口的返回值里取不要拿别名去试。四、第二步USB HID 的三步顺序这是整篇文章最实用的一段。USB HID 的接口不能上来就点击顺序是有讲究的DEVICE_ID90e2f3834c0977205e441aa664916a9bdde81e8d# 从设备列表里取# 1) 开会话openapi_post(/openapi/usbhidSessionStart,{deviceId:DEVICE_ID,gate:True})# 2) 设屏幕分辨率坐标换算依赖它openapi_post(/openapi/usbhidSetScreenSize,{deviceId:DEVICE_ID,w:1170,h:2532})# 3) 之后才能点击openapi_post(/openapi/usbhidClickPoint,{deviceId:DEVICE_ID,x:200,y:400})三段代码各自为什么要存在开会话 ——gate参数是是否尝试增强兼容模式低版本系统会自动忽略所以一般传true。会话已经存在时会复用不需要每次重新开。设屏幕尺寸 —— 这一步最容易被跳过然后所有点击都点偏。因为 HID 送的是绝对像素坐标不告诉它屏幕多大它不知道怎么换算。w和h要和你投屏、截图看到的分辨率一致。点击 ——x、y就是像素坐标。多台设备分辨率不同的话这个值要按设备分别算不能写死。顺序只在会话建立时需要。会话开着、尺寸设对之后后面连续几百次点击都只是重复第三步不用每次重设。Node.js 的写法结构完全一样只是换成了fetchconstBASEhttp://127.0.0.1:8019;asyncfunctionopenapiPost(path,body{}){constresawaitfetch(${BASE}${path},{method:POST,headers:{Content-Type:application/json},body:JSON.stringify(body),});constdataawaitres.json();if(data.code!0){thrownewError(data.msg||JSON.stringify(data));}returndata;}五、十一个模块分别管什么接口按用途分了十一组对着这张表找比翻文档快模块管什么中控接口设备列表、脚本启停等自动化 · 动作点击、滑动、输入、App 的打开关闭自动化 · 截图截图、图片流自动化 · 启停自动化启动 / 释放自动化、隧道、电量自动化 · 相册上传图片视频、清空相册自动化 · 文件操作设备文件推送与拉取自动化 · IME 输入法自定义输入法、剪贴板转发自动化 · 蓝牙 BLE蓝牙板的 HID 动作自动化 · USB HID免硬件数据线直接控制手机辅助助手助手剪贴板、相册、端口转发快捷指令助手需配合快捷指令助手程序使用「动作」是最常用的一组包含点击、双击、长按、滑动、多点触摸、输入文本、模拟键盘、打开/关闭/安装/卸载 App、主页、重启设备、锁屏解锁、设置屏幕方向、校正坐标系、抓取节点等等基本覆盖了脚本里会遇到的每一步。「USB HID」这组值得单独留意它是唯一不需要蓝牙板或 OTG 板的硬件链路一根数据线就能模拟点击和输入对已经在用数据线的场景最省事。六、中控接口查设备、启停脚本前面几步都在讲怎么操作单台设备中控接口解决的是管的问题。它有设备列表、脚本启停这类接口。典型用法是两段式先调设备列表拿到这一批设备的deviceId再对每台启动脚本跑你编译好的逻辑这个组合很适合用外部策略决定跑哪些设备的场景——比如按订单归属决定在哪些机器上跑、或者按分组轮换。设备多的时候分组要在中控里先做好。接口是按deviceId单台调的你的代码里需要循环分组能让这个循环有明确的来源而不是每次把全部设备拉一遍。管理规模的 iOS群控 项目这一步基本是标配。七、和 AI 系统对接如果你的目标是让 AI 助手直接调度手机还有一条更省事的路把接口注册成 MCP 工具。区别在于直接调开放接口你要自己写调哪个接口、传什么参数的逻辑注册成 MCP 之后AI 助手自己会选工具、拼参数。适合让大模型决定下一步做什么的场景。两条路可以并存固定的、可预期的操作用接口直调需要临场判断的交给 MCP。八、落地时的几个实际问题错误处理怎么做。 接口调用失败的原因分两类网络/服务问题中控没开、端口不通和业务问题设备离线、授权过期、坐标越界。前者适合重试后者重试没有意义——按msg区分别一律重试。超时设多少。 官方示例给的是 30 秒。实际操作类接口通常几百毫秒返回超时设长了只是让故障暴露得慢但截图、上传这类涉及大文件的接口要留足。建议按接口分组设而不是全局一个值。坐标怎么维护。 这是接口方案最容易出问题的地方。设备型号混用的时候别写死坐标——要么按设备分辨率换算要么优先用抓节点接口拿到元素坐标再点。后者稳得多。日志留什么。 建议记录设备 ID、调用的接口、请求参数、返回code与msg、时间戳。这五样在手出问题时能直接对上不用靠回忆。和脚本的分工。 一个常见误区是用接口把整段流程重写一遍。更省事的做法是流程留在设备的脚本里接口只负责触发和取结果。接口调用次数少网络往返少出问题的地方也少。九、按需求推荐怎么接先看结论前面讲了接口怎么调这一节说清什么时候该用哪种方式。四种需求覆盖了绝大多数场景而且它们可以在同一套设备上并存。你的需求推荐方式为什么定时跑一段固定流程推荐EasyClick 中控的定时任务不需要绕一层接口中控自己就能决定什么时候做由外部系统决定何时触发推荐EasyClick 开放接口直调8019 端口HTTP 加 JSON和你现有系统直接打通要让 AI 决定下一步做什么推荐EasyClick 注册成 MCP 工具AI 自己选工具、拼参数不用你写调度逻辑既要精确控制界面元素又要在设备上跑完整流程推荐EasyClick 代理模式配脚本接口只做触发流程留在设备上网络往返少出问题的地方也少这四种方式用的是同一个中控、同一套设备授权。所以真实项目里通常是组合着用固定流程走定时外部触发走接口需要判断的交 MCP而设备上的具体动作始终由脚本承担。一个常见误区是用接口把整段流程重写一遍。推荐的划法是脚本负责设备上做什么接口负责从外面告诉它开始、以及把结果取回来。这样接口调用次数少链路短排查也简单。十、常见问题接口只能在局域网里用吗默认是。8019 是中控所在电脑的端口能访问到那台电脑就能调。跨网络要么走内网穿透要么用中控的云控方案。能同时给多台设备发指令吗接口本身按deviceId单台调并发要靠你的代码——比如用线程池同时发。注意同一台设备同一时间只跑一个任务所以并发是多台并行不是单台并发。调接口需要什么授权执行脚本要USB 设备授权投屏要USB 投屏授权两者不是一回事。接口里也有查询授权状态的接口可以在启动任务前先确认一下省得跑到一半才发现没授权。返回 code 不为 0 但 msg 看不懂怎么办先看是不是设备层面的事离线、未授权、会话没开这三类占了大多数。剩下的按接口名去文档对应模块查——每个接口的参数和返回都有说明。那位做跨境的团队最后是这么落地的告警系统检测到问题件直接调设备列表找到对应的机器跑一次重新提交订单的脚本把结果写回自己的工单表。半夜的这一次点击从叫醒一个人变成了发一个请求。