Documentation

Get started with ClawHQ

Everything you need to connect your OpenClaw gateway and start tracking costs.

Quick Start

Get ClawHQ connected to your OpenClaw gateway in under 2 minutes.

Sign up & get your API key

Create a free account at app.clawhq.co/signup. Your API key will be generated automatically during onboarding.

Add 2 lines to your openclaw.json

// Add to your openclaw.json

{

"diagnostics": {

"enabled": true,

"otel": {

"enabled": true,

"endpoint": "https://app.clawhq.co/api/v1/otlp",

"headers": {

"Authorization": "Bearer chq_YOUR_KEY_HERE"

}

Restart your gateway

Run openclaw gateway restart and cost data will start flowing to your ClawHQ dashboard immediately.

Supported Metrics

ClawHQ collects the following metrics from your OpenClaw gateway via the OpenTelemetry protocol (OTLP).

Metric	Description
openclaw.tokens	Token usage by type (input, output, cache_read, cache_write)
openclaw.cost.usd	Estimated cost in USD for the API call
openclaw.run.duration_ms	Duration of the agent run in milliseconds
openclaw.session.*	Session state transitions and lifecycle events
openclaw.context.tokens	Context window usage
gen_ai.request.model	Model used for the request (e.g., claude-sonnet-4)
gen_ai.system	Provider (e.g., anthropic, openai)

💡 Privacy Note

ClawHQ only collects token counts, costs, model names, and session IDs. We never see your prompts, responses, or any content — unless you explicitly enable content capture in your OpenClaw config.

API Reference

ClawHQ exposes OTLP-compatible ingestion endpoints and a dashboard API for programmatic access (Team plan and above).

Ingestion Endpoints

POST/api/v1/otlp/metrics— Receive OTLP metrics (token counts, costs)

POST/api/v1/otlp/traces— Receive OTLP traces (span-level data)

Dashboard API (Team plan)

GET/api/dashboard/overview— Total spend, trends, top agents

GET/api/dashboard/agents— Per-agent cost breakdown

GET/api/dashboard/agents/[name]— Individual agent detail

GET/api/dashboard/models— Per-model cost comparison

Authentication

All API requests require a chq_ API key in the Authorization header:

Authorization: Bearer chq_xxxxxxxxxxxx

Budget Alerts

Budget alerts notify you when spending exceeds your defined thresholds. Available on Pro and Team plans.

Alert Scopes

•Total — Alert on your entire fleet's combined spend
•Per-Agent — Alert when a specific agent exceeds a threshold
•Per-Model — Alert when spend on a specific model exceeds a threshold

Alert Periods

•Daily — Resets at midnight UTC
•Weekly — Resets every Monday
•Monthly — Resets on the 1st

Notification Channels

•Email — Sent via Resend to your account email
•Webhook — POST to any URL with alert payload
•In-App — Visible on your dashboard

FAQ

What version of OpenClaw do I need?

OpenClaw v2026.2 or later with diagnostics support.

Does this slow down my agents?

No. Telemetry data is emitted asynchronously and has no measurable impact on agent performance.

What if I rotate my API key?

Generate a new key in Settings, update your openclaw.json, and restart your gateway. The old key is immediately deactivated.

Can I use this with multiple gateways?

Yes — all gateways using the same API key will aggregate into one dashboard. Use different agent names to distinguish them.

What happens to my data if I downgrade?

Data beyond your tier's retention period is deleted. We recommend exporting first (Pro+ plans).

Full API documentation is available

Explore our REST API for fleet management, cost tracking, skill streaming, and task automation.

Questions? Email team@clawhq.co