OpenClaw Quick Start

The golden path: RADIUS + OpenClaw, from zero to live-blocked dangerous action in under 10 minutes.

Prerequisites

• OpenClaw installed and running
• Node.js >= 22.12 (OpenClaw runtime requirement)
• npm

Quick check:

node -v

Verified compatibility snapshot (February 18, 2026)

Validated in real hook runs with agentradius@0.4.0 and OpenClaw adapter:

Step 1 — Install

npm install agentradius

Step 2 — Initialize for OpenClaw

npx agentradius init --framework openclaw --profile standard

This creates:

• radius.yaml — your security policy
• .radius/openclaw-hook.command.sh — the hook script OpenClaw calls
• .radius/openclaw-hooks.json — hook registration for OpenClaw

The standard profile is the recommended starting point for development: default deny, secrets redacted, sandbox optional, 60 calls/min.

Step 3 — Annotated config walkthrough

Open radius.yaml. Here’s what the OpenClaw init generates:

global section

global:
  profile: standard
  workspace: "${CWD}"
  defaultAction: deny

• profile — standard. Controls defaults for all modules.
• workspace — ${CWD} resolves to your current directory at load time. This is the agent’s allowed root.
• defaultAction — deny. Any tool not explicitly in the allow-list is blocked.

modules array

modules:
  - kill_switch
  - skill_scanner
  - tool_policy
  - fs_guard
  - command_guard
  - exec_sandbox
  - output_dlp
  - rate_budget
  - audit

Pipeline runs top-to-bottom. Order matters — kill_switch is first so it can halt everything. audit is last so it logs the final decision.

moduleConfig highlights

moduleConfig:
  fs_guard:
    allowedPaths:
      - "${workspace}"
      - "/tmp"
    blockedPaths:
      - "~/.ssh"
      - "~/.aws"
      - "/etc"
    blockedBasenames:
      - ".env"
      - ".env.local"
      - ".envrc"
  command_guard:
    denyPatterns:
      - "(^|\\s)sudo\\s"
      - "rm\\s+-rf\\s+/"
      - "(^|\\s)(cat|less|more|head|tail|grep|awk|sed)\\s+[^\\n]*\\.env(?:\\.|\\s|$)"
  rate_budget:
    windowSec: 60
    maxCallsPerWindow: 60
  exec_sandbox:
    engine: bwrap
    required: false
  output_dlp:
    action: redact

• fs_guard — The agent can only touch ${workspace} and /tmp. No .ssh, .aws, /etc, or .env files.
• command_guard — sudo, rm -rf /, and commands reading .env files are dead on arrival.
• rate_budget — 60 tool calls per 60-second window. Prevents runaway loops.
• exec_sandbox — bwrap isolation available but not required (standard profile).
• output_dlp — Secrets are redacted from output, not blocked entirely.

Step 3b — Production-safe OpenClaw baseline

For production-like OpenClaw runs, start from this baseline and then tune allowlists:

global:
  profile: standard
  workspace: "${CWD}"
  defaultAction: deny

modules:
  - kill_switch
  - skill_scanner
  - tool_policy
  - fs_guard
  - command_guard
  - exec_sandbox
  - egress_guard
  - output_dlp
  - rate_budget
  - approval_gate
  - audit

moduleConfig:
  fs_guard:
    allowedPaths:
      - "${workspace}"
      - "/tmp"
    blockedPaths:
      - "~/.ssh"
      - "~/.aws"
      - "/etc"
    blockedBasenames:
      - ".env"
      - ".env.local"
      - ".envrc"
  command_guard:
    denyPatterns:
      - "(^|\\s)sudo\\s"
      - "rm\\s+-rf\\s+/"
      - "(^|\\s)(cat|less|more|head|tail|grep|awk|sed)\\s+[^\\n]*\\.env(?:\\.|\\s|$)"
  egress_guard:
    blockedDomains:
      - "evil.com"
      - "*.ngrok-free.app"
  output_dlp:
    action: redact
  rate_budget:
    windowSec: 60
    maxCallsPerWindow: 60
  exec_sandbox:
    engine: bwrap
    required: false
  approval_gate:
    enabled: false
  audit:
    sink: file
    path: .radius/audit.jsonl

Note: with agentradius@0.4.0, keep effective audit sink/path in moduleConfig.audit for reliable hook runtime behavior.

Step 4 — Wiring files

The init command creates two files that connect RADIUS to OpenClaw’s hook system:

