Troubleshooting Common Issues

If your host doesn't appear in the dashboard after running the agent:

1. Check agent status:
   $ clawkeeper.sh agent --status

   Verify the API key is configured and the timer/LaunchAgent is active.

2. Run a manual scan:
   $ clawkeeper.sh agent run

   Watch for errors in the output. The most common issues are an invalid or deleted API key.

3. Verify your API key:

   Check that the key in ~/.config/clawkeeper/config.env starts with ck_live_ and matches a key in Settings → API Keys.

4. Re-install the agent:
   $ clawkeeper.sh agent --uninstall && clawkeeper.sh agent --install

The dashboard refreshes when you navigate to the page. If data looks stale:

• Hard-refresh the browser (Cmd+Shift+R / Ctrl+Shift+R)
• Check the "Last Scan" column on the Hosts page — if the timestamp is current, the data is synced
• The agent runs on a schedule (typically hourly). Run clawkeeper.sh agent run for an immediate sync

The free plan allows 1 API key. If you see this error when clicking "Add Host," you already have a key created from a previous attempt.

Go to Settings → API Keys to view your existing key. You can either use it for the new host or delete it and create a fresh one.

• Verify the key starts with ck_live_
• Check that you haven't deleted the key from Settings since creating it
• Ensure there are no trailing spaces or newlines in your env variable
• If you lost the key, delete it in Settings and create a new one, then re-run clawkeeper.sh agent --install

gum provides styled terminal output. If it fails to install:

• macOS: brew install gum
• Linux: See the gum installation docs for your distro

Clawkeeper works fine without gum — it falls back to plain ANSI colors. To force the fallback, set:

If Clawkeeper reports "OpenClaw not running" after a setup:

1. Native install: Check that openclaw is on your PATH and the gateway is responding:
   $ curl -s http://localhost:18789/health
2. Docker install: Check the container is running:
   $ docker ps | grep openclaw

   If not running, check logs:

   $ docker logs openclaw
3. Re-run setup: The setup wizard is safe to re-run and will skip already-completed steps:
   $ clawkeeper.sh setup

The CVE audit requires:

• Network access to fetch the CVE feed from GitHub
• python3 for version comparison

If either is unavailable, the check gracefully degrades to SKIPPED (not counted against your grade). Install Python 3 and ensure network access to resolve.

Some checks need elevated permissions (e.g., reading firewall state on Linux). If you see permission errors:

The scan report marks checks that need sudo. Running without sudo causes those checks to SKIP rather than FAIL.

The free plan supports 1 host. If you're scanning a second machine, you'll get a 403 error on upload. Options:

• Upgrade to a paid plan for up to 3 workstations (Pro) or unlimited (Team)
• Remove the old host from the dashboard and scan the new one instead
• Keep scanning locally without the agent — the CLI works without a dashboard account

NemoClaw requires Python 3.11 and the NeMo Guardrails package. If the guardrails service isn't starting:

1. Check the venv exists:
   $ ls -la /home/openclaw/nemoclaw-venv/bin/activate
2. Verify NeMo Guardrails is installed:
   $ su - openclaw -c 'source ~/nemoclaw-venv/bin/activate && pip show nemoguardrails'
3. Check Python version:
   $ python3.11 --version

   If missing, install from the deadsnakes PPA:

   $ sudo add-apt-repository -y ppa:deadsnakes/ppa && sudo apt-get update && sudo apt-get install -y python3.11 python3.11-venv

NemoClaw instances take longer to provision due to Python and guardrails installation. If stuck beyond 10 minutes:

• Check cloud-init logs: cat /var/log/clawkeeper-cloud-init.log
• Look for Python or pip errors in the log
• Ensure the instance has at least 4GB RAM (NeMo Guardrails needs ~800MB heap)

NanoClaw only supports WhatsApp, Telegram, and Discord. If your bot isn't connecting to the channel:

• Verify the bot token is correct (check for trailing spaces)
• For Telegram: ensure the bot hasn't been revoked via @BotFather
• For Discord: check that the bot has the Message Content privileged intent enabled
• Check gateway logs: su - openclaw -c 'docker logs openclaw'

Re-run the installer to get the latest version:

This overwrites the existing script. Your agent configuration and API key are stored separately in ~/.config/clawkeeper/ and are not affected by updates.

This removes OpenClaw (native or Docker), wipes config files, and removes the LaunchAgent/systemd timer. To also remove the agent config: