openclaw-safeclaw-plugin 1.1.0 → 1.3.0

package/README.md

@@ -1,74 +1,247 @@
 # openclaw-safeclaw-plugin
 
-Neurosymbolic governance plugin for OpenClaw AI agents. Validates every tool call, message, and action against safety constraints before execution.
+Neurosymbolic governance plugin for OpenClaw AI agents. Validates every tool call, message, and action against OWL ontologies and SHACL constraints before execution.
 
-## Install
+## Installation
+
+### Via ClawHub (recommended)
+
+```bash
+openclaw plugins install safeclaw
+```
+
+### Manual install
 
 ```bash
 npm install -g openclaw-safeclaw-plugin
+safeclaw-plugin setup
+safeclaw-plugin restart-openclaw
 ```
 
+The `setup` command copies the plugin manifest to `~/.openclaw/extensions/safeclaw/` and enables it in `~/.openclaw/openclaw.json`. After install, restart OpenClaw to activate the plugin.
+
 ## Quick Start
 
-1. Sign up at [safeclaw.eu](https://safeclaw.eu) and create an API key
-2. Install and connect:
+1. Install the plugin (see above)
+2. Connect to SafeClaw (cloud or self-hosted):
 
 ```bash
-npm install -g openclaw-safeclaw-plugin
+# Cloud
 safeclaw-plugin connect <your-api-key>
+
+# Self-hosted
+safeclaw-plugin config set serviceUrl http://localhost:8420/api/v1
+```
+
+3. Restart OpenClaw:
+
+```bash
 safeclaw-plugin restart-openclaw
 ```
 
-That's it. Every tool call your AI agent makes is now governed by SafeClaw.
+Every tool call your AI agent makes is now governed by SafeClaw.
 
-## Commands
+## Configuration
 
+Configuration is resolved in this order (later sources override earlier ones):
+
+1. **Defaults** -- hardcoded in the plugin
+2. **Config file** -- `~/.safeclaw/config.json`
+3. **Environment variables** -- `SAFECLAW_*` prefixed vars
+4. **OpenClaw plugin config** -- values from `api.pluginConfig` (set via OpenClaw settings UI or `openclaw.json`)
+
+### Config file
+
+Created automatically by `safeclaw-plugin connect`. Structure:
+
+```json
+{
+  "enabled": true,
+  "remote": {
+    "serviceUrl": "http://localhost:8420/api/v1",
+    "apiKey": "sc_live_..."
+  },
+  "enforcement": {
+    "mode": "enforce",
+    "failMode": "open"
+  }
+}
 ```
-safeclaw-plugin connect <api-key>  Connect to SafeClaw and register with OpenClaw
-safeclaw-plugin setup              Register plugin with OpenClaw (no key needed)
-safeclaw-plugin config show        Show current plugin configuration
-safeclaw-plugin config set <k> <v> Set a plugin configuration value
-safeclaw-plugin tui                Open the interactive settings TUI
-safeclaw-plugin restart-openclaw   Restart the OpenClaw daemon
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SAFECLAW_URL` | `http://localhost:8420/api/v1` | SafeClaw service URL |
+| `SAFECLAW_API_KEY` | *(empty)* | API key for authentication |
+| `SAFECLAW_TIMEOUT_MS` | `5000` | HTTP request timeout in milliseconds |
+| `SAFECLAW_ENABLED` | `true` | Set `false` to disable the plugin entirely |
+| `SAFECLAW_ENFORCEMENT` | `enforce` | Enforcement mode (see below) |
+| `SAFECLAW_FAIL_MODE` | `open` | Fail mode (see below) |
+| `SAFECLAW_AGENT_ID` | *(empty)* | Agent identifier for multi-agent governance |
+| `SAFECLAW_AGENT_TOKEN` | *(empty)* | Agent authentication token |
+
+### OpenClaw plugin config
+
+When running inside OpenClaw, the plugin reads `api.pluginConfig` which maps to the `configSchema` in `openclaw.plugin.json`. These values take priority over the config file. Set them via the OpenClaw settings UI or directly in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "safeclaw": {
+        "enabled": true,
+        "config": {
+          "enforcement": "enforce",
+          "failMode": "open",
+          "serviceUrl": "http://localhost:8420/api/v1"
+        }
+      }
+    }
+  }
+}
 ```
 
-## What It Does
+## Enforcement Modes
 
-- **Blocks dangerous actions** — force push, deleting root, exposing secrets
-- **Enforces dependencies** — tests must pass before git push
-- **Checks user preferences** — confirmation for irreversible actions
-- **Governs messages** — blocks sensitive data leaks
-- **Full audit trail** — every decision logged with ontological justification
+| Mode | Behavior |
+|------|----------|
+| `enforce` | Block tool calls and messages that violate constraints. Recommended for production. |
+| `warn-only` | Log warnings but allow all actions through. Useful during initial rollout. |
+| `audit-only` | Server-side logging only, no client-side warnings or blocks. |
+| `disabled` | Plugin is completely inactive. No HTTP calls to the service. |
 
-## How It Works
+## Fail Modes
 
-The plugin registers hooks on OpenClaw events:
+Controls what happens when the SafeClaw service is unreachable:
 
-1. **before_tool_call** — validates against SHACL shapes, policies, preferences, dependencies
-2. **before_agent_start** — injects governance context into the agent's system prompt
-3. **message_sending** — checks outbound messages for sensitive data
-4. **after_tool_call** — records action outcomes for dependency tracking
-5. **llm_input/output** — logs LLM interactions for audit
+| Mode | Behavior |
+|------|----------|
+| `open` | Allow all actions when the service is unavailable. Default. |
+| `closed` | Block all actions when the service is unavailable. Use when safety is critical. |
 
-## Configuration
+## Hooks
 
-Set via environment variables or `~/.safeclaw/config.json`:
+The plugin registers 11 hooks on OpenClaw events. Each hook communicates with the SafeClaw service via HTTP.
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SAFECLAW_URL` | `https://api.safeclaw.eu/api/v1` | SafeClaw service URL |
-| `SAFECLAW_API_KEY` | *(empty)* | API key (set automatically by `safeclaw-plugin connect`) |
-| `SAFECLAW_TIMEOUT_MS` | `5000` | Request timeout in ms |
-| `SAFECLAW_ENABLED` | `true` | Set `false` to disable |
-| `SAFECLAW_ENFORCEMENT` | `enforce` | `enforce`, `warn-only`, `audit-only`, or `disabled` |
-| `SAFECLAW_FAIL_MODE` | `open` | `open` (allow on failure) or `closed` (block on failure) |
+### Blocking hooks (can prevent actions)
 
-## Enforcement Modes
+| Hook | Priority | Description |
+|------|----------|-------------|
+| `before_tool_call` | 100 | The main gate. Evaluates every tool call against SHACL shapes, policies, preferences, and dependencies. Returns `{ block: true }` if the action violates constraints. |
+| `message_sending` | 100 | Checks outbound messages for sensitive data leaks, contact rule violations, and content policy. Returns `{ cancel: true }` to block. |
+| `subagent_spawning` | 100 | Evaluates child agent spawn requests. Detects delegation bypass attempts where a blocked parent tries to spawn an unrestricted child. |
+
+### Context hooks (modify agent behavior)
+
+| Hook | Priority | Description |
+|------|----------|-------------|
+| `before_prompt_build` | 100 | Injects governance context into the agent system prompt via `prependSystemContext`. Tells the agent what constraints are active. |
+
+### Recording hooks (fire-and-forget)
+
+| Hook | Description |
+|------|-------------|
+| `after_tool_call` | Records tool execution results (success/failure, duration, errors) for dependency tracking and audit. |
+| `llm_input` | Logs the prompt sent to the LLM, including provider and model name. |
+| `llm_output` | Logs the LLM response, including token usage. |
+| `subagent_ended` | Records child agent lifecycle completion. |
+| `session_start` | Notifies the service when a new session begins. |
+| `session_end` | Notifies the service when a session ends. |
+| `message_received` | Evaluates inbound messages for governance (sender, channel, content). |
+
+## Agent Tools
+
+The plugin registers two tools that agents can call to introspect governance state.
+
+### `safeclaw_status`
+
+Returns the current governance status. No parameters.
+
+```json
+{
+  "status": "ok",
+  "enforcement": "enforce",
+  "failMode": "open",
+  "serviceUrl": "http://localhost:8420/api/v1",
+  "handshakeCompleted": true
+}
+```
+
+### `safeclaw_check_action`
+
+Dry-run check of whether a tool call would be allowed. No side effects.
+
+**Parameters:**
+- `toolName` (string, required) -- tool name to check
+- `params` (object, optional) -- tool parameters to validate
+
+```json
+{
+  "block": false,
+  "reason": null,
+  "constraints": ["shacl:ActionShape", "policy:NoForceOnMain"]
+}
+```
+
+## CLI Commands
+
+The plugin ships a standalone CLI (`safeclaw-plugin`) and registers a `safeclaw` subcommand in the OpenClaw CLI via `api.registerCli`.
+
+### Standalone CLI
+
+```
+safeclaw-plugin connect <api-key>    Save API key, validate via handshake, register with OpenClaw
+safeclaw-plugin setup                Register plugin with OpenClaw (no key needed)
+safeclaw-plugin restart-openclaw     Restart the OpenClaw daemon
+safeclaw-plugin status               Run diagnostics (config, service, handshake, OpenClaw, NemoClaw)
+safeclaw-plugin config show          Show current configuration
+safeclaw-plugin config set <k> <v>   Set a config value (enforcement, failMode, enabled, serviceUrl)
+safeclaw-plugin tui                  Open interactive settings TUI
+```
+
+### OpenClaw CLI extension
+
+When loaded by OpenClaw, the plugin adds:
+
+```
+openclaw safeclaw status    Show SafeClaw service status and enforcement mode
+```
+
+## NemoClaw Sandbox
+
+When running inside a NemoClaw sandbox (detected via the `OPENSHELL_SANDBOX` environment variable), the plugin automatically adjusts:
+
+- **Service URL**: `localhost` is rewritten to `host.containers.internal` since the sandbox runs in a container and cannot reach the host's loopback interface directly.
+- **Egress policy**: The bundled `policies/safeclaw.yaml` defines the network rules NemoClaw needs to allow SafeClaw traffic.
+
+### Setup
+
+1. Copy the egress policy into your NemoClaw configuration:
+
+```bash
+nemoclaw policy-add safeclaw
+```
+
+Or manually copy `policies/safeclaw.yaml` to your NemoClaw policy directory.
+
+2. The policy allows two destinations:
+   - `api.safeclaw.eu:443` (HTTPS) -- cloud service
+   - `host.containers.internal:8420` (HTTP) -- self-hosted service on the host machine
+
+3. No additional configuration is needed. The plugin detects the sandbox automatically and adjusts the service URL.
+
+## Architecture
+
+This plugin is a thin HTTP bridge (~450 lines). All governance logic lives in the SafeClaw Python service. The plugin:
+
+1. Registers hooks on OpenClaw events
+2. Forwards event data to the SafeClaw service via HTTP POST
+3. Acts on the service response (block, warn, or allow)
+4. Sends a heartbeat every 30 seconds with config hash
+5. Registers as an OpenClaw service for clean lifecycle management (no `process.exit()`)
 
