Clawsy Skill — Agent Reference

Platform: macOS 14+ (Sonoma / Sequoia), Apple Silicon + Intel Download: https://github.com/iret77/clawsy/releases/latest

---

Sub-Agent Propagation (MANDATORY)

When spawning sub-agents, you must include a Clawsy context block so they can report progress and use Clawsy capabilities. Copy this verbatim into every sub-agent system prompt:

## Clawsy — macOS Companion
A Clawsy node (platform="macos") is connected. You can:
- Take screenshots: nodes(action="invoke", invokeCommand="screen.capture")
- Read clipboard: nodes(action="invoke", invokeCommand="clipboard.read")
- Write clipboard: nodes(action="invoke", invokeCommand="clipboard.write", invokeParamsJson='{"text":"..."}')
- Read/write files in shared folder: file.get, file.set, file.list, etc.
- Get location: nodes(action="invoke", invokeCommand="location.get")

Report progress after each significant step:
sessions_send(sessionKey="clawsy-service", timeoutSeconds=3,
  message='{"kind":"agent.status","payload":{"agentName":"<YOUR_LABEL>","title":"<STEP>","progress":<0.0-1.0>,"statusText":"<DETAILS>"}}')
Start at 0.05 — finish at 1.0. Timeout errors on sessions_send are normal; do not retry.

For full command reference, read the clawsy skill: skill(name="clawsy")

This applies to all sub-agents — current and future. A sub-agent that does not receive this block cannot report Mission Control status and will not know about Clawsy capabilities.

---

Quick Start — Is Clawsy Connected?

nodes(action="status")
# Look for a node with platform="macos" and connected=true

• Connected: Use any command from the reference below.
• Not connected: Skip Clawsy actions. Do not ask the user to "open Clawsy" — it runs automatically as a menu bar app.
• No Clawsy at all: See "First-Time Setup" below.

---

First-Time Setup

A) User Already Has Clawsy Installed

The user clicks "Add Host" in Clawsy. The app copies a setup prompt to the clipboard. The user sends it to you via any channel (Telegram, Slack, etc.).

When you receive the prompt, respond with the gateway connection details:

CLAWSY-SETUP
host: <gateway hostname or IP — no protocol, no port>
token: <gateway authentication token>

The user pastes your response into Clawsy. Done — host is created and connects.

How to find the values:

• host: The hostname or IP where the OpenClaw gateway runs.
• token: The authToken from your gateway config. Run cat ~/.openclaw/gateway.json | python3 -c "import json,sys;print(json.load(sys.stdin).get('authToken',''))" if unsure.

After pairing, a node with platform="macos" appears in nodes(action="status"). Approve if prompted:

openclaw nodes approve <requestId>

B) User Needs to Install Clawsy First

Send this message:

Download Clawsy (free, macOS 14+): https://github.com/iret77/clawsy/releases/latest Unzip, drag to /Applications, launch. Then click "Add Host" — the app will copy a prompt to your clipboard. Send it to me and I'll give you the setup code.

C) Auto-Setup (Server-Side Script)

If you prefer automated setup:

curl -sL https://raw.githubusercontent.com/iret77/clawsy/main/server/install.sh | bash

The script detects the network topology and sends a clawsy://pair?code=... link to the user. Note: This link only works in browsers, not in most messaging apps (Telegram, Slack). The clipboard-based flow (A) works everywhere.

---

setupState — Targeted Onboarding

When a Clawsy node connects, the hello payload includes setupState:

{
  "setupState": {
    "sharedFolderConfigured": true,
    "sharedFolderPath": "~/Documents/Clawsy",
    "finderSyncEnabled": false,
    "accessibilityGranted": false,
    "screenRecordingGranted": true,
    "firstLaunch": false
  }
}

Read it from clawsy-service session history. If any permissions are missing, tell the user specifically what to enable — don't send a generic list.

---

Command Reference

Screen & Camera

Clipboard

Location

File Operations

All file operations are auto-approved and sandboxed to the configured shared folder (default ~/Documents/Clawsy). Paths are relative to the shared folder root.

file.batch Operations

nodes(action="invoke", invokeCommand="file.batch",
  invokeParamsJson='{"ops": [
    {"op": "mkdir", "name": "output"},
    {"op": "copy", "source": "template.txt", "destination": "output/report.txt"},
    {"op": "delete", "name": "temp.log"}
  ]}')

Supported op values: copy, move, delete, mkdir, rename. Returns per-operation results with ok status for each.

Large File Transfers (> 200 KB)

The gateway has a ~512 KB payload limit. For large files, use chunked transfer:

Upload (agent to Mac):

# Split file into ~150KB base64 chunks
for i, chunk in enumerate(chunks):
    nodes(action="invoke", invokeCommand="file.set.chunk",
      invokeParamsJson=f'{{"name":"large.pdf","chunk":"{chunk}","index":{i},"total":{len(chunks)}}}')

