VAGUS

Openclaw Deployment Overview

OpenClaw uses VAGUS through natural language. The user should not need terminal commands to install, pair, or use the phone capabilities. The agent retrieves files, installs dependencies, pairs with the app, and runs MCP operations autonomously.

Natural-Language Flow

Primary UX is conversational. A typical user flow:

1. User asks OpenClaw to install VAGUS from the repository URL.
2. Agent fetches skill files, installs Node dependency, and registers the skill.
3. Agent asks user for the code from the VAGUS Android app.
4. Agent pairs, verifies capabilities, and confirms connection in plain language.
5. User asks for actions in natural language (notify, open URL, send SMS, create event, read context).

Pairing is a one-time bootstrap. Subsequent requests reuse the saved session token until expired or revoked.

Prompt Cookbook

This prompt-first contract is the primary documentation surface for OpenClaw operators.

User Journey

1. Install and Pair

User: Install VAGUS from https://github.com/vagus-mcp/openclaw-skill
Agent: I installed the skill. Open the VAGUS app and share your pairing code.
User: 584821
Agent: Paired successfully. I can now access phone resources and tools.

2. Ask for Context

User: Are you tracking my screen state?
Agent: Yes. Your screen is currently on and unlocked.
User: Start tracking location too.
Agent: Done. I am now streaming screen and location context.

3. Trigger Actions

User: Send a test notification.
Agent: Sent.
User: Open withvagus.com.
Agent: Opened on your phone.
User: Add an event Sunday 3pm called Event Name.
Agent: Created the event.

4. Recover from Failures

User: Send the SMS again.
Agent: The device approval timed out. Please approve on your phone and I will retry once.
User: Retry.
Agent: Sent successfully.

These transcripts are the intended user-facing interaction model in OpenClaw. CLI details remain internal.

Architecture

Protocol Lifecycle

1. Pair

Client posts pairing code and receives session token.

POST https://relay.withvagus.com/pair
{"code":"ABC123"}

2. Connect + Initialize

Client opens WSS with the token and runs MCP initialization. Implementation sends compatibility variants: initialized, notifications/initialized, and an initialized request.

connect WSS -> initialize -> initialized notifications
-> resources/list + tools/list

MCP responses and notifications now include request correlation metadata at: metadata.requestId. This is emitted by the server for request/notification lineage.

{
  "jsonrpc": "2.0",
  "id": 2,
  "metadata": {
    "requestId": "43818824:resources/read:5545a8fa214dd67e:2c570c8b7e66e561"
  },
  "result": { "contents": [ ... ] }
}

3. Operate

Client executes reads, tool calls, or subscriptions. All stdout is JSONL for machine parsing.

Agent Execution Contract (Internal)

The following command interface is internal to agent implementation and diagnostics. End users should interact via natural language prompts.

Base invocation used by agent runtime:

node {baseDir}/scripts/vagus-connect.js <command> [args]

Streaming Model

Subscriptions are long-running agent-managed processes. OpenClaw should keep each subscription process alive, parse JSONL updates, and stop streams only when user intent changes.

node {baseDir}/scripts/vagus-connect.js subscribe vagus://device/screen

{"type":"subscribed","uri":"vagus://device/screen"}
{"type":"update","uri":"vagus://device/screen","data":{"screen_on":true,"locked":false,"last_event":"init","ts":1772036194947}}

On reconnect, server may emit session_reconnect and replay buffered updates before resuming live events. Raw MCP notification envelopes also include metadata.requestId.

User-facing phrasing should remain natural: for example, "I am now tracking your screen and location state." OpenClaw JSONL output is normalized and includes MCP correlation metadata under mcp for operational commands and streamed updates. Capture raw MCP frames only if you need full envelopes.

Resources

Core URI groups:

• Session: vagus://session/info
• Sensors: vagus://sensors/motion, activity, activity_recognition, location, environment
• Inference: vagus://inference/attention, indoor_confidence, sleep_likelihood, notification_timing
• Device: vagus://device/connectivity, screen, battery, clipboard, notifications

For inference URIs, subscription mode generally provides better quality than cold one-shot reads.

node {baseDir}/scripts/vagus-connect.js read vagus://inference/attention
node {baseDir}/scripts/vagus-connect.js subscribe vagus://sensors/location

Tools

Call pattern:

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

Validated Examples

node {baseDir}/scripts/vagus-connect.js call sms/send '{"to":"+15556667777","body":"Test message from VAGUS OpenClaw"}'
node {baseDir}/scripts/vagus-connect.js call intent/open_url '{"url":"https://withvagus.com"}'
node {baseDir}/scripts/vagus-connect.js call calendar/create_event '{"title":"Event Name","startTimeMs":1771772400000,"endTimeMs":1771776000000,"allDay":false}'

User Permissions (Server-Side)

Permission state is controlled by the user in the VAGUS Android app (server side), not by OpenClaw. OpenClaw can request reads/tool calls, but execution depends on enabled modules and approval outcomes.

If blocked, agent messaging should be explicit: ask the user to enable permission or approve on-device, then retry once.

Reliability and Timeouts

If no pong is received within the heartbeat deadline, the socket is force-terminated and upper layers must re-establish connection state.

Error Codes and Handling

Operational Runbooks

Natural-Language Recovery Prompts

• Your session expired. Please open VAGUS and share a new pairing code.
• I can’t reach the relay right now. Please confirm your phone has internet and VAGUS is running.
• This action needs permission in VAGUS. Please enable it, then I’ll retry once.

Session Repair

rm ~/.openclaw/vagus-session.json
node {baseDir}/scripts/vagus-connect.js pair <NEW_CODE>
node {baseDir}/scripts/vagus-connect.js status

Connectivity Probe

node {baseDir}/scripts/vagus-connect.js status
node {baseDir}/scripts/vagus-connect.js read vagus://session/info
node {baseDir}/scripts/vagus-connect.js list-tools

Permission Probe

node {baseDir}/scripts/vagus-connect.js call notify '{"title":"Permission Check","body":"Testing notify permission"}'
node {baseDir}/scripts/vagus-connect.js read vagus://device/notifications

Detailed schema references remain in references/mcp-resources.md, references/mcp-tools.md, and references/troubleshooting.md.