Clawshell

ClawShell

Human-in-the-loop security layer for OpenClaw. ClawShell intercepts shell commands before execution, analyzes their risk level, and requires your explicit approval (via push notification) for dangerous operations.

How it works

1. The agent calls clawshell_bash instead of bash
2. ClawShell analyzes the command against built-in and configurable risk rules
3. Based on risk level:
   • Critical (e.g. rm -rf /, fork bombs) — automatically blocked
   • High (e.g. rm -rf, curl to external URLs, credential access) — sends a push notification and waits for your approval
   • Medium (e.g. npm install, git push) — logged and allowed
   • Low (e.g. ls, cat, git status) — allowed
4. All decisions are logged to logs/clawshell.jsonl

Tools

clawshell_bash

Secure replacement for bash. Analyzes command risk and executes only if safe or approved.

Parameters:

• command (string, required) — The shell command to execute
• workingDir (string, optional) — Working directory (defaults to cwd)

Returns: { exitCode, stdout, stderr }

High-risk commands will block until you approve or reject via push notification. Critical commands are rejected immediately.

clawshell_status

Returns current ClawShell state: pending approval requests and recent decisions.

Parameters: none

clawshell_logs

Returns recent log entries for audit and debugging.

Parameters:

• count (number, optional) — Number of entries to return (default: 20)

Setup

1. Install dependencies

cd /app/workspace/skills/clawshell
npm install

2. Configure Pushover notifications

Create a Pushover application at https://pushover.net/apps/build and add your keys to .env:

CLAWSHELL_PUSHOVER_USER=your-user-key
CLAWSHELL_PUSHOVER_TOKEN=your-app-token

Alternatively, configure Telegram instead:

CLAWSHELL_TELEGRAM_BOT_TOKEN=your-bot-token
CLAWSHELL_TELEGRAM_CHAT_ID=your-chat-id

3. Add to TOOLS.md

Add the following to your OpenClaw TOOLS.md so the agent uses ClawShell for shell commands:

## Shell Access

Use `clawshell_bash` for ALL shell command execution. Do not use `bash` directly.
ClawShell will analyze commands for risk and require human approval for dangerous operations.

Available tools:
- `clawshell_bash(command, workingDir)` — Execute a shell command with risk analysis
- `clawshell_status()` — Check pending approvals and recent decisions
- `clawshell_logs(count)` — View recent audit log entries

Configuration

ClawShell reads configuration from environment variables (CLAWSHELL_*) with fallback to config.yaml.

Custom rules can also be defined in config.yaml under rules.blocklist and rules.allowlist using exact strings, globs, or regex patterns.

Limitations

• Not a security guarantee. LLMs can encode, split, or obfuscate commands to bypass pattern matching.
• Defense-in-depth only. Use alongside OpenClaw's sandbox mode, not as a replacement.
• Approval latency. High-risk commands block execution until you respond or the timeout expires.

Always ask your AI to scan any skill or software for security risks.