OpenClaw not working? Common setup problems and how to fix them (2026)

OpenClaw is powerful but has moving parts: a gateway daemon, channel plugins, API keys, cron jobs, memory files, and model routing. When something stops working, it is usually one of a small set of problems. This guide covers all of them.

Start here: the fastest general diagnosis

Before anything else, run this three-step check:

1. Is the gateway running? Run openclaw gateway status in your terminal. If it says stopped or not found, start it with openclaw gateway start.
2. Are the API keys valid? Open your OpenClaw config and verify the relevant API keys are current. Many problems trace back to an expired or rotated key.
3. Are the core instruction files intact? Check that SOUL.md, AGENTS.md, and today's daily memory file exist and are not empty. Empty or missing files break continuity.

Most OpenClaw problems are one of these three things. If you find it here, you are done in two minutes. If not, keep reading.

---

Problem 1: OpenClaw is not responding at all

Symptoms: No reply to messages. The bot appears offline. Commands have no effect. Channel shows the assistant as inactive.

Most likely causes

• The gateway daemon stopped (most common after a machine restart or sleep)
• The channel token expired or was revoked
• The API key for the model provider hit a billing limit or was rotated
• A config change was made but the gateway was not restarted

Fix

1. Run openclaw gateway status. If stopped, run openclaw gateway start.
2. In your channel platform (Discord, Telegram, Slack), verify the bot token is still valid and the bot is still in the server or chat.
3. Check the model provider dashboard (Anthropic, OpenAI) for billing or rate-limit notices.
4. If you made config changes recently, run openclaw gateway restart to reload them.

Prevention

Set the gateway to start automatically on login. On macOS, create a launchd plist. On Linux, use a systemd unit. This eliminates the most common cause of silent failures after reboots.

---

Problem 2: OpenClaw is forgetting things between sessions

Symptoms: The assistant does not remember recent context. It acts like it has never met you. Projects feel like they reset every session.

Why this happens

OpenClaw is designed to wake up fresh and read memory from files. If those files are not being read on startup, or not being written at session end, continuity breaks.

Fix

1. Open AGENTS.md (or wherever your session startup instructions live). Confirm it explicitly instructs the assistant to read SOUL.md, USER.md, today's and yesterday's daily memory file, and MEMORY.md before doing anything else.
2. Check whether the nightly memory consolidation is actually running. If you use a cron job for this, verify the job is active with openclaw cron list or equivalent.
3. Open the most recent daily memory file (e.g. memory/2026-03-28.md). Is it being written to? If it is empty or missing, the write step is broken — likely because the session end instruction is not triggering.
4. For high-priority context, write it to MEMORY.md directly. This file should hold the distilled long-term knowledge that matters most.

Tip

Mental notes do not survive sessions. If it matters, write it to a file. The rule is: if you want the assistant to remember it next week, it has to be in a file right now.

---

Problem 3: Cron jobs and scheduled workflows are not firing

Symptoms: The morning brief stopped arriving. Scheduled reminders are not firing. Recurring tasks are silent.

Most likely causes

• The gateway stopped (cron jobs stop with it)
• The cron job was accidentally disabled during a config edit
• The schedule expression has an error (wrong timezone, invalid syntax)
• The target session no longer exists (for session-bound jobs)

Fix

1. Run openclaw gateway status — all scheduled work requires the gateway to be running.
2. List your jobs with the cron tool and confirm the relevant job shows enabled: true.
3. Check the last run time and last run result for the job. A failed run with an error message usually tells you exactly what broke.
4. For timezone issues: make sure the cron expression timezone matches your intended local time, not UTC (unless you explicitly want UTC).
5. If the job was a session-bound job pointing to a now-deleted session, recreate it pointing to the current session.

---

Problem 4: Responses are very slow

Symptoms: The assistant takes 30+ seconds to reply. Recurring workflows feel sluggish. Heartbeats are slow.

Most likely causes

• A large model is being used for a simple task
• A local model is undersized for the hardware (e.g. running a 70B model on a machine with 16GB RAM)
• A remote API is rate-limiting or having high latency
• The context window is overloaded with too many files being read at startup

Fix

1. Match model to task. Recurring summaries, heartbeats, and simple workflows do not need Claude Opus or GPT-4o. Route them to a lighter model. Use strong models only for high-stakes reasoning tasks.
2. Check RAM on local models. Ollama's throughput drops sharply when a model does not fit in RAM. For fast local inference on Apple Silicon, stick to models that fit within your unified memory budget (typically 7B–27B range for a Mac mini).
3. Trim startup context. If your session startup reads 15 files before every response, that is a lot of tokens per turn. Trim instruction files. Keep MEMORY.md focused. Archive old daily memory files.
4. Check provider status pages if remote APIs feel slow across the board.

---

Problem 5: Channel plugin not working (Discord, Telegram, Slack, etc.)

Symptoms: The bot does not respond in a specific channel. Messages arrive but get no reply. The bot was working yesterday.

Most likely causes

• Token expired or rotated in the channel platform
• Bot was removed from the server, group, or workspace
• Webhook URL changed (e.g. after a gateway restart with a different port or ngrok tunnel)
• Channel plugin config entry is missing or has a typo
• The bot lacks permission to read or post in that specific channel

Fix

1. Open the channel platform (Discord Developer Portal, BotFather in Telegram, Slack App settings) and verify the token is current. Regenerate if needed and update your config.
2. Confirm the bot is still in the server/group/workspace and has the right permissions.
3. If you are using a webhook-based setup with a public tunnel (ngrok, Cloudflare Tunnel), verify the tunnel is active and the URL in your config matches.
4. Restart the gateway after any config change.

---

Problem 6: The assistant is doing the wrong thing in workflows

Symptoms: Tone is off. Tasks are not completed correctly. The assistant ignores context it should know. Workflows produce generic output instead of personalized work.

Why this happens

Instruction drift. Over time, the gap between what the instruction files say and what you actually want grows. The assistant does not drift — the instructions just stopped being accurate.

Fix

1. Read SOUL.md and AGENTS.md out loud as if you just received them. Do they still represent the assistant you want? If not, update them.
2. Be specific, not vague. "Be helpful" is weak. "When I ask about a project, always check the relevant folder first before asking clarifying questions" is useful. Replace vague rules with concrete behaviors.
3. Check USER.md. If your context, goals, or priorities have shifted, update USER.md so the assistant knows who it is working with.
4. For skill-specific drift, read the SKILL.md file for that skill and verify its instructions still reflect what you want. If the skill is outdated, update it.

---

Problem 7: The morning brief (or other heartbeat workflow) stops after a few days

Symptoms: The morning brief worked for a week, then silently stopped. No error message. Just nothing.

Diagnosis

This is almost always one of two things: the gateway stopped running, or the cron job targeting that session is now targeting a stale session.

Fix

1. Check openclaw gateway status. If the machine restarted without the gateway set to auto-start, scheduled jobs stopped.
2. Check the cron job's session target. If it was set to current binding at a specific session that no longer exists, it may be silently failing. Recreate the job pointing to a live session or use isolated mode for standalone jobs that do not need session binding.
3. Check whether HEARTBEAT.md has grown large. If it is several hundred lines, trim it — large instruction files at every heartbeat inflate token use and can cause timeouts on slower models.

---

Problem 8: Local Ollama models behaving strangely

Symptoms: Local model responses are repetitive, low-quality, or cut off. The model ignores system prompts. Output is much worse than expected for the model size.

Most likely causes

• Quantization level is too low (Q2 or Q3 models lose significant quality)
• Context window is set too large for the available RAM, causing severe performance degradation
• The model is not the right choice for the task (instruction-following is weak in some base models)
• Ollama version is outdated and has a known bug with that model family

Fix

1. Upgrade quantization. Use Q4_K_M or Q5_K_M as the default. Q2 and Q3 are too lossy for instruction-following tasks. Q8 is high quality but uses much more RAM.
2. Check RAM pressure. Run ollama ps to see active models. If a model is being swapped to disk, it will be unusable for real work.
3. Use instruct-tuned variants, not base models, for agent tasks. Base models are pre-training checkpoints with no instruction tuning — they will not follow directions reliably.
4. Update Ollama with brew upgrade ollama or the appropriate method for your OS.

---

Problem 9: Too many messages — the assistant is being noisy or overly chatty

Symptoms: The assistant responds to conversations it should stay quiet in. Heartbeat check-ins are too frequent. Group chats feel cluttered.

Fix

1. Add explicit "stay quiet when" rules to AGENTS.md or SOUL.md. Be specific: "Do not respond to group chat messages unless directly mentioned or your response adds clear value that no one else in the conversation can provide."
2. Reduce heartbeat frequency in the cron schedule. 30-minute heartbeats are usually sufficient for ambient monitoring. More frequent polling rarely adds value and increases cost.
3. In HEARTBEAT.md, add specific quiet-hour rules so the assistant does not trigger check-ins during night hours or when the human is clearly busy.

---

Problem 10: Cost is higher than expected

Symptoms: API bills are growing faster than expected. A single workflow seems to be using a lot of tokens. Monthly spend is hard to predict.

Fix

1. Audit which models are doing what. A recurring workflow that runs every 30 minutes using Claude Opus will cost significantly more than one using a lighter model or a local model.
2. Route appropriately. The model routing principle: use the cheapest model that gets the job done reliably. Escalate to a stronger model only when quality or reliability actually matters for that specific task.
3. Trim context size. Long instruction files, large memory files, and files read unnecessarily at startup inflate token counts on every turn. Keep MEMORY.md curated. Archive old daily notes.
4. Set spending caps in the model provider dashboards (Anthropic, OpenAI) as a hard ceiling so unexpected spend cannot go unbounded.
5. Move repetitive low-stakes tasks to local models. A daily summary, calendar check, or simple file organization task runs fine on a local 7B–14B model at zero API cost.

---

Quick reference: symptom → likely cause → fastest fix

Symptom	Most likely cause	Fastest fix
No response at all	Gateway stopped	openclaw gateway start
Forgetting between sessions	Memory files not read/written	Check AGENTS.md startup + nightly cron
Cron jobs not firing	Gateway stopped or job disabled	Check gateway status + job enabled flag
Slow responses	Model too large or wrong for task	Route to lighter model for that task
Channel plugin offline	Expired token or bot removed	Regenerate token, update config, restart
Wrong behavior in workflows	Instruction drift in SOUL/AGENTS	Rewrite specific rules more concretely
Brief stopped after a week	Gateway or stale session binding	Gateway auto-start + recreate cron job
Bad local model output	Low quantization or base model	Use Q4_K_M+ instruct-tuned variants
Too chatty in groups	Missing quiet rules	Add explicit silence conditions to AGENTS.md
High API costs	Wrong model for routine tasks	Reroute to cheaper/local model, trim context

---

When the problem is not on this list

Most unusual OpenClaw problems come from one of three root causes:

1. Config mismatch — a change was made but the gateway was not restarted, or two conflicting settings exist.
2. File corruption or accidental overwrite — a key instruction file was accidentally emptied or overwritten. Keep a brief backup of SOUL.md, AGENTS.md, and MEMORY.md in a safe location.
3. Version incompatibility — a model API changed its behavior, or an Ollama model update changed defaults. Check release notes when upgrading.

If you still cannot isolate it, start fresh with a minimal config (just gateway + one model + one channel) and add back complexity one layer at a time until the problem reappears.

---

Frequently asked questions

---