clawsy

# 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". 1. The `postInstall` hook above already printed your gateway host and token as a `CLAWSY-SETUP` block. If not, read them manually: ```bash 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',''))" ``` 2. Send the user **everything in one message**: > **Clawsy Setup** > > 1. Download Clawsy (free, macOS 14+): https://github.com/iret77/clawsy/releases/latest > 2. Unzip, drag to /Applications, run `xattr -cr /Applications/Clawsy.app`, launch. > 3. 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:** > 1. `nodes(action="status")` — always call this first. > 2. The `[clawsy:connected]` message in session `clawsy-inbox` (Clawsy posts it > on every connect; it contains live `node_id`, `platform`, and capability list). > 3. 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. ```python nodes(action="status") # Look for a node with platform="macos" and connected=true # Use the node_id from this live result — never from any cached file. ``` - **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: ```bash 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** > > 1. Download Clawsy (free, macOS 14+): https://github.com/iret77/clawsy/releases/latest > 2. Unzip, drag to /Applications, run `xattr -cr /Applications/Clawsy.app`, launch. > 3. 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`: ```json { "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 ```python 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):** ```python # Split raw bytes into ~150 KB pieces, base64-encode each, then send: 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)}}}')) # The final chunk triggers assembly; intermediate chunks return # {"status":"chunk_received","chunkIndex":i}. ``` **Download (Mac to agent):** ```python stat = nodes(action="invoke", invokeCommand="file.stat", invokeParamsJson='{"subPath":"large.pdf"}') # Calculate chunk count from stat.size (default chunk size 358400 bytes), then: for i in range(chunk_count): chunk = nodes(action="invoke", invokeCommand="file.get.chunk", invokeParamsJson=f'{{"subPath":"large.pdf","chunkIndex":{i}}}') # Each response includes base64 "content", "chunkIndex", "totalChunks", "totalBytes". ``` --- ## Invoking Commands Use the `nodes` tool. Clawsy registers as a node with `platform="macos"`. ```python # 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}')