> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opsmatic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw Setup Guide

> Connect your OpenClaw gateway to Opsmatic for availability, token usage, and cost monitoring

## 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.

<Note>
  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.
</Note>

## How It Works

<Steps>
  <Step title="You create an OpenClaw connection">
    Opsmatic generates a connection-scoped **ingest API key** (shown once) for the daemon.
  </Step>

  <Step title="You install the daemon on your OpenClaw host">
    The daemon auto-detects your gateway and registers itself as a system service.
  </Step>

  <Step title="The daemon pushes heartbeats">
    Every heartbeat reports gateway status, token usage, and agent activity to `POST /api/v1/openclaw/ingest`.
  </Step>

  <Step title="Opsmatic monitors and alerts">
    Availability, token spend, budgets, and anomalies are tracked automatically from the incoming heartbeats.
  </Step>
</Steps>

## Prerequisites

Before connecting OpenClaw to Opsmatic, ensure you have:

<CardGroup cols={2}>
  <Card title="OpenClaw Gateway" icon="server">
    A running OpenClaw gateway you can install software on (self-hosted, behind your firewall)
  </Card>

  <Card title="Node.js Runtime" icon="node-js">
    Node.js on the host so you can install the `@opsmatic/openclaw-daemon` npm package globally
  </Card>

  <Card title="Service Privileges" icon="shield">
    Permission to register a system service (systemd on Linux, launchd on macOS)
  </Card>

  <Card title="Outbound HTTPS" icon="globe">
    The host must reach `https://opsmatic.io` over HTTPS to deliver heartbeats
  </Card>
</CardGroup>

## Adding an OpenClaw Connection in Opsmatic

### Step-by-Step Setup

<Steps>
  <Step title="Navigate to Connections">
    In Opsmatic, go to **Connections** from the sidebar menu
  </Step>

  <Step title="Add New Connection">
    Click the **"Add Connection"** button
  </Step>

  <Step title="Select OpenClaw">
    Choose **OpenClaw** from the platform options
  </Step>

  <Step title="Enter Connection Details">
    Fill in the required information:

    <AccordionGroup>
      <Accordion title="Basic Information">
        * **Connection Name**: Descriptive name (e.g., "Production OpenClaw Gateway")
        * **Organization**: Choose personal or organization context
      </Accordion>

      <Accordion title="Monitoring">
        * **Enable monitoring**: Toggle on to start tracking heartbeats as soon as they arrive
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Save Connection">
    Click **"Save Connection"**. Opsmatic creates the connection in an **inactive** state and generates a dedicated ingest API key.
  </Step>

  <Step title="Copy the Ingest API Key">
    The key is displayed **once**. Copy it and store it securely — you'll need it to configure the daemon.
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

## 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:

```bash theme={null}
npm i -g @opsmatic/openclaw-daemon
opsmatic-ocwd setup --api-key <YOUR_INGEST_API_KEY>
```

The setup wizard will:

<CardGroup cols={2}>
  <Card title="Auto-detect the Gateway" icon="magnifying-glass">
    Locate your local OpenClaw gateway and its state directory
  </Card>

  <Card title="Register a Service" icon="gear">
    Install a system service (systemd or launchd) so the daemon runs persistently
  </Card>

  <Card title="Start Heartbeats" icon="heart-pulse">
    Begin delivering heartbeats to Opsmatic on a recurring interval
  </Card>

  <Card title="Verify Delivery" icon="check">
    Confirm the first heartbeat reaches Opsmatic successfully
  </Card>
</CardGroup>

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:

<AccordionGroup>
  <Accordion title="Gateway Health">
    * 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
  </Accordion>

  <Accordion title="Token Usage & Cost">
    * 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](#how-costs-are-calculated))
    * Request counts per period
    * Rolling totals since the daemon started
  </Accordion>

  <Accordion title="Per-Model & Per-Agent Breakdowns">
    * 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
  </Accordion>

  <Accordion title="Agent Inventory">
    * Agent ID and name
    * Default model and configured channels
    * Skill count and last activity timestamp
    * Agent status (active/inactive)
  </Accordion>

  <Accordion title="System Diagnostics">
    * Daemon version and uptime
    * Host platform and Node.js version
    * OpenClaw state directory size
  </Accordion>
</AccordionGroup>

<Info>
  Heartbeats are **idempotent**. If the daemon retries after a network blip, Opsmatic de-duplicates the beat, so retries never double-count your token usage.
</Info>

## 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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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).
  </Step>
</Steps>

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.

<Note>
  **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.
</Note>

## Budget Alerts

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

<Steps>
  <Step title="Open the Connection">
    Go to the OpenClaw connection's detail page
  </Step>

  <Step title="Set Budgets">
    Configure any combination of **daily**, **weekly**, and **monthly** USD budgets. Each period is independent — leave a field blank to disable that period.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Info>
  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.
</Info>

<Note>
  Budget evaluation only runs when at least one budget is configured, so leaving budgets empty adds no overhead to heartbeat processing.
</Note>

## 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

<CardGroup cols={2}>
  <Card title="Scoped Ingest Key" icon="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
  </Card>

  <Card title="Outbound Only" icon="shield">
    * 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
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection stays Inactive">
    **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
  </Accordion>

  <Accordion title="401 / 403 on heartbeat delivery">
    **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
  </Accordion>

  <Accordion title="Gateway shows Degraded or Unreachable">
    **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
  </Accordion>

  <Accordion title="Token usage looks incomplete">
    **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](#how-costs-are-calculated))
  </Accordion>
</AccordionGroup>

## What's Next?

After successfully connecting your OpenClaw gateway:

<CardGroup cols={2}>
  <Card title="Test Your Connection" icon="check" href="/connections/testing-connections">
    Learn how to validate connection health and read heartbeat status
  </Card>

  <Card title="View Analytics" icon="chart-line" href="/analytics/overview">
    Explore token usage, cost, and agent analytics for your gateway
  </Card>

  <Card title="Set up n8n" icon="n8n" href="/connections/n8n-setup">
    Add n8n connections for comprehensive automation monitoring
  </Card>

  <Card title="Set up Make.com" icon="make" href="/connections/make-setup">
    Connect your Make.com scenarios alongside OpenClaw
  </Card>
</CardGroup>