ClawSentinel / Documentation

Full Documentation

ClawSentinel is a macOS menu bar app that watches the OpenClaw gateway, checks whether it is healthy, runs deeper diagnostics on a schedule, and tries to recover from common failures before you have to intervene manually.

01 — Overview

What ClawSentinel does

At a high level, it does six things:

Checks the gateway regularly.
Falls back through multiple health checks so it does not panic too early.
Watches for known problem patterns such as token exhaustion, repeated restarts, and relay conflicts.
Attempts recovery automatically when the gateway is really down.
Shows status, diagnostics, metrics, logs, and settings in one menu bar popover.
Sends macOS notifications when you need to do something yourself.

ClawSentinel only starts active monitoring after the app has a valid license activation.

02 — How It Works

Health check logic

Every health check uses this order:

GET /health
If /health returns 404, try GET /
If HTTP checks still do not confirm health, try a direct TCP connection to the configured port

If any of those succeed, ClawSentinel treats the gateway as up.

Default timing

Health check interval

Default: 30 seconds

Full diagnostic interval

Default: 120 seconds

Auto-recovery trigger

2 consecutive failed health checks

Maximum automatic recovery attempts per outage

03 — Settings Reference

Every user-facing setting

These are all the settings available in ClawSentinel's Settings panel.

Gateway Host

Default: 127.0.0.1

Tells ClawSentinel which host to probe for gateway health and diagnostics. Change this only if your gateway is intentionally bound somewhere other than local loopback.

If you point it at the wrong host, ClawSentinel will report false outages and recovery actions may target the wrong endpoint.

Gateway Port

Default: 18789

Tells ClawSentinel which TCP port belongs to the gateway. Change this if your gateway is configured to listen on a different port.

If this does not match the real gateway port, health checks, conflict detection, and recovery logic will all be looking in the wrong place.

Health Check Interval

Default: 30 seconds

Controls how often ClawSentinel performs the lightweight gateway health check. Lower it for faster outage detection; raise it for less frequent polling.

Lower values catch failures sooner but create more background activity. Higher values reduce noise but delay alerts and auto-recovery.

Full Diagnostic Interval

Default: 120 seconds

Controls how often ClawSentinel runs deeper diagnostics — token usage, version checks, and conflict checks.

Lower values give earlier warnings but run more subprocesses and network calls. Higher values are quieter but may delay detection of non-fatal problems.

Token Warning

Default: 80%

Sets when token usage starts showing a warning state in diagnostics.

Lower thresholds are safer but noisier. Higher thresholds reduce warnings but may leave less time to reset the session cleanly.

Token Critical

Default: 90%

Sets when token usage becomes critical in diagnostics.

Lower values warn earlier. Higher values reduce alerts but increase the chance the agent becomes sluggish before you act.

Enable Notifications

Default: On

Allows ClawSentinel to send standard macOS alerts and sounds.

Turning it off reduces interruptions, but you may miss recovery failures or session-reset warnings when the menu is closed.

Enable Auto-Recovery

Default: On

Lets ClawSentinel take action automatically after repeated failed health checks.

On = less downtime. Off = all recovery is manual, but avoids automatic restarts and process kills.

Enable Diagnostic Auto-Fix

Default: On

Lets the diagnostics engine automatically repair certain detected issues.

On can save time. Off is safer when you are actively debugging and do not want ClawSentinel changing the environment.

Custom openclaw Path

Default: blank (auto-detect)

Overrides the path ClawSentinel uses to run the openclaw CLI. Use if OpenClaw is installed in a non-standard location.

A wrong override breaks every CLI-driven check and repair action.

Custom node Path

Default: blank (auto-detect)

Overrides the path ClawSentinel uses to run node when openclaw is installed as a Node.js script.

Necessary for some npm-based installs. An incorrect path prevents script-based OpenClaw commands from running.

Reset to Defaults

One-click action

Clears all saved settings and restores built-in defaults. Use if the app is behaving oddly after configuration changes.

You will lose custom host, port, interval, threshold, and CLI-path overrides.

Deactivate License

Account action

Removes this Mac's activation locally and asks the license server to release the activation remotely. Use before moving to a new Mac or troubleshooting license-seat issues.

After deactivation, the app stops monitoring until the license is activated again.

04 — Recovery Logic

How ClawSentinel recovers

ClawSentinel does not attempt recovery on the first missed check. It waits for two consecutive failures so short hiccups do not trigger unnecessary repairs.

Once recovery starts, ClawSentinel uses a smart decision tree instead of blindly running openclaw gateway restart.

Recovery Decision Tree

Port conflict detected

Checks: Looks for a listening process on the configured gateway port. If that process does not look like the OpenClaw gateway, treats it as a port conflict.

Action: Logs the reason, terminates the conflicting process, then runs the normal gateway restart.

LaunchAgent not registered

Checks: Verifies the LaunchAgent plist exists, then asks launchctl whether the service is actually registered.

Action: If the plist exists but launchctl does not know about the service, runs launchctl bootstrap gui/<uid> <plist> to re-register it, then restarts the gateway.

CPU or memory spike

Checks: Inspects the running gateway process. Flags usage above 80% CPU or 2 GB RAM as a possible self-recovering spike.

Action: Logs the spike, waits 30 seconds, checks again, and only restarts if the gateway is still unhealthy.

Token exhaustion

Checks: Refreshes session token usage from the gateway status endpoint.

Action: If token usage is over 95%, does not restart the gateway. Logs the reason and sends a notification to run /new in Telegram.

Gateway process absent

Checks: If no gateway process can be found at all, treats it as a missing-process case.

Action: Logs the reason and follows the normal restart flow.

Gateway present but unresponsive

Checks: If the gateway exists but none of the smarter preflight checks match, treats it as a plain unresponsive gateway.

Action: Logs the reason and runs the normal restart command.

Normal Restart Flow

When ClawSentinel reaches the normal restart flow, it runs:

openclaw gateway restart

The app uses its binary discovery logic first, so it can work with Homebrew installs, npm installs, and custom override paths from Settings.

Silent Restart Failure Handling

ClawSentinel also verifies that a restart actually worked.

It waits up to 15 seconds for the gateway to respond.
If the gateway still does not respond, it retries the restart once.
If the second attempt also fails, it marks the gateway as down and alerts the user.

This prevents false confidence from a restart command that exits successfully but does not really restore service.

Recovery Logging

For every recovery case, ClawSentinel appends a clear log line to ~/.openclaw/logs/gateway.log. The Logs tab shows entries explaining:

Why a process was killed
Why a LaunchAgent was bootstrapped
Why ClawSentinel waited instead of restarting immediately
Why it skipped restart and asked for /new
Why it retried a restart verification

05 — Failure Modes

17 documented failure modes

The codebase has two sources of truth: the shipped Swift code actively detects a smaller set of issues in real time, and the app also defines a broader list of 17 documented failure-mode names. Each entry below tells you which it is.

FM-01

Session Token Exhaustion Active

Reads /api/v1/session/status and calculates percentage used. Warns at the configured threshold, becomes critical at the critical threshold, and skips restart when usage is over 95%, sending a notification to run /new.

If auto-fix fails: Run /new in Telegram, then confirm the session token percentage drops.

FM-02

Stale LaunchAgent Plist Active

Counts restart events and treats more than two restarts in one hour as a stale-service pattern. If diagnostic auto-fix is enabled, runs openclaw gateway install --force.

If auto-fix fails: Reinstall the gateway service manually, confirm the plist path is current, and restart the gateway.

FM-03

Desktop App Conflict Active

Looks for OpenClaw.app and watches for repeated gateway restarts. If the desktop app looks like the conflict source, terminates that app process.

If auto-fix fails: Quit OpenClaw.app fully, make sure only one controller is managing the gateway, and restart the gateway.

FM-04

LaunchAgent Unregistered Active

The LaunchAgent plist exists, but launchctl print gui/<uid>/ai.openclaw.gateway says the service is not known. Runs launchctl bootstrap with the plist path, then restarts the gateway.

If auto-fix fails: Bootstrap the service manually, confirm the plist is valid, and check launchctl print again.

FM-05

Port Conflict (Zombie Process) Active

Checks which PID is listening on the configured gateway port and compares that process to the expected gateway. Kills the conflicting listener first, then restarts the gateway.

If auto-fix fails: Use lsof -nP -iTCP:<port> -sTCP:LISTEN to identify the process, stop it manually, and retry the gateway restart.

FM-06

Memory/CPU Resource Leak Active

Inspects the gateway process and flags usage above 80% CPU or 2 GB RAM. Waits 30 seconds for self-recovery, then restarts only if the gateway is still unhealthy.

If auto-fix fails: Check what the gateway was doing at the time, restart manually, and consider shortening session length or reducing workload.

FM-07

Restart Registration Failed Planned

Named failure-mode slot in the code, but no dedicated live detector is currently implemented. No separate automatic action yet beyond the broader LaunchAgent recovery path.

Treat it like a LaunchAgent or service-registration issue and re-register the service manually.

FM-08

Tailscale Bind Conflict Planned

No live detector is currently implemented in the shipped Swift code. No automatic fix yet.

Verify that Tailscale or another network overlay is not changing the expected bind address or port, then restart the gateway with the correct bind settings.

FM-09

Config/Binary Version Mismatch Active

Compares the installed OpenClaw binary version with the version found in ~/.openclaw/config.toml. Raises a diagnostic issue and, when auto-fix is enabled, triggers the update flow.

If auto-fix fails: Run the OpenClaw update manually and verify that config and binary versions match.

FM-10

Orphaned Chromium Processes Planned

No live detector is currently implemented in the shipped Swift code. No automatic cleanup yet.

Look for stray Chromium or Chrome-for-Testing processes and terminate the ones that should no longer exist.

FM-11

MCP Zombie Processes Planned

No live detector is currently implemented in the shipped Swift code. No automatic fix yet.

Identify stuck MCP-related processes and terminate them manually.

FM-12

Relay Conflicts Active

Looks for multiple relay processes and checks for an EasyClaw Chrome extension install. Raises a diagnostic issue and alerts the user. Does not disable extensions automatically.

If auto-fix fails: Disable duplicate relays, remove or disable EasyClaw, and keep only one active relay path.

FM-13

Telegram Channel Degraded Planned

No dedicated live detector is currently implemented in the shipped Swift code. No automatic fix yet.

Check the Telegram integration separately and confirm that the channel is reachable from OpenClaw.

FM-14

Cron/Heartbeat Blocked Planned

No dedicated live detector is currently implemented in the shipped Swift code. No automatic fix yet.

Verify your cron or heartbeat process manually and confirm scheduled jobs are still running.

FM-15

Version Drift Active

Compares the installed OpenClaw version to the result of openclaw version --check-latest. Raises a low-severity issue and sends an update notification.

If auto-fix fails: Update OpenClaw manually when convenient.

FM-16

Network Communication Failure Partial

The gateway monitor surfaces network failures (timeouts, host lookup failures, connection failures), but there is no separate dedicated diagnostic issue pipeline for this named bucket yet. Marks the gateway down and may enter the recovery decision tree.

If auto-fix fails: Verify host and port settings, confirm the gateway is reachable locally, and check whether another process or firewall rule is interfering.

FM-17

Agent Response Timeout Active

Actively detected, but exposed as a generic diagnostic issue rather than one of the numbered product-table entries. Runs openclaw gateway health --expect-final --timeout <ms> and tracks consecutive failures and slow responses. Surfaces warnings for slow responses, raises critical issue after repeated timeouts.

If auto-fix fails: Check token usage, verify the gateway is still responsive, and reset the session if the agent is stuck.

06 — Logs Tab

Reading the gateway log

The Logs tab is a simple viewer for the gateway log file at:

~/.openclaw/logs/gateway.log

What you can do there

Read the last 100 log lines
Filter by log level
Search within the visible logs
Clear the in-memory view without deleting the underlying log file
Export the currently filtered view to a plain text file
Refresh the view manually

Log levels

ERROR Something failed or recovery did not work.

WARN Something needs attention or ClawSentinel is taking a protective action.

INFO Normal operating information, including recovery reasons and successful actions.

DEBUG Extra detail, if the gateway writes debug-level entries.

ALL Shows everything in the viewer.

Export behavior

The Export button writes the currently visible, filtered lines. If you have a level filter or search filter active, the export reflects that filtered view rather than the whole file.

07 — License

Activation & licensing

ClawSentinel uses LemonSqueezy-backed activation. The app stores the key in the macOS Keychain and keeps a small amount of activation state in user defaults.

Price

$7.99

One-time purchase. No subscription.

Devices

Deactivate an old machine to free up a seat.

Offline Grace

7 days

Works offline if the license server is unreachable.

Activation

Enter your license key in the activation screen.
If activation succeeds, ClawSentinel stores the key securely and starts monitoring.
The app revalidates periodically in the background.

Deactivation

Use the Deactivate License button in Settings before moving to another Mac whenever possible.
Deactivation clears the local key and asks the server to release this machine's activation.

Transfer to a new Mac

Deactivate on the old Mac.
Install ClawSentinel on the new Mac.
Activate with the same license key there.

08 — Troubleshooting

Common problems

ClawSentinel says the gateway is down, but you know it is running

Check that Gateway Host and Gateway Port match the real OpenClaw gateway.
Open the Logs tab and look for a recovery-reason line from ClawSentinel.
If the port is wrong, ClawSentinel may be watching the wrong service.

ClawSentinel cannot find openclaw

Open Settings and set the custom openclaw path.
If your install is script-based, also set the node path.
This is common with non-standard npm or local installs.

The app keeps wanting to restart the gateway

Open Diagnostics and check for token exhaustion, relay conflicts, or repeated restarts.
Look for a port-conflict or resource-spike entry in the Logs tab.
If the gateway is actually overloaded, a restart may only be a symptom fix.

Restart says it worked, but the gateway still does not come back

ClawSentinel verifies restart success for 15 seconds and retries once.
If that still fails, inspect launchctl, the gateway log, and the configured CLI path.
A successful command exit does not always mean the service really came back.

Token warnings keep appearing

Send /new in Telegram.
This is usually a session-length problem, not a gateway-process problem.
Restarting the gateway is intentionally skipped in the >95% exhaustion case.

Notifications are not showing

Confirm Enable Notifications is on in Settings.
Confirm macOS notification permissions for ClawSentinel are allowed.
The app still works without notifications, but you will need to rely on the UI instead.

Logs tab is empty

The viewer only shows what exists in ~/.openclaw/logs/gateway.log.
If the gateway has never written that file yet, the tab will say so.
Refresh after the gateway or ClawSentinel has had time to append new lines.

License stopped validating

Check internet connectivity.
If you are within the 7-day grace window, the app can keep working temporarily.
If grace has expired, reactivate the license.