VAGUS

Openclaw Deployment (Legacy) 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 Somatic Memory OpenClaw plugins from https://github.com/embodiedsystems-org/Somatic-Memory-for-Openclaw
Agent: I installed the plugin stack. 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

Persistent streaming should be managed through one long-lived manager session. Direct subscribe remains useful for ad hoc single-stream workflows, but it is no longer the preferred pattern for multiple concurrent long-lived streams.

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

{"type":"lifecycle","uri":"vagus://device/screen","event":{"type":"connected","subscriptions":["vagus://device/screen"]}}
{"type":"stream_state","uri":"vagus://device/screen","status":"warming","freshness_ms":null,"thresholds":null}
{"type":"update","uri":"vagus://device/screen","data":{"screen_on":true,"locked":false,"last_event":"init","ts":1772036194947},"freshness":{"status":"fresh"}}

On reconnect, the client emits session_reconnect, transitions streams through grace/warming as needed, then resumes update delivery once fresh data arrives.

User-facing phrasing should remain natural: for example, "I am now tracking your screen and location state." Freshness should be inferred from stream_state and recent update timing, not from log file activity.

node {baseDir}/scripts/vagus-manager.js
node {baseDir}/scripts/vagus-manager.js add vagus://sensors/location
node {baseDir}/scripts/vagus-manager.js status

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

Subscriptions vs Read-Only

Agents should choose read or subscribe per URI based on server support. Attempting to subscribe to a read-only URI returns an MCP error.

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 io/set_subscription_resolution '{"resolutionMs":30000}'
node {baseDir}/scripts/vagus-connect.js call infer/set_subscription_resolution '{"resolutionMs":30000}'
node {baseDir}/scripts/vagus-connect.js call calendar/create_event '{"title":"Event Name","startTimeMs":1771772400000,"endTimeMs":1771776000000,"allDay":false}'

io/set_subscription_resolution only works when the app governance toggle Allow agent to set resolution is enabled (default off). infer/set_subscription_resolution only works when Allow agent to set infer resolution is enabled (default off).

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
node {baseDir}/scripts/vagus-manager.js status

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.