winnode

<!-- REGENERATE-ME-WHEN-CAPABILITIES-CHANGE

The list of supported commands below is checked at CI time against the live capability surface (see SkillMdDriftTests). When a capability is added, removed, or renamed in src/OpenClaw.Shared/Mcp/McpToolBridge.cs (CommandDescriptions), update this document so the drift test stays green - the test compares command identifiers, so prose can still be tweaked by hand. -->

winnode skill reference

winnode.exe invokes OpenClaw Windows-node commands on the local tray over a loopback MCP HTTP endpoint (default http://127.0.0.1:8765/). Enable Local MCP Server in Settings > Permissions > Integrations before calling. A connection refused on that port means the tray is not listening. Do not reinstall the CLI. Start the tray with EnableMcpServer true, then point OPENCLAW_TRAY_DATA_DIR at that tray's data directory so the CLI loads mcp-token.txt. browser.proxy stays off tools/list until the app has a gateway client, a shared token, and a verified browser endpoint. The call then returns Unknown tool: browser.proxy.

This document is the agent-facing reference: every supported command, its argument shape, and the A2UI v0.8 JSONL grammar. It is shipped alongside winnode.exe so an agent can read it once and emit token-efficient calls.

---

Invocation shape

winnode --command <name> [--params '<json-object>'] [--invoke-timeout <ms>] [--identity release|dev]
winnode --list-tools [--mcp-url <url>|--mcp-port <port>] [--identity release|dev]

• --command (required) - node command (e.g. system.which, canvas.a2ui.push).
• --list-tools - query the live MCP server's tools/list method and print the advertised tools. Useful when settings-gated capabilities differ from this static reference.
• --params - single JSON object string, default {}. Must be a JSON object, not an array or scalar. --params @<path> loads the JSON object from a file on disk (useful for big A2UI payloads / canvas.eval scripts).
• --invoke-timeout - milliseconds, default 15000, max 600000 (10 min). HTTP timeout adds a 5s buffer.
• --node - accepted for parity with openclaw nodes invoke; ignored locally. Safe to copy/paste from gateway-side commands.
• --idempotency-key - accepted for parity; ignored, and the CLI emits a [winnode] WARN to stderr because local MCP does not dedupe retries - re-running a command after a transient failure can double-execute side effects. If you need idempotency, target the gateway, not winnode.
• --mcp-url <url> / --mcp-port <port> - override the endpoint. Falls back to OPENCLAW_MCP_PORT env var, then port 8765. --mcp-port must be in [1, 65535]; out of range fails with exit code 2.
• --mcp-token <token> - bearer token override (testing / explicit only). The literal value is visible to other same-user processes via the OS process listing (Get-CimInstance Win32_Process | Select CommandLine, Process Explorer, etc.). The CLI emits a stderr warning when this flag is used. Prefer OPENCLAW_MCP_TOKEN (env var) or the on-disk %APPDATA%\OpenClawTray\mcp-token.txt which the release tray writes when MCP is enabled. Both OPENCLAW_MCP_TOKEN and the on-disk file should themselves be treated as sensitive operational secrets.
• --identity release|dev - selects which tray profile supplies the default on-disk MCP token. Defaults to OPENCLAW_APP_IDENTITY, then release. Use --identity dev for a side-by-side dev tray; its default token path is %APPDATA%\OpenClawTray-Dev\mcp-token.txt. OPENCLAW_TRAY_DATA_DIR still wins for isolated runs and points directly at the data folder.
• --verbose - log endpoint + ignored flags to stderr. Without --verbose, HTTP error bodies are emitted only as the first line; with --verbose, the full body is shown (after sanitization + token-shape redaction).
• --input-file <path> - raw local input for file.create. Computes size and SHA256, checks any caller-supplied values, and streams bounded messages.
• --output-file <new-path> - raw local output for file.fetch; requires explicit positive maxBytes. Never overwrites. Validates returned size and SHA256 before publishing its owned partial file at the requested destination. Both options use one --invoke-timeout deadline, preserve supplied expected identity, and use ordinary preflight only to fill missing binding/path fields.

Output contract: stdout receives the capability payload as pretty-printed JSON (matches openclaw nodes invoke). stderr receives errors. Exit code:

Code	Meaning
0	Success
1	Tool error, JSON-RPC error, transport failure, or HTTP non-2xx
2	Argument error (missing/invalid flags, bad --params JSON, out-of-range port/timeout, non-http URL)

Off-loopback safety: when --mcp-url points at a non-loopback host, the CLI refuses to send the auto-loaded local MCP token (and warns on stderr). An explicitly supplied --mcp-token is honored with a warning. This preserves the loopback-only threat model the tray's MCP server relies on.

---

Commands

Files and directories

All eight commands use the existing Node Sandbox configuration and executor, the same as system.run. Supported Windows runs the fixed worker through MXC. Positively unsupported Windows uses explicit uncontained compatibility, with no Sandbox filesystem/network enforcement; failed probes, SDK or launch errors do not downgrade. Existing Node/MCP enablement applies, without new file permission switches or shell exec approval prompts. Remote Gateway trust/allowlists and admin checks remain independent. Settings changes apply to new operations only.

Unary reads/archives default to 8 MiB and cap at 16 MiB. Writes/uploads cap at 16 MiB decoded. CLI file envelopes use a command-specific bounded HTTP allowance, not an increase to every tool's request/response limit. Ordinary MCP clients can use unary and preflight calls without the optional framed extension.

file.stat

Inspect metadata: { "path": "C:\\Data\\sample.txt" }. Optional followSymlinks, preflightOnly, expectedCanonicalPath, expectedBinding. Returns {ok,path,type,size,mtimeMs,binding} and an opaque identity binding. Preserve returned bindings without rewriting IDs. Ordinary local drive paths are supported. Reparse points, Cloud Files hydration, case-sensitive directories and followSymlinks:true fail explicitly.

file.fetch

Unary read: { "path": "C:\\Data\\sample.txt", "maxBytes": 16777216 }. Returns {ok,path,size,mimeType,base64,sha256,binding}. Optional shared identity fields and preflightOnly. For binary, require transport:"binary", explicit positive maxBytes, an existing expectedBinding, and framed IO.

winnode --command file.fetch --params '{"path":"C:\\Data\\sample.bin","maxBytes":52428800}' --output-file .\received.bin --invoke-timeout 60000

dir.list

{ "path": "C:\\Data", "maxEntries": 200, "pageToken": "0" }. Returns entries, nextPageToken, path and binding. Page size caps at 5000. Children blocked by the current Sandbox policy are omitted, and paging counts only visible entries. A blocked target directory still returns a permission error. Optional preflightOnly, followSymlinks and shared identity fields.

dir.fetch

{ "path": "C:\\Data", "maxBytes": 16777216 }. Returns tarBase64, tarBytes, sha256, fileCount, entries and binding. Expanded archive data caps at 64 MiB; entry count caps at 5000. Optional preflightOnly, followSymlinks and shared identity fields.

file.write

{ "path": "C:\\Data\\sample.txt", "contentBase64": "YWJj", "overwrite": false }. Accepts canonical standard/base64url, padded or unpadded. Optional createParents, rejectHardlinks, expectedSha256, expectedCanonicalPath, expectedBinding, preflightOnly. Returns {ok,path,size,sha256,overwritten,binding}. No overwrite by default.

file.create

Requires path, sizeBytes, expectedSha256. Optional maxBytes (default 50 MiB), createParents, identity fields and preflightOnly. Preflight needs no channel; real creation streams messages of at most 1 MiB, waits for an ack after each, and sends an empty message for EOF. Returns {ok,path,size,sha256,status:"created",binding} when created. An existing target returns status:"exists" without size/hash fields and is not read back to verify content equality. Never overwrites.

winnode --command file.create --params '{"path":"C:\\Data\\new.bin"}' --input-file .\source.bin --invoke-timeout 60000

fs.listDir

Directory navigation, with optional { "path": "C:\\Data" }. Remote calls are Gateway-admin-gated; local calls use the existing MCP bearer. Neither grants elevation or bypasses contained data access. Children blocked by the current Sandbox policy are omitted; requesting a blocked directory itself still fails.

terminal.upload

{ "name": "sample.txt", "contentBase64": "YWJj" }. Requires canonical padded standard base64. Returns {path,size}. The raw node command stages an upload without a terminal session. Remote calls require genuine Gateway admin authorization. The app schedules retained cleanup; the same mode-selected worker scans and deletes only identity-owned upload data. New uploads use automatic private storage belonging to the current Companion profile, outside its settings and runtime-code folders. Downloads and the legacy upload-location setting receive no automatic grant. Contained ordinary commands can read all retained uploads in that profile after ownership verification, but cannot modify them through the automatic grant. Only upload/cleanup operations receive managed-storage write access. Explicit read-only/No access restrictions still apply, including an inherited read-only policy. This is profile-scoped sharing, not per-file or per-conversation isolation.

The app establishes only the exact private profile boundary as trusted metadata before launching the contained worker. It checks current policy and reserves cleanup ownership first. Uploaded bytes and cleanup still run inside the worker, without granting write access to the boundary's parent. Cancellation or launch failure can leave an owned empty boundary for later safe reuse. Unbound or unrecognized ownership requires review, not automatic adoption or deletion.

The committed transfer budget defaults to 50 MiB and cannot exceed 1024 MiB; valid existing settings remain effective. This command still has the tighter 16 MiB decoded unary limit. Retention remains bounded to 24 hours, 64 upload directories and 256 MiB. Cleanup of remembered legacy roots still requires their current folder permissions and ownership identity. A blocked cleanup is not a reason to retry a completed upload.

Error semantics: the six plugin commands retain the Gateway outer success envelope with inner {ok:false,code,message}. The two admin commands use outer errors. MCP converts typed semantic failure to isError:true; winnode exits 1. An explicit binary/create call without a channel returns DUPLEX_REQUIRED. See local framed transport for the optional authenticated lease protocol. It is not standard MCP streaming.

system.notify

Show a Windows toast notification.

{"title": "OpenClaw", "body": "string", "subtitle": "string", "sound": true}

Returns { "sent": true }. All fields optional except body in practice.

system.run

Execute canonical argv. Subject to the local exec approval policy at %APPDATA%\OpenClawTray\exec-approvals.json.

Supported Windows uses Microsoft.Mxc.Sdk 1.0.0 containment. There is no Off setting. Positively unsupported Windows instead runs approved argv uncontained, with a persistent Node Sandbox warning and disabled sandbox permission controls. File/network/clipboard/UI restrictions are not enforced there; approvals, deadline, bounded output and revalidation remain active. Missing SDK components, unknown/failed probes or native execution failures never downgrade. On supported Windows, unsupported/unavailable policy and stale authorization are tool errors (isError=true). Balanced reads the OS user profile and resolved personal/redirected folders; Open reads/writes the same scope. Neither grants a whole drive or other users. Projects outside that scope need explicit Custom grants. Readonly profile plus selected write children is supported. Volume roots are never granted, even readonly. Missing required locations block with diagnostics; optional unavailable OneDrive is not included. Protected OpenClaw settings, SSH, browser-profile and PSReadLine roots remain excluded in every scope. Explicit cwd must already be granted; omitted cwd uses private scratch. Settings affect new commands only. Pending requests revalidate before spawn. Cancellation dismisses approval, releases the prompt lock, and explicitly terminates the owned SDK process, including a late native launch.

{
  "command": ["executable", "arg", ...], // required
  "rawCommand": "string",                // optional display metadata
  "cwd":     "string",
  "timeoutMs": 30000
}

Shell behavior must be explicit in the argv, for example {"command":["cmd.exe","/d","/s","/c","echo hello"],"rawCommand":"echo hello"}. The gateway's exec host=node path performs this wrapping automatically. Non-empty custom env is rejected until environment values can be identity-bound and shown safely during approval.

Migration from the pre-V2 low-level contract

The V2 node boundary intentionally rejects string-form command with command-array-required. Update raw MCP, node.invoke, plugin, and direct winnode callers to send the shell transport explicitly:

// Before
{"command":"echo hello","shell":"cmd"}

// V2
{"command":["cmd.exe","/d","/s","/c","echo hello"],"rawCommand":"echo hello"}

PowerShell callers must likewise name powershell.exe or pwsh.exe and its -Command arguments explicitly. Remove custom env from the request; V2 rejects non-empty environments rather than approving an executable under hidden process configuration. Exited commands return { stdout, stderr, exitCode, timedOut, success, durationMs }. Retained output is bounded by UTF-8 bytes per stream, including any truncation marker, while discarded output continues to drain. Removing policy on exit does not undo writes to granted folders.

system.run.prepare

Pre-flight a system.run invocation. Same args as system.run. Returns the parsed plan (argv, cwd, rawCommand, agentId, sessionKey) without executing.

system.which

Resolve binary names to absolute paths.

{"bins": ["git", "node", "powershell"]}

Returns { "bins": { "git": "C:\\...", ... } }. Names not found are omitted.

system.execApprovals.get

No params. Returns the active V2 snapshot: { path, exists, hash, file: { version, defaults: { security, ask, askFallback, autoAllowSkills }, agents: { "<agentId>": { security, ask, askFallback, autoAllowSkills, allowlist: [{ id, pattern, lastUsedAt?, lastResolvedPath? }] } } } }. security is deny|allowlist|full; ask is off|on-miss|always|deny; askFallback is deny|allowlist|full. Socket credentials are never returned. Pass hash as baseHash when calling system.execApprovals.set.

system.execApprovals.set

Replace the full V2 file using compare-and-swap. baseHash is required and must equal the latest hash returned by system.execApprovals.get.

{
  "baseHash": "<hash-from-get>",
  "file": {
    "version": 1,
    "defaults": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": false
    },
    "agents": {
      "main": {
        "security": "allowlist",
        "ask": "on-miss",
        "askFallback": "deny",
        "autoAllowSkills": false,
        "allowlist": []
      }
    }
  }
}

Returns the updated snapshot. A remote update may preserve or remove existing allowlist grants, but it cannot add or change grants or set full access. Missing or stale hashes are rejected. This command changes future system.run authorization decisions. The winnode path is local loopback MCP, so no gateway scope applies. Remote operators must use the gateway exec.approvals.node.* control-plane methods, which are separately gated by gateway admin scope.

canvas.present

Open the WebView2 canvas window.

{
  "url":   "string",          // OR "html": "string"
  "html":  "string",
  "width": 800, "height": 600,
  "x": -1, "y": -1,           // -1 centers
  "title": "Canvas",
  "alwaysOnTop": false
}

Returns { "presented": true }.

canvas.hide

No params. Hides the canvas without destroying state.

canvas.navigate

{"url": "https://..."}    // also accepts file:// or local canvas paths

canvas.eval

{"script": "document.title"}    // also accepts "javaScript" or "javascript"

Returns the evaluated result.

canvas.snapshot

{"format": "png|jpeg", "maxWidth": 1200, "quality": 80}

Returns { format, base64 }.

canvas.a2ui.push

Render an A2UI v0.8 surface in the canvas. The canvas window opens automatically - no canvas.present required.

{
  "jsonl":     "string",   // OR jsonlPath
  "jsonlPath": "string",   // must live under %TEMP%
  "props":     {}           // optional
}

