phone-agent

Phone Agent Skill

通过本地 MCP Server 桥接浏览器中运行的 Mobile AI Agent，让 OpenClaw 可以远程控制手机——无需额外代码，直接用自然语言描述任务即可。

⚠️ 安全须知 —— 使用前必读

本技能会在真实设备上执行实际操作。 Agent 可以打开应用、点击界面元素、输入文本、发送消息、更改设置，以及运行多步骤自动化流程——这些操作可能不可逆地改变设备状态或产生现实后果。

潜在影响

用户同意要求

1. 明确确认：在执行任何可能发送消息、触发购买或修改关键设置的任务之前，Agent 必须向用户确认操作意图并等待明确批准。
2. 任务范围清晰：用户应精确描述任务。模糊的指令（如“清理我的手机”）可能导致非预期操作。
3. 建议在旁监督：首次使用或高风险操作时，请在旁观察 Agent 通过投屏实时执行的过程。
4. 可随时中止：如 Agent 开始非预期操作，可随时调用 abort_task 立即停止。

AI Agent 调用本技能的最佳实践

• 在调用 run_agent_task 执行涉及发送消息、购买、删除数据或更改系统设置的目标之前，务必先征得用户确认。
• 优先使用只读操作：先用 take_screenshot 和 get_device_status 检查当前状态，再执行写入操作。
• 涉及金融交易或不可逆操作的失败任务，未经用户重新确认不得自动重试。

何时使用本技能

• 用户要求操控真实手机（打开应用、点击、输入、滑动）
• 用户要求查看手机当前界面（截图）
• 用户要求查询设备信息（型号、系统版本）
• 用户要求在手机上执行多步骤 AI 自动化任务
• 用户要求查询/中断正在运行的 Agent 任务

架构概览

┌──────────────────────────────────────────────────────────────────────┐
│                        External AI Agent                             │
│              (OpenClaw / Qoder / Claude Desktop / Chrome AI)         │
└───────────┬──────────────────────────────────────────┬───────────────┘
            │ 通道 A：stdio JSON-RPC 2.0                │ 通道 B：document
            ▼                                          │   .modelContext
┌───────────────────────────────┐                      │   .callTool()
│  mcp-server/dist/server.js    │                      ▼
│  (Node.js McpServer)          │      ┌───────────────────────────────┐
│  6 Tools 注册于 stdio 传输      │      │   Chrome WebMCP Runtime       │
└───────────┬───────────────────┘      │   (#enable-webmcp-testing)    │
            │ WebSocket                └───────────────┬───────────────┘
            │ ws://localhost:7788                      │ execute()
            ▼                                          ▼
┌──────────────────────────────────────────────────────────────────────┐
│                        浏览器页面（Mobile AI Use）                     │
│   McpRelayClient(通道 A)        WebMcpService(通道 B)                 │
│                └────────────┬────────────┘                           │
│                             ▼  McpServiceContext（共用）              │
│            Plan-and-Resolve Agent / ReAct Agent                      │
└─────────────────────────────┬────────────────────────────────────────┘
                              │  Web ADB
                              ▼
┌──────────────────────────────────────────────────────────────────────┐
│                       Android / iOS Device                           │
└──────────────────────────────────────────────────────────────────────┘

Installation/Setup

1. 启动本地 MCP Server

cd <项目根目录>/mcp-server
npm install      # 首次运行需安装依赖
npm run build    # 编译 TypeScript
npm start        # 启动服务（监听 stdio + WebSocket :7788）

2. 打开 Mobile AI Agent 页面

访问 https://mobile-ai-use.com/mobileAi ，页面 header 右上角的 Relay 指示器变绿即表示连接成功。

3. 连接手机

通过 USB 连接 Android 设备，页面显示"已连接"。

4. 配置 OpenClaw（在 openclaw.json 中添加）

{
  mcp: {
    servers: {
      "phone-agent": {
        command: "node",
        // 将  替换为实际绝对路径
        args: ["/mcp-server/dist/server.js"],
        env: {
          // 可选：修改 WebSocket 端口（默认 7788）
          PHONE_AGENT_WS_PORT: "7788"
        }
      }
    }
  }
}

也可以通过 CLI 配置：

openclaw mcp set phone-agent --command node --args "/mcp-server/dist/server.js"

Usage

直接描述任务，无需写代码：

打开微信，找到和张三的对话，发送一条"你好"

截个屏看看手机当前界面是什么

打开手机设置，查看系统版本信息

中断正在执行的任务

最近一次 Agent 任务的结果是什么

工具说明

完整调用链

OpenClaw Agent
    │ stdio  JSON-RPC 2.0
    ▼
mcp-server/dist/server.js  (Node.js MCP Server)
    │ WebSocket  ws://localhost:7788
    ▼
浏览器页面 AiChatPanel  (McpRelayClient)
    │ McpServiceContext
    ▼
PlanResolveAgent / ReAct Agent
    │ Web ADB
    ▼
手机

故障排查