Sage — Safety for Agents

What is Sage?

Sage is a security layer for OpenClaw. It intercepts tool calls — shell commands, URL fetches, file writes — and checks them for threats before they execute. If something looks dangerous, Sage blocks it with a native approval dialog.

What it protects against

• Malicious URLs — phishing, malware, and scam sites detected via cloud reputation
• Dangerous commands — reverse shells, pipe-to-curl, credential theft, data exfiltration
• Prompt injection — heuristics + a fine-tuned ML model detect injected instructions in fetched content
• Suspicious file operations — writes to sensitive paths, credential files, system configs
• Supply-chain attacks — malicious or typosquatted npm/PyPI packages
• Compromised plugins — automatic scanning of installed plugins at session start

Install

See the install guide for step-by-step instructions, or run:

openclaw plugins install @gendigital/sage-openclaw

Sage loads automatically — no configuration needed.

To verify it's working, ask your agent to run echo __sage_test_deny_cmd_a75bf229__. Sage should block this harmless canary command.

What Sage intercepts

Sage hooks into OpenClaw's before_tool_call lifecycle:

• exec — shell commands
• write / edit — file modifications
• read — file reads (sensitive paths)
• web_fetch — URL fetches and downloads
• apply_patch — patch application

How it works

When your agent makes a tool call, Sage evaluates it and returns a verdict:

| Verdict | What happens | |---------|-------------| | Allow | No threats detected — the action proceeds normally | | Ask | Suspicious activity — you're prompted via native approval dialog | | Deny | Threat detected — the action is blocked |

Sage is designed to fail open: if anything goes wrong internally, the action proceeds. Your agent is never blocked due to a Sage error.

Configuration

Sage works out of the box with no configuration. To customize behavior, edit ~/.sage/config.json:

{
  "sensitivity": "balanced",
  "url_check": { "enabled": true },
  "heuristics_enabled": true
}

See Configuration for all options.

Links

• User Guide — verify install, handle alerts, manage false positives
• Configuration — all config options
• Exceptions — pattern-based allow/deny rules
• Privacy — what data is sent, what stays local
• GitHub