ClawVault: a proxy and hooks that watch what your coding agent touches

Enforcement happens where traffic leaves the machine

ClawVault's central architectural decision is that an agent cannot be trusted at the point where it decides to act, only at the boundary where data moves. That is why the core is a transparent proxy gateway on port 8765 sitting between your agent and the model provider, with no change required to application logic. OpenAI and Anthropic traffic passes through it, gets inspected, and then either continues, is rewritten, or stops.

Layered on top are local agent hooks. The README names two integration surfaces explicitly: OpenClaw session and runtime protection, and Claude Code prompt and tool hooks. That pairing matters more than it first appears. A proxy can see requests leaving, but it cannot see a file the agent read locally, and it cannot stop a tool call that never touches a model endpoint. Hooks fill exactly that gap by inspecting prompts on submit and tool calls before execution.

The v0.3.0 release, published on 2026-08-06, is what made this end-to-end. It added Claude Code `UserPromptSubmit` support to scan prompts before they reach the model, plus `PreToolUse` runtime-action guarding, and it unified the two paths so the same detector, rule engine, guard modes, audit store and dashboard semantics apply to both. Before that release, the Claude Code side was a separate integration with its own behaviour.

Three guard modes decide what a detection actually does

The v0.1.0 release notes describe three guard modes, and this is the part of the design most security tooling gets wrong by only offering block or no block. `interactive` asks for permission before proceeding, `strict` blocks automatically, and `permissive` logs only. That gives you a way to start a policy in observation mode and tighten it once you know what it will do to your workflow.

The detections feeding those modes are specific. The feature list names sensitive data detection across API keys, passwords, PII and credit cards across more than 15 pattern types, prompt injection defence covering role hijacking, instruction override and data exfiltration, and a dangerous command guard that intercepts `rm -rf`, `curl|bash` and privilege escalation attempts. Auto-sanitization replaces secrets with placeholders on the way out and restores them on the response, which is the behaviour you want when a prompt legitimately needs to contain a key.

There is also a token budget control with daily and monthly limits and cost alerts. That is not a security feature, but it belongs in the same tool because an agent with unrestricted tool access and an unrestricted token budget is a reliability problem as much as a security one.

Installing as a skill, as a package, or on a remote server

Option 1 in the README installs from ClawHub as an OpenClaw skill, and it is the recommended path. The installer is versioned, which matters more than it sounds for something that sits in front of your traffic.

openclaw skills install tophant-clawvault-installer --version=0.2.9 --force

The installer exposes subcommands for the whole lifecycle rather than just setup. `install --mode quick` does a fast setup, `health` checks status, `generate-rule` creates security rules from a description, and `test --category all` runs the detection tests. That last one is the interesting part: a scanner you can ask to prove it still detects things is more trustworthy than one you have to take on faith.

Option 2 is a plain Python install for anyone not on OpenClaw.

pip install -e .

clawvault start

The CLI also has `clawvault scan` for scanning a piece of text directly, which is the fastest way to evaluate the detection engine, and `clawvault demo` for an interactive walkthrough. Deployment to a remote machine is one script that packs, uploads and installs, followed by `setup.sh` and `start.sh` on the server.

Packaging metadata that lags the release history

The `pyproject.toml` in the repository declares version 0.1.0 and classifies the project under Development Status as Alpha. The GitHub release history is further along: v0.1.0 in March 2026, v0.2.0 in June, and v0.3.0 in August, each with a substantive changelog. Both statements are in the repository at the same time and they are not reconciled.

The practical consequence is narrower than it looks. Nothing stops you installing the current release, since installation goes through the skill installer or `pip install -e .` rather than a version pin from the metadata. But if you write automation that reads the version out of the package metadata to decide compatibility, you will be reading 0.1.0 for a codebase whose latest tagged release is v0.3.0. Treat the tags as authoritative and the metadata as stale.

The dependency list is more informative about what this thing actually is. `mitmproxy` provides the interception layer, `fastapi` and `uvicorn` the API and dashboard, `aiosqlite` the audit store, `cryptography` the credential handling, `typer` the CLI, `croniter` the periodic notifications, and `inotify_simple` the file-side watching that backs the file access monitoring described in the README. Three console entry points are declared: the main `clawvault` CLI and two separate Claude Code hooks.

The audit trail and how it reaches you

The README's monitoring story is built around a vault metaphor, and the mechanics underneath it are more ordinary than the metaphor suggests. Events are collected at two places: the API gateway, which sees invocations, and the file side, which sees access and change tracking through the inotify-based watcher. Those events go into a SQLite store, which is what the dashboard reads.

Notifications are configurable in two ways. Periodic change notifications are a scheduled job, which is why `croniter` is a dependency, and real-time alerts are immediate. The intended delivery is an instant message, described as a notification that tells you who touched what in your vault and when, so an agent acting at 3am on a file you care about produces a message rather than a log line you will read in the morning.

The dashboard is a web UI with an audit log, a protection monitor, per-agent configuration and a quick-test facility. The v0.3.0 notes record that the audit log and protection monitor were updated to show persisted prompt and tool guard events, which is the piece that makes the two integration paths auditable in one place rather than in two. The `tests/` directory and top-level `test_dashboard.py` and `test_vaults_feature.py` suggest the dashboard behaviour is covered by tests.

Limits worth knowing before you trust it

The first limit is what any content filter has: pattern matching catches the shapes you anticipated. Fifteen-plus secret patterns and three named injection categories is a reasonable starting set, not a proof. The README's generative policy feature, where you describe a scenario in natural language and the system generates and executes policy rules, is the interesting answer to that, but generating a rule from a description is exactly the step where a miss becomes a silent gap.

The second limit is coverage of local action. Hooks and a proxy can see prompts, tool calls and model traffic. They cannot see an agent that opens a file through a path the watcher is not attached to, and file monitoring depends on inotify on Linux, which is a platform assumption the README does not discuss.

The third is operational risk, and here the project is better than average. `setup-claude-code.sh` runs a dry run by default and the release notes describe install, status and uninstall flows. There is a `scripts/uninstall.sh` documented as restoring original state. When you install something that intercepts every request your agent makes, the ability to get back to a clean machine without archaeology is a feature, and this one has it. The v0.3.0 notes also state that the Claude Code hooks fail closed when the local guard API is unavailable, which is the correct default for a security control: no guard running means no agent action, not unrestricted access.

Editorial conclusion

ClawVault is worth reading even if you never install it, because the proxy-plus-hooks design is the correct shape for agent security: enforce at the point where traffic actually leaves, and hook the two places a Claude Code session can be interrupted. The detection breadth is real, with named pattern classes for injection, credentials and dangerous commands rather than a vague claim of coverage. What should temper enthusiasm is the maturity signal: the package metadata still says version 0.1.0 and classifies the project as alpha, while GitHub releases have reached v0.3.0. The uninstall script and the dry-run default on the Claude Code hook installer are the details that suggest the author thought about leaving a system in a working state, which is more than most agent tooling does. A sensible first step is `clawvault scan` on text you already know contains a secret, since that tests the detector without granting a proxy any authority.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. tophant-ai/ClawVault on GitHub