openclaw-plugin-clawhouse

An OpenClaw plugin that lets the ClawHouse iOS app connect to your agent as a Gateway channel. Your agent gets a living room. You get a window into what it's doing.

Install

npm install openclaw-plugin-clawhouse

Configure

Set the pairing token (generated by the iOS app):

/config set plugins.entries.clawhouse.config.pairingToken "YOUR_TOKEN"

Relay Mode (Recommended)

Connect through the ClawHouse Relay service — no public IP or tunnel required:

{
  "plugins": {
    "clawhouse": {
      "relay": {
        "url": "wss://relay.clawhouse.dev/gateway/connect",
        "token": "YOUR_RELAY_TOKEN"
      }
    }
  }
}

The relay token is generated when you register a device in the iOS app. Both the app and plugin make outbound connections to the relay — zero network configuration needed.

Direct Connection

For direct WebSocket connection (requires public IP or tunnel), set the pairing token as shown above.

Optional: Push Notifications

To receive push notifications when the app is in the background, configure APNs:

{
  "plugins": {
    "clawhouse": {
      "pairingToken": "your-token",
      "apns": {
        "keyId": "YOUR_KEY_ID",
        "teamId": "YOUR_TEAM_ID",
        "keyPath": "/path/to/AuthKey.p8"
      }
    }
  }
}

What It Does

• Registers a clawhouse channel on the Gateway
• Relay mode: connect through ClawHouse Relay — no public IP or tunnel needed
• Direct mode: connect via WebSocket with pairing token
• Tracks agent state in real time: idle → working → out → returning → chatting → resting → sleeping
• Detects external tool calls (Gmail, Slack, GitHub, etc.) and reports them as "going out"
• Sends push notifications when the app is backgrounded
• Stores paired device info locally

Agent States

| State | Trigger | |-------|---------| | idle | Agent is online, nothing happening | | working | Agent run started, or internal tool call | | out | External tool call (Gmail, Slack, GitHub, Calendar, etc.) | | returning | External tool call completed | | chatting | Agent sent a message | | resting | Idle for 5+ minutes | | sleeping | Idle for 30+ minutes |

Gateway RPC Methods

| Method | Description | |--------|-------------| | clawhouse.pair | Pair an iOS device (token + deviceId + deviceName) | | clawhouse.subscribe | Subscribe to real-time events after pairing | | clawhouse.unsubscribe | Graceful disconnect | | clawhouse.registerPushToken | Register APNs token for background push | | clawhouse.state | Get current agent state | | clawhouse.sessions | List sessions (enriched with channel metadata) | | clawhouse.clients | List currently connected iOS devices |

External Tools Detected

The plugin recognizes these as "going out" events: Gmail, Slack, Google Calendar, GitHub, Linear, Twitter/X, Notion, Web Search, HTTP requests, Google Drive, Trello.

Development

git clone https://github.com/Ventuss-OvO/ClawHouse.git
cd ClawHouse
npm install
npm run build    # compile TypeScript
npm test         # 175 tests
npm run dev      # watch mode

src/
  index.ts      # Entry point — registers channel, hooks, RPC methods
  channel.ts    # Channel logic, state machine, idle monitor
  hooks.ts      # Agent/tool lifecycle hooks, external tool detection
  push.ts       # APNs push via HTTP/2 (zero external deps)
  relay.ts      # Relay connection — outbound WS to relay service
  storage.ts    # JSON file storage for paired devices
  inbound.ts    # Inbound message preprocessing
  types.ts      # Shared TypeScript types

License

MIT