hanzo-bot

Hanzo Bot (@hanzo/bot) is a TypeScript ESM multi-channel AI messaging gateway connecting AI agents to 50+ messaging platforms through a plugin/extension architecture.

Hanzo Bot - Multi-Channel AI Messaging Gateway

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-agent.md, hanzo/hanzo-mcp.md, hanzo/hanzo-playground.md

Overview

Hanzo Bot (@hanzo/bot) is a TypeScript ESM multi-channel AI messaging gateway connecting AI agents to 50+ messaging platforms through a plugin/extension architecture. First-class integrations for Discord, Telegram, Slack, WhatsApp, Signal, iMessage, Line, MS Teams, IRC, Matrix, and more. Includes TUI, web UI, native apps (iOS/Android/macOS), and an Agent Client Protocol (ACP) gateway.

Fork of OpenClaw/ClawdBot, fully rebranded. Package: @hanzo/bot, binary: hanzo-bot.

When to use

Deploying AI agents across multiple messaging platforms from a single codebase
Running an AI assistant on Discord, Telegram, Slack, or WhatsApp
Building a multi-channel chatbot with conversation memory
Need an ACP-compatible agent gateway
Connecting team channels (hanzo.team) to LLM proxy

Hard requirements

Node.js >= 22 with ESM support
pnpm for package management
Platform tokens for each channel (DISCORD_TOKEN, TELEGRAM_TOKEN, etc.)
LLM backend: Connects to Hanzo LLM Gateway (api.hanzo.ai/v1) or any OpenAI-compatible endpoint

Quick reference

| Item | Value | |------|-------| | Repo | github.com/hanzoai/bot | | Package | @hanzo/bot (npm) | | Version | 2026.3.x (calver) | | Stack | TypeScript ESM, pnpm, Node.js >= 22 | | Binary | hanzo-bot | | Image | ghcr.io/hanzoai/bot:latest | | Dev | pnpm dev | | Build | pnpm build | | Test | pnpm test | | TUI | pnpm tui | | Web UI | pnpm ui:dev | | Formatter | oxfmt | | Linter | oxlint (type-aware) | | K8s manifests | universe/infra/k8s/bot/ |

Architecture

 Messaging Platforms
 Discord | Telegram | Slack | ...
 |
 Extension Layer (50+)
 |
 +-----+-----+
 | |
 Channel ACP Gateway
 Framework (cross-agent)
 | |
 Agent Runtime |
 | |
 +----+----+ |
 | | | |
 Memory Context LLM
 (LanceDB) Engine Proxy
 |
 api.hanzo.ai/v1

Channel extensions (extensions/)

50+ extensions in the extensions/ directory:

| Category | Extensions | |----------|-----------| | Chat | discord, telegram, slack, whatsapp, signal, irc, matrix, mattermost | | Asian | line, feishu, zalo, zalouser | | Enterprise | msteams, googlechat, synology-chat, nextcloud-talk | | Social | twitch, nostr, tlon, lobster | | Apple | imessage, bluebubbles | | Voice | voice-call, talk-voice | | Dev | copilot-proxy, diffs, ci-fix-loop, flow | | AI/Memory | memory-core, memory-lancedb, llm-task, continuous-learning, self-improvement | | Infra | diagnostics-otel, device-pair, acpx, thread-ownership, phone-control |

Source structure

hanzoai/bot/
 src/
 agents/ # AI agent runtime
 channels/ # Channel framework (registry, config, session)
 discord/ # Discord-specific logic
 telegram/ # Telegram-specific logic
 slack/ # Slack-specific logic
 whatsapp/ # WhatsApp (Baileys) integration
 signal/ # Signal integration
 imessage/ # iMessage integration
 line/ # LINE integration
 web/ # Web channel
 gateway/ # ACP gateway
 tui/ # Terminal UI
 cli/ # CLI commands
 memory/ # Conversation memory
 context-engine/ # Context management
 providers/ # LLM providers
 commerce/ # Commerce module
 browser/ # Browser automation (Playwright)
 media-understanding/ # Media processing
 plugin-sdk/ # Plugin SDK exports
 extensions/ # 50+ extension plugins
 apps/
 ios/ # Swift iOS app
 android/ # Kotlin Android app
 macos/ # macOS app

Key dependencies

| Package | Purpose | |---------|---------| | grammy | Telegram Bot API | | @discordjs/voice + discord-api-types | Discord | | @slack/bolt + @slack/web-api | Slack | | @whiskeysockets/baileys | WhatsApp | | @line/bot-sdk | LINE | | playwright-core | Browser automation | | sqlite-vec | Vector search | | @agentclientprotocol/sdk | ACP |

Quickstart

git clone https://github.com/hanzoai/bot.git
cd bot
pnpm install

# Configure channel tokens
cp .env.example .env
# Edit .env: DISCORD_TOKEN, TELEGRAM_TOKEN, SLACK_BOT_TOKEN, etc.

# Development
pnpm dev

# Production
pnpm build && pnpm start

# TUI mode (interactive terminal)
pnpm tui

# Web UI
pnpm ui:dev

Playground registration

Bot instances register with the Hanzo Playground control plane (app.hanzo.bot) for:

Node registry and health monitoring
Execution tracking and audit
Workflow orchestration across multiple bots
Memory scope management (global, bot, session, run)

K8s deployment

# universe/infra/k8s/bot/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: hanzo-bot
 namespace: hanzo
spec:
 replicas: 2
 template:
 spec:
 containers:
 - name: bot
 image: ghcr.io/hanzoai/bot:latest
 envFrom:
 - secretRef:
 name: bot-secrets # KMS-synced
 env:
 - name: LLM_BASE_URL
 value: http://llm.hanzo.svc:4000/v1

Skills (separate repos)

Skills live outside the bot repo:

Monorepo: github.com/hanzobot/skills -- full collection with history
Per-skill repos: github.com/hanzoskill org (739 public repos, one per skill)
Each skill has: SKILL.md, _meta.json, scripts/, .author

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | Bot not responding | Missing channel token | Check .env for platform-specific token | | LLM timeout | Gateway unreachable | Verify LLM_BASE_URL points to working gateway | | Memory not persisting | LanceDB not initialized | Check memory-lancedb extension is enabled | | Discord rate limited | Too many messages | Bot auto-handles rate limits via discord.js |

Related Skills

hanzo/hanzo-playground.md -- Bot control plane
hanzo/hanzo-agent.md -- AI agent framework
hanzo/hanzo-mcp.md -- MCP tools (extensions can expose MCP tools)
hanzo/hanzo-team.md -- Team platform integration

Last Updated: 2026-03-23 Category: Hanzo Ecosystem Related: bot, messaging, gateway, channels, discord, telegram, slack, whatsapp, acp Prerequisites: Node.js >= 22, pnpm, messaging platform tokens