-- **`enforce`** — block actions that violate constraints (recommended)
-- **`warn-only`** — log warnings but allow all actions
-- **`audit-only`** — server-side logging only, no client-side action
-- **`disabled`** — plugin is completely inactive
+The plugin performs a handshake with the service on startup to validate the API key and confirm the engine is ready. If the handshake fails and `failMode` is `closed`, all tool calls are blocked until the service becomes reachable.
 
 ## License
 

package/SKILL.md

@@ -1,48 +1,49 @@
-# SafeClaw — Neurosymbolic Governance for OpenClaw
+# SafeClaw -- Neurosymbolic Governance for OpenClaw
 
-SafeClaw adds ontology-based constraint checking to your OpenClaw agent. Every tool call, message, and action is validated against OWL ontologies and SHACL shapes before execution.
+SafeClaw validates every tool call, message, and agent action against OWL ontologies and SHACL constraints before execution. It acts as a governance gate between your AI agent and the tools it uses.
 
 ## What it does
 
-- **Blocks dangerous actions** — force push, deleting root, exposing secrets
-- **Enforces dependencies** — tests must pass before git push
-- **Checks user preferences** — confirmation for irreversible actions based on autonomy level
-- **Governs messages** — blocks sensitive data leaks, enforces never-contact lists
-- **Full audit trail** — every decision logged with ontological justification
+- **Blocks dangerous actions** -- force push, deleting root, exposing secrets
+- **Enforces dependencies** -- tests must pass before git push
+- **Checks user preferences** -- confirmation for irreversible actions based on autonomy level
+- **Governs messages** -- blocks sensitive data leaks, enforces contact rules
+- **Controls subagent delegation** -- prevents blocked parents from spawning unrestricted children
+- **Full audit trail** -- every decision logged with ontological justification
 
