check_exists

Clawthority

A semantic authorization runtime for AI agents. Define what your agent can do, enforce it at the boundary, and keep a human in the loop for what matters.

Clawthority is a policy engine plugin for OpenClaw. It sits between your AI agent and every tool it calls, evaluates rules before execution, and - if policy says no - the call is never placed.

Agent tool call  ─►  Clawthority  ─►  Allow  │  Deny  │  Ask human  ─►  Audit log

[!NOTE] v1.x - stable API. The plugin API and policy bundle schema follow semantic versioning; breaking changes ship in a future major release. The version badge above reflects the current release (1.3.4).

---

Contents

• Why Clawthority
• What it is - and isn't
• Quickstart
• How it works
• Action registry
• Human-in-the-loop
• Configuration
• Budget control
• Documentation
• Development
• License

---

Why Clawthority

AI agents call tools. When a tool can delete files, send money, or talk to strangers, who decides whether that call goes through - the model, or you?

Skill-based safety (instruct the model to "please check first") fails the moment the model is wrong, distracted, or prompt-injected. Clawthority moves the decision outside the model's loop - into the code path between the agent and the tool.

A skill asks the model to enforce. A plugin enforces regardless of what the model decides.

---

What it is - and isn't

Clawthority is:

• A policy decision + enforcement layer for tool calls, installed as an OpenClaw plugin.
• A semantic authorizer - rules are written against canonical action classes (filesystem.delete, payment.initiate), not brittle tool-name regexes.
• A cryptographic capability system - HITL approvals are SHA-256-bound to (action_class, target, payload_hash) at approval time. Param tampering after approval = auto-deny.
• Two install modes - open (default, implicit permit + critical forbids) for zero-friction installs, and closed (implicit deny, explicit permits required) for locked-down production. Stage 1 capability/HITL gates and pipeline-level error handling fail closed in both modes.

Clawthority isn't:

• A model-safety or alignment layer. It does not enforce semantic constraints on prompt content, and it does not inspect tool outputs for sensitive data.
• A runtime for agents. OpenClaw still decides which tools the agent sees; Clawthority decides whether those calls run.
• A substitute for good action-class registration. Misregistered tools fall through to unknown_sensitive_action, which is forbidden at priority 100 in closed mode but implicitly permitted in open mode unless you add an explicit forbid rule for it in data/rules.json — a signal you need to register the alias.
• A full process sandbox. Clawthority enforces in-band tool calls only - calls routed through OpenClaw's tool dispatcher. Skills or workspace helpers that call fs, child_process, or network APIs directly bypass the dispatcher and are out of scope. See docs/threat-model.md for the full boundary definition and recommended mitigations.

---

Quickstart

Install from npm into the OpenClaw plugins directory:

mkdir -p ~/.openclaw/plugins/clawthority
cd ~/.openclaw/plugins/clawthority
npm init -y >/dev/null
npm install @clawthority/clawthority

Installing the package runs scripts/post-install.mjs, which writes a data/.installed marker under the plugin root. The marker gates policy activation — see isInstalled() in src/index.ts. No other files outside the plugin directory are touched.

Register in ~/.openclaw/config.json:

{ "plugins": ["clawthority"] }

[!NOTE] The three companion soft-enforcement skills (human-approval, token-budget, whatdidyoudo) live in a separate clawthority-skills repository. They are optional and independent of the plugin.

By default Clawthority runs in open mode - implicit permit, with a critical-forbid safety net (shell.exec, code.execute, payment.initiate, credential.read, credential.write, credential.rotate). Note: unknown_sensitive_action is not in this safety net — unregistered tool names are implicitly permitted in open mode unless you add an explicit forbid rule for unknown_sensitive_action in data/rules.json. To fail closed on unknown tools out of the box, run in closed mode (implicit deny, explicit permits required) by setting the env var before launching your agent:

export CLAWTHORITY_MODE=closed

Mode is read once at activation - restart the agent to change it.

Customise the baseline by dropping hot-reloadable rules into data/rules.json:

[
  { "effect": "permit", "action_class": "filesystem.read" },
  { "effect": "forbid", "action_class": "payment.initiate", "priority": 90 },
  { "effect": "forbid", "resource": "tool", "match": "my_custom_tool" }
]

Run your agent. A shell.exec call now terminates at the boundary:

[clawthority] │ DECISION: BLOCKED (cedar/forbid priority=100 rule=action:shell.exec) - Shell execution is unconditionally forbidden

Every block - plus every HITL outcome - is appended to data/audit.jsonl as structured JSONL with stage, rule, priority, and mode fields. See docs/troubleshooting.md for the recovery runbook.

[!TIP] data/rules.json and hitl-policy.yaml hot-reload within ~300ms. Anything else under src/ requires a gateway restart.

---

How it works

Agent picks a tool → Clawthority intercepts
      │
      │  normalize_action(toolName, params) → { action_class, target, payload_hash }
      │  buildEnvelope(...)                  → ExecutionEnvelope
      ▼
┌──────────────────────── Pipeline ────────────────────────┐
│  Stage 1: Capability Gate                                │
│    • low-risk bypass                                     │
│    • approval_required / TTL / payload binding           │
│    • one-time consumption, session scope                 │
│    • untrusted source + high risk → deny                 │
│                                                          │
│  Stage 2: Constraint Enforcement Engine                  │
│    • protected path che