VAGUS - Phone MCP Connection

VAGUS gives you access to the user's Android phone through the Model Context Protocol. You interact with it by running subcommands of the connection script at {baseDir}/scripts/vagus-connect.js.

Note on installation location: The skill must reside in the user OpenClaw skills directory ~/.openclaw/skills/vagus. This directory is persistent and survives OpenClaw updates. System-wide installs to /usr/local/lib/node_modules/openclaw/skills/vagus may be removed during updates and are not recommended.

All commands output one JSON object per line (JSONL). Parse the output to get structured data.

Connection Management

Check if already paired

cat ~/.openclaw/vagus-session.json 2>/dev/null

If the file exists and contains a session_token, you can connect directly. If not, you need to pair first.

Pair with the phone (first time)

Ask the user: "Open the VAGUS app on your phone and tap Generate Code. What's the 6-character code?"

Then run:

node {baseDir}/scripts/vagus-connect.js pair <CODE>

If {baseDir} is not set or the script not found, ensure the skill is installed correctly in ~/.openclaw/skills/vagus (see README).

Output on success:

{"type":"paired","session_token":"...","device_model":"...","vagus_version":"..."}
{"type":"capabilities","resources":[...],"tools":[...]}

Output on failure:

{"type":"error","code":"PAIR_FAILED","message":"..."}

If pairing fails, ask the user to check the VAGUS app is running and generate a new code.

Set agent identity name (required after install/pair)

After a successful pair (or first successful connect on a fresh install), set the device-side agent name to your Identity Name.

Run:

node {baseDir}/scripts/vagus-connect.js call agent/set_name '{"name":"<IDENTITY_NAME>"}'

If you need to clear the stored name:

node {baseDir}/scripts/vagus-connect.js call agent/set_name '{"name":""}'

Connect (already paired)

node {baseDir}/scripts/vagus-connect.js connect

Output:

{"type":"connected","device_model":"...","vagus_version":"..."}
{"type":"capabilities","resources":[...],"tools":[...]}

If the session token is expired or invalid:

{"type":"error","code":"SESSION_EXPIRED","message":"..."}

Delete the session file and re-pair:

rm ~/.openclaw/vagus-session.json

Then ask the user for a new pairing code.

Check status

node {baseDir}/scripts/vagus-connect.js status

Output:

{"type":"status","connected":true,"device_model":"...","active_modules":[...],"subscriptions":[...],"uptime_s":3600}

Or if disconnected:

{"type":"status","connected":false,"last_error":"...","reconnect_attempts":3}

Reading Phone State

Read a resource (one-shot)

node {baseDir}/scripts/vagus-connect.js read vagus://sensors/motion

Output: