Skip to content
Clasper Core

Integration

Integration

Section titled “Integration”

Clasper Core is a governance authority for AI execution. It integrates through two explicit contracts:

  • Control Plane Contract (backend): Clasper Core ↔ your backend for tasks/messages/documents (and optional notifications).
  • Adapter Contract (executors): Clasper Core ↔ execution adapters for governed execution decisions + telemetry ingest.

Keeping these separate prevents “god mode” runtimes and makes execution provider-agnostic.

Typical deployment

Section titled “Typical deployment”
┌─────────────────────┐      ┌─────────────────────┐
│     Your backend    │◀────▶│     Clasper Core     │
│ (Control Plane v1)  │      │ (Governance + Ops)   │
└─────────────────────┘      └─────────┬───────────┘
                                       │ governed execution
                                       ▼
                              ┌─────────────────────┐
                              │  Execution Adapters │
                              │ (optional clients)  │
                              └─────────────────────┘

Profile A: Governance + built-in runtime (developer convenience)

Section titled “Profile A: Governance + built-in runtime (developer convenience)”

Your backend calls Clasper Core’s built-in runtime adapter via:

  • POST /api/agents/send
  • POST /api/agents/stream (streaming)

Clasper Core runs the governance checks and executes LLM work statelessly while keeping OS/browser/data actions in your backend.

For a full guide to the runtime adapter (request format, configuration, and flow), see Built-in Runtime Adapter.

Profile B: Governance-only (external adapters)

Section titled “Profile B: Governance-only (external adapters)”

External adapters integrate directly with Core:

  1. Decision: POST /api/execution/request (requires X-Adapter-Token)
  2. If pending: adapter polls either:
    • GET /api/execution/:executionId (simple “effect” check), or
    • GET /api/decisions/:decisionId (full decision record)
  3. Resume: once approved, adapters re-call POST /api/execution/request with the same execution_id (Core has a retry/resume path that returns allowed: true after local approval)
  4. Telemetry ingest: POST /api/ingest/* (requires X-Adapter-Token)

For OpenClaw specifically, the adapter now supports request-scoped pending reuse:

  • retries of the same request can reuse the same pending execution_id instead of creating a new approval row
  • wait/poll behavior is adapter-configured (approvalWaitTimeoutMs, approvalPollIntervalMs, executionReuseWindowMs)
  • this is adapter-local and strict (not a broad Core approval grant)

Note: Decision tokens (/api/decisions/:id/consume) are Cloud-only. In OSS, approvals are local and self-attested via the Ops Console.

For high-risk capabilities, adapters should also include optional execution context signals in the decision request:

  • intent (why)
  • context (network/files/privileges/package manager)
  • provenance (marketplace/internal/git)

See:

Configuration reference

Section titled “Configuration reference”

Clasper Core’s configuration is documented in the canonical env template:

  • Clasper Core: clasper-core/.env.example (authoritative) For a human-readable reference, see: Configuration.

Conformance testing (control plane)

Section titled “Conformance testing (control plane)”

Validate your backend’s Control Plane implementation:

Terminal window
export CONTROL_PLANE_URL=http://localhost:9001
export AGENT_TOKEN=<your-agent-jwt>
npm run conformance
Section titled “Related”