VERIFIED · 01.10.2026 UPDATED · 01.10.2026

Troubleshooting common OpenClaw problems

When something does not work, guessing is the expensive part. Here is a fixed order of diagnosis — five commands that tell you where the problem is — and fixes for the four most common cases: the Discord bot stays silent, the Gateway will not start, the model times out, and OpenClaw cannot reach Ollama from WSL2.

⏱ 30–45 min Intermediate OpenClaw · Lesson 3.4 Diagnostics · Discord · Gateway · Ollama · WSL2

OpenClaw (Gateway)🔒 local Ollama (the model)🔒 local Discord (channel)🌐 global Cloud model (optional)🌐 global

🔄

UPDATED · 01.10.2026 — what changed

We checked every command, setting and message against the official OpenClaw, Microsoft (WSL) and Ollama documentation. We now start with the "command ladder" from the official guide (status → gateway status → logs --follow → doctor → channels status --probe) instead of three commands that did not cover channels. Corrected: (1) the setting agents.defaults.llm.idleTimeoutSeconds and its exact error text do not appear in the documentation — replaced with the documented models.providers.ollama.timeoutSeconds plus keep_alive (⚠️ the old key is unverified; if you have it in your config, openclaw doctor will tell you whether it is valid); (2) the log line is drop guild message (mention required, not "skipping guild message (no-mention)", and we added what pairing and the server list (channels.discord.guilds) are for; (3) for the Discord token we now recommend an environment variable instead of a command that leaves it in your terminal history; (4) the JSON5 config is checked with openclaw config validate, not python3 -m json.tool (which cannot read JSON5); (5) for Ollama on WSL2 there are now two network modes — mirrored (recommended by Microsoft; 127.0.0.1 works both ways) and NAT; we removed the manual netsh portproxy because neither the OpenClaw nor the Ollama documentation mentions it; (6) we added the known WSL2 crash loop with NVIDIA and ollama.service. A real Discord user number and a real machine address were removed from the examples — replaced by <PLACEHOLDER>. Open WebUI: we found no step in this lesson that belongs to Open WebUI; if old files show an "openclaw" image with WEBUI_SECRET_KEY, that is Open WebUI, not OpenClaw.

⚠️

What we have not run ourselves

During the check we did not run OpenClaw and WSL2 on a live machine. Everything is checked against the documentation but not tested end to end — so there is no "TESTED" label. Two things remain unverified: the exact text of the model-timeout error in the latest version, and whether your network needs a Windows firewall rule (see step 5).

01What you'll learn

How to find where the problem is with five commands in the right order, instead of guessing.
Why a Discord bot is "connected but silent" and which three settings are most often the cause.
How to recognise a busy port, a broken config or missing Gateway authentication.
How to stop timeouts from a slow local model without touching anything unnecessary.
How OpenClaw on WSL2 reaches Ollama — in mirrored mode and in NAT mode.
How to share a log without leaking anything secret.

02Before you start

You have OpenClaw installed with a Gateway (see DevStation · Lesson 3 and OpenClaw · Lesson 3). The commands are for openclaw in Ubuntu on WSL2; on Windows the same ones work.
If you use Discord: the bot exists in the Discord Developer Portal 🌐 global.
If you use a local model: Ollama 🔒 local is installed (DevStation · Lesson 2).
For WSL2 mirrored mode: Windows 11 22H2 or newer.

⛔

Logs are not for sharing "as they are"

Logs, dumps and diagnostics can contain tokens, machine names, paths and message content. Before showing them to anyone — in a chat, a forum or a ticket — review them and remove anything sensitive. When you ask for help, send a short excerpt and replace addresses and names with <PLACEHOLDER>.

03Steps

The command ladder — always first

The official OpenClaw guide recommends five commands in this order. Each one answers one question, and the first one that fails shows where to dig. That way you do not guess whether it is the network, the config or the channel.

bash · diagnostics

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Command	What you are asking	Good sign
`openclaw status`	Overall state	No warnings
`openclaw gateway status`	Is the Gateway running?	`Runtime: running` and `Connectivity probe: ok`
`openclaw logs --follow`	What is happening right now?	Watch while you send a message
`openclaw doctor`	Is a config or service broken?	No blocking issues
`openclaw channels status --probe`	Are the channels alive?	Live status per account; where supported, `works` or `audit ok`

💡

Where the logs are

The easiest way is openclaw logs --follow — no path needed. On Linux the default file is /tmp/openclaw/openclaw-YYYY-MM-DD.log (one per day); the path can be changed in logging.file in the configuration.

The Discord bot does not answer 🌐 global

When the channel is "connected" but silent, it is almost always a question of rules, not of connection. Check in order:

a) The privileged intents. In the Discord Developer Portal → your application → Bot → Privileged Gateway Intents: turn on Message Content Intent (needed for ordinary server messages) and preferably Server Members Intent. Then restart the Gateway. Without Message Content Intent the bot sees that a message exists but cannot read its text. If Discord does not let you have this intent, OpenClaw can still work in direct messages and on explicit mention — see the channels.discord.intents.messageContent setting in the documentation.

