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

CODEBLOCK0

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:

CODEBLOCK1

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:

CODEBLOCK2

Output on failure:

CODEBLOCK3

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:

CODEBLOCK4

If you need to clear the stored name:

CODEBLOCK5

Connect (already paired)

CODEBLOCK6

Output:

CODEBLOCK7

If the session token is expired or invalid:

CODEBLOCK8

Delete the session file and re-pair:

CODEBLOCK9

Then ask the user for a new pairing code.

Check status

CODEBLOCK10

Output:

CODEBLOCK11

Or if disconnected:

CODEBLOCK12

Reading Phone State

Read a resource (one-shot)

CODEBLOCK13

Output:

CODEBLOCK14

Available resources

Always read vagus://session/info first to see which modules are active. If a module is not in active_modules, do not try to read its resource, it will fail with a permission error.

Subscribe to continuous updates

CODEBLOCK15

This streams updates as they occur, one JSON line per update:

CODEBLOCK16

Unsubscribe:

CODEBLOCK17

How subscribe works in OpenClaw

• - subscribe is a long-running command. The agent should keep the exec process alive while updates are needed.
• The script emits one JSON object per line (type: "update") on stdout as updates arrive.
• OpenClaw receives these JSONL lines directly from the running process output stream.
• To stop streaming, terminate the process (SIGTERM/SIGINT) or run unsubscribe explicitly.
• Module lifecycle is subscription-driven: modules start when at least one active subscription needs them, and stop when subscriptions end.
• For inference URIs, accuracy is highest while actively subscribed (stream-warm state). One-off read may be cold-start and less accurate briefly.
• On reconnect, the server sends a session/reconnect marker that includes sessionId, gap_ms, and ts.
• After reconnect, each subscribed/re-subscribed resource receives bounded replay (up to last 64 buffered updates since disconnect window), then one fresh snapshot, then normal live updates.

List all available resources

CODEBLOCK18

Acting Through the Phone

Call a tool

CODEBLOCK19

Output on success:

CODEBLOCK20

Output on failure:

CODEBLOCK21

Available tools

haptic/pulse - Single vibration

node {baseDir}/scripts/vagus-connect.js call haptic/pulse '{"durationMs":200}'

haptic/pattern - Custom vibration pattern

node {baseDir}/scripts/vagus-connect.js call haptic/pattern '{"pattern":[0,120,80,120]}'

speak - Text-to-speech through phone speaker

node {baseDir}/scripts/vagus-connect.js call speak '{"text":"You have a meeting in 10 minutes"}'

notify - Push notification

node {baseDir}/scripts/vagus-connect.js call notify '{"title":"Reminder","body":"Check your email"}'

clipboard/set - Write to clipboard

node {baseDir}/scripts/vagus-connect.js call clipboard/set '{"content":"https://example.com"}'

sms/send - Send an SMS message

node {baseDir}/scripts/vagus-connect.js call sms/send '{"to":"+15145551212","body":"Running 10 minutes late"}'

intent/open_url - Open a URL in browser

node {baseDir}/scripts/vagus-connect.js call intent/open_url '{"url":"https://withvagus.com"}'

calendar/create_event - Create a calendar event on device

node {baseDir}/scripts/vagus-connect.js call calendar/create_event '{"title":"Team Sync","startTimeMs":1771693200000,"endTimeMs":1771696800000,"location":"Zoom","description":"Weekly planning","allDay":false}'

agent/set_name - Set device-side agent identity name

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

List all available tools

CODEBLOCK31

Behavioral Rules

1. 1. Read vagus://session/info before using any other resource to check what is available.
2. Do not read location or notifications unless the user's request is relevant to them.
3. Prefer notify over speak for non-urgent communication.
4. Check vagus://device/screen before speaking, do not speak if the screen is off and the user might be sleeping.
5. If a resource read or tool call returns PERMISSION_DENIED, tell the user which capability they need to enable in the VAGUS app. Do not retry.
6. If connection drops, run status to check. If SESSION_EXPIRED, delete ~/.openclaw/vagus-session.json and ask for a new pairing code.
7. Do not poll resources in a tight loop. Read when contextually relevant.
8. For inference resources, prefer a short subscription window when accuracy matters (instead of immediate one-off read after idle).

Troubleshooting

If something is not working, check in this order:

1. 1. node {baseDir}/scripts/vagus-connect.js status - is WebSocket connected?
2. INLINECODE73 - does session file exist?
3. Ask user: "Is the VAGUS app running? Do you see the persistent notification?"
4. Ask user: "Is your phone connected to the internet?"
5. If nothing works: rm ~/.openclaw/vagus-session.json and re-pair with a new code.

Full diagnostics: INLINECODE75