OpenClaw AI SAFE² Security Setup Guide: Static, Runtime, Ishi Hardening

Need to lock down an OpenClaw deployment that’s about to touch customer PII, production Kubernetes or a payment gateway? This guide walks through installing and configuring AI SAFE² — the third-party hardening layer that wraps OpenClaw with defense-in-depth controls. We’ll cover the three moving parts (static policy checks, runtime guards, and the Ishi supervisor agent), where they sit in the request path, and why you might not want them for a weekend hack project.

Why SAFE² Exists and When to Use It

Out of the box, OpenClaw already ships with TLS, CSRF protection, auth middleware, and rate limiting. For most internal prototypes that’s enough. The SAFE² framework comes into play when one of these is true:

You’re connecting OpenClaw to tools that hold sensitive data (Gmail, Stripe, Production Postgres).
The agent will issue shell commands on hosts that matter.
You need SOC 2, ISO 27001, or internal red-team sign-off.
Latency budget can afford an extra 30–60 ms per request.

If you’re in the “it’s just a Discord bot for my D&D group” camp, SAFE² is overkill. Skip it and keep your YAML simple.

Understanding the Three SAFE² Components

1. Static Controls (safe2-lint)

Think of safe2-lint as ESLint for agent workflows. It parses OpenClaw configuration (JSON or YAML), checks it against a policy bundle, and fails CI if you try something sketchy — e.g., mapping shell.exec to rm -rf / without a confirmation step.

2. Runtime Controls (safe2-guard)

This is a sidecar process that proxies every OpenClaw tool invocation. It uses Open Policy Agent (OPA) under the hood. When your agent wants to hit the Gmail API, safe2-guard evaluates a Rego policy first. Denied calls never leave the box.

3. Ishi Supervisor Agent

Ishi is a lightweight Go binary that monitors the OS level: file descriptors, network sockets, memory usage. It can kill or throttle the OpenClaw process if it goes rogue. Think systemd-oomd but policy-aware.

Prerequisites and Caveats

OpenClaw ≥ 1.9.0 (requires Node 22+).
safe2-cli 0.8.1 or later (tested with 0.9.0-rc2).
Docker ≥ 24 if you run sidecars in containers.
Ubuntu 22.04 LTS or a recent Alpine image. macOS is fine for local dev, Ishi won’t enforce cgroups there.
Ability to edit your CI pipeline (GitHub Actions examples below).

SAFE² is licensed under AGPL-v3. If you embed it in a SaaS, your legal team may want a word.

Installation Walk-Through

1. Install the CLI

Globally or as a dev dependency. I prefer the latter so CI has the same version:

npm install --save-dev @safe2/cli@0.9.0-rc2

2. Initialize a Policy Repo

npx safe2 init-security --out .safe2

This scaffolds:

.safe2/policies/*.rego
.safe2/controls.yml
.github/workflows/safe2-ci.yml (optional)

3. Add Sidecar Image

If you deploy via Docker Compose, drop this in:


services:
  claw_gateway:
    image: ghcr.io/openclaw/gateway:1.9.2
    depends_on: [safe2_guard]
    environment:
      SAFE2_ENDPOINT: "http://safe2_guard:8282"
  safe2_guard:
    image: ghcr.io/safe2/guard:0.9.0-rc2
    ports:
      - "8282:8282"

4. Install Ishi on the Host

curl -sSL https://ishidownloads.safe2.dev/ishi_0.5.3_linux_amd64.tar.gz | sudo tar -xz -C /usr/local/bin
sudo ishi enroll --policy /.safe2/ishi-policy.yml

Configuring Static Controls

Open .safe2/controls.yml. A minimal config:


static:
  denyShellCommands:
    - "rm -rf*"
    - "mkfs*"
  maxOpenAITokens: 4096
  allowedHTTPHosts:
    - "api.github.com"
    - "api.openai.com"

Run the checker locally:

npx safe2 lint gateway.config.yaml

You’ll get output like:


ERROR shell.exec "rm -rf /" violates rule denyShellCommands (S2-113)

In CI (GitHub Actions):


name: SAFE2 Lint
on: [push]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx safe2 lint gateway.config.yaml

Enabling Runtime Controls

The guard sidecar needs policies. Edit .safe2/policies/claw.rego:


package safe2.claw

allow {
  input.action == "github.createIssue"
  input.repo == "my-org/*"
}

deny[msg] {
  input.action == "shell.exec"
  not input.cwd == "/tmp/sandbox"
  msg := sprintf("Shell execution outside sandbox: %v", [input.cwd])
}

Build a bundle:

npx safe2 build --bundle .safe2/policies --out bundle.tar.gz

Mount the bundle into the sidecar:


  safe2_guard:
    image: ghcr.io/safe2/guard:0.9.0-rc2
    volumes:
      - ./bundle.tar.gz:/bundle.tar.gz
    command: ["--bundle", "/bundle.tar.gz"]

Check logs:

docker logs -f safe2_guard | grep decision

You should see lines like:

decision_id=ab12 method=POST path=/evaluate result=allow

Wiring in the Ishi Supervisor Agent

Ishi reads cgroup metrics every 250 ms and evaluates a local Rego file (ishi-policy.yml):


process_limits:
  max_memory: 512MiB
  max_open_files: 2048
  max_cpu_seconds: 60
kill_on_violation: true
notify_webhook: "https://hooks.slack.com/services/T0.../B0.../X0..."

After enrollment, start the service:

sudo systemctl enable --now ishi

Trigger a violation by allocating 1 GiB:

node -e "Buffer.alloc(1024*1024*1024)"

You’ll find in /var/log/ishi.log:

[MEM] pid 3421 exceeded 512MiB. SIGKILL sent.

Testing the Whole Chain

Attempt a forbidden static change (e.g., add shell.exec: "mkfs.ext4 /dev/sda"). CI should fail.
Run the gateway locally and invoke an action blocked by runtime policy. The sidecar should return HTTP 403 with JSON {"error":"policy_denied"}.
Stress-test memory to watch Ishi step in.

If all three fail-safes trigger as expected, pat yourself on the back and log the evidence for your auditor.

Trade-offs: Cost, Latency, Complexity

Latency: safe2-guard adds ~2ms per policy evaluation, plus network hops if sidecar isn’t localhost. Expect 30–60 ms P95 end-to-end.
Memory: guard runs OPA; baseline 60 MiB RSS. Ishi adds another 20 MiB.
Dev Ergonomics: Two extra YAMLs and Rego files. New engineers need onboarding.
License: AGPL means source distribution obligations if you modify SAFE².
Maintenance: Policies drift. You’ll need a monthly review cycle or they rot.

If your threat model is a curious intern accidentally running DROP DATABASE, SAFE² is worth it. If you’re a solo hacker building a weekend Slack bot, pass.

Where to Go from Here

1) Publish your first policy bundle to an internal registry. 2) Add safe2 trivy-pass to bake container scanning into the same workflow. 3) For ClawCloud users, open Settings → Security and paste the bundle URL; the platform spins up guard for you automatically.

That’s it — you now have an OpenClaw deployment that fails closed, not open. Next time compliance asks for “evidence of compensating controls,” you won’t have to fake screenshots.