Skip to main content

​
Overview

OpenClaw is a self-hosted AI agent gateway that runs behind your own firewall. Because Opsmatic cannot reach it directly, OpenClaw monitoring is push-based: a lightweight daemon (@opsmatic/openclaw-daemon) runs alongside your gateway and pushes periodic heartbeats to Opsmatic. Those heartbeats carry gateway health, token usage, per-agent and per-model cost breakdowns, and agent inventory — giving you the same availability and analytics experience as n8n and Make.com, plus AI spend tracking.
OpenClaw connections work differently from n8n and Make.com. Instead of Opsmatic polling your instance with an API key, you install a daemon that pushes data out. There is no Base URL to configure and no pre-save connection test — the connection activates once the daemon delivers its first heartbeat.

​
How It Works

1

You create an OpenClaw connection

Opsmatic generates a connection-scoped ingest API key (shown once) for the daemon.
2

You install the daemon on your OpenClaw host

The daemon auto-detects your gateway and registers itself as a system service.
3

The daemon pushes heartbeats

Every heartbeat reports gateway status, token usage, and agent activity to POST /api/v1/openclaw/ingest.
4

Opsmatic monitors and alerts

Availability, token spend, budgets, and anomalies are tracked automatically from the incoming heartbeats.

​
Prerequisites

Before connecting OpenClaw to Opsmatic, ensure you have:

OpenClaw Gateway

A running OpenClaw gateway you can install software on (self-hosted, behind your firewall)

Node.js Runtime

Node.js on the host so you can install the @opsmatic/openclaw-daemon npm package globally

Service Privileges

Permission to register a system service (systemd on Linux, launchd on macOS)

Outbound HTTPS

The host must reach https://opsmatic.io over HTTPS to deliver heartbeats

​
Adding an OpenClaw Connection in Opsmatic

​
Step-by-Step Setup

1

Navigate to Connections

In Opsmatic, go to Connections from the sidebar menu
2

Add New Connection

Click the “Add Connection” button
3

Select OpenClaw

Choose OpenClaw from the platform options
4

Enter Connection Details

Fill in the required information:
  • Connection Name: Descriptive name (e.g., “Production OpenClaw Gateway”)
  • Organization: Choose personal or organization context
  • Enable monitoring: Toggle on to start tracking heartbeats as soon as they arrive
5

Save Connection

Click “Save Connection”. Opsmatic creates the connection in an inactive state and generates a dedicated ingest API key.
6

Copy the Ingest API Key

The key is displayed once. Copy it and store it securely — you’ll need it to configure the daemon.
The ingest API key is shown only once. Opsmatic never displays it again after you close the dialog. If you lose it, delete the connection and create a new one to generate a fresh key.

​
Installing the Daemon

On the host running your OpenClaw gateway, install the daemon and run the setup wizard with the ingest API key from the previous step:
The setup wizard will:

Auto-detect the Gateway

Locate your local OpenClaw gateway and its state directory

Register a Service

Install a system service (systemd or launchd) so the daemon runs persistently

Start Heartbeats

Begin delivering heartbeats to Opsmatic on a recurring interval

Verify Delivery

Confirm the first heartbeat reaches Opsmatic successfully
Once the first healthy heartbeat is received, the connection status flips from Inactive to Active automatically. Refresh the Connections list in Opsmatic to confirm.

​
What Data is Monitored

Each heartbeat carries a snapshot of your gateway. Opsmatic persists and analyzes:
  • Gateway status: healthy, degraded, or unreachable
  • Gateway latency (ms) and version
  • Whether the gateway process is alive
  • Mirrored into availability metrics so uptime and response-time charts work like any other connection
  • Input, output, and cache read/write tokens per period
  • Estimated cost in USD — provider-reported when OpenClaw logs it, otherwise computed by Opsmatic (see How Costs Are Calculated)
  • Request counts per period
  • Rolling totals since the daemon started
  • Token usage and cost grouped by model and provider
  • Token usage and cost grouped by agent
  • Feeds the analytics views for identifying your most expensive models and agents
  • Agent ID and name
  • Default model and configured channels
  • Skill count and last activity timestamp
  • Agent status (active/inactive)
  • Daemon version and uptime
  • Host platform and Node.js version
  • OpenClaw state directory size
Heartbeats are idempotent. If the daemon retries after a network blip, Opsmatic de-duplicates the beat, so retries never double-count your token usage.

​
How Costs Are Calculated

