clawsy

---

What It Does

Clawsy sits in your menu bar and acts as a secure bridge between your Mac and your OpenClaw agent. Your agent can see your screen, read your clipboard, manage files, and track its own tasks — all with your explicit approval.

Nothing happens behind your back. Every screenshot, clipboard read, or file write requires your permission.

---

Requirements

• macOS 14+ (Sonoma / Sequoia), Apple Silicon or Intel
• OpenClaw instance — running and accessible from your Mac (github.com/openclaw/openclaw)

---

Getting Started

Recommended: Let Your Agent Handle It

Send this to your OpenClaw agent:

Install the Clawsy macOS companion: clawhub install clawsy — then read the SKILL.md and follow the IMMEDIATE ACTION section.

Your agent installs the skill, reads the setup instructions, and sends you the download link and setup code in one message.

---

Already Have Clawsy Installed?

If you downloaded Clawsy separately:

1. Launch Clawsy and click Add Host
2. A setup prompt is copied to your clipboard automatically
3. Send the prompt to your agent via any channel (chat, Telegram, Slack, ...)
4. Your agent responds with a setup code — paste it back into Clawsy

Done. Clawsy connects, and the agent receives the full skill reference automatically.

---

Manual Setup (Advanced)

For full manual control over every setting:

1. Download Clawsy.app.zip from the latest release
2. Unzip, drag to /Applications, remove quarantine:

   xattr -cr /Applications/Clawsy.app
   

3. Launch Clawsy — the onboarding assistant walks you through permissions
4. Open Settings → enter Gateway Host, Port (18789), and Token
5. Approve the pairing request on your server:

   openclaw devices list
   openclaw devices approve <requestId>
   

The agent receives the full skill reference automatically after connection.

---

Multi-Host Support

Clawsy can connect to multiple OpenClaw gateways simultaneously. Each host gets:

• Its own connection, token, and device pairing
• A color-coded label in the host switcher bar
• An isolated shared folder (no cross-contamination)
• Independent Mission Control task tracking

To add a host: Click the + button in the Clawsy header or go to Settings → Add Host.

Use this when you run separate OpenClaw instances (e.g., work vs. personal, dev vs. prod).

---

Features at a Glance

Feature	Description
Screenshot & Camera	Full-screen or area screenshots, camera snap with preview
Clipboard Sync	Push/pull clipboard content between Mac and agent
File Sync	Shared folder with bidirectional file transfer
FinderSync Extension	Right-click folders in Finder to configure .clawsy rules
Share Extension	Share from any app directly to your agent
Mission Control	Real-time task view of your agent's activity
Multi-Host	Connect to multiple OpenClaw gateways with color-coded switching
Auto-Update	Background update checks with one-click install
SSH Tunnel Fallback	Automatic encrypted tunnel when direct connection fails
Quick Send	Global hotkey (⌘⇧K) to message your agent from anywhere
.clawsy Rules	File-event automation with glob matching and agent/notify actions

---

Key Features

⚡ Quick Send

A global hotkey (⌘⇧K) opens a floating panel anywhere on your Mac. Type a message to your agent without switching apps.

📋 Clipboard, Screen & Camera

Push your clipboard to the agent silently. Let the agent request a screenshot or camera frame. Every request goes through a permission dialog — allow once, for an hour, or deny.

📁 Shared Folder & Automation Rules

A local folder syncs with your agent's workspace. Drop a .clawsy rule file into any subfolder to define triggers — "when a PDF is added, summarize it". Right-click any folder in Finder to configure rules via the FinderSync Extension.

🔗 Share Extension

Share files, text, or URLs from any macOS app directly to your agent via the system Share menu.

📊 Mission Control

See what your agent is doing, in real time.

Agents push task status via WebSocket. Clawsy shows progress bars, task names, and status text instantly.

🔒 SSH Tunnel Fallback

Can't reach your gateway directly? Clawsy automatically falls back to an SSH tunnel — encrypted, zero-config if you have ~/.ssh keys set up.

🔒 You Stay in Control

Every file write, screenshot, or clipboard read requires your approval.

---

Settings

Open the Clawsy menu → Settings:

Setting	Description
Gateway Host	Your OpenClaw server hostname or IP
Gateway Port	Default: 18789
Token	Your OpenClaw auth token
SSH Fallback	Auto-tunnels via SSH if direct connection fails
Shared Folder	Local folder synced with your agent (default: ~/Documents/Clawsy)

---

Agent Integration

Once paired, your agent uses the nodes tool to interact with Clawsy:

# Take a screenshot
nodes(action="invoke", invokeCommand="screen.capture")

# Read the clipboard
nodes(action="invoke", invokeCommand="clipboard.read")

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

# Camera snap
nodes(action="invoke", invokeCommand="camera.snap",
      invokeParamsJson='{"facing": "front"}')

# List files in shared folder
nodes(action="invoke", invokeCommand="file.list",
      invokeParamsJson='{"path": "."}')

# Read a file
nodes(action="invoke", invokeCommand="file.get",
      invokeParamsJson='{"name": "report.pdf"}')

# Write a file
nodes(action="invoke", invokeCommand="file.set",
      invokeParamsJson='{"name": "notes.txt", "content": "<base64>"}')

# Move, copy, rename files
nodes(action="invoke", invokeCommand="file.move",
      invokeParamsJson='{"source": "old.txt", "destination": "new.txt"}')
nodes(action="invoke", invokeCommand="file.copy",
      invokeParamsJson='{"source": "a.txt", "destination": "b.txt"}')
nodes(action="invoke", invokeCommand="file.rename",
      invokeParamsJson='{"path": "old-name.txt", "newName": "new-name.txt"}')

# File info and batch operations
nodes(action="invoke", invokeCommand="file.stat",
      invokeParamsJson='{"path": "report.pdf"}')
nodes(action="invoke", invokeCommand="file.exists",
      invokeParamsJson='{"path": "report.pdf"}')
nodes(action="invoke", invokeCommand="file.batch",
      invokeParamsJson='{"ops": [{"op": "copy", "source": "a.txt", "destination": "b.txt"}]}')

Available commands: screen.capture, clipboard.read, clipboard.write, camera.list, camera.snap, file.list, file.get, file.set, file.get.chunk, file.set.chunk, file.move, file.copy, file.rename, file.stat, file.exists, file.batch, file.delete, file.rmdir, file.mkdir, location.get

Full command reference and agent integration: SKILL.md

---

Build from Source

git clone https://github.com/iret77/clawsy.git
cd clawsy
./build.sh
# → Clawsy.app lands in .build/app/

Requires Swift 5.9+ (Xcode Command Line Tools). CI builds run automatically on every tagged release via GitHub Actions.

---

License

MIT — see LICENSE.