How to Add ZizkaDB to OpenClaw: A Tamper-Evident Audit Trail for Every Agent Turn

November 12, 2026 · 1,670 words
If you run agents on OpenClaw, you already have logs. What you probably do not have is a record that answers three questions after something goes wrong: what did the agent receive, which tool call followed because of it, and can anyone show the record was not edited afterwards? This guide shows how to add ZizkaDB to OpenClaw with the ZizkaDB plugin, so each turn is recorded as a causally linked, tamper-evident audit trail.

The setup takes a few minutes. The business value is that the next time an agent sends the wrong message or calls the wrong tool, you replay the turn instead of guessing.

A note on scope. ZizkaDB is an independent project and is not affiliated with or endorsed by OpenClaw. The plugin details below come from the plugin's ClawHub listing (version 0.1.1 when we checked on 12 November 2026) and OpenClaw's plugin documentation. Plugin versions change, so check the listing before you rely on a specific option.

What you get

The ZizkaDB plugin records each OpenClaw agent turn in ZizkaDB. According to its listing, recorded items include messages, tool calls, model outputs, token usage and replies. Each OpenClaw turn becomes one hash chain, and each conversation session maps to a ZizkaDB session. Tamper evidence comes from per agent hash chaining, which you can verify through the ZizkaDB API.

Two design choices make it safe to try. The plugin is observe-only: it does not block, alter or delay messages or tool calls, and a failed write does not affect the agent. And the optional in-agent tools are off by default.

Before you start

You need three things:

A running OpenClaw gateway. The plugin records inside the running gateway, so it covers chat channels, cron jobs and openclaw agent turns.
A ZizkaDB server. Use ZizkaDB Cloud at db.zizka.ai with an API key, or self host the open source server, which runs from a single docker command.
A supported Node.js version. The listing names Node.js 24.16 or later, which it describes as OpenClaw's own requirement.
Step 1: install the plugin

From ClawHub, run:

bash
openclaw plugins install clawhub:@zizka-ai/zizkadb

You can also install it from npm. Installs from outside ClawHub need the force flag:

bash
openclaw plugins install npm:zizkadb-openclaw --force

OpenClaw asks you to approve the plugin's permissions during install. In scripts, you can pass the accept capabilities flag instead of answering the prompt. Read the permission list before approving, as you would for any plugin that touches conversation data.

OpenClaw documents the clawhub and npm source prefixes so you can pick the source explicitly. Without a prefix, bare package names may resolve differently depending on your OpenClaw version.

Step 2: configure openclaw.json

Edit the OpenClaw config file, usually at ~/.openclaw/openclaw.json, and restart the gateway afterwards. The listing names these settings:

plugins.allow should include zizkadb.
plugins.entries.zizkadb.enabled should be true.
hooks.allowConversationAccess should be true if you want model outputs and token usage recorded. Without it, messages and tool activity are still recorded, and the gateway log notes the gap at startup.
config.apiKey holds your ZizkaDB key, from Cloud settings or your own server.
config.host is the server URL for self hosted use, for example http://localhost:8000.
config.agent is the agent name inside ZizkaDB. The default is openclaw.
config.captureContent controls whether content is stored (see Step 5).

You can use the environment variables ZIZKADB_API_KEY and ZIZKADB_HOST instead of putting the key and host in the file. That keeps secrets out of a config you might commit or share. An illustrative layout, to be checked against the listing:

json
{
  "plugins": {
    "allow": ["zizkadb"],
    "entries": {
      "zizkadb": {
        "enabled": true,
        "config": { "host": "http://localhost:8000", "agent": "support-bot" }
      }
    }
  },
  "hooks": { "allowConversationAccess": true }
}

Give each agent its own name through config.agent. ZizkaDB keeps a hash chain per agent, so distinct names keep your audit trails separate.

Step 3: verify it loaded

OpenClaw's plugin documentation describes an inspect command with a runtime flag for proving that a plugin registered its hooks and tools:

bash
openclaw plugins inspect zizkadb --runtime --json

Then send your agent a message through a normal channel and open the ZizkaDB dashboard. You should see a session with the turn in it. If nothing appears, check that the gateway was restarted after the config change, and remember that one-shot openclaw agent --local runs are not recorded, because recording happens in the running gateway.

Step 4: see what gets recorded

The listing maps OpenClaw hooks to ZizkaDB events:

What happens in OpenClaw	ZizkaDB event	What is captured
A message arrives	user_message	Text, sender, media count
A tool is called	tool_call, then tool_result or tool_error	Tool name, arguments, result or error, duration
The model answers	llm_end	Provider, model, answer, token usage
A reply is sent	assistant_response	Sent text, delivery success
A run fails	agent_error	Error, duration

Events carry metadata including the source, the agent ID and the channel. Values longer than 8,000 characters are truncated, so very long tool results are stored in shortened form.

For a business reader, the useful part is the chain. A user message leads to a tool call, which leads to a result, which leads to a reply. When the reply is wrong, you start from it and walk backwards.

Step 5: decide what content to store

Conversation content can be sensitive. The plugin gives you a switch. When config.captureContent is false, prompts, replies, tool arguments and tool results are not stored. Tool names, models, token usage and errors are still recorded.

A sensible approach is to start with content capture off for any agent that handles personal or regulated data, and turn it on only where you have a reason and a legal basis for keeping it. You keep the shape of what happened, which tools ran, how often they failed and what they cost, without keeping the words. Whether you may store a given conversation depends on your data protection obligations, so check with whoever owns that for your organisation.

Step 6: add the optional in-agent tools

Two tools are off by default: zizkadb_why, which returns the causal chain behind an event, and zizkadb_search, which searches past events. Enable them with tools.alsoAllow set to both names.

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. Agent wide audits need the dashboard or the SDK with your own key. That design matters: an agent can look back at its own conversation without being able to read other customers' histories.

Step 7: query the trail

For investigation outside the agent, use the zizkadb-sdk package. According to the listing, db.query finds recent events and db.why walks back the causal chain from an event. A minimal sketch, with parameter names to be checked against the SDK reference:

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

The dashboard shows sessions, the causal graph, tool error rates and token costs, which is useful for the people who do not write code: support leads, finance and compliance.

Step 8: verify the chain and keep the head somewhere else

A per agent hash chain makes later edits to the record detectable. You can check it through the chain endpoint at GET /v1/events/chain. Run the check on a schedule and store the chain head outside the ZizkaDB database, for example in a separate system, so that nobody with database access can rewrite both the history and its head. The chain shows that the record is unchanged. It does not show that the agent was right.

Gotchas
Restart the gateway after any config change. The plugin runs inside it.
Without hooks.allowConversationAccess, you lose model outputs and token usage. Messages and tool activity still record.
One-shot local runs are not recorded.
Long values are truncated at 8,000 characters.
Installing from npm outside ClawHub needs the force flag.
Do not paste API keys into shared config files. Use the environment variables.
Why this matters beyond debugging

Three business outcomes follow from this setup.

Faster incident response. When a customer complains about an agent action, you open the turn, read the chain and answer in minutes.

Cost visibility. Token usage is recorded per model call, so you can see which agents and tools drive spend.

Evidence for oversight and record keeping. If your agents fall under rules such as EU AI Act Article 12 on automatic event recording for high risk systems, a causally linked, tamper-evident record is the kind of evidence that points toward. Whether a given system is high risk depends on what it does. ZizkaDB supports record keeping and investigation. It is not legal advice and does not by itself make any system compliant with the EU AI Act or any other law.

If your OpenClaw agents also read content from other agents, for instance on a social network such as Moltbook, which researchers have reported runs mostly on OpenClaw agents, the same trail lets you trace what an agent read before it acted. ZizkaDB records that. It cannot tell whether content was malicious or true, and it does not stop an agent from being persuaded.

Limits to remember

The plugin records. It does not block or filter anything, so it complements least privilege and sandboxing and does not replace them. The ClawHub listing shows an automated security scan as passing, which is an automated check and not a guarantee, so review the permissions yourself. The open source edition of ZizkaDB records one agent per install, and fleets or agent to agent tracing use the Cloud edition.

Get started

Install the plugin, give one agent its own name, run it for a day with content capture off, and open the dashboard. Then pick a single tool call and run why() on it. That is the first answer your current logs cannot give.

Corrections: if you represent a party named here and believe a statement is inaccurate, contact us and we will review it promptly.

Sources: ClawHub listing for the ZizkaDB OpenClaw plugin (clawhub.ai/zizka-ai/plugins/zizkadb); OpenClaw documentation, Plugins and Manage plugins (docs.openclaw.ai).