Troubleshooting

Most LaunchZero diagnostics are local. The tray and dashboard show the gateway, policy, approval, and Activity state on your machine. Provider or integration failures may also require upstream status information. Start with these two local surfaces:

• The tray icon (menu-bar icon on macOS) shows whether the gateway is running.
• The dashboard - opened from the tray / menu-bar supervisor, which launches LaunchZero’s ControlApp - shows the rest: Home for overall health, Activity for the audit trail, and Approvals for anything pending.

Because LaunchZero gates in the moment and verifies after the fact, the Activity trail is usually the fastest way to see why a given call resolved the way it did. Diagnostic logs live under ~/.launchzero/logs if you need them.

Common issues

The gateway won’t start (the dashboard won’t open)

If the dashboard won’t open - the ControlApp can’t reach the local gateway - the gateway is down. Confirm the tray / menu-bar supervisor is present; if it isn’t, relaunch LaunchZero from your applications menu so the supervisor restarts the gateway and ControlApp. If it still won’t come up, the per-platform guides cover startup and permissions: Windows, macOS, Linux.

Your agent isn’t being governed

If your agent runs but calls through monitored tools or LaunchZero-managed integrations do not appear in Activity, check the managed connection in this order:

1. LaunchZero’s entry is in the agent’s config. The wizard writes it there - mcp.servers.launchzero in OpenClaw’s ~/.openclaw/openclaw.json, or mcp_servers.launchzero in Hermes’s config.yaml under HERMES_HOME (~/.hermes on macOS/Linux, %LOCALAPPDATA%\hermes on Windows). If it’s missing, re-run the setup wizard for that agent to rewrite it.
2. The gateway is up. Open the dashboard from the tray / menu-bar supervisor (the ControlApp) and confirm Home shows the system healthy.
3. The agent’s own process is running. OpenClaw runs on localhost:18789; if the agent itself isn’t up, nothing reaches LaunchZero to govern.

There’s no bridge URL or user-supplied bridge token for you to set. The wizard configures the authenticated connection; if its managed entry is missing, re-run setup rather than editing it by hand. See Connect your agent.

Agent setup didn’t finish in the wizard

If the wizard couldn’t install or configure your agent, re-run it from the tray or menu-bar supervisor and step through Choose → Connect → Model → Launch again. Confirm the model provider accepts the configured API key. Provider authentication or availability failures may require that provider’s status information. OpenClaw and Hermes are both first-class, so either can be set up here.

A call is unexpectedly denied

An unexpected denial usually means one of three things: the integration’s policy explicitly denies that tool; the tool matched no rule and fell through to default-deny; or a monitored file or network tool reached beyond its allowlist. The Activity trail names the reason:

time	action	outcome
11:02:07	gmail · modify_labels	deny · default-deny (no matching rule)
11:02:31	Filesystem.WriteText	deny · path outside allowed workspace folders

Adjust the integration’s policy in the dashboard, or add the host/folder to the relevant allowlist under Settings → Network & Workspace; the change takes effect immediately. See Policies & approvals.

An approval never appears

If you expected an approval card and none showed up, the call probably didn’t resolve to Require approval at all - it resolved to Allow (so it ran straight through) or Deny (so nothing happened and no card was needed). Only calls that resolve to require-approval pause for a human. Check that tool’s policy in the dashboard: if it’s set to allow, the call already executed; if deny, it was blocked. The Activity trail confirms which verdict the call received and when.

A download checksum doesn’t match

If your download doesn’t match the published hash, do not run the installer. A mismatch means the file is incomplete or has been tampered with. Delete it, re-download from the download page, and verify again. Every release ships a SHA256SUMS manifest; check your download against it (run this in the directory holding both the download and SHA256SUMS):

# macOS
shasum -a 256 -c SHA256SUMS --ignore-missing

# Linux
sha256sum -c SHA256SUMS --ignore-missing

On Windows, compute the hash with Get-FileHash .\LaunchZero-*-win-x64.exe -Algorithm SHA256 and compare it against the manifest. The checksums section has the full verify steps for each platform.

Still stuck?

Next steps

• Quickstart - start from a clean install and confirm the whole gate-and-verify loop end to end.