clawvisor

# Clawvisor Skill

## Overview

Clawvisor sits between you and external APIs. You declare what you need to do,
the user approves the scope, and Clawvisor handles credential injection,
execution, and audit logging. You never hold API keys.

Authorization works in three layers — applied in order:

1. **Restrictions** — hard blocks set by the user. Matched requests are blocked immediately.
2. **Tasks** — pre-approved scopes you declare. In-scope actions with `auto_execute` run without per-request approval.
3. **Per-request approval** — the fallback for anything without a covering task.

At the start of each session, fetch your service catalog to see what's available:

```
GET $CLAWVISOR_URL/api/skill/catalog
Authorization: Bearer $CLAWVISOR_AGENT_TOKEN
```

---

## Typical Flow

1. Fetch the catalog — confirm the service is active and the action isn't restricted
2. Create a task declaring your purpose and the actions you need
3. Tell the user to approve it; wait for the callback (or poll)
4. Make gateway requests under the task — in-scope actions execute automatically
5. Mark the task complete when done

For one-off actions, skip the task — the request goes to per-request approval instead.

---

## Task Creation

Declare a task with a `purpose`, a list of `authorized_actions`, and a TTL.
All tasks start as `pending_approval`.

```bash
curl -s -X POST "$CLAWVISOR_URL/api/tasks" \
  -H "Authorization: Bearer $CLAWVISOR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "Review last 30 iMessage threads and classify reply status",
    "authorized_actions": [
      {
        "service": "apple.imessage",
        "action": "list_threads",
        "auto_execute": true,
        "expected_use": "List recent threads to find ones needing replies"
      },
      {
        "service": "apple.imessage",
        "action": "get_thread",
        "auto_execute": true,
        "expected_use": "Read individual threads to classify reply status"
      }
    ],
    "...

# Clawvisor — OpenClaw Skill

Route tool requests through [Clawvisor](https://github.com/clawvisor/clawvisor)
for policy enforcement, credential vaulting, and human approval flows.

The agent never holds API keys. Every action is logged and auditable. The user
controls what is allowed via dashboard policies.

## Supported services

- **Google Gmail** — list, read, send, draft, delete
- **Google Calendar** — list, get, create, update, delete events
- **Google Drive** — list, get, create, update, delete files
- **Google Contacts** — list, get, create, update contacts
- **GitHub** — issues, pull requests, repositories

## Quick start

**1. Run Clawvisor**

```bash
# Local (SQLite, no Docker)
git clone https://github.com/clawvisor/clawvisor
cd clawvisor-gatekeeper
JWT_SECRET=your-secret make run-sqlite
```

Or deploy to Cloud Run — see `deploy/` in the repository.

**2. Set up your account**

Open http://localhost:8080, register, then:
- **Services** → connect Google (covers Gmail, Calendar, Drive, Contacts) and/or GitHub
- **Agents** → create an agent, copy the token
- **Policies** → optionally add policies to control what the agent can do

**3. Install the skill**

```bash
clawhub install clawvisor
```

**4. Configure credentials**

```bash
openclaw credentials set CLAWVISOR_URL http://localhost:8080
openclaw credentials set CLAWVISOR_AGENT_TOKEN <token from dashboard>
```

**5. Use it**

Ask your agent to send an email, check your calendar, create a GitHub issue —
it routes everything through Clawvisor automatically.

---

## How it works

```
Agent → POST /api/gateway/request → Policy check → Vault inject → Adapter → Result
                                          ↓
                                   Approval queue (if policy requires)
                                          ↓
                                   Telegram / Dashboard → Human approves/denies
                                          ↓
                                   Callback to agent session
```...