openclaw-occ

Append-only cryptographic receipts for every OpenClaw agent action.

After each tool execution (bash, file read, browser navigation, API call), the plugin computes SHA-256 digests of the inputs and outputs locally, commits a signed receipt to an OCC notary, and stores the proof in a JSONL file on your machine. If a malicious skill or prompt injection causes actions that shouldn't have happened, those actions appear in the log without a valid proof path — or don't appear at all.

Quick start (10 seconds)

# 1. Install
npm install -g openclaw-occ

# 2. Copy to OpenClaw extensions folder
openclaw-occ install

# 3. Restart OpenClaw, then in any chat:
occ audit

That's it. Works out of the box in remote mode against the hosted OCC notary.

Privacy model

By default, raw tool inputs and outputs never leave your machine.

The plugin computes SHA-256 digests locally and sends only:

| What's sent to the notary | What stays local | |---|---| | stepId (UUID per action) | Full tool input | | toolName (e.g. "bash") | Full tool output | | inputDigest (SHA-256) | Session ID | | outputDigest (SHA-256) | Model name | | timestamp | Elapsed time | | clientNonce (32 random bytes) | Run ID |

To verify a proof, you re-derive the digests from your local data and compare. No raw content ever needs to go back to the notary.

opt-in: sendRawBytes — if you self-host your own notary and need full payload retention for legal hold, set sendRawBytes: true in occ.json. Never use this with a third-party notary.

Trust model

| Claim | Basis | |---|---| | This action happened | Notary signature + monotonic counter | | This is the sequence | Counter increments; gaps are detectable | | The content is intact | SHA-256 digest matches on re-verification | | The notary is legitimate | Ed25519 public key saved at deploy time |

What OCC does not claim:

• It does not prevent malicious actions — it makes them visible after the fact.
• A software-mode notary key is stored in Cloudflare KV. A sophisticated attacker who controls the notary infrastructure could forge a proof. For stronger guarantees, use a measured-tee notary (AWS Nitro Enclave) where the key is sealed in hardware and the enclave measurement is public.
• Counter gaps indicate a missing proof. They do not conclusively prove an attack — a transient network failure produces the same signal.

Install

From npm (recommended):

npm install -g openclaw-occ
openclaw-occ install

From source:

node bin/install.js

OpenClaw discovers the plugin on next start by scanning ~/.openclaw/extensions/ for openclaw.extensions in package.json.

Configuration

Create ~/.openclaw/workspace/occ.json:

{
  "mode": "remote",
  "notaries": ["https://occ-notary.gjp9tm85hq.workers.dev/commit"]
}

Modes

| Mode | What it does | |------|-------------| | stub | Local SHA-256 only. No network call. Proofs are self-contained hashes. Best for offline or privacy-first use. | | remote | POST to one notary endpoint. Returns a signed OCC proof with Ed25519 signature + monotonic counter. Default. | | tee | POST to multiple notaries in parallel. All results stored. Falls back gracefully if some are unreachable. Best for compliance/redundancy. |

Tee example (your own notary + hosted fallback)

{
  "mode": "tee",
  "notaries": [
    "https://my-own-notary.example.com/commit",
    "https://occ-notary.gjp9tm85hq.workers.dev/commit"
  ]
}

Chat commands

Type these in any connected chat (WhatsApp, Telegram, Slack, Discord…):

occ audit          — today's summary: action count, proof status, last tool run
occ verify bash    — re-verify the last 5 bash tool proofs against the notary

CLI

# List recent proofs
npx occ-verify

# Full detail
npx occ-verify --verbose

# Filter by date
npx occ-verify --date 2026-02-27

# Filter by tool
npx occ-verify --tool bash

# Filter by session
npx occ-verify --session <id>

# Re-verify all proofs against the notary
npx occ-verify --check

# Raw JSON output (for piping / scripting)
npx occ-verify --json

Control UI panel

The plugin registers an audit log panel in the OpenClaw Control UI. It shows:

• Every agent action with timestamp, tool name, and proof hash
• Mode indicator (⚪ stub / 🔏 signed)
• One-click verification against the notary
• Full proof JSON on expand
• Tee results (which notaries succeeded/failed)

Auto-refreshes every 30 seconds.

Self-host your own notary

Don't want to trust a hosted notary? Deploy your own in ~2 minutes:

cd notary-worker
npx wrangler kv:namespace create OCC_PROOFS
# Copy the id into wrangler.toml
npx wrangler deploy

After deploy, save your public key:

curl https://your-worker.workers.dev/key
# → { "publicKeyB64": "...", "version": "occ/1" }

This lets you verify proofs offline, forever, even if the Worker is taken down.

Then point the plugin at your notary:

{
  "mode": "remote",
  "notaries": ["https://your-worker.workers.dev/commit"]
}

Proof format

Each proof is stored as a JSONL entry in ~/.openclaw/workspace/occ-proofs/YYYY-MM-DD.jsonl:

{
  "payload": {
    "tool": "bash",
    "input": { "cmd": "ls -la" },
    "output": "total 48\n…",
    "session": "abc123",
    "model": "claude-opus-4-6",
    "elapsed": 312,
    "ts": 1709078400000
  },
  "proof": {
    "version": "occ/1",
    "artifact": { "hashAlg": "sha256", "digestB64": "…" },
    "commit": { "nonceB64": "…", "counter": "42", "time": 1709078400000 },
    "signer": {
      "publicKeyB64": "…",
      "signatureB64": "…",
      "enforcement": "software"
    }
  }
}

• digestB64 — SHA-256 of the serialized action payload. Re-hash it yourself to verify.
• counter — monotonic integer from the notary. Gaps mean missing proofs.
• enforcement: "software" — signed by a software key (standard). "measured-tee" = AWS Nitro Enclave.
• tee — present when mode is tee. Array of results from each notary.

Proof storage

Proofs live entirely on your machine:

~/.openclaw/workspace/occ-proofs/
  2026-02-27.jsonl
  2026-02-26.jsonl
  …

One JSONL file per day. Append-only. Crash-safe. Easy to archive, grep, or pipe into other tools.

How it works

OpenClaw agent
    │
    ▼ tool:after event
openclaw-occ plugin
    │
    ├─ stub mode:  SHA-256 locally → store proof
    │
    ├─ remote mode: POST bytes → notary → signed proof → store
    │
    └─ tee mode:   POST bytes → all notaries in parallel
                   → store all results + primary proof
                   → fail open (never blocks the agent)

The plugin never blocks the agent. If the notary is unreachable, a fallback stub proof is stored so the gap is visible in the audit log. Your agent keeps running.

ClawHub skill

A companion ClawHub skill is available in clawhub/SKILL.md. Install it so your agent knows how to help users set up and troubleshoot OCC:

clawhub publish ./clawhub \
  --slug openclaw-occ \
  --name "openclaw-occ" \
  --version 1.0.0 \
  --tags latest

The skill gives your agent step-by-step install instructions, configuration guidance, and explains how to interpret audit results — without the agent needing to look anything up.

License

Apache-2.0 · occ-core