Skip to main content

WebClaw Web Client

WebClaw is a community-built, browser-based chat interface for OpenClaw. It connects to your Gateway over WebSockets and provides a clean, modern UI for interacting with your agent from any device with a browser.

info

WebClaw is currently in beta (637 stars, 5 contributors). It is a third-party project and not maintained by the OpenClaw team. The repository was last updated March 17, 2026.

Why a Browser Frontend?​

OpenClaw ships with a built-in WebChat UI accessible at http://localhost:18789/chat, but community frontends offer a richer experience:

FeatureBuilt-in WebChatWebClawPinchChat
FrameworkVanilla JSReact 19 / TanStack RouterReact 19 / Vite 7
CustomizationLimitedFull source accessFull source access
Mobile UXBasicResponsive-firstPWA with offline support
ThemingDark onlyConfigurableDark / Light / OLED Black + 6 accents
Multi-sessionNoNoSplit-view monitoring
i18nNoNoEnglish, French
Install methodBuilt-innpx webclawDocker or git clone
LicenseApache 2.0MITMIT
StatusStableBetaStable (119 releases)

If the built-in WebChat works for you, there's no need to switch. These frontends are for users who want a more customizable or polished web experience.

Quick Start​

The fastest way to get WebClaw running:

npx webclaw

This downloads the CLI package and starts WebClaw locally. For more control, clone and configure manually — see Installation below.

