Overview

SafeClaw is a neurosymbolic governance layer for autonomous AI agents. It validates every tool call, message, and action against OWL ontologies and SHACL constraints before execution.

The system has two components:

• openclaw-safeclaw-plugin — a TypeScript plugin that intercepts OpenClaw events and forwards them to the SafeClaw service via HTTP.
• safeclaw-service — a Python FastAPI service that runs the constraint pipeline against a knowledge graph of ontologies, policies, and user preferences.

The plugin is a thin client (~275 lines) with no governance logic of its own. All validation happens server-side, making it easy to update policies without redeploying the agent.

How SafeClaw Controls OpenClaw

The plugin registers 6 event hooks with the OpenClaw runtime. Each hook intercepts a specific lifecycle event:

Enforcement Modes

Fail Modes

The Ontology

OWL (Web Ontology Language) defines a formal class hierarchy of actions your agent can take. SHACL (Shapes Constraint Language) defines structural constraints that validate the shape of each action's data.

Together, they give SafeClaw a machine-readable understanding of what each action means, how risky it is, and what constraints apply — not just pattern matching, but genuine semantic reasoning.

At startup, SafeClaw pre-computes the full rdfs:subClassOf hierarchy via pure-Python SPARQL traversal (no Java required). This enables hierarchy-aware policy checking — blocking ShellAction automatically blocks all subclasses like GitPush and ForcePush. Custom ontology extensions inherit risk levels and constraints without Python code changes.

Action Class Hierarchy

Action
├── FileAction
│   ├── ReadFile          (Low, reversible, LocalOnly)
│   ├── WriteFile         (Medium, reversible, LocalOnly)
│   ├── EditFile          (Medium, reversible, LocalOnly)
│   ├── DeleteFile        (Critical, irreversible, LocalOnly)
│   ├── ListFiles
│   └── SearchFiles
├── ShellAction
│   ├── ExecuteCommand    (High, reversible, LocalOnly)
│   ├── GitCommit         (Medium, reversible, LocalOnly)
│   ├── GitPush           (High, irreversible, SharedState)
│   ├── ForcePush         (Critical, irreversible, SharedState)
│   ├── GitResetHard      (Critical, irreversible, LocalOnly)
│   ├── RunTests          (Low, reversible, LocalOnly)
│   ├── DockerCleanup     (High, irreversible, LocalOnly)
│   └── PackagePublish    (Critical, irreversible, ExternalWorld)
├── NetworkAction
│   ├── WebFetch          (Medium, reversible, ExternalWorld)
│   ├── WebSearch         (Low, reversible, ExternalWorld)
│   └── NetworkRequest
├── MessageAction
│   └── SendMessage       (High, irreversible, ExternalWorld)
└── BrowserAction         (Medium, reversible, ExternalWorld)

Risk Levels

Scopes

The 9-Step Constraint Pipeline

Every tool call passes through these gates in order. Execution blocks at the first violation.

Built-in Policies

Default prohibitions and obligations defined in the ontology:

Prohibitions

Obligations

Roles & Permissions

SafeClaw ships with three roles. Custom roles can be defined in Turtle files.

User Preferences

Per-user preferences are stored as RDF triples and loaded from ~/.safeclaw/ or the ontology's users/ directory.

Safety Preferences

Coding Preferences

Communication Preferences

How Mistral AI Enhances SafeClaw

SafeClaw includes an optional LLM layer powered by Mistral AI. It is activated by setting SAFECLAW_MISTRAL_API_KEY. This layer is purely passive and advisory — it never blocks the constraint pipeline.

The Security Reviewer specifically watches for:

• Base64/hex-encoded payloads hiding malicious commands
• Multi-step evasion chains (e.g., write script then execute)
• URL-based payload delivery (curl | sh patterns)
• Flag reordering and command aliases
• Environment variable manipulation

Context Injection

Before each agent session starts, SafeClaw injects governance context into the agent's system prompt via the before_agent_start hook. This gives the LLM awareness of its constraints before it even proposes an action.

Injected Context Includes

• Active user preferences — autonomy level, confirmation requirements, forbidden paths
• Active domain policies — summarized constraints with reasoning
• Recent violations — last 5 blocked actions and reasons, so the agent avoids retrying the same approach
• Session history — last 10 actions with outcomes, files modified, and violation summary
• Agent role info — role name, autonomy level, denied action classes

This context injection improves agent self-regulation: the LLM learns what's prohibited and adjusts its behavior, reducing the number of blocked actions over the course of a session.

Audit Trail

Every decision — allow or block — is recorded as a DecisionRecord in append-only JSONL files at ~/.safeclaw/audit/.

DecisionRecord Structure

{
  "id": "uuid",
  "timestamp": "ISO-8601",
  "session_id": "...",
  "user_id": "...",
  "agent_id": "...",
  "action": {
    "tool_name": "write_file",
    "params": { ... },
    "ontology_class": "WriteFile",
    "risk_level": "MediumRisk",
    "is_reversible": true,
    "affects_scope": "LocalOnly"
  },
  "decision": "allowed",
  "justification": {
    "constraints_checked": [
      { "constraint_uri": "...",
        "constraint_type": "...",
        "result": "satisfied",
        "reason": "..." }
    ],
    "preferences_applied": [ ... ],
    "elapsed_ms": 12.3
  }
}

The dashboard at /admin provides a web interface for browsing audit logs, viewing decision history, and managing the system.

Message Governance

Outbound messages are governed by the message_sending hook with three checks:

1. Never-Contact List

Recipients on the never-contact list (configured via neverContactList preference) are unconditionally blocked.

2. Sensitive Data Detection

Message content is scanned against 7 regex patterns:

3. Rate Limiting

Default: 50 messages per session per hour.

Error Handling

The SafeClaw service returns structured error responses with machine-readable codes and human-readable hints for every failure:

{
  "error": "ENGINE_NOT_READY",
  "detail": "Engine not initialized — the service is still starting up.",
  "hint": "Wait a moment and retry, or check service logs."
}

Error Codes

Plugin Error Handling

The TypeScript plugin (v0.1.3+) parses structured errors and provides context-specific warnings:

• Timeout — logs timeout duration and service URL
• Connection refused — suggests checking if the service is running
• HTTP errors — parses and displays the detail and hint fields from the response
• Fail-closed blocks — include the service URL in the block reason for easier debugging

CLI & TUI

SafeClaw provides CLI commands and an interactive terminal UI for managing the service, diagnosing issues, and controlling OpenClaw.

safeclaw tui

Opens the interactive settings TUI. The Status tab shows live health for both SafeClaw and the OpenClaw daemon:

  Service      ● Connected (localhost:8420)
  OpenClaw     ● Running
  Enforcement  enforce
  Fail Mode    closed
  Enabled      ON

  Service v0.1.0
  Last check: 14:32:05

  Press r to restart OpenClaw daemon

The status auto-refreshes every 10 seconds. Press r to restart the OpenClaw daemon directly from the TUI.

safeclaw connect

Links your local agent to the SafeClaw service by writing your API key to ~/.safeclaw/config.json:

$ safeclaw connect sc_abc123...
Connected! Your API key has been saved to ~/.safeclaw/config.json

The config file is created with 0600 permissions (owner read/write only). If a config file already exists, only the remote.apiKey and remote.serviceUrl fields are updated — other settings are preserved.

By default the service URL is set to https://api.safeclaw.eu/api/v1. To connect to a self-hosted instance:

$ safeclaw connect sc_abc123... --service-url http://localhost:8420/api/v1

safeclaw restart-openclaw

Restarts the OpenClaw daemon from the command line without opening the TUI:

$ safeclaw restart-openclaw
OpenClaw daemon restarted successfully.

safeclaw status check

Pings the running service and displays component-level health:

$ safeclaw status check
Service: ok
Version: 0.1.0
Engine ready: True
Uptime: 1234s

┌───────────────┬────────────────────────┐
│ Component     │ Detail                 │
├───────────────┼────────────────────────┤
│ Knowledge Graph│ 847 triples           │
│ LLM           │ not configured         │
│ Sessions      │ 3 active               │
│ Agents        │ 2 registered, 1 active │
└───────────────┴────────────────────────┘

If the service is not running, it shows a clear error with the suggested fix.

safeclaw status diagnose

Runs offline checks without requiring the service to be running:

• Config file at ~/.safeclaw/config.json
• Ontology .ttl files present
• Audit directory exists
• Mistral API key set (optional)

Each check prints OK or ISSUE with remediation hints.

safeclaw serve

Starts the SafeClaw service:

$ safeclaw serve
$ safeclaw serve --host 0.0.0.0 --port 8420 --reload

