Files
Obsidian/openclaw/28 painful mistakes I made with OpenClaw so you don't have to.md
2026-07-21 14:53:24 +08:00

30 KiB

title, source, author, published, created, description, tags
title source author published created description tags
28 painful mistakes I made with OpenClaw so you don't have to https://x.com/kloss_xyz/status/2032011756890177552
Unknown
2026-03-12 2026-03-13 Be quiet
clippings

What if I told you every single time you tried to make your AI agent system better, you're probably making it much worse. And you likely have no idea why either. I spent the last 3 weeks or so learning this the hard way. And the worst part about it is I did it to myself, over and over again. Now here's exactly how it happened. I'd see someone post a badass prompt, an article, or YouTube video about OpenClaw thinking "damn that's smart", and send it straight to my agent system thinking it would improve things. Another person's tips on their orchestration framework? Send it over. Someone's skill configuration? Import it in. A new memory system on the timeline? Dump it in.

And every single time, instead of simply improving the system, it broke things that were already working multiple times over. The new config would conflict with existing rules. The imported skills would collide with skills I already had. The governance framework would rewrite assumptions my routing depended on. I was context poisoning my own system with good intentions. And there's way more people out there doing the exact same thing too. The more I tried to make my system better by importing in other people's approaches, the worse my system got.

The turning point was when I stopped doing that and started asking different questions. Instead of "what can I find on my timeline to absorb today?", it became "what's actually wrong with this system right now or my own? What did this system help improve this week? What broke and why did it break when we implemented it? What should we intelligently improve? What gaps aren't covered?" Structured reflection instead of impulse importing things into my system. Auditing what exists before bolting on something new.

That shift in logic is what took my own system score from a 4.2 out of 10 on reliability and trust to something that actually reliably works (most of the time).

That 4.2/10 wasn't because my system was inherently bad. It was because everything within it was lying to me and it was driving me fucking crazy frankly. Stale docs that it told me were current. Agents saying "done" when nothing was actually done or it hallucinated new context in. Rules I wrote in 3 different files getting violated in the same session they were cited in. Even corrections I gave the agent that somehow magically vanished the next day. System health scores that said everything was fine while critical stuff was failing underneath and I had no idea. And half of those problems were caused by me dumping in outside configs that didn't fit my own setup.

And yes, eventually I fixed all of it. Every single damn thing that broke my system (and me frankly) got documented and turned into something reinforced and mechanical so it couldn't happen again. What follows below is everything I learned, what those failures actually looked like, and what I built to make my own system stop gaslighting me.

This isn't something you skim and forget. Bookmark it now. Save it. Come back to it every time your agents start doing things you didn't ask for, or worse, telling you they did things they didn't actually do. You'll need it.

Let's get into it.

1. Your Words Trigger Wrong Actions

When I first set up my OpenClaw, I used loose word matching for action commands. Things like "go" and "proceed" as trigger words. The problem with that is those words show up in normal conversation all the time, so those commands were firing when they shouldn't have been. The agent would do something completely insane and I'd spend an hour figuring out why.

The fix was embarrassingly simple. Use exact whole word matching instead of fuzzy word matching. Essentially, stop trying to be super clever with your routing and just be explicit about what triggers what. The collision that actually broke my orchestration layer came from a phrase nobody would have thought to test for either. That's why it was such a painful process to debug.

And that's the other lesson here: if you're only testing your routing with prompts that should work, you're going to ship bugs that only show up when someone says something unexpected. Test with the weird inputs too. Push your system in all sorts of ways.

2. Letting Every Agent Do Everything Is Expensive Chaos

I tried running agents and subagents without a strict hierarchy at first. It sounded flexible and efficient on paper. Wanted to see how OpenClaw would work out of the box. But it was just theory.

In reality it was a mess. Context got thrashed between agents. Nobody owned anything. Two agents would work on the same files without knowing the other one was touching them, produce conflicting changes, and neither would flag it. I was burning tokens and context and concurrent sessions on agents fighting each other and didn't even realize it either.

