openguardrails-instrumentation-openclaw 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# openguardrails-instrumentation-openclaw
+
+Guard an [OpenClaw](https://github.com/openclaw/openclaw) assistant through the
+**OpenGuardrails (OGR)** protocol — a vendor-neutral enforcement layer for AI
+agent safety & security. It's the multi-channel counterpart of
+[`openguardrails-instrumentation-opencode`](../instrumentation-opencode).
+
+**No OpenClaw core changes.** This is a pure plugin built on OpenClaw's
+in-process [plugin hooks](https://docs.openclaw.ai/plugins/hooks). It is
+*restrict-only*: it can stop a would-run tool call or a would-send message,
+never loosen one.
+
+## What it does
+
+Each hooked event becomes an OGR `GuardEvent`, runs through a `Runtime` built
+from **your own policy** (deterministic text/regex rules, plus optionally your
+own model as an LLM judge), and the resulting `Verdict` is enforced:
+
+| Hook | `allow` / `modify` / `redact` | `block` | `require_approval` |
+| --- | --- | --- | --- |
+| **`before_tool_call`** | proceed | `{ block }` | `{ requireApproval }` — native `/approve` human gate |
+| **`message_sending`** (outbound) | deliver | `{ cancel }` | `{ cancel }` |
+
+The human-confirm gate and enforcement stay **privilege-separated**: the plugin
+*decides*, the user *approves*, the host *enforces*.
+
+## Install
+
+```bash
+openclaw plugins install clawhub:openguardrails
+# or, during the npm cutover:
+openclaw plugins install openguardrails-instrumentation-openclaw
+```
+
+## Configure
+
+The assistant configures its **own** guardrails. Resolution order (low → high):
+
+1. A safe default policy (curl-pipe-to-sh, `rm -rf /`, secret-file reads, …).
+2. `<workspace>/openguardrails.json` — an OGR `policy.json` the assistant can
+   edit to give itself guardrails. Override the path with `policyPath` or the
+   `OPENGUARDRAILS_POLICY` env var.
+3. Inline plugin config (highest precedence), in your OpenClaw config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openguardrails": {
+        "config": {
+          "judge": {
+            "baseURL": "http://localhost:11434/v1",
+            "model": "your-guard-model",
+            "apiKey": "..."
+          },
+          "guardMessages": true
+        }
+      }
+    }
+  }
+}
+```
+
+`judge` points the LLM-judge detector at any OpenAI-compatible chat endpoint —
+the same model the assistant already uses, a cheaper sibling, or a dedicated
+guard model. The policy format is identical across every OGR integration
+(opencode, hermes, python), so one `policy.json` works everywhere.
+
+## Scope & follow-ups
+
+- v0.1 treats the principal as trusted. Channel-inbound tainting (untrusted
+  message / web / mcp content → untrusted provenance, correlated into the tool
+  call) is the next step via `message_received`.
+- Input guardrails on the prompt itself (`before_agent_run`) require the
+  operator to set `plugins.entries.openguardrails.hooks.allowConversationAccess`
+  — a config flag, not a code change. Not needed for the tool/message
+  enforcement above.
+
+## License
+
+Apache-2.0

package/dist/config.d.ts

@@ -0,0 +1,33 @@
+import type { Policy } from "@openguardrails/core";
+/** "Use your own model as the guardrail" — any OpenAI-compatible chat endpoint. */
+export interface JudgeConfig {
+    baseURL: string;
+    model: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+}
+/** Plugin config, delivered through OpenClaw `plugins.entries.openguardrails.config`. */
+export interface GuardrailsOptions {
+    /** Inline OGR policy (overrides the file + default). */
+    policy?: Policy;
+    /** Path to a guardrails policy file (defaults to <workspace>/openguardrails.json). */
+    policyPath?: string;
+    /** Enable the LLM-judge detector backed by your own model. */
+    judge?: JudgeConfig;
+    /** Also evaluate inbound/outbound channel messages (default true). */
+    guardMessages?: boolean;
+}
+/** Default text/regex guardrails — deterministic, no model required. */
+export declare const DEFAULT_POLICY: Policy;
+export interface ResolvedConfig {
+    policy: Policy;
+    judge?: JudgeConfig;
+    guardMessages: boolean;
+}
+/**
+ * Resolve the effective policy. `workspaceDir` is the OpenClaw workspace (known
+ * at `gateway_start`); when absent we fall back to `process.cwd()` so the plugin
+ * still resolves a file during early registration.
+ */
+export declare function loadGuardrailsConfig(workspaceDir: string | undefined, options?: GuardrailsOptions): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAElD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,sEAAsE;IACtE,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,wEAAwE;AACxE,eAAO,MAAM,cAAc,EAAE,MA0C5B,CAAA;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,aAAa,EAAE,OAAO,CAAA;CACvB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,cAAc,CAmBlH"}

package/dist/config.js

@@ -0,0 +1,87 @@
+/**
+ * Guardrails configuration for the OpenClaw integration.
+ *
+ * The assistant configures its OWN guardrails — text + regex rules (no model
+ * needed), and optionally its own model as an LLM judge. Resolution order
+ * (lowest → highest precedence):
+ *
+ *   1. a sensible default policy (below)
+ *   2. `<workspace>/openguardrails.json` (agent-editable — this is how an
+ *      assistant gives itself guardrails); path overridable via plugin config
+ *      `policyPath` or the `OPENGUARDRAILS_POLICY` env var
+ *   3. inline plugin config `policy` (set in OpenClaw config under
+ *      `plugins.entries.openguardrails.config`)
+ *
+ * The policy IS an OGR policy.json (composition + config_rules), so the same
+ * file format works across every OGR integration (opencode, hermes, python).
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+/** Default text/regex guardrails — deterministic, no model required. */
+export const DEFAULT_POLICY = {
+    composition: {
+        "security.*": { strategy: "deny-wins", on_all_failed: "block" },
+        default: { strategy: "deny-wins" },
+    },
+    config_rules: {
+        secret_env_markers: ["SECRET", "TOKEN", "KEY", "PASSWORD", "AWS_", "PRIVATE", "CREDENTIAL"],
+        command_rules: [
+            {
+                id: "pipe-to-shell",
+                regex: "(curl|wget)\\b.*\\|\\s*(ba)?sh",
+                category: "security.malicious_command",
+                decision: "require_approval",
+                score: 0.85,
+                why: "remote script fetched and piped directly into a shell",
+            },
+            {
+                id: "rm-rf-root",
+                regex: "rm\\s+-rf\\s+/(\\s|$)",
+                category: "security.malicious_command",
+                decision: "block",
+                score: 1.0,
+                why: "destructive recursive delete of the filesystem root",
+            },
+            {
+                id: "secret-file-access",
+                regex: "(\\.env\\b|/\\.aws/credentials|/\\.ssh/id_|/\\.ssh/|auth\\.json|\\.netrc)",
+                category: "security.secret_leak",
+                decision: "block",
+                score: 0.9,
+                why: "command references a credential file — independent of the reader",
+            },
+            {
+                id: "pipe-to-sudo",
+                regex: "\\|\\s*sudo\\b",
+                category: "security.privilege_escalation",
+                decision: "require_approval",
+                score: 0.7,
+                why: "output piped into sudo",
+            },
+        ],
+    },
+};
+/**
+ * Resolve the effective policy. `workspaceDir` is the OpenClaw workspace (known
+ * at `gateway_start`); when absent we fall back to `process.cwd()` so the plugin
+ * still resolves a file during early registration.
+ */
+export function loadGuardrailsConfig(workspaceDir, options) {
+    let policy = DEFAULT_POLICY;
+    const path = options?.policyPath ??
+        process.env["OPENGUARDRAILS_POLICY"] ??
+        join(workspaceDir ?? process.cwd(), "openguardrails.json");
+    if (existsSync(path)) {
+        try {
+            policy = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            // malformed file → keep the safe default rather than failing open silently
+        }
+    }
+    if (options?.policy)
+        policy = options.policy;
+    const judge = options?.judge ?? policy["judge"];
+    return { policy, judge, guardMessages: options?.guardMessages ?? true };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAuBhC,wEAAwE;AACxE,MAAM,CAAC,MAAM,cAAc,GAAW;IACpC,WAAW,EAAE;QACX,YAAY,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE;QAC/D,OAAO,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE;KACnC;IACD,YAAY,EAAE;QACZ,kBAAkB,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,CAAC;QAC3F,aAAa,EAAE;YACb;gBACE,EAAE,EAAE,eAAe;gBACnB,KAAK,EAAE,gCAAgC;gBACvC,QAAQ,EAAE,4BAA4B;gBACtC,QAAQ,EAAE,kBAAkB;gBAC5B,KAAK,EAAE,IAAI;gBACX,GAAG,EAAE,uDAAuD;aAC7D;YACD;gBACE,EAAE,EAAE,YAAY;gBAChB,KAAK,EAAE,uBAAuB;gBAC9B,QAAQ,EAAE,4BAA4B;gBACtC,QAAQ,EAAE,OAAO;gBACjB,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,qDAAqD;aAC3D;YACD;gBACE,EAAE,EAAE,oBAAoB;gBACxB,KAAK,EAAE,2EAA2E;gBAClF,QAAQ,EAAE,sBAAsB;gBAChC,QAAQ,EAAE,OAAO;gBACjB,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,kEAAkE;aACxE;YACD;gBACE,EAAE,EAAE,cAAc;gBAClB,KAAK,EAAE,gBAAgB;gBACvB,QAAQ,EAAE,+BAA+B;gBACzC,QAAQ,EAAE,kBAAkB;gBAC5B,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,wBAAwB;aAC9B;SACF;KACF;CACF,CAAA;AAQD;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAAgC,EAAE,OAA2B;IAChG,IAAI,MAAM,GAAW,cAAc,CAAA;IAEnC,MAAM,IAAI,GACR,OAAO,EAAE,UAAU;QACnB,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;QACpC,IAAI,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,qBAAqB,CAAC,CAAA;IAE5D,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAW,CAAA;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,2EAA2E;QAC7E,CAAC;IACH,CAAC;IACD,IAAI,OAAO,EAAE,MAAM;QAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;IAE5C,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAK,MAAM,CAAC,OAAO,CAA6B,CAAA;IAC5E,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,IAAI,IAAI,EAAE,CAAA;AACzE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * openguardrails-instrumentation-openclaw
+ *
+ * An OpenClaw plugin that guards an assistant through the OpenGuardrails (OGR)
+ * protocol — the multi-channel counterpart of
+ * `openguardrails-instrumentation-opencode`.
+ *
+ * It registers in-process plugin hooks, turns each event into an OGR
+ * `GuardEvent`, runs it through a `Runtime` built from the assistant's own
+ * guardrails policy (text/regex rules, plus optionally its own model as an LLM
+ * judge), and enforces the `Verdict`:
+ *
+ *   before_tool_call   allow | modify | redact → proceed
+ *                      block                   → { block }
+ *                      require_approval        → { requireApproval } (human gate)
+ *
+ *   message_sending    allow | modify | redact → deliver
+ *                      block | require_approval → { cancel } (outbound guard)
+ *
+ * No OpenClaw core changes required. This is a "restrict-only" guard: it can
+ * stop a would-run tool call or a would-send message, never loosen one. The
+ * human-confirm gate (`requireApproval`) and enforcement stay privilege-
+ * separated: the plugin decides, the user approves, the host enforces.
+ */
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+declare const plugin: ReturnType<typeof definePluginEntry>;
+export default plugin;
+export { DEFAULT_POLICY } from "./config.js";
+export type { GuardrailsOptions, JudgeConfig } from "./config.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AAwEpE,QAAA,MAAM,MAAM,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAyF/C,CAAA;AAEF,eAAe,MAAM,CAAA;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,165 @@
+/**
+ * openguardrails-instrumentation-openclaw
+ *
+ * An OpenClaw plugin that guards an assistant through the OpenGuardrails (OGR)
+ * protocol — the multi-channel counterpart of
+ * `openguardrails-instrumentation-opencode`.
+ *
+ * It registers in-process plugin hooks, turns each event into an OGR
+ * `GuardEvent`, runs it through a `Runtime` built from the assistant's own
+ * guardrails policy (text/regex rules, plus optionally its own model as an LLM
+ * judge), and enforces the `Verdict`:
+ *
+ *   before_tool_call   allow | modify | redact → proceed
+ *                      block                   → { block }
+ *                      require_approval        → { requireApproval } (human gate)
+ *
+ *   message_sending    allow | modify | redact → deliver
+ *                      block | require_approval → { cancel } (outbound guard)
+ *
+ * No OpenClaw core changes required. This is a "restrict-only" guard: it can
+ * stop a would-run tool call or a would-send message, never loosen one. The
+ * human-confirm gate (`requireApproval`) and enforcement stay privilege-
+ * separated: the plugin decides, the user approves, the host enforces.
+ */
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { Runtime, ConfigRulesDetector, LLMJudgeDetector, } from "@openguardrails/core";
+import { loadGuardrailsConfig } from "./config.js";
+import { openAICompatibleBackend } from "./own-model.js";
+let seq = 0;
+function id(prefix) {
+    seq += 1;
+    const rand = globalThis.crypto?.randomUUID?.().slice(0, 8) ?? seq.toString(36).padStart(8, "0");
+    return `${prefix}-${seq.toString(36)}-${rand}`;
+}
+function brief(v) {
+    const cats = v.categories.map((c) => `${c.id}(${c.score})`).join(", ");
+    const why = v.reasons.filter((r) => !r.startsWith("[")).join("; ");
+    return [cats, why].filter(Boolean).join(" — ") || v.decision;
+}
+/**
+ * Lazily builds and caches the OGR runtime. The policy file lives in the
+ * workspace, which is only known at `gateway_start`; tool/message hooks build
+ * on first use if startup has not populated it yet.
+ */
+class GuardManager {
+    runtime;
+    guardMessages = true;
+    workspaceDir;
+    options;
+    configure(workspaceDir, options) {
+        this.workspaceDir = workspaceDir;
+        this.options = options;
+        this.runtime = undefined; // force rebuild with the new workspace/options
+        this.ensure();
+    }
+    ensure() {
+        if (this.runtime)
+            return this.runtime;
+        const { policy, judge, guardMessages } = loadGuardrailsConfig(this.workspaceDir, this.options);
+        const detectors = [new ConfigRulesDetector(policy.config_rules ?? {})];
+        if (judge)
+            detectors.push(new LLMJudgeDetector(openAICompatibleBackend(judge)));
+        this.guardMessages = guardMessages;
+        this.runtime = new Runtime(detectors, policy);
+        return this.runtime;
+    }
+    get messagesEnabled() {
+        this.ensure();
+        return this.guardMessages;
+    }
+    evaluate(ev) {
+        return this.ensure().evaluate(ev);
+    }
+}
+/** Best-effort read of this plugin's config out of the OpenClaw config tree. */
+function readOptions(config) {
+    const entries = config?.plugins?.entries;
+    return entries?.["openguardrails"]?.config;
+}
+// Annotate via the importable `definePluginEntry` symbol so the emitted
+// declaration does not inline OpenClaw's non-exported `DefinedPluginEntry`
+// type (TS2742 portability).
+const plugin = definePluginEntry({
+    id: "openguardrails",
+    name: "OpenGuardrails",
+    description: "Enforce the OpenGuardrails (OGR) protocol on tool calls and channel traffic — block, rewrite, or require human approval under a policy you own.",
+    register(api) {
+        const guard = new GuardManager();
+        // Resolve the workspace-scoped policy once the Gateway is up.
+        api.on("gateway_start", (_event, ctx) => {
+            const c = ctx;
+            guard.configure(c.workspaceDir, readOptions(c.config));
+        });
+        // Core enforcement: every tool call, before it runs.
+        api.on("before_tool_call", async (event, ctx) => {
+            const c = ctx;
+            const ev = {
+                kind: "tool_call",
+                observationPoint: "agent_hook",
+                subject: {
+                    agent_id: c.agentId ?? "openclaw",
+                    agent_type: "openclaw",
+                    session_id: c.sessionKey,
+                    channel: c.channelId,
+                },
+                payload: { name: event.toolName, arguments: event.params },
+                eventId: id("evt"),
+                guardId: event.toolCallId ?? id("ga"),
+                timestamp: new Date().toISOString(),
+                sessionId: c.sessionKey,
+                // v0.1: the principal is trusted. Channel-inbound tainting
+                // (untrusted message/web/mcp content → untrusted provenance) is a
+                // follow-up via message_received correlation.
+                provenance: [{ source: "user", trust: "trusted" }],
+            };
+            const verdict = await guard.evaluate(ev);
+            if (verdict.decision === "block") {
+                return { block: true, blockReason: `[OpenGuardrails] ${brief(verdict)}` };
+            }
+            if (verdict.decision === "require_approval") {
+                return {
+                    requireApproval: {
+                        title: `Approve ${event.toolName}?`,
+                        description: `[OpenGuardrails] ${brief(verdict)}`,
+                        severity: "warning",
+                        timeoutBehavior: "deny",
+                        pluginId: "openguardrails",
+                    },
+                };
+            }
+            // allow | modify | redact → proceed unchanged
+            return;
+        }, { priority: 50 });
+        // Outbound guard: cancel a reply a deny verdict would forbid.
+        api.on("message_sending", async (event, ctx) => {
+            if (!guard.messagesEnabled)
+                return;
+            const e = event;
+            const c = ctx;
+            const ev = {
+                kind: "model_output",
+                observationPoint: "gateway",
+                subject: { agent_id: c.agentId ?? "openclaw", agent_type: "openclaw", session_id: c.sessionKey },
+                payload: { content: e.content ?? "", channel: c.messageProvider },
+                eventId: id("evt"),
+                guardId: id("ga"),
+                timestamp: new Date().toISOString(),
+                sessionId: c.sessionKey,
+                provenance: [{ source: "model", trust: "unverified" }],
+            };
+            const verdict = await guard.evaluate(ev);
+            if (verdict.decision === "block" || verdict.decision === "require_approval") {
+                return {
+                    cancel: true,
+                    cancelReason: `openguardrails:${verdict.decision}`,
+                    metadata: { reason: brief(verdict) },
+                };
+            }
+            return;
+        });
+    },
+});
+export default plugin;
+export { DEFAULT_POLICY } from "./config.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/own-model.d.ts

@@ -0,0 +1,12 @@
+/**
+ * "Use your own model as the guardrail" — an OGR LLMBackend that calls any
+ * OpenAI-compatible chat-completions endpoint. Point it at the same model the
+ * assistant already uses, a cheaper sibling, or a dedicated guard model.
+ *
+ * Identical contract to the opencode/hermes integrations: one OpenAI-compatible
+ * POST, OGR does the rest.
+ */
+import type { LLMBackend } from "@openguardrails/core";
+import type { JudgeConfig } from "./config.js";
+export declare function openAICompatibleBackend(cfg: JudgeConfig): LLMBackend;
+//# sourceMappingURL=own-model.d.ts.map

package/dist/own-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"own-model.d.ts","sourceRoot":"","sources":["../src/own-model.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,WAAW,GAAG,UAAU,CA4BpE"}

package/dist/own-model.js

@@ -0,0 +1,31 @@
+export function openAICompatibleBackend(cfg) {
+    const url = cfg.baseURL.replace(/\/+$/, "") + "/chat/completions";
+    return {
+        name: `own-model:${cfg.model}`,
+        async complete(system, user) {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...(cfg.apiKey ? { authorization: `Bearer ${cfg.apiKey}` } : {}),
+                    ...(cfg.headers ?? {}),
+                },
+                body: JSON.stringify({
+                    model: cfg.model,
+                    temperature: 0,
+                    messages: [
+                        { role: "system", content: system },
+                        { role: "user", content: user },
+                    ],
+                }),
+            });
+            if (!res.ok)
+                throw new Error(`guard model returned ${res.status}`);
+            const data = (await res.json());
+            const text = data.choices?.[0]?.message?.content ?? "";
+            // Strip a ```json fence if the model wrapped its reply.
+            return text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();
+        },
+    };
+}
+//# sourceMappingURL=own-model.js.map

