Architecture

How It Works

Constclaw follows a two-layer architecture: a thin browser extension client and a local AI gateway. No data leaves your machine unless you explicitly configure a remote provider.

High-level overview

The extension captures text selections, sends them over WebSocket to your local OpenClaw gateway, and renders the AI response in Chrome's side panel. The gateway handles provider routing, authentication, and model orchestration.

  ┌─────────────────────────────────────────────────────────────┐
  │                    Chrome Browser                            │
  │                                                              │
  │   ┌──────────────┐    chrome.runtime    ┌────────────────┐  │
  │   │  content.js   │───────────────────▶│  background.js  │  │
  │   │  (selection)   │                     │ (service worker)│  │
  │   └──────┬─────────┘                     └────────┬───────┘  │
  │          │                                        │          │
  │          │ chrome.runtime.sendMessage              │          │
  │          ▼                                        ▼          │
  │   ┌─────────────────────────────────────────────────────┐   │
  │   │               sidepanel.js                           │   │
  │   │  • Renders selected text                             │   │
  │   │  • Mode selector (5 modes)                           │   │
  │   │  • WebSocket client → gateway                        │   │
  │   │  • Query history (chrome.storage.local)              │   │
  │   └─────────────────────┬───────────────────────────────┘   │
  │                         │                                    │
  └─────────────────────────┼────────────────────────────────────┘
                            │  WebSocket (ws://127.0.0.1:18789)
                            ▼
              ┌──────────────────────────┐
              │     OpenClaw Gateway      │
              │                           │
              │  • Protocol handshake     │
              │  • Auth / token check     │
              │  • Provider routing       │
              │  • Rate limiting          │
              └────────────┬──────────────┘
                           │  HTTPS
                           ▼
              ┌──────────────────────────┐
              │     AI Model Provider     │
              │                           │
              │  Anthropic (Claude)       │
              │  OpenAI (GPT)             │
              │  Local (Ollama, etc.)     │
              └──────────────────────────┘

Extension components

Constclaw is a Manifest V3 Chrome extension with three main scripts:

content.js Content Script

Injected into every webpage. Listens for mouseup events, detects text selection, and shows the floating "Ask Constclaw" button. Sends the selected text to the side panel via chrome.runtime.sendMessage.

background.js Service Worker

Registers the context menu item ("Ask Constclaw"). Relays messages between content scripts and the side panel. Manages side panel lifecycle with chrome.sidePanel.open().

sidepanel.js Side Panel

The main UI controller. Manages the WebSocket connection to OpenClaw, implements the gateway protocol, renders AI responses, and stores query history in chrome.storage.local.

Data flow

Here's the step-by-step flow from text selection to AI response:

User selects text on any webpage

content.js detects selection, shows floating button

User clicks button → triggers chrome.runtime.sendMessage

background.js opens side panel, relays selected text

sidepanel.js receives text, displays it in the panel

User selects analysis mode and clicks Analyze

sidepanel.js opens WebSocket to ws://127.0.0.1:18789

Gateway handshake: challenge → connect → hello-ok

Extension sends formatted prompt via "send" method

Gateway routes to AI provider, streams response back

sidepanel.js renders response, saves to history

Prompt construction

Each analysis mode uses a purpose-built system prompt. The extension wraps the user's selected text with mode-specific instructions before sending it to the gateway:

Prompt template (simplified)js

"kw">class="c">// Mode: "explain"
"kw">const prompt = [
  "You are a knowledgeable assistant.",
  "The user has selected the following text ">from a webpage:",
  "",
  `"${selectedText}"`,
  "",
  "Please explain this text in clear, accessible language.",
  "Define any key terms. Provide context where helpful.",
  `Respond in ${responseLanguage}.`,
].join("\n");

"kw">class="c">// Sent to gateway as:
"kw">class="c">// { method: "send", params: { message: prompt } }

Security model

🔒

Local-only by default

The extension connects to 127.0.0.1 only. No external requests unless you configure a remote gateway.

🔑

Optional token auth

Set OPENCLAW_GATEWAY_TOKEN to require authentication on the gateway connection.

💾

Local storage only

Query history uses chrome.storage.local — never synced, never uploaded.

🛡️

No API keys in extension

AI provider keys live in the OpenClaw config, not in the extension. The extension has no access to them.

← Quick Start Gateway Protocol →