Returns { "pushed": true }. See A2UI grammar below.

canvas.a2ui.pushJSONL

Alias of canvas.a2ui.push. It uses the identical handler, size/line caps, and jsonl/jsonlPath contract. It exists for naming parity, not as a separate streaming path.

canvas.a2ui.reset

No params. Clears any rendered surfaces. Returns { "reset": true }.

canvas.a2ui.dump

No params. Returns the current surface graph for introspection. Read-all: this exposes every currently-rendered surface - operators should treat it as equivalent to a screenshot of every open A2UI surface.

canvas.caps

No params. Returns renderer capabilities (renderer, snapshot, a2ui version).

screen.snapshot

{
  "format": "png|jpeg", "maxWidth": 1920, "quality": 80,
  "monitor": 0, "screenIndex": 0,    // 0 = primary
  "includePointer": true
}

Returns { format, width, height, base64, image } (image is a data: URL). The first use requires remembered user consent. Every invocation displays a visible notification before screen capture begins.

screen.record

{
  "durationMs": 5000,         // required, max 300000
  "format": "mp4|webm",
  "monitor": 0, "screenIndex": 0,
  "maxWidth": 1920, "fps": 30
}

Returns { format, durationMs, base64 }.

camera.list

No params. Returns { cameras: [{ deviceId, name, isDefault }] }.

