[Docs] Gateway + Telegram on Windows — Hermes-style multi-channel workforce deployment guide

Labels: documentation, gateway, windows, telegram, hermes-parity

Overview

PraisonAIDocs needs a complete runbook for deploying a Hermes-style AI workforce on PraisonAI — specifically on Windows, with multiple Telegram bots, multiple agents, and dual-brain RAG — using the gateway pattern.

The in-repo channels-gateway.md is 32 lines. It mentions pip install "praisonai[bot]" but not the gateway's [api] requirement, Windows UTF-8 setup, single-instance rules, multi-channel token env conventions, or troubleshooting for silent bots. Operators following current docs hit multiple failures before getting a working workforce.

This doc issue tracks the documentation gap. Code fixes are filed separately in PraisonAI (deepcopy, allowlist, typing, port preflight, health, encoding).

Target audience

• Non-developer operators running bots on a Windows laptop or VPS
• Teams migrating from Hermes agent (1 gateway, 3 bots, 4 brains)
• Anyone running praisonai gateway start with more than one Telegram channel

Architecture — Hermes workforce on PraisonAI

flowchart TB
    subgraph Users["Telegram users"]
        U1["DM @cfo_bot"]
        U2["DM @ops_bot"]
        U3["DM @content_bot"]
    end

    subgraph Gateway["PraisonAI WebSocketGateway — ONE process"]
        PORT["127.0.0.1:8765"]
        WS["/ws + /health"]
        CH1["channel: telegram_cfo → agent cfo"]
        CH2["channel: telegram_ops → agent ops"]
        CH3["channel: telegram_content → agent content"]
    end

    subgraph Brains["Knowledge (Chroma / filesystem)"]
        SHARED["company_shared brain"]
        P1["finance_private"]
        P2["ops_private"]
        P3["content_private"]
    end

    subgraph External["External services"]
        OAI["OpenAI API"]
        TAV["Tavily / search tools"]
    end

    U1 --> CH1
    U2 --> CH2
    U3 --> CH3

    CH1 --> P1
    CH1 --> SHARED
    CH2 --> P2
    CH2 --> SHARED
    CH3 --> P3
    CH3 --> SHARED

    CH1 --> OAI
    CH2 --> OAI
    CH3 --> OAI

Golden rules for this architecture:

1. One gateway process per machine (port 8765).
2. One Telegram token per channel — never reuse tokens.
3. Each agent searches shared + private brain via custom tools.
4. Replies take 20–30 seconds — normal for RAG + tools; not a sign of failure.

Documentation sections needed

1. Installation — both extras required

Current docs say:

pip install "praisonai[bot]"

Gateway also requires HTTP server dependencies. Without them:

ImportError: Gateway requires starlette and uvicorn.
Install with: pip install praisonai[api]

Document:

pip install "praisonai[bot,api]"
# or full install:
pip install "praisonai[all]"

Explain what each extra provides:

2. Windows UTF-8 setup

Document mandatory environment for Windows gateway deployments:

$env:PYTHONUTF8 = "1"
# alternative:
$env:PYTHONIOENCODING = "utf-8"

Explain the error users will see without this:

Error: 'charmap' codec can't encode character '\u26a0' in position 1: character maps to <undefined>

Clarify: this often appears after an API failure (e.g. OpenAI 429 quota) — fix billing first, then encoding.

3. Multi-channel gateway.yaml example

Full Hermes workforce example:

gateway:
  host: "127.0.0.1"
  port: 8765

agents:
  cfo:
    model: gpt-4o-mini
    tools: [search_knowledge]
  ops:
    model: gpt-4o-mini
    tools: [search_knowledge]
  content:
    model: gpt-4o-mini
    tools: [search_knowledge]

channels:
  telegram_cfo:
    platform: telegram
    token: ${TELEGRAM_CFO_TOKEN}
    routes:
      default: cfo
  telegram_ops:
    platform: telegram
    token: ${TELEGRAM_OPS_TOKEN}
    routes:
      default: ops
  telegram_content:
    platform: telegram
    token: ${TELEGRAM_CONTENT_TOKEN}
    routes:
      default: content

Matching .env:

TELEGRAM_CFO_TOKEN=
TELEGRAM_OPS_TOKEN=
TELEGRAM_CONTENT_TOKEN=
OPENAI_API_KEY=
GATEWAY_AUTH_TOKEN=

Note: create three separate bots in @Botfather — one token each.

4. Single gateway instance rule

Document clearly:

Never run two gateway processes. Only one process may bind port 8765 and poll each Telegram token.

Symptoms of duplicate gateway:

• Bot stops replying mid-session
• Log: Conflict: terminated by other getUpdates request
• /health may still show "running": true

Fix:

# Stop all gateway processes, start one
praisonai gateway stop
# or kill PIDs manually on Windows
curl http://127.0.0.1:8765/health

5. Health check interpretation

curl http://127.0.0.1:8765/health

Explain each field. Note current limitation: "running": true does not guarantee Telegram polling is healthy (until PraisonAI health enhancement ships).

Expected healthy response:

{
  "status": "healthy",
  "agents": 3,
  "channels": {
    "telegram_cfo": { "platform": "telegram", "running": true }
  }
}

6. Response latency expectations

Document prominently:

• First reply may take 20–30 seconds (knowledge search + LLM).
• Typing indicator disappears after ~5 seconds (known UX gap).
• Do not send duplicate messages or restart gateway during this window.

7. Security — allowed_users

Document allowed_users configuration via onboard:

allowed_users: ${TELEGRAM_ALLOWED_USERS}

TELEGRAM_ALLOWED_USERS=123456789

Important caveat to document until PraisonAI fix ships: gateway Telegram polling path may not enforce allowlist — verify after security fix (PraisonAI issue TBD).

8. Troubleshooting table

Proposed doc pages (PraisonAIDocs)

Link to PraisonAI code issues

Acceptance criteria

• New deployment-windows.mdx runbook published
• Install docs updated: gateway needs [bot,api]
• Hermes workforce example (3 bots, 3 agents) with full .env
• Troubleshooting table includes real error strings
• Cross-links to PraisonAI issues as fixes ship