safeclaw init

Generates a default ~/.safeclaw/config.json with all sections:

$ safeclaw init --user-id myname
$ safeclaw init --user-id myname --mode remote --service-url http://localhost:8420/api/v1

safeclaw audit

View and query audit records:

$ safeclaw audit show --last 20
$ safeclaw audit show --blocked
$ safeclaw audit report <session-id> --format markdown
$ safeclaw audit stats --last 100
$ safeclaw audit compliance
$ safeclaw audit explain <audit-id>

safeclaw policy

Manage governance policies:

$ safeclaw policy list
$ safeclaw policy add NoSecrets --type prohibition --reason "Secrets must not be committed" --path-pattern ".*\.secret.*"
$ safeclaw policy remove NoSecrets
$ safeclaw policy add-nl "Never allow deploys on weekends"

safeclaw pref

View or set user preferences:

$ safeclaw pref show --user-id myuser
$ safeclaw pref set autonomyLevel cautious --user-id myuser
$ safeclaw pref set confirmBeforeDelete true

safeclaw llm

Manage LLM features (requires Mistral API key):

$ safeclaw llm suggestions
$ safeclaw llm findings

Real-Time Events (SSE)

SafeClaw provides a Server-Sent Events (SSE) endpoint for real-time visibility into governance decisions. The endpoint requires admin authentication.

$ curl -N -H 'X-Admin-Password: yourpass' http://localhost:8420/api/v1/events

event: safeclaw
data: {"event_type":"blocked","severity":"warning","title":"Blocked: shell","detail":"[SafeClaw] Force push can destroy shared history","metadata":{"tool_name":"shell","ontology_class":"ForcePush"}}

Event Types

Event Bus Limits

• Max 100 concurrent SSE subscribers
• Max 100 queued events per subscriber (oldest dropped on overflow)
• No external dependencies — uses asyncio.Queue internally

Admin Dashboard

The admin dashboard is available at /admin and provides a web interface for monitoring and managing SafeClaw.

Live Features

• Toast notifications — real-time pop-up alerts when actions are blocked or security findings are detected, powered by the SSE event stream
• Auto-refresh — home page stats update every 5 seconds via HTMX
• Agent monitoring — cards showing registered and active agent counts

Audit Log Detail

Clicking 'Details' on any audit record expands to show:

• Action parameters (truncated to 500 chars)
• Constraint checks with type, result, and reason
• Preferences applied
• Session action history (last 5 entries)
• Block reason for early-exit blocks (agent governance, role checks)

Dashboard Pages

User Dashboard

The user dashboard at /dashboard provides a self-service web interface for managing your SafeClaw integration. Sign in with GitHub OAuth to access it.

Authentication Flow

