AARI Execution Firewall — OpenClaw Plugin

Execution firewall for OpenClaw agents. The plugin intercepts tool calls before execution, asks the AARI control plane for a decision, and enforces ALLOW / WARN / BLOCK behavior inside OpenClaw.

This README reflects the current hook-based implementation and the runtime behavior already validated on a live OpenClaw instance.

What it does

The plugin adds a real pre-execution control layer in front of OpenClaw tool calls.

Main user value:

• OpenClaw remains powerful
• risky actions can be scored and blocked before they execute
• users get clear block reasons instead of silent failures or hidden behavior
• AARI receives an audit trail for decisions and outcomes

Current implementation model

The plugin uses native OpenClaw hooks:

1. before_prompt_build

   • injects AARI system context into the prompt
   • advisory layer only

2. before_tool_call

   • maps the OpenClaw tool call to an AARI action_type
   • calls the AARI /gate endpoint
   • enforces the decision before execution

3. after_tool_call

   • reports SUCCESS / FAILURE outcomes back to AARI
   • blocked calls are reported as skipped from the blocking path

This is the current source-of-truth behavior. It is not based on registerTool tool-shadowing in the current implementation.

Decision behavior

For each intercepted tool call, AARI returns one of:

• ALLOW — execution proceeds normally
• WARN — execution proceeds, but the action is flagged
• BLOCK — execution is stopped before the tool runs

In enforced mode, BLOCK returns a clean OpenClaw block result such as:

[AARI BLOCK] 'exec' blocked. Policy: ...

The goal is to stop the action cleanly without breaking the runtime.

Fail-closed behavior

If the AARI server is unreachable, the plugin uses local degraded/fail-closed logic.

This is action-type based, not a universal block-all mode:

• filesystem.rm, filesystem.write, file.delete, code.execute → BLOCK locally
• unknown.action, agent.action → WARN locally (never silent pass-through)
• Other action types → ALLOW or WARN depending on class

Installation

Package name

Current package name:

@aari/aari-firewall

Local/path install

OpenClaw can install the plugin from a local path. Example:

openclaw plugins install /path/to/openclaw-aari

After installation, configure the plugin entry in openclaw.json.

Minimal config example

{
  "plugins": {
    "allow": ["aari-firewall"],
    "entries": {
      "aari-firewall": {
        "enabled": true,
        "config": {
          "apiKey": "sk_aari_...",
          "server": "https://api.getaari.com",
          "agentId": "openclaw-agent",
          "environment": "dev",
          "mode": "enforced",
          "timeoutMs": 5000
        }
      }
    }
  }
}

Then restart OpenClaw.

Configuration

| Field | Type | Default | Description | |---|---|---|---| | apiKey | string | required | AARI API key | | server | string | https://api.getaari.com | AARI server URL | | agentId | string | openclaw-agent | Agent identifier used in AARI audit trail | | environment | dev \| staging \| prod | prod | Deployment environment | | mode | enforced \| advisory | enforced | enforced blocks; advisory warns only | | timeoutMs | number | 5000 | Gate request timeout |

Tool mapping

The plugin maps OpenClaw tool names into AARI action types.

Confirmed important mappings

| OpenClaw tool | AARI action type | |---|---| | shell, bash, exec, execute | code.execute | | file_write, write_file | filesystem.write | | file_delete, delete_file | filesystem.rm | | http_post | http.post | | send_email, email_send | email.send | | message | message.send | | sql, db_query, db_execute | db.execute | | fallback | unknown.action |

The message mapping is important because real OpenClaw outbound messaging flows through message, not only through older names like send_message.

Any tool name not in the mapping table falls back to unknown.action (score 55, WARN territory). This means unmapped tools are never silently low-risk.

Runtime validation already completed

The following paths have already been validated on a live OpenClaw instance:

Shell / exec

• exec ALLOW path works
• destructive exec commands can be blocked by AARI policy
• blocked exec actions do not execute

Protected path escalation

• writes and deletes targeting ~/.ssh, .aws/credentials, and other secret paths → BLOCK
• writes and deletes targeting /etc/, /usr/bin/, and other system paths → BLOCK
• code.execute commands touching protected paths → BLOCK (enforced mode)
• temp path operations score correctly without false elevation

Outbound messaging

• outbound message -> telegram ALLOW path works
• outbound message -> telegram BLOCK path works
• message.send and email.send → WARN by default (warn policies fire)

Unknown / unmapped tools

• unmapped tool names fall back to unknown.action
• unknown.action → WARN decision (never silent ALLOW)
• warn-oc-unknown-action policy fires on all unmapped tool calls

This means the plugin is validated on:

• shell/exec enforcement
• protected-path blocking (secret and system paths)
• outbound messaging visibility and control
• unmapped tool fallback behavior

Audit trail

Every intercepted action can be reported into AARI with:

• action type
• resource
• score
• policy hits
• decision
• outcome (SUCCESS, FAILURE, SKIPPED)
• agent ID / run context

This makes the plugin both an enforcement layer and an audit surface.

Known limitations

Current known limitations:

• README/install flow still needs a fresh-user validation pass
• other OpenClaw channels beyond exec and Telegram are not yet all proven end-to-end
• command understanding is heuristic (pattern matching, not full shell-intent parsing)
• workspace root is not configured — workspace-like path detection is heuristic
• actions are evaluated independently — cross-tool multi-step correlation is not yet supported
• scripts are scored by execution context, not by reading script contents

Honest V1 scope

This plugin is currently proven as:

• an OpenClaw execution firewall for shell/exec actions
• protected-path blocking (secret and system paths, write and delete)
• outbound messaging visibility and control (message.send, email.send, Telegram)
• safe unmapped tool fallback via unknown.action (never silent)
• fail-closed behavior when AARI is unreachable

It should not yet be described as universal coverage for every OpenClaw channel or every agent ecosystem.

Summary

AARI Execution Firewall for OpenClaw provides:

• pre-execution interception via native OpenClaw hooks
• ALLOW / WARN / BLOCK decisions from AARI
• clean blocking behavior inside OpenClaw
• outcome reporting for audit trail
• proven protection for exec and shell commands
• proven protected-path blocking (secret and system paths)
• outbound messaging visibility and control
• safe fallback for unmapped tools via unknown.action