Gateway Config Migration

Upgrade legacy bot.yaml and platforms: configs to the canonical schema

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 — on both praisonai bot serve and praisonai gateway start — and 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

• Migration runs on both praisonai bot serve and praisonai gateway start — before PR #3019, only bot serve migrated.
• 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

Run doctor before upgrading

Use praisonai doctor --only gateway_config_migration after pulling a new PraisonAI release to see whether your persisted YAML can be simplified.

Persist canonical YAML when WARN appears

Runtime auto-migration is transparent, but persisting the canonical channels: form makes configs easier to diff and review in PRs.

Keep explicit group_policy values

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.

Convert allowed_users to lists

Comma-separated strings still load, but list form is clearer and matches the schema validators.

---

Related

Gateway

Full gateway and channel configuration reference

Doctor

Gateway doctor checks and remediation