openclaw-agent-receipts

Agent Receipts plugin for OpenClaw

Cryptographically signed, hash-linked audit trail for every tool call an OpenClaw agent makes.

Built on @agnt-rcpt/sdk-ts and @sinclair/typebox.

What it looks like

After a session where the agent reads files, runs a command, browses a page, and writes output, querying the audit trail returns:

{
  "total_receipts": 5,
  "total_chains": 1,
  "by_risk": { "low": 4, "high": 1 },
  "by_status": { "success": 4, "failure": 1 },
  "by_action": {
    "filesystem.file.read": 2,
    "filesystem.file.create": 1,
    "system.command.execute": 1,
    "system.browser.navigate": 1
  },
  "results": [
    { "id": "rec-…01", "timestamp": "2026-04-01T02:10:01Z", "action": "filesystem.file.read",    "risk": "low",  "target": "read_file",        "status": "success", "sequence": 1 },
    { "id": "rec-…02", "timestamp": "2026-04-01T02:10:02Z", "action": "filesystem.file.read",    "risk": "low",  "target": "read_file",        "status": "failure", "sequence": 2 },
    { "id": "rec-…03", "timestamp": "2026-04-01T02:10:03Z", "action": "system.command.execute",  "risk": "high", "target": "run_command",      "status": "success", "sequence": 3 },
    { "id": "rec-…04", "timestamp": "2026-04-01T02:10:04Z", "action": "system.browser.navigate", "risk": "low",  "target": "browser_navigate", "status": "success", "sequence": 4 },
    { "id": "rec-…05", "timestamp": "2026-04-01T02:10:05Z", "action": "filesystem.file.create",  "risk": "low",  "target": "write_file",       "status": "success", "sequence": 5 }
  ]
}

Verifying the chain confirms nothing was tampered with:

Chain "chain_openclaw_main_sid-42" is valid: 5 receipts, all signatures and hash links verified.

Every receipt is a signed W3C Verifiable Credential — parameters are hashed by default (with optional plaintext disclosure via parameterDisclosure), and each receipt is hash-linked to the previous one, forming a tamper-evident chain.

Why receipts?

AI agents that read files, run commands, and browse the web are powerful — but that power needs accountability. When an agent operates autonomously, you need to know exactly what it did, prove that the record hasn't been tampered with, and keep sensitive details private.

Use cases:

Post-incident review — your agent ran overnight and something broke. The receipt chain shows exactly which commands it ran, in what order, and whether each succeeded or failed — with cryptographic proof that the log hasn't been altered after the fact.
Compliance and audit — regulated environments require evidence of what systems did and why. Receipts are W3C Verifiable Credentials with Ed25519 signatures, giving auditors a tamper-evident trail they can independently verify.
Safer autonomous agents — the agent can query its own audit trail mid-session. Before taking a high-risk action, it can check what it has already done and whether previous steps succeeded, enabling self-correcting workflows.
Multi-agent trust — when agents collaborate, receipts serve as proof of prior actions. Agent B can verify that Agent A actually completed step 1 before proceeding to step 2, without trusting a shared log.
Cost and usage tracking — every tool call is classified by type and risk level, giving you a structured breakdown of what your agent spent its time on across sessions.

Beyond local storage

Today, receipts are stored locally in SQLite — fully under your control. The Agent Receipts protocol is designed for receipts to travel further when you choose: publishing to a shared ledger, forwarding to a compliance system, or exchanging with other agents as proof of prior actions. The receipts are portable W3C Verifiable Credentials, but where they go is always your decision.

How it works

Every time the OpenClaw agent executes a tool, this plugin:

Classifies the action using the Agent Receipts taxonomy
Creates a signed receipt — a W3C Verifiable Credential with Ed25519 proof
Hash-links it into a per-session chain (tamper-evident)
Stores it in a local SQLite database

The agent also gets two introspection tools to query and verify its own audit trail.

OpenClaw Gateway
  │
  ├─ before_tool_call ──► capture params + timing
  │
  ├─ [tool executes]
  │
  └─ after_tool_call ──► classify → sign → chain → store

Install

openclaw plugins install @agnt-rcpt/openclaw

Then enable the plugin in your OpenClaw config. See docs/INSTALL.md for tool visibility setup and configuration options.

CLI — Receipt Explorer

Query and verify receipts outside of agent sessions, useful for auditing and debugging.

Subcommand	Description
`receipts`	List and query receipts (returns a collection)
`verify`	Verify chain integrity (signatures + hash links)
`export`	Export receipts as JSON-LD W3C Verifiable Credentials

# List all receipts
npx @agnt-rcpt/openclaw receipts

# Filter by risk level
npx @agnt-rcpt/openclaw receipts --risk high

# Filter by action type and output as JSON
npx @agnt-rcpt/openclaw receipts --action system.command.execute --json

# `receipts` always returns a collection — use `export --id` to fetch a single receipt by ID
npx @agnt-rcpt/openclaw export --id urn:receipt:abc-123

# Filter receipts --json output with jq (fields: id, action, risk, target, status, sequence, chain_id, timestamp)
npx @agnt-rcpt/openclaw receipts --json \
  | jq '.receipts[] | select(.risk == "high" and .action == "system.command.execute")'

# Verify all chains
npx @agnt-rcpt/openclaw verify

# Verify a specific chain
npx @agnt-rcpt/openclaw verify --chain chain_openclaw_main_sid-42

# Export a chain as JSON-LD (full W3C Verifiable Credentials)
npx @agnt-rcpt/openclaw export --chain chain_openclaw_main_sid-42

# Export as a W3C Verifiable Presentation envelope
npx @agnt-rcpt/openclaw export --chain chain_openclaw_main_sid-42 --format presentation

Note: parameterDisclosure controls what gets stored inside receipts — it does not add fields to receipts --json output. To inspect parameters_disclosure values, export the full receipt with export --id or export --chain. See Parameter disclosure for configuration details.

Run npx @agnt-rcpt/openclaw --help for all options including --status, --limit, and --db.

Agent tools

`ar_query_receipts`

Search the audit trail by action type, risk level, or outcome status. Returns receipt summaries and aggregate statistics.

> Query all high-risk actions from this session

{
  "total_receipts": 12,
  "results": [
    { "action": "filesystem.file.delete", "risk": "high", "target": "delete_file", "status": "success", "sequence": 7 },
    { "action": "system.command.execute", "risk": "high", "target": "run_command", "status": "success", "sequence": 3 }
  ]
}

`ar_verify_chain`

Cryptographically verify the integrity of the receipt chain. Checks Ed25519 signatures, hash links, and sequence numbering.

> Verify the audit trail for this session

Chain "chain_openclaw_main_sid-42" is valid: 12 receipts, all signatures and hash links verified.

What's in a receipt?

Each receipt is a W3C Verifiable Credential signed with Ed25519, recording:

Field	What it captures
Issuer	Which agent performed the action (`did:openclaw:<agentId>`)
Principal	Which session authorized it (`did:session:<sessionKey>`)
Action	What happened — classified type, risk level, target tool
Outcome	Success/failure status and error details
Chain	Sequence number + SHA-256 hash link to previous receipt
Privacy	Parameters are hashed by default; opt in via `parameterDisclosure` to include selected fields in plaintext
Proof	Ed25519Signature2020 with verification method

Taxonomy

The plugin maps OpenClaw tool names to Agent Receipts action types:

OpenClaw tool	Action type	Risk
`read_file`	`filesystem.file.read`	low
`write_file`	`filesystem.file.create`	low
`edit_file`	`filesystem.file.modify`	medium
`delete_file`	`filesystem.file.delete`	high
`run_command`	`system.command.execute`	high
`browser_navigate`	`system.browser.navigate`	low
`browser_click`	`system.browser.form_submit`	medium
`send_message`	`system.application.control`	medium

See taxonomy.json for the full 20-tool mapping. Override with a custom file via the taxonomyPath config option.

Configuration

All settings are optional — the plugin works out of the box with sensible defaults.

Setting	Default	Description
`enabled`	`true`	Generate receipts for tool calls
`dbPath`	`~/.openclaw/agent-receipts/receipts.db`	SQLite receipt database path
`keyPath`	`~/.openclaw/agent-receipts/keys.json`	Ed25519 signing key pair path
`taxonomyPath`	(bundled)	Custom tool-to-action-type mapping
`parameterDisclosure`	`false`	Selectively disclose parameters in plaintext (see below)
`daemonForwarding`	`false`	Forward each tool call to a local agent-receipts daemon over AF_UNIX (see Daemon forwarding)

Default config block:

{
  "plugins": {
    "entries": {
      "openclaw-agent-receipts": {
        "config": {
          "enabled": true,
          "dbPath": "~/.openclaw/agent-receipts/receipts.db",
          "keyPath": "~/.openclaw/agent-receipts/keys.json",
          // "taxonomyPath": "/path/to/custom-taxonomy.json",  // optional — overrides bundled taxonomy
          "parameterDisclosure": false,  // false | true | "high" | string[]
          "daemonForwarding": false       // boolean | { enabled: boolean }
        }
      }
    }
  }
}

Ed25519 signing keys are generated automatically on first run and persisted to keyPath.

Parameter disclosure

By default, action parameters are hashed but not stored in plaintext. Enable parameterDisclosure to selectively disclose specific fields per action type — useful for auditing high-risk commands without exposing sensitive data on lower-risk calls.

{
  "plugins": {
    "entries": {
      "openclaw-agent-receipts": {
        "config": {
          "parameterDisclosure": "high"
        }
      }
    }
  }
}

Options:

Value	Behavior
`false`	Hashes only — no plaintext (default)
`true`	Disclosure enabled for all action types
`"high"`	Disclosure enabled for `high` and `critical` risk actions only
`["system.command.execute"]`	Disclosure enabled for specific action types

With "high" enabled, a system.command.execute receipt includes:

{
  // ...other receipt fields
  "parameters_hash": "sha256:9c84a8c9...",
  "parameters_disclosure": {
    "command": "echo \"Testing agent-receipts plugin fix\""
  }
}

The hash always covers the full original parameters regardless of disclosure config. Only the first matching field from the taxonomy's disclosure_fields list is included in parameters_disclosure, and non-string values are JSON-stringified. Disclosed values are signed and durable — do not list fields that may contain secrets.

Daemon forwarding

Off by default. When enabled, each tool call is also forwarded to a local agent-receipts daemon over AF_UNIX (ADR-0010), in addition to the in-process receipt path. The daemon canonicalises and signs frames out-of-process so plugins do not need to hold key material.

{
  "plugins": {
    "entries": {
      "openclaw-agent-receipts": {
        "config": {
          "daemonForwarding": true   // or { "enabled": true }
        }
      }
    }
  }
}

Trust boundary: enabling daemon forwarding sends raw input and output JSON across a process boundary so the daemon can canonicalise (RFC 8785) and SHA-256 hash the call. The daemon does not persist the raw values — only their hashes appear in stored receipts — but the bytes are observable on the socket and in daemon memory while the frame is in flight. This is a stricter trust boundary than the in-process parameterDisclosure contract, which is why it is opt-in.

Forwarding is fire-and-forget: a missing or unreachable daemon never blocks the plugin or affects in-process receipt creation. The socket path resolves from AGENTRECEIPTS_SOCKET, then $TMPDIR/agentreceipts/events.sock on macOS, or $XDG_RUNTIME_DIR/agentreceipts/events.sock on Linux.

Setting up the daemon

daemonForwarding requires the agent-receipts daemon to be installed and running locally. If the daemon is absent or stopped, forwarding is silently skipped and in-process receipts are unaffected.

macOS (Homebrew — recommended):

brew install agent-receipts/tap/agent-receipts-daemon
brew services start agent-receipts-daemon

Linux (one-command install):

curl -fsSL https://github.com/agent-receipts/ar/releases/latest/download/install.sh | sh
sudo loginctl enable-linger $USER   # one-time root step; log out and back in after

Linux — openclaw gateway running as a system service (User=openclaw in the unit file):

XDG_RUNTIME_DIR is not set automatically for system services, so the plugin may resolve the wrong socket path. Add it via a drop-in override:

sudo systemctl edit openclaw

[Service]
Environment=XDG_RUNTIME_DIR=/run/user/1001   # replace 1001 with: id -u openclaw

Restart the gateway after saving.

Full daemon documentation and the migration guide are at agentreceipts.ai/getting-started/daemon-setup/.

Project structure

src/
  index.ts          # Plugin entry — wires hooks, tools, service
  cli.ts            # Receipt Explorer CLI (npx @agnt-rcpt/openclaw)
  hooks.ts          # before_tool_call / after_tool_call → receipt creation
  classify.ts       # Tool name → action type + risk level classification
  chain.ts          # Per-session hash-linked chain state
  tools.ts          # ar_query_receipts + ar_verify_chain
  config.ts         # Config resolution + Ed25519 key management
taxonomy.json       # Default OpenClaw tool → action type mappings

Development

pnpm install
pnpm test              # run the test suite
pnpm run typecheck     # TypeScript strict mode
pnpm test:coverage     # with V8 coverage


Language	TypeScript ESM, strict mode
Testing	Vitest (colocated `*.test.ts` files)
Runtime deps	`@agnt-rcpt/sdk-ts` + `@sinclair/typebox`

Ecosystem

Repository	Description
agent-receipts/spec	Protocol specification, JSON Schemas, canonical taxonomy
agent-receipts/sdk-ts	TypeScript SDK
agent-receipts/sdk-py	Python SDK (PyPI)
agent-receipts/openclaw (this plugin)	OpenClaw integration
agent-receipts/ar/mcp-proxy	MCP proxy + CLI

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 160 Commits
.claude		.claude
.github		.github
docs		docs
scripts		scripts
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
lefthook.yml		lefthook.yml
openclaw.plugin.json		openclaw.plugin.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
taxonomy.json		taxonomy.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

openclaw-agent-receipts

Agent Receipts plugin for OpenClaw

What it looks like

Why receipts?

Beyond local storage

How it works

Install

CLI — Receipt Explorer

Agent tools

`ar_query_receipts`

`ar_verify_chain`

What's in a receipt?

Taxonomy

Configuration

Parameter disclosure

Daemon forwarding

Setting up the daemon

Project structure

Development

Ecosystem

License

About

Uh oh!

Releases 12

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

openclaw-agent-receipts

Agent Receipts plugin for OpenClaw

What it looks like

Why receipts?

Beyond local storage

How it works

Install

CLI — Receipt Explorer

Agent tools

ar_query_receipts

ar_verify_chain

What's in a receipt?

Taxonomy

Configuration

Parameter disclosure

Daemon forwarding

Setting up the daemon

Project structure

Development

Ecosystem

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`ar_query_receipts`

`ar_verify_chain`

Packages