praisonai gateway command resolves its config through one canonical order, so onboard, start, doctor, test, status, send, and channels never look at different files.
Quick Start
1
Onboard once
2
Start with no --config
start prints the file it picked before binding, so you always know which config is live.How It Works
Resolution walks a fixed precedence: an explicit--config always wins, then the working-dir config, then the onboarded home config, then the legacy alias.
Discovery works even without the optional
praisonai-code package installed — the home fallback is a plain filesystem convention, not owned by any one package.
Configuration Options
Two environment variables steer discovery when the defaults don’t fit.Common Patterns
start with no config found
When nothing is discovered, start prints an actionable hint and exits 78 instead of silently starting channel-less:
Single-agent mode skips channel discovery
Pass--agents <path> to run one agent with no channel config — discovery is skipped:
Diagnostics use the same file start binds
doctor, test, status, send, and channels default --config to a gateway.yaml sentinel. Left at the default, they run the same discovery order, so a doctor run inspects exactly what start would bind:
Best Practices
Onboard, then start with no flags
Onboard, then start with no flags
praisonai onboard → praisonai gateway start is the happy path. start discovers the onboarded config and prints Using gateway config: <path> so you always see which file is live.Check in ./bot.yaml for project-local configs
Check in ./bot.yaml for project-local configs
A
./bot.yaml in the working dir wins over the home config (precedence 2). Commit it to keep a project’s gateway config alongside its code.Point at a custom home with PRAISONAI_BOT_CONFIG
Point at a custom home with PRAISONAI_BOT_CONFIG
Set
PRAISONAI_BOT_CONFIG (or PRAISONAI_HOME) to run multiple onboarded profiles from one machine without passing --config every time.Treat exit 78 as 'run onboard'
Treat exit 78 as 'run onboard'
An exit
78 from start means no config was found — run praisonai onboard or pass --config. The installed daemon units treat 78 as do-not-restart, so a missing config won’t loop the service.Related
Gateway CLI
Every gateway command, its flags, and the discovery order in context
Onboarding
Writes the
~/.praisonai/bot.yaml that discovery findsConfig Migration
Start-time
config_version validation on the discovered configExit Codes
Exit
78 — the do-not-restart contract when no config is found