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

Structured Conversation Management

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.

Interactive Agent UI (A2UI)

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.

Background Task Automation

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.

Built-in Debug Log

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.

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

Prerequisites

An OpenClaw instance
For self-hosting (Option B or C): Node.js 22+, Wrangler CLI

Choose Your Deployment

BotsChat is 100% open source — the same code runs whether you use our hosted console, run it locally, or deploy to your own Cloudflare. The only difference is where the server runs; your API keys and data always stay on your machine.

Mode	Best for	Clone repo?
A. Hosted Console	Zero setup, start in minutes	No
B. Run Locally	Development, no cloud account	Yes
C. Deploy to Cloudflare	Remote access (e.g. from phone)	Yes

Pick one below and follow its steps, then continue to Install the OpenClaw Plugin.

Option A: Hosted Console (Recommended)

We run the same open-source stack at console.botschat.app. No clone, no deploy: open the link → sign up → create a pairing token → connect OpenClaw.

Your API keys and data still stay on your machine; the hosted console only relays chat messages via WebSocket.

→ Then go to Install the OpenClaw Plugin.

Option B: Run Locally

Clone, install, and run the server on your machine. Wrangler uses Miniflare, so D1, R2, and Durable Objects all run locally — no Cloudflare account needed.

git clone https://github.com/botschat-app/botsChat.git
cd botsChat
npm install
# One-command startup: build web → migrate D1 → start on 0.0.0.0:8787
./scripts/dev.sh

Or step by step:

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:

./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

→ Then go to Install the OpenClaw Plugin.

Option C: Deploy to Cloudflare

For remote access (e.g. chatting from your phone), deploy the same code to Cloudflare Workers. The free tier is enough for personal use.

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

# 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

→ Then go to Install the OpenClaw Plugin.

Install the OpenClaw Plugin

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

1. Install the plugin

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

# 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 <BOTSCHAT_URL>
openclaw config set channels.botschat.pairingToken <YOUR_PAIRING_TOKEN>
openclaw config set channels.botschat.enabled true

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

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

4. Restart the gateway and verify

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.

How It Works

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

Plugin Reference

Configuration

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

Message Protocol

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`

Uninstall

openclaw plugins disable botschat
# or remove entirely:
openclaw plugins remove botschat

Development

Build the plugin

npm run build:plugin

Type-check everything

npm run typecheck

License

Apache-2.0

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
migrations		migrations
packages		packages
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
wrangler.toml		wrangler.toml

Navigation Menu

Repository files navigation

BotsChat

Key Features

Structured Conversation Management

Interactive Agent UI (A2UI)

Background Task Automation

Built-in Debug Log

Architecture

Concepts

Getting Started

Prerequisites

Choose Your Deployment

Option A: Hosted Console (Recommended)

Option B: Run Locally

Option C: Deploy to Cloudflare

Install the OpenClaw Plugin

How It Works

Plugin Reference

Configuration

Message Protocol

Uninstall

Development

Build the plugin

Type-check everything

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

BotsChat

Key Features

Structured Conversation Management

Interactive Agent UI (A2UI)

Background Task Automation

Built-in Debug Log

Architecture

Concepts

Getting Started

Prerequisites

Choose Your Deployment

Option A: Hosted Console (Recommended)

Option B: Run Locally

Option C: Deploy to Cloudflare

Install the OpenClaw Plugin

How It Works

Plugin Reference

Configuration

Message Protocol

Uninstall

Development

Build the plugin

Type-check everything

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages