Sentinel Troubleshooting — AI Agent Security

Symptom

Running `openclaw plugins install @sentinel-agents/sentinel` on Windows fails with "Error: spawn EINVAL" during the dependency install step.

Cause

This is a known issue in OpenClaw's plugin installer on Windows. It cannot spawn npm correctly without a shell context. It does not affect macOS or Linux.

Fix

Install the plugin manually in two steps:

openclaw plugins install @sentinel-agents/sentinel
cd %APPDATA%\openclaw\plugins\sentinel
npm install

After running npm install manually, restart the gateway with openclaw gateway restart. The plugin will load normally. This workaround is only needed once — updates install cleanly after the initial setup.

Symptom

Running /sentinel returns "command not found" or the plugin does not appear in the OpenClaw plugin list.

Cause

The plugin was not installed correctly, or the gateway was not restarted after installation.

Fix

Reinstall the plugin and restart the gateway:

openclaw plugins install @sentinel-agents/sentinel
openclaw gateway restart

If the plugin still doesn’t load, check that Node.js 18+ is installed with node --version.

Symptom

Sentinel reports "Licence invalid" or "Licence key not found" when running any command.

Cause

The licence key environment variable is missing, malformed, or has expired.

Fix

Re-set the licence key and restart:

openclaw config set plugins.entries.sentinel.config.SENTINEL_LICENCE_KEY your-key-here
openclaw gateway restart

Ensure there are no trailing spaces or newline characters in your key. If the key has expired, check your email for a renewal link or visit the pricing page.

Symptom

Inbound scanning is disabled with "sentinel-scan not found" in the logs, or sentinel-scan returns "command not found" in the terminal.

Cause

The pip auto-install step may have failed silently (Python not in PATH at install time), or sentinel-security was installed in a virtual environment that OpenClaw cannot see.

Fix

Run pip install manually:

pip install sentinel-security

After installing, restart your OpenClaw instance. If sentinel-scan is still not found, the pip scripts directory may not be in your PATH. On macOS/Linux this is typically ~/.local/bin. On Windows, check %APPDATA%\Python\Scripts. You can also verify your licence with: sentinel-scan --verify

Symptom

Threats are detected but no alert notifications arrive on Slack, Discord, or email.

Cause

The webhook URL is incorrect, the alert provider was not added, or the endpoint is rejecting requests.

Fix

Check your configured alerts:

/sentinel status

/sentinel alerts add slack https://hooks.slack.com/services/T00/B00/xxxx

/sentinel alerts test

Symptom

The Sentinel dashboard URL returns a connection error or blank page.

Cause

The dashboard runs on the OpenClaw gateway. If the gateway is down or the port is blocked, the dashboard won’t load.

Fix

Check that the gateway is running:

openclaw gateway status

openclaw gateway start

Symptom

/sentinel audit reports "No rules loaded" and skips all checks.

Cause

The detection rules failed to download. This usually means a network issue or an expired licence.

Fix

Check your licence status with `/sentinel status`. If your licence has expired, renew it from the pricing page.

/sentinel status

If the network is restricted, ensure the gateway can reach sentinel-agents.com on port 443.

Symptom

Sentinel flags legitimate content as threats, causing unnecessary blocks.

Cause

Some content patterns (particularly technical documentation or security-related text) can trigger detection rules.

Fix

Adjust the minimum severity threshold for blocking:

openclaw config set plugins.entries.sentinel.config.SENTINEL_MIN_BLOCK_SEVERITY HIGH
openclaw gateway restart

This sets Sentinel to only block HIGH and CRITICAL threats, allowing MEDIUM and LOW findings through with a warning. If specific content is consistently flagged, contact support with example files so we can tune the rules.

Symptom

The OpenClaw gateway fails to start or crashes immediately after starting with Sentinel installed.

Cause

Version incompatibility between the plugin and the OpenClaw gateway, or corrupted installation files.

Fix

Uninstall and reinstall the plugin cleanly:

openclaw plugins uninstall @sentinel-agents/sentinel
openclaw plugins install @sentinel-agents/sentinel
openclaw gateway restart

openclaw gateway logs --tail 50