OpenClaw on a VPS: Fixing Connection and Service Errors

Published on

OpenClaw down on your VPS? Fix a Gateway that is gone after a reboot, port 18789 conflicts, dashboard logins, silent channels and API key errors, in order.

A laptop almost closed on a dark table, its screen glow lighting the keyboard

Your OpenClaw agent stopped answering on Telegram, the dashboard won't load through your SSH tunnel, or the Gateway was gone after a reboot. The Gateway runs as a systemd user service, and most failures sit in six places: the service, the port, the dashboard login, a channel, the API key or memory. This guide checks them in that order, with commands from OpenClaw's docs for version 2026.10.9, the stable release of 29 October 2026. It assumes our OpenClaw setup guide on Ubuntu 24.04 or Debian 12: a user named openclaw, the default profile and the Gateway on loopback port 18789.

Quick answer: As the openclaw user, run openclaw status, openclaw gateway status, openclaw logs --follow, openclaw doctor and openclaw channels status --probe. A Gateway gone after a reboot usually means lingering is off (sudo loginctl enable-linger openclaw) or the service isn't enabled. EADDRINUSE means port 18789 is taken; refusing to bind gateway ... without auth means the bind left loopback without a token. Silent channels usually mean an unapproved pairing code or mention gating, and a silent model usually means an API key the service can't see: save it with openclaw models auth paste-api-key.

Start With OpenClaw's Command Ladder

Run openclaw commands as the openclaw user and sudo commands from your admin account:

sudo -iu openclaw
export XDG_RUNTIME_DIR=/run/user/$(id -u)

Without XDG_RUNTIME_DIR, systemctl --user stops with Failed to connect to bus: No medium found and OpenClaw's service checks may fail too; the Gateway runbook gives the same export for headless servers. Then run the ladder from the troubleshooting runbook:

openclaw status
openclaw gateway status
openclaw logs --follow   # Ctrl+C stops it
openclaw doctor
openclaw channels status --probe

Healthy means Runtime: running, a successful connectivity check, a Capability: line such as read-only or admin-capable, and, where supported, works or audit ok for each channel account. Three details:

  • Read the output of openclaw gateway status, not just its exit code. In scripts, --require-rpc exits non-zero when the read check fails.
  • Runtime: running is systemd's view; the connectivity check is a real WebSocket connection. If they disagree, compare the check URL with Listening: and read Last gateway error:.
  • Plain openclaw doctor can already migrate config and state; --lint is read-only, and --fix stops the Gateway, repairs and starts it again.

When the Gateway won't start, read its journal with journalctl --user -u openclaw-gateway.service -n 200 --no-pager. File logs are in /tmp/openclaw/openclaw-YYYY-MM-DD.log unless you set logging.file.

The Gateway Is Gone After a Reboot or Logout

Check lingering from your admin account:

loginctl show-user openclaw --property=Linger