package/dist/own-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"own-model.js","sourceRoot":"","sources":["../src/own-model.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,uBAAuB,CAAC,GAAgB;IACtD,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,mBAAmB,CAAA;IACjE,OAAO;QACL,IAAI,EAAE,aAAa,GAAG,CAAC,KAAK,EAAE;QAC9B,KAAK,CAAC,QAAQ,CAAC,MAAc,EAAE,IAAY;YACzC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC3B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChE,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;iBACvB;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,KAAK,EAAE,GAAG,CAAC,KAAK;oBAChB,WAAW,EAAE,CAAC;oBACd,QAAQ,EAAE;wBACR,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;wBACnC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE;qBAChC;iBACF,CAAC;aACH,CAAC,CAAA;YACF,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAA;YAClE,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA4D,CAAA;YAC1F,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,CAAA;YACtD,wDAAwD;YACxD,OAAO,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;QAC7E,CAAC;KACF,CAAA;AACH,CAAC"}

package/openclaw.plugin.json

@@ -0,0 +1,38 @@
+{
+  "id": "openguardrails",
+  "name": "OpenGuardrails",
+  "description": "Enforce the OpenGuardrails (OGR) protocol on tool calls and channel traffic — block, rewrite, or require human approval under a policy you own.",
+  "activation": {
+    "onStartup": true,
+    "onCapabilities": ["hook"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "policyPath": {
+        "type": "string",
+        "description": "Path to an OGR policy.json. Defaults to <workspace>/openguardrails.json."
+      },
+      "policy": {
+        "type": "object",
+        "description": "Inline OGR policy (composition + config_rules). Overrides the file and the default.",
+        "additionalProperties": true
+      },
+      "judge": {
+        "type": "object",
+        "description": "Use your own model as an LLM-judge detector (any OpenAI-compatible chat endpoint).",
+        "additionalProperties": true,
+        "properties": {
+          "baseURL": { "type": "string" },
+          "model": { "type": "string" },
+          "apiKey": { "type": "string" }
+        }
+      },
+      "guardMessages": {
+        "type": "boolean",
+        "description": "Also evaluate inbound/outbound channel messages (defaults to true)."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "openguardrails-instrumentation-openclaw",
+  "version": "0.1.0",
+  "description": "Guard an OpenClaw assistant's tool calls and channel traffic through the OpenGuardrails (OGR) protocol — agent-configurable text/regex guardrails, or use your own model as the judge. No core changes.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "OpenGuardrails",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "src", "openclaw.plugin.json"],
+  "openclaw": {
+    "extensions": ["./dist/index.js"],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean"
+  },
+  "keywords": ["openclaw", "plugin", "ai", "agent", "security", "guardrails", "ogr", "openguardrails"],
+  "dependencies": {
+    "@openguardrails/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "openclaw": "^2026.6.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openguardrails/openguardrails-js.git",
+    "directory": "packages/instrumentation-openclaw"
+  },
+  "homepage": "https://openguardrails.com",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.ts

@@ -0,0 +1,117 @@
+/**
+ * Guardrails configuration for the OpenClaw integration.
+ *
+ * The assistant configures its OWN guardrails — text + regex rules (no model
+ * needed), and optionally its own model as an LLM judge. Resolution order
+ * (lowest → highest precedence):
+ *
+ *   1. a sensible default policy (below)
+ *   2. `<workspace>/openguardrails.json` (agent-editable — this is how an
+ *      assistant gives itself guardrails); path overridable via plugin config
+ *      `policyPath` or the `OPENGUARDRAILS_POLICY` env var
+ *   3. inline plugin config `policy` (set in OpenClaw config under
+ *      `plugins.entries.openguardrails.config`)
+ *
+ * The policy IS an OGR policy.json (composition + config_rules), so the same
+ * file format works across every OGR integration (opencode, hermes, python).
+ */
+import { readFileSync, existsSync } from "node:fs"
+import { join } from "node:path"
+import type { Policy } from "@openguardrails/core"
+
+/** "Use your own model as the guardrail" — any OpenAI-compatible chat endpoint. */
+export interface JudgeConfig {
+  baseURL: string
+  model: string
+  apiKey?: string
+  headers?: Record<string, string>
+}
+
+/** Plugin config, delivered through OpenClaw `plugins.entries.openguardrails.config`. */
+export interface GuardrailsOptions {
+  /** Inline OGR policy (overrides the file + default). */
+  policy?: Policy
+  /** Path to a guardrails policy file (defaults to <workspace>/openguardrails.json). */
+  policyPath?: string
+  /** Enable the LLM-judge detector backed by your own model. */
+  judge?: JudgeConfig
+  /** Also evaluate inbound/outbound channel messages (default true). */
+  guardMessages?: boolean
+}
+
+/** Default text/regex guardrails — deterministic, no model required. */
+export const DEFAULT_POLICY: Policy = {
+  composition: {
+    "security.*": { strategy: "deny-wins", on_all_failed: "block" },
+    default: { strategy: "deny-wins" },
+  },
+  config_rules: {
+    secret_env_markers: ["SECRET", "TOKEN", "KEY", "PASSWORD", "AWS_", "PRIVATE", "CREDENTIAL"],
+    command_rules: [
+      {
+        id: "pipe-to-shell",
+        regex: "(curl|wget)\\b.*\\|\\s*(ba)?sh",
+        category: "security.malicious_command",
+        decision: "require_approval",
+        score: 0.85,
+        why: "remote script fetched and piped directly into a shell",
+      },
+      {
+        id: "rm-rf-root",
+        regex: "rm\\s+-rf\\s+/(\\s|$)",
+        category: "security.malicious_command",
+        decision: "block",
+        score: 1.0,
+        why: "destructive recursive delete of the filesystem root",
+      },
+      {
+        id: "secret-file-access",
+        regex: "(\\.env\\b|/\\.aws/credentials|/\\.ssh/id_|/\\.ssh/|auth\\.json|\\.netrc)",
+        category: "security.secret_leak",
+        decision: "block",
+        score: 0.9,
+        why: "command references a credential file — independent of the reader",
+      },
+      {
+        id: "pipe-to-sudo",
+        regex: "\\|\\s*sudo\\b",
+        category: "security.privilege_escalation",
+        decision: "require_approval",
+        score: 0.7,
+        why: "output piped into sudo",
+      },
+    ],
+  },
+}
+
+export interface ResolvedConfig {
+  policy: Policy
+  judge?: JudgeConfig
+  guardMessages: boolean
+}
+
+/**
+ * Resolve the effective policy. `workspaceDir` is the OpenClaw workspace (known
+ * at `gateway_start`); when absent we fall back to `process.cwd()` so the plugin
+ * still resolves a file during early registration.
+ */
+export function loadGuardrailsConfig(workspaceDir: string | undefined, options?: GuardrailsOptions): ResolvedConfig {
+  let policy: Policy = DEFAULT_POLICY
+
+  const path =
+    options?.policyPath ??
+    process.env["OPENGUARDRAILS_POLICY"] ??
+    join(workspaceDir ?? process.cwd(), "openguardrails.json")
+
+  if (existsSync(path)) {
+    try {
+      policy = JSON.parse(readFileSync(path, "utf8")) as Policy
+    } catch {
+      // malformed file → keep the safe default rather than failing open silently
+    }
+  }
+  if (options?.policy) policy = options.policy
+
+  const judge = options?.judge ?? (policy["judge"] as JudgeConfig | undefined)
+  return { policy, judge, guardMessages: options?.guardMessages ?? true }
+}

package/src/index.ts

@@ -0,0 +1,191 @@
+/**
+ * openguardrails-instrumentation-openclaw
+ *
+ * An OpenClaw plugin that guards an assistant through the OpenGuardrails (OGR)
+ * protocol — the multi-channel counterpart of
+ * `openguardrails-instrumentation-opencode`.
+ *
+ * It registers in-process plugin hooks, turns each event into an OGR
+ * `GuardEvent`, runs it through a `Runtime` built from the assistant's own
+ * guardrails policy (text/regex rules, plus optionally its own model as an LLM
+ * judge), and enforces the `Verdict`:
+ *
+ *   before_tool_call   allow | modify | redact → proceed
+ *                      block                   → { block }
+ *                      require_approval        → { requireApproval } (human gate)
+ *
+ *   message_sending    allow | modify | redact → deliver
+ *                      block | require_approval → { cancel } (outbound guard)
+ *
+ * No OpenClaw core changes required. This is a "restrict-only" guard: it can
+ * stop a would-run tool call or a would-send message, never loosen one. The
+ * human-confirm gate (`requireApproval`) and enforcement stay privilege-
+ * separated: the plugin decides, the user approves, the host enforces.
+ */
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"
+import {
+  Runtime,
+  ConfigRulesDetector,
+  LLMJudgeDetector,
+  type Detector,
+  type GuardEvent,
+  type Verdict,
+} from "@openguardrails/core"
+import { loadGuardrailsConfig, type GuardrailsOptions } from "./config.js"
+import { openAICompatibleBackend } from "./own-model.js"
+
+let seq = 0
+function id(prefix: string): string {
+  seq += 1
+  const rand = globalThis.crypto?.randomUUID?.().slice(0, 8) ?? seq.toString(36).padStart(8, "0")
+  return `${prefix}-${seq.toString(36)}-${rand}`
+}
+
+function brief(v: Verdict): string {
+  const cats = v.categories.map((c) => `${c.id}(${c.score})`).join(", ")
+  const why = v.reasons.filter((r) => !r.startsWith("[")).join("; ")
+  return [cats, why].filter(Boolean).join(" — ") || v.decision
+}
+
+/**
+ * Lazily builds and caches the OGR runtime. The policy file lives in the
+ * workspace, which is only known at `gateway_start`; tool/message hooks build
+ * on first use if startup has not populated it yet.
+ */
+class GuardManager {
+  private runtime: Runtime | undefined
+  private guardMessages = true
+  private workspaceDir: string | undefined
+  private options: GuardrailsOptions | undefined
+
+  configure(workspaceDir: string | undefined, options: GuardrailsOptions | undefined): void {
+    this.workspaceDir = workspaceDir
+    this.options = options
+    this.runtime = undefined // force rebuild with the new workspace/options
+    this.ensure()
+  }
+
+  private ensure(): Runtime {
+    if (this.runtime) return this.runtime
+    const { policy, judge, guardMessages } = loadGuardrailsConfig(this.workspaceDir, this.options)
+    const detectors: Detector[] = [new ConfigRulesDetector(policy.config_rules ?? {})]
+    if (judge) detectors.push(new LLMJudgeDetector(openAICompatibleBackend(judge)))
+    this.guardMessages = guardMessages
+    this.runtime = new Runtime(detectors, policy)
+    return this.runtime
+  }
+
+  get messagesEnabled(): boolean {
+    this.ensure()
+    return this.guardMessages
+  }
+
+  evaluate(ev: GuardEvent): Promise<Verdict> {
+    return this.ensure().evaluate(ev)
+  }
+}
+
+/** Best-effort read of this plugin's config out of the OpenClaw config tree. */
+function readOptions(config: unknown): GuardrailsOptions | undefined {
+  const entries = (config as { plugins?: { entries?: Record<string, { config?: unknown }> } })?.plugins?.entries
+  return entries?.["openguardrails"]?.config as GuardrailsOptions | undefined
+}
+
+// Annotate via the importable `definePluginEntry` symbol so the emitted
+// declaration does not inline OpenClaw's non-exported `DefinedPluginEntry`
+// type (TS2742 portability).
+const plugin: ReturnType<typeof definePluginEntry> = definePluginEntry({
+  id: "openguardrails",
+  name: "OpenGuardrails",
+  description:
+    "Enforce the OpenGuardrails (OGR) protocol on tool calls and channel traffic — block, rewrite, or require human approval under a policy you own.",
+  register(api) {
+    const guard = new GuardManager()
+
+    // Resolve the workspace-scoped policy once the Gateway is up.
+    api.on("gateway_start", (_event, ctx) => {
+      const c = ctx as { workspaceDir?: string; config?: unknown }
+      guard.configure(c.workspaceDir, readOptions(c.config))
+    })
+
+    // Core enforcement: every tool call, before it runs.
+    api.on(
+      "before_tool_call",
+      async (event, ctx) => {
+        const c = ctx as { agentId?: string; sessionKey?: string; channelId?: string }
+        const ev: GuardEvent = {
+          kind: "tool_call",
+          observationPoint: "agent_hook",
+          subject: {
+            agent_id: c.agentId ?? "openclaw",
+            agent_type: "openclaw",
+            session_id: c.sessionKey,
+            channel: c.channelId,
+          },
+          payload: { name: event.toolName, arguments: event.params },
+          eventId: id("evt"),
+          guardId: event.toolCallId ?? id("ga"),
+          timestamp: new Date().toISOString(),
+          sessionId: c.sessionKey,
+          // v0.1: the principal is trusted. Channel-inbound tainting
+          // (untrusted message/web/mcp content → untrusted provenance) is a
+          // follow-up via message_received correlation.
+          provenance: [{ source: "user", trust: "trusted" }],
+        }
+
+        const verdict = await guard.evaluate(ev)
+
+        if (verdict.decision === "block") {
+          return { block: true, blockReason: `[OpenGuardrails] ${brief(verdict)}` }
+        }
+        if (verdict.decision === "require_approval") {
+          return {
+            requireApproval: {
+              title: `Approve ${event.toolName}?`,
+              description: `[OpenGuardrails] ${brief(verdict)}`,
+              severity: "warning",
+              timeoutBehavior: "deny",
+              pluginId: "openguardrails",
+            },
+          }
+        }
+        // allow | modify | redact → proceed unchanged
+        return
+      },
+      { priority: 50 },
+    )
+
+    // Outbound guard: cancel a reply a deny verdict would forbid.
+    api.on("message_sending", async (event, ctx) => {
+      if (!guard.messagesEnabled) return
+      const e = event as { content?: string }
+      const c = ctx as { agentId?: string; sessionKey?: string; messageProvider?: string }
+      const ev: GuardEvent = {
+        kind: "model_output",
+        observationPoint: "gateway",
+        subject: { agent_id: c.agentId ?? "openclaw", agent_type: "openclaw", session_id: c.sessionKey },
+        payload: { content: e.content ?? "", channel: c.messageProvider },
+        eventId: id("evt"),
+        guardId: id("ga"),
+        timestamp: new Date().toISOString(),
+        sessionId: c.sessionKey,
+        provenance: [{ source: "model", trust: "unverified" }],
+      }
+
+      const verdict = await guard.evaluate(ev)
+      if (verdict.decision === "block" || verdict.decision === "require_approval") {
+        return {
+          cancel: true,
+          cancelReason: `openguardrails:${verdict.decision}`,
+          metadata: { reason: brief(verdict) },
+        }
+      }
+      return
+    })
+  },
+})
+
+export default plugin
+
+export { DEFAULT_POLICY } from "./config.js"
+export type { GuardrailsOptions, JudgeConfig } from "./config.js"

package/src/own-model.ts

@@ -0,0 +1,40 @@
+/**
+ * "Use your own model as the guardrail" — an OGR LLMBackend that calls any
+ * OpenAI-compatible chat-completions endpoint. Point it at the same model the
+ * assistant already uses, a cheaper sibling, or a dedicated guard model.
+ *
+ * Identical contract to the opencode/hermes integrations: one OpenAI-compatible
+ * POST, OGR does the rest.
+ */
+import type { LLMBackend } from "@openguardrails/core"
+import type { JudgeConfig } from "./config.js"
+
+export function openAICompatibleBackend(cfg: JudgeConfig): LLMBackend {
+  const url = cfg.baseURL.replace(/\/+$/, "") + "/chat/completions"
+  return {
+    name: `own-model:${cfg.model}`,
+    async complete(system: string, user: string): Promise<string> {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...(cfg.apiKey ? { authorization: `Bearer ${cfg.apiKey}` } : {}),
+          ...(cfg.headers ?? {}),
+        },
+        body: JSON.stringify({
+          model: cfg.model,
+          temperature: 0,
+          messages: [
+            { role: "system", content: system },
+            { role: "user", content: user },
+          ],
+        }),
+      })
+      if (!res.ok) throw new Error(`guard model returned ${res.status}`)
+      const data = (await res.json()) as { choices?: Array<{ message?: { content?: string } }> }
+      const text = data.choices?.[0]?.message?.content ?? ""
+      // Strip a ```json fence if the model wrapped its reply.
+      return text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim()
+    },
+  }
+}