BridgeTalk

Bridge the gap between you and AI agents.

A minimal, task-focused client for OpenClaw Gateway

Built entirely with AI assistance (Claude, Codex & Kimi)

---

📖 What is this?

BridgeTalk is a modern client for OpenClaw Gateway, communicating via WebSocket protocol.

Core Features: Task-first mode · Multi-agent management · Local data persistence · Mobile-first design · Pure black & white minimalist UI

vs. OpenClaw Default UI

Feature	OpenClaw Default UI	BridgeTalk
Conversation Mode	Simple chat history	Task-first, conversations organized around tasks
Agent Management	Single session	Multi-agent simultaneous management
Data Persistence	Temporary	SQLite permanent storage
Mobile Experience	Basic	PWA, installable to home screen
Collaboration	None	Subtask collaboration, multi-agent coordination
UI Style	Standard	Minimalist B&W, zero distractions

---

🚀 Quick Start

Prerequisites

• ✅ OpenClaw Gateway installed and running (default ws://127.0.0.1:18789)
• ✅ Node.js 18+ and pnpm 8+ (recommended: Node 20/22 LTS)

Windows note (better-sqlite3): Node 24 may not have matching prebuilt binaries, which can trigger node-gyp rebuild. If install fails, switch to Node 22 LTS and reinstall:

nvm install 22
nvm use 22
pnpm install

3-Step Installation

# 1. Clone and install
git clone https://github.com/zhuamber370/bridgetalk.git
cd bridgetalk
pnpm install

# 2. Configure (copy and edit .env)
cp .env.example .env
# Edit .env and fill in your OpenClaw Gateway Token

# 3. Start
pnpm dev

Visit http://localhost:5173 to use.

First Use

1. Click "+ New Agent"
2. Enter name (e.g. "Assistant") and select model (e.g. claude-opus-4-6)
3. After creation, click the agent card to enter Inbox
4. Type a message to start conversation

---

📱 UI Preview

• Agent List / - Manage all agents
• Agent Inbox /agents/:id - Task list + conversation window
• Task Detail /agents/:id/tasks/:taskId - View single task

---

🛠️ Development

# Start dev servers (frontend + backend)
pnpm dev

# Start separately
pnpm --filter @bridgetalk/client dev  # Frontend :5173
pnpm --filter @bridgetalk/server dev  # Backend :3001

# Build for production
pnpm build

# Type check
pnpm lint

Data Locations:

• Tasks and messages: packages/server/agent_channel_v2.db
• Agent config: ~/.openclaw/openclaw.json (shared with OpenClaw Gateway)

---

🚢 Production Deployment

Using PM2 + Nginx (Recommended)

# 1. Build
pnpm build

# 2. Start backend (using PM2)
cd packages/server
pm2 start dist/index.js --name bridgetalk
pm2 save

# 3. Configure Nginx (see nginx.conf.example)
sudo cp nginx.conf.example /etc/nginx/sites-available/bridgetalk
# Edit config, modify domain and paths
sudo ln -s /etc/nginx/sites-available/bridgetalk /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

See DEPLOYMENT.md for detailed deployment guide.

---

❓ FAQ

Q: Can't see any agents in the list?

A: BridgeTalk reads agents from ~/.openclaw/openclaw.json. If the list is empty:

1. Check if OpenClaw Gateway is properly configured
2. OpenClaw should have at least a main agent in openclaw.json
3. You can manually create agents in BridgeTalk using the "+ New Agent" button
4. Check backend logs: pnpm --filter @bridgetalk/server dev

Q: Frontend stays on "Loading..." after pnpm dev?

A: Check in this order:

1. Confirm backend is running: pnpm --filter @bridgetalk/server dev and check http://localhost:3001/health
2. Confirm frontend is running on http://localhost:5173
3. Open browser DevTools Network tab and verify /api/v1/agents is 200
4. If /api/v1/agents fails, verify OpenClaw config file exists: ~/.openclaw/openclaw.json (or set OPENCLAW_HOME)
5. On Windows, if you previously installed with Node 24, switch to Node 22 and reinstall dependencies

Q: "No available models" error?

A: Check:

1. OpenClaw Gateway is running (ws://127.0.0.1:18789)
2. OPENCLAW_GATEWAY_TOKEN in .env is correct
3. View backend logs: pnpm --filter @bridgetalk/server dev

Q: No response after sending message?

A: Possible causes:

1. Gateway connection lost - check backend logs
2. Token expired - regenerate and update .env
3. Network issue - check browser console

Q: Sending message fails with missing scope: operator.write?

A: This is a Gateway device scope issue (not frontend UI):

1. Run openclaw devices list --json
2. Find the device with clientId: "gateway-client" and clientMode: "backend"
3. Rotate that device token with full operator scopes (example): openclaw devices rotate --device <DEVICE_ID> --role operator --scope operator.read --scope operator.write --scope operator.pairing --scope operator.approvals --scope operator.admin
4. Delete local cache files (~/.openclaw-inbox/device-token.json and ~/.openclaw-inbox/device-keypair.json)
5. Restart Gateway and pnpm dev

Q: Sending message fails with HTTP 401 authentication_error: API Key invalid/expired?

A: This means the upstream model provider key used by OpenClaw Gateway is invalid/expired:

1. Confirm which model your agent is using
2. Update the corresponding provider API key in Gateway configuration/environment
3. Restart Gateway
4. Restart BridgeTalk (pnpm dev) and retry

Note: This is different from OPENCLAW_GATEWAY_TOKEN in BridgeTalk .env.

Q: How to backup data?

A: Backup these two files:

cp packages/server/agent_channel_v2.db ~/backup/
cp ~/.openclaw/openclaw.json ~/backup/

---

📖 Documentation

• Quick Start - README.md (this file)
• Architecture - docs/ARCHITECTURE.md
• API Reference - docs/API.md
• Deployment Guide - DEPLOYMENT.md
• Contributing - CONTRIBUTING.md
• Security - SECURITY.md

---

🤝 Contributing

We welcome all forms of contributions!

• 🐛 Report Bug
• 💡 Feature Request
• 📝 Improve Docs
• 🔧 Submit PR

See CONTRIBUTING.md for details.

---

📄 License

This project is licensed under the MIT License.

---

🙏 Acknowledgments

• Built with OpenClaw Gateway
• Inspired by minimalist design principles

🤖 AI-Powered Development

All code and documentation in this project were created with the assistance of AI:

• Claude (Anthropic) - Architecture design, core implementation, and documentation
• Codex (OpenAI) - Code generation and optimization
• Kimi (Moonshot AI) - Additional development support

---

Made with ⚫⚪ by zhuamber370

If you find this useful, please give it a ⭐️