BotsChat


A self-hosted chat interface for OpenClaw AI agents.

BotsChat gives you a modern, Slack-like web UI to interact with your OpenClaw agents — organize conversations into Channels, schedule Background Tasks, and monitor Job executions. Everything runs on your own infrastructure; your API keys and data never leave your machine.

Key Features

$3

BotsChat organizes your conversations through a Channel → Session → Thread three-layer hierarchy, keeping complex agent interactions clean and navigable:

- Channel — one workspace per agent (e.g. "#General", "#BotsChat"), listed in the left sidebar.
- Session — multiple session tabs within each channel, so you can run parallel conversations without losing context.
- Thread — branch off from any message to start a focused sub-conversation in the right panel, without cluttering the main chat.

You can also switch models on the fly from the top-right selector, and trigger common Skills (like /model, /help, /skills) directly from the command bar at the bottom of the chat.

!Conversation Structure — Channel, Session, and Thread

$3

Instead of plain text walls, BotsChat renders agent responses as interactive UI elements — clickable buttons, radio groups, and selection cards. When an agent asks "What kind of project do you want to create?", you see styled option buttons you can click, not just text to read and retype. This makes multi-step workflows feel like a guided wizard rather than a raw chat.

!Interactive UI — Agent responses rendered as buttons and selection cards

$3

Schedule cron-style background tasks that run your agents on autopilot. Each task has its own prompt, schedule, model selection, and full execution history. You can view detailed job logs, re-run tasks on demand, and enable/disable them with a single toggle.

!Background Task — Schedule, prompt, and execution history

$3

A collapsible Debug Log panel at the bottom of the UI gives you real-time visibility into what's happening under the hood — WebSocket events, cron task loading, agent scan results, and more. Filter by log level (ALL, WS, WST, API, INF, WRN, ERR) to quickly diagnose issues without leaving the chat interface.

!Debug Log — Real-time logs with level filtering

---

Architecture

!BotsChat Architecture

OpenClaw runs your agents locally (with your API keys, data, and configs). The BotsChat plugin establishes an outbound WebSocket to the BotsChat server — no port forwarding, no tunnels. Your API keys and data never leave your machine; only chat messages travel through the relay.

You can run BotsChat locally on the same machine, or deploy it to Cloudflare for remote access (e.g. from your phone).

Concepts

BotsChat introduces a few UI-level concepts that map to OpenClaw primitives:

| BotsChat | What it is | OpenClaw mapping |
|-------------------|---------------------------------------------------------|--------------------------|
| Channel | A workspace for one agent (e.g. "Research Bot") | Agent (agentId) |
| Task | A unit of work under a Channel | CronJob or Session |
| Job | One execution of a Background Task | CronRunLogEntry |
| Session | A conversation thread within a Task | Session |
| Thread | A branched sub-conversation from any message | Thread Session |

Task types:

- Background Task — runs on a cron schedule (e.g. "post a tweet every 6 hours"). Each run creates a Job with its own conversation session.
- Ad Hoc Chat — a regular conversation you start whenever you want.

Getting Started

$3

- Node.js 22+
- Wrangler CLI
- An OpenClaw instance

$3

``bash
git clone https://github.com/botschat-app/botsChat.git
cd botsChat
npm install
`

$3

Choose one of the three options below:

#### Option A: Use Hosted Console (Recommended)

The easiest way to get started — no deployment needed. We run a hosted BotsChat instance at console.botschat.app. Just sign up, generate a pairing token, and connect your OpenClaw instance directly.

Your API keys and data still stay on your machine — the hosted console only relays chat messages via WebSocket, exactly the same as a self-hosted deployment.

> Skip to Step 3 after signing up.

#### Option B: Run Locally

Wrangler uses Miniflare under the hood, so D1, R2, and Durable Objects all run locally — no Cloudflare account needed.

`bash


One-command startup: build web → migrate D1 → start server on 0.0.0.0:8787


./scripts/dev.sh
`

Or step by step:

`bash
npm run build -w packages/web # Build the React frontend
npm run db:migrate # Apply D1 migrations (local)
npx wrangler dev --config wrangler.toml --ip 0.0.0.0 # Start on port 8787
`

Open http://localhost:8787 in your browser.

Other dev commands:

`bash
./scripts/dev.sh reset # Nuke local DB → re-migrate → start
./scripts/dev.sh migrate # Only run D1 migrations
./scripts/dev.sh build # Only build web frontend
./scripts/dev.sh sync # Sync plugin to remote OpenClaw host + restart gateway
./scripts/dev.sh logs # Tail remote gateway logs
`

#### Option C: Deploy to Cloudflare

For remote access (e.g. chatting with your agents from your phone), deploy to Cloudflare Workers. The free tier is more than enough for personal use.

`bash


Create Cloudflare resources

wrangler d1 create botschat-db # Copy the database_id into wrangler.toml
wrangler r2 bucket create botschat-media

Build & deploy

npm run build -w packages/web # Build the React frontend
npm run deploy # Deploy API + web + Durable Objects
npm run db:migrate:remote # Apply migrations to remote D1
wrangler secret put JWT_SECRET # Set a production JWT secret
`

| Service | Purpose | Free Tier |
|------------------|----------------------------------------|----------------------------------|
| Workers | API server (Hono) | 100K req/day |
| Durable Objects | WebSocket relay (ConnectionDO) | 1M req/mo, hibernation = free |
| D1 | Database (users, channels, tasks) | 5M reads/day, 100K writes/day |
| R2 | Media storage | 10GB, no egress fees |

$3

After the BotsChat server is running, connect your OpenClaw instance to it.

1. Install the plugin

`bash
openclaw plugins install @botschat/botschat
`

2. Create a pairing token

Open the BotsChat web UI, register an account, and generate a pairing token from the dashboard.

3. Configure the connection

`bash


For hosted console, use https://console.botschat.app

For local deployment, use http://localhost:8787 or your LAN IP

For Cloudflare deployment, use your Workers URL

openclaw config set channels.botschat.cloudUrl
openclaw config set channels.botschat.pairingToken
openclaw config set channels.botschat.enabled true
`

This writes the following to your ~/.openclaw/openclaw.json:

`json
{
"channels": {
"botschat": {
"enabled": true,
"cloudUrl": "http://localhost:8787",
"pairingToken": "bc_pat_xxxxxxxxxxxxxxxx"
}
}
}
`

4. Restart the gateway and verify

`bash
openclaw gateway restart
`

Check the gateway logs — you should see:

`
Authenticated with BotsChat cloud
Task scan complete
`

Open the BotsChat web UI in your browser, sign in, and start chatting with your agents.

$3

1. When your OpenClaw gateway starts, the BotsChat plugin establishes an outbound WebSocket to ws:///api/gateway/.
2. This WebSocket stays connected (with automatic reconnection if it drops).
3. When you type a message in the web UI, it travels: Browser → ConnectionDO → WebSocket → OpenClaw → Agent → response back through the same path.
4. Your API keys, agent configs, and data never leave your machine — only chat messages travel through the relay.

Plugin Reference

$3

All config lives under channels.botschat in your openclaw.json:

| Key | Type | Required | Description |
|-----------------|---------|----------|------------------------------------------------------|
| enabled | boolean | no | Enable/disable the channel (default: true) |
| cloudUrl | string | yes | BotsChat server URL (e.g. http://localhost:8787) |
| pairingToken | string | yes | Your pairing token from the BotsChat dashboard |
| name | string | no | Display name for this connection |

$3

The plugin uses a JSON-based WebSocket protocol:

| Direction | Message Types |
|--------------------|------------------------------------------------------------------|
| Cloud → Plugin | user.message, user.action, user.command, task.schedule, task.delete, task.run, task.scan.request |
| Plugin → Cloud | agent.text, agent.media, agent.a2ui, agent.stream.*, job.update, job.output, task.scan.result, model.changed |

$3

`bash
openclaw plugins disable botschat


or remove entirely:


openclaw plugins remove botschat
`

---

Development

$3

`bash
npm run build:plugin
`

$3

`bash
npm run typecheck
``

License

Apache-2.0