Vagus

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:

{"type":"resource","uri":"vagus://sensors/motion","data":{"ax":0.38801706,"ay":-0.26395237,"az":0.86320007,"gx":0.89825606,"gy":0.7034855,"gz":-0.21225691,"ts":1771626476045}}

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

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

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

{"type":"update","uri":"vagus://sensors/motion","data":{"ax":0.12,"ay":-0.04,"az":0.98,"gx":0.01,"gy":0.02,"gz":-0.01,"ts":1771626476045}}
{"type":"update","uri":"vagus://sensors/motion","data":{"ax":0.20,"ay":-0.10,"az":0.92,"gx":0.03,"gy":0.05,"gz":-0.02,"ts":1771626477045}}

Unsubscribe:

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

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

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

Acting Through the Phone

Call a tool

node {baseDir}/scripts/vagus-connect.js call <tool-name> '<json-params>'

Output on success:

{"type":"result","tool":"notify","success":true,"data":{...}}

Output on failure:

{"type":"result","tool":"notify","success":false,"error":"PERMISSION_DENIED","message":"..."}

Available tools

haptic/pulse - Single vibration

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

Parameters: durationMs (10-5000, optional; default device value)

haptic/pattern - Custom vibration pattern

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

Parameters: pattern (array of integer durations in ms, optional; default device pattern)

speak - Text-to-speech through phone speaker

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

Parameters: text (string max 5000 chars, required), language (BCP 47 tag, optional), rate (0.25-2.0, optional), pitch (0.5-2.0, optional), interrupt (boolean, optional)

notify - Push notification

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

Parameters: title (string max 200 chars, required), body (string max 1000 chars, required)

clipboard/set - Write to clipboard

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

Parameters: content (string max 10000 chars, required)

sms/send - Send an SMS message

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

Parameters: to (string phone number in local or E.164 format, required), body (string max 2000 chars, required)

intent/open_url - Open a URL in browser

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

Parameters: url (string http/https URL, required)

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}'

Parameters: title (string max 200 chars, required), startTimeMs (integer Unix epoch ms, optional), endTimeMs (integer Unix epoch ms, optional), location (string max 200 chars, optional), description (string max 2000 chars, optional), allDay (boolean, optional)

agent/set_name - Set device-side agent identity name

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

Parameters: name (string, required; set to "" to clear)

List all available tools

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

Behavioral Rules

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. node {baseDir}/scripts/vagus-connect.js status - is WebSocket connected?
2. cat ~/.openclaw/vagus-session.json - 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: {baseDir}/references/troubleshooting.md