openclaw-poke

Bidirectional bridge between OpenClaw and Poke.

Architecture

User ←→ Poke (phone) ←→ Tunnel ←→ MCP Server ←→ OpenClaw (agent)
                                        ↑
External services (GitHub, Vercel, etc.) → webhooks → Poke → OpenClaw

Poke owns: triggers, schedules, condition monitoring, user-facing UI OpenClaw owns: execution — acting on events, running code, deploying, responding

Quick Start

npx openclaw-poke setup

The setup command handles the full handshake:

1. Auto-discovers your OpenClaw config (gateway port, auth tokens, hooks URL)
2. Authenticates with Poke
3. Prompts for Poke API key
4. Writes plugin config into openclaw.json
5. Creates + starts systemd service for MCP server on :3210
6. Installs the agent skill
7. Patches Poke SDK tunnel bug (≤0.4.2) automatically
8. Creates + starts systemd service for Poke tunnel
9. Verifies the connection

After setup, both the MCP server and tunnel run as systemd user services that auto-restart.

What You Get

Agent Tools (OpenClaw side)

| Tool | Description | |------|-------------| | poke_send | Text the user via Poke (SMS/iMessage) | | poke_sessions | List active OpenClaw sessions | | poke_session_send | Send a message to any session by key | | poke_webhook | Create Poke triggers that fire events into OpenClaw |

MCP Tools (Poke side)

| Tool | Description | |------|-------------| | send_to_agent | Send message to OpenClaw (with optional session targeting) | | list_sessions | List active OpenClaw sessions | | check_agent_status | Health check | | create_reminder | Set a reminder via the agent | | send_media | Send media to agent | | get_logs | Recent agent logs | | read_file | Read a workspace file | | create_trigger | Create a trigger on OpenClaw side |

Plus

• /poke/inbound HTTP route — receives Poke trigger POSTs
• npx openclaw-poke test — send a test message through the bridge
• Agent skill auto-installed — teaches the agent when/how to use Poke

Source Routing

All messages from Poke arrive prefixed with [Poke→OpenClaw]. The agent uses this to:

• Know the request came from Poke (not Telegram/WhatsApp/Discord)
• Route responses back via poke_send instead of the chat channel

Session Targeting

Poke can see and target specific OpenClaw sessions:

1. Call list_sessions to see what's running
2. Call send_to_agent with session_key to talk to a specific agent/session

Manual Tunnel (Alternative)

Setup auto-creates a systemd tunnel service. If you prefer manual control:

# Poke tunnel (recommended — zero config, authenticated relay)
poke tunnel http://localhost:3210/mcp --name "OpenClaw"

# Or Tailscale Funnel (if you have Tailscale)
tailscale funnel localhost:3210 /poke

# Or register a public URL directly
poke mcp add https://your-host.example.com/mcp --name "OpenClaw"

Webhook Triggers (Post-Handshake)

After connection is live, wire external services through Poke:

GitHub/Vercel/Stripe → webhook → Poke (catches + routes) → OpenClaw (executes)

Create triggers via the tool, CLI, or by texting Poke directly.

SDK

import { Pokebridge } from 'openclaw-poke';

const bridge = new Pokebridge();
await bridge.send('Hello from the agent');
await bridge.createTrigger({ condition: 'when deploy fails' });

CLI Commands

npx openclaw-poke setup      # Full interactive setup (9 steps)
npx openclaw-poke test       # Send a test message through Poke
npx openclaw-poke serve      # Start MCP server only (no tunnel)
npx openclaw-poke recipe     # Start MCP + tunnel + generate recipe link & QR
npx openclaw-poke webhook    # Create a Poke → OpenClaw webhook trigger
npx openclaw-poke install    # Install the agent skill only

Environment Variables

| Variable | Description | |----------|-------------| | POKE_API_KEY | Poke API key for sending messages | | OPENCLAW_HOOKS_URL | OpenClaw hooks endpoint (auto-detected by setup) | | OPENCLAW_HOOKS_TOKEN | Hooks bearer token (auto-detected by setup) | | OPENCLAW_MCP_PORT | MCP server port (default: 3210) |

Known Issues

Poke SDK tunnel bug (≤0.4.2)

poke tunnel may fail with "Server did not return a valid connection ID or tunnel URL." The setup command patches this automatically. If you installed manually, run npx openclaw-poke setup to apply the fix.

Systemd Services

Setup creates two user services:

| Service | Description | |---------|-------------| | openclaw-poke-mcp | MCP server on :3210 | | openclaw-poke-tunnel | Poke tunnel relay |

# Check status
systemctl --user status openclaw-poke-mcp openclaw-poke-tunnel

# Restart
systemctl --user restart openclaw-poke-mcp openclaw-poke-tunnel

# View logs
journalctl --user -u openclaw-poke-tunnel -f

License

MIT — Versatly Holdings