open-claw-team/.openclaw/workspace/skills/hook-management/SKILL.md

name, description

name	description
hook-management	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

# 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:

{
  "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

# ~/.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:

{
  "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:

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)