Your OpenClaw Agent Cannot See Its Own Mistakes. Here Is How to Fix That with ZizkaDB
DEV Community

Your OpenClaw Agent Cannot See Its Own Mistakes. Here Is How to Fix That with ZizkaDB

Most OpenClaw setups are built to act. Few are built to learn from what they did.

The agent answers messages, calls tools, runs on a schedule, and when something goes wrong a person opens a log file and starts guessing.

This guide is about the step after installation. If you have not installed the ZizkaDB plugin yet, start with our companion how-to, How to Add ZizkaDB to OpenClaw, which covers installation and configuration. Here we assume the plugin is running and ask a different question: how do you use the record it creates to make the agent, and the people responsible for it, noticeably better?

We cover seven ways: self-inspection inside a conversation, operator debugging, cost control, drift detection, safe upgrades, guardrails that use the record, and evidence for customers and auditors. Each has a small snippet and a business reason.

A note on scope. ZizkaDB is an independent project and is not affiliated with or endorsed by OpenClaw. Plugin details come from the ClawHub listing for the ZizkaDB plugin (version 0.1.1 when we last checked, on 12 November 2026), and they may have changed, so check the listing before relying on an option. SDK parameter names below are illustrative.

ZizkaDB records events and links them; it does not block actions, judge whether an agent was right, or make any system compliant with a law.

From a log to a causal record

An ordinary log tells you what happened in order. The ZizkaDB plugin records each OpenClaw turn as a chain of linked events: a message arrives, a tool is called, a result returns, the model answers, a reply is sent.

According to the listing, each turn is one hash chain, and each conversation session maps to a ZizkaDB session. That structure is what makes the rest possible.

Because every event points to what caused it, you can ask why a reply was sent, what else was affected by a bad tool result, and whether the agent behaves differently this month than last. None of those questions can be answered from a flat log without a person reconstructing the story.

Let the agent look back at its own conversation

The plugin offers two optional in-agent tools, both off by default: zizkadb_why, which returns the causal chain behind an event, and zizkadb_search, which searches past events. You enable them through the tools allowance in the OpenClaw configuration.

Per the listing, each tool is limited to the current conversation, the scope comes from OpenClaw's trusted session context and not from model arguments, and results are labelled as untrusted historical data. This is a deliberate safety choice.

An agent can answer a customer who says that is not what you told me earlier, by checking what it actually did, and it cannot browse other customers' histories.

Business value: fewer escalations that turn on whose memory is right. The agent can quote its own earlier tool result instead of improvising.

Two cautions. Treat the returned history as data, not instructions, which is why the listing labels it untrusted: a past tool result may contain text that tried to steer the agent. And do not expect these tools to give the agent memory across customers or sessions. Cross-conversation analysis is for operators, covered next.

Give operators a fast path from complaint to cause

When a customer says the agent did something wrong, the operator needs the answer in minutes. With the SDK and your own key, an operator can query across the whole agent, not only one conversation.

errs = await db.query(agent="support-bot", event="tool_error", limit=20)
(await db.why(errs[0].id)).print()

A practical routine for a support lead:

  • Find the session from the customer's message or time.
  • Open the turn and read the chain from the user message to the reply.
  • Check each tool call and result for errors or surprises.
  • Decide whether the cause was a bad input, a tool fault, a prompt problem or a model slip.
  • Record the finding so that the next person sees it.

You can write that finding back as an event linked to the turn, which keeps the explanation next to the evidence.

await db.log(agent="support-ops", event="finding", data={"turn": errs[0].id, "cause": "tool timeout returned empty result", "fix": "retry with backoff"}, parent_id=errs[0].id)

Business value: mean time to answer a complaint falls from days to minutes in the cases where the chain is complete, and the answer is something you can show, not recall.

See where the money goes

The plugin records token usage with each model answer, provided that hooks.allowConversationAccess is enabled in OpenClaw's configuration, as the listing describes. Without it, messages and tool activity still record, and the gateway log notes the gap at startup.

With usage recorded per turn, you can ask which agents, channels, tools and conversations drive cost. Typical findings are boring and valuable: a cron job that retries forever, a channel where long threads re-send large context every turn, a tool that returns huge payloads the model then reads in full.

A weekly routine:

  1. Rank agents and channels by token use.
  2. List the most expensive turns and read two or three chains.
  3. For each, ask whether the spend bought a better answer.
  4. Fix the biggest avoidable cause first, whether that is trimming a tool result, shortening context or capping retries.

Business value: cost control based on evidence. We have written elsewhere about a team that turned a huge monthly bill into a manageable one; the method is the same here, and your own numbers will differ.

Detect drift before customers do

Agents change when prompts change, models update, tools evolve or inputs shift. The result is rarely a crash. It is a slow change in behaviour: more tool errors, longer answers, different tool choices.

ZizkaDB offers baseline comparison of recent behaviour against a reference period. Pick a few signals that fit an OpenClaw agent:

  • SignalWhy it matters Tool error rate per toolA rising rate points to a broken integration or a prompt that misuses a tool Tools called per turn A jump suggests loops or over-eager behaviour Tokens per turn A jump suggests bloated context or a model change Reply lengthA shift may signal a prompt or model change Share of turns ending in agent_errorA direct reliability measure
drift = await db.baseline(agent="support-bot", window="7d", reference="30d")

Review a drift report weekly. When something moves, open the turns behind it and look for the change, such as a prompt edit on a particular date. Drift is a prompt to investigate, not proof that something is wrong.

Business value: you find regressions in days, from your own data, instead of from a customer complaint.

Upgrade models and prompts without guessing

Changing the model or the prompt behind a live agent is the riskiest routine change you make. A safer method uses your own history.

Pick a sample of past turns that represent your real traffic, including difficult ones and ones where the agent erred. Replay the inputs through the new version in a test setup, recorded as a separate agent name such as support-bot-shadow, so it never mixes with production.

Compare the outputs: tool choices, errors, length and, for important cases, a human read of the answers. Review the disagreements by following their chains. Roll out to a small share of traffic first and watch the same signals.

Keep the production and shadow agents distinct, since ZizkaDB keeps a hash chain per agent. If you replay sensitive conversations, apply the same redaction and retention rules as in production.

Business value: you learn what an upgrade changes before it reaches customers, and you have a record of what you checked.

Build guardrails from the record

The plugin is observe-only. It does not block or alter messages or tool calls, and a failed write does not affect the agent. That is a feature: adding an audit layer cannot break your agent. It also means the plugin does not protect you from a bad action. Protection comes from OpenClaw's permissions, sandboxing and least privilege, which the record then helps you tune.

Here is how to use the record to improve those controls.

Find over-broad permissions. List which tools the agent actually calls over a month. Tools never used are candidates for removal.

Find risky patterns. Query for turns where a tool with side effects, such as sending a message or changing data, followed content from an outside source. Review whether a human should approve those.

Tag untrusted inputs. If your agent reads web pages, documents or messages from other agents, make sure those inputs are identifiable in the record, so you can later find every action that depended on them.

Check approvals. Where a person approves a risky action, record what they saw and did, so the approval means something.

risky = await db.query(agent="support-bot", event="tool_call", where={"tool": "send_email"}, limit=100)

Be clear about the limits. ZizkaDB does not detect prompt injection, and it cannot tell whether content an agent read was malicious. It lets you trace what an agent read before it acted, which is what you need to investigate after the fact and to design stronger controls.

Produce evidence for customers, auditors and your own board

A record that can be queried is also a record that can be shared. For customers: a clear account of what the agent did in a disputed case, drawn from the chain. For auditors and security reviewers: an export of a defined period, plus the result of a chain verification, with the chain head stored outside the database so that the history cannot be quietly rewritten.

check = await db.verify_chain(agent="support-bot")
export = await db.export_events(agent="support-bot", since="2026-11-01", until="2026-11-20")

For regulators and counsel: if your agents fall under rules that require automatic event recording, such as EU AI Act Article 12 for high-risk systems, a linked, tamper-evident record is the kind of evidence those rules point toward. Whether any given system is high-risk depends on what it does, and the application dates have been moving, so take legal advice. ZizkaDB supports record keeping and does not by itself make a system compliant.

Use read-only, expiring keys when you give outsiders access, and decide what content you store. When config.captureContent is false, the plugin does not store prompts, replies, tool arguments or tool results, but still records tool names, models, token usage and errors. For agents handling personal or regulated data, start with capture off and turn it on only where you have a reason and a lawful basis.

A worked example, as a composite

This is illustrative and not a real customer. A small online store runs an OpenClaw support agent across chat and email. It answers order questions, looks up shipments with a tool and can issue small refunds under a set limit.

In week one the team installs the plugin and leaves content capture off. In week two the cost review shows that a handful of long conversations account for much of the token spend, because a shipment tool returns the full order history on every call. They trim the tool result, and spend falls.

In week three the drift report shows the share of tool errors on the shipment tool rising. The chains show a courier API returning empty results at certain hours, so the agent tells customers their order cannot be found. The team adds a retry and a clear fallback message.

In week four a customer disputes a refund. The operator opens the turn, sees the user message, the order lookup, the refund tool call and the reply, and replies with a precise account within minutes.

In week five the team tests a new model by replaying a sample of past turns as a shadow agent, finds that it chooses the refund tool more eagerly, and adjusts the prompt before rollout.

None of these steps required the agent itself to be smarter. They required the team to see what it was doing.

Common mistakes

  • Installing and never looking. A record nobody reviews is an expense. Schedule a weekly review.
  • Using one agent name for everything. Distinct names keep chains, baselines and permissions clean.
  • Storing content by default. Capture content deliberately, not out of habit.
  • Trusting past tool results as instructions. History is data. Treat it as untrusted.
  • Skipping the chain head. Store it outside the database, or verification proves less.
  • Confusing observation with protection. The plugin watches. Controls come from permissions and sandboxing.
  • Forgetting one-shot runs. Per the listing, local one-shot runs are not recorded, because recording happens in the running gateway.

A two week plan

Days 1 to 2: confirm the plugin is recording, give each agent its own name and decide on content capture with your data protection lead.

Days 3 to 4: enable the in-agent tools on one agent and test the why and search behaviour in a conversation.

Days 5 to 6: run the first cost review and fix the biggest avoidable cause.

Days 7 to 8: pick drift signals, take the first baseline and schedule the weekly review.

Days 9 to 10: review tool permissions against actual use and tighten them.

Days 11 to 12: run a replay test of one prompt or model change as a shadow agent.

Days 13 to 14: verify the chain, store the head elsewhere, export a sample period and hand it to someone who did not build the system.

Where ZizkaDB fits, and where it stops

ZizkaDB is an open source causal audit database for AI agents, with a self hosted edition that runs in a single Docker container and a managed Cloud edition at db.zizka.ai. It records events with parent links, answers why() for any decision, supports session replay, time travel, drift baselines and export, and shows whether stored history has been altered through a hash chain.

It does not prevent bad actions, detect manipulation, judge correctness or deliver compliance. The open source edition records one agent per install, so fleets and agent to agent tracing use the Cloud edition.

The record is only as complete as what the plugin and your own

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.