camera.snap

{"deviceId": "string", "format": "jpeg|png", "maxWidth": 1280, "quality": 80}

Returns { format, width, height, base64 }. deviceId defaults to system default camera. The first use requires remembered user consent. Every invocation displays a visible notification before camera capture begins.

camera.clip

{
  "deviceId": "string",       // optional
  "durationMs": 3000,         // required, max 60000
  "format": "mp4|webm",
  "maxWidth": 1280
}

Returns { format, durationMs, base64 }.

Speech-to-text (stt.*)

Local Whisper.net runs on this device - no audio leaves the box. The model is downloaded on first use; until then every stt.* call returns a clear error pointing the caller at the Voice Settings page. Privacy-sensitive: requires NodeSttEnabled in tray Settings.

stt.transcribe

Bounded fixed-duration mic capture + transcription.

{
  "maxDurationMs": 5000,      // required, > 0, max 30000
  "language": "en"            // optional BCP-47 tag or "auto" - falls back to SttLanguage setting
}

Returns { transcribed, text, durationMs, language, engineEffective: "whisper" }.

stt.listen

Mic capture with voice-activity detection. Returns when the user stops speaking or after timeoutMs. Result is the full silence-bounded utterance (all Whisper segments concatenated), not a partial first segment.

{
  "timeoutMs": 30000,         // optional, default 30000, range 1000..120000
  "language": "auto"          // optional BCP-47 tag or "auto"
}

Returns { text, language, durationMs, segments[{ text, startMs, endMs }], engineEffective: "whisper" }.

stt.status