Opsmatic uses a two-tier cost model for OpenClaw. The daemon never guesses prices — it reports what OpenClaw actually logged, and Opsmatic fills in the rest:
1

Provider-reported cost (preferred)

When OpenClaw records the real cost of a request in its session logs (most direct provider integrations do), the daemon forwards that exact figure. This is your source of truth — it reflects what the provider actually charged.
2

Server-side pricing (fallback)

When a request has only token counts and no cost, the daemon sends the tokens with the cost marked as unknown, and Opsmatic computes it at ingest using its maintained per-model pricing table (input, output, cache-read, and cache-write rates per million tokens).
Every usage record notes which tier priced it, so server-computed costs are always distinguishable from provider-reported ones — and can be recomputed if pricing tables change.
Using OpenRouter? Routed model IDs such as openrouter/anthropic/claude-sonnet-4-5 resolve to the underlying model’s price automatically. The special openrouter/auto model cannot be priced from tokens — the routed model differs per request — so those requests show $0 cost unless OpenRouter’s actual cost appears in the OpenClaw logs. Token counts are always tracked accurately either way.

​
Budget Alerts

OpenClaw connections support spend budgets so you get notified before costs run away.
1

Open the Connection

Go to the OpenClaw connection’s detail page
2

Set Budgets

Configure any combination of daily, weekly, and monthly USD budgets. Each period is independent — leave a field blank to disable that period.
3

Receive Notifications

Opsmatic sends a budget warning email when spend reaches 80% of a limit and a budget exceeded email when the limit is crossed. Repeat notifications are rate-limited per period (6h for daily, 24h for weekly, 72h for monthly budgets) so a sustained overage doesn’t flood your inbox.
Budget periods follow UTC calendar windows: daily budgets reset at midnight UTC, weekly on Sunday, and monthly on the 1st. Spend is summed from the per-model usage records — including costs Opsmatic computed server-side.
Budget evaluation only runs when at least one budget is configured, so leaving budgets empty adds no overhead to heartbeat processing.

​
Anomaly Detection

OpenClaw token spend is included in Opsmatic’s statistical anomaly detection. Using a rolling 7-day baseline, Opsmatic flags unusual spikes in token spend (alongside response time and execution failure rate for other platforms), opens an anomaly with an alert email, and resolves it automatically when spend returns to normal. Open anomalies are also queryable via GET /api/v1/anomalies.

​
Security Best Practices

Scoped Ingest Key

  • The ingest key can only push usage data for its one connection
  • It cannot read your other connections or account data
  • Rotate it by recreating the connection if it’s ever exposed

Outbound Only

  • The daemon initiates all traffic outbound over HTTPS
  • No inbound ports need to be opened on your firewall
  • Your gateway stays fully behind your network perimeter

​
Troubleshooting

Symptoms: The connection never turns Active after setup.Solutions:
  • Confirm the daemon service is running on the host (systemctl status / launchctl list)
  • Verify the host can reach https://opsmatic.io over HTTPS (check outbound firewall rules)
  • Re-run opsmatic-ocwd setup with the correct ingest API key
  • Check the daemon logs for delivery errors
Symptoms: Daemon logs show authentication or permission errors.Solutions:
  • Ensure you used the ingest API key generated for this connection
  • The key must be a usage-ingestion key scoped to the connection — keys created elsewhere won’t work
  • If the key was lost or rotated, recreate the connection to issue a new one
Symptoms: Heartbeats arrive but report a non-healthy gateway status.Solutions:
  • Check that the OpenClaw gateway process is running and responsive
  • Review gateway latency in the connection details for performance issues
  • Confirm the daemon auto-detected the correct gateway URL during setup
Symptoms: Cost or token totals seem lower than expected.Solutions:
  • Token data is read from OpenClaw session logs; confirm the daemon can access the gateway’s state directory
  • Allow a few heartbeat cycles for backfill after a fresh install or daemon restart
  • Verify the daemon version is current (npm i -g @opsmatic/openclaw-daemon)
  • If you route through openrouter/auto, costs show as $0 when OpenClaw doesn’t log the provider’s actual charge — token counts remain accurate (see How Costs Are Calculated)

​
What’s Next?

After successfully connecting your OpenClaw gateway:

Test Your Connection

Learn how to validate connection health and read heartbeat status

View Analytics

Explore token usage, cost, and agent analytics for your gateway

Set up n8n

Add n8n connections for comprehensive automation monitoring

Set up Make.com

Connect your Make.com scenarios alongside OpenClaw