PhoneBase 文档

简体中文

English

简体中文

English

主题

连接设备 ​

本指南涵盖 PhoneBase 中设备的完整生命周期 -- 从创建云手机到连接、控制和多设备管理。

设备生命周期概览 ​

PhoneBase 云手机经历以下阶段：

创建 → 启动 → 连接 → 操作 → 断开 → 停止 / 删除
        ↑                           ↓
        └───── 重启 (reboot) ───────┘
阶段命令说明
创建pb devices create分配一台新的云手机
启动pb devices start启动已停止的设备
连接pb connect <code>建立实时控制连接
操作pb tap、pb text 等向设备发送命令
断开pb disconnect断开与设备的连接
停止pb devices stop关闭设备（保留状态）
删除pb devices delete永久删除设备

TIP

只有设备处于运行中（已启动）状态时才会计费。已停止和已断开连接的设备不产生费用，但请注意：运行中的设备即使没有连接也会继续计费。

创建设备 ​

分配一台新的 Android 云手机：

bash
pb devices create

人类可读输出：

✓ 设备已创建
  device_code  IDY291LX6WW6RCW
  status       starting

JSON 输出（非 TTY / AI Agent）：

json
{
  "code": 0,
  "msg": "设备已创建",
  "data": {
    "device": {
      "id": "dev_01jk...",
      "device_code": "IDY291LX6WW6RCW",
      "status": "starting"
    }
  }
}

设备初始状态为 starting，大约 15 秒内转为 running。

列出设备 ​

查看你的所有设备：

bash
pb devices list

也可以使用简写形式：

bash
pb devices

两者输出相同：

CODE               STATUS         ONLINE   CONNECTED  STARTED_AT
IDY291LX6WW6RCW   running        yes      yes        2026-04-09T10:30:00Z
K8X3M2P7QRST      stopped        no       -          -

字段说明 ​

字段说明
CODE设备编码，用于在命令中标识设备
STATUS设备状态：starting（启动中）、running（运行中）、stopped（已停止）、deleting（删除中）
ONLINE设备代理是否可达
CONNECTED你的 CLI 当前是否已连接到该设备
STARTED_AT设备最后一次启动的时间戳

启动 / 停止设备 ​

启动 ​

启动一台已停止的设备：

bash
pb devices start IDY291LX6WW6RCW
json
{
  "code": 0,
  "msg": "设备 IDY291LX6WW6RCW: start",
  "data": { "task_id": "task_abc123" }
}

INFO

启动操作是异步的。设备状态从 stopped 变为 starting 再变为 running，通常需要约 15 秒。

停止 ​

关闭一台运行中的设备：

bash
pb devices stop IDY291LX6WW6RCW
json
{
  "code": 0,
  "msg": "设备 IDY291LX6WW6RCW: stop",
  "data": { "task_id": "task_def456" }
}

WARNING

停止设备会断开所有活跃的连接。请确保在停止前完成你的操作。

如果省略设备 ID，命令会使用当前已连接的设备：

bash
pb devices stop

连接设备 ​

连接到云手机以实时控制设备：

bash
pb connect IDY291LX6WW6RCW
✓ 已连接设备 IDY291LX6WW6RCW

连接原理 ​

  1. CLI 自动启动一个后台进程（如果尚未运行）
  2. 后台进程向 PhoneBase 云端建立持久连接
  3. 后续所有 pb 命令通过此连接路由到设备
  4. 连接在后台持续存在 -- 你可以关闭终端，之后重新使用
  5. 如果连接断开，会自动重连

TIP

连接后不需要保持终端打开。连接在后台保持。在任何终端会话中执行新的 pb 命令都会使用已有的连接。

断开连接 ​

断开与设备的连接：

bash
# 断开指定设备
pb disconnect IDY291LX6WW6RCW

# 断开所有设备
pb disconnect
✓ 已断开连接

INFO

断开连接不会停止设备。设备会继续运行（计费也会继续）。要停止计费，请使用 pb devices stop。

设备详情 ​

查看指定设备的详细信息：

bash
pb devices info IDY291LX6WW6RCW

JSON 输出：

json
{
  "code": 0,
  "data": {
    "id": "dev_01jk...",
    "device_code": "IDY291LX6WW6RCW",
    "status": "running",
    "plex_status": "running",
    "is_online": true,
    "started_at": "2026-04-09T10:30:00Z",
    "created_at": "2026-04-09T10:29:45Z",
    "instance_id": "inst_xyz789"
  }
}

查看任务历史 ​

检查设备的异步任务历史（启动、停止、重启等）：

bash
pb devices tasks IDY291LX6WW6RCW

多设备管理 ​

指定目标设备 ​

当连接了多台设备时，使用 -s 全局标志指定命令要操作的设备：

bash
# 对指定设备截图
pb -s IDY291LX6WW6RCW screencap

# 对指定设备点击
pb -s K8X3M2P7QRST tap 540 960

设置默认设备 ​

避免每次都输入设备编码：

bash
pb config set device_default IDY291LX6WW6RCW

此后不带 -s 的命令会自动使用此设备。

自动解析规则 ​

如果省略了设备标识：

  1. CLI 首先检查是否提供了 -s 参数
  2. 然后检查 device_default 配置项
  3. 然后使用当前已连接的设备（如果恰好只连接了一台）
  4. 如果以上都无法解析，命令会报错退出

设备控制操作 ​

重启 ​

重启运行中的设备（Android 系统软重启）：

bash
# 通过 devices 子命令
pb devices reboot IDY291LX6WW6RCW

# 或使用简写形式（使用已连接/默认设备）
pb reboot
json
{
  "code": 0,
  "msg": "设备 IDY291LX6WW6RCW: reboot",
  "data": { "task_id": "task_ghi789" }
}

工厂重置 ​

将设备重置为初始状态：

bash
pb devices reset IDY291LX6WW6RCW

DANGER

工厂重置会永久清除设备上的所有数据 -- 已安装的应用、应用数据、文件等全部清空。此操作不可撤销。请在重置前使用快照保存你的状态。

从快照恢复 ​

将设备恢复到之前保存的快照状态：

bash
pb devices restore IDY291LX6WW6RCW --snapshot snap_abc123
json
{
  "code": 0,
  "msg": "设备 IDY291LX6WW6RCW 已恢复",
  "data": { "task_id": "task_jkl012" }
}

快照管理

你可以创建、列出和删除快照：

bash
# 将当前设备状态保存为快照
pb snapshots create IDY291LX6WW6RCW --name "setup-complete"

# 列出所有快照
pb snapshots list

# 删除快照
pb snapshots delete snap_abc123

删除设备 ​

永久删除一台设备：

bash
pb devices delete IDY291LX6WW6RCW

DANGER

此操作不可逆。设备及其所有数据将被永久删除。如需保留状态，请先创建快照。

设备模式 ​

PhoneBase 支持三种设备模式，各适用于不同的使用场景：

无状态模式（Stateless） ​

每个任务在全新设备上运行。执行完毕后设备即销毁，运行之间不会有状态泄漏。

任务 → [ 全新设备 ] → 结果 → 销毁

适用于： 一次性任务、测试、CI/CD 流水线、需要保证干净环境的任务。

快照模式（Snapshot） ​

预先配置好手机 -- 安装应用、登录账号、设置偏好 -- 然后拍摄快照。每次会话从该快照克隆，用完即弃。

快照 ──→ 克隆 → 执行 → 丢弃

适用于： 需要特定初始化配置的重复性任务（如预装并登录好的应用）、批量处理、需要相同起始状态的并行执行。

持久模式（Persistent） ​

一台专属的常驻设备。会话之间的状态完整保留。运行期间按小时计费。

设备 ──→ 会话₁ → 会话₂ → 会话₃ ···

适用于： 长期运行的 Agent、需要随时间积累状态的任务、开发和调试。

浏览器实时查看 ​

在默认浏览器中打开设备的实时画面：

bash
pb view IDY291LX6WW6RCW
✓ 已打开: IDY291LX6WW6RCW

这会在浏览器中打开一个标签页，显示设备屏幕的实时视频流。用于监控设备正在做什么。

故障排除 ​

设备显示 "offline" ​

设备代理可能不可达。尝试：

  1. 检查设备状态：pb devices info <code>
  2. 如果状态是 running 但 is_online 为 false，尝试重启：pb devices reboot <code>
  3. 如果设备是 stopped，启动它：pb devices start <code>

连接超时 ​

如果 pb connect 一直等待或超时：

  1. 确认设备正在运行且在线：pb devices list
  2. 检查你的网络连接
  3. 如果使用 VPN 或代理，确保连接不被阻断
  4. 尝试断开后重连：
    bash
    pb disconnect
pb connect <code>

连接断开 ​

如果看到 "no active connection" 错误：

  1. 后台进程可能已停止。重新连接：
    bash
    pb connect <code>
  2. 后台进程会在执行 pb connect 时自动重启

命令返回 "no device specified" ​

CLI 无法确定要操作哪台设备：

  1. 连接一台设备：pb connect <code>
  2. 或用 -s 指定设备：pb -s <code> <command>
  3. 或设置默认设备：pb config set device_default <code>

Copyright © 2026 PhoneBase