You want Linger=yes. Linger=no, or Failed to get user: User ID 1001 is not logged in or lingering (with your user's ID), means the user's services only run while that user is logged in. Enabling lingering starts the user manager at once:

sudo loginctl enable-linger openclaw
# then, as the openclaw user:
systemctl --user enable --now openclaw-gateway.service
systemctl --user status openclaw-gateway.service
journalctl --user -u openclaw-gateway.service -b -n 100 --no-pager

What the status means:

  • Unit openclaw-gateway.service could not be found. It was never installed: run openclaw gateway install. Adding --force replaces a damaged definition.
  • Exit status 78. That is EX_CONFIG, a configuration error, and the unit's RestartPreventExitStatus=78 stops retries until you fix it. openclaw config validate checks the file, and openclaw doctor --fix repairs legacy keys or restores the last good copy, saving your edit as openclaw.json.clobbered.*.
  • Exit status 1. Startup couldn't read its config or state (storage unavailable, for example), and systemd retries. Check free space (df -h) and that the openclaw user owns ~/.openclaw.
  • start-limit-hit. Too many failed starts in a short time; OpenClaw's example unit allows 10 in 300 seconds. Fix the cause, run systemctl --user reset-failed openclaw-gateway.service, then start it.

Port 18789 Is Taken or the Bind Is Refused

another gateway instance is already listening or EADDRINUSE. Something already holds the port. Find it from your admin account, then look for duplicate services as openclaw:

sudo ss -ltnp 'sport = :18789'
openclaw gateway status --deep

ss names the process and PID, for example a Gateway started by hand in tmux or screen. A system unit next to the user unit shows up in --deep as Other gateway-like services detected. After a change of gateway.port, Gateway service port does not match current gateway config means the service still pins the old port: run openclaw gateway install --force and openclaw gateway restart.

refusing to bind gateway ... without auth. gateway.bind is set to lan, tailnet or custom without a token or password. Don't add a token just to put the port online. Return to loopback, which needs a restart:

openclaw config set gateway.bind loopback
openclaw gateway restart

gateway.bind takes modes (auto, loopback, lan, tailnet, custom), not addresses such as 0.0.0.0. tailnet falls back to loopback while Tailscale is down. A related startup error, Gateway start blocked: set gateway.mode=local, means gateway.mode is remote or missing: openclaw config set gateway.mode local.

The Dashboard Won't Connect

On the server, as openclaw, check that the Gateway serves the dashboard:

curl -sS http://127.0.0.1:18789/

If that prints OpenClaw's HTML, the fault is in the tunnel or the browser. Restart the tunnel on your computer with ssh -N -L 18789:127.0.0.1:18789 you@your-server-ip, open http://127.0.0.1:18789/ directly, not an old link, and match the message:

  • unauthorized or AUTH_TOKEN_MISMATCH: a wrong or stale token. openclaw dashboard --no-open on the server prints a short-lived, one-time pairing link to open through the tunnel, and openclaw gateway auth-token --show shows the token. No token yet: run openclaw doctor --generate-gateway-token, then restart.
  • PAIRING_REQUIRED: run openclaw devices list, then openclaw devices approve <requestId>.
  • too many failed authentication attempts (retry later): a temporary lockout for that browser origin. Wait, then use the right token.
  • gateway connect failed: the URL or port is wrong, or the tunnel is down.

Opening port 18789 fixes none of these; keep the Gateway private, as in our setup guide.

A Channel Is Connected but Nobody Gets a Reply

Check the channel and its waiting senders; for another channel, replace telegram with its name:

openclaw channels status --probe
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
openclaw channels logs --channel telegram

Pairing codes expire after one hour, and an approval covers direct messages only, not groups. Then match the logs:

Log line or symptomCauseFix
pairing requestSender not approvedopenclaw pairing approve <channel> <CODE>
drop guild message (mention required or mention requiredGroup mention gatingMention the bot or set requireMention: false for that group; on Telegram, also turn off privacy mode with BotFather's /setprivacy and re-add the bot
getMe returned 401Telegram rejected the bot tokenRe-copy or regenerate it in BotFather; tokenFile and botToken in the config win over TELEGRAM_BOT_TOKEN
TypeError: fetch failed or Network request for 'getUpdates' failed!The server can't reach api.telegram.orgTest IPv4 and IPv6 below
Discord bot online, silent in serversMessage Content Intent off, or server not allowlistedEnable it under Privileged Gateway Intents in the Discord Developer Portal, check channels.discord.guilds, restart the Gateway
missing_scope, not_in_channel, Forbidden, 401/403The bot lacks permissionsFix its scopes or channel permissions on the platform
plugin load failed: dependency tree corrupted; run openclaw doctor --fixAn update broke the channel pluginopenclaw doctor --fix, then openclaw gateway restart

For Telegram network errors, test both IP versions as openclaw:

curl -4 -sS -o /dev/null -m 10 -w '%{http_code}\n' https://api.telegram.org/
curl -6 -sS -o /dev/null -m 10 -w '%{http_code}\n' https://api.telegram.org/

An HTTP status code means that route works; curl: (7) or curl: (28) means it failed to connect or timed out. Some hosts resolve api.telegram.org to IPv6 first, OpenClaw's Telegram page notes, so if only IPv6 fails, run openclaw config set channels.telegram.network.dnsResultOrder ipv4first. If both fail, check your outbound firewall; per-user rules like those in our AI agent security guide apply to this test too.

After a crash loop of three unclean boots within five minutes, OpenClaw holds back channel auto-start. Once the cause is fixed, openclaw gateway call channels.start --params '{"channel":"telegram"}' starts a channel right away.

API Key and Model Errors

A systemd service doesn't inherit your shell environment, so an ANTHROPIC_API_KEY exported in .bashrc never reaches the Gateway. Check what the Gateway can use:

openclaw models status
openclaw models status --check; echo $?

--check exits with 0 when no model route has missing or expired credentials, 1 when one does and 2 when one is about to expire, without calling the model. To store or replace a key, let OpenClaw prompt for it. It updates the provider's active key, or creates a profile if none exists, and prints a recovery step if the Gateway can't refresh:

openclaw models auth paste-api-key --provider anthropic

Use --provider openai for an OpenAI key. To use an environment variable instead, put ANTHROPIC_API_KEY=... in ~/.openclaw/.env, keep that file at mode 600 and run openclaw gateway restart. Then match the error:

  • No credentials found for profile anthropic:default: the Gateway host has no key it can load. Add one as above; if a pinned order still points at a missing profile, run openclaw models auth order clear --provider anthropic.
  • No API key found for provider "google": a fallback model has no key. Add one, or remove that model from agents.defaults.model.fallbacks.
  • HTTP 429: rate_limit_error: Extra usage is required for long context requests: the Anthropic model has a native 1M context window your credential isn't eligible for. Choose a standard-window model, use an API key, or set fallback models.
  • 401 errors after an update or a new sign-in: openclaw doctor --fix removes stale per-agent copies of OAuth profiles.

openclaw models status --probe sends real requests, can use tokens and needs the Gateway stopped first with openclaw gateway stop.

The Gateway Dies When Memory Runs Out

Browser automation and large tool output can fill a small server's memory:

free -h
sudo journalctl -k | grep -i "killed process"

The kernel logs Out of memory: Killed process with the victim's PID and name, and OpenClaw logs memory pressure: level=critical. Where it can, OpenClaw raises the oom_score_adj of child processes such as the browser to 1000 so the kernel kills them first, and OOMPolicy=continue keeps the service up when a child dies. If the Gateway itself is killed, Restart=always in its unit starts it again.

Fixes, cheapest first: swap (step 4 of our setup guide), fewer browser or tool jobs at once, or more RAM. OpenClaw's hosting FAQ recommends 2 GB or more and warns that Node tools and browser automation "can be resource hungry." On a Space-Node VPS you move to a bigger plan from the client area; the AI agent VPS plans show the RAM of each.

If It Still Fails

  • openclaw gateway diagnostics export or openclaw triage --non-interactive writes a sanitized report to share. Review it before you attach it.
  • After an update, compare which -a openclaw and openclaw --version with the install root in openclaw gateway status. An older binary refuses to start a service whose config a newer version wrote: fix your PATH, then run openclaw gateway install --force and openclaw gateway restart from the newer install.
  • openclaw: command not found means npm's global bin folder isn't on your PATH. Add export PATH="$(npm prefix -g)/bin:$PATH" to ~/.bashrc.
  • OpenClaw's official support is its community at community.openclaw.ai.

Space-Node support helps with the VPS itself by live chat, Discord and email from 08:00 to 20:00 UTC; OpenClaw on top of it is self-managed.

FAQ

Why does OpenClaw stop when I close my SSH session? Lingering is off, so the openclaw user's services don't outlive the login. Run sudo loginctl enable-linger openclaw. OpenClaw's runbook names this the supported way to keep the Gateway running without a login session.

Does restarting the Gateway lose my agent's work? Usually not on 2026.10.9: main chat sessions that were working resume on their own, even after a crash or forced kill. The restart recovery docs for newer builds change this: a graceful restart asks each working session to continue, and a crash resumes nothing. Either way, check files and outside actions before you repeat a task.

Can I run two Gateways on one VPS? You rarely need to, since one Gateway runs several channels and agents. For a rescue bot or hard isolation, give each instance a profile: openclaw --profile <name> creates ~/.openclaw-<name>. Set a unique gateway.port in that profile and install its service with openclaw --profile <name> gateway install; systemd then names it openclaw-gateway-<name>.service.

Is openclaw triage safe to run on the server? Collecting diagnostics is read-only, and the archive excludes secrets, tokens, raw chat payloads and raw logs. Without --non-interactive, triage also starts a coding agent such as Codex or Claude Code and asks it to repair the install autonomously, within its own permissions.

Sources

All opened on 31 October 2026: