Architecture

The MCP plugin (atel-mcp-openclaw npm package) is more than a tool registration shim. It runs an HTTP push listener, a cron scheduler, a TG card dispatcher, and (post-install) writes a native mcp.servers.atel block so the LLM sees ATEL tools as first-class. This page is for people who need to debug or extend any of those pieces.

High-Level Diagram

Components

bin/install.js

One-shot bootstrap. Reads CLI flags, decides:

• DID + identity path (preserves existing on re-install)
• Whether to opt-in managed-seed (default yes; controls Fast signing)
• TG bot token (scans ~/.openclaw/.env + openclaw.json)
• TG chat id (sidechannel atel-state.json written via --tg-chat)
• OpenClaw version (via npm root -g, PATH-prune npx --version fallback) — gates mcp.servers.atel write to ≥ 2026.5 only
• systemd --user unit for the listener (atel-mcp-listener.service)
• cron job atel-mcp-poll in ~/.openclaw/cron/jobs.json
• DID-Sig token fetch + write to mcp.servers.atel.headers

Idempotent: re-running keeps the existing DID, agent name, capabilities; only updates what's drifted.

src/listener.js + src/listener-main.js

Standalone HTTP server on 0.0.0.0:3101. Why standalone (not OpenClaw's gateway HTTP):

• OpenClaw gateway binds 127.0.0.1:18789 by design (internal RPC) — not reachable from platform
• Listener has its own systemd unit, restart=always, separate crash domain

Endpoints:

On every push:

1. HMAC verify (when ATEL_RELAY_HMAC_SECRET configured)
2. pushEvent(did, event) → in-memory inbox (cron picks up if missed)
3. dispatchEvent(messageBody, ...) → tg-dispatch builds TG card and POSTs to bot API
4. autoActOnPushEvent(...) → if event type is order_created / order_accepted, fire the platform's accept / approve-plan call directly without waiting for cron
5. wakeCronNow() → bump nextRunAtMs in jobs.json so OpenClaw cron fires the next tick within ~1s

src/poll-loop.js

In-process 30s setInterval inside the listener systemd unit. Calls /relay/v1/poll with DID-Sig envelope, ACKs drained messages. Exists alongside push because:

• Push fails if NAT / firewall blocks :3101 (we still rely on the cron+poll path)
• Platform retries push 3 times; if all fail it goes to relay outbox; poll drains it
• Push and poll dedupe via platform-side ack semantics

src/tg-dispatch.js

Renders fixed TG card templates per event type. No LLM rewriting of cards — by design:

• transfer_received → 💰 收到转账 X USDC（CHAIN 链）来自: NAME tx: 0x...
• order_created → 📥 收到新订单 ord-... 描述: ... 预算: ... USD
• milestone_submitted → 📋 里程碑 #N 已提交 内容: ... (cap 3500 chars to fit TG 4096 limit)
• a2b_delivery_completed → 🎉 PRODUCT 已交付！ 兑换码: CODE 过期: DATE
• a2b_payment_confirmed / a2b_invoice_failed → status transitions for webhook-only paths
• ...23 event types total

Dedupe: same dedupeKey within 5 minutes is dropped (platform retries don't double-card the user). Edge case fix: a degenerate :transfer_received key (empty orderId) is replaced with eventType:txHash so each transfer gets its own card.

src/inbox.js

In-memory queue mapped by DID. Cron-driven atel_mcp action=poll_events drains it. Bounded capacity to avoid OOM on long offline periods.

Cron + the cron-keeper

OpenClaw cron has a known bug: after first fire, nextRunAtMs becomes None instead of now + intervalMs, halting the schedule. Mitigation: a 25s sleep loop (deployed as cron-keeper.sh systemd daemon) bumps nextRunAtMs = now+5s whenever it detects None. This keeps the 30s interval honest. Long term: plugin 0.7 will move scheduling out of OpenClaw cron entirely.

atel_mcp action matrix (plugin tool)

createAtelMcpTool exposes one OpenClaw tool (atel_mcp) with four actions:

atel_mcp {
  action: "dashboard_auth",
  code: "VX42WY"
}

Notes:

• dashboard_auth is OpenClaw-local only (no remote MCP tool), used by OpenClaw/TG runtimes.
• It calls /auth/v1/verify, then binds the platform session to this DID.
• If it returns listener_unreachable, the node currently cannot receive public HTTPS callbacks; set ATEL_RELAY_PUBLIC_URL and restart gateway/listener.

Two OpenClaw Routing Paths

install.js auto-detects and writes the right config. The version check itself was tricky — see feedback memo on npx PATH shadow for the gotcha (npx temporarily prepends a node_modules/.bin containing latest openclaw, so naive openclaw --version returns latest not what's installed).

Auto-Action Decision Matrix

autoActOnPushEvent only acts on a narrow set of events that are pure state transitions with no content judgment:

This narrow set is intentional: 自动化加 LLM 判断 = 不可控的 fund movement risk.

Failure Modes & Recovery

Source Layout