137 lines
3.6 KiB
Markdown
137 lines
3.6 KiB
Markdown
---
|
|
name: hook-management
|
|
description: Implement lifecycle hooks (PreToolUse/PostToolUse) using OpenClaw's existing tools and config
|
|
---
|
|
|
|
## When to use
|
|
Use when you need to:
|
|
- Add validation before dangerous tools (exec, write, edit)
|
|
- Audit/log all tool usage
|
|
- Enforce custom security policies
|
|
- Track costs/metrics around tool calls
|
|
- Transform tool outputs before they reach the model
|
|
|
|
**Note**: OpenClaw does not have native PreToolUse/PostToolUse hooks. This skill shows you how to achieve similar effects using available mechanisms.
|
|
|
|
## Approach 1: Permission Mode + Rules (Built-in)
|
|
|
|
OpenClaw already has a permission system. Use it:
|
|
|
|
### Set permission mode
|
|
```bash
|
|
# Ask before every write/exec (default safe)
|
|
gateway config set tools.exec.security full
|
|
|
|
# Or use plan mode to block all writes
|
|
# (requires implementing plan_mode toggle)
|
|
```
|
|
|
|
### Path-level rules in config
|
|
Edit `openclaw.json`:
|
|
```json
|
|
{
|
|
"permissions": {
|
|
"path_rules": [
|
|
{ "pattern": "**/secrets/**", "allow": false },
|
|
{ "pattern": "**/*.key", "allow": false }
|
|
],
|
|
"denied_commands": ["rm -rf /", "DROP TABLE *", "format c:"]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Approach 2: Wrapper Scripts (Shell Proxy)
|
|
|
|
Create wrapper scripts that add validation/logging:
|
|
|
|
### Example: Safe exec wrapper
|
|
```bash
|
|
# ~/.openclaw/wrappers/exec-safe
|
|
#!/bin/bash
|
|
# PreToolUse validation
|
|
CMD="$1"
|
|
if echo "$CMD" | grep -qE "(rm -rf|dd if=|mkfs)"; then
|
|
echo "ERROR: Dangerous command blocked: $CMD" >&2
|
|
exit 1
|
|
fi
|
|
|
|
# Audit log
|
|
echo "$(date -Iseconds) USER EXEC: $CMD" >> ~/.openclaw/logs/exec-audit.log
|
|
|
|
# Execute
|
|
exec /usr/lib/openclaw/tools/exec.real "$@"
|
|
```
|
|
|
|
Then configure OpenClaw to use the wrapper instead of the built-in exec tool.
|
|
|
|
## Approach 3: Plugin Interception (If Plugin System Supports)
|
|
|
|
If OpenClaw plugins can intercept tool calls:
|
|
|
|
```json
|
|
{
|
|
"name": "audit-plugin",
|
|
"version": "1.0.0",
|
|
"preToolUse": {
|
|
"command": "audit-log",
|
|
"priority": 1000
|
|
}
|
|
}
|
|
```
|
|
|
|
**Check plugin docs** to see if `preToolUse`/`postToolUse` are supported.
|
|
|
|
## Approach 4: Custom Agent with Restricted Tools
|
|
|
|
Spawn a subagent with limited tool set:
|
|
|
|
```bash
|
|
clawteam spawn tmux openclaw \
|
|
--agent-type restricted \
|
|
--tools "read,write,web_search" # no exec, no dangerous tools
|
|
```
|
|
|
|
## Common Use Cases & Solutions
|
|
|
|
### Audit logging all tool calls
|
|
- **Solution**: Wrapper scripts that log to file
|
|
- Or use OpenClaw's built-in logging if available
|
|
|
|
### Block dangerous commands
|
|
- **Solution**: `denied_commands` in config
|
|
- Or wrapper validation
|
|
|
|
### Rate limiting
|
|
- **Solution**: Track in session memory, check before allowing
|
|
- No built-in — implement in custom plugin/agent
|
|
|
|
### Cost tracking
|
|
- **Solution**: Parse logs, aggregate token usage
|
|
- OpenClaw may already log token counts
|
|
|
|
### Input sanitization
|
|
- **Solution**: Pre-process arguments in wrapper
|
|
- Or validate in agent logic before calling tool
|
|
|
|
## Verification Checklist
|
|
- [ ] Hooks/validation are actually triggered
|
|
- [ ] Dangerous operations are blocked as intended
|
|
- [ ] Audit logs capture necessary details (who, what, when)
|
|
- [ ] No performance degradation (wrappers are fast)
|
|
- [ ] Rules don't interfere with normal operations
|
|
- [ ] Fail open/closed appropriately (security vs availability)
|
|
|
|
## Limitations
|
|
|
|
- No native hook priority system — order depends on wrapper chain
|
|
- No automatic hook discovery — manual registration needed
|
|
- Wrapper approach requires maintaining extra scripts
|
|
- Not as elegant as built-in hook system
|
|
|
|
## Future: Request Native Hooks
|
|
|
|
If hooks are critical, consider:
|
|
- Feature request to OpenClaw maintainers
|
|
- Contributing a hook system implementation
|
|
- Using OpenHarness as an alternative (has native hooks)
|