.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
If you run OpenClaw on a VPS it stops being a “tool you open sometimes” and turns into a small service you depend on. That changes what “working fine” means. You don’t just care that it answers in chat. You care that the Gateway stays up after reboots, that channels stay logged in, that latency does not creep up at 2 AM, that a model provider outage does not silently break half your automations.
This guide is a practical monitoring playbook for OpenClaw in production. I’m going to cover health checks, logs, metrics, tracing, dashboards and alerting. I’ll also talk about the stuff people skip until it hurts like log rotation, channel auth expiry, token spend drift and “the Gateway is up but nothing is delivering messages”.
If you are still early in your setup, two LumaDock guides pair well with monitoring work: host OpenClaw securely on a VPS and OpenClaw security best practices. Monitoring is not a replacement for good ops hygiene but it makes problems visible before users do.
What to monitor in OpenClaw production
Most monitoring setups start with CPU and RAM graphs. That’s fine but OpenClaw failure modes are often higher up the stack. I’d group monitoring into these categories:
Gateway availability and health checks
This is the boring baseline. Is the Gateway reachable? Does it pass its health endpoint? Is the configured port free or did another service steal it? OpenClaw’s own health checks are the fastest signal that something is wrong at the application level.
Message delivery and channel connectivity
“The process is running” does not mean “WhatsApp is still paired” or “Telegram bot token is still valid” or “Slack events are still flowing”. You want monitoring that catches channel disconnects and repeated delivery failures.
Latency and error rate
Users notice delays more than they notice small outages. If OpenClaw starts responding in 12 seconds instead of 2 seconds you will feel it. A good dashboard shows request rate and latency percentiles not just averages.
Model provider health and token spend
Provider outages happen. So do rate limits. So do expired OAuth tokens. Monitoring should surface when model calls fail or when you are burning more tokens than you expected. This is especially relevant if you run heartbeat or cron 24/7. If you want the “why” behind proactive runs, read OpenClaw heartbeat vs cron on a VPS.
Logs that you can actually use
Logs are either a tool or a junk drawer. In production you want structured logs with rotation so you can answer simple questions fast: what broke, when did it start, which channel did it affect, what error did the model provider return.
System-level signals
Disk usage, file descriptor exhaustion, network drops, DNS weirdness and clock drift can all produce “AI is broken” symptoms. You still want node-level monitoring. If you already run a typical VPS monitoring stack you can plug OpenClaw into it instead of inventing a new stack.
OpenClaw endpoints and local health checks
Before dashboards and alerts, get your local checks working. It makes troubleshooting way faster because you can test from the VPS itself before you blame Telegram or a reverse proxy.
Know your Gateway port and bind settings
OpenClaw runs a single Gateway port for its local web interfaces and operational endpoints. The default port referenced in OpenClaw ops tooling is 18789. If you change it, document it. You will forget it later when you are half-asleep debugging a “connection refused”.
Runbook reference: OpenClaw’s Gateway runbook includes common operational checks and it also calls out port collision diagnostics and service troubleshooting. You can keep it bookmarked as a “panic page”: OpenClaw Gateway runbook.
Use the health endpoint for a fast yes or no
OpenClaw includes a health check endpoint intended for automation and supervisors. This is the endpoint you use for systemd watchdog scripts, external uptime checkers and basic “is it alive” probes. Official docs are here: OpenClaw health checks.
From the VPS itself:
curl -fsS http://127.0.0.1:18789/healthIf you are fronting the Gateway with a reverse proxy, still keep a local loopback check. When the proxy breaks you don’t want to lose the ability to tell if OpenClaw is healthy.
Use OpenClaw Doctor as your first-line repair tool
When OpenClaw acts “haunted” the fix is often boring: legacy config keys, state directory layout drift, missing permissions, extra gateway installs, stale supervisor configs, expired auth profiles. OpenClaw ships a repair and migration tool that handles a lot of this.
Docs: OpenClaw doctor.
Common commands:
openclaw doctoropenclaw doctor --non-interactiveopenclaw doctor --repairI treat openclaw doctor like “fsck for the OpenClaw install”. It is not your monitoring system but it is what you run after an alert when you need to stabilize the box quickly.
Logging setup for production
OpenClaw monitoring becomes dramatically easier when logs are consistent. If you only do one thing from this article, do this: turn on structured logs and make sure rotation is in place.
Official docs: OpenClaw logging.
Structured logs vs plain text logs
Plain text is readable until you want to filter by agent id or channel or error class. Structured logs let you do simple parsing with tools like jq or route logs into Loki, Elasticsearch or any other log system.
If you are using journald via a systemd service you can still get structured output. If you also write to a file, rotate it. Otherwise your “monitoring” becomes “disk full at 3 AM”.
Viewing logs during an incident
In production I use two views:
- the supervisor logs (systemd or journald) to see restarts and crashes
- the application logs to see channel failures and provider errors
For a systemd user service you can tail logs like this:
journalctl --user -u openclaw-gateway -fIf you run a system service instead, drop the --user flag. Then filter for errors in the last hour:
journalctl --user -u openclaw-gateway --since "1 hour ago" -p errWhen you see repeated restarts, don’t just restart again. Look for the first error before the crash loop starts. That line is usually the real cause.
Log rotation and retention
If you log to files, enforce size limits and keep a bounded number of rotated files. If you log to journald, set journald retention and size limits so it does not eat the disk.
On Ubuntu a quick journald sanity check looks like this:
journalctl --disk-usageIf that number is scary, fix it now not “later”. Later is always when the disk is at 100%.
Metrics and tracing with OpenTelemetry
This is where OpenClaw monitoring gets interesting. OpenClaw can export diagnostics using OpenTelemetry (OTel) so you can feed metrics and traces into a real observability stack. The official logging documentation includes the diagnostics and export configuration options: OpenClaw logging and diagnostics.
Why OpenTelemetry is the sane default
OTel is not “one more thing”. It is the glue that lets you send the same signals to different backends. You can start small with an OTel Collector on the VPS and later route to Prometheus, Grafana, Tempo, Jaeger or a hosted observability provider without rewriting your app config.
What signals you actually want from OpenClaw
In a real setup, I focus on metrics that answer operator questions:
- request volume by channel and by agent
- latency percentiles so I can see p95 drift
- error rate and error types
- tool call volume and failures
- queue depth or backlog signals if your setup uses message queues
- token usage trends by model if you track spend
Tracing is optional but valuable when you run multi-step agent flows. A trace that shows “message received -> model call -> tool calls -> response” can save hours when something is slow.
Running an OpenTelemetry Collector on the VPS
A common pattern is:
- OpenClaw exports OTel data to a local Collector on
127.0.0.1 - the Collector exposes Prometheus metrics for scraping
- Grafana reads from Prometheus for dashboards
- alert rules trigger Alertmanager notifications
External docs that explain the Collector and exporters well:
Here is a minimal OTel Collector config that receives OTLP and exposes a Prometheus scrape endpoint. You will still need to wire OpenClaw to export to the Collector based on the OpenClaw logging and diagnostics options.
receivers:
otlp:
protocols:
grpc:
http:
processors:
batch:
exporters:
prometheus:
endpoint: "127.0.0.1:9464"
service:
pipelines:
metrics:
receivers: [otlp]
processors: [batch]
exporters: [prometheus]Then Prometheus scrapes 127.0.0.1:9464. Keep it loopback-only unless you have a good reason to expose it.
System metrics on the same dashboards
OpenClaw metrics without node metrics can be misleading. If latency jumps, is it model provider slowdown or is your VPS swapping? You want both views on the same screen.
The usual approach is node_exporter. Official docs: Prometheus node_exporter.
Basic install on Ubuntu often looks like “install package or run a container” depending on how you manage the box. If you already have node_exporter installed, great. If you don’t, install it and lock it down to localhost or a private monitoring network.
Prometheus scrape config example
This is intentionally boring. Boring is good in monitoring configs.
global:
scrape_interval: 15s
scrape_configs:
- job_name: "openclaw-otel"
static_configs:
- targets: ["127.0.0.1:9464"]
- job_name: "node"
static_configs:
- targets: ["127.0.0.1:9100"]At this point you have enough to build dashboards and alerts.
Grafana dashboards that you will keep using
A dashboard that looks pretty and a dashboard that helps during an incident are different things. I want a front page that answers these questions in under 10 seconds:
- is OpenClaw up
- are messages flowing
- is it slow
- is it erroring
- is the VPS in trouble
Recommended panels for an OpenClaw overview
Gateway availability
Show an “up” metric for the Collector scrape and node_exporter scrape. If either is down, alert. If OpenClaw is down but the VPS is up, that is an application incident. If both are down, that is a host incident.
Request rate by channel
This shows if traffic dropped to zero or spiked. Spikes can mean a loop in an automation or a group chat meltdown.
Latency percentiles
p50 is nice but p95 is what users feel. If p95 jumps, dig into traces and logs.
Error rate
Graph errors and annotate deploys or config changes. People underestimate how useful a “changed config at 14:02” annotation is when you are debugging at 14:10.
Tool call volume
If your agent suddenly starts calling a tool 10x more than normal, that is worth investigating. It can be a prompt drift problem or a new automation.
Host CPU, RAM, disk, load average
Simple system graphs catch a lot: runaway processes, memory leaks, disk filling from logs or media attachments.
Don’t forget alert annotations and runbooks
If you use Grafana alerting or Prometheus Alertmanager, add a runbook link in each alert description. Even a small runbook is useful. You can point to internal docs, a private wiki or a public guide. If you are writing internal runbooks, reuse the “fault diagnosis” approach from OpenClaw’s runbook and doctor docs because they are already structured around real failure cases.
Alerting rules for the OpenClaw reality
Most people alert on CPU. For OpenClaw, I care more about “is it answering” and “is it delivering” and “is it broken in a way I will not notice”.
Gateway health check alert
Use an active probe. The clean option is the Prometheus blackbox exporter or a simple curl-based health check script feeding a metric. If the health endpoint fails for a minute, alert.
External reference: Prometheus blackbox exporter.
Restart loop alert
If the service restarts repeatedly, you want to know quickly. A restart loop often means “bad config” or “auth store permissions” or “port collision”. OpenClaw doctor explicitly includes port collision diagnostics and supervisor audits which is why it belongs in your response playbook.
Channel disconnect alert
If your business relies on WhatsApp or Slack messages, channel health is not optional. The specific metric names depend on how you export diagnostics. The idea is consistent: alert when channel status becomes unhealthy or when delivery failures spike.
Channel setups are covered in other LumaDock tutorials. If you want to tighten production WhatsApp, read OpenClaw WhatsApp production setup. For multi-channel routing, OpenClaw multi-channel setup helps.
Latency regression alert
Set a p95 latency threshold that reflects your environment. Don’t set it to 1 second if your model provider averages 3 seconds. You will train yourself to ignore alerts.
I usually start with:
- warning if p95 is above 6 to 8 seconds for 10 minutes
- critical if p95 is above 15 seconds for 5 minutes
Then adjust after you have a week of baseline data.
Token spend drift alert
If you run heartbeat and cron, token spend can creep up from small config edits. If you have metrics for token usage, alert on daily usage above a budget threshold. That is the difference between “nice automation” and “why is my bill double”.
If you want a clean mental model for proactive tasks, use OpenClaw cron scheduler guide and OpenClaw heartbeat vs cron on a VPS.
External uptime checks and synthetic monitoring
Internal monitoring is necessary but it won’t catch a dead firewall rule or a broken reverse proxy. I like running at least one external check that hits a public endpoint. If you do not want to expose the Gateway directly, you can expose a tiny health proxy endpoint that only returns “ok” and protects everything else behind auth.
If you run a reverse proxy anyway, this is where you add a minimal location and lock it down by IP allowlist or a secret header. Keep it simple.
Self-healing for the boring failures
Self-healing is a loaded topic. In practice, I only automate fixes for failures that are safe and obvious. For example, “process is down” can be safely handled by systemd restart policies. “model provider is rate limiting” cannot be solved by restarts.
Systemd restart policy
Make sure your service has a reasonable restart policy and a small delay. A restart loop that hammers a provider can cause more trouble than the original failure.
When I actually run repair commands automatically
I don’t run openclaw doctor --repair --force automatically. That one can overwrite supervisor configs. It is intended for humans. What I will run unattended is openclaw doctor --non-interactive in a maintenance window if I know I am upgrading or migrating and I want to normalize state. The Doctor docs explain the difference between non-interactive safe migrations and aggressive repairs.
Common production incidents and how I debug them
Gateway is running but nothing replies
I check these in order:
- local health endpoint returns 200
- logs show inbound messages arriving
- provider auth is valid and not expired
- channel status is healthy
Then I run openclaw doctor because it catches stale configs, broken state directories and channel auth issues that are easy to miss when you are guessing.
High latency that started “randomly”
Most “random” latency is a resource issue or a provider issue. I look at VPS load and memory pressure first. If the host is fine, I look at model provider errors and rate limit logs. If you have tracing, this is where it shines because you can see which step is slow.
Disk fills up over a weekend
Common causes:
- logs without rotation
- media attachments saved locally without cleanup
- debug logging left enabled
This is also why backups matter. If you want a full backup plan for state, workspaces and memory use OpenClaw backup and export. It is not a monitoring guide but it prevents “we lost everything” situations.
Monitoring in multi-agent setups
Multi-agent is great but it adds more surfaces to watch. You now care about per-agent session counts, per-agent tool failure rates and per-agent model routing. If you want a refresher on how agents and sub-agents behave in OpenClaw, read OpenClaw multi-agent setup.
Two practical notes:
- separate dashboards or dashboard filters by agent id save time during incidents
- don’t let one noisy agent hide failures in a quieter agent. This happens when you only look at totals
Hardening notes that affect monitoring
Monitoring touches security because observability endpoints and log stores can leak sensitive data. Treat diagnostics like production data. If you export traces, scrub anything that includes message content unless you are sure it is safe.
If you are exposing any web UI remotely, follow the approach in OpenClaw API proxy setup so you have a controlled boundary instead of a raw exposed port.
Practical checklist for a first production monitoring pass
- verify local health checks work with curl on the VPS
- enable structured logs and enforce rotation or journald retention
- install node_exporter and scrape it locally
- export OpenClaw diagnostics via OpenTelemetry to a local Collector
- scrape the Collector with Prometheus and build a basic Grafana overview
- add alerts for health failures, restart loops, sustained latency and disk pressure
- document a short incident flow that starts with logs and openclaw doctor
