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.

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"
      }
    ],
    "expires_in_seconds": 1800,
    "callback_url": "${OPENCLAW_HOOKS_URL}/clawvisor/callback?session=<session_key>"
  }'

• purpose — shown to the user during approval and used by intent verification to ensure requests stay consistent with declared intent. Be specific.
• expected_use — per-action description of how you'll use it. Shown during approval. More specific is better.
• auto_execute — true runs in-scope requests immediately; false still requires per-request approval (use for destructive actions like send_message).
• expires_in_seconds — omit and set "lifetime": "standing" for a task that persists until the user revokes it.

Scope expansion — if you need an action not in the original scope: