Tools
Aari
By Execution firewall plugin for OpenClaw agents, powered by AARI.
Install
openclaw plugins install /path/to/openclaw-aariConfiguration 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
}
}
}
}
}README
# 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:
```text
[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 for high-risk action types.
This is **action-type based**, not a universal block-all mode.
High-risk categories can still be blocked locally even without a live server round-trip.
---
## Installation
### Package name
Current package name:
```text
@aari/aari-firewall
```
### Local/path install
OpenClaw can install the plugin from a local path.
Example:
```bash
openclaw plugins install /path/to/openclaw-aari
```
After installation, configure the plugin entry in `openclaw.json`.
### Minimal config example
```json
{
"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 | `agent.action` |
The `message` mapping is important because real OpenClaw outbound messaging flows through `message`, not only through older names like `send_message`.
---
## 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
### Telegram messaging
- Telegram channel wiring works
- Telegram inbound path works
- outbound `message -> telegram` ALLOW path works
- outbound `message -> telegram` BLOCK path works
This means the plugin is already validated on:
- one real execution path (`exec`)
- one real messaging/channel path (`message -> telegram`)
---
## 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
- validation is currently strongest for `exec` and Telegram
- other OpenClaw channels are not yet all proven end-to-end
- current V1 truth should be stated narrowly and honestly
---
## Honest V1 scope
This plugin is currently strongest as:
- an OpenClaw execution firewall
- with proven `exec` enforcement
- and proven Telegram outbound enforcement
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
- ALLOW / WARN / BLOCK decisions from AARI
- clean blocking behavior inside OpenClaw
- outcome reporting for audit trail
- proven protection for `exec`
- proven protection for outbound Telegram messaging
tools
Comments
Sign in to leave a comment