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.
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.
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
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
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
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
openclaw channels status --probe
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.
- timestamp (UTC)
- actor (user/service)
- action type + payload hash
- workflow/channel correlation id
- grant/deny + policy version
Production
Monitoring in production
Health & uptime
- →
/healthzon 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 statsor 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
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: 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).