Skip to main content
PraisonAI auto-migrates legacy bot.yaml and BotOS platforms: configs to the canonical GatewayConfigSchema at load time — praisonai doctor reports migration opportunities so you can persist them.

​
Quick Start

1

Detect legacy format

praisonai doctor --only gateway_config_migration
If your config is already canonical, you will see PASS — Config uses current format.
2

Review WARN output

Example when migration is available:
⚠ Gateway Config Migration [MEDIUM]
  Config can be migrated: 2 change(s)
  • Single-bot format can be migrated to multi-channel format
  • telegram: allowed_users string → list migration available
3

Persist canonical YAML

Rewrite your config to the canonical channels: form (see migration table below). At runtime, legacy shapes already load — persisting is optional but recommended for clarity.

​
Migration Table

​
Single-bot → multi-channel

Before (legacy bot.yaml): 
platform: telegram
token: ${TELEGRAM_BOT_TOKEN}
agent:
  name: assistant
  instructions: "Help users"
After (canonical): 
agent:
  name: assistant
  instructions: "Help users"
channels:
  telegram:
    platform: telegram
    token: ${TELEGRAM_BOT_TOKEN}

​
BotOS platforms: → channels:

Before: 
agent:
  name: assistant
platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
  discord:
    token: ${DISCORD_BOT_TOKEN}
After: 
agent:
  name: assistant
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
  discord:
    token: ${DISCORD_BOT_TOKEN}

​
String allowed_users → list

Before: 
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users: "123456,789012"
After: 
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users:
      - "123456"
      - "789012"

​
Behaviour Notes

  • BotYamlSchema is an alias of GatewayConfigSchema — existing Python imports keep working.
  • group_policy defaults to mention_only for new channels without an explicit value. Configs that explicitly set respond_all keep that value.
  • Comma-separated allowed_users strings are auto-converted to lists at load time.
  • All three YAML shapes (platform+token, agents+channels, platforms:) validate against one schema — see Gateway.

Gateway

Full gateway and channel configuration reference

Doctor

Gateway doctor checks and remediation