Engine readiness. No params. Carries no PII (no transcript history, no language history, no device IDs, no model paths). Returns { engine: "whisper", readiness, modelDownloadProgress, isListenWithVadSupported, isBoundedTranscribeSupported } where readiness ∈ "ready" | "initializing" | "model-downloading" | "model-not-downloaded" | "unavailable".

Text-to-speech (tts.*)

Five providers - Kokoro (local neural via kokoro.cpp, default), Piper (local neural via Sherpa-ONNX), Windows built-in speech, ElevenLabs (cloud), and MiniMax (cloud). Provider + per-provider voice are configured in tray Settings. While Kokoro is the provider and TTS is enabled, the tray downloads the selected Kokoro voice pack in the background on unmetered connections; until it is ready, tts.status reports voice-not-downloaded and speech falls back to Windows.

tts.speak

Speak text aloud on the Windows node.

{
  "text": "string",           // required
  "provider": "kokoro|piper|windows|elevenlabs|minimax",  // optional; omit to use TtsProvider setting
  "voiceId": "string",        // optional, overrides the per-provider configured voice
  "model": "string",          // optional, cloud providers only
  "interrupt": false          // default false; true cuts off any in-progress playback
}

When provider is omitted and the configured provider isn't usable (no cloud API key, Kokoro voice pack or Piper voice not downloaded), the node falls back to Windows TTS so playback still happens. Explicit provider requests stay strict and do not silently reroute. Returns { spoken, provider, requestedProvider, fellBack, contentType, durationMs } where provider is the provider that actually spoke.

tts.status

TTS provider readiness. No params. Carries no PII (no voice ids, no key fragments, no device names). Returns { configuredProvider, effectiveProvider, willFallBack, providers[{ provider, readiness, isReady }] } where effectiveProvider is what would run now after fallback and readiness ∈ "ready" | "needs-api-key" | "needs-voice" | "voice-not-downloaded" | "unavailable". The configured/effective view reflects configured defaults only; explicit tts.speak provider requests stay strict and may not match the default snapshot.

Local model inference (ollama.*)

Runs against a separately installed Windows Ollama service (not the app-managed Local AI gateway provider). Any paired active gateway, local or remote, may invoke it once enabled. Requires NodeOllamaInferenceEnabled in tray Settings > Permissions (opt-in, default off).

ollama.models

List locally installed Ollama models. Read-only inventory - no prompt or chat content. No params. Returns { provider, models[{ name, size, modifiedAt, family, parameterSize, quantization, contextWindow, capabilities, loaded }] }.

ollama.chat

Send a single-turn chat prompt to a local Ollama model. Privacy and resource sensitive - sends prompt content to a locally running model and consumes CPU/GPU. Only one chat runs at a time per node; a concurrent call while one is in flight returns an error.

{
  "model": "string",          // required
  "prompt": "string",         // required, max 128000 chars
  "system": "string",         // optional, max 32000 chars
  "temperature": 0.7,         // optional, 0..2
  "maxTokens": 512,           // optional, default 512, max 8192
  "timeoutMs": 120000         // optional, default 120000, max 600000
}

Returns { provider, model, response, usage?: { promptTokens, completionTokens }, timings?: { loadMs, totalMs } }.

Newer gateways with the bundled Ollama plugin expose these commands through the node_inference agent tool. Older gateways can invoke them through the generic nodes tool after both exact command names are added to gateway.nodes.allowCommands. Feature-detect the node's effective commands; do not infer support from the gateway version.

App control (app.*)

Read-only and small write operations targeting the running tray. Used by the command palette and by automation that wants to drive the UI.

app.navigate

Navigate Workspace or the Settings companion to a specific page.

{"page": "workspace:home"}

Returns { navigated, page }. home and chat open Workspace chat; workspace:notifications opens Workspace notifications. Unprefixed routes such as sessions, settings, and connection open the Settings companion. Deprecated Workspace routes return Home. Unknown workspace: routes return a tool error before any window is opened or navigation is forwarded.

app.status

Current connection / node state. No params. Returns { connectionStatus, overallState, operatorState, nodeState, nodeConnected, nodePaired, nodePendingApproval, nodeError, gatewayVersion, sessionCount, nodeCount }. For agent-facing connection troubleshooting, prefer app.connection.status.

app.sessions

Active sessions, optionally filtered by agent.

{"agentId": "string"}        // optional

Returns array of { Key, Status, Model, AgeText, tokens }.

app.agents

List agents from the connected gateway. No params. Returns the raw agents JSON array.

app.nodes

List connected nodes and their capabilities. No params. Returns array of { DisplayName, NodeId, IsOnline, Platform, CapabilityCount }.

app.config.get

Read gateway configuration value at a dot-path.

{"path": "string"}           // optional; omit to fetch the full config tree

Returns the config subtree (or full config) as JSON.

app.settings.get

Read a local app setting by name.

{"name": "string"}           // required

Returns the setting value (type depends on the setting).

app.settings.set

Set a local app setting, persist it, and apply the same reconnect/reload behavior as saving settings in the app UI.

{"name": "string", "value": "string"}  // both required

Returns { name, value }; runtime apply failures surface as tool errors.

app.menu

Get tray menu state (status, session count, node count). No params. Returns array of menu items; the status item includes status, overallState, nodeState, and nodeError.

app.search

Search locally available navigation destinations without opening them or making Gateway requests. Settings results identify their destination rather than toggle anything. Message snippets are excluded.

{"query": "string"}          // required

Returns up to 10 { Title, Subtitle, Icon, Group, OpensDashboard, HasDashboardCounterpart }.

app.dashboard.url

Build the same gateway dashboard URL the tray opens.

{"path": "string"}           // optional

Returns { url, credentialSource, usesSharedGatewayToken, hasTokenQuery }.

App connection diagnostics and setup (app.connection.*)

Local MCP-only tools for connection diagnostics, setup, pairing approvals, and targeted reconnects. These tools are not advertised to the remote gateway node transport. Read-only diagnostics redact token values and expose credential presence/outcome only.

app.connection.status

Read-only connection diagnostics for agents and CLIs. No params. Returns: { schemaVersion, connectionState, effectiveMode, legacyConnectionStatus, gateway, protocol, operator, node, mcp, browserProxy, pendingActions, retry, diagnostics }.

The payload includes the active gateway id/name/url, operator and node role states, credential sources/statuses, MCP enabled/running/error state, browser proxy shared-token caveat, pending approval commands, retry hints inferred from recent diagnostics, and recent connection diagnostic events. effectiveMode reflects Settings mode (EnableNodeMode / EnableMcpServer); node.intended reflects the manager snapshot plus current Node mode setting. gateway.packageVersion is the installed Gateway npm package version reported by hello-ok; it is separate from the wire protocol. protocol reports the accepted Gateway wire protocol, the Windows-supported current/minimum/maximum values (currently 4/3/4), normalized compatibility (compatible, gateway_too_old, gateway_too_new, mismatch, or unknown), the operator/node source, available Gateway protocol expectations, and whether the condition is retryable. During an active mismatch, selectedProtocol comes only from that connection attempt and is otherwise null, even if cached Gateway self information remains available.

app.connection.gateways

Read-only saved gateway diagnostics. No params. Returns: { activeGatewayId, count, gateways[] }.

Each gateway includes id/name/url, active flag, local/v2 flags, lastConnected, credential presence booleans (hasSharedGatewayToken, hasBootstrapToken), browser-control port/caveat, and SSH tunnel metadata. Token values are never returned.

app.connection.applySetupCode

Apply a setup or QR code and connect the tray to that gateway.

{"setupCode": "string"}      // required

Returns { outcome, error, gatewayUrl, connected }. Side effects: creates or updates a gateway record, sets it active, persists credentials from the setup code, and asks GatewayConnectionManager to connect.

app.connection.connectSharedToken

Connect with a shared gateway token.

{
  "gatewayUrl": "string",    // required
  "token": "string"          // required
}

Returns { outcome, error, gatewayUrl, connected }. Side effects: creates or updates a gateway record, stores the shared token on that record, sets it active, and asks GatewayConnectionManager to connect.

app.connection.pendingApprovals

Read pending device/node pairing approvals from the connected gateway. No params. Returns { connected, error, totalPending, devicePending[], nodePending[] }.

app.connection.approveDevicePairing

Approve a pending device pairing request.

{"requestId": "string"}      // required; "id" alias accepted

Returns the refreshed pending approvals payload plus { decision }. Side effect: calls the connected operator client's device-pair approval RPC.

app.connection.rejectDevicePairing

Reject a pending device pairing request.

{"requestId": "string"}      // required; "id" alias accepted

Returns the refreshed pending approvals payload plus { decision }. Side effect: calls the connected operator client's device-pair rejection RPC.

app.connection.approveNodePairing

Approve a pending Windows node pairing or command-trust request.

{"requestId": "string"}      // required; "id" alias accepted

Returns the refreshed pending approvals payload plus { decision }. Side effect: calls the connected operator client's node-pair approval RPC.

app.connection.rejectNodePairing

Reject a pending Windows node pairing or command-trust request.

{"requestId": "string"}      // required; "id" alias accepted

