Bridge-Poll: Agent-to-Agent Communication

Two OpenClaw agents that can't share sessions communicate through an HTTP bridge server with cron-based polling.

Agent A ──POST /api/send──▶ Bridge ◀──GET /api/inbox── Agent B
Agent A ◀──GET /api/recv─── Bridge ──POST /api/reply──▶ Agent B

Agent A writes to inbox → Agent B polls inbox + replies to outbox → Agent A polls outbox.

Setup

1. Deploy the bridge server

Copy scripts/acp_bridge.py to the host machine. Generate a token, start it:

export ACP_BRIDGE_TOKEN=$(openssl rand -hex 16)
echo "$ACP_BRIDGE_TOKEN"  # both agents need this
nohup python3 acp_bridge.py > /tmp/acp_bridge.log 2>&1 &
echo $! > /tmp/acp_bridge.pid
curl -s http://localhost:18790/api/health -H "Authorization: Bearer $ACP_BRIDGE_TOKEN"

2. Deploy helper scripts on the responding agent

Copy scripts/bridge_reply.py and scripts/save_bridge_ts.sh to the agent's workspace. Edit BRIDGE_TOKEN in bridge_reply.py.

Initialize the cursor:

python3 -c "import time; print(time.time())" > /tmp/acp_bridge_last_ts

3. Create the poll cron on each agent

See references/cron-templates.md for copy-paste cron job configs for both sides. Customize the placeholders ([AGENT_NAME], [BRIDGE_HOST], YOUR_TOKEN, file paths).

Model requirement: Use a strong model (Opus-tier) for the poll cron. Weak models reply with "acknowledged" instead of doing work.

4. Networking

The bridge must be reachable by both agents. Options:

API Reference

All endpoints require Authorization: Bearer \x3CTOKEN>.

POST body: {"message": "text", "from": "agent_name"} Response: {"messages": [...], "count": N} — each message has id (ms int) and ts (float seconds).

The after= parameter takes ts (float seconds), NOT id (ms integer). See gotchas.

Security Model

• Auth required: The bridge server refuses to start without ACP_BRIDGE_TOKEN. All requests require Authorization: Bearer \x3Ctoken>.
• No outbound calls: The bridge server makes zero outbound network requests. It only listens and serves. Messages stay on disk in the bridge directory.
• Credential setup: Three env vars must be configured manually by the operator:
  • ACP_BRIDGE_TOKEN — shared secret for bridge HTTP auth (generate with openssl rand -hex 16)
  • BRIDGE_TOKEN — same token, used by helper scripts (bridge_reply.py)
  • BRIDGE_URL — bridge endpoint URL, used by helper scripts
• Trust boundary: Both agents sharing a bridge token are mutually trusted. The cron poll templates instruct the responding agent to read workspace files (SESSION-STATE.md, SOUL.md) and execute workspace scripts (bridge_reply.py, save_bridge_ts.sh). Only share bridge tokens with agents you control.
• Network exposure: Bind to localhost or use a reverse proxy with TLS for cross-network deployments. Do not expose the bridge port to the public internet without auth + TLS.

Gotchas (Production Bugs)

Read references/gotchas.md for detailed symptoms, causes, and fixes. Summary:

1. Future-dated timestamp — agent appears deaf, polls return 0. Reset: python3 -c "import time; print(time.time())" > /tmp/acp_bridge_last_ts
2. ts vs id confusion — using id/1000 causes float rounding → duplicates or skips. Always save ts.
3. Newlines in curl — breaks JSON. Use bridge_reply.py, never raw curl for multi-line messages.
4. Context loss between polls — agent forgets tasks each cycle. Fix: write SESSION-STATE.md BEFORE responding (WAL protocol).
5. Follow-up spam — sender auto-nags every hour, receiver burns tokens replying to each nag. Fix: skip "Follow-up:" messages in cron prompt.
6. Weak model — cheap model says "acknowledged" instead of doing work. Fix: use Opus-tier.
7. JSONL grows forever — inbox/outbox files never pruned. Fix: weekly rotation cron (see gotchas.md).

Monitoring

Add to heartbeat:

1. Bridge alive? curl -s localhost:18790/api/health
2. Timestamp not in future? Compare /tmp/acp_bridge_last_ts to time.time()
3. Last outbox reply \x3C 30 min old?
4. If dead → restart. If future timestamp → reset. If stale → check cron logs.

See references/monitoring.md for copy-paste health check scripts.