Logging and debugging

File logs (structured): /tmp/openclaw/openclaw-YYYY-MM-DD.log for the default profile, or /tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log for a named profile. Set a stable path via logging.file; file log level via logging.level; console verbosity via --verbose and logging.consoleLevel.

Fastest tail:

openclaw logs --follow

Service/supervisor logs (when the gateway runs via launchd/systemd):

• macOS launchd stdout: ~/Library/Logs/openclaw/gateway.log (profiles use gateway-<profile>.log; stderr is suppressed).
• Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager.
• Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST.

See Troubleshooting for more.

openclaw gateway statusopenclaw gateway restart

If you run the gateway manually, openclaw gateway --force can reclaim the port. See Gateway.

Three Windows install modes:

1) Windows Hub local setup: the native app manages a local app-owned WSL Gateway. Open OpenClaw Companion from the Start menu or tray, then use Gateway Setup or the Connections tab.

2) Manual WSL2 Gateway: the Gateway runs inside Linux.

wslopenclaw gateway statusopenclaw gateway restart

If you never installed the service, start it in the foreground: openclaw gateway run.

3) Native Windows CLI/Gateway: runs directly in Windows.

openclaw gateway statusopenclaw gateway restart

If you run it manually (no service): openclaw gateway run.

Docs: Windows, Gateway service runbook.

Quick health sweep:

openclaw statusopenclaw models statusopenclaw channels statusopenclaw logs --follow

Common causes: model auth not loaded on the gateway host (check models status), channel pairing/allowlist blocking replies (check channel config and logs), or WebChat/Dashboard open without the right token. If remote, confirm the tunnel/Tailscale connection is up and the Gateway WebSocket is reachable.

Docs: Channels, Troubleshooting, Remote access.

Usually means the UI lost the WebSocket connection. Check: is the Gateway running (openclaw gateway status)? Is it healthy (openclaw status)? Does the UI have the right token (openclaw dashboard)? If remote, is the tunnel/Tailscale link up?

Then tail logs:

openclaw logs --follow

Docs: Dashboard, Remote access, Troubleshooting.

openclaw channels statusopenclaw channels logs --channel telegram

Then match the error:

• BOT_COMMANDS_TOO_MUCH: the Telegram menu has too many entries. OpenClaw already trims to the Telegram limit and retries with fewer commands, but some menu entries may still be dropped. Reduce plugin/skill/custom commands, or disable channels.telegram.commands.native if you do not need the menu.
• TypeError: fetch failed, Network request for 'setMyCommands' failed!, or similar network errors: on a VPS or behind a proxy, confirm outbound HTTPS is allowed and DNS works for api.telegram.org.

If the Gateway is remote, check logs on the Gateway host.

Docs: Telegram, Channel troubleshooting.

openclaw statusopenclaw models statusopenclaw logs --follow

In the TUI, use /status to see the current state. If you expect replies in a chat channel, confirm delivery is enabled (/deliver on).

Docs: TUI, Slash commands.

If you installed the service (launchd on macOS, systemd on Linux):

openclaw gateway stopopenclaw gateway start

In the foreground, stop with Ctrl-C, then openclaw gateway run.

Docs: Gateway service runbook.

openclaw gateway restart restarts the background service (launchd/systemd). openclaw gateway runs the gateway in the foreground for this terminal session. Use the gateway subcommands if you installed the service; use the bare foreground run for a one-off.

Start the Gateway with --verbose for more console detail, then inspect the log file for channel auth, model routing, and RPC errors.