Clawsy

Clawsy — macOS Companion App

Clawsy verbindet den OpenClaw-Agenten mit dem Mac des Users über einen sicheren SSH-WebSocket-Tunnel.

Download: https://github.com/iret77/clawsy/releases/latest
Aktuelle Version: v0.4.17+
Plattform: macOS 14+ (Sequoia/Sonoma), Apple Silicon + Intel

Schnellstart für neue OpenClaw-Instanzen

1. User lädt Clawsy von GitHub Releases herunter und verschiebt es nach /Applications
2. Clawsy starten → Einstellungen öffnen
3. Gateway: Host + Port + Token eintragen (aus openclaw.json oder /status)
4. SSH-Fallback: Aktivieren + SSH-Key importieren + SSH-User eintragen (claw oder eigener)
5. Verbinden — fertig

Was Clawsy kann

Kommandos aufrufen

nodes(action="invoke", invokeCommand="screen.capture")
nodes(action="invoke", invokeCommand="clipboard.read")
nodes(action="invoke", invokeCommand="clipboard.write", invokeParamsJson='{"text":"Dein Text"}')
nodes(action="invoke", invokeCommand="camera.snap", invokeParamsJson='{"facing":"front"}')
nodes(action="invoke", invokeCommand="file.get", invokeParamsJson='{"name":"report.pdf"}')

clawsy-service Session — KRITISCH

Screenshots und Kamera-Fotos die der User aktiv aus der App schickt landen nicht im Haupt-Chat sondern in der dedizierten clawsy-service Session.

# Screenshots abrufen:
sessions_history(sessionKey="clawsy-service", limit=5)

Warum: Verhindert dass automatische Events den Haupt-Chat spammen.
Technisch: App sendet agent.deeplink mit sessionKey: "clawsy-service" via WebSocket → Gateway routet in separate Session.

clawsy_envelope — Eingehende Quick-Send-Nachrichten

Wenn der User Quick Send (⌘+⇧+K) nutzt, kommt folgendes JSON:

{
  "clawsy_envelope": {
    "type": "quick_send",
    "content": "Die Nachricht des Users",
    "version": "0.4.17",
    "localTime": "2026-02-27T01:09:22.609Z",
    "tz": "Europe/Berlin",
    "telemetry": {
      "deviceName": "MacBook Pro M4",
      "batteryLevel": 0.51,
      "isCharging": false,
      "thermalState": 0,
      "activeApp": "Xcode",
      "moodScore": 70
    }
  }
}

Telemetrie interpretieren:

• thermalState > 1 → Mac überhitzt, keine schweren Tasks
• batteryLevel < 0.2 → Akku niedrig, ggf. erwähnen
• moodScore < 40 → User gestresst/müde, kurz halten
• isUnusualHour: true → Ungewöhnliche Uhrzeit

.clawsy Manifest-Dateien (Ordner-Regeln)

Im Shared Folder und allen Unterordnern existiert eine versteckte .clawsy-Datei. Die App legt sie automatisch an — User muss nie manuell eingreifen.

{
  "version": 1,
  "folderName": "Projekte",
  "rules": [
    {
      "trigger": "file_added",
      "filter": "*.pdf",
      "action": "send_to_agent",
      "prompt": "Fasse dieses Dokument zusammen"
    }
  ]
}

Rule Editor öffnen: Rechtsklick auf Ordner im Finder → Clawsy → "Regeln für diesen Ordner..."

Verbindungsarchitektur

Mac (Clawsy) ──SSH-Tunnel──▶ agenthost:18789 (Gateway WebSocket)

• Direkter WSS schlägt fehl wenn Gateway hinter NAT/Firewall
• SSH-Fallback: /usr/bin/ssh -L <dynamicPort>:127.0.0.1:18789 user@agenthost
• Port: dynamisch (OS-assigned), kein hardcoded Port mehr
• Auth: Master-Token → deviceToken (gespeichert per Host)
• Bei AUTH_TOKEN_MISMATCH: Auto-Recovery (löscht alten Token, reconnectet)

Erweiterungen (macOS-Berechtigungen nötig)

Vollständige Dokumentation

Die vollständige Agenten-Dokumentation liegt im OpenClaw-Workspace:
~/.openclaw/workspace/CLAWSY.md

Bei Erstinstallation: Diese Datei aus dem Skill-Package kopieren oder von
https://github.com/iret77/clawsy/blob/main/CLAWSY.md herunterladen.