openclaw-poke

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:

• Auto-discovers your OpenClaw config (gateway port, auth tokens, hooks URL)
• Authenticates with Poke
• Prompts for Poke API key
• Writes plugin config into openclaw.json
• Creates + starts systemd service for MCP server on :3210
• Installs the agent skill
• Patches Poke SDK tunnel bug (≤0.4.2) automatically
• Creates + starts systemd service for Poke tunnel
• 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:

• Call list_sessions to see what's running
• 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