What actually works is a real chain of command. The main session orchestrates intent and stays lean. Your C-suite level agents (CTO, CMO, COO, or whatever roles you personally need) could dispatch domain work within their workspace. Employee agents execute that work. Specialist subagents handle deep focused tasks. And task specific subagents are disposable workers that do one bounded thing and report back too as subagents can also spawn subagents.

Think of agents like managers and subagents like contractors on a single ticket. An agent has a durable identity, its own memory, its own lane. Not every agent needs a workspace though, but it could have one. A subagent is temporary compute. Mixing those two up is how you burn tokens and get garbage output as well.

3. When One Agent Passes Work to Another, Context Could Get Lost

When one agent passes work to another, the handoff needs to carry actual information. Who's sending it, what the task is, when it was dispatched, where the results should go, and what evidence exists. If the receiving agent can't verify where the work came from, your handoffs become a game of telephone where context degrades at every step. Remember that game as a kid? Same concept at hand.

I didn't figure this out until I kept getting outputs that made no sense because the receiving agent was working from a half understood version of what the sending agent intended. Garbage in, garbage out as we all are aware. Once I tightened up what goes in a handoff, the quality of work jumped immediately.

4. Setting Up Rules in the Wrong Order Will Waste Full Days

I lost entire days to this before it fully clicked for me. When you're setting up rules for your agents, there's a specific order they need to happen in. If you do them out of sequence, every change you make ripples back and forces you to redo the last three things you just finished. It's maddening. I wanted to pull my hair out.

For me, the sequence that stopped the circular edits was: align your core identity files first (SOUL.md, AGENTS.md, potentially more depending on your setup), then lock your routing rules, then lock your language and communication contracts, then run stress tests. That specific order really does matter because each step depends on the previous one being stable. If you're constantly going back and editing earlier steps because a later step broke something, your setup is out of order. And I know it, because I've been there.

5. Two Agents Working on the Same Files Without Knowing It

I spawned 4 agents from my CEO agent on what looked like a simple idea. Two of them ended up overlapping on the same files, produced conflicting changes, and neither one flagged it.

Parallelism is a multiplier, not a strategy. You have to define who owns what before you parallelize anything or try to add swarms or do things concurrently. Make the ownership explicit. Then let them run. Ensure you set up your agents right first.

6. Your Agent Going Silent Will Kill Your Trust in the System

This one was a huge trust killer for me. I'd give the agent a directive and hear nothing for minutes. Typing animation in Telegram showing endlessly. Some messages looked like they never even registered too. My confidence in the whole system would tank and I'd start micromanaging everything. Literally drove me so crazy one night I decided to rebuild my whole comms and memory system over again lol.

The worst single wait I measured was almost 10 minutes. Not because there was a queue of messages ahead of mine. Because one long running process in the same session that handles my messages timed out and blocked everything behind it. One bad process and my entire Telegram DM channel was absolutely frozen. Almost 10 minutes of silence while I'm sitting there wondering if the thing even heard me.

Two fixes. First, fast acknowledgment matters more than perfect wording. A quick response followed by the actual work is worth more than a polished response that arrives minutes late. Second, if your agent is going to be doing long running work, it needs to be doing that in a separate session so it doesn't block the channel where you're actually trying to talk to it. Had my main agent doing this plenty.

7. Asking Your Agent to Fix 5 Things at Once Gets You Absolute Garbage

When you hand an agent a list of 5 problems and say "fix all of these," it tries to solve everything at once and does a half ass mediocre job on each one. Multi problem asks either time out or produce fixes that don't actually work.

One problem per agent. Or one problem at a time. Clean scope, clean output. This was the single biggest recent improvement I made to execution quality. Because it's the same way you should code. Not trying to do everything at once. But in order. Break the work into atomic pieces, dispatch each one separately, and let each agent focus on exactly one thing.

8. When and Why Your Agent's Session Could Die and Take All Unsaved Work With It