Returns the refreshed pending approvals payload plus { decision }. Side effect: calls the connected operator client's node-pair rejection RPC.

app.connection.reconnect

Reconnect the active gateway through GatewayConnectionManager. No params. Returns { reconnected, error? }. Side effect: disconnects and reconnects the operator/node lifecycle for the active gateway.

app.connection.reconnectNode

Reconnect only the Windows node role for the active gateway through GatewayConnectionManager. No params. Returns { reconnected, error? }. Side effect: restarts node connection intent without changing the active gateway.

app.chat.snapshot

Read the current native chat snapshot for local automation and diagnostics. READ-ALL: returns recent chat text from the selected timeline and outgoing queue text.

{"threadId": "string"}       // optional; "sessionKey" alias also accepted

Returns { connectionStatus, defaultThreadId, composeTarget, threads, queue, selectedTimeline }.

app.chat.send

Send a message through the same native chat provider used by the Chat UI.

{
  "message": "string",       // required
  "threadId": "string"       // optional; defaults to compose/default thread
}

Returns { sent, threadId, entryCount, turnActive, error? }.

app.chat.reset

Reset the target chat session through the gateway sessions.reset path.

{"threadId": "string"}       // optional; "sessionKey" alias also accepted

When threadId/sessionKey is omitted this resets the current compose/default thread, which usually means the active chat session. Returns { reset, threadId, error? }.

app.chat.queue.list

List native chat outgoing queue entries. READ-ALL: returns queued message text.

{"threadId": "string"}       // optional; "sessionKey" alias also accepted

When threadId/sessionKey is omitted this returns all queued threads. Returns: { defaultThreadId, requestedThreadId, totalCount, selectedThread, threads } where each thread has { threadId, count, messages }, and each message has { id, text, createdAt, sendState, errorText, canCancel }. Queue message IDs are ephemeral UI/provider IDs; read them from the current app.chat.queue.list or app.chat.snapshot response and do not cache them across app lifetimes.

app.chat.queue.cancel

Cancel/remove one native chat outgoing queue entry before it is sent.

{
  "queuedMessageId": "string", // required; from the current app.chat.queue.list or app.chat.snapshot queue
  "threadId": "string"         // required; "sessionKey" alias also accepted
}

Only Queued and Failed entries can be removed. Sending entries may already have reached the gateway and are not canceled. Returns { canceled, threadId, queuedMessageId, remainingCount, error? }.

Location (location.*)

location.get

Get the device's current geographic location.

{
  "accuracy": "default|high",  // optional, default "default"
  "maxAge": 30000,             // ms; return a cached fix if younger than this
  "locationTimeout": 10000     // ms; fail if no fix within this time
}

Returns { latitude, longitude, accuracy (meters), timestamp (ms) }. Requires the Location capability to be enabled and OS location permission granted to the app. The first use also requires remembered OpenClaw consent. Every invocation displays a visible notification before location access begins. Error LOCATION_PERMISSION_REQUIRED if the user has not granted location access.

Device (device.*)

device.info

Get static device metadata. No params. Returns { deviceName, modelIdentifier, systemName, systemVersion, appVersion, appBuild, locale }.

device.status

Get live system health data.

{
  "sections": ["os","cpu","memory","disk","battery"]  // optional; omit for all
}

Returns a map with collectedAt (ISO-8601 string) and one key per section. Each section may contain { error: "collection failed" } if data was unavailable. Legacy fields always present: thermal, storage, network, uptimeSeconds.

Battery sub-object: { level, state ("charging"|"discharging"|"unknown"), lowPowerModeEnabled }.

Privacy note: device.status reveals battery level, network type, and disk usage. Agents should request only the sections they need.

Browser control proxy (browser.*)

browser.proxy

Proxy an HTTP request to the local OpenClaw browser control host (Chrome DevTools Protocol server) running on gateway port + 2.

{
  "path": "/json/list",        // required - local control path
  "method": "GET",             // optional, default GET; allowed: GET|POST|DELETE
  "body": {},                  // JSON object, for POST/DELETE
  "query": {},                 // appended as query-string params
  "profile": "Default",        // optional browser profile name
  "timeoutMs": 20000           // optional, max 120000
}

Returns { result, files? } - files is an array of { path, base64, mimeType } if the response referenced local file paths.

