OpenClaw Status Command: Check Gateway Health in One Command

Thirty seconds after something breaks, you want to know what failed, which channels are affected, and whether the gateway is even alive. The openclaw status command answers all three in a single output. We've used it in incident response for production deployments handling 50,000+ messages per day — it consistently surfaces the root cause in the first glance.

Reading the Basic Output

Run the command with no flags:

openclaw status

The output looks like this:

OpenClaw Gateway Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Status:      ● HEALTHY
  Version:     1.0.0
  Uptime:      3d 14h 22m
  Memory:      142 MB / 512 MB
  Active Agents: 2

Channels
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ telegram        connected    last msg: 2m ago
  ✓ slack           connected    last msg: 18m ago
  ✗ imessage        error        failed: token expired

LLM Providers
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ anthropic       reachable    latency: 340ms
  - openai          not configured

The overall status at the top is the key signal. HEALTHY means everything is operating normally. DEGRADED means the gateway is running but at least one channel or provider has an issue. ERROR means a critical failure that's likely preventing agents from operating.

Understanding Channel Status

Each channel entry has a status indicator and additional context:

• ✓ connected — channel is connected and receiving messages normally
• ⚠ degraded — connected but with elevated error rate or latency
• ✗ error — connection failed; message shows the specific failure reason
• ○ disconnected — channel is registered but not currently active
• - not configured — channel type exists but no credentials provided

When a channel shows error, the failure reason is the most important field. Common reasons and what they mean:

• token expired — refresh or regenerate the API token in your channel provider settings
• webhook not reachable — the public URL in your gateway config is not accessible from the provider's servers
• rate limit exceeded — too many API calls; check your provider plan limits
• connection refused — network issue between the gateway and the channel provider's API

JSON Output for Automation

For scripting and monitoring integration, use JSON output:

openclaw status --output json

Example output:

{
  "status": "degraded",
  "version": "1.0.0",
  "uptime_seconds": 306120,
  "memory_mb": 142,
  "active_agents": 2,
  "channels": [
    {
      "id": "telegram",
      "status": "connected",
      "last_message_at": "2025-01-30T14:22:18Z",
      "error_count": 0
    },
    {
      "id": "imessage",
      "status": "error",
      "error": "token expired",
      "error_count": 47
    }
  ],
  "providers": [
    {
      "id": "anthropic",
      "status": "reachable",
      "latency_ms": 340
    }
  ]
}

Parse this with jq for specific fields:

# Check overall status
openclaw status --output json | jq -r '.status'

# Get all channels with errors
openclaw status --output json | jq '.channels[] | select(.status == "error")'

# Get gateway uptime in hours
openclaw status --output json | jq '.uptime_seconds / 3600 | floor'

Use in Monitoring and Health Checks

The most common use case for JSON output is a monitoring health check script. Here's a production-tested pattern:

#!/bin/bash
STATUS=$(openclaw status --output json | jq -r '.status')

case "$STATUS" in
  "ok")
    echo "OpenClaw: healthy"
    exit 0
    ;;
  "degraded")
    echo "OpenClaw: degraded - check channels"
    # Send alert to Slack or PagerDuty
    exit 1
    ;;
  "error"|*)
    echo "OpenClaw: CRITICAL - gateway may be down"
    # Page on-call
    exit 2
    ;;
esac

Schedule this with cron every 5 minutes and pipe failures to your alerting system. As of early 2025, this is how most production OpenClaw deployments handle automated monitoring.

Exit Codes

When the Gateway Is Not Running

If the status command returns "gateway not running", the connection to the gateway API failed. Work through this checklist:

1. Is the gateway process running? Check: systemctl status openclaw or ps aux | grep openclaw
2. Is it listening on the expected port? Check: ss -tlnp | grep 8080
3. Did you specify a custom host/port? Add: openclaw status --host localhost --port 8081
4. Is there a firewall blocking localhost connections? Rare but possible with strict iptables configs

Common Mistakes

• Ignoring degraded status — a degraded gateway is partially broken; don't wait for ERROR to investigate
• Not checking exit codes in scripts — openclaw status exit codes are meaningful; always use $? in monitoring scripts
• Running status on wrong host — if your gateway is on a remote server, the status command must run there, not locally
• Missing --output json for automation — the text output format can change between versions; JSON is stable and parseable

Frequently Asked Questions

What does openclaw status show?

The status command shows gateway uptime, version, connected channels and their state (connected/disconnected/error), active agent count, memory usage, last heartbeat time, and LLM provider connectivity. It's the fastest way to get a complete health snapshot of your OpenClaw installation.

How do I get openclaw status output as JSON?

Run: openclaw status --output json. This outputs a machine-readable JSON object with all status fields. Use this for monitoring scripts, health checks in CI pipelines, or feeding status data into external monitoring tools like Datadog or PagerDuty.

What does a red channel status mean in openclaw status?

A red or 'error' channel status means the channel is registered but cannot connect — typically a bad token, expired webhook, or network issue. Check the specific error message shown next to the channel name, then verify the credentials in gateway.yaml and restart the gateway.

Can I run openclaw status in a monitoring script?

Yes. Use --output json and parse the result with jq or any JSON parser. Check the top-level 'status' field — 'ok' means all systems healthy, 'degraded' means partial issues, 'error' means critical failure. Exit codes: 0 for ok, 1 for degraded, 2 for error — useful for shell script conditionals.

How do I check if a specific channel is connected with openclaw status?

Run openclaw status --channel telegram. This shows the detailed status for that channel only: connection state, last message time, error count, and webhook URL if applicable. Omitting --channel shows all channels in a summary view.

Why does openclaw status show 'gateway not running'?

This means the status command cannot reach the gateway process. Either the gateway isn't started (run: openclaw gateway start) or it's running on a non-default port/address (specify with --host and --port flags). If started via systemd, check: systemctl status openclaw.