Download (Mac to agent):

stat = nodes(action="invoke", invokeCommand="file.stat",
  invokeParamsJson='{"path":"large.pdf"}')
# Calculate chunk count from stat.size, then:
for i in range(chunk_count):
    chunk = nodes(action="invoke", invokeCommand="file.get.chunk",
      invokeParamsJson=f'{{"name":"large.pdf","index":{i}}}')

---

Invoking Commands

Use the nodes tool. Clawsy registers as a node with platform="macos".

# Screenshot
nodes(action="invoke", invokeCommand="screen.capture")

# Clipboard
nodes(action="invoke", invokeCommand="clipboard.read")
nodes(action="invoke", invokeCommand="clipboard.write",
  invokeParamsJson='{"text": "Hello from agent"}')

# Camera
nodes(action="invoke", invokeCommand="camera.snap")
nodes(action="invoke", invokeCommand="camera.list")

# Files
nodes(action="invoke", invokeCommand="file.list")
nodes(action="invoke", invokeCommand="file.list",
  invokeParamsJson='{"subPath": "docs/", "recursive": true}')
nodes(action="invoke", invokeCommand="file.get",
  invokeParamsJson='{"name": "report.pdf"}')
nodes(action="invoke", invokeCommand="file.set",
  invokeParamsJson='{"name": "output.txt", "content": "<base64>"}')

# Location
nodes(action="invoke", invokeCommand="location.get")

---

Mission Control (MANDATORY)

When Clawsy is connected, you must send status events so the user sees what you're doing. This is not optional.

agent.info — Identity (send on session start + every heartbeat)

sessions_send(sessionKey="clawsy-service", timeoutSeconds=3,
  message='{"kind":"agent.info","payload":{"agentName":"YourName","model":"claude-opus-4-6","updatedAt":"2026-03-29T12:00:00Z"}}')

TTL is 45 minutes. Resend every heartbeat to stay visible.

agent.status — Task Progress (send during active work)

sessions_send(sessionKey="clawsy-service", timeoutSeconds=3,
  message='{"kind":"agent.status","payload":{"agentName":"YourName","title":"Building feature X","progress":0.5,"statusText":"Compiling sources..."}}')

• progress: 0.0 to 1.0. At 1.0, task disappears after 10 seconds.
• Timeout errors are normal. The event is still delivered. Do not retry.

HEARTBEAT.md Snippet

Add this to your HEARTBEAT.md:

## Clawsy (every heartbeat)
If clawsy-service session exists:
sessions_send(sessionKey="clawsy-service", timeoutSeconds=3,
  message='{"kind":"agent.info","payload":{"agentName":"<NAME>","model":"<MODEL>","updatedAt":"<ISO-UTC>"}}')
If actively working, also send agent.status with current task + progress.

---

Incoming Data — clawsy-service Session

Push data from Clawsy arrives in the clawsy-service session, not in the main chat.

sessions_history(sessionKey="clawsy-service", limit=10)

Envelope Types

Quick Send Telemetry

{
  "clawsy_envelope": {
    "type": "quick_send",
    "content": "User's message",
    "telemetry": {
      "deviceName": "MacBook Pro",
      "batteryLevel": 0.75,
      "isCharging": true,
      "thermalState": 0,
      "activeApp": "Safari",
      "moodScore": 70,
      "isUnusualHour": false
    }
  }
}

Hints: thermalState > 1 = overheating, batteryLevel < 0.2 = low battery, moodScore < 40 = user may be stressed, isUnusualHour = late/early work.

---

Shared Folder & .clawsy Rules

.clawsy Manifest Files

Folders within the shared directory can contain a .clawsy manifest for automation rules. Users configure these via Finder right-click menu.

{
  "version": 1,
  "folderName": "Projects",
  "rules": [
    {
      "trigger": "file_added",
      "filter": "*.pdf",
      "action": "send_to_agent",
      "prompt": "Summarize this document"
    }
  ]
}

• Triggers: file_added, file_changed, manual
• Filters: Glob patterns (*.pdf, *.mov, *)
• Actions: send_to_agent, notify

Rule events arrive in clawsy-service as file_rule envelopes.

---

Error Handling

---

macOS Permissions

These are on the user's side. If a capability doesn't work, point them to the specific setting — don't list everything.

---

Connection Architecture

Mac (Clawsy) ──── WSS ────> OpenClaw Gateway (port 18789)
                              SSH tunnel as fallback

• Primary: Direct WebSocket. Setup code contains gateway host + token.
• SSH fallback: User configures in Settings when direct WSS is unreachable.
• Auth: Server token > device token (Ed25519, persisted per host).
• Multi-host: Clawsy can connect to multiple gateways simultaneously. Each host has its own connection, shared folder, and color-coded label.

---

When to Use What