ClawShell

Human-in-the-loop security for OpenClaw agents.

What it does

ClawShell intercepts shell commands before execution, analyzes their risk level, and requires your explicit approval (via phone notification) for dangerous operations like rm -rf, curl to external URLs, or accessing credentials.

| Risk Level | Action | Examples | |------------|--------|----------| | Critical | Auto-blocked | rm -rf /, fork bombs, dd to disks | | High | Pushover/Telegram notification, waits for approval | rm -rf, curl to external URLs, sudo, credential access | | Medium | Logged, allowed | npm install, git push, git commit | | Low | Allowed | ls, cat, git status, npm test |

Quick Start

1. Add to your OpenClaw workspace skills:

   npx clawhub install clawshell

2. Add your notification keys to .env:

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

3. Add to your TOOLS.md:

   Use clawshell_bash instead of bash for all shell commands.

4. Done! You'll get push notifications for risky commands.

Tools

• clawshell_bash(command, workingDir) — Secure bash replacement with risk analysis
• clawshell_status() — View pending approvals and recent decisions
• clawshell_logs(count) — View audit log entries
• clawshell_config() — View current configuration (without secrets)

Configuration

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

| Variable | Default | Description | |----------|---------|-------------| | CLAWSHELL_PUSHOVER_USER | -- | Pushover user key | | CLAWSHELL_PUSHOVER_TOKEN | -- | Pushover app token | | CLAWSHELL_TELEGRAM_BOT_TOKEN | -- | Telegram bot token (alternative) | | CLAWSHELL_TELEGRAM_CHAT_ID | -- | Telegram chat ID (alternative) | | CLAWSHELL_TIMEOUT_SECONDS | 300 | Seconds to wait for approval | | CLAWSHELL_LOG_DIR | logs/ | JSONL log directory | | CLAWSHELL_BLOCKLIST | -- | Comma-separated extra blocked commands | | CLAWSHELL_ALLOWLIST | -- | Comma-separated extra allowed commands |

Custom rules can also be defined in config.yaml using exact strings, globs, or regex patterns. See config.example.yaml for the full template.

Development

# Run unit tests (standalone)
npm test

# Docker - isolated (no network)
docker-compose -f docker/docker-compose.yml build
docker-compose -f docker/docker-compose.yml up -d
docker exec -it clawshell-dev bash

# Docker - with network (Pushover testing)
docker-compose -f docker/docker-compose.network.yml up -d
docker exec -it clawshell-dev-network bash

# Inside container
cd /app/workspace/skills/clawshell
node --test test/risk-analyzer.test.mjs
node --test test/logger.test.mjs
node --test test/integration.test.mjs

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.

License

MIT