Clawvisor
API gateway for purpose-based authorization for AI agents. Human approval for tasks, AI-native enforcement for agents.
Install / Use
/learn @clawvisor/ClawvisorREADME
[!WARNING] Use at your own risk. Clawvisor is experimental software under active development. It has not been audited for security. LLMs are inherently nondeterministic — we make no guarantees that policies or safety checks will behave as expected in every case. Do not use Clawvisor as your sole safeguard for sensitive data or critical systems.
AI agents are getting good at doing things. The problem is letting them — safely. Give an agent your Gmail credentials and it can read, send, and delete anything. Refuse, and it can't help you at all.
Clawvisor sits in the middle. Agents never hold credentials. Instead, they declare tasks describing what they need to do, the user approves the scope, and Clawvisor handles credential injection, execution, and audit logging for every request under that task.
The typical flow: a user asks their agent to triage their inbox. The agent creates a Clawvisor task declaring what it needs — read emails, but ask before sending. The user approves the scope once, and the agent makes as many requests as it needs within that scope without further interruption. Actions outside the scope go to the user for per-request approval. Restrictions can hard-block specific actions entirely.
Approve a purpose, not a permission. Clawvisor enforces it on every request.
Get Started
The setup guides in docs/ are written as agent-executable
instructions — give the right one to your AI agent and it will walk you
through setup and integration interactively.
Point your agent at docs/SETUP.md to get started. It covers two steps:
- Run Clawvisor — locally with Go, with Docker, or on a remote server
- Connect your agent — Claude Code, Claude Desktop (MCP), OpenClaw, or any HTTP agent
Or jump directly to the guide you need:
| Run Clawvisor | Connect your agent | |---|---| | Local — Go + SQLite, no Docker | Claude Code | | Docker — Docker Compose locally | Claude Desktop (MCP) | | Cloud — remote server or container platform | OpenClaw | | | Generic agent |
For the complete agent API protocol, see
skills/clawvisor/SKILL.md.
Manual quickstart
If you prefer to set up without an agent:
git clone https://github.com/clawvisor/clawvisor.git
cd clawvisor
make setup # interactive config wizard
make run # start server (SQLite, magic link auth)
make tui # terminal dashboard (separate terminal)
make setup generates config.yaml and a vault.key (database, Google OAuth, intent verification). make run starts the server, creates an admin@local user, and opens the dashboard via a magic link. make tui auto-authenticates using the local session file.
Configuration
Clawvisor loads config.yaml from the working directory (override with CONFIG_FILE env var). Most settings have env var overrides:
| Setting | Env var | Notes |
|---|---|---|
| Database driver | DATABASE_DRIVER | postgres or sqlite (auto-selects sqlite locally) |
| Postgres URL | DATABASE_URL | Required for postgres driver |
| JWT secret | JWT_SECRET | Auto-generated locally; required in prod |
| Vault key | VAULT_KEY | Base64-encoded 32-byte key; alternative to vault.key file |
| Auth mode | AUTH_MODE | magic_link (default locally) or password |
| Allowed emails | ALLOWED_EMAILS | Comma-separated emails allowed to register |
| Google OAuth | GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | Needed for Google services |
| Public URL | PUBLIC_URL | Used in Telegram notification links |
| LLM config | CLAWVISOR_LLM_* | Shared provider, model, API key for all LLM features |
| Intent verification | CLAWVISOR_LLM_VERIFICATION_* | Optional LLM check that request params match task purpose |
| Task risk assessment | CLAWVISOR_LLM_TASK_RISK_* | Optional LLM risk assessment when tasks are created |
| Chain context | CLAWVISOR_LLM_CHAIN_CONTEXT_* | Optional LLM extraction of facts from results for multi-step verification |
| Approval timeout | APPROVAL_TIMEOUT | Seconds before pending approvals expire (default 300) |
| Rate limits | RATE_LIMIT_* | Per-agent gateway, per-user OAuth, policy API, and review limits |
| MCP timeout | MCP_APPROVAL_TIMEOUT | Seconds MCP blocks waiting for approval (default 240) |
| Telemetry | TELEMETRY_ENABLED | Opt-in anonymous usage telemetry |
See config.example.yaml for the full configuration reference.
How It Works
Agent Clawvisor External API
│ │ │
├── POST /api/tasks ─────►│ (declare scope, wait for user) │
│◄── task approved ───────┤ │
│ │ │
├── POST /api/gateway ───►│ │
│ (with task_id) ├─ Check restrictions │
│ ├─ Check task scope │
│ ├─ Auto-execute or queue approval │
│ │ │
│ │ ┌─ On execute: ──────────────┐ │
│ │ │ Inject credentials │ │
│ │ │ Call adapter ────────────────►│
│ │ │ Format response ◄────────────┤
│ │ │ Intent verification │ │
│ │ │ Audit log │ │
│ │ └────────────────────────────┘ │
│◄── Response ────────────┤ │
Every gateway request passes through three authorization layers, checked in order:
- Restrictions — hard blocks you configure on specific service/action pairs. If a restriction matches, the request is denied immediately. Use these for actions you never want any agent to take (e.g. "no agent can delete calendar events").
- Task scopes — the primary mechanism. When an agent needs to do something, it creates a task declaring the purpose and which service/action pairs it needs. You review and approve the scope once. After that, requests under that task execute without further interruption — you approved the purpose, not each individual call. Tasks can be session-scoped (expire after a TTL) or standing (persist until you revoke them).
- Per-request approval — the fallback. Any request that isn't covered by a task scope goes to the approval queue, and you're notified via the dashboard, Telegram, or push notification to your phone. This is the default for actions the agent didn't declare upfront, or for task actions marked
auto_execute: false(e.g. sending emails).
When a task is created, Clawvisor can optionally run an LLM-powered risk assessment that evaluates the scope breadth, purpose-scope coherence, and internal consistency of the task. The assessment produces a risk level (low, medium, high, critical) shown in the dashboard to help inform your approval decision. High and critical risk tasks require a confirmation step before approval.
For multi-step tasks, chain context verification tracks structural facts (IDs, email addresses, phone numbers) extracted from adapter results and feeds them into subsequent verification prompts. This prevents a compromised agent from reading an inbox and then targeting an entity not present in the results. Chain context is activated by passing a consistent session_id across related gateway requests.
All three LLM subsystems (intent verification, chain context extraction, and task risk assessment) are covered by eval suites totaling 249 cases. See docs/eval-results.md for accuracy breakdowns and failure analysis.
Supported Services
| Service ID | Service | Actions |
|---|---|---|
| google.gmail | Gmail | list_messages, get_message, send_message |
| google.calendar | Google Calendar | list_events, get_event, create_event, update_event, delete_event, list_calendars |
| google.drive | Google Drive | list_files, get_file, create_file, update_file, search_files |
| google.contacts | Google Contacts | list_contacts, get_contact, search_contacts |
| github | GitHub | list_issues, get_issue, create_issue, comment_issue, list_prs, get_pr, list_repos, search_code |
| slack | Slack | list_channels, get_channel, list_messages, send_message, search_messages, list_users |
| notion | Notion | search, get_page, create_page, update_page, query_database, list_databases |
| linear | Linear | list_issues, get_issue, create_issue, update_issue, add_comment, list_teams, list_projects, search_issues |
| stripe | Stripe | list_customers, get_customer, list_charges, get_charge, list_subscriptions, get_subscription, create_refund, get_balance |
| twilio | Twilio | send_sms, send_whatsapp, list_messages, get_message |
| apple.imessage | iMessage | search_messages, list_threads, get_thread, send_message |
Google services share a single OAuth connection — activating o
