ADB 遠端連線與 API 快速入門

快速入門

從新帳號到用腳本控制裝置，只要五個步驟。這裡的每一步也都能在控制台手動完成。

1. 建立帳號

   用 Email、Google 或 GitHub 註冊。你的第一台裝置可以免費用 30 分鐘，不用信用卡，也不用先儲值。

2. 儲值

   到「帳務 → 儲值」，$10 起，可用加密貨幣、WeChat Pay 或 Alipay。裝置費用從這個預付餘額扣；餘額用完時，建立呼叫會回傳 402。

3. 建立 API 金鑰

   到「設定 → API 金鑰」。選擇權限範圍 read 或 control，以及它涵蓋的裝置。金鑰只顯示一次。

4. 建立裝置

   先列出可以建立的機型，再帶上網路和方案建立一台。

5. 看著它開機

   裝置一開始顯示為 starting，大約一分鐘後變成 running，並顯示它的出口國家和 IP。

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 版本的手機。在你刪除之前，關機和重開機都會保留它的 App 和資料。

開機、關機和重開機會回傳 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  # 換新 IP，類型與國家不變
POST /v1/network/check                     {"url":"http://user:pass@198.51.100.24:8080"}

時區、語言、SIM 和回報的位置都跟著出口走。出口設在 Android 底層，DNS 也走它，出口一斷流量就停。運作原理

App

像手機從 Play 商店安裝一樣，從我們的目錄安裝，或上傳任何 APK。

GET  /v1/apps                                # 套件、名稱、分類、版本、大小
POST /v1/devices/{name}/apps  {"package":"com.instagram.android"}
GET  /v1/devices/{name}/apps                 # 從目錄安裝了哪些 App
curl -X POST https://api.clousd.com/v1/devices/{name}/apk \
  -H "Authorization: Bearer $CLOUSD_KEY" -F apk=@app-release.apk

從目錄安裝的 App，安裝來源會顯示為 Play 商店。如果已經裝了相同或更新的版本，工作會以「already」結束。

快照與複製

快照會把裝置定格保存：App、登入狀態、檔案和設定。還原它就能回到當時；複製它就能建立設定相同、但有自己序號、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 移除。在控制台的「自動化」裡，還能用方塊組出流程，以及熱門 App 的現成動作。各 App 能自動化哪些事

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 金鑰、團隊，以及建立或刪除裝置。 操作員負責你分配給他們的裝置：開機、關機、App、網路、快照和 ADB，但不能碰帳務、金鑰，也不能刪除裝置。 在「團隊」用 Email 邀請成員；他們第一次登入時就會加入。

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 代理。App 看到的是它的 IP，時區、語言和 SIM 都跟著它的國家走。

地區

裝置運作的地方。選離看畫面或跑 ADB 的人最近的那個；地區和出口是分開選的。

快照

整台裝置的完整備份：App、登入狀態、檔案和設定。一步就能還原，也能從它複製出新裝置。

複製

從快照建立的新裝置：App、檔案和設定都一樣，但有自己的序號、IMEI、SIM、Wi-Fi 與藍牙位址，以及 Android ID。

身分

裝置回報的硬體識別碼：序號、IMEI、電話號碼和 Wi-Fi 資訊。一個呼叫就能換成新身分。

腳本

針對單一 App 動作的現成自動化，例如登入、養號、發布貼文或刪除最新貼文，可以在一台手機、一個群組或依排程執行。

通用步驟

任何 App 都能用的基本動作：開啟 App 或網址、點擊、滑動、輸入文字、按鍵、瀏覽、捲動、等待、檢查畫面上的文字和截圖。

流程

在「自動化」裡用方塊組成的一連串步驟，例如登入、養號、暫停和發布，每一步都有時長和 ± 浮動範圍。

群組

一次下指令的一組裝置：開機、關機、安裝 App 和執行步驟，手機之間隨機錯開。

排程

依星期幾和時間（UTC）在裝置或群組上執行的腳本或步驟。

資源庫

存放帳號和素材的地方：每個帳號的登入資料加密儲存並連結到一台手機，另外還有 Media 庫。

Media 庫

資源庫裡的照片和影片資料夾。發布步驟會取最新或隨機的檔案，同一台手機上絕不重複發同一個檔案。

Multi-view 與 Sync

並排顯示的一整面即時畫面牆。Sync 會把點擊、滑動或輸入的文字同步到你選定的手機。

擁有者與操作員

團隊角色。擁有者負責帳務、API 金鑰、團隊，以及建立或刪除裝置；操作員只能操作分配給他們的裝置。

ADB 中繼

用 adb 連到裝置的方式：連上中繼，用一次性代碼登入。只限你的 IP 位址、預設關閉、有時效。