ADB远程连接与API快速入门

快速入门

从注册新账户到用脚本控制一台设备，只需五步。这里的每一步也都可以在控制台里手动完成。

1. 创建账户

   用邮箱、Google或GitHub注册。第一台设备可免费运行30分钟，无需绑卡，也无需充值。

2. 充值余额

   “账单 → 充值”，最低$10，支持加密货币、WeChat Pay或Alipay。设备费用从这笔预付余额中扣除；余额用完时，创建请求会返回402。

3. 创建API密钥

   “设置 → API密钥”。选择权限范围read或control，以及它能操作的设备。密钥只显示一次。

4. 创建设备

   先列出可创建的机型，再指定网络和计费方式创建一台。

5. 等它启动

   设备先显示为starting，大约一分钟后变为running，并显示出口国家和地址。

export CLOUSD_KEY=cl_live_your_key

# 1. 能创建什么？- 机型 id 和对应的 Android 版本
curl https://api.clousd.com/v1/models -H "Authorization: Bearer $CLOUSD_KEY"

# 2. 创建：Galaxy A16 5G，Android 15，美国移动出口，按分钟计费
curl -X POST https://api.clousd.com/v1/devices \
  -H "Authorization: Bearer $CLOUSD_KEY" \
  -H "Idempotency-Key: first-device-001" \
  -d '{"profile":"galaxya16","plan":"metered","network":{"type":"mobile","country":"US"}}'
# → 202 {"ok": true, "name": "c3f9a41d2", "state": "starting", "poll": "/v1/devices/c3f9a41d2"}

# 3. 轮询，直到设备运行中
curl https://api.clousd.com/v1/devices/c3f9a41d2 -H "Authorization: Bearer $CLOUSD_KEY"

设备

一台设备就是一款机型、一个Android版本的一台手机。在你删除它之前，应用和数据在关机、重启后都会保留。

开机、关机和重启会返回202和一个任务。删除是永久的：设备及其数据都会被移除，无法撤销。计费方式按设备设置：metered（每分钟$0.004，每天最多$0.80）或monthly（$12.00包30天）。

POST   /v1/devices/{name}/start
POST   /v1/devices/{name}/stop
POST   /v1/devices/{name}/restart
GET    /v1/devices/{name}/screenshot?w=320     # PNG，或带 w 参数的小尺寸 JPEG
POST   /v1/devices/{name}/action  {"op":"open_app","package":"com.android.chrome"}
DELETE /v1/devices/{name}                     # 彻底删除

action无需实时画面即可执行单个步骤：open_app、close_app、url、tap、swipe、text、key、scroll，以及文字辅助操作find_text、tap_text、wait_text、screen_text。

网络

每台设备有一个出口。GET /v1/network/options列出当前可选的类型和国家。

POST /v1/devices/{name}/network         {"type":"residential","country":"GB"}
POST /v1/devices/{name}/network         {"url":"socks5://user:pass@203.0.113.7:1080"}
POST /v1/devices/{name}/network/rotate  # 新地址，类型和国家不变
POST /v1/network/check                     {"url":"http://user:pass@198.51.100.24:8080"}

时区、语言、SIM和上报的位置都跟随出口。出口在Android底层生效，DNS也走出口，出口断开时流量随之停止。工作原理

应用

像手机从Play商店安装一样，从我们的应用库安装，或者上传任意APK。

GET  /v1/apps                                # 包名、名称、分类、版本、大小
POST /v1/devices/{name}/apps  {"package":"com.instagram.android"}
GET  /v1/devices/{name}/apps                 # 从应用库安装了哪些应用
curl -X POST https://api.clousd.com/v1/devices/{name}/apk \
  -H "Authorization: Bearer $CLOUSD_KEY" -F apk=@app-release.apk

从应用库安装的应用，安装来源显示为Play商店。如果已安装相同或更新的版本，任务会以“already”结束。

快照与克隆

快照会把设备定格：应用、登录状态、文件和设置。恢复快照即可回到当时的状态；克隆快照可以创建配置相同的新设备，各自拥有独立的序列号、IMEI、SIM和Android ID。

POST /v1/devices/{name}/snapshots                  {"name":"ready-v3"}
GET  /v1/devices/{name}/snapshots
POST /v1/devices/{name}/snapshots/{id}/restore
POST /v1/devices/{name}/snapshots/{id}/clone    {"name":"eu01"}

克隆出来的就是普通设备，计费方式和其他设备一样，并会加入创建它的密钥的设备列表。需要定时备份，请用“控制台 → 快照 → 每晚备份”。

分组与定时任务

分组任务会在多台设备上执行一串步骤，每台设备在你设定的错开时间内随机开始。任务会按设备报告进度。

POST /v1/groups
{
  "phones":  ["c3f9a41d2", "c81d07e5a", "c2b9f4a10"],
  "stagger": [30, 180],
  "steps": [
    {"op":"install_app","package":"com.instagram.android"},
    {"op":"open_app","package":"com.instagram.android"},
    {"op":"browse","seconds":240},
    {"op":"wait","seconds":20,"seconds_max":90},
    {"op":"screenshot"}
  ]
}

步骤：open_app、close_app、install_app、url、tap、swipe、text、key、wait（在seconds和seconds_max之间随机）、browse（随机滚动和停顿，10–600秒）、scroll、if_text / unless_text（屏幕上没有指定文字时跳过后续步骤）、screenshot、start、stop、restart。

定时任务就是按时钟运行的同一种任务：POST /v1/schedules，带上name、phones、steps、stagger、at（"HH:MM"，UTC）和days（1–7）。用/toggle暂停，用/delete删除。在控制台的“自动化”里，还有用卡片拼出的流程，以及主流应用的现成动作。各应用支持哪些自动化

ADB访问

ADB默认关闭。为设备开启时，填上你要连接的来源地址；你会拿到主机、端口和一次性登录码，只显示一次。

POST /v1/devices/{name}/adb  {"ttl_hours":24,"allow_ips":["203.0.113.7","198.51.100.0/24"]}
# → {"host": "…", "port": 27001, "code": "a1b2c3", "expires": "…",
#    "connect": "adb connect host:27001", "login": "adb -s host:27001 shell clousd-login a1b2c3"}

adb connect host:27001
adb -s host:27001 shell clousd-login a1b2c3      # → login ok
adb -s host:27001 install app.apk

DELETE /v1/devices/{name}/adb                 # 关闭并断开所有会话

限制：allow_ips为必填（最多20个IP或网段）；ttl_hours默认24，最大168；每台设备最多3个会话；输错5次验证码会断开会话，10分钟内累计20次会关闭中继；空闲会话30分钟后断开；每个会话push和pull最多2 GiB。root、remount、disable-verity、reverse、reboot、tcpip、usb、jdwp、sideload和restore始终被拒绝。重新生成验证码会断开现有会话。

Webhook

密钥可以绑定一个Webhook URL（创建密钥时设置）。该密钥下设备的事件会以POST请求推送，JSON请求体为{"event", "ts", "phone", "job" | "incident"}。

每个请求都带有X-Clousd-Signature：用你API密钥的十六进制SHA-256作为密钥，对原始请求体计算HMAC-SHA256，取十六进制值。最多投递三次：立即一次、10秒后一次、60秒后一次，每次超时10秒。

AI Agent

两个调用，让Agent形成闭环：先看，再做。

GET /v1/devices/{name}/observe?w=540
# → {"seq": 41, "image": {"w": 540, "format": "jpeg", "data": "…"}, "package": "…", "activity": "…",
#    "ui": [{"text": "Checkout", "id": "…", "b": [60, 1560, 1020, 1680], "click": true}, …]}

POST /v1/devices/{name}/act  {"op":"tap_text","text":"Checkout","seq":41,"settle":true}
# → {"ok": true, "seq": 42, "settled": true, "waited_ms": 830}

observe每次都会拍一张新截图，并返回最多500个屏幕元素及其边界。如果在你传入的seq之后发生过其他observe或act，act会以409 stale拒绝执行，所以Agent绝不会对着旧画面操作；带上settle时，它会等画面不再变化（最多5秒）。每次运行之间用恢复快照来重置。给AI Agent用的手机

