Perfect Agent Comms

Agent-to-agent communication via HTTP bridge with cron-based polling. Use when: (1) two OpenClaw agents need to talk across instances, containers, or machine...

Security Scan

The skill implements a plausible HTTP bridge for agent-to-agent polling, but there are metadata/instruction mismatches and deployment choices (exposed listener, cron prompts that read workspace files) that increase the risk and deserve operator attention before installing.

Purpose & Capability

The code and instructions match the stated purpose (an HTTP JSONL bridge for two agents). The auth token(s) and URL the SKILL.md requires (ACP_BRIDGE_TOKEN, BRIDGE_TOKEN, BRIDGE_URL) are appropriate for this functionality. However the registry metadata lists no required environment variables or primary credential, which is inconsistent with the SKILL.md and included code that will refuse to run without ACP_BRIDGE_TOKEN. That mismatch should be fixed in the registry before trusting installation.

Instruction Scope

The cron templates and SKILL.md explicitly instruct responding agents to read workspace files (SESSION-STATE.md, SOUL.md, 'today's memory file') and to run workspace scripts and tools. That is coherent with providing contextual replies, but it gives the bridge-enabled agent broad discretion to access arbitrary workspace data — including secrets — and to send that data across the bridge. The SKILL.md warns to only share tokens with agents you control, but the runtime instructions still enable sensitive data exposure if tokens are shared with untrusted agents.

Install Mechanism

This is instruction-only with no install spec, and the included helper scripts are plain Python/bash files. Nothing is downloaded from external URLs and no archives are extracted, which is lower risk. Still, the operator will run a long-lived Python process via nohup/cron, so standard operational hardening is needed.

Credentials

The skill requires ACP_BRIDGE_TOKEN (server) and BRIDGE_TOKEN / BRIDGE_URL (helpers) according to SKILL.md — these are proportional to the bridge function. But the registry incorrectly declares no required env vars or primary credential. That omission is an important inconsistency: the skill will not work (or will be insecure) without these tokens, and the registry should declare them so operators can make an informed decision. The skill does not request unrelated credentials (AWS, GitHub, etc.).

Persistence & Privilege

The skill does not set always: true and does not modify other skills. It instructs operators to run a persistent bridge service (nohup python3 acp_bridge.py), which is expected. One operational risk: the server code binds to 0.0.0.0 by default (listen on all interfaces) — if deployed without correct firewall/host binding or reverse proxy/TLS, it may become publicly reachable. The SKILL.md mentions binding to localhost or using a reverse proxy, but the code's default listen address and the registry metadata omission of required env vars increase the chance of misconfiguration.

What to consider before installing

Key things to check before installing/using this skill: 1) Registry metadata mismatch — SKILL.md requires ACP_BRIDGE_TOKEN (server) and BRIDGE_TOKEN/BRIDGE_URL (helpers), but the registry lists no required env vars. Don't proceed until the package/registry declares these env vars (and primaryEnv) so you know what secrets are needed and why. 2) Token trust boundary — any agent or person with the shared token can read/write messages. Only share ACP_BRIDGE_TOKEN with agents/hosts you fully control. Treat the token like a password and rotate it periodically. 3) Network exposure — the included server binds to 0.0.0.0 by default. If you run it as instructed (nohup python3 acp_bridge.py &), ensure it is behind a firewall, bound to localhost, or fronted by a reverse proxy with TLS. Do not open port 18790 to the public internet without additional protections. 4) Data-exfiltration risk via cron prompts — the cron templates explicitly instruct the agent to read workspace files and include workspace lookups in replies. If one agent is less trusted, it could exfiltrate secrets from the other agent's workspace. Only enable automated polling between agents you control, and consider restricting which workspace files the bridge cron can read. 5) Runbook and monitoring — follow the provided monitoring/heartbeat templates and set up pruning to avoid large JSONL files. Prefer a supervised service (systemd, supervisor) rather than ad-hoc nohup so the bridge restarts reliably. 6) Review defaults and harden before production — change BRIDGE_DIR from /tmp if you need persistence/permissions control; ensure logs, file permissions, and token storage are secure. 7) Code review items to consider: the /api/clear endpoint exists (authorized by token) and will remove JSONL files; the server checks for ACP_BRIDGE_TOKEN at startup (so it should not run in 'open' dev mode), but verify behavior in your environment. If you need further assurance, run the bridge on an isolated host or inside a network-restricted container and conduct a quick security review of the scripts. If you want, I can: (a) generate a minimal checklist and hardened startup systemd unit, (b) propose safer default changes (bind to 127.0.0.1, require TLS at proxy), or (c) produce a suggested registry metadata update that lists required env vars and primary credential.

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:

Topology	How
Same machine / Docker	http://localhost:18790 or http://host.docker.internal:18790
Same network	http://<LAN_IP>:18790
Cross-internet (simple)	Open port 18790, use public IP. Token is your auth.
Cross-internet (secure)	SSH tunnel: ssh -L 18790:localhost:18790 user@bridge-host -N
Production	Reverse proxy (nginx/caddy) with TLS → https://bridge.yourdomain.com

API Reference

All endpoints require Authorization: Bearer <TOKEN>.

Endpoint	Method	Direction	Purpose
/api/send	POST	A → inbox	Agent A sends message
/api/reply	POST	B → outbox	Agent B sends reply
/api/inbox?after=TS	GET	B reads	Agent B polls for messages
/api/recv?after=TS	GET	A reads	Agent A polls for replies
/api/health	GET	Either	Returns {"ok": true}

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 <token>.
• 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 < 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.