When Things Break (And They Will)

You've built a lot in these nine chapters. You've got an agent on Telegram, a security guardian running every 6 hours, memory that actually works, and search powered by QMD. That's a real system now — and real systems break.

This isn't doom and gloom. It's just reality. A cron job will go silent at 3 AM. A config change won't seem to apply. Telegram will stop responding and you'll wonder if you accidentally deleted something important.

The good news? Most OpenClaw problems are the same five issues, and most of those are fixed by restarting the gateway. This chapter teaches you how to figure out what's actually wrong — and fix it without panicking.

The Troubleshooting Mindset

Before we dig into specific issues, here's how experienced OpenClaw users approach a problem:

1. Don't panic. Seriously. Your data is almost certainly fine. OpenClaw stores everything in plain files — nothing is locked in a database that might corrupt. If the gateway crashes, your memory files, agent configs, and scripts are all still there.

2. Check logs first, guess second. The single biggest mistake beginners make is guessing what's wrong and changing random things. The logs tell you exactly what happened. Read them.

3. Restart fixes 80% of problems. This isn't a joke. The majority of "something is broken" issues are solved by openclaw gateway restart. Config changes don't apply until restart. Memory flushes don't resume until restart. Cron jobs don't re-register until restart.

4. Change one thing at a time. If you change three settings and restart, and something breaks, you don't know which change caused it. Change one thing. Restart. Test. Repeat.

Finding Your Logs

Logs are your best friend when something goes wrong. OpenClaw writes everything that happens — agent conversations, gateway events, errors, cron executions — to log files you can read anytime.

Gateway Logs (The Main Ones)

The gateway writes a daily log file to:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

Today's log:

/tmp/openclaw/openclaw-2026-02-20.log

To watch it live (new lines appear as they happen):

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

To search for errors in today's log:

grep -i "error" /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

Agent Logs

Each agent also keeps its own logs:

~/.openclaw/agents/<agentId>/logs/

If Argus is misbehaving but your main agent is fine, check Argus's logs specifically. The agent ID is whatever you named it — usually something like argus-panoptes or security-agent.

What to Look For

When reading logs, scan for:

• ERROR or FATAL — Something actually broke. Read the full line and the line after it for context.
• WARN — Something unexpected happened but the system kept going. Worth reading.
• timeout — A connection to an AI model or external service timed out. Usually transient.
• 401 or 403 — Authentication failed. A token is wrong or expired.
• EADDRINUSE — The port is already taken. Another process (or another OpenClaw instance) is using it.

Checking Gateway Status

Before digging into logs, check if the gateway is even running:

openclaw gateway status

You want to see:

Runtime: running
Port: 18789
Uptime: 2h 34m
Agents: 2 active
Cron: 3 jobs registered

If you see Runtime: stopped, that's your problem. Start it:

openclaw gateway start

Common Issue #1: Telegram Bot Not Responding

This is the one you'll hit first. You send a message, the blue checkmarks appear, but no reply comes back.

Step 1: Is the gateway running?

openclaw gateway status

If it says stopped, start it. Problem solved 60% of the time.

Step 2: Did you restart after a config change?

If you recently edited openclaw.json, the gateway is still running the old config. Restart:

openclaw gateway restart

Step 3: Is the bot token valid?

Open ~/.openclaw/openclaw.json and find the Telegram section. Does the token look right? Tokens look like 123456789:ABCdef... — a number, a colon, then a string.

If you're not sure, open Telegram, find @BotFather, send /mybots, select your bot, and check the token. If it's been revoked or doesn't match, regenerate it and update your config.

Step 4: Is your user ID in the allowedUsers list?

Check the allowedUsers array in your Telegram config. If your numeric user ID isn't in there, OpenClaw will silently ignore your messages. This is a security feature (you set this up in Chapter 4) — but it catches people who change Telegram accounts or typo their ID.

Step 5: Check the logs.

tail -50 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

Look for lines mentioning "telegram" or "bot." If you see connection errors, the problem is between OpenClaw and Telegram's servers. If you see message-received events but no responses, the problem is in your agent config.

Common Issue #2: Memory Not Working

Your agent used to remember things. Now it doesn't. Or it saves some things but not others. Or you're getting "I don't have any information about that" for things you told it yesterday.

Step 1: Is memoryFlush enabled?

Check ~/.openclaw/openclaw.json. Look for the memory configuration you set up in Chapter 7:

"agents": {
  "defaults": {
    "memoryFlush": true,
    "compaction": {
      "strategy": "prune"
    }
  }
}

If memoryFlush is missing or set to false, your agent isn't saving memories before compaction. That's your problem.

Step 2: Did you restart after the config change?

You know the drill:

openclaw gateway restart

Step 3: Check for flush attempts in logs.

grep -i "flush" /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

You should see lines like Memory flush completed or Flushing context to memory. If you see errors here, something is wrong with the write process.

Step 4: Verify the config is valid.

A stray comma or missing bracket can silently break your config:

python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null

If this prints nothing, your JSON is valid. If it prints an error, it'll tell you exactly which line has the problem.

Common Issue #3: QMD Not Working

You installed QMD in Chapter 9, but searches aren't returning results — or QMD commands fail entirely.

Step 1: Is QMD installed and in your PATH?

which qmd

If this returns nothing, QMD isn't installed or isn't in your PATH. Reinstall:

bun install -g qmd

Step 2: First search is slow (that's normal).

The very first time QMD runs a search, it downloads embedding models (100-300 MB). This takes 5-10 minutes and only happens once. If your "broken" search is actually just the first search — give it time.

Step 3: Does the collection exist?

qmd collection list

You should see your memory collection listed. If it's empty, QMD hasn't indexed anything yet.

Step 4: Are files actually indexed?

qmd ls memory

This lists every file QMD knows about. If files are missing, re-index:

qmd embed

Step 5: Nuclear option — re-index everything.

If searches return garbage or nothing:

qmd update && qmd embed

This updates QMD itself and re-indexes all files from scratch.

Common Issue #4: Agent Not Waking on Cron

You set up Argus (or another agent) on a schedule, but it's not running. No reports, no activity.

Step 1: Is the cron job registered?

openclaw cron list

You should see your scheduled jobs with their intervals. If the list is empty, the cron job didn't register — probably because the gateway restarted after you set it up and the job wasn't persisted. Re-create it.

Step 2: Check the last run timestamp.

The cron list output should show when each job last ran. If the timestamp is old (hours or days ago), something is preventing execution.

Step 3: Was the gateway running at the scheduled time?

This catches more people than you'd expect. If the gateway was stopped at 2 AM when Argus was supposed to run, the job simply didn't execute. There's no "catch up" — missed runs are missed runs.

Step 4: Check the logs for cron activity.

grep -i "cron" /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

Look for lines showing cron triggering (or failing to trigger) your scheduled job.

Step 5: Manually trigger the agent.

If you need the job to run right now:

openclaw sessions spawn --agent <agentId>

This wakes the agent immediately outside of its schedule. Useful for testing.

Common Issue #5: Config Changes Not Applying

You edited the config. You restarted the gateway. But the behavior hasn't changed.

Step 1: Did you actually restart?

Not "did you think you restarted" — actually verify:

openclaw gateway status

Check the uptime. If it says Uptime: 4h 12m and you restarted 2 minutes ago, your restart didn't work. Try:

openclaw gateway stop && openclaw gateway start

Step 2: Is your JSON valid?

python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null

A single syntax error — a missing comma, an extra bracket, a trailing comma after the last item — will cause OpenClaw to silently use default values instead of your config. This is the sneakiest problem because there's no error message.

Step 3: Is the setting in the right section?

Some settings go at the root level of the JSON. Others go inside agents.defaults. Others go inside specific agent configs. If you put a setting in the wrong section, it's ignored.

Quick reference:

• Gateway settings (port, telegram config) → root level
• Default agent behavior (memoryFlush, compaction) → agents.defaults
• Specific agent overrides → agents.<agentId>

Step 4: Check what config the gateway is actually using.

openclaw config show

This shows the merged, resolved config the gateway loaded at startup. Compare it to what you expect. If your changes aren't reflected here, you found the problem.

The Restart Hierarchy

Not all restarts are equal. Start with the lightest touch and escalate only if needed:

Level 1: Session reset — Clears the current conversation but doesn't touch the gateway. Use when your agent is confused or stuck in a loop.

In your chat, type /new or /reset.

Level 2: Gateway restart — Reloads config, re-registers cron jobs, reconnects to Telegram. Fixes 80% of problems. This is your go-to.

openclaw gateway restart

Level 3: Full stop and start — Completely shuts down the gateway process and starts a fresh one. Use when restart doesn't seem to work.

openclaw gateway stop && openclaw gateway start

Level 4: Machine reboot — Rarely needed. But if you're running OpenClaw on a Raspberry Pi or VPS and nothing else works, a reboot clears everything — stale processes, locked files, port conflicts.

Getting Help (When You're Really Stuck)

Sometimes you'll hit something these five common fixes don't cover. That's fine — the OpenClaw community is active and helpful. But you'll get much faster help if you ask the right way.

Before you ask, gather these:

1. The last 50 lines of your gateway log:

tail -50 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

2. The relevant section of your config (not the whole thing — just the part that's misbehaving). Strip any API keys or tokens first.

3. What you expected to happen vs. what actually happened.

4. What you already tried — "I restarted the gateway and checked the logs" saves everyone time.

Where to ask:

• OpenClaw Discord → #help channel — Best for quick questions. Active community, usually get a response within the hour.
• GitHub Issues — For actual bugs. If you've confirmed something is broken and not just misconfigured, file an issue with your logs and config snippet.
• This community — The AgentArks Discord is growing too. Come say hi.

The Prevention Checklist

Most troubleshooting is avoidable. Here's a checklist to save yourself future headaches:

• Restart the gateway after every config change. Make it muscle memory.
• Check logs when something seems off. Don't guess — look.
• Back up your config before major changes. A simple cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak before you start editing saves you from "I don't remember what it looked like before."
• Test one change at a time. Change one setting, restart, verify. Then the next.
• Name cron jobs clearly. "argus-security-patrol-6h" is debuggable. "job1" is not.
• Validate JSON before restarting. Run python3 -m json.tool on your config. Catch syntax errors before they cause silent failures.
• Keep a terminal open with tail -f on the log. While you're learning, watching the live log teaches you how OpenClaw works more than any documentation.

You Just Finished Molt 1

That's it. Ten chapters, and you went from "what is OpenClaw?" to running a system with:

• A working OpenClaw installation connected to Telegram
• A locked-down security setup you actually understand
• A dedicated security agent (Argus) running automated patrols
• Daily workflows and cron jobs that run while you sleep
• Memory that actually persists and a second brain via QMD
• The skills to diagnose and fix problems when they come up

You're not a beginner anymore. The Hatchling has molted.

Molt 2: The Juvenile is where things get really interesting. You'll connect more messaging platforms, browse ClawHub for skills that extend what your agent can do, start managing costs, and turn OpenClaw into something you genuinely rely on daily. The training wheels come off — but you've got the foundation to handle it.

You've come out of your shell. Time to grow into the next one.