Bot Status API

Deploy a lightweight status API that exposes your OpenClaw bot's runtime health, service connectivity, cron jobs, skills, system metrics, and more. Use when setting up a monitoring dashboard, health endpoint, or status page for an OpenClaw agent. Supports any services via config (HTTP checks, CLI commands, file checks). Zero dependencies — Node.js only.

Security Scan

The skill is internally consistent with its stated purpose (a local status/health API for an OpenClaw agent), but it performs extensive local file reads and executes shell commands based on configuration and discovered skill metadata — so review config and run it with least privilege before deploying publicly.

Purpose & Capability

The code implements a status API that collects bot core vitals, services checks (HTTP/command/file), email unread counts via configured commands, cron jobs, Docker/Portainer containers, dev-server processes, installed skills, and /proc system metrics — all match the description.

Instruction Scope

Instructions and code intentionally read OpenClaw files (heartbeat-state.json, cron/jobs.json, auth-profiles.json), scan skill directories, and run configured shell commands for service/email checks. This fits monitoring use but means the skill will read potentially sensitive local files and run arbitrary commands specified in config.

Install Mechanism

No install spec (instruction-only install). Source files are provided and intended to be copied/run by the user; nothing is fetched from external URLs during install.

Credentials

The skill declares no required env vars or credentials, which matches the bundle. However server.js sets NODE_TLS_REJECT_UNAUTHORIZED=0 (disables TLS verification globally) and the collectors read agent files (auth-profiles.json) and arbitrary paths from config. Those behaviors are explainable by Portainer/self-signed setups and local monitoring, but they broaden the data and network trust surface.

Persistence & Privilege

always is false and the skill does not attempt to modify other skills or system-wide agent configs. It is a standalone service the user runs (systemd instructions are optional).

Assessment

This skill is coherent for local monitoring, but it reads local OpenClaw files and runs shell commands you configure — so review and harden before use. Key things to consider before installing: - Inspect config.json: service checks of type "command" and email accounts execute whatever commands you put there; treat these as powerful and only use trusted commands. - Least privilege: run the service under a dedicated low-privilege user so it cannot read unrelated sensitive files. Do not run as root. - Sensitive files access: the collectors read files under your OpenClaw home/workspace (heartbeat-state.json, cron/jobs.json, auth-profiles.json). Ensure you’re comfortable exposing those contents via the /status endpoint locally or to any network. - Public exposure: /status returns system metrics, skill lists, cron job metadata and service summary. Avoid binding to a public network or put it behind authentication/reverse proxy if you must expose it externally. - Command injection / unsanitized exec: services.checkFileExists uses exec(`ls ${svc.path}`) and other code runs user-supplied commands and `which` on discovered bin names. Make sure service paths and skill directories are trusted and not writable by untrusted users. - TLS behavior: the server forces NODE_TLS_REJECT_UNAUTHORIZED=0 to allow self-signed Portainer connections; this disables TLS validation globally. Prefer configuring Portainer with proper certs or carefully restrict network access if you keep this behavior. If you want a safer deployment: run on localhost only, restrict via firewall, remove/replace the global TLS-disable line, and avoid adding untrusted skillDirs or service commands to config.json.

A configurable HTTP service that exposes your OpenClaw bot's operational status as JSON. Designed for dashboard integration, monitoring, and transparency.

What It Provides

• Bot Core: Online status, model, context usage, uptime, heartbeat timing
• Services: Health checks for any HTTP endpoint, CLI tool, or file path
• Email: Unread counts from any email provider (himalaya, gog, etc.)
• Cron Jobs: Reads directly from OpenClaw's cron/jobs.json
• Docker: Container health via Portainer API
• Dev Servers: Auto-detects running dev servers by process grep
• Skills: Lists installed and available OpenClaw skills
• System: CPU, RAM, Disk metrics from /proc

Setup

1. Copy the service files

Copy server.js, collectors/, and package.json to your desired location.

2. Create config.json

Copy config.example.json to config.json and customize:

{
  "port": 3200,
  "name": "MyBot",
  "workspace": "/path/to/.openclaw/workspace",
  "openclawHome": "/path/to/.openclaw",
  "cache": { "ttlMs": 10000 },
  "model": "claude-sonnet-4-20250514",
  "skillDirs": ["/path/to/openclaw/skills"],
  "services": [
    { "name": "myservice", "type": "http", "url": "http://...", "healthPath": "/health" }
  ]
}

Service Check Types

Type	Description	Config
http	Fetch URL, check HTTP 200	url, healthPath, method, headers, body
command	Run shell command, check exit 0	command, timeout
file-exists	Check path exists	path

3. Run

node server.js

4. Persist (systemd user service)

# ~/.config/systemd/user/bot-status.service
[Unit]
Description=Bot Status API
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/bot-status
ExecStart=/usr/bin/node server.js
Restart=always
RestartSec=5
Environment=PORT=3200
Environment=HOME=/home/youruser
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now bot-status
loginctl enable-linger $USER  # survive logout

5. Context/Vitals from OpenClaw

The bot should periodically write vitals to heartbeat-state.json in its workspace:

{
  "vitals": {
    "contextPercent": 62,
    "contextUsed": 124000,
    "contextMax": 200000,
    "model": "claude-opus-4-5",
    "updatedAt": 1770304500000
  }
}

Add this to your HEARTBEAT.md so the bot updates it each heartbeat cycle.

Endpoints

Endpoint	Description
GET /status	Full status JSON (cached)
GET /health	Simple {"status":"ok"}

Architecture

• Zero dependencies — Node.js built-ins only (http, fs, child_process)
• Non-blocking — All shell commands use async exec, never execSync
• Background refresh — Cache refreshes on interval, requests always served from cache instantly (~10ms)
• Config-driven — Everything in config.json, no hardcoded values