| name | clawsy |
| version | 1.0.4 |
| description | Clawsy is a native macOS companion app that gives your OpenClaw agent eyes and hands on the user's Mac — screenshots, clipboard, camera, files, location, and live Mission Control. Connects via WebSocket (SSH fallback available). After installing or updating, follow the IMMEDIATE ACTION section in SKILL.md to send the user their setup code.
|
| metadata | {"openclaw":{"emoji":"🐱","postInstall":[{"command":"python3 -c \"import json,pathlib; c=json.loads(pathlib.Path.home().joinpath('.openclaw/gateway.json').read_text()); h=c.get('host','localhost');t=c.get('authToken',''); print(f'CLAWSY-SETUP\\nhost: {h}\\ntoken: {t}')\"","label":"Read gateway config for Clawsy setup code"}],"postInstallMessage":"Clawsy skill installed. Now send the user the setup instructions from SKILL.md (section \"IMMEDIATE ACTION AFTER INSTALL\") including the download link and the setup code printed above. Do NOT just say \"installed\".\n"}} |
Clawsy Skill — Agent Reference
Platform: macOS 14+ (Sonoma / Sequoia), Apple Silicon + Intel
Download: https://github.com/iret77/clawsy/releases/latest
IMMEDIATE ACTION AFTER INSTALL
After installing this skill, you must send the user their setup instructions.
Do not just reply "installed" or "done".
- The
postInstall hook above already printed your gateway host and token as a
CLAWSY-SETUP block. If not, read them manually:
cat ~/.openclaw/gateway.json | python3 -c "import json,sys;c=json.load(sys.stdin);print('host:', c.get('host','localhost'));print('token:', c.get('authToken',''))"
- Send the user everything in one message:
Clawsy Setup
- Download Clawsy (free, macOS 14+): https://github.com/iret77/clawsy/releases/latest
- Unzip, drag to /Applications, run
xattr -cr /Applications/Clawsy.app, launch.
- Click "Add Host" and paste this setup code:
CLAWSY-SETUP
host: <actual hostname>
token: <actual token>
Replace the placeholders with the real values. Do not send placeholders.
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?
⚠️ Node ID freshness — read this first.
The Clawsy Node ID changes whenever the user re-pairs the Mac (macOS reinstall,
new device, manual reset). Never cache it. Any Node ID you find in a local
cheat sheet (TOOLS.md, AGENTS.md, prior notes, hard-coded constants) is
presumed stale and must not be used to invoke a command.
The only sources of truth are, in order:
nodes(action="status") — always call this first.- The
[clawsy:connected] message in session clawsy-inbox (Clawsy posts it
on every connect; it contains live node_id, platform, and capability list).
- The auto-maintained
## Clawsy Integration block in your memory.md
(Clawsy rewrites it on every connect).
If a Clawsy call fails with "node offline" or "node not found", do not give up
— re-run nodes(action="status") to get the current Node ID before telling the
user Clawsy is down.
nodes(action="status")
- Connected: Use any command from the reference below.
- Not connected / No node found: You must run the First-Time Setup now. Check if the user already has Clawsy installed. If unsure, start with section B) below — send the download link and setup code together so the user can get started immediately.
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 (Most Common Path)
Look up your gateway host and token, then send everything in one message so
the user can get started right away:
Clawsy Setup
- Download Clawsy (free, macOS 14+): https://github.com/iret77/clawsy/releases/latest
- Unzip, drag to /Applications, run
xattr -cr /Applications/Clawsy.app, launch.
- Click "Add Host" and paste this setup code:
CLAWSY-SETUP
host: <your gateway hostname or IP>
token: <your gateway auth token>
Replace the placeholders with actual values before sending (see "How to find
the values" above). The user should not have to come back and ask for more info.
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
| Command | Approval | Description |
|---|
screen.capture | User approval | Capture the full screen or selected area. Returns {format, base64} |
camera.snap | User approval | Take a photo from the Mac camera. Params: deviceId (optional). Returns {format, base64} |
camera.list | Auto | List available cameras. Returns [{id, name}] |
Clipboard
| Command | Approval | Description |
|---|
clipboard.read | User approval | Read current clipboard text |
clipboard.write | Auto | Write text to clipboard. Params: {text} |
Location
| Command | Approval | Description |
|---|
location.get | Auto | Get device GPS location. Returns {latitude, longitude, accuracy, locality, country, ...}. 10s timeout. |
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.
All file paths are passed as subPath — a path relative to the shared
folder root (e.g. "notes/report.pdf"). There are no aliases; subPath is
the only accepted parameter name.
| Command | Params | Description |
|---|
file.list | subPath?, recursive? | List files. recursive: true walks subdirectories (max depth 5) |
file.get | subPath | Read file, returns base64 content |
file.set | subPath, content (base64) | Write file (≤ 200 KB — use file.set.chunk for larger) |
file.stat | subPath | File metadata: size, dates, type. Supports glob |
file.exists | subPath | Returns {exists, isDirectory} |
file.mkdir | subPath | Create directory (with intermediate parents) |
file.delete | subPath | Delete file or directory |
file.rmdir | subPath | Delete directory (alias for file.delete) |
file.move | source, destination | Move/rename file. Supports glob in source |
file.copy | source, destination | Copy file. Supports glob in source |
file.rename | subPath, newName | Rename file (name only, same directory) |
file.checksum | subPath | SHA256 hash of file |
file.batch | ops[] | Execute multiple operations sequentially (see below) |
file.get.chunk | subPath, chunkIndex, chunkSizeBytes? | Read chunk of large file (default 350 KB) |
file.set.chunk | subPath, chunk (base64), chunkIndex, totalChunks | Write chunk; assembles on final chunk |
file.batch Operations
nodes(action="invoke", invokeCommand="file.batch",
invokeParamsJson='{"ops": [
{"op": "mkdir", "subPath": "output"},
{"op": "copy", "source": "template.txt", "destination": "output/report.txt"},
{"op": "delete", "subPath": "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 files larger than ~200 KB of
base64 payload (≈ 150 KB raw), use chunked transfer. file.set will reject
single-shot writes above that limit — if in doubt, chunk.
Upload (agent to Mac):
for i, chunk_b64 in enumerate(chunks_b64):
nodes(action="invoke", invokeCommand="file.set.chunk",
invokeParamsJson=(
f'{{"subPath":"large.pdf","chunk":"{chunk_b64}",'
f'"chunkIndex":{i},"totalChunks":{len(chunks_b64)}}}'))
Download (Mac to agent):
stat = nodes(action="invoke", invokeCommand="file.stat",
invokeParamsJson='{"subPath":"large.pdf"}')
for i in range(chunk_count):
chunk = nodes(action="invoke", invokeCommand="file.get.chunk",
invokeParamsJson=f'{{"subPath":"large.pdf","chunkIndex":{i}}}')
Invoking Commands
Use the nodes tool. Clawsy registers as a node with platform="macos".
nodes(action="invoke", invokeCommand="screen.capture")
nodes(action="invoke", invokeCommand="clipboard.read")
nodes(action="invoke", invokeCommand="clipboard.write",
invokeParamsJson='{"text": "Hello from agent"}')
nodes(action="invoke", invokeCommand="camera.snap")
nodes(action="invoke", invokeCommand="camera.list")
nodes(action="invoke", invokeCommand="file.list")
nodes(action="invoke", invokeCommand="file.list",
invokeParamsJson='{"subPath": "docs/", "recursive": true}')
nodes(action="invoke", invokeCommand="file.get",
invokeParamsJson='{"subPath": "report.pdf"}')
nodes(action="invoke", invokeCommand="file.set",
invokeParamsJson='{"subPath": "output.txt", "content": "<base64>"}')
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
| Type | Contains | Triggered by |
|---|
quick_send | content (text) + telemetry | User presses Cmd+Shift+K |
screenshot | Image data | screen.capture result / user-initiated |
clipboard | Text content | clipboard.read result |
camera | Image data | camera.snap result |
file_rule | File path + rule info | .clawsy rule trigger |
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
| Situation | Action |
|---|
sessions_send times out | Normal. Event is delivered. Do not retry. |
No node with platform="macos" | Clawsy not connected. Skip Clawsy actions silently. |
invoke returns denied | User denied the request. Respect it. Do not re-ask. |
invoke returns sandbox_violation | Path escapes shared folder. Fix the path. |
invoke returns timeout | Command took >30s. Retry once if appropriate. |
| Node disconnects mid-task | Mission Control clears automatically. No cleanup. |
AUTH_TOKEN_MISMATCH | Clawsy auto-recovers. Wait for reconnection. |
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.
| Permission | Required for | Where |
|---|
| Screen Recording | screen.capture | System Settings > Privacy > Screen Recording |
| Camera | camera.snap | System Settings > Privacy > Camera |
| Accessibility | Global hotkeys (Cmd+Shift+K) | System Settings > Privacy > Accessibility |
| Notifications | Desktop alerts | System Settings > Notifications > Clawsy |
| FinderSync Extension | Finder right-click menu | System Settings > Extensions > Finder |
| Share Extension | "Send to Agent" in Share menu | Automatic when app is in /Applications |
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
| You want to... | Use |
|---|
| See user's screen | screen.capture |
| Read what user copied | clipboard.read |
| Give user text to paste | clipboard.write |
| See what's in front of the user | camera.snap |
| Exchange files with user | file.get / file.set via shared folder |
| Transfer large files (>200KB) | file.get.chunk / file.set.chunk |
| Batch file operations | file.batch |
| Know where user is | location.get |
| Show user what you're working on | agent.status via Mission Control |
| Respond to user's quick message | Read quick_send from clawsy-service |
| React to file drops in shared folder | .clawsy rules (file_added trigger) |
