OpenClaw and Hermes Agent: common setup errors and fixes

Last checked Oct 23, 2026. Every fix below is quoted or summarized from the official docs, release notes, or a maintainer’s reply on GitHub, linked inline. AideDex did not run these commands. Check the linked page before running anything, since both projects ship changes almost daily.

For install steps, start with our setup guides for OpenClaw and Hermes Agent. Product facts are on the OpenClaw and Hermes Agent pages.

First, collect diagnostics

OpenClaw’s docs list these commands to share when asking for help, and say to check the output for secrets first (OpenClaw FAQ):

openclaw status --all
openclaw models status
openclaw doctor
openclaw logs --follow
openclaw gateway status --deep

For Hermes, the docs point to hermes doctor, hermes config show and the gateway log at ~/.hermes/logs/gateway.log (Hermes FAQ).

OpenClaw

“Unsupported Node” after updating to 2026.10.6

OpenClaw 2026.10.6, released Oct 22, 2026, requires Node 24.22.1+ or 26.12.1+. The release notes say those versions reject TLS chains signed with compromised certificate keys, and that openclaw update now refuses with recovery guidance on an older Node (v2026.10.6 release). The Node page adds that Node 22, 23 and 25 are unsupported and Node 26 is recommended (Node.js docs). The first-run FAQ still lists an older floor of 24.16+ or 26.1+ and defers to the Node page (OpenClaw FAQ). Follow the Node page.

Check with node -v. If you run openclaw on an incompatible Node in an interactive terminal, the CLI offers Update NodeJS: Y/N. Answering Y downloads a checksum-verified Node into ~/.openclaw/tools/cli-node without replacing your system Node (Node.js docs).

Two older reports show how this bites:

• Windows Companion pinned an old Node. OpenClaw creator Peter Steinberger (Wikipedia) confirmed the Windows Companion pipeline hard-codes Node 22.22.3. The issue was closed as not planned, pointing to Windows Hub v2026.9.3; the reporter said the install step passed after updating (issue #145658).
• Gateway won’t restart after an update. The service kept a Node too old for the new release. Steinberger closed it as “Fixed by #108668”: the updater now moves an owned service to a compatible Node (issue #106920).

openclaw: command not found

The docs say this “almost always means npm’s global bin directory isn’t on your PATH.” Find it with npm prefix -g and add it to your shell startup file (Node.js docs):

export PATH="$(npm prefix -g)/bin:$PATH"

If you use nvm, fnm or another version manager, initialize it in ~/.zshrc or ~/.bashrc, or new terminals won’t find openclaw (Node.js docs). On Linux, EACCES during npm install -g means you should move npm’s global prefix to a folder you own, such as ~/.npm-global (Node.js docs).

On Windows, add the output of npm config get prefix (usually %AppData%\npm) to your user PATH and reopen PowerShell. If you see spawn git or “git not found”, install Git for Windows first (OpenClaw FAQ).

Onboarding stuck on “Wake up, my friend”

If you skipped model setup, onboarding shows “Model auth missing”; run openclaw onboard again to add a provider. If the wake-up line gets no reply and tokens stay at 0, the docs say to run openclaw gateway restart, then openclaw status, openclaw models status, openclaw logs --follow, and finally openclaw doctor (OpenClaw FAQ).

“Another gateway instance is already listening”

The Gateway takes a lock by binding its port, by default ws://127.0.0.1:18789. EADDRINUSE means something else holds it. Stop the other instance, free the port, or start with openclaw gateway --port <port> (OpenClaw docs).

API keys vanish when the Gateway runs as a service

Services started by launchd or systemd don’t inherit your shell. Put the keys in ~/.openclaw/.env, or turn on env.shellEnv.enabled (OpenClaw docs).

Ollama prints tool calls as text, or won’t connect

OpenClaw uses Ollama’s native API. The docs warn: “Do not use the /v1 OpenAI-compatible URL.” It breaks tool calling. Use http://host:11434 (Ollama docs). If curl works but OpenClaw doesn’t, common causes are a localhost URL while the Gateway runs in Docker or elsewhere, a /v1 URL, a firewall, or the model only being pulled on another machine (Ollama troubleshooting).

Telegram bot rejects its token or ignores groups

getMe returned 401 means a bad bot token. Re-copy or regenerate it in BotFather and update your config. If the bot does not respond to group messages without a mention while requireMention is false, disable privacy mode in BotFather (/setprivacy), then remove and re-add the bot, and check the group allowlist (Telegram troubleshooting).

Gateway down after an update

The docs’ sequence: openclaw status --all, openclaw update status --json, openclaw gateway status --deep, openclaw doctor --fix, then openclaw gateway restart. If an older openclaw binary refuses gateway start, stop or restart because openclaw.json was written by a newer version, run which openclaw, fix PATH so the newer install resolves, then run openclaw gateway install --force and openclaw gateway restart (Updates and rollbacks).

Hermes Agent

hermes: command not found

Your shell hasn’t reloaded PATH. Run source ~/.bashrc (or ~/.zshrc) or open a new terminal. The installer puts hermes in ~/.local/bin; add export PATH="$HOME/.local/bin:$PATH" if your shell config is unusual (Hermes FAQ).

Permission denied during install

The docs say not to run the installer with sudo, since it installs to ~/.local/bin. If you did, remove /usr/local/bin/hermes and re-run the standard installer (Hermes FAQ).

Unsupported Python version

Current first-party installs need Python 3.14, which the installer and packaged apps provide. For a managed install, run hermes doctor and use that install’s update method (Hermes FAQ).

Error 400 on the first chat, or the API key “doesn’t work”

The docs say a first-run 400 is usually a model name your provider doesn’t offer, or a key without access. Run hermes config show, then hermes model. Keys must match the provider: an OpenAI key won’t work with OpenRouter. On OpenRouter, check that the key has credits (Hermes FAQ). If /model shows only one provider, exit the chat and run hermes model to add more (Hermes FAQ).

Ollama and local models

Unlike OpenClaw, Hermes connects to local servers as an OpenAI-compatible custom endpoint. The docs’ example base URL is http://localhost:11434/v1, with a context length of at least 64000. If you set num_ctx in Ollama, set the same context length in Hermes (Hermes FAQ).

A remote Ollama box that only worked via localhost was reported in issue #7494. A repository collaborator closed it as fixed on main: provider: ollama with a LAN URL now goes to that endpoint instead of falling back to OpenRouter (issue #7494). Update Hermes if you hit this.

Telegram or other chat bot not responding

Per the docs, the bot “isn’t running, isn’t authorized, or your user isn’t in the allowlist.” Check hermes gateway status, start it with hermes gateway start, and read ~/.hermes/logs/gateway.log. If messages stop delivering, re-check the bot token with hermes gateway setup (Hermes FAQ).

Gateway keeps stopping on WSL

The docs call WSL’s systemd support unreliable and suggest running hermes gateway run in the foreground, under tmux, or with nohup (Hermes FAQ).

macOS: “node not found” or “ffmpeg not found” in the gateway

launchd services get a minimal PATH. Re-run hermes gateway install to capture your current PATH, then hermes gateway start (Hermes FAQ). For the WhatsApp error “Node.js not installed or bridge not configured”, a collaborator said current main uses a Hermes-managed Node runtime, so a missing standalone node no longer causes it (issue #2976).

FAQ

What Node version does OpenClaw need?

Node 24.22.1+ or 26.12.1+ as of release 2026.10.6, with Node 26 recommended (v2026.10.6 release, Node.js docs).

Why does my terminal say openclaw: command not found after installing?

npm’s global bin folder isn’t on your PATH. Add the output of npm prefix -g (plus /bin on macOS and Linux) to PATH (Node.js docs).

Why does hermes say command not found?

Your shell hasn’t picked up ~/.local/bin. Reload your shell profile or open a new terminal (Hermes FAQ).

Should I use the /v1 URL for Ollama?

Not in OpenClaw; it breaks tool calling there (Ollama docs). Hermes’ own example uses http://localhost:11434/v1 as a custom endpoint (Hermes FAQ).

Where do I get help if none of this works?

OpenClaw points to community.openclaw.ai and GitHub issues (OpenClaw FAQ). Hermes points to GitHub issues and the Nous Research Discord (Hermes FAQ).