Agent Tools

The @agnt-rcpt/openclaw plugin registers two tools that the OpenClaw agent can call directly during a session:

Tool	Purpose
ar_query_receipts	Query and summarise receipts from the current or past sessions
ar_verify_chain	Verify the cryptographic integrity of a receipt chain

These tools are not visible by default. See Installation: Tool visibility for the alsoAllow config required to expose them to the agent.

---

ar_query_receipts

Returns a summary of receipts matching the given filters, including breakdowns by risk level, outcome status, and action type.

Parameters

Parameter	Type	Description
action_type	string (optional)	Filter by action type, e.g. filesystem.file.read
risk_level	string (optional)	Filter by risk level: low, medium, high, critical
status	string (optional)	Filter by outcome: success or failure
limit	number (optional)	Maximum number of results to include
session_id	string (optional)	Restrict to a specific session; defaults to the current session

All parameters are optional. Called with no arguments the tool returns a summary of all receipts in the current session.

Example

Agent prompt:

Query all high-risk actions from this session

Tool response:

{
  "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 }
  ]
}

Tip

The agent can use ar_query_receipts to self-audit mid-session — for example, to confirm which files it has already written before deciding whether to proceed with a destructive operation.

---

ar_verify_chain

Verifies the cryptographic integrity of a receipt chain: checks every Ed25519 signature and every SHA-256 hash link between receipts.

Parameters

Parameter	Type	Description
chain_id	string	The chain to verify. Defaults to the current session’s chain if omitted.

Example — valid chain

Agent prompt:

Verify the audit trail for this session

Tool response:

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

Example — broken chain

If a receipt has been modified or removed after it was signed, the tool reports the first position where verification fails:

Chain "chain_openclaw_main_sid-42": BROKEN at position 7
Tamper detected! The following receipts have issues:
  [7] urn:receipt:...: invalid signature, hash link

A broken chain means receipts at or after the reported position cannot be trusted

A valid chain guarantees that no receipt was altered, inserted, or deleted after signing. The strength of that guarantee depends on where the signing key lives: in the default in-process configuration the key is stored on disk alongside the agent, so a compromised agent process could read the key and forge receipts. With daemonForwarding: true the key lives in agent-receipts-daemon — the agent process cannot read the key material or rewrite already-signed receipts. Note that the daemon listens on a local Unix socket: any process running as the same OS user can still connect and emit new events; preventing that requires the daemon to run as a dedicated OS user (the production deployment). If the chain is broken, treat all receipts from the reported position onward as potentially compromised and investigate before relying on them.

---

Tool visibility

Both tools require explicit opt-in. The default "coding" profile in OpenClaw does not expose plugin-registered tools. Add them to alsoAllow in your openclaw.json:

{
  "tools": {
    "profile": "coding",
    "alsoAllow": ["ar_query_receipts", "ar_verify_chain"]
  }
}

See Installation: Tool visibility for alternative configurations, including profile-level and plugin-level allowlisting.