Skip to main content
The gateway now ships in the praisonai-bot package. praisonai serve gateway still works exactly as documented here; for a standalone install see praisonai-bot Migration.
from praisonaiagents import Agent

agent = Agent(name="migration-agent", instructions="Migrate gateway configuration to the new format.")
agent.start("Migrate my gateway.yaml from the old schema to the new one.")
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. 
praisonai doctor --only gateway_config_migration
The user runs praisonai doctor; migration reports legacy bot.yaml or BotOS configs and normalises them to the gateway schema at load time.

​
How It Works

​
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.

​
Best Practices

Use praisonai doctor --only gateway_config_migration after pulling a new PraisonAI release to see whether your persisted YAML can be simplified.
Runtime auto-migration is transparent, but persisting the canonical channels: form makes configs easier to diff and review in PRs.
group_policy defaults to mention_only for new channels only. If your bot should respond to every message, set respond_all explicitly rather than relying on legacy defaults.
Comma-separated strings still load, but list form is clearer and matches the schema validators.

Gateway

Full gateway and channel configuration reference

Doctor

Gateway doctor checks and remediation