错误与限制

错误以JSON返回，包含机器可读的kind和说明：{"error": "busy", "message": "…"}。状态码：400请求有误，401未授权，402余额不足，403权限范围或设备列表不允许，404未找到，409忙碌或画面过期，429触发限流。

按密钥限流：每分钟60次请求；/devices/{name}/…类接口每台设备每分钟120次，所有设备合计每分钟600次。收到429表示需要放慢速度，并以退避方式重试。

团队与API密钥

账户里有所有者和运营人员两种角色。所有者负责账单、API密钥、团队，以及创建或删除设备。 运营人员操作你分配给他们的设备：开机、关机、应用、网络、快照和ADB，但不能碰账单、密钥，也不能删除设备。 在“团队”里通过邮箱邀请成员；他们首次登录即加入。

API密钥属于账户，而不属于某个人：每个密钥都有权限范围（read或control）和设备列表。只读密钥调用会改动状态的接口时，会收到403。吊销密钥后立即失效。

账单

Clousd采用预付余额。最低充值$10，支持加密货币、WeChat Pay或Alipay；每笔充值和扣费都在“账单”中单独列出，“用量”页面显示每台设备的分钟数和费用。 按分钟计费的设备运行时每分钟扣$0.004，每天最多$0.80；包月设备每30天扣一次$12.00。 Android 15加价10%，Android 16加价25%，Android 17加价25%。 付费网络出口按GB计费。余额归零时，正在运行的按分钟计费设备会关机，数据保留。 价格

获取帮助

发邮件到support@clousd.com，或使用联系表单；由真人回复，通常在一个工作日内。请附上控制台里的设备ID（以dev_开头）或它的API名称，并说明你预期的结果。平台当前状态见状态页面，近期更新见更新日志。

术语表

控制台、API和本文档使用的术语，都在这里。

出口

在Android底层为单台设备配置的代理：移动、住宅、ISP、机房出口，或你自己的SOCKS5、HTTP代理。应用看到的是出口的地址，时区、语言和SIM跟随出口所在国家。

区域

设备运行的位置。选离看画面或跑ADB的人最近的那个；它和出口是分开选择的。

快照

整台设备的保存副本：应用、登录状态、文件和设置。一步即可恢复，也可以从它克隆新设备。

克隆

从快照创建的新设备：应用、文件和设置相同，但有独立的序列号、IMEI、SIM、Wi-Fi和蓝牙地址以及Android ID。

设备身份

设备上报的硬件标识：序列号、IMEI、手机号码和Wi-Fi信息。一次调用即可整体换成新身份。

脚本

针对某个应用操作的现成自动化，比如登录、养号、发布帖子或删除最新帖子，可在单台手机、分组或定时任务上运行。

通用步骤

任何应用都能用的基础动作：打开应用或URL、点击、滑动、输入文字、按键、浏览、滚动、等待、检查屏幕上的文字，以及截图。

流程

在“自动化”里用卡片拼出的一串步骤，比如登录、养号、暂停和发布，每一步都有时长和 ± 浮动范围。

分组

一组可以统一操作的设备：开机、关机、安装应用和执行步骤，手机之间随机错开时间。

定时任务

按星期几和时间（UTC）在设备或分组上运行的脚本或步骤。

资源库

存放账号和素材的地方：每个账号的登录凭据加密存储并绑定到一台手机，另有素材库。

素材库

资源库中的照片和视频文件夹。发布步骤会取最新或随机的文件，同一台手机上绝不重复发同一个文件。

Multi-view与Sync

实时画面并排组成的屏幕墙。Sync（同步）把一次点击、滑动或输入的文字同步到你选中的手机上。

所有者与运营人员

团队角色。所有者负责账单、API密钥、团队以及创建或删除设备；运营人员只操作分配给自己的设备。

ADB中继

用adb连接设备的方式：连上中继，用一次性验证码登录。仅限你的IP地址，默认关闭，限时开放。