A self-hosted, multi-tier Telegram AI assistant.
Routes every query through the cheapest viable model tier — semantic cache, live web lookups, headless scraping, and deep synthesis — all on a single 4 GB VPS.
📟 BEO (Bureau of Ethereal Operations) is a self-hosted multi-model routing layer built for OpenClaw. Instead of sending every query to one model through a provider with an incentive to maximize your spend, BEO routes each query to the cheapest model that can handle it.
BEO operates via a distinct roster of specialized agents:
- 🎬 The Director (OpenClaw): The primary orchestration daemon that sits on the local node and autonomously determines operational Tiers.
- 🔑 The Gatekeeper (LiteLLM): The API proxy that enforces rate limits, failover logic, and manages promotional keys.
- 🎙 The MC (Gemini 3 Flash Preview): The sassy front-end voice that processes logic and formats the final broadcast.
- 📚 The Librarian (Redis): The keeper of the semantic cache that serves identical previous queries instantly.
- 💼 The Broker (Brave Search API): A programmatic search index that trades real-time web snippets for fractions of a cent.
- 🏃 The Minions (Gemini 3.1 Flash-Lite): High-concurrency grunts that execute local parallel scraping and strip CSS/JS.
- 🔮 The Oracle (Gemini 1.5 Pro): A cloud-based model with a 2M-token vision used for deep synthesis of massive payloads.
- 🏛️ The Board (Claude 4.6 Opus): The ultimate authority summoned exclusively via strict keyword rituals for existential overrides.
Every inbound message passes through a pre-flight pipeline that enforces a strict escalation ladder:
| Tier | Name | Action | Target Cost |
|---|---|---|---|
| 0 | 🧠 The Brain | Pure Logic: Handled by The MC directly from internal neural weights. | ~$0.00007 |
| 1 | 🗄️ The Cabinet | Redis Cache: Instant bypass of LLM generation for identical semantic queries. | $0.00 |
| 2 | 🗂️ The Desk | Quick Facts: Bypasses scraping, pays The Broker directly for a JSON snippet. | ~$0.0005 |
| 3 | 🗺️ The Field | General Browsing: Deploys Minions to locally scrape and strip HTML from specific URLs. | ~$0.01 |
| 4 | 🌀 The Extraction | Deep Research: Massive data payloads hoisted to The Oracle for deep synthesis. | ~$0.10 |
| 5 | 👑 The VIP | The Board: Bypasses The Director entirely via the /opus trigger. |
$0.50+ |
Built on OpenClaw + LiteLLM + Redis + Telegram long-polling. Designed to run on a single lower-tier VPS (2 vCPU, 4 GB RAM).
See docs/BLUEPRINT.md for the full engineering spec (BLU-01 → BLU-33).
Telegram
│
▼
Pre-flight
├── Language detect (lingua, ~1ms, no API call)
├── TLD validation (IANA cache)
├── URL extraction (1–5 → Tier 3, 5+ → Tier 4)
├── Slash commands (/opus → Tier 5)
├── Attachment / char count triggers (→ Tier 4)
├── Desk keyword match (→ Tier 2, no_store=true)
└── Nano-classifier fallback (Flash Lite → Tier 1 or 2)
│
▼
Redis Semantic Cache ── Tier 0
├── Embedding: text-embedding-004
├── Similarity threshold: 0.92
├── Cache HIT ──► return immediately (no LLM call, no cost)
└── Cache MISS ──► continue
│
▼
LiteLLM Gateway
├── Budget enforcement (per-key max_budget, SQLite)
├── Key rotation (Gemini promo pool, simple-shuffle / least-busy)
├── Per-tier timeouts
└── Semantic cache write (no_store flag from pre-flight)
│
├─────────────────┬──────────────────┬──────────────────┬─────────────────┐
▼ ▼ ▼ ▼ ▼
Tier 1 Tier 2 Tier 3 Tier 4 Tier 5
The Brain The Desk The Field The Extraction The VIP
───────── ──────── ───────── ────────────── ───────
Flash Pro Flash Pro Flash Lite Flash Pro Opus / top
+ The Broker + The Minions + The Oracle capability
│ (mcp-search (1 sub-agent (multi-source model
│ live lookup) per URL, synthesis,
│ mcp-firecrawl structured │
│ │ JS fallback) memo output) │
│ │ │ │ │
│ │ token overflow? │ │
│ │ (>8k tokens) │ │
│ │ └──────────────────────┘ │
│ │ │ │
└─────────────────┴───────────────────────┴───────────────────────────────┘
│
▼
The MC
┌───────────────────┐
│ Tier 1: generate │
│ Tier 2–5: railblock│
│ (format + deliver │
│ only, no re- │
│ synthesis) │
└───────────────────┘
│
Runtime Redirection (if needed)
├── live fact detected → Tier 2
├── URLs found mid-turn → Tier 3
└── massive payload → Tier 4
│
▼
Telegram
(response delivered)
- A VPS with 4 GB RAM minimum (Hetzner CAX11 or equivalent)
- Docker + Docker Compose installed
- A Openclaw
- A Telegram bot token from @BotFather
- At least one of, but n keys capable:
- Google AI Studio API key (free tier works)
- OpenRouter API key
# 1. Clone
git clone https://github.com/YOUR_USERNAME/beo.git && cd beo
# 2. Bootstrap — creates required host dirs and copies .env.example
./setup.sh
# 3. Fill in your keys
nano .env
# 4. Copy and adjust OpenClaw config
cp openclaw.json.example openclaw.json
# 5. Launch
docker compose up -d
# 6. Check logs
docker compose logs -fWhy
setup.sh? Git cannot track empty directories.data/redis/must exist on the host before Docker mounts it — otherwise Docker creates it as root and Redis fails to write.setup.shcreates it with correct ownership. Run it once after every fresh clone.
All configuration lives in three files:
| File | Purpose |
|---|---|
.env |
API keys and operational thresholds (never committed) |
litellm_config.yaml |
Model aliases, budgets, router strategy, semantic cache |
openclaw.json |
Agent definitions, approval policy, compaction settings |
See .env.example for all required variables with inline documentation.
BEO is designed for a single-node VPS. The deploy workflow is:
# On your VPS — after git clone and .env setup
docker compose up -d
# To update after a git push
git pull origin main && docker compose up -d --no-buildSee docs/DEPLOY.md for the full VPS setup walkthrough.
See docs/ROADMAP.md for the phased deployment roadmap (Phase 0 → Phase 6).
MIT — see LICENSE.