OpenClaw Governance Quickstart

OpenClaw Governance Quickstart

Clasper intercepts OpenClaw tool calls and enforces policy before execution. No OpenClaw tool with side effects can execute unless Clasper explicitly allows it.

This guide connects OpenClaw (an execution gateway + tool ecosystem) to Clasper Core (governance + Ops).

The result:

• OpenClaw tool calls are intercepted and sent to Clasper Core for a decision
• Side-effectful tools can be blocked or require approval
• Unknown/new tools default to require_approval via fallback policy
• Every decision is audited with matched policies + explainability

10-minute verification checklist

1. Core running → npx clasper-core seed openclaw → plugin installed in OpenClaw
2. Start gateway with --plugins clasper-openclaw
3. Trigger a governed tool (e.g. exec or delete)
4. See pending approval in Ops Console → approve/deny → execution resumes or is blocked
5. Try rm or delete → blocked (deny). Try read → allowed. Evidence in Audit log.

Prerequisites

• Node.js 22+ (required by OpenClaw)
• Clasper Core running locally
• OpenClaw installed + onboarded

Step 1: Install + onboard OpenClaw

Follow the official OpenClaw “Getting Started” and make sure the gateway comes up:

• OpenClaw docs: https://docs.openclaw.ai/start/getting-started
• Install overview: https://docs.openclaw.ai/install

During onboarding you’ll see a few prompts that often confuse first-time users:

• Skills: optional plugins (you can install more later)
• Hooks: optional automation scripts (recommended: session-memory, command-logger)
• Hatching: first-run of your bot (recommended: “Hatch in TUI” to quickly verify your channel works)

Step 2: Configure Clasper Core for OpenClaw

In clasper-core/.env set the adapter secret and approval behavior:

# Shared secret used to mint/verify X-Adapter-Token JWTs.
# The OpenClaw plugin signs requests with this secret and Clasper verifies them.
ADAPTER_JWT_SECRET=my-dev-secret

# Approvals in OSS:
# - simulate: auto-approve require_approval, but label it loudly in audit/decisions (dev-friendly)
# - enforce: pause execution until an operator approves/denies in Ops (local/self-attested)
CLASPER_APPROVAL_MODE=enforce

CLASPER_PORT=8081

Start Core:

cd /path/to/clasper-core
npx clasper-core dev

Step 3: Seed the OpenClaw policy pack

Seed the default policy pack:

cd /path/to/clasper-core
npx clasper-core seed openclaw

Important: fallback policy for unknown tools

OpenClaw is extensible: new tools can appear as you install new skills/plugins.

No-match behavior is controlled by CLASPER_MODE (default permissive allows no-match). To avoid “silent allow” of new tool surfaces, the OpenClaw pack includes a fallback rule:

• openclaw-fallback-require-approval

This rule matches any tool at very low precedence and yields require_approval so unknown tools don’t run without governance coverage.

Step 4: Install the Clasper plugin into OpenClaw

From the clasper-core repo root:

openclaw plugins install ./integrations/openclaw

Step 5: Configure the OpenClaw plugin

Edit your OpenClaw config (usually ~/.openclaw/openclaw.json) and add:

{
  "plugins": {
    "entries": {
      "clasper-openclaw": {
        "enabled": true,
        "config": {
          "clasperUrl": "http://localhost:8081",
          "adapterId": "openclaw-local",
          "adapterSecret": "my-dev-secret",
          "approvalWaitTimeoutMs": 300000,
          "approvalPollIntervalMs": 2000,
          "executionReuseWindowMs": 600000
        }
      }
    }
  }
}

Critical: adapterSecret must match Clasper’s ADAPTER_JWT_SECRET.

Approval wait + retry reuse settings

• approvalWaitTimeoutMs (default 300000): max time the plugin waits for a human approval before fail-closed timeout.
• approvalPollIntervalMs (default 2000): polling interval while waiting for approval status.
• executionReuseWindowMs (default 600000): when retrying the same request, reuse the same pending execution_id instead of creating another pending approval.

Reuse is strict and request-scoped (same tool + normalized targets + session context), so this reduces approval spam without broadening authority.

For now, broader Core-side “approve once for similar requests” grants are not enabled by default; this guide uses request-scoped reuse only.

What operators should expect

When CLASPER_APPROVAL_MODE=enforce:

1. First governed call creates a pending decision in Ops.
2. The plugin waits up to approvalWaitTimeoutMs and polls every approvalPollIntervalMs.
3. If the user retries the same request while it is still pending, OpenClaw reuses the same pending execution_id.
4. Approve/deny resolves the decision and clears the reuse entry.
5. Different request fingerprint (tool/target/session context) opens a new pending decision.

Step 6: Start OpenClaw with the plugin enabled

openclaw gateway start --plugins clasper-openclaw

On startup you should see logs indicating:

• the plugin initialized
• the adapter registered with Clasper Core
• tool dispatch is governed (fail-closed when Core is unreachable)

Step 7: Verify approvals + fallback behavior

• Trigger a governed tool (e.g. exec, write_file, http_request)
• In CLASPER_APPROVAL_MODE=enforce, you should see a pending decision in the Ops Console
• Approve/deny locally (self-attested) and confirm the adapter resumes after approval
• If you retry the exact same request while still pending, OpenClaw should reuse the same pending decision/execution instead of creating a new one

If a tool hits the fallback policy, Core emits an explicit audit event (policy_fallback_hit) so you can tighten policy coverage.

Reference

• OpenClaw integration repo guide: clasper-core/integrations/openclaw/README.md
• Governance concepts: /docs/governance/
• Adapter contract: /docs/adapter-contract/