mobile-agent

Phone Agent Skill

Bridges the Mobile AI Agent running in the browser via a local MCP Server, allowing OpenClaw to remotely control a real phone — no extra code needed, just describe the task in natural language.

⚠️ Safety Notice — Read Before Use

This skill performs real actions on a physical device. The Agent can open apps, tap UI elements, type text, send messages, change settings, and execute multi-step automation workflows — all of which may irreversibly alter device state or have real-world consequences.

Potential Impacts

User Consent Requirements

1. Explicit confirmation: Before executing any task that may send messages, trigger purchases, or modify critical settings, the Agent must confirm the intended action with the user and wait for explicit approval.
2. Clear task scope: Users should describe tasks precisely. Vague commands (e.g. "clean up my phone") may lead to unintended operations.
3. Supervision recommended: For first-time use or high-risk operations, stay present and observe the Agent's execution in real time via the screen mirror.
4. Abort capability: Call abort_task at any time to immediately stop the Agent if it begins an unintended action.

Best Practices for AI Agents Calling This Skill

• Always ask the user for confirmation before calling run_agent_task with goals that involve sending messages, making purchases, deleting data, or changing system settings.
• Prefer read-only operations first: Use take_screenshot and get_device_status to inspect the current state before executing write operations.
• Never auto-retry failed tasks that involve financial transactions or irreversible actions without re-confirming with the user.

When to Use This Skill

• The user asks to operate a real phone (open apps, tap, input, swipe)
• The user asks to view the current phone screen (screenshot)
• The user asks to query device information (model, OS version)
• The user asks to run a multi-step AI automation task on the phone
• The user asks to query/abort a running Agent task

Architecture Overview

┌──────────────────────────────────────────────────────────────────────┐
│                        External AI Agent                             │
│              (OpenClaw / Qoder / Claude Desktop / Chrome AI)         │
└───────────┬──────────────────────────────────────────┬───────────────┘
            │ Channel A: stdio JSON-RPC 2.0            │ Channel B: document
            ▼                                          │   .modelContext
┌───────────────────────────────┐                      │   .callTool()
│  mcp-server/dist/server.js    │                      ▼
│  (Node.js McpServer)          │      ┌───────────────────────────────┐
│  6 Tools registered on stdio  │      │   Chrome WebMCP Runtime       │
└───────────┬───────────────────┘      │   (#enable-webmcp-testing)    │
            │ WebSocket                └───────────────┬───────────────┘
            │ ws://localhost:7788                      │ execute()
            ▼                                          ▼
┌──────────────────────────────────────────────────────────────────────┐
│                    Browser Page (Mobile AI Use)                      │
│   McpRelayClient (Channel A)    WebMcpService (Channel B)            │
│                └────────────┬────────────┘                           │
│                             ▼  McpServiceContext (shared)            │
│            Plan-and-Resolve Agent / ReAct Agent                      │
└─────────────────────────────┬────────────────────────────────────────┘
                              │  Web ADB
                              ▼
┌──────────────────────────────────────────────────────────────────────┐
│                       Android / iOS Device                           │
└──────────────────────────────────────────────────────────────────────┘

Installation/Setup

1. Start the Local MCP Server

cd /mcp-server
npm install      # Install dependencies on first run
npm run build    # Compile TypeScript
npm start        # Start the server (listens on stdio + WebSocket :7788)

2. Open the Mobile AI Agent Page

Navigate to https://mobile-ai-use.xyz/mobileAi — the Relay indicator in the top-right corner of the page header turning green indicates a successful connection.

3. Connect the Phone

Connect an Android device via USB; the page should display "Connected".

4. Configure OpenClaw (add to openclaw.json)

{
  mcp: {
    servers: {
      "phone-agent": {
        command: "node",
        // Replace  with the actual absolute path
        args: ["/mcp-server/dist/server.js"],
        env: {
          // Optional: change the WebSocket port (default 7788)
          PHONE_AGENT_WS_PORT: "7788"
        }
      }
    }
  }
}

You can also configure via CLI:

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

Usage

Simply describe the task in natural language — no coding required:

Open WeChat, find the conversation with Zhang San, and send a "Hello" message

Take a screenshot to see what's currently on the phone screen

Open phone Settings and check the system version information

Abort the currently running task

What was the result of the most recent Agent task

Tool Reference

Full Call Chain

OpenClaw Agent
    │ stdio JSON-RPC 2.0
    ▼
mcp-server/dist/server.js  (Node.js MCP Server)
    │ WebSocket ws://localhost:7788
    ▼
Browser Page AiChatPanel (McpRelayClient)
    │ McpServiceContext
    ▼
PlanResolveAgent / ReAct Agent
    │ Web ADB
    ▼
Phone

Troubleshooting