ClawGuard Documentation

ClawGuard is a Layer 2.5 security middleware that wraps any OpenClaw agent's tool_dispatch function to enforce declarative capabilities, stop unauthorized actions, and anchor identities to ENS and 0G Storage.

Core Concept: Every agent has a SKILL.md manifest. ClawGuard hashes it, anchors it on-chain, and uses it at runtime to gate tool access. Violations are pushed to an append-only 0G File Storage audit trail.

Getting Started

Follow these steps to integrate ClawGuard into a new or existing OpenClaw project from scratch.

Step 1: Installation

Install the core middleware and CLI directly into your project:

$ npm install @shanejoans/clawguard

Step 2: Environment Configuration

Create a .env file in your project root. You must provide a funded wallet for the 0G Galileo and Sepolia ENS testnets:

# 0G Testnet Config
ZG_PRIVATE_KEY=your_hex_private_key_here
ZG_CHAIN_RPC=https://rpc-testnet.0g.ai
ZG_INDEXER_RPC=https://indexer-storage-testnet-turbo.0g.ai

# Ethereum Sepolia Config
ETH_SEPOLIA_RPC=https://sepolia.infura.io/v3/your_project_id
REGISTRY_ADDRESS=0x2205AC38725F42d9da0ffaDD94166B5E5b83010A

Step 3: Define Capabilities (SKILL.md)

Create a SKILL.md file in your agent's directory to declare what it's allowed to do:

# Example Agent
## Allowed Tools
- web.fetch
- data.parse_json

Step 4: Publish Manifest

Use the CLI to publish your SKILL.md. This computes the cryptographic hash, stores the JSON to 0G, and registers it to ENS.

$ npx clawguard publish ./path/to/directory --description "My Agent"

The CLI will output an ENS name like my-agent.skills.clawhub.eth. Use this in the next step.

SDK Reference

wrapWithClawGuard()

The primary entry point. Wraps your agent's execution layer.

import { wrapWithClawGuard, addViolationHandler } from '@shanejoans/clawguard';

const safeDispatch = wrapWithClawGuard(agent.tool_dispatch, {
  agentId: 'defi-monitor-agent',
  ensName: 'defi-reader.skills.clawhub.eth',
  auditLog: true,
  failOpen: false, // Rule S-01: block all calls if manifest fetch fails
});

// Optional: intercept violations
addViolationHandler(safeDispatch, (event) => {
  console.error('[SECURITY]', event.blockedTool, 'blocked');
});

ensName

Auto-resolves ENS to 0G storage hash to fetch the manifest.

auditLog

If true, automatically uploads immutable violation logs to 0G File Storage.

CLI Toolchain

The CLI manages the lifecycle of your agent manifests.

clawguard publish <path>

Parses SKILL.md, hashes it, uploads to 0G, and registers on ENS.

$ npx clawguard publish packages/example-agent/skills/defi-reader --description "DeFi Monitor"

clawguard inspect <ens-name>

Reads and verifies the manifest live from the network.

$ npx clawguard inspect defi-reader.skills.clawhub.eth --check-tool wallet.transfer
⛔ DENIED: "wallet.transfer" is explicitly blocked for "defi-reader"

clawguard verify <path>

Runs 0G Compute sealed inference to verify code behavior matches manifest.

$ npx clawguard verify packages/example-agent/skills/defi-reader

SKILL.md Format

Capabilities are defined declaratively in Markdown.

# DeFi Reader

Read-only DeFi market data agent.

## Allowed Tools
- wallet.read_balance
- web.fetch
- data.parse_json

## Blocked Tools
- wallet.transfer
- shell.exec

## Constraints
- max_external_calls: 10

Architecture

1. ENS Resolution
ClawGuard looks up skill.clawhub.eth on Sepolia to retrieve the 0G storageKey (Merkle Root) and manifestHash.
2. Zero-Trust Fetch
The JSON manifest is fetched from the 0G File Storage Indexer REST API.
3. Cryptographic Verification
The downloaded manifest is hashed via SHA-256. If it doesn't match the ENS anchor, execution fails closed (Rule S-03).
4. Interception & Audit
Any attempt to call a tool in the blocked list results in a thrown exception and an immutable audit event uploaded back to 0G Storage.