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
- The agent calls
clawshell_bash
instead of bash
- ClawShell analyzes the command against built-in and configurable risk rules
- 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
- 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 executeworkingDir
(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
.
| 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 before auto-reject |
CLAWSHELL_LOG_DIR
| logs/ | Directory for JSONL log files |
CLAWSHELL_LOG_LEVEL
| info | Log verbosity: debug, info, warn, error |
CLAWSHELL_BLOCKLIST
| — | Comma-separated extra blocked commands |
CLAWSHELL_ALLOWLIST
| — | Comma-separated extra allowed commands |
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.