b) The server rules. If the policy is an allowlist (groupPolicy: "allowlist") but your server is not listed in channels.discord.guilds, messages are rejected. If a channel list exists, only the listed channels are allowed. The requireMention setting must be in the right place — under channels.discord.guilds or in the channel entry. A typical log line: drop guild message (mention required — the bot is waiting to be mentioned.

c) Direct messages. By default Discord DMs are in pairing mode: an unknown sender waits for approval.
bash · pairing
```
openclaw pairing list --channel discord
openclaw pairing approve discord <CODE>
```
If you use a list instead of pairing (channels.discord.dmPolicy: "allowlist"), the bot answers only senders in channels.discord.allowFrom; check that your Discord user ID is there (openclaw config get channels.discord.allowFrom). The legacy keys channels.discord.dm.policy and dm.allowFrom are still read, and openclaw doctor --fix moves them to the new ones.

d) The token. If you reset it in the Developer Portal, the old one stops working. Set the new one as an environment variable on the machine where OpenClaw runs — do not type it into a chat and do not leave it in your terminal history. For a service installed with openclaw gateway install, the value must also be available to the service (for example in the .env file in the OpenClaw folder).
bash · token (placeholder)
```
export DISCORD_BOT_TOKEN="<BOT_TOKEN>"
openclaw gateway restart
```
⚠️
Unverified line from the old lesson
The old lesson mentioned a "sender not in allowFrom" log line. We could not find it in the documentation — do not rely on it. The documented signals are drop guild message (mention required and pairing request (waiting for approval).

The Gateway does not start or keeps falling over

Start with the ladder, then look at exactly what gateway status says.

bash · Gateway

openclaw gateway status
openclaw gateway status --deep   # also looks for extra services
openclaw logs --follow
openclaw doctor

On Linux/WSL2 you can also look at the systemd service itself (the default name is openclaw-gateway.service; for a user service use --user, without sudo) and at who holds the port:

bash · service and port

systemctl --user status openclaw-gateway.service
journalctl --user -u openclaw-gateway.service -n 50 --no-pager
ss -ltnp | grep 18789

⚠️ If the service is installed as a system service rather than a user one, drop --user and add sudo; openclaw gateway status shows the exact name.

The most common signals and what they mean (from the official guide):

Signal	Meaning	Fix
`another gateway instance is already listening` or `EADDRINUSE`	The port is busy — a second Gateway or another process	Stop the extra one. By default the Gateway listens on port 18789; most setups want one Gateway per machine
`Gateway start blocked: set gateway.mode=local`	Local mode is not on, or the config lost the line	Set `gateway.mode="local"` or run `openclaw onboard --mode local`
`refusing to bind gateway ... without auth`	Trying to listen beyond loopback without authentication	Go back to loopback (the default) or set up a Gateway token/password
`Gateway service port does not match current gateway config`	The service still holds the old port	`openclaw doctor --fix` or `openclaw gateway install --force`, then restart

A broken config. The Gateway accepts only a configuration that fully matches the schema: an unknown key or invalid value = it refuses to start. The config is JSON5 (comments and trailing commas allowed), so the standard json.tool is no use. Use:

bash · config

openclaw config validate
openclaw doctor --fix

The second command repairs legacy keys; the old config stays in a backup (.bak).

💡

Changes apply by themselves

The Gateway watches the file ~/.openclaw/openclaw.json and applies most changes without a restart. If something did not change, run openclaw gateway restart. On Linux the managed service is systemd (user); on Windows it is a Task Scheduler task; in both cases openclaw gateway status is the easiest way to see it.

The model times out (local model)

OpenClaw aborts a model request if no part of an answer arrives within a set time. According to the documentation that time is 120 seconds for a cloud model and 300 seconds for a self-hosted one. A large local model on first load (cold start) can exceed that.

The documented way is to extend the time only for the Ollama provider and keep the model loaded between requests. Add to ~/.openclaw/openclaw.json (the example follows the official Ollama-for-OpenClaw documentation; replace the model name with yours):
json5 · models.providers.ollama
```
{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "<MODEL_NAME>",
            name: "<MODEL_NAME>",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}
```
✅
Why this way, and not with the "global" timeout
The documentation recommends extending the time for the specific provider before raising the timeout of the whole agent. That way one slow model does not loosen every other safeguard. If the model does not answer at all, test it directly: curl http://127.0.0.1:11434/api/tags on the machine where Ollama runs.

⚠️
Unverified from the old lesson
The key agents.defaults.llm.idleTimeoutSeconds and the text "The model did not produce a response before the LLM idle timeout" are not in the current documentation — so we do not give them as fact. If you see a different message, run openclaw logs --follow and look for the word "timeout".

If the Ollama server is on WSL2 with NVIDIA and Windows keeps restarting it in a loop — see the end of the next step.
OpenClaw cannot reach Ollama from WSL2 🔒 local

First decide where Ollama is relative to OpenClaw — everything depends on it:
- Both in Ubuntu on WSL2. No network problem: curl http://127.0.0.1:11434/api/tags from the same terminal.
- OpenClaw in WSL2, Ollama on Windows. Here the WSL2 network mode decides everything (below).
- OpenClaw in a container. localhost inside the container is not your machine — the host address is different (see DevStation · Lesson 3).
Option A — mirrored mode (recommended)

Microsoft recommends the newer mirrored mode (Windows 11 22H2 or newer). In it Windows and WSL2 see each other through 127.0.0.1, so you do not need to hunt for addresses. On Windows create or extend the file %USERPROFILE%\.wslconfig:
ini · .wslconfig (Windows)
```
[wsl2]
networkingMode=mirrored
```
Then in PowerShell: wsl --shutdown and open Ubuntu again. Check from Ubuntu:
bash · check
```
curl http://127.0.0.1:11434/api/tags
```
You should get JSON with the list of models. The provider address in OpenClaw is http://127.0.0.1:11434 — without /v1 (with /v1 Ollama switches to a compatibility mode and tools break).

Option B — NAT mode (the default)

Here WSL2 sits "behind" Windows and localhost in Ubuntu is not Windows. The host address shows up as the default gateway:
bash · Windows host address
```
ip route show | grep -i default | awk '{ print $3 }'
curl http://<WINDOWS_HOST_ADDRESS>:11434/api/tags
```
Ollama for Windows listens only on 127.0.0.1 by default; to reach it from WSL2 in this mode you must change its listening address with the OLLAMA_HOST variable, for example 0.0.0.0:11434; on Windows you set it as an environment variable for your account (Settings → "Edit environment variables for your account"), then quit Ollama and start it again (see the Ollama documentation). Listening on all addresses opens Ollama to every network your machine is connected to — be careful.

⚠️
Unverified: firewall and "portproxy"
The old lesson gave a Windows firewall rule and a manual netsh interface portproxy. Neither is in the OpenClaw or Ollama documentation. The firewall may block the port; if mirrored mode is not available to you and the connection fails, review the firewall rules — but we have not tested a specific command, so we do not give one.

❌
WSL2 restarts by itself as soon as Ollama starts
The OpenClaw documentation describes a known problem on WSL2 with NVIDIA: the ollama.service unit with Restart=always loads a model at startup and Windows kills the virtual machine in a loop. Fixes: sudo systemctl disable ollama and start Ollama by hand; or in %USERPROFILE%\.wslconfig add the line autoMemoryReclaim=disabled under [experimental], then wsl --shutdown.
How to ask for help without leaking secrets
- Send a short excerpt of the log, not the whole file, and name your OpenClaw version (openclaw --version).
- Replace tokens, addresses, machine names and user names with <PLACEHOLDER>.
- For a full diagnosis use openclaw gateway diagnostics export (the documentation describes it as sanitised), but review it too before you attach it.
- If a token has leaked anywhere, reset it in the Developer Portal immediately — the old one counts as compromised.