@peac/adapter-openclaw

Offline-verifiable activity records for OpenClaw sessions.

Quick Start

import { activate, generateSigningKey } from '@peac/adapter-openclaw';

// Generate a signing key (one-time setup)
const key = await generateSigningKey({ outputDir: '.peac' });

// Activate the plugin
const plugin = await activate({
  config: {
    signing: {
      key_ref: `file:${key.keyPath}`,
      issuer: 'https://my-org.example.com',
    },
  },
});

plugin.instance.start();
// Records are now captured automatically via hooks.

Never log or print the contents of key_ref. Use env: key references in CI, file: for local development. Signing key files are written with 0600 permissions (owner read/write only).

What It Records

Every tool call your agent makes is captured as a tamper-evident record:

• Tool name, timing, status: what ran, when, whether it succeeded
• Input/output digests: SHA-256 hashes by default (payloads are never stored in plaintext unless you explicitly allowlist a tool)
• Chain linkage: each record links to the previous one, so gaps or reordering are detectable

Records are signed with your key and written to disk as individual .peac.json files.

Commands

Key Generation

npx peac-keygen --output-dir .peac

Generates a signing keypair. The private key is written with 0600 permissions. Print the kid and public key for registration with your infrastructure.

Plugin Tools

The plugin exposes 4 tools to the agent:

Configuration

activate() Options

const plugin = await activate({
  config: {
    signing: {
      key_ref: 'env:PEAC_SIGNING_KEY', // or 'file:/path/to/key.jwk'
      issuer: 'https://my-org.example.com',
      audience: 'https://api.example.com', // optional
    },
    output_dir: '.peac/receipts', // optional (default: {dataDir}/receipts/)
    background: {
      drain_interval_ms: 1000, // optional (default: 1000)
      batch_size: 100, // optional (default: 100)
    },
  },
  dataDir: '.peac', // optional (default: ~/.openclaw/peac/)
  spoolOptions: {
    maxEntries: 100_000, // optional (default: 100,000)
    maxFileBytes: 104_857_600, // optional (default: 100MB)
    autoCommitIntervalMs: 5000, // optional (default: 5000, 0 to disable)
  },
});

Key Reference Schemes

Compatibility

Architecture

Two-Stage Pipeline

Tool Call        Spool             Receipts
(sync hook) --> (append-only)  --> (signed receipt)
< 10ms          spool.jsonl        *.peac.json

1. Capture stage (sync, < 10ms target): Map OpenClaw event to a captured action, hash payloads inline, write to tamper-evident spool
2. Emit stage (async background): Drain spool periodically, convert to interaction evidence, sign with configured key, write receipt to output directory

OpenClaw-to-Receipt Mapping

API Reference

High-Level (Recommended)

import { activate, generateSigningKey } from '@peac/adapter-openclaw';

// activate() wires all components from config
const plugin = await activate(options);
plugin.instance.start();

// Capture events via the hook handler
await plugin.hookHandler.afterToolCall(event);

// Flush pending records into signed receipts
await plugin.flush();

// Clean shutdown (flushes + closes stores)
await plugin.shutdown();

Lower-Level (Advanced)

For custom wiring or when you need direct access to individual components:

import {
  createHookHandler,
  createReceiptEmitter,
  createBackgroundService,
  mapToolCallEvent,
  createSessionHistoryTailer,
} from '@peac/adapter-openclaw';

See the source for createHookHandler(), createReceiptEmitter(), createBackgroundService(), and createSessionHistoryTailer().

Security

• Privacy by default: All inputs and outputs are hashed (SHA-256). Plaintext is only captured for explicitly allowlisted tools.
• Key protection: Signing key files are written with 0600 permissions. Use env: references in CI to avoid keys on disk.
• Tamper evidence: Each spool entry links to the previous via digest. Gaps or reordering are detectable.
• No secret logging: The adapter never logs private key material. Only the key ID (kid) and public key component appear in logs.

Error Codes

Warning Codes

License

Apache-2.0