Documentation

Overview — How ClawGate Works

ClawGate adds human-in-the-loop approval to AI agent workflows using passkeys (Face ID / Touch ID). When your agent tries to do something sensitive — delete files, send emails, publish packages — ClawGate intercepts the action, sends a push notification to your phone, and waits for your biometric approval before proceeding.

ClawGate follows the delegation pattern: your agent requests approval for specific actions, you approve with your passkey, and the agent receives a scoped, time-limited token. The agent never has access to your passkey — same model as OAuth 2.0.

End-to-End Flow

Here's exactly what happens when your agent hits a sensitive command:

Quick Start

1. Download the ClawGate iOS App

Get ClawGate from the App Store. Create your account with email, then register your passkey — just one Face ID scan. Your passkey syncs via iCloud Keychain across all your Apple devices.

2. Generate an API Key

In the app: Settings → API Keys → Create New. Name it (e.g. "My Agent") and copy the key. It looks like ag_xDWZ7V_OamQEDz-uBk5t4LeM6bZxBHXi. You won't see it again, but you can always generate a new one.

3. Install the OpenClaw Plugin

# Via OpenClaw CLI (recommended)
openclaw plugins install clawgate

# Or manually
mkdir -p ~/.openclaw/extensions/clawgate
cd ~/.openclaw/extensions/clawgate
npm install clawgate

4. Add to Your OpenClaw Config

Edit ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "clawgate": {
        "enabled": true,
        "config": {
          "apiKey": "ag_YOUR_KEY_HERE",
          "agentId": "my-agent"
        }
      }
    }
  }
}

The server defaults to https://api.clawgate.ai. Only change it if you're self-hosting.

5. Restart and Test

openclaw gateway restart
openclaw clawgate status   # verify connection
openclaw clawgate test     # send test approval to your phone

Approve the test notification with Face ID. Then try asking your agent to delete a test file — you'll see ClawGate intercept it in real time.

Configuring Patterns

Patterns determine which tool calls require approval. They use regular expressions (case-insensitive) and can be scoped to specific tools.

Default Patterns

ClawGate ships with sensible defaults that catch dangerous operations:

Custom Patterns

Override or extend patterns in your config:

"config": {
  "apiKey": "ag_YOUR_KEY",
  "agentId": "my-agent",
  "patterns": [
    { "match": "rm\\s", "description": "Delete files", "tools": ["exec"] },
    { "match": "stripe.*charge", "description": "Stripe charge", "tools": ["exec"] },
    { "match": "curl.*POST", "description": "HTTP POST", "tools": ["exec"] },
    { "match": "send.*email", "description": "Send email" }
  ]
}

Always-Approve Tools

Require approval for every call to a specific tool, regardless of pattern:

"alwaysRequireApproval": ["message", "browser"]

All Configuration Options

CLI Commands

openclaw clawgate status

Shows server connection, agent ID, pattern count, fail-closed mode.

openclaw clawgate test

Sends a test approval request to your phone. Use to verify Face ID flow works end-to-end.

openclaw clawgate patterns

Lists all active patterns with their regex and tool scope.

Security Model

Why not just use passwords or OTPs?

API Reference

Use the API to integrate ClawGate with any agent framework — not just OpenClaw. Full reference: API.md on GitHub

Request Approval

POST https://api.clawgate.ai/api/v1/approval/request
Authorization: Bearer ag_your_api_key
Content-Type: application/json

{
  "agentId": "my-agent",
  "action": "send-email",
  "description": "Send quarterly report to investors@company.com",
  "timeoutSeconds": 120,
  "scopes": ["email:send"]
}

// Response:
{
  "requestId": "req_abc123",
  "status": "pending",
  "expiresAt": "2026-02-11T18:05:00Z"
}

Poll for Status

GET https://api.clawgate.ai/api/v1/approval/status/{requestId}
Authorization: Bearer ag_your_api_key

// Response (approved):
{
  "requestId": "req_abc123",
  "status": "APPROVED",
  "token": "eyJhbGciOiJFUzI1NiIs...",
  "tokenExpiresAt": "2026-02-11T18:08:00Z"
}

// Possible statuses: PENDING, APPROVED, DENIED, EXPIRED

Integration Example (Python)

import requests, time

API_KEY = "ag_your_key"
BASE = "https://api.clawgate.ai/api/v1"

def request_approval(action, description):
    r = requests.post(f"{BASE}/approval/request",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"agentId": "my-agent", "action": action, "description": description}
    )
    req_id = r.json()["requestId"]
    
    for _ in range(60):  # poll for 2 minutes
        s = requests.get(f"{BASE}/approval/status/{req_id}",
            headers={"Authorization": f"Bearer {API_KEY}"}
        ).json()
        if s["status"] == "APPROVED": return True
        if s["status"] in ("DENIED", "EXPIRED"): return False
        time.sleep(2)
    return False

if request_approval("send-email", "Send report to investors@co.com"):
    send_the_email()
else:
    print("Denied by user")

Self-Hosting

ClawGate is 100% open source. Self-host everything if you want full control.

Requirements

• Node.js 20+
• PostgreSQL 14+ (or SQLite for development)
• HTTPS domain (required for WebAuthn)
• Apple Developer account (for push notifications)

Docker

git clone https://github.com/AsteyaTech-com/clawgate-api.git
cd clawgate-api
docker-compose up -d

Manual

git clone https://github.com/AsteyaTech-com/clawgate-api.git
cd clawgate-api/server
npm install
cp .env.example .env    # edit with your DB, keys, etc.
npx prisma db push
npm run dev

Then set serverUrl in your plugin config to your server's URL. Full guide: GETTING_STARTED.md

Troubleshooting