Skip to content
Clasper Core

Configuration

Configuration

Section titled “Configuration”

Clasper Core is configured entirely via environment variables.

OSS vs Cloud: OSS runs locally with self-attested approvals. Cloud adds decision tokens and external proof. See OSS vs Cloud.

The canonical, always-up-to-date list is in:

  • clasper-core/.env.example

This page summarizes the most important configuration options.

Core server

Section titled “Core server”
  • CLASPER_PORT: HTTP port (default 8081)
  • CLASPER_DB_PATH: SQLite DB path (default ./clasper.db)

Control plane integration (backend)

Section titled “Control plane integration (backend)”
  • BACKEND_URL: backend base URL
  • AGENT_JWT_SECRET: shared secret used to mint/verify X-Agent-Token

Adapter authentication

Section titled “Adapter authentication”
  • ADAPTER_JWT_SECRET: verify X-Adapter-Token (required for adapter endpoints)
  • ADAPTER_JWT_ALGORITHM: JWT alg (default HS256)

Trust, integrity, and enforcement

Section titled “Trust, integrity, and enforcement”

  • Telemetry signature verification

    • CLASPER_TELEMETRY_SIGNATURE_MODE: off | warn | enforce
    • CLASPER_TELEMETRY_MAX_SKEW_SECONDS: allowed clock skew

  • Tool authorization enforcement

    • CLASPER_TOOL_AUTH_MODE: off | warn | enforce
    • CLASPER_TOOL_TOKEN_SECRET: required to issue tool auth tokens
    • CLASPER_TOOL_TOKEN_ALGORITHM: JWT alg (default HS256)

Policy engine

Section titled “Policy engine”
  • CLASPER_POLICY_PATH: legacy YAML policy path (still supported for older flows)
  • CLASPER_MODE: governance mode for no-match behavior:
    • permissive (default): no-match allows
    • guarded: no-match requires fallback policy; if fallback is missing, no-match is blocked
    • strict: no-match denies
  • CLASPER_DECISION_MAX_ROWS: retention cap for the decisions table (default 100000; set <= 0 to disable cap)

Clasper Core policies are stored as data and managed via Ops APIs:

  • GET/POST/PATCH/DELETE /ops/api/policies

Async approvals (decision tokens)

Section titled “Async approvals (decision tokens)”
  • CLASPER_DECISION_TOKEN_SECRET: required to mint/verify decision tokens
  • CLASPER_DECISION_TOKEN_ALGORITHM: JWT alg (default HS256)
  • CLASPER_DECISION_TOKEN_TTL_SECONDS: token TTL in seconds (default 600)

Approvals (OSS)

Section titled “Approvals (OSS)”

Clasper Core supports local, self-attested approvals via the Ops Console. In OSS there is no Cloud-issued authority token; approvals are recorded and enforced by Core locally.

  • CLASPER_APPROVAL_MODE:
    • simulate (default): any require_approval is AUTO-APPROVED and the decision/audit makes that explicit (dev-friendly)
    • enforce: require_approval creates a pending decision and execution pauses until an operator approves/denies in Ops

OpenClaw adapter timing knobs are configured in plugin config (not Core env vars):

  • approvalWaitTimeoutMs (default 300000)
  • approvalPollIntervalMs (default 2000)
  • executionReuseWindowMs (default 600000)

Back-compat (older name, still supported):

  • CLASPER_REQUIRE_APPROVAL_IN_CORE=allow → CLASPER_APPROVAL_MODE=simulate
  • CLASPER_REQUIRE_APPROVAL_IN_CORE=block → CLASPER_APPROVAL_MODE=enforce

Verifiable exports (offline verification)

Section titled “Verifiable exports (offline verification)”
  • CLASPER_EXPORT_SIGNING_MODE: off | warn | enforce (default off)
  • CLASPER_EXPORT_SIGNING_KEY_PATH: path to Ed25519 private key (PEM)
  • CLASPER_EXPORT_SIGNING_KEY_ID: optional key identifier for rotation

Export endpoints / CLI:

  • POST /ops/api/exports
  • npx clasper-core export ... (download bundle)

Ops Console auth (OIDC)

Section titled “Ops Console auth (OIDC)”
  • OPS_OIDC_ISSUER
  • OPS_OIDC_AUDIENCE
  • OPS_OIDC_JWKS_URL (optional if issuer is set)
  • OPS_RBAC_CLAIM
  • OPS_TENANT_CLAIM
  • OPS_WORKSPACE_CLAIM
  • OPS_ALLOWED_TENANTS_CLAIM