• Click Sign In in the nav bar to start GitHub OAuth
• Authorize the SafeClaw app on GitHub
• First-time users are redirected to the onboarding wizard to set preferences and get their API key
• Returning users go straight to /dashboard
• All /dashboard/* routes are protected by Beforeware

Dashboard Pages

API Keys

API keys authenticate your agent's plugin against the SafeClaw service. Each key has a sc_ prefix and is shown only once at creation time.

• Label — a human-readable name for the key
• Scope — full (all endpoints) or evaluate (evaluation endpoints only)
• Keys are stored as SHA-256 hashes; the raw key cannot be recovered
• Revoked keys are immediately invalidated

Governance Preferences

Self-Hosting

To run the landing site with user management locally:

cd safeclaw-landing
pip install -r requirements.txt
export GITHUB_CLIENT_ID=your_id
export GITHUB_CLIENT_SECRET=your_secret
python main.py  # starts on port 5002

The SQLite database is created automatically in ~/.safeclaw-landing/safeclaw.db.

Demonstration Flows

These walkthroughs show what happens inside SafeClaw when an agent attempts different actions. Each flow traces the request through the constraint pipeline from prompt to final decision.

Flow 1: Blocking a File Deletion

Prompt: "Delete /tmp/safeclaw-test.txt"

Tool Call sent by the agent:

{
  "tool": "delete",
  "params": { "path": "/tmp/safeclaw-test.txt" }
}

Classification: DeleteFile / CriticalRisk — the action classifier maps the delete tool to the sc:DeleteFile ontology class.

Decision: The developer role does not include DeleteFile in its allowed action classes. Pipeline step 3 (Role-Based Access) blocks the call.

Response:

{
  "decision": "block",
  "reason": "Role developer does not permit DeleteFile actions",
  "constraintId": "role-access-check",
  "riskLevel": "critical",
  "pipelineStep": 3
}

Flow 2: Blocking a Force Push

Prompt: "Push my changes with --force"

Tool Call sent by the agent:

{
  "tool": "exec",
  "params": { "command": "git push --force" }
}

Classification: ForcePush / CriticalRisk — the shell-command pattern matcher recognises git push --force and maps it to sc:ForcePush.

Decision: The developer role explicitly denies ForcePush. Pipeline step 3 (Role-Based Access) blocks the call.

Response:

{
  "decision": "block",
  "reason": "Role developer does not permit ForcePush actions",
  "constraintId": "role-access-check",
  "riskLevel": "critical",
  "pipelineStep": 3
}

Flow 3: Allowing a Safe Read

Prompt: "Read the config file"

Tool Call sent by the agent:

{
  "tool": "read",
  "params": { "path": "./config.json" }
}

Classification: ReadFile / LowRisk — a simple read operation classified as sc:ReadFile.

Decision: All 9 pipeline steps pass. The developer role permits ReadFile, SHACL shapes validate, no policies or preferences restrict reading, and rate limits are within bounds.

Response:

{
  "decision": "allow",
  "reason": "All constraints satisfied",
  "riskLevel": "low",
  "pipelineStep": 9
}

API Reference

All endpoints are under /api/v1. Admin endpoints require the X-Admin-Password header or API key authentication.

Evaluation & Context

Recording & Logging

Audit & Reporting (admin)

Ontology (admin)

Preferences (admin)

Agent Management (admin)

Health & Connection

LLM Features

Real-Time

Configuration Reference

Plugin Environment Variables

Service Environment Variables

Config File (~/.safeclaw/config.json)

The safeclaw connect command writes a JSON config file that the plugin reads at startup. The safeclaw init command generates a full config with all sections:

{
  "enabled": true,
  "userId": "",
  "mode": "embedded | remote | hybrid",
  "remote": {
    "serviceUrl": "https://api.safeclaw.eu/api/v1",
    "apiKey": "sc_abc123...",
    "timeoutMs": 500
  },
  "hybrid": {
    "circuitBreaker": {
      "failureThreshold": 3,
      "resetTimeoutSec": 30,
      "fallbackMode": "local-only"
    }
  },
  "enforcement": {
    "mode": "enforce",
    "blockMessage": "[SafeClaw] Action blocked: {reason}",
    "maxReasonerTimeMs": 200
  },
  "contextInjection": {
    "enabled": true,
    "includePreferences": true,
    "includePolicies": true,
    "includeSessionFacts": true,
    "includeRecentViolations": true,
    "maxContextChars": 2000
  },
  "audit": {
    "enabled": true,
    "logLlmIO": true,
    "logAllowedActions": true,
    "logBlockedActions": true,
    "retentionDays": 90,
    "format": "jsonl"
  },
  "roles": {
    "defaultRole": "developer"
  }
}

The remote section takes precedence over environment variables for SAFECLAW_API_KEY and SAFECLAW_URL. The file is created with 0600 permissions.

SaaS Onboarding

SafeClaw is available as a hosted service at safeclaw.eu. No server setup required.

1. Create an account

Click Get Started on the landing page. Sign in with your GitHub account.

2. Onboarding wizard

First-time users are guided through a three-step wizard:

• Step 1 — Autonomy level — choose how much control SafeClaw has (cautious, moderate, or autonomous)
• Step 2 — Mistral API key (optional) — provide your own Mistral API key to enable LLM-powered features such as semantic action classification. You can skip this step and add it later from the dashboard.
• Step 3 — API key & connection — a SafeClaw API key is generated automatically. The wizard shows the safeclaw connect command to run in your terminal.

3. Connect your agent

Install the plugin and connect using the command shown in the wizard:

$ npm install -g openclaw-safeclaw-plugin
$ safeclaw connect sc_your_key_here

safeclaw connect writes the key to ~/.safeclaw/config.json and verifies the connection to https://api.safeclaw.eu/api/v1. No manual environment variables needed.

4. Manage from the dashboard

After onboarding, the dashboard at safeclaw.eu/dashboard lets you:

• Create and revoke API keys
• Set preferences (confirm before delete, max files per commit)
• View connected agents
• Add or update your Mistral API key