Requires the gateway URL to have an explicit port (e.g. ws://localhost:8080). The browser control host must be running locally on 127.0.0.1:<gatewayPort + 2>.

Listed only when BrowserProxyActivation is RegistrationBlock.None: the toggle is on, a gateway client is attached, the shared gateway token is set, and the browser endpoint is verified. MCP-only startup (EnableMcpServer true, EnableNodeMode false) does not attach a gateway client, so this command stays off tools/list and the call returns Unknown tool: browser.proxy.

---

A2UI v0.8 grammar (for canvas.a2ui.push)

The jsonl argument is a string of newline-separated JSON-RPC-like messages. Three message kinds are supported. createSurface and v0.9 messages are rejected.

Message kinds

// 1. Declare components for a surface (creates the surface if new).
{"surfaceUpdate": {
  "surfaceId": "string",
  "components": [ ComponentDef, ... ]
}}

// 2. Pick the root component and (optionally) styles. Send AFTER surfaceUpdate.
{"beginRendering": {
  "surfaceId": "string",
  "root": "componentId",
  "styles": { "primaryColor": "#FF6F61", "radius": 8.0, "spacing": 12.0 }
}}

// 3. Seed/update the data model bound by Path() values.
{"dataModelUpdate": {
  "surfaceId": "string",
  "contents": [
    {"key": "headline", "valueString":  "Hi"},
    {"key": "agreed",   "valueBoolean": false},
    {"key": "volume",   "valueNumber":  20.0}
  ]
}}

// 4. (Optional) Remove a surface.
{"deleteSurface": {"surfaceId": "string"}}

ComponentDef

{"id": "uniqueId", "component": {"<ComponentName>": { ...props }}}

Value bindings (inside a component prop)

Form	Meaning
{"literalString": "x"}	Literal string
{"path": "/key"}	Read/write the data model
Plain string "x"	Component-id reference (e.g. child)
Plain number / bool	Used directly for numeric/bool props

Component catalog

Category	Name	Notable props
Container	Row	children: {explicitList: ["id", ...]}
Container	Column	children: {explicitList: ["id", ...]}
Container	List	children, dataBinding
Container	Card	child: "id"
Container	Tabs	tabItems: [{title, child}]
Container	Modal	child
Container	Divider	`axis: "horizontal"
Display	Text	text: Lit/Path, `usageHint: "h1
Display	Image	url: Lit/Path, `fit: "contain
Display	Icon	name: Lit("settings"|...)
Display	Video	url, autoplay, controls
Display	AudioPlayer	url, controls
Interactive	Button	child, primary: bool, action: {name, ...context}
Interactive	CheckBox	label: Lit/Path, value: Path
Interactive	TextField	value: Path, `textFieldType: "shortText
Interactive	DateTimeInput	value: Path, `mode: "date
Interactive	MultipleChoice	value: Path, options: [{value, label}]
Interactive	Slider	value: Path, minValue, maxValue, step

Lit/Path = the value-binding shapes from the previous section.

Minimal "hello world" payload

{"surfaceUpdate":{"surfaceId":"hello","components":[{"id":"helloText","component":{"Text":{"text":{"literalString":"Hello, world!"},"usageHint":"h1"}}}]}}
{"beginRendering":{"surfaceId":"hello","root":"helloText"}}

Pass this as the jsonl value (a single JSON string with \n between messages).

---

Token-efficient call patterns

1. Skip --node / --idempotency-key - they're ignored locally; including them just costs tokens. --idempotency-key triggers a stderr warning.
2. Omit --params when the command takes no args (camera.list, canvas.hide, canvas.a2ui.reset, canvas.a2ui.dump, canvas.caps, system.execApprovals.get).
3. Large A2UI payloads - write the JSONL to a file under the system temp directory and pass {"jsonlPath": "<path>"}. The capability rejects paths outside %TEMP%. Or pass --params @<path> to load the entire JSON argument object from disk.
4. Big binary results (snapshots, captures) - output is base64 in stdout. Pipe to a file (> capture.json) instead of letting the agent read it inline.
5. Errors are exit-code-driven - check $LASTEXITCODE (or $? in bash) first, then read stderr only on non-zero. Exit 2 = your call is malformed.
6. Debug with --verbose, not by sharing transcripts - without --verbose the CLI shows only the first line of an HTTP error body and redacts long base64url runs. With --verbose it shows the full sanitized body. Treat any verbose output as containing potentially sensitive paths or partial command output before pasting it elsewhere.

What's NOT exposed

• Pairing / device approval (gateway concept; doesn't apply locally).
• chat.send, sessions.list, usage.list, node.list - these belong to the operator-side OpenClaw.Cli.exe, not winnode.exe.
• Idempotency. The gateway de-dupes retries against --idempotency-key; local MCP does not. Retrying a system.run / system.notify / canvas.present call after a transient failure can double-execute the side effect.
• Wildcards in --command. The MCP server has an explicit allowlist; unknown commands return Unknown tool: <name>.