> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Config Migration

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

<Note>
  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](/docs/guides/praisonai-bot-migration).
</Note>

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[bot.yaml<br/>platform + token] --> M[🧩 Canonical Schema]
    B[gateway.yaml<br/>agents + channels] --> M
    C[BotOS config<br/>agent + platforms] --> M
    M --> N[✅ Channels dict<br/>auto-normalized]

    classDef legacy fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef schema fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class A,B,C legacy
    class M schema
    class N result

```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Gateway Config Migration

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result    Agent-->>User: Response
```

## Quick Start

<Steps>
  <Step title="Detect legacy format">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai doctor --only gateway_config_migration
    ```

    If your config is already canonical, you will see **PASS — Config uses current format**.
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## Migration Table

### Single-bot → multi-channel

**Before** (legacy `bot.yaml`):

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
platform: telegram
token: ${TELEGRAM_BOT_TOKEN}
agent:
  name: assistant
  instructions: "Help users"
```

**After** (canonical):

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent:
  name: assistant
  instructions: "Help users"
channels:
  telegram:
    platform: telegram
    token: ${TELEGRAM_BOT_TOKEN}
```

### BotOS `platforms:` → `channels:`

**Before**:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent:
  name: assistant
platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
  discord:
    token: ${DISCORD_BOT_TOKEN}
```

**After**:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent:
  name: assistant
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
  discord:
    token: ${DISCORD_BOT_TOKEN}
```

### String `allowed_users` → list

**Before**:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users: "123456,789012"
```

**After**:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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](/docs/features/gateway).

***

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Convert allowed_users to lists">
    Comma-separated strings still load, but list form is clearer and matches the schema validators.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Gateway" icon="tower-broadcast" href="/docs/features/gateway">
    Full gateway and channel configuration reference
  </Card>

  <Card title="Doctor" icon="stethoscope" href="/docs/cli/doctor">
    Gateway doctor checks and remediation
  </Card>
</CardGroup>