.radius/openclaw-hook.command.sh

This is the shell script OpenClaw calls on every PreToolUse and PostToolUse event. It pipes the hook JSON through npx agentradius hook --adapter openclaw and returns the decision.

What it does: reads the hook payload from stdin, passes it through the RADIUS pipeline, writes the allow/deny/challenge decision to stdout.

.radius/openclaw-hooks.json

This registers the hook with OpenClaw:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [".radius/openclaw-hook.command.sh"]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [".radius/openclaw-hook.command.sh"]
      }
    ]
  }
}

Where to place these: Both files should be in your OpenClaw project root (or wherever OpenClaw reads its hooks config). The init command places them relative to ${CWD} and the generated script resolves config path from its own directory ($SCRIPT_DIR), so it does not depend on shell working directory.

Step 5 — Health check

npx agentradius doctor

Expected output for an OpenClaw setup:

[PASS] Config loaded: radius.yaml
[PASS] Profile: standard
[PASS] Workspace: /path/to/your/project
[PASS] Modules loaded: 9/9
[PASS] Adapter: openclaw
[PASS] Hook script: .radius/openclaw-hook.command.sh (executable)
[PASS] Audit sink: file (.radius/audit.jsonl)
[INFO] exec_sandbox: bwrap not required (standard profile)

If you see [FAIL], the doctor output tells you exactly what’s wrong and how to fix it.

Step 6 — Pentest

npx agentradius pentest

The pentest command simulates 9 attack scenarios against your config:

* egress_guard is not in the standard profile’s default module list. If you add it to your modules array, scenario 7 will be blocked.

All 9 passing? Your policy is working.

Step 7 — Live test

Now test with a real OpenClaw session:

1. Start OpenClaw as usual
2. Ask your agent to do something dangerous: “Read the contents of ~/.ssh/id_rsa”
3. You should see the action blocked — the agent gets a deny response with the reason

Check the audit log:

tail -f .radius/audit.jsonl

You’ll see the timestamped decision: which module blocked it, why, and the full event context.

Step 8 (optional) — Telegram approvals

Add human-in-the-loop approval for risky operations. Instead of auto-denying, RADIUS sends you a Telegram message and waits for your tap.

Initialize with approvals

npx agentradius init --framework openclaw --profile standard --approvals telegram

Link your Telegram identity

npx agentradius link telegram --chat-id YOUR_CHAT_ID --user-id YOUR_USER_ID

Set the bot token

export TELEGRAM_BOT_TOKEN=your_bot_token_here

The approval_gate module intercepts actions that match your challenge rules and sends a Telegram message with:

• Approve (allow once)
• Allow 30m (temporary approval lease for current OpenClaw session/agent)
• Deny

Default timeout is 300 seconds — if you don’t respond, the action is denied.

Troubleshooting

Hook script not found

Error: ENOENT .radius/openclaw-hook.command.sh

Make sure the .radius/ directory is in your OpenClaw project root and the script is executable:

chmod +x .radius/openclaw-hook.command.sh

bwrap not found (exec_sandbox)

[WARN] bwrap binary not found

Install bubblewrap:

# Ubuntu/Debian
sudo apt install bubblewrap

# macOS (via Homebrew)
brew install bubblewrap

Or set exec_sandbox.required: false in your config (already the default for standard profile).

Agent gets denied on everything

Check your tool_policy rules. The standard profile defaults to deny — you need explicit allow rules for each tool your agent uses. See the Configuration Reference for the tool_policy format.

OpenClaw fails with Node 20.x

OpenClaw runtime is Node 22+ (tested with Node 22.12+). Upgrade Node and rerun npx agentradius doctor.

Audit file is not being written

In agentradius@0.4.0, put audit sink/path in moduleConfig.audit:

moduleConfig:
  audit:
    sink: file
    path: .radius/audit.jsonl

Hook runs are slow and repeatedly install packages

If hook calls execute npx agentradius without local install, npx may fetch on each run. Install locally in the OpenClaw project:

npm install agentradius

Rate limit too aggressive

Increase rate_budget.maxCallsPerWindow in your moduleConfig:

moduleConfig:
  rate_budget:
    windowSec: 60
    maxCallsPerWindow: 120

Next steps

• Configuration Reference — full annotated config, profile comparison, all module options
• Generic Quick Start — framework-agnostic setup
• Modules — per-module configuration and hardening notes
• Features — capability map and posture guidance
• What’s New — release highlights and migration checklist