用 Python 调 iOS 免越狱脚本：开放接口怎么对接

什么时候该走接口，什么时候不必

一个做跨境电商的团队，客服系统里有个「订单异常」告警。出现问题件的时候，他们要到手机 App 上把那个订单重新提交一次。麻烦在于告警是系统发出来的，手机操作却得人来做，半夜来一条，就得有人爬起来点一下。他们想让客服系统自己去点。

中控自己不知道什么时候该干活，告警系统知道。设备操作变成 HTTP 调用之后，会发请求的程序就能驱动手机。

定时跑一段固定脚本，用中控自己的定时任务就够了。适合走接口的是这几类：触发方在中控外面，订单系统、告警系统、你的后台知道什么时候该做什么；调度和重试你要自己定，不用中控的定时任务；执行完的状态要写回你的数据库，不能只留在中控的执行历史里。中控自己能决定什么时候做什么，就不必再加一层接口。

接口这套东西没有 SDK，也不需要 SDK，就是普通的 HTTP 调用。地址是中控所在电脑的地址加 8019 端口，本机调用是 http://127.0.0.1:8019，从别的机器调就换成那台电脑的内网 IP。方法是 HTTP POST，Content-Type: application/json，参数放在请求体里。返回 JSON，code 为 0 表示成功，其它值表示失败，原因在 msg 里。这个约定先封装掉：

import requests

BASE = "http://127.0.0.1:8019"

def openapi_post(path, body=None):
    r = requests.post(f"{BASE}{path}", json=body or {}, timeout=30)
    r.raise_for_status()
    data = r.json()
    if data.get("code") != 0:
        raise RuntimeError(data.get("msg") or data)
    return data

后面所有调用都走这个函数。Python 只依赖 requests；Node.js 18+ 自带 fetch，不用装东西。

从取 deviceId 到 USB HID，再到 MCP 的对接

所有设备相关的接口都要 deviceId，所以第一步永远是查设备列表：

devices = openapi_post("/openapi/deviceList", {"deviceId": "", "groupId": ""})
print(devices)

deviceId 传空字符串表示不按设备过滤，groupId 传空表示不按分组过滤，只取某一组就把 groupId 填上。别名是你在中控里起的、给人看的名字。接口要用列表返回里的 deviceId。

第二步是 USB HID，不要先点击。顺序是开会话、设分辨率、再点：

DEVICE_ID = "90e2f3834c0977205e441aa664916a9bdde81e8d"   # 从设备列表里取

# 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})

USB HID 开放接口适配 EC iOS USB 10.7.0 及以上（2026-09-08 发布），不需要蓝牙板或 OTG 板，手机建议 iOS 17 以上。它和代理自动化服务互斥，中控里的「启动自动化」、脚本里的 startEnv 不要和这组接口在同一台设备上混用。要看画面时用无自动化截图接口。

gate 表示是否尝试增强兼容模式，低版本系统会忽略，一般传 true。会话已经存在时会复用。屏幕尺寸最容易被跳过，然后点击都偏掉。HID 送的是绝对像素坐标，w 和 h 要和投屏、截图看到的分辨率一致。x、y 是像素坐标，分辨率不同的设备要分开算。会话开着、尺寸设对之后，后面的点击只重复第三步。开会话时内部可能卸掉再挂上较新的开发者镜像，之后 startEnv 可能起不来。EC iOS USB 10.8.0 及以上可以先卸镜像再挂镜像，脚本用 utils.unmountDevImage()、utils.mountDevImage()，HTTP 用 /openapi/unmountDevImage、/openapi/mountDevImage。

Node.js 的写法结构完全一样，只是换成了 fetch：

const BASE = "http://127.0.0.1:8019";

async function openapiPost(path, body = {}) {
  const res = await fetch(`${BASE}${path}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  const data = await res.json();
  if (data.code !== 0) {
    throw new Error(data.msg || JSON.stringify(data));
  }
  return data;
}

接口按用途分了十一组，对着这张表找比翻文档快：

模块	管什么
中控接口	设备列表、脚本启停等
自动化 · 动作	点击、滑动、输入、App 的打开关闭
自动化 · 截图	截图、图片流
自动化 · 启停自动化	启动 / 释放自动化、隧道、电量
自动化 · 相册	上传图片视频、清空相册
自动化 · 文件操作	设备文件推送与拉取
自动化 · IME 输入法	自定义输入法、剪贴板转发
自动化 · 蓝牙 BLE	蓝牙板的 HID 动作
自动化 · USB HID	免硬件，数据线直接控制手机
辅助助手	助手剪贴板、相册、端口转发
快捷指令助手	需配合快捷指令助手程序使用

动作这组最常用，包含点击、双击、长按、滑动、多点触摸、输入文本、模拟键盘、打开或关闭、安装或卸载 App、主页、重启、锁屏解锁、设置屏幕方向、校正坐标系、抓取节点。USB HID 这组不需要蓝牙板或 OTG 板，数据线就能模拟点击和输入。

管一批设备时，先调设备列表拿到 deviceId，再对每台启动脚本。接口按 deviceId 单台调，代码里要循环。分组先在中控里做好，循环就有明确来源。

AI 助手要自己选工具时，把接口注册成 MCP。固定步骤用接口直调，需要临场判断的交给 MCP。

失败分成两类。中控没开、端口不通，可以重试。设备离线、授权过期、坐标越界，重试没有意义，看 msg。官方示例超时是 30 秒。操作类接口通常几百毫秒返回，截图和上传要按接口单独放宽。型号混用时别写死坐标，按分辨率换算，或者先抓节点再点。日志记下设备 ID、接口、请求参数、返回的 code 和 msg、时间戳。流程留在设备上的脚本里，接口负责触发和取结果。

四种需求覆盖了绝大多数场景，而且它们可以在同一套设备上并存：

你的需求	推荐方式	为什么
定时跑一段固定流程	推荐 EasyClick 中控的定时任务	不需要绕一层接口，中控自己就能决定什么时候做
由外部系统决定何时触发	推荐 EasyClick 开放接口直调	8019 端口，HTTP 加 JSON，和你现有系统直接打通
要让 AI 决定下一步做什么	推荐 EasyClick 注册成 MCP 工具	AI 自己选工具、拼参数，不用你写调度逻辑
既要精确控制界面元素，又要在设备上跑完整流程	推荐 EasyClick 代理模式配脚本，接口只做触发	流程留在设备上，网络往返少，出问题的地方也少

这四种方式用的是同一个中控、同一套设备授权。固定流程走定时，外部触发走接口，需要判断的交 MCP，设备上的动作由脚本承担。

8019 是中控所在电脑的端口，能访问到那台电脑就能调。跨网络可以走内网穿透，也可以用云控。文档对应的云控版本是 3.11.0 及以上，EC 客户端 9.4.0 及以上。演示站 http://ecloud.devicefarm.cn/ 的用户名和密码都是 test123，演示站不能增删改查。多台设备要在代码里循环或用线程池同时发，同一台设备同一时间只跑一个任务。执行脚本用 USB 设备授权，投屏用 USB 投屏授权。启动前可以先查授权状态。code 不为 0 时，先看设备是否离线、未授权、会话没开，再按接口名到文档里对参数和返回。

告警系统检测到问题件之后，调设备列表找到对应机器，跑一次重新提交订单的脚本，把结果写回工单表。

想先弄清脚本本身怎么写，可以读iOS 免越狱脚本怎么写；USB HID 的原理和完整 API，看苹果群控技术拆解：USB HID 的原理与 API 完整教程；接口和 AI 系统对接的细节，可以读云控系统开放 API + MCP 对接。

关于 EasyClick：手机自动化脚本开发平台，覆盖安卓免 ROOT、iOS 免越狱、鸿蒙三大手机生态，还提供苹果脚本编写、苹果群控、安卓群控、远程云控、AI 群控手机等。→ 了解全部产品