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 INLINECODE1 - 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
- 4. All decisions are logged to INLINECODE10
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 - INLINECODE13 (string, optional) — Working directory (defaults to cwd)
Returns: INLINECODE14
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
CODEBLOCK0
2. Configure Pushover notifications
Create a Pushover application at https://pushover.net/apps/build and add your keys to .env:
CODEBLOCK1
Alternatively, configure Telegram instead:
CODEBLOCK2
3. Add to TOOLS.md
Add the following to your OpenClaw TOOLS.md so the agent uses ClawShell for shell commands:
CODEBLOCK3
Configuration
ClawShell reads configuration from environment variables (CLAWSHELL_*) with fallback to config.yaml.
| Variable | Default | Description |
|---|
| INLINECODE20 | — | Pushover user key |
| INLINECODE21 |
— | 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.
ClawShell
OpenClaw 的人工参与安全层。ClawShell 在执行前拦截 shell 命令，分析其风险等级，并要求您通过推送通知明确批准危险操作。
工作原理
- 1. 代理调用 clawshell_bash 而非 bash
- ClawShell 根据内置和可配置的风险规则分析命令
- 根据风险等级：
-
严重（例如 rm -rf /、fork 炸弹）——自动阻止
-
高（例如 rm -rf、向外部 URL 发起 curl、凭据访问）——发送推送通知并等待您的批准
-
中（例如 npm install、git push）——记录并允许
-
低（例如 ls、cat、git status）——允许
- 4. 所有决策均记录到 logs/clawshell.jsonl
工具
clawshell_bash
bash 的安全替代方案。分析命令风险，仅在安全或获得批准时执行。
参数：
- - command（字符串，必需）——要执行的 shell 命令
- workingDir（字符串，可选）——工作目录（默认为当前工作目录）
返回： { exitCode, stdout, stderr }
高风险命令将阻塞，直到您通过推送通知批准或拒绝。严重命令会立即被拒绝。
clawshell_status
返回当前 ClawShell 状态：待处理的批准请求和最近的决策。
参数： 无
clawshell_logs
返回最近的日志条目，用于审计和调试。
参数：
- - count（数字，可选）——返回的条目数（默认：20）
设置
1. 安装依赖
bash
cd /app/workspace/skills/clawshell
npm install
2. 配置 Pushover 通知
在 https://pushover.net/apps/build 创建一个 Pushover 应用程序，并将您的密钥添加到 .env：
env
CLAWSHELLPUSHOVERUSER=您的用户密钥
CLAWSHELLPUSHOVERTOKEN=您的应用令牌
或者，改用 Telegram 配置：
env
CLAWSHELLTELEGRAMBOT_TOKEN=您的机器人令牌
CLAWSHELLTELEGRAMCHAT_ID=您的聊天 ID
3. 添加到 TOOLS.md
将以下内容添加到您的 OpenClaw TOOLS.md，以便代理使用 ClawShell 执行 shell 命令：
markdown
Shell 访问
所有 shell 命令执行均使用 clawshell_bash。不要直接使用 bash。
ClawShell 将分析命令的风险，并要求人工批准危险操作。
可用工具：
- - clawshellbash(command, workingDir)——执行带有风险分析的 shell 命令
- clawshellstatus()——检查待处理的批准和最近的决策
- clawshell_logs(count)——查看最近的审计日志条目
配置
ClawShell 从环境变量（CLAWSHELL_*）读取配置，如果未设置则回退到 config.yaml。
| 变量 | 默认值 | 描述 |
|---|
| CLAWSHELLPUSHOVERUSER | — | Pushover 用户密钥 |
| CLAWSHELLPUSHOVERTOKEN |
— | Pushover 应用令牌 |
| CLAWSHELL
TELEGRAMBOT_TOKEN | — | Telegram 机器人令牌（替代方案） |
| CLAWSHELL
TELEGRAMCHAT_ID | — | Telegram 聊天 ID（替代方案） |
| CLAWSHELL
TIMEOUTSECONDS | 300 | 等待批准的超时秒数，超时后自动拒绝 |
| CLAWSHELL
LOGDIR | logs/ | JSONL 日志文件目录 |
| CLAWSHELL
LOGLEVEL | info | 日志详细程度：debug、info、warn、error |
| CLAWSHELL_BLOCKLIST | — | 额外阻止的命令列表，以逗号分隔 |
| CLAWSHELL_ALLOWLIST | — | 额外允许的命令列表，以逗号分隔 |
自定义规则也可以在 config.yaml 的 rules.blocklist 和 rules.allowlist 下定义，支持精确字符串、通配符或正则表达式模式。
局限性
- - 并非安全保证。 LLM 可以对命令进行编码、拆分或混淆以绕过模式匹配。
- 仅作为深度防御。 与 OpenClaw 的沙盒模式一起使用，而非替代品。
- 批准延迟。 高风险命令会阻塞执行，直到您响应或超时到期。
始终要求您的 AI 扫描任何技能或软件的安全风险。
