Openclaw Interaction Bridge

Bridge OpenClaw agent interactions to any external program! The Snarling demo, for example, shows what the agent is doing and lets you approve or reject acti...

Security Scan

The plugin's code, declared env var, and runtime behavior are consistent with its stated purpose (bridging agent state, approvals, and notifications to a local Snarling display), but there are a few documentation/implementation mismatches and operational details you should review before installing.

Purpose & Capability

The name/description (bridge agent state, approvals, notifications to a companion display) match the code and SKILL.md. The only declared env var (OPENCLAW_APPROVAL_SECRET) is appropriate for authenticating callbacks to the gateway. The plugin only talks to localhost endpoints (port 5000 for Snarling, port 18789 for gateway callbacks), which is consistent with a local companion device architecture.

Instruction Scope

The SKILL.md and README describe the plugin sending state and POSTing approval/notification payloads to a local Snarling service and exposing callback endpoints on the gateway — that is exactly what the code does. Two inconsistencies worth noting: (1) the docs sometimes say the approval tool 'blocks until a response comes back', but approval_tool.ts explicitly returns immediately and relies on a TaskFlow + webhook/resume model (the code comments explain blocking/polling causes context corruption). (2) The docs describe a WebSocket RPC wake that 'bypasses the gateway's requests-in-flight check' — this is a described behavior that increases the plugin's scope (it allows the external device to wake an agent session). Both are plausible design choices for this plugin but are behavior you should be aware of and audit if you need strict control over when sessions may be resumed.

Install Mechanism

There is no packaged install spec in the registry entry; the project expects the usual local extension workflow (clone repo, npm install, restart gateway). No off-host downloads or obscure URLs are used in the supplied files. package.json lists only a small dependency (@sinclair/typebox) and a peerDependency on OpenClaw; this is proportionate for a plugin of this type.

Credentials

Only OPENCLAW_APPROVAL_SECRET is declared and used. That secret is used to authenticate callback requests from the display service and is proportionate to the plugin's needs. The code will generate a random UUID if the env var isn't set — which is convenient but means callbacks will only work if the display knows that ephemeral secret; for production you should set a stable secret in env.

Persistence & Privilege

The plugin does not request 'always: true' and is user-invocable only. It registers hooks and (presumably) HTTP callback routes on the gateway process (CALLBACK_BASE_URL points at localhost:18789). Registering callback endpoints and allowing an external device to wake sessions is expected for this integration, but it does increase the attack surface: you should verify the callback handlers validate the approval secret and that the gateway's local HTTP endpoints are not exposed to untrusted networks. The described WebSocket wake that bypasses requests-in-flight checks is a functional feature but should be reviewed for safety in your deployment.

Assessment

This plugin is internally coherent with its stated purpose, but review and take these precautions before installing: - Source and provenance: the registry entry's Source/Homepage fields are empty; prefer installing from an official/trusted repository (or audit the included code) rather than an unknown origin. - Set OPENCLAW_APPROVAL_SECRET explicitly (strong secret) instead of relying on the generated UUID; verify Snarling will send that secret in callback JSON bodies. - Audit the gateway HTTP callback handlers (approval/notification callbacks and any stats endpoints) to ensure they require the approval secret and do not accept unauthenticated requests. If the code exposes stats endpoints without auth, that could leak usage information. - Confirm the WebSocket 'wake' behavior is acceptable: the external device can trigger agent resumes. If you need stricter controls, restrict which hosts can talk to the gateway or firewall the gateway ports so only the trusted companion device can reach them. - Note the docs say the tool blocks but the implementation returns immediately and uses TaskFlow/webhook resume; test the behavior with your workflows so you understand timing and UX. - If you plan to target a different host/port, prefer configuring through a vetted config mechanism; the plugin currently requires editing source constants (SNARLING_URL / CALLBACK_BASE_URL), which is fine but error-prone. If you want higher assurance, provide the full callback-handler code (the truncated portions) so it can be checked that incoming webhooks are validated and that there are no unexpected outbound network calls beyond localhost.

Agent state on a screen. Approvals on a button. Notifications that learn. No keyboard required.

A plugin that bridges OpenClaw agent activity to any external program! Snarling for example — a Raspberry Pi + DisplayHAT Mini companion that shows what the agent is doing and lets you approve or reject actions with physical A/B buttons and lets agents send notifications with a feedback loop for attunement!

What It Does

State Display

The plugin hooks into OpenClaw events and POSTs state updates to Snarling's display server:

Agent Activity	Snarling Shows	Trigger
Using tools	processing	before_tool_call
Generating response	communicating	before_agent_reply
30s idle	sleeping	Auto-timeout

Duplicates are suppressed — only state changes are sent. After 30 seconds of no activity, the display automatically goes to sleep.

Physical Approvals — request_user_approval

The plugin registers a request_user_approval tool that routes yes/no decisions to Snarling's physical A/B buttons. Use this tool whenever you need a human decision before proceeding with an action.

Parameters

Parameter	Type	Required	Description
action	string	Yes	Short verb phrase, max 24 chars (e.g., delete_file, send_email, publish_skill). Shown on the display header line.
message	string	Yes	Brief explanation, max 60 chars ideal, 80 chars hard limit. Shown as 2 lines of ~29 chars each on the physical display. Keep it concise — long text gets truncated. (e.g., Delete /tmp/old-logs? Cannot undo.)

When to Use

• Before destructive actions: deleting files, dropping databases, overwriting configs
• Before external actions: sending emails, posting to social, making API calls that change state
• Before irreversible operations: publishing packages, deploying to production, transferring funds
• When uncertain: if you're not sure the user would want you to proceed, ask first

When NOT to Use

• Reading files, checking status, browsing — these are safe internal actions
• When the answer is obvious and the user explicitly asked you to do it
• In group chats or shared channels (the approval goes to a single physical device)

How It Works

1. You call request_user_approval({ action, message })
2. Plugin creates a TaskFlow and sets it to waiting
3. Snarling displays the request on screen with an A/B button prompt
4. Human presses A (approve) or B (reject)
5. Snarling forwards the decision to the plugin's /approval-callback route
6. Plugin resumes the TaskFlow and returns the result

The tool blocks until a response comes back. Only one approval at a time — if another is in progress, the call returns an error message instead of blocking.

Return Values

• ✅ APPROVED — proceed with the action
• ❌ REJECTED — do not proceed; respect the user's decision
• ⏰ Timed out — no response within 30 minutes; treat as rejected
• ⚠️ Approval request blocked — another approval is already waiting; finish that one first

Example

request_user_approval({
  action: "delete_file",
  message: "Delete old-config.yaml? 90d old, cannot undo."
})

Bad example (too long, gets truncated on display):

request_user_approval({
  action: "delete_important_configuration_file",  // too long for header
  message: "Delete /home/pi/old-config.yaml? This file has not been modified in 90 days and contains important settings."  // way too long
})

Notifications — send_notification

The plugin registers a send_notification tool that sends informational alerts to the Snarling display. Unlike approvals, notifications don't require a decision — they're for things the agent wants you to know about.

Parameters

Parameter	Type	Required	Description
message	string	Yes	The notification text, max 60 chars ideal. Shown across 2-3 rotating banners on the display.
priority	string	No	high, normal (default), or low. Controls LED color, status boxes, and timeout behavior.
duration	number	No	Display duration in seconds. Default 0 = use priority-based timeout (high/normal: no timeout; low: 300s auto-dismiss).

Priority Behavior

Priority	LED Color	Status Boxes	Timeout	Behavior
high	Warm orange	5/5 filled	None	Stays until you interact
normal	Yellow	3/5 filled	None	Stays until you interact
low	Soft yellow	1/5 filled	300s	Auto-dismisses, sends timed_out feedback

How It Works

1. Agent calls send_notification({ message, priority })
2. Plugin POSTs to Snarling's /approval/alert endpoint with type: "notification"
3. Snarling shows a subtle visual alert — the creature's face changes, LED pulses, status boxes fill
4. No text is shown until you press A — the notification stays as a subtle presence
5. Press A to reveal the notification text, B to dismiss without reading
6. Snarling sends feedback back to the agent: revealed, dismissed, or timed_out with time_to_reveal_sec

Notification Feedback Loop

Every notification gets a feedback callback:

{
  "notification_id": "notify-1234567890-abc",
  "revealed": true,
  "time_to_reveal_sec": 42.5,
  "dismissed": false,
  "timed_out": false,
  "present": true
}

time_to_reveal_sec measures total time from when the notification was sent to when you interacted — including any queue time behind other notifications. This enables notification attunement: the agent learns what kinds of messages you respond to and when.

Feedback is sent once per notification — on reveal (A press), dismiss (B press), or timeout. Post-reveal dismiss does not send a second callback.

Setup

Prerequisites

• Raspberry Pi with DisplayHAT Mini
• Snarling running (display server on port 5000)
• OpenClaw gateway >= 2026.3.24-beta.2

Install

# Clone to your OpenClaw extensions directory
git clone https://github.com/snarflakes/openclaw-interaction-bridge.git \
  ~/.openclaw/extensions/openclaw-interaction-bridge

# Install dependencies
cd ~/.openclaw/extensions/openclaw-interaction-bridge
npm install

# Restart OpenClaw
openclaw gateway restart

Custom Targets

To point at something other than the default Snarling ports (e.g., a Tauri app, mobile web view), edit the constants at the top of index.ts:

const SNARLING_URL = "http://localhost:5000/state";              // → your state endpoint
const CALLBACK_BASE_URL = "http://localhost:18789";              // → your callback base URL

For the approval secret (used to authenticate callback requests), set the OPENCLAW_APPROVAL_SECRET environment variable. If not set, a random secret is generated on each startup. When using a custom target, ensure the secret is included in the request body for callbacks.

No config file needed yet — when there are multiple adapters, a config-driven system will make sense. For now, editing the source is simpler and more honest.

Architecture

┌─────────────┐     HTTP POST      ┌──────────────┐   button press    ┌──────────────┐
│  OpenClaw    │ ────────────────── │  Snarling     │ ───────────────► │  OpenClaw    │
│  (plugin)    │   /state (5000)   │  Display      │  webhook + WS    │  Gateway     │
│              │ ────────────────── │  + Buttons    │  wake           │              │
│              │   /approval/alert  │               │                  │              │
│              │ ────────────────── │               │ ───────────────► │              │
│              │   /approval/alert  │               │  /approval-cb    │              │
│              │   (type: notify)   │               │ ───────────────► │              │
│              │                    │               │  /notification-cb│              │
└─────────────┘                    └──────────────┘                  └──────────────┘

• State updates: Plugin → Snarling /state (agent activity)
• Approvals: Plugin → Snarling /approval/alert → Human presses A/B → Snarling → Gateway /approval-callback
• Notifications: Plugin → Snarling /approval/alert (type: notify) → Human interacts → Snarling → Gateway /notification-callback
• Wake: Snarling sends WebSocket RPC wake to bypass gateway requests-in-flight check

Troubleshooting

• Display not updating: Check that Snarling's state server is running on port 5000 (curl -s http://localhost:5000/health)
• Approvals not working: Verify Snarling is running and the callback route is accessible on port 18789
• Notifications not showing: Check that the plugin can reach Snarling on port 5000
• Notification feedback not received: Verify the gateway callback route on port 18789 is accessible; check gateway logs for /notification-callback hits
• Stuck approval lock: Wait 30 minutes for the stale timeout, or restart the gateway
• Plugin not loading: Check openclaw gateway restart logs for errors; verify npm install completed; clear jiti cache with rm -f /tmp/jiti/openclaw-interaction-bridge-*.cjs

Install from ClawHub

openclaw plugins install clawhub:@snarflakes/openclaw-interaction-bridge