RunClaw Docs

Troubleshooting

Solutions for common issues you might run into with RunClaw.

Agent not starting after deployment

Symptoms: Dashboard shows the instance but the agent page isn't loading. Status might show "provisioning" or "initializing."

What's happening: Cloud-init is still running. It needs to download Docker images, install the agent, and configure TLS certificates.

Solutions:

  1. Wait 2-3 minutes. The initial setup takes time, especially for larger agent images.
  2. Check the dashboard for status updates — you'll see progress indicators during provisioning.
  3. If it's been more than 5 minutes, check if the server exists in your Hetzner Cloud Console. If it does, cloud-init may have encountered an error.

You can SSH into the server and check cloud-init status with:

ssh root@{server-ip}
cloud-init status

Can't connect to my agent

Symptoms: Browser shows a connection error or timeout when visiting {slug}.runclaw.run.

Solutions:

  1. Check DNS propagation. New domains can take a few minutes to propagate. Try again in 2-5 minutes.
  2. Check if the server is running. Log in to your Hetzner Cloud Console and verify the server status is "Running."
  3. Check Hetzner firewall rules. If you've added a Hetzner firewall to your server, make sure ports 80 and 443 are open for inbound traffic.
  4. Try a hard refresh. Your browser may have cached a failed DNS lookup. Try Ctrl+Shift+R or open an incognito window.

RunClaw configures the server firewall (UFW) automatically. If you've modified firewall rules via SSH, make sure ports 80 (HTTP), 443 (HTTPS), and 22 (SSH) are allowed.

LLM provider errors

Symptoms: Agent responds with an error message about the AI model or API key.

Solutions:

  1. Verify your API key. Go to Dashboard > Instance > Settings and check that your key is entered correctly. Some providers use prefixed keys (e.g., sk-... for OpenAI).
  2. Check your provider's status page. The AI provider may be experiencing an outage.
  3. Check your provider account balance. Many providers require a positive balance or active billing to make API calls.
  4. Verify model availability. Some models require a specific plan or waitlist access at the provider.

Provider status pages:

Dashboard shows "Offline"

Symptoms: Your instance card on the dashboard shows an "Offline" status badge.

What's happening: The sidecar (a small management agent on your VPS) has lost its WebSocket connection to RunClaw.

Solutions:

  1. Wait 30 seconds. The sidecar reconnects automatically. Brief disconnections are normal and usually resolve themselves.
  2. Check if the VPS is running. Open Hetzner Cloud Console and verify the server hasn't been powered off or is in a maintenance state.
  3. Restart the sidecar. SSH into your server and run: 
    ssh root@{server-ip}
systemctl restart openclaw-sidecar
  4. Check sidecar logs: 
    journalctl -u openclaw-sidecar -f --lines 50

The sidecar only handles monitoring and remote management. Your agent continues to work even when the sidecar is disconnected — you just lose dashboard visibility.

Forgot vault password

Symptoms: RunClaw asks for your vault password but you don't remember it.

What's happening: Your Hetzner API token is encrypted in your browser's local storage using a password you set during onboarding. Without this password, the encrypted token can't be decrypted.

Solutions:

  1. Re-enter your Hetzner API token. Go to your dashboard — you'll see a banner prompting you to re-enter your token. Generate a new API token from Hetzner Cloud Console (or use the same one if you saved it).
  2. Note: This doesn't affect your running servers. They're already deployed and will continue working. The token is only needed for new operations (creating servers, resizing, snapshots).

Agent update failed

Symptoms: You clicked Update but the dashboard shows an error or the agent is stuck on the old version.

Solutions:

  1. Try again. Click the Update button once more. Transient network issues can cause the first attempt to fail.
  2. Check if the agent is still running. If the update process was interrupted, the agent may have been rolled back to the previous version automatically.
  3. Restart the agent container. From your dashboard, click Restart on the instance. If that doesn't work, SSH in: 
    ssh root@{server-ip}
cd /opt/openclaw  # or /opt/agent-zero
docker compose up -d --build

High CPU or memory usage

Symptoms: Dashboard metrics show high resource usage, or the agent is responding slowly.

Solutions:

  1. Check what's running. SSH in and check: 
    docker stats
htop
  2. Consider resizing. If your agent consistently needs more resources, you can resize your server from the dashboard (requires Solo plan or higher). This is a non-destructive operation.
  3. Restart the agent. Sometimes a runaway process just needs a restart: 
    docker compose restart

Need more help?

If your issue isn't covered here:

Frequently Asked Questions

Answers to the most common questions about RunClaw.

On this page

Agent not starting after deploymentCan't connect to my agentLLM provider errorsDashboard shows "Offline"Forgot vault passwordAgent update failedHigh CPU or memory usageNeed more help?