Clawshell

Human-in-the-loop security layer. Intercepts high-risk commands and requires push notification approval.

Security Scan

The skill claims to be a shell-intercepting approval layer but is instruction-only with no implementation or install spec; it asks you to run npm install and to add a tool that doesn't exist, and it references extra credentials — these mismatches warrant caution.

Purpose & Capability

The skill's stated purpose is to intercept and mediate shell commands (provide clawshell_bash). However, there are no code files and no install spec that would place a clawshell_bash implementation on disk or in PATH. The registry requires only 'node' and Pushover env vars, but nothing in the package actually implements the interception behavior; instructing the agent (and the user) to replace bash with clawshell_bash is not feasible without additional code. This is an incoherence between claimed capability and the actual artifact.

Instruction Scope

SKILL.md tells the agent to use clawshell_bash for ALL shell execution and to log to logs/clawshell.jsonl, and it instructs the user to run `npm install` in a skill directory. Those runtime instructions assume an implementation exists and that npm will install dependencies from a package manifest in that directory — but none is provided. The doc also references alternative Telegram env vars (CLAWSHELL_TELEGRAM_BOT_TOKEN, CLAWSHELL_TELEGRAM_CHAT_ID) that are not declared in the registry metadata. The instructions therefore overreach relative to the actual bundle and give the agent broad directives that cannot be validated from the skill itself.

Install Mechanism

There is no formal install spec (instruction-only), which is low risk from a supply-chain perspective. However, SKILL.md tells the operator to run `npm install` in /app/workspace/skills/clawshell; because no package files are shipped, this instruction is ambiguous. If a user follows it in a directory that contains a package.json (or if the skill later adds one), that could pull arbitrary npm packages. The absence of a concrete install spec is inconsistent and should be clarified before running installs.

Credentials

The declared required env vars (CLAWSHELL_PUSHOVER_USER and CLAWSHELL_PUSHOVER_TOKEN) align with the described use of Pushover for approvals. That is proportionate. However, the documentation also mentions Telegram-related variables that are not listed in the registry metadata; the skill suggests storing tokens in a .env file. Requiring user/app tokens is expected for notification delivery, but you should confirm the exact variables the installed code will read and avoid placing high-privilege credentials in a skill-specific .env without review.

Persistence & Privilege

The skill does not request always:true and does not declare config paths or other elevated system access. It asks the user to add an entry to TOOLS.md so the agent uses clawshell_bash, which changes agent behavior but is an expected integration step for a tool that mediates shell execution. This is not an unexplained persistence or privilege escalation by itself.

What to consider before installing

This skill's description and runtime instructions promise a command-interception tool, but the package contains no implementation or install spec. Do NOT run `npm install` or add the tool to TOOLS.md until you have the actual source code or a vetted package to install. Ask the publisher for: (1) the repository or packaged code that implements clawshell_bash, (2) a clear install script or vetted release URL, and (3) a manifest showing which env vars the code actually reads. If you decide to test it, create isolated environment (container/VM), use limited-scope notification credentials (create a dedicated Pushover app/user), and review any package.json and source files before executing. Because the skill can be invoked by the agent, treat it as able to influence many agent actions — only install after verifying the code.

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.

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.