-## Setup
+## Hooks
 
-The plugin connects to `https://api.safeclaw.eu/api/v1` by default — no configuration needed.
+11 hooks covering the full agent lifecycle:
 
-### Self-hosted mode
+- `before_tool_call` -- constraint gate for every tool invocation
+- `before_prompt_build` -- injects governance context into system prompt
+- `message_sending` -- outbound message governance
+- `message_received` -- inbound message evaluation
+- `llm_input` / `llm_output` -- LLM interaction audit logging
+- `after_tool_call` -- records outcomes for dependency tracking
+- `subagent_spawning` / `subagent_ended` -- multi-agent governance
+- `session_start` / `session_end` -- session lifecycle tracking
 
-To run your own SafeClaw service, override the URL:
+## Agent tools
 
-```bash
-export SAFECLAW_URL="http://localhost:8420/api/v1"
-export SAFECLAW_API_KEY="sc_live_your_key_here"  # optional
-```
+- `safeclaw_status` -- check governance service status and active enforcement mode
+- `safeclaw_check_action` -- dry-run check if a specific tool call would be allowed
 
 ## Configuration
 
-Set via environment variables or `~/.safeclaw/config.json`:
+Set via OpenClaw plugin settings, `~/.safeclaw/config.json`, or `SAFECLAW_*` environment variables. Supports four enforcement modes (`enforce`, `warn-only`, `audit-only`, `disabled`) and two fail modes (`open`, `closed`).
+
+### NemoClaw sandbox
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SAFECLAW_URL` | `https://api.safeclaw.eu/api/v1` | SafeClaw service URL |
-| `SAFECLAW_API_KEY` | (empty) | API key for remote/cloud mode |
-| `SAFECLAW_TIMEOUT_MS` | `500` | Request timeout in milliseconds |
-| `SAFECLAW_ENABLED` | `true` | Set to `false` to disable |
-| `SAFECLAW_ENFORCEMENT` | `enforce` | `enforce`, `warn-only`, `audit-only`, or `disabled` |
+Automatically detects NemoClaw sandboxes and rewrites `localhost` to `host.containers.internal`. Includes a bundled egress policy at `policies/safeclaw.yaml`.
 
-## How it works
+### Self-hosted
 
-This plugin registers hooks on every OpenClaw event:
+Run the SafeClaw service locally:
 
-1. **before_tool_call** — validates against SHACL shapes, policies, preferences, dependencies
-2. **before_agent_start** — injects governance context into the agent's system prompt
-3. **message_sending** — checks outbound messages for sensitive data and contact rules
-4. **after_tool_call** — records action outcomes for dependency tracking
-5. **llm_input/output** — logs LLM interactions for audit
+```bash
+pip install safeclaw
+safeclaw serve
+```
 
-If the SafeClaw service is unavailable, the plugin degrades gracefully — no blocks, no crashes.
+The plugin connects to `http://localhost:8420/api/v1` by default.

package/cli.tsx

@@ -7,7 +7,7 @@ import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import App from './tui/App.js';
-import { loadConfig, saveConfig, type SafeClawConfig } from './tui/config.js';
+import { loadConfig, saveConfig, isNemoClawSandbox, getSandboxName, type SafeClawConfig } from './tui/config.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8')).version as string;
@@ -464,6 +464,13 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     allOk = false;
   }
 
+  // 9. NemoClaw sandbox
+  if (isNemoClawSandbox()) {
+    console.log(`[ok] NemoClaw sandbox: ${getSandboxName()}`);
+  } else {
+    console.log('[--] NemoClaw: not in sandbox (standalone mode)');
+  }
+
   // Summary
   console.log('');
   if (allOk) {
@@ -483,8 +490,8 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
   console.log('  restart-openclaw     Restart the OpenClaw daemon to pick up plugin changes');
   console.log('');
   console.log('Diagnostics:');
-  console.log('  status               Run 8 checks: config, API key, service health, evaluate endpoint,');
-  console.log('                       handshake, OpenClaw binary, plugin files, OpenClaw config');
+  console.log('  status               Run 9 checks: config, API key, service health, evaluate endpoint,');
+  console.log('                       handshake, OpenClaw binary, plugin files, OpenClaw config, NemoClaw');
   console.log('');
   console.log('Configuration:');
   console.log('  config show          Show current enforcement, failMode, enabled, serviceUrl, apiKey');

package/dist/cli.js

@@ -7,7 +7,7 @@ import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import App from './tui/App.js';
-import { loadConfig, saveConfig } from './tui/config.js';
+import { loadConfig, saveConfig, isNemoClawSandbox, getSandboxName } from './tui/config.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8')).version;
 function readJson(path) {
@@ -473,6 +473,13 @@ else if (command === 'status') {
         console.log('[!!] OpenClaw config: not found');
         allOk = false;
     }
+    // 9. NemoClaw sandbox
+    if (isNemoClawSandbox()) {
+        console.log(`[ok] NemoClaw sandbox: ${getSandboxName()}`);
+    }
+    else {
+        console.log('[--] NemoClaw: not in sandbox (standalone mode)');
+    }
     // Summary
     console.log('');
     if (allOk) {
@@ -494,8 +501,8 @@ else {
     console.log('  restart-openclaw     Restart the OpenClaw daemon to pick up plugin changes');
     console.log('');
     console.log('Diagnostics:');
-    console.log('  status               Run 8 checks: config, API key, service health, evaluate endpoint,');
-    console.log('                       handshake, OpenClaw binary, plugin files, OpenClaw config');
+    console.log('  status               Run 9 checks: config, API key, service health, evaluate endpoint,');
+    console.log('                       handshake, OpenClaw binary, plugin files, OpenClaw config, NemoClaw');
     console.log('');
     console.log('Configuration:');
     console.log('  config show          Show current enforcement, failMode, enabled, serviceUrl, apiKey');

package/dist/index.d.ts

@@ -6,25 +6,11 @@
  * This plugin is a thin HTTP bridge that forwards OpenClaw events
  * to the SafeClaw service and acts on the responses.
  */
-interface PluginEvent {
-    sessionId?: string;
-    userId?: string;
-    [key: string]: unknown;
-}
-interface PluginContext {
-    sessionId?: string;
-    userId?: string;
-    [key: string]: unknown;
-}
-interface PluginApi {
-    on(event: string, handler: (event: PluginEvent, ctx: PluginContext) => Promise<Record<string, unknown> | void> | void, options?: {
-        priority?: number;
-    }): void;
-}
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk/core';
 declare const _default: {
     id: string;
     name: string;
     version: string;
-    register(api: PluginApi): void;
+    register(api: OpenClawPluginApi): void;
 };
 export default _default;