Why logging
is crucial

Running OpenClaw in production without observability is like flying blind: Gateway logs, approval audit trails, browser tool traces, and Docker/journald correlation are how you truly debug stuck agents, injection attempts, and restart loops.

✓ audit trails
✓ Gateway + Docker
✓ approval queue
✓ Product debugging

direct answer

Why do you have to
Monitor OpenClaw?

Short answer: Because failures often reside in tools, approvals, and infrastructure — not in “the model is not responding.” Without logs, you don’t see stuck queues, WebSocket drops, or who approved a destructive action.

Nuance: Monitoring ≠ uptime only. AI agent observability encompasses behavioral patterns: retries, browser timeouts, runaway workflows. That is governance, not vanity metrics.

problems · docker · approvals

logs
tools
audit
approve
Alert
queue
Correlate
GW+Docker

observability

What you need to log

approvals

Pending, granted, denied — actor, timestamp, payload (command, URL, mail-subject), audit id. Without this, “AI does nothing” looks like an outage.

Browser actions

navigate, click, submit — target URL, selector summary, outcome. Connect Browser automation incidents

Terminal execution

Command, exit code, stderr snippet — never full secrets in plain text.

API / upstream calls

Provider (Anthropic, OpenAI-compatible, Ollama), HTTP status, latency — no API keys in logs.

Workflow events

Step start/end, workflow id, channel — for workflow regressions

Failures & escalations

tool denied, timeout, WebSocket disconnect, restart — with correlation id over Gateway + container.

AI agents

Why AI agents need extra monitoring

Short answer: probabilistic plans + autonomous tool execution = failure modes that lack classic app metrics.

  • → Hallucinated plans that are presented as valid tool calls.
  • → Autonomous retries without a cap → rate limits and approval spam.
  • → Browser instability: hang, OOM, CAPTCHA — Gateway “healthy”, agent silent.
  • → Prompt injection attempts visible as unusual tool sequences.
  • → Cascading failures: mail trigger → browser timeout → stuck approval → queue growth.

Debugging

Logs & terminal-first debugging

terminal
openclaw logs --follow

Expected: Gateway ready, agent runs, tool calls

If incorrect: silent after inbound → approvals or dead service

Next: openclaw gateway status && openclaw doctor

terminal
journalctl -u openclaw-gateway -f

Expected: systemd Gateway logs on bare metal

If incorrect: restart-loop → config/auth before metrics

Next: journalctl -u openclaw-gateway -n 100 --no-pager

terminal
docker compose logs -f --tail=100

Expected: container stdout + health context

If incorrect: only OOM/restart → docker RAM/healthz

Next: docker compose ps && curl …/healthz

terminal
openclaw channels status --probe

Expected: channels connected

If incorrect: disconnect → WebSocket/proxy

Next: see problems

governance

audit trails
& accountability

Short answer: Logs for operators; audit trails for whom decided about mutating agent actions.

  • ✓ Who approved which destructive command — user id, not just “approved”.
  • ✓ Immutable or append-only retention for compliance windows.
  • ✓ Reviewability: export audit trail in case of an incident without product secrets.
  • ✓ Rollback: config/image pin linked to deploy audit ID.
  • ✓ Accountability: separation of dev/prod agents in log labels.
📋 Minimum audit fields
  • timestamp (UTC)
  • actor (user/service)
  • action type + payload hash
  • workflow/channel correlation id
  • grant/deny + policy version

Production

Monitoring in production

Health & uptime

  • →/healthz on Gateway — alert for non-200
  • →systemd/Docker restart count — no “silent” crash loop
  • →WebSocket/channel probe periodically

Queues & workers

  • →Approval queue depth — alert above threshold
  • →Browser worker memory — Docker stats or host metrics
  • →Workflow step failure rate per 24h

Alerts (SME realistic)

  • →Gateway not ready > 2 min
  • →Pending approvals > N without human action
  • →Repeated browser tool timeout (>5/h)
  • →OOM / Exit 137 on container

Signals

When agents become unreliable

Retry loops

Same tool call 50x — often CAPTCHA, selector miss, or injection-driven plan.

Runaway workflows

Mail storm triggers hundreds of runs — no rate limit on triggers.

Broken approvals

Queue full, no one is getting notified — agent seems “broken”.

Memory pressure

Heap warnings → silent restart — correlate with browser + Gateway on one VPS.

Zombie containers

Old browser/Gateway container next to compose stack — port conflict, incorrect logs.

Operational

Common monitoring mistakes

  • ✕ No audit log on approve/deny — post-mortem incident impossible
  • ✕ Only “AI said X” without tool payload
  • ✕ Do not save logs (journald vacuum, Docker log driver default small)
  • ✕ No restart loop alert — discovered by user
  • ✕ Browser worker crashes not monitored — Gateway logs appear normal
  • ✕ Approvals pending not in dashboard — incorrect “model down” diagnosis
  • ✕ Prompt injection not recognized — no alert for strange tool chains

FAQ

Logs &
monitoring FAQ

Instant answer per question — snippets and AI overviews.

Troubleshooting →

Short answer: AI agents are not deterministic — logs show tool calls, approvals, and failures that you need for debugging and governance.

Cause: Chat output alone is insufficient for production.

Advice: log Gateway + tools + approvals with correlation id.

Short answer: Approvals, browser/terminal/API tools, workflow steps, WebSocket disconnects, restarts — with actor and timestamp.

Cause: Mutating acts without audit = compliance gap.

Advice: no secrets in plain text.

Short answer: Per action URL + outcome + timeout rate; worker RAM; approval on submit.

Cause: DOM/hang not visible in Gateway-only logs.

Advice: Browser automation metrics

Short answer: Usually failed healthz, OOM, or Gateway crash — read Docker compose logs before restart.

Cause: config, memory, double Gateway.

Advice: docker + problems.

Short answer: Immutable (or append-only) records of who performed which tool/approval — accountability, not “the AI decided”.

Cause: regulation and internal post-mortems.

Advice: approvals Logging required on prod.

Short answer: Abnormal tool sequences after mail/browse — unexpected shell, export, admin URLs; not a perfect detector, but logging + alerts.

Cause: Injection triggers plans, not a “virus signature”.

Advice: safety + deny rules on tools.

Short answer: Without an approve/deny audit, you do not know whether an action was caused by people or policy — a critical point regarding destructive steps.

Cause: pending queue masks as AI failure.

Advice: alert on queue depth + log every state change.

observability

Monitoring & audit
have it furnished?

We review Gateway logging, approval audit trails, Docker/journald retention, and alerts on queue depth, restarts, and browser tool failures — for SMB stacks that are actually running OpenClaw in production. Send your current log setup (without secrets).

✓ audit trails
✓ governance
✓ Bespoke