If the agent times out at minute 14 of a 15 minute window and all the work was going to be committed at minute 15, you just lost everything. Agent sessions have hard time limits that human work sessions don't. If you're not committing incrementally, you're gambling that the session won't die before the big save at the end. Incredibly risky.

Commit incrementally. Small commits, frequent saves. Don't let work pile up waiting for one big commit at the end.

This sounds obvious but I promise you'll forget it the first time an agent loses 12 minutes of work.

9. Your Agent Saying "Done" Is Worthless Without Receipts

This is the single most important thing I built. Before this fix, the agent could say "task complete" and I'd have to manually go check every single time whether anything actually happened. Every. Single. Damn. Time.

I built an evidence gate. Before any task can be marked done, it has to include:

  • Repo and branch
  • Commit hash
  • What files changed
  • Verification that the changes actually work
  • Screenshot or artifact if it's a UI change

No proof, then it's not done.

The system got dramatically more honest overnight. If you take one thing from this entire article, take this:

Your agent saying "done" is completely worthless unless it comes with receipts. It's like a kid saying they brushed their teeth to their parents. You believing them unless you see those pearly whites? Didn't think so.

10. Checking "Is It Done Yet?" Every Minute Is a Waste

If your agent is checking "is this done yet?" every 5 seconds or a minute for 10 minutes straight, that's 120 status checks burning context tokens and generating noise with zero useful information for you. I had one scheduled cron job time out 8 times in a single day because it kept retrying with no backoff or fallback, continuously adding load to a system that was already struggling.

Wait for the event. If the event doesn't come within a reasonable window, escalate. Don't sit there pinging in a loop. It'll just bubble up more delays.

11. Your Corrections Vanish Between Sessions

In context memory vanishes when a session ends or compacts. Every correction you made, every decision you clarified, every time you told the agent "that's not a priority right now" disappears unless it was saved to a file.

I corrected the same wrong assumptions across 3 separate conversations before I finally built a persistent decisions log. Three times I said "stop surfacing client outreach, that's deprioritized". Three times the same day it came back acting like I never said it. I wanted to scream out of frustration.

The fix was a simple file called decisions.md that gets loaded at the start of every session. Every redirect, every "not now," every "stop doing that" goes in there immediately with a date:

2026-03-02: Client outreach is deprioritized. Do not surface. 2026-03-02: Revenue mode is paused. Build mode only. 2026-03-03: Do not re-propose trading bot changes without explicit ask.

If a correction isn't written to a file in the same session you gave it, it didn't happen.

Same thing with daily logs. When a day's log is missing, the next session doesn't know what happened. So it rediscovers problems already solved, reruns checks already passed, surfaces work already deprioritized. Missing logs look like a minor housekeeping issue. They're not. Every session that boots without yesterday's context is a session that wastes your time.

Memory without structure is just forgetting slowly. Unfortunately and sadly, somewhat reminiscent of Alzheimer's.

12. Phantom Progress (Work That's "Done" but Keeps Coming Back)

This one drove me frankly crazy. My main agent would say "task complete" in our chat, and I'd see it and move on. But the completion state wasn't actually written to disk yet. So the next session would boot up with no record of the work being done. As far as the system was concerned, it never happened. Work that was "done" kept reappearing as not done and I couldn't figure out why for the longest time.

Now the rule is write first, speak second. Always.

The agent persists the state to a file before it tells me anything. This single rule eliminated an entire class of bugs where work that was "done" kept reappearing as not done.

13. Your Agent Confidently Reporting False Information

CLI summaries were getting mistaken for actual state, and it drove me insane yet again. My main agent would read a truncated command output and treat it as the complete picture. "No agents are currently running" when agents were absolutely running. "No meaningful improvement" when 4 repos had overnight commits it never checked.

The rule is simple. CLI summaries are views, not truth. The actual source files are truth. If a summary says one thing and the source file says another, the source file wins. Always.

Your agent's confidence is not a measure of its accuracy. It can sound completely sure about something and be dead wrong because it read a partial output and filled in the rest with assumptions.

14. "This File Doesn't Exist" (When It Absolutely Does)

When the agent says "this file doesn't exist" and it absolutely does, the problem is usually that it checked the wrong path or read an incomplete directory listing. So I built inventory scripts that count what actually exists on disk: repos, scheduled jobs, config files, all of it. The false alarm rate dropped immediately.

Think of inventory scripts as anti hallucination tools. They keep your agent grounded in reality instead of letting it make confident claims based on only partial information.

15. Half Your Scheduled Cron Jobs Are Likely Making Things Worse

Every scheduled cron job is a potential source of unexpected behavior. I had jobs that were producing no meaningful value but still consuming resources, generating log output, cluttering up my Telegram channels, and occasionally doing things that confused the rest of the system like coding on duplicate ghost repos it accidentally created. It took me way too long to just kill them.

Cut them. If a job doesn't produce something you'd actually read or act on, it shouldn't be running. My own signal to noise ratio improved immediately. Yours will too.

16. Noisy Cron Jobs Steal Your Attention

A scheduled cron job that dumps output into a channel you're monitoring is stealing your attention whether the output matters or not. I built a standard format for all job output:

  1. What happened?
  2. Why does it matter?
  3. What's next?
  4. How confident is the agent? (0-100)
  5. What's the evidence?

If nothing worth reporting happened, the output is nothing. Not silence where you wonder if it ran. Just a clean acknowledgment that it ran and found nothing worth flagging.

That distinction matters because "no output" and "nothing to report" are completely different signals. You should be able to debug your own problems. Not wonder where the hell they came from.

17. Running the Same Cron Job Twice at the Same Time Breaks Everything

If the system is already running a cycle and you manually trigger the same cron job on top of it, you get two processes competing over the same state. I saw this when automated loops were running while I was also simultaneously changing the rules those loops follow. You end up with a mix of old and new policies being applied at the same time and the output makes no sense.

Trust the active loop. If it's broken, fix it. Don't run a second one alongside it.

And when you do fix something, let it soak. The impulse is always to turn things back on the moment a fix lands. Resist that please. Let the fix run for a full cycle. Watch it. Then re-enable what was disabled. The delay costs you hours. Skipping it cost me days of rework. Twice. Seriously.

18. Your Health Score Lies While Everything Is Broken

I saw my own system health scores sitting at 94 while critical stuff was failing underneath. The score was calculated hours ago against data that no longer reflected reality.

A stale system score is the most dangerous thing in an agent system because it makes you feel safe when you're not.

So I built a three layer scoring system to fix this:

  • Top layer: a simple letter grade for quick readability
  • Middle layer: category level scores so you can see exactly where problems are and debug further
  • Bottom layer: hard gates that cannot be averaged away

If a critical gate fails, the whole system shows as degraded regardless of how good everything else looks.

On top of that I built an integrity index where integrity acts as a multiplier on the entire score. If your system's integrity checks pass, the score is normal. If they're in a warning state, the score gets multiplied by 0.67. If they're failing, it gets multiplied by 0.33.

This catches the lie you'll see in every autonomous system: high activity does not mean the system is healthy. Your agent can be shipping a ton of output while core integrity is broken. The multiplier catches that.

19. "Things Are Looking Good" Tells You Absolutely Nothing

A status update that says "things are looking good" tells me nothing I can truly verify. Like zero. A structured report with explicit pass/fail criteria tells me exactly what passed, what failed, and what to investigate next. I pair a machine readable JSON artifact with a human readable markdown summary for every major report. Now I get best of both worlds.

If your agent is giving you narrative updates instead of structured reports, you're going to miss problems until they blow up in your face.

20. Your Safety Checks Get Skipped the Moment Things Get Crazy and Busy

Your approval processes will get ignored under pressure. Every single time. Concrete, numbered, and sequential gates with explicit pass/fail criteria get followed. So I built 5 formal gates just for one skill cleanup myself: freeze the mapping, verify everything matches, snapshot the current state, tighten the handoff contracts, and run validation with evidence.

The difference isn't the rules. It's whether the rules are structured so that skipping a step is harder than just doing it. No rules and chaos will unravel your system.

21. Changing Your Agent's Rules, Skills, Agents, and System Without Testing It First

I deployed 13 formal system standards and ran every single one in advisory only mode before turning on any enforcement. No actual changes to the system, just "here's what would happen if this rule was active." That way I could study all the ways it could break, so the plan could be written with higher confidence and a lesser probability for negative impact on my unique setup.

This was one of the biggest wins of the entire last 3 weeks for me. If the advisory practice run shows problems, you fix them before anything touches your production repo and system. You reduce the risk. If you're deploying rule changes straight to production without testing them in read only audit and review mode first, you're asking for a whole lot of pain.

22. Changing Settings Without Saving the Old Ones First

Before you touch any configuration, snapshot the current state. Not because you expect to need it. Because when you do need it and don't have it, the recovery takes 10 times longer than the original change.

I had 54 config like files and over 200 risky values scattered across the system. Hardening all of that without snapshots would have been incredibly reckless. And believe it or not, I did it a few times to my own peril and learning lessons. Now every change gets a snapshot first, no exceptions.

23. Your Agent Violates Its Own Rules Even Though It Cites Them in the Same Session

This is the learning lesson that changed everything for me. I had "investigate before concluding" written in 3 different configuration files. The agent violated it in the same session where it cited the rule.

Three files with the same rule, and yet still broken.

The rule only held once I built a script that forced the agent to load its context before responding to anything. No longer a suggestion. Not a guideline. A mechanical reinforced gate that literally cannot be skipped.

I measured this across the whole system:

  • Rules that only existed as documentation: about 48% success rate
  • Rules backed by actual scripts: near 100% now

That gap tells you everything about the difference between writing rules and enforcing them.

Every mistake or broken logic in your agent system is potentially a rule you haven't turned into a script yet.

24. Your Agent Doing Something You Can't Undo

Agents can do almost everything. But the things they can't undo, the things that are visible to people outside the system, those need a human checkpoint. Branch first, pause before merge, and review before ship.

This isn't bureaucracy either. It's the only safety net that actually works when something goes wrong with an irreversible action. And if you don't have this in place, you will learn why the hard way. Pro tip: you should have your OpenClaw unique workspace on GitHub as a repository. If you don't, you're majorly messing up and causing yourself future pain.

25. Your Perfectly Written Prompts Will Drift Over Time

You can write a beautiful prompt. Clear structure, explicit rules, detailed guardrails. And the agent will still drift away from it over time unless there's something enforcing it mechanically.

This gets even worse when you import someone else's rules, articles, videos, or configs into your existing setup. Your carefully tuned and crafted prompts get overridden or contradicted by the new stuff, and now the agent is following a Frankenstein of two different systems.

Instructions in files are suggestions.

Scripts that run before every response are enforcement.

The prompt tells the agent what to do. The enforcement wrapper makes sure it actually does it.

26. That "Random" Bug Isn't Random

I had this bizarre problem where my own system kept opening localhost pages via Chrome browser and working on a ghost duplicate repo with no apparent trigger to me. It looked completely random. Turned out it was a managed browser profile interfering with automation in ways that only showed up under specific conditions and subagents. Once I figured out the boundary, the "random" behavior became completely predictable and fixable.

If something in your system looks random, I can assure you it's not. You just haven't found the specific boundary causing the 'random' behavior yet.

27. Duplicate Repos Silently Wreck Everything

I found 6 sets of duplicate repos across my projects directory and my own OpenClaw workspace. Did I ever ask my system to do that? Nope. I quite literally told it where all my projects should live. Yet it did the opposite. And if two copies of a repo exist and the agent doesn't know which one is the real one, it reads from the wrong copy and makes confident statements based on outdated code.

One location per repo. Audit regularly. Make sure nothing else is pretending to be the source of truth. This is one of those problems that's invisible until it ruins your whole afternoon or a week de-duping repositories, features, and design across duplicates.

28. Fixing All Your Security Issues or Problems at Once Is a Trap

One shot security changes are terrifying because if something breaks, you don't know which of the 15 changes caused it. I found credentials in places they shouldn't be, mismatched account contexts between tools, and embedded secrets in session logs. That's the kind of stuff that makes you want to fix everything immediately all at once. Don't even if it's tempting as hell.

Every single one of those has to be fixed one at a time, in order, with a snapshot and rollback plan at each step. Phased hardening with checkpoints between each change means you can isolate any problem immediately. Don't do that? You'll regret it. How do I know? I've done it so you don't have to.

The Correct Fix Order (If Your OpenClaw System Is Gaslighting You Right Now)

The short version of everything above is this: I didn't fail from a lack of plans. I failed from gaps between what I planned and what was actually enforced at runtime. And I made it worse every time I imported someone else's setup thinking it would fix my own.

An agent system doesn't fail from one big bug. It fails from thousands of tiny assumptions nobody verified. It also fails from very real context poisoning, even if it's little bits over time. The only real fix is a closed loop: make sure context is loaded before the agent responds, make sure claims are backed by evidence, make sure rules are enforced by scripts not docs, and make sure your health scores reflect current reality.

The process that actually works now is simple. Every week I ask: what broke? Why did it break? What's working that we should protect? What should we improve? And the improvements come from auditing what exists, not from grabbing some other person's config and hoping it fits. And now when I find systems or prompts or techniques I ask, "what can we learn from this", "does it make sense for our own system", "what doesn't make sense", or even "what is the specific plan for our own unique setup to achieve something like this"?

If your agent system is lying to you right now, fix it in this exact order:

  1. Build a context gate that loads corrections, decisions, and recent memory before the agent responds to anything. So no more cold answers.
  2. Build a decisions log where every redirect you give the agent gets saved permanently and loaded at session start. Now you don't need to constantly repeat yourself across sessions.
  3. Require evidence for every done claim. Repo, branch, commit hash, what changed, and proof it works. If there's no receipts, it's not done.
  4. Build a health score that includes timestamps, freshness checks, and category level detail. If a critical check fails, the whole score should reflect it, not average it away or out so you can't see it.
  5. Make integrity a multiplier on your health score. High activity with broken integrity should show as a bad score, not a good one.
  6. Turn every repeated failure into a script. If you've corrected the same problem twice, it needs a mechanical gate, not another line in a doc.

Do those six and your system stops lying to you every day.

The unlock is not better prompts. The unlock is operational mechanics. You can have the best AI models and skilled agents on the market and still run a fragile system. You can have an average model with strong enforcement and run a reliable one. Reliability wins because enforcement compounds over time. It breaks when rules stay as prose.

The real work isn't building the agent system. It's building the infrastructure that stops the agent system from lying to you. And believe me when I say that takes longer than anyone admits because I've been at it for weeks and it's still far from perfect in my mind. But once it's in place, it compounds every single day. And that's the reliability you want to see.

So please stop importing other people's configs and praying they will fit yours. Start auditing your own system and fixing what's actually broken.

If you made it this far, you're already ahead of 99.9% of people who will bookmark this and likely never come back to it. They'll keep importing other people's configs.

I'm not an infrastructure engineer. I'm self taught. I'm not claiming to have all the answers or the best setup for everyone either here, and if someone claims they do, they're lying to you. Everything here comes from building with this stuff daily, breaking things constantly, and writing down what actually works so nobody else has to guess. There's no playbook for most of this stuff as it is brand new tech. You need to be having fun and breaking things. It's how you learn. If something in here is wrong, missing, or outdated, tell me for sure too. I'd rather fix it than let someone build on bad information. Thanks for reading everyone!

Follow me (@kloss_xyz) for more on agents, systems, and building with AI.