---
description: Use this skill when the user asks how VisionClaw works, what commands are available, how to interact with the agent, or needs help understanding the agent's features and behavior. Covers commands, messaging channels, wake/sleep cycle, Telegram Mini Apps, realtime voice, WeChat login, tools, memory, skills, and the web console.
---

# VisionClaw User Manual

This document describes how VisionClaw works and how the owner can interact with it.

## What is VisionClaw?

VisionClaw is a personal desktop agent that runs as a long-lived process on macOS or Windows. It owns and controls the computer it runs on: it can execute terminal commands, control GUI applications, browse the web, manage files, send emails, use calendars, and interact with desktop/mobile apps. It is powered by the Claude Agent SDK and can be configured with different model providers.

The agent has its own identity: a dedicated Gmail account, Google Calendar, Google Drive, Telegram bot, and optional app accounts such as WeChat and GitHub. It acts autonomously on behalf of its owner, while keeping the owner reachable through Telegram and other enabled channels.

## Communication Channels

### Command Channel: Telegram

Telegram is the primary command channel. Telegram messages wake the agent immediately and are processed with highest priority. When the agent is sleeping, a Telegram message wakes it. When the agent is busy, the message is injected into the active turn and the fast responder may immediately acknowledge it.

Any normal text message sent by the owner via Telegram is treated as a command or task for the agent to execute.

### Telegram Slash Commands

Owner-only commands:

| Command | Description |
|---|---|
| `/help` | Show the live command list. |
| `/status` | Open the status Mini App when available, or send a cached text status report. |
| `/status refresh` | Force fresh service health checks and send a text status report. |
| `/tasks` | Show the current task, todo list, and recent activity steps. |
| `/stop` | Stop the agent's current task and return to sleep. |
| `/sleep <minutes>` | Change the heartbeat interval, 1–1440 minutes. Example: `/sleep 30`. |
| `/console` | Get the web console URL. |
| `/restart` | Restart the agent process after a short delay. Useful after configuration changes or when the agent is stuck. |
| `/tunnel restart` | Restart the tunnel connection without restarting the agent. |
| `/screenshot` | Take a desktop screenshot and send it back via Telegram. |
| `/rdp [minutes]` | Generate a temporary browser-based remote desktop link. Defaults to 30 minutes; max 480 minutes. |
| `/realtime` | Open the realtime voice Telegram Mini App. |
| `/settings` | Open settings for language/timezone changes. |
| `/backup` | Create a ZIP backup of memories, skills, sessions, and profile data. |
| `/subscribe` | Show subscription status and billing management options. |
| `/usage` | Show a tool-call usage report with recent trends. |
| `/silent [on\|off]` | Toggle silent context compaction mode. |
| `/refresh` | Force context compaction to recover from a confused/corrupted session. |
| `/weixin` or `/wechat` | Start WeChat QR login from Telegram. |
| `/android-use on\|off` | Toggle Android-use tools. Requires restart to fully take effect. |
| `/chat-monitor on\|off` | Toggle realtime chat message monitoring for supported chat apps such as WeChat/Feishu. |
| `/upgrade_beta` | Upgrade to the latest beta release. |
| `/upgrade_dev <tag>` | Upgrade to a dev release by npm dist-tag. |

Telegram's slash-command menu intentionally shows only the most common commands, including `/stop`, `/restart`, `/screenshot`, `/status`, `/tasks`, `/subscribe`, `/refresh`, `/realtime`, and `/settings`. Hidden commands such as `/rdp`, `/weixin`, `/upgrade_beta`, and `/upgrade_dev` still work when typed manually.

Unknown slash commands are rejected with a short help message instead of being forwarded to the main agent. Natural-language messages that do not start with `/` are unaffected.

### Unknown Telegram Chat Approval

When a new Telegram DM or group that has not been approved yet contacts the agent:

- The chat is marked as pending.
- The owner receives a notification with the chat name, preview, and Approve / Block inline buttons.
- The owner can manage requests with `/requests`, `/approve <id>`, `/block <id>`, and `/chats`.
- Messages from that chat are held until approval instead of being delivered immediately.
- Once approved, held messages are released to the agent automatically.
- Non-owner chats cannot use owner-only slash commands.

### Realtime Voice Mini App (`/realtime`)

`/realtime` sends an inline Telegram Web App button that opens VisionClaw's realtime voice interface. The Mini App is served from the existing observability tunnel at `/realtime`; no separate port or DNS setup is needed.

The realtime voice interface is designed for short, live conversations with the verified owner:

- It uses Telegram Mini App init-data verification, so only the Telegram owner can create a voice session.
- It creates a short-lived realtime session and connects to OpenAI's realtime voice model.
- It has a compact snapshot of the main agent's state and live activity summary at session start.
- It can answer conversationally and use a small set of safe realtime tools.
- It stores each completed voice transcript under the profile's `voice-transcripts` data and in a SQLite voice session table.
- After the call ends, VisionClaw summarizes the voice transcript. Open follow-up requests are injected back into the normal agent message path so the main desktop agent can handle work that was outside the realtime interface.

Realtime voice capabilities are intentionally narrower than the main desktop agent. It can use tools such as calendar, web/news/local/hotel/flight/finance search, Gmail list/send, persistent memory, stock quotes, Telegram self-message, and quick reminders. It cannot control the desktop, run terminal commands, edit files, automate chat apps, manage MCP servers, restart/upgrade/reconfigure the main agent, or access the full historical context. For anything outside its realtime tool list, it should briefly acknowledge the request and hand it off to the main agent through the post-call summary.

Requirements and caveats:

- The OBS/console tunnel must be available; otherwise `/realtime` reports that the Mini App is unavailable.
- Telegram bot token and owner Telegram chat ID must be configured.
- An OpenAI API key must be configured for the realtime model.
- Voice session links are short-lived and tied to the verified Telegram session.

### WeChat Login (`/weixin` / `/wechat`)

`/weixin` and `/wechat` start the WeChat login flow from Telegram:

1. VisionClaw asks the WeChat/OpenClaw service to start a QR-code login session.
2. It renders the login URL as a QR image and sends the image to the owner in Telegram.
3. The owner scans the QR code with WeChat.
4. VisionClaw waits for login completion for up to about 8 minutes.
5. On success, it saves the WeChat account credentials into the current VisionClaw profile, enables the WeChat channel configuration, registers the account ID, and schedules a restart so the new configuration is loaded.

There is also a CLI command, `visionclaw weixin-login`, for standalone QR authentication. The CLI and Telegram flows store WeChat state under VisionClaw's profile directory rather than a global OpenClaw directory.

### Other Channels

- **Gmail** — Always available when configured. The agent can send, receive, search, and manage email as its Gmail identity.
- **Discord** — Optional. Can be enabled in configuration.
- **WeChat and other chat apps** — Can be used through configured integrations, chat monitoring, browser automation, mobile automation, or desktop control depending on the environment. They are not as privileged as the owner Telegram command channel.
- **System/internal messages** — Some subsystems, such as realtime voice summaries or restart markers, enqueue internal messages into the same wake/interrupt path as user messages.

### Message Priority

- Telegram owner messages and commands → instant wake or active-turn interrupt.
- Internal system messages → normal queue path; can wake or interrupt depending on agent state.
- Gmail / Discord messages → queued and processed by the message queue.
- Desktop/app notifications → observed through screenshots, chat monitors, or explicit automation during wake cycles.

## Wake / Sleep Cycle

VisionClaw operates on an infinite wake/sleep loop:

1. **Sleep** — The agent idles, waiting for a new message, an internal event, or the heartbeat timer.
2. **Wake** — The agent gathers context, including desktop screenshot, upcoming calendar events, queued messages, memory, active realtime voice session metadata, and other configured context.
3. **Act** — The agent decides what to do and executes tasks using tools such as browser automation, terminal, desktop control, email/calendar/drive, and memory.
4. **Report** — The agent notifies the owner of meaningful results or blockers.
5. **Finish** — The agent calls `finish` and returns to sleep.

If a new message arrives while the agent is busy, the fast responder may send a quick acknowledgement, and the message is injected into the active context. The main agent is still single-threaded: it can only perform one active task step at a time.

## Sessions and Context

### Single-Threaded Execution

VisionClaw can only operate one active desktop/browser/terminal workflow at a time. If multiple requests arrive, the agent decides whether to switch tasks, queue work, or finish its current step first.

### Dual-Session Architecture (Optional)

When enabled, VisionClaw keeps separate conversation sessions:

- **General session** — Conversations, quick tasks, questions, scheduling, status checks, and non-coding work.
- **Coding session** — Complex coding tasks such as refactors, debugging, and multi-file implementation.

Only one session is active at a time. The `switch_session` tool hands off between sessions with a memo containing progress and decisions.

### Context Maintenance

VisionClaw may compact or refresh context to stay within model limits. `/refresh` forces compaction when the agent seems confused. `/silent on` suppresses routine compaction notifications; `/silent off` restores them.

## Available Tools

### Communication

- **notify_user** — Send text, images, files, and screenshots back to the owner through enabled channels.
- **Telegram command handling** — Stop, status, tasks, realtime, RDP, backup, settings, subscription, WeChat login, and maintenance commands are handled directly without asking the main LLM to improvise.

### Desktop, Browser, and Remote Access

- **computer_use_click / move / scroll / drag / type / key / screenshot** — Control mouse and keyboard for desktop applications using AI-powered coordinate resolution.
- **Playwright MCP tools** — Browser automation: navigate, click, fill forms, inspect pages, execute JavaScript, and capture snapshots. Prefer Playwright for browser work; use computer-use tools for desktop apps or fallback cases.
- **remote desktop (`/rdp`)** — Generate a temporary browser-based desktop stream link through the OBS tunnel.
- **Chrome Remote Desktop / Windows RDP** — The owner can also connect directly when configured.

### Productivity

- **manage_calendar** — Create, update, delete, list events, and find free time.
- **manage_email** — Send, read, search, and manage Gmail.
- **manage_drive** — Upload, download, list, and manage Google Drive files.
- **web_fetch** — Fetch URL content in readable form.
- **Search tools** — Web/news/local/hotel/flight/finance and stock quote tools are available in the main agent and a safe subset is available to realtime voice.

### Memory & Knowledge

- **memory** — Persistent storage under `/memories` that survives context compaction. The agent should proactively save important owner preferences, durable facts, project state, and long-running task notes.
- **Transcript memory** — Realtime voice sessions are summarized and stored separately so actionable follow-ups can reach the main agent.

### Skills

- **manage_skills** — Create, update, delete, list, browse catalog, and install reusable `SKILL.md` instruction sets.
- **Skill invocation** — The SDK can invoke installed skills when a task pattern matches.

### MCP Server Management

- **manage_mcp_servers** — Add, remove, or list external MCP servers at runtime. Supported transport types include stdio, HTTP, and SSE. Added servers persist across restarts and are hot-loaded into the current session where possible.

### System and Maintenance

- **screenshot** — Capture the current desktop.
- **wait** — Pause execution.
- **finish** — Signal task completion and return to sleep.
- **upgrade** — Self-update VisionClaw.
- **backup / restore / reset / reconfigure** — Profile maintenance is available through CLI commands, and backup can be requested from Telegram.

## Web Console, Mini Apps, and Self-Monitoring

VisionClaw includes a built-in observability server exposed through the existing tunnel. Use `/console` to get the console URL.

The console provides:

- Real-time activity log: watch tool calls, messages, and agent activity live.
- Memory viewer: browse persistent memory files.
- Skills viewer: inspect installed skills and descriptions.
- Agent status: see whether the agent is idle or busy.
- Stop button: emergency stop from the web UI.
- Mounted apps: status Mini App, realtime voice Mini App, and browser-based remote desktop links are served from the same tunnel when enabled.

### Agent Self-Inspection

VisionClaw typically runs under pm2 as a managed process. Useful commands include:

- `pm2 logs visionclaw --lines 100` — View recent stdout/stderr.
- `pm2 logs visionclaw --err --lines 50` — View recent errors.
- `pm2 logs visionclaw --nostream --lines 200` — Dump recent logs without tailing.

CLI status helpers:

- `visionclaw agent status` — Show agent status, process info, and config.
- `visionclaw ctx status` — Show context window usage and session info.
- `visionclaw ctx compact` — Trigger manual context compaction while the agent is stopped.
- `visionclaw ctx refresh` — Rotate current sessions and force new sessions on next start.

### Pre-Installed System Utilities

- **pm2** — Process manager for VisionClaw and other long-running services.
- **cloudflared** — Cloudflare Tunnel client. The onboarding service provisions the tunnel. Do not run `cloudflared tunnel login`, create a replacement tunnel, or overwrite credentials unless explicitly instructed by maintainers.

## Memory System

The agent maintains a persistent memory directory (`/memories`). Since the model context window is finite, important information should be saved there proactively.

Memory should be used for:

- Owner preferences and durable facts.
- Long-running task state.
- Credentials metadata or account notes, but never raw secrets unless explicitly designed for secure storage.
- Project conventions and recurring workflows.

At wake time, the agent checks memory for relevant prior context. During work, it records status updates and important facts to preserve continuity across compaction and restarts.

## Skills System

Skills are reusable `SKILL.md` files that teach the agent specialized procedures. Built-in skills are installed automatically, and the agent can create or install additional skills for repeated tasks. Skills should contain operational guidance, not ephemeral task notes.

## CLI Commands

Main user/operator commands include:

| Command | Description |
|---|---|
| `visionclaw` | Start the agent using the selected profile. |
| `visionclaw prepare` | Auto-detect platform and run preparation steps. |
| `visionclaw prepare-mac` | Prepare a fresh Mac: dependencies, desktop settings, permissions. |
| `visionclaw prepare-mac-power` | Run only macOS power/screen settings. |
| `visionclaw prepare-windows` | Prepare a fresh Windows machine. |
| `visionclaw setup <source>` | Run manufacturer/pre-ship setup from provisioning JSON, URL, or onboarding key. |
| `visionclaw set-owner` | Set the owner email/name for post-ship onboarding. |
| `visionclaw reconfigure` | Update an existing profile without starting the agent. |
| `visionclaw backup` | Create and upload a ZIP backup. |
| `visionclaw restore` | Restore from a backup ZIP or signed HTTP URL. |
| `visionclaw reset --owner` | Clear owner data, memories, skills, and DBs while preserving config/logs. |
| `visionclaw reset --machine` | Delete the entire profile directory for a fresh setup. |
| `visionclaw reinstall-skills` | Reinstall built-in skills. |
| `visionclaw weixin-login` | Authenticate WeChat via QR code scan. |
| `visionclaw daemon start\|stop\|restart\|status\|logs` | Manage the pm2/LaunchAgent daemon. |
| `visionclaw daemon install\|uninstall` | Install or remove macOS login auto-start. |
| `visionclaw ctx status\|compact\|refresh` | Inspect or manage context/session state. |
| `visionclaw agent status` | Show agent/process/config status. |

Data-processing and internal maintenance commands also exist for log sanitization, restructuring, batch processing, transcript expansion, and memory backfill.

Global options:

- `--profile <name>` — Use a specific profile; default is `default`.
- `-d`, `--debug` — Enable debug logging.
- `-v`, `--version` — Print version.
- `-h`, `--help` — Show CLI help.

## Proactive Behavior

During heartbeat wakes, VisionClaw may:

- Review upcoming calendar events.
- Follow up on pending tasks.
- Check queued messages and internal events.
- Observe desktop/app state.
- Perform maintenance such as update checks or context/memory housekeeping.

## Error Handling

- Retryable errors such as transient network problems, rate limits, and server errors are retried with exponential backoff.
- Fatal errors such as authentication or billing problems are reported to the owner and retried later.
- Repeated failures trigger owner notifications with details.
- Telegram administrative commands such as `/stop`, `/restart`, `/console`, and `/screenshot` are designed to remain available even when the main agent is otherwise impaired.

## Remote Desktop Access

The owner can take direct control of the agent's machine.

### Browser-Based RDP Link

Use `/rdp [minutes]` in Telegram to generate a temporary remote desktop link served through the OBS tunnel. This is useful for quick visual inspection or intervention without opening a separate remote desktop product.

### Chrome Remote Desktop / Native RDP

On macOS, Chrome Remote Desktop is commonly configured. On Windows, native RDP or Chrome Remote Desktop may be available.

How to connect with Chrome Remote Desktop:

1. Log in to the same Google account the agent uses.
2. Open [Chrome Remote Desktop](https://remotedesktop.google.com/access).
3. Select the agent machine.
4. Enter the connection PIN from onboarding.

Important notes:

- The owner and the agent share the same screen. Manual mouse/keyboard activity may interfere with the agent. Use `/stop` before taking control when possible.
- Use `/screenshot`, `/status`, `/tasks`, and `/console` for lighter-weight inspection before taking over.

## Subscription & Billing

VisionClaw uses a subscription-based billing model. Each agent requires an active subscription to operate.

Subscription states:

- **Active** — The agent processes messages normally.
- **Expired / cancelled** — The agent stops processing normal tasks, but Telegram administrative commands continue to work where possible.

Use `/subscribe` in Telegram to view subscription status and billing options. Owners can also manage subscription, payment methods, invoices, cancellation, or resubscription through the Stripe customer portal:

[Manage Subscription](https://billing.stripe.com/p/login/dR65nN0KEf6z1Og8ww)

## Tips for Owners

1. Use Telegram for urgent commands; it is the fastest control path.
2. Use `/tasks` to see what the agent is currently doing before interrupting it.
3. Use `/status` for a quick dashboard and `/status refresh` for fresh health checks.
4. Use `/realtime` for short live voice conversations; longer or desktop-heavy work will be handed off to the main agent after the call.
5. Use `/weixin` when WeChat needs to be logged in or refreshed.
6. Use `/stop` before taking over the desktop manually.
7. Use `/restart` if the process is misbehaving and `/tunnel restart` if public links stop working.
8. Use `/rdp` or Chrome Remote Desktop for hands-on intervention.
9. Use `/sleep 5` for frequent check-ins or `/sleep 60` for quieter operation.
10. Send images, documents, audio, and voice messages through Telegram when useful; the agent can process multimodal inputs.
11. Let the agent save durable preferences to memory so you do not need to repeat context.