Prerequisites​

  • A running OpenClaw Gateway (default: ws://localhost:18789)
  • Node.js >= 20
  • pnpm (preferred) or npm

Installation​

Method 1: npx (Quickest)​

npx webclaw

Method 2: Clone and Build​

git clone https://github.com/ibelick/webclaw.git
cd webclaw

# Install dependencies
pnpm install

# Development mode (with hot reload)
pnpm dev

# Production build
pnpm build
pnpm start

The WebClaw UI will be available at http://localhost:3000 by default.

Method 3: Docker​

Community Docker images are available:

docker run -d \
  --name webclaw \
  -p 3000:3000 \
  -e OPENCLAW_GATEWAY_URL=ws://host.docker.internal:18789 \
  -e OPENCLAW_GATEWAY_TOKEN=your-token-here \
  land007/webclaw:latest
tip

Use host.docker.internal (Docker Desktop) or 172.17.0.1 (Linux) to reach the Gateway running on the host.

Configuration​

Create the environment file at apps/webclaw/.env.local:

apps/webclaw/.env.local
OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789
OPENCLAW_GATEWAY_TOKEN=your-gateway-token-here

The token must match your OpenClaw Gateway authentication settings. You can find or set your token in ~/.openclaw/openclaw.json:

~/.openclaw/openclaw.json
{
  "gateway": {
    "auth": {
      "mode": "shared-secret",
      "token": "your-gateway-token-here"
    }
  }
}
tip

If you use password authentication instead of token auth, set OPENCLAW_GATEWAY_PASSWORD instead of OPENCLAW_GATEWAY_TOKEN.

Environment Variables​

VariableRequiredDefaultDescription
OPENCLAW_GATEWAY_URLYesws://127.0.0.1:18789WebSocket URL of your Gateway
OPENCLAW_GATEWAY_TOKENRecommended—Authentication token
OPENCLAW_GATEWAY_PASSWORDAlternative—Password auth (if not using token)
caution

The WebClaw repository's .env.example may still use the legacy CLAWDBOT_GATEWAY_* variable names. OpenClaw only reads OPENCLAW_* environment variables — the legacy CLAWDBOT_* and MOLTBOT_* prefixes are silently ignored. Always use the OPENCLAW_* prefix.

Tech Stack​

WebClaw is a TypeScript monorepo (93.6% TypeScript) managed with pnpm 9.15.4:

webclaw-monorepo/
├── apps/
│   ├── webclaw/        # Main web client (React 19 + TanStack Router)
│   └── landing/        # Marketing site (webclaw.dev)
├── packages/
│   └── webclaw/        # npm-publishable CLI (npx webclaw)
├── pnpm-workspace.yaml
└── package.json

Core Dependencies​

LibraryVersionPurpose
React^19.2.0UI framework
TanStack Router^1.132.0Client-side routing
Tailwind CSS^4.1.18Utility-first styling
TypeScript—Type safety
info

WebClaw uses TanStack Router, not Next.js. It's a single-page application with client-side routing, not a server-rendered framework.

Architecture​

WebClaw communicates with OpenClaw through the same WebSocket control plane that all clients use:

WebClaw is just another client — it doesn't replace or modify the Gateway.

WebSocket Protocol​

WebClaw uses the Gateway's standard wire protocol with three frame types:

FrameDirectionStructurePurpose
RequestClient to Gateway{type: "req", id, method, params}Send messages, invoke tools
ResponseGateway to Client{type: "res", id, ok, payload}RPC replies
EventGateway to Client{type: "event", event, payload}Streaming tokens, tool calls

Streaming and Optimistic Updates​

WebClaw implements streaming chat with an optimistic update pattern:

  1. User sends a message
  2. WebClaw writes an optimistic entry into the history cache immediately (no round-trip delay)
  3. The Gateway streams response events back in real-time
  4. When server history arrives, WebClaw reconciles optimistic entries using clientId matching or near-timestamp matching (10-second window)

This is implemented across use-chat-history.ts, chat-queries.ts, and use-chat-pending-send.ts.

Production Deployment​

Behind a Reverse Proxy​

For remote access, run WebClaw behind Nginx or Caddy with TLS:

nginx.conf
server {
    listen 443 ssl;
    server_name webclaw.example.com;

    ssl_certificate     /etc/letsencrypt/live/webclaw.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/webclaw.example.com/privkey.pem;

    # WebClaw frontend
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Gateway WebSocket (proxied through same domain)
    location /ws {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}
webclaw.example.com {
    reverse_proxy /ws localhost:18789
    reverse_proxy localhost:3000
}

Cloudflare Tunnel​

Expose WebClaw without opening ports:

cloudflared tunnel --url http://localhost:3000
warning

If using Cloudflare Tunnel, you still need to configure Gateway authentication. The tunnel provides transport encryption but not application-layer auth.

SSH Tunnel (Simple Remote Access)​

For quick access without a full reverse proxy setup:

# Forward both WebClaw and Gateway ports
ssh -L 3000:localhost:3000 -L 18789:localhost:18789 user@your-server

Then open http://localhost:3000 in your browser.

Security​

Authentication Is Required​

The Gateway enforces authentication by default (fail-closed model since v2026.2.19, after CVE-2026-25253). WebClaw authenticates using the token or password in your environment variables.

Auth ModeHow It WorksConfig
Token (recommended)Shared secret compared at handshakeOPENCLAW_GATEWAY_TOKEN
PasswordPassword-based authOPENCLAW_GATEWAY_PASSWORD
Trusted proxyGateway trusts X-Forwarded-* headersNginx/Caddy config

TLS Requirements​

The Gateway enforces TLS for non-local connections:

Connection SourcePlaintext ws://Encrypted wss://
Loopback (127.0.0.1)AllowedAllowed
Private network (192.168.x.x, 10.x.x.x)AllowedAllowed
.local hostnamesAllowedAllowed
Tailnet (*.ts.net)AllowedAllowed
Everything elseBlockedRequired

CORS​

When WebClaw runs on a different origin than the Gateway (e.g., localhost:3000 vs. localhost:18789), the Gateway handles CORS automatically for loopback connections. For non-loopback deployments, configure allowed origins:

~/.openclaw/openclaw.json
{
  "gateway": {
    "cors": {
      "origins": ["https://webclaw.example.com"]
    }
  }
}

Best Practices​

  • Never expose WebClaw to the public internet without Gateway authentication enabled
  • Use token auth rather than leaving the Gateway open — WebClaw has the same access as any Gateway client
  • Keep tokens in .env.local files (never committed to git) — the .env.example notes "Keep secrets here (never in the browser)"
  • For remote access, always use a reverse proxy with TLS or an SSH tunnel
  • Review the Security Hardening guide for full Gateway lockdown

PinchChat (Alternative Frontend)​

PinchChat is a more mature alternative browser frontend with 182 stars and 119 releases (latest v1.71.3):

FeatureWebClawPinchChat
Stars637182
Releases0 (beta)119 (stable)
Multi-sessionSingle chatSplit-view monitoring
ThemesConfigurableDark / Light / OLED Black + 6 accents
PWANoYes (installable, offline)
i18nNoEnglish, French
Tool visualizationBasicColored badges per tool type
Message searchNoCtrl+F search
ExportNoMarkdown export
Session managementBasicDrag-and-drop reordering

Installing PinchChat​

git clone https://github.com/MarlBurroW/pinchchat.git
cd pinchchat
docker compose up -d

PinchChat connects to the same Gateway WebSocket and uses the same JSON-framed protocol. Choose PinchChat if you need multi-session monitoring, PWA support, or a more polished out-of-the-box experience. Choose WebClaw if you want a lightweight SPA to customize and build upon.

Customization​

Theming​

WebClaw uses Tailwind CSS v4, so you can customize the look by editing the Tailwind configuration in apps/webclaw/:

apps/webclaw/src/styles/globals.css
@theme {
  --color-primary: #your-brand-color;
  --color-background: #1a1a2e;
  --color-surface: #16213e;
}

Building a Custom Frontend​

Since WebClaw is MIT-licensed with full source access, you can fork it as a starting point for your own UI. The monorepo structure makes it easy to modify the client without touching the CLI package:

# Fork and clone
git clone https://github.com/YOUR-USERNAME/webclaw.git
cd webclaw

# Work only on the web client
cd apps/webclaw
pnpm dev

Key files to customize:

FilePurpose
apps/webclaw/src/routes/Page routes (TanStack Router)
apps/webclaw/src/components/UI components
apps/webclaw/src/hooks/use-chat-history.tsChat history and streaming
apps/webclaw/src/hooks/use-chat-pending-send.tsOptimistic message sending
apps/webclaw/src/lib/chat-queries.tsGateway API integration

Troubleshooting​

Connection Issues​

ProblemCauseFix
Connection refusedGateway not runningRun openclaw status, check URL in .env.local
Authentication failedToken mismatchVerify token matches ~/.openclaw/openclaw.json
CORS errorsDifferent origin, non-loopbackConfigure gateway.cors.origins or use reverse proxy
WebSocket closes immediatelyProtocol mismatchEnsure Gateway is updated to latest version
Blank screen after buildMissing env varsCheck .env.local exists with correct variables

Environment Variable Issues​

# Verify Gateway is running and accessible
openclaw status

# Test WebSocket connection directly
wscat -c ws://127.0.0.1:18789

# Check Gateway auth settings
cat ~/.openclaw/openclaw.json | grep -A 5 'auth'
caution

If you cloned WebClaw before March 2026, your .env.local may use the legacy CLAWDBOT_GATEWAY_* variable names. Rename them to OPENCLAW_GATEWAY_* — the Gateway silently ignores the old prefix.

Performance​

ProblemCauseFix
Slow with long conversationsLarge history cacheClear browser cache, start new session
High memory usageAccumulated WebSocket eventsRefresh the page periodically
Laggy typingHeavy re-rendersUse production build (pnpm build && pnpm start)

Project Info​

FieldValue
Repositorygithub.com/ibelick/webclaw
Websitewebclaw.dev
LicenseMIT
LanguageTypeScript (93.6%)
StatusBeta
Stars637
Contributors5

See Also​