快速起步

快速上手

4 步完成鉴权、查询设备、驱动手机与监听事件

在调用 API 驱动 AI 手机之前，请先前往浪花开放平台注册开发者账号。注册登录后，进入 控制台 · 开发者密钥 即可一键获取系统为您分配的专属 AppKey 与 网关通信地址 (Gateway URL)。

第 1 步：获取与配置开发者 AppKey 及网关通信地址

AppKey 是上位机调用网关接口与驱动名下真机设备的唯一安全凭据，每个 AppKey 严格与开发者的账号资产及设备权限绑定。

网关地址与凭据获取：进入 开放平台 · 凭据中心 即可直接复制：

网关通信地址：包含开发测试网关与高可用生产网关，已与您的账号专属通道自动关联。
开发者 AppKey：格式为 sk-lh-xxxxxxxxxxxxxxxx，支持随时查看明文与轮换重置。

1. 桌面端（Hermes Plus）可视化配置

在开放平台获取到 AppKey 与网关地址后：

打开 Hermes Plus 桌面端，在左侧导航进入 【开发者设置】；
填入在开放平台获取的 网关通信地址（本地开发可填局域网 IP，如 http://localhost:58166；远程/云端模式填开放平台控制台提供的网关地址）；
填入专属 开发者 AppKey；
点击 【保存并校验凭据】。客户端将自动连通网关进行合法性探活，通过后通信信道即刻激活。

2. 自定义代码 / SDK 调用配置

若使用 Python、TypeScript 或 cURL 自行编写自动化任务，所有发往网关地址的请求均需在 HTTP Header 中携带 X-AppKey：

# 将 $GATEWAY_URL 替换为开放平台控制台获取的网关地址
# 将 $APP_KEY 替换为您名下的开发者 AppKey
export GATEWAY_URL="http://localhost:58166"
export APP_KEY="sk-lh-xxxxxxxxxxxxxxxx"

curl -X POST "$GATEWAY_URL/gateway/device-binding/ticket" \
  -H "Content-Type: application/json" \
  -H "X-AppKey: $APP_KEY"

import requests

# 网关通信地址与 AppKey 均在浪花开放平台控制台一键获取
GATEWAY_URL = "http://localhost:58166"
APP_KEY = "sk-lh-xxxxxxxxxxxxxxxx"

headers = {
    "Content-Type": "application/json",
    "X-AppKey": APP_KEY
}
# 所有发往网关的请求统一携带 headers

// 网关通信地址与 AppKey 均在浪花开放平台控制台一键获取
const GATEWAY_URL = "http://localhost:58166";
const APP_KEY = "sk-lh-xxxxxxxxxxxxxxxx";

const headers = {
  "Content-Type": "application/json",
  "X-AppKey": APP_KEY,
};

鉴权拦截机制：若请求未携带 X-AppKey，网关将返回 401 Unauthorized；若填写的 AppKey 错误或已被停用，网关将返回 403 Forbidden 并阻断一切设备操控与事件监听。

第 2 步：查看已绑定的手机

# 查询名下已绑定的在线 AI 手机
curl -X GET "$GATEWAY_URL/gateway/device/list" \
  -H "X-AppKey: $APP_KEY"

headers = {"X-AppKey": APP_KEY}
devices = requests.get(f"{GATEWAY_URL}/gateway/device/list", headers=headers).json()["data"]
print("在线设备列表:", devices)

const res = await fetch(`${GATEWAY_URL}/gateway/device/list`, {
  headers: { "X-AppKey": APP_KEY }
});
const { data: devices } = await res.json();

{
  "code": 200,
  "data": [
    {
      "deviceId": "848bd13e2f9",
      "deviceAlias": "1号测试机",
      "model": "Langhua AI Phone Pro",
      "status": "ONLINE",
      "battery": 90,
      "screenResolution": "1080x2400"
    }
  ]
}

第 3 步：发送点击指令

向设备屏幕中心坐标 (540, 1200) 发送一次物理点击：

curl -X POST "$GATEWAY_URL/gateway/skill/execute" \
  -H "Content-Type: application/json" \
  -H "X-AppKey: $APP_KEY" \
  -d '{
    "device_id": "848bd13e2f9",
    "skill_id": "ui.tap",
    "params": { "x": 540, "y": 1200 }
  }'

payload = {
    "device_id": "848bd13e2f9",
    "skill_id": "ui.tap",
    "params": {"x": 540, "y": 1200}
}
res = requests.post(f"{GATEWAY_URL}/gateway/skill/execute", json=payload, headers=headers).json()
print("执行结果:", res)

const res = await fetch(`${GATEWAY_URL}/gateway/skill/execute`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-AppKey": APP_KEY
  },
  body: JSON.stringify({
    device_id: "848bd13e2f9",
    skill_id: "ui.tap",
    params: { x: 540, y: 1200 }
  })
});
const result = await res.json();

{
  "success": true,
  "message": "点击成功",
  "data": { "x": 540, "y": 1200 },
  "skillId": "ui.tap",
  "deviceId": "848bd13e2f9"
}

第 4 步：监听实时事件流 (SSE)

建立长连接，监听设备心跳、前台 App 切换与微信/短信消息：

curl -N -H "Accept: text/event-stream" \
  -H "X-AppKey: $APP_KEY" \
  "$GATEWAY_URL/gateway/sse"

# pip install sseclient-py
import json
import urllib.request
import sseclient

req = urllib.request.Request(
    f"{GATEWAY_URL}/gateway/sse",
    headers={"Accept": "text/event-stream", "X-AppKey": APP_KEY}
)
client = sseclient.SSEClient(urllib.request.urlopen(req))
for msg in client:
    if msg.data:
        event = json.loads(msg.data)
        print("收到事件:", event["type"], event)

const eventSource = new EventSource(`${GATEWAY_URL}/gateway/sse`, {
  headers: { "X-AppKey": APP_KEY }
});

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("收到事件:", data.type, data);
};

data: {"type":"HEARTBEAT","device_id":"848bd13e2f9","battery":90,"cpu":12.4,"status":"online"}

data: {"type":"GUARD_EVENT","event":"NOTIFICATION_POSTED","device_id":"848bd13e2f9","app_label":"微信","title":"客户A","content":"请问有现货吗？"}