PhoneBase 文档

简体中文

English

简体中文

English

主题

快速开始 ​

欢迎使用 PhoneBase！本指南带你在大约 5 分钟内从零开始控制一台真实的 Android 云手机。你将安装 CLI、创建设备、与之交互，并运行第一个 Skill。

准备工作 ​

开始之前，请确保你已具备：

  • PhoneBase 账号 — 在 phonebase.cloud 注册获取 API Key（首次赠送 $5 额度，无需信用卡）
  • 已安装 pb CLI — 如尚未安装，请参考安装指南

第一步：登录 ​

使用你的 PhoneBase 账号进行身份验证。CLI 会自动打开浏览器完成 OAuth 登录：

bash
pb login

预期输出：

正在打开浏览器...
你的一次性验证码: ABCD-1234
等待认证... (298s)
✓  登录成功

替代方式：API Key 认证

如果你不方便使用浏览器（例如在服务器或 CI/CD 中），可以直接设置 API Key：

bash
pb apikey <你的-api-key>

验证登录状态和账户余额：

bash
pb status
json
{
  "code": 0,
  "data": {
    "authenticated": true,
    "auth_type": "token",
    "balance_cents": 500
  }
}

第二步：创建云手机 ​

分配一台新的 Android 云手机：

bash
pb devices create
✓ 设备已创建
  device_code  IDY291LX6WW6RCW
  status       starting

INFO

device_code（如 IDY291LX6WW6RCW）是后续所有命令中使用的设备标识。请记下来，接下来会用到。

确认设备出现在列表中：

bash
pb devices list
CODE               STATUS         ONLINE   CONNECTED  STARTED_AT
IDY291LX6WW6RCW   running        yes      -          2026-04-09T10:30:00Z

第三步：连接设备 ​

连接到你的云手机：

bash
pb connect IDY291LX6WW6RCW
✓ 已连接设备 IDY291LX6WW6RCW

TIP

CLI 会自动启动一个后台进程来管理连接。你不需要保持终端窗口打开 -- 连接会持续存在，直到你主动断开。

第四步：初次设备操作 ​

连接成功后，来试试几个基础命令：

截图 ​

截取当前屏幕并保存为 JPG 图片：

bash
pb screencap
✓ 截图已保存: ~/.phonebase/data/screencap/20260409/IDY291LX6WW6RCW-20260409103500.jpg (45.2 KB)

点击屏幕 ​

点击典型手机屏幕（1080x1920）的中心位置：

bash
pb tap 540 960
json
{
  "code": 0,
  "msg": "ok"
}

输入文字 ​

在当前聚焦的输入框中输入文字：

bash
pb text "Hello PhoneBase"
json
{
  "code": 0,
  "msg": "ok"
}

按键 ​

发送 Android 按键事件（例如回到桌面）：

bash
pb keyevent HOME
json
{
  "code": 0,
  "msg": "ok"
}

支持的按键名称

常用按键：HOME、BACK、ENTER、DELETE、POWER、VOLUME_UP、VOLUME_DOWN、TAB、SPACE、MENU、SEARCH、ESCAPE。也可以直接使用数字键码（如 pb keyevent 3 代表 HOME）。

检查屏幕（截图 + UI 布局树） ​

使用 inspect 命令可以同时获取截图和 UI 布局树，深入了解设备当前状态：

bash
pb inspect
✓ 检查完成: IDY291LX6WW6RCW

  inspect:    ~/.phonebase/data/inspect/20260409/IDY291LX6WW6RCW-20260409103600-inspect.html
  screenshot: ~/.phonebase/data/inspect/20260409/IDY291LX6WW6RCW-20260409103600-screenshot.jpg
  layout:     ~/.phonebase/data/inspect/20260409/IDY291LX6WW6RCW-20260409103600-layout.xml

  Cmd+Click inspect.html 在浏览器中打开

TIP

inspect.html 提供了一个交互式的视觉检查器，将 UI 布局叠加显示在截图上。这对需要理解屏幕上下文的 AI Agent 尤其有用。

第五步：运行第一个 Skill ​

Skill 是针对常见应用操作的可复用自动化脚本。安装内置 skills：

bash
pb skills install
✓ 已安装 8 个内置 skill

  正在安装全局 skills (phonebase-skills)...
✓ 全局 skills 已安装

查看可用的 skills：

bash
pb skills list
NAME          KIND      ENABLED  VERSION  DESCRIPTION
googleplay    builtin   yes      1.0.0    Google Play 商店自动化
settings      builtin   yes      1.0.0    Android 设置自动化
...

运行一个 skill -- 例如打开 Google Play：

bash
pb googleplay open

搜索应用：

bash
pb googleplay search --keyword "twitter"

TIP

每个 skill 提供多个子命令。使用 pb <skill名称> --help 查看该 skill 的所有可用操作。

第六步：AI Agent 集成 ​

pb 的每个命令在非 TTY 环境下（如被 Claude Code 或其他 AI Agent 调用时）都会输出结构化 JSON。AI Agent 可以直接解析输出，无需额外处理。

例如，当 Claude Code 执行：

bash
pb inspect

它收到的是：

json
{
  "code": 0,
  "msg": "Inspect complete: IDY291LX6WW6RCW",
  "data": {
    "inspect": "/Users/you/.phonebase/data/inspect/20260409/...-inspect.html",
    "screenshot": "/Users/you/.phonebase/data/inspect/20260409/...-screenshot.jpg",
    "layout": "/Users/you/.phonebase/data/inspect/20260409/...-layout.xml"
  }
}

Agent 读取截图来"看到"手机画面，分析布局树来理解 UI 结构，然后发出下一条 pb 命令 -- 全程不需要任何自定义 API 集成。

INFO

在交互式终端中也可以通过设置 PHONEBASE_OUTPUT=json 来强制 JSON 输出。详见环境变量。

第七步：断开连接 ​

操作完成后，断开与设备的连接：

bash
pb disconnect
✓ 已断开连接

WARNING

断开连接不会停止或删除设备。设备会继续运行，计费也会继续。要停止计费，请明确停止或删除设备：

bash
# 停止设备（之后可以重新启动）
pb devices stop IDY291LX6WW6RCW

# 或者永久删除设备
pb devices delete IDY291LX6WW6RCW

下一步 ​

你已经完成了 PhoneBase 的基础配置。接下来可以了解：

Copyright © 2026 PhoneBase