praisonai-bot package. praisonai serve gateway still works exactly as documented here; for a standalone install see praisonai-bot Migration.How It Works
Deployment Steps
Quick Start
Install Dependencies
[api] you’ll get:Configure Windows UTF-8
Create Gateway Configuration
gateway.yaml:.env file:Start Gateway
Windows-Specific Configuration
Environment Variables
Windows PowerShell environment setup:APPDATA. praisonai gateway install uses %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup (Startup-folder fallback) and a Scheduled Task wrapper script under the same folder. If APPDATA is unset (as in most non-Windows shells and some WSL contexts), install/uninstall refuse cleanly rather than write to a literal %APPDATA%\... path. See PR #4996.UTF-8 Encoding Setup
Three ways to configure UTF-8 on Windows:- Environment Variable
- System Environment
- Per-Process
Windows Service Installation
For production deployment as Windows service:Multi-Channel Windows Setup
Hermes-Style Workforce Example
Completegateway.yaml for 3-bot Hermes workforce:
.env file:
Creating Multiple Telegram Bots
Important: Each channel needs its own Telegram bot token.-
Create CFO Bot:
- Message @BotFather
/newbot- Name: “CFO Assistant Bot”
- Username: “your_company_cfo_bot”
- Save token as
TELEGRAM_CFO_TOKEN
-
Create Ops Bot:
/newbot(same BotFather)- Name: “Operations Assistant Bot”
- Username: “your_company_ops_bot”
- Save token as
TELEGRAM_OPS_TOKEN
-
Create Content Bot:
/newbot(same BotFather)- Name: “Content Assistant Bot”
- Username: “your_company_content_bot”
- Save token as
TELEGRAM_CONTENT_TOKEN
Health Monitoring
Health Check Commands
Monitor gateway status:Process Management
Check running gateway processes:Security Configuration
User Access Control
Configure allowed users to prevent unauthorized access:.env configuration:
TELEGRAM_ALLOWED_USERS empty, you must also set unknown_user_policy: "allow" for the bot to reply to anyone (since PR #1885). For production, set TELEGRAM_ALLOWED_USERS to your user IDs and leave unknown_user_policy at the default "deny".Token Security
Secure token storage on Windows:Troubleshooting Windows Issues
Common Windows Errors
gateway install fails: 'startup folder path still contains an unexpanded variable'
gateway install fails: 'startup folder path still contains an unexpanded variable'
RuntimeError:{"ok": False, "error": "..."}:APPDATA is not set in the current shell. This is normal on macOS/Linux, common in WSL where APPDATA isn’t inherited from the Windows host, and can happen inside containerised CI runners. The autostart installer expands %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup; with APPDATA unset the variable stays literal, so the installer refuses rather than write a stray path.Solutions:On native Windows, verify APPDATA is set
C:\Users\<user>\AppData\Roaming.Off Windows, use the native autostart mechanism
launchd (macOS) or systemd --user (Linux) instead — see Platform-Specific Notes.Clean up a stray directory from an older install
%APPDATA%\Microsoft\... in the working tree. Check for it and remove it:actions/checkout if committed. Delete it if found.%APPDATA%\Microsoft\... directory into the current working directory. uninstall() reports Startup script location unresolved (unexpanded variable); skipped and moves on.charmap codec error
charmap codec error
- Missing UTF-8 environment configuration
- OpenAI API failure (429 quota) + encoding issue
ImportError: Gateway requires starlette
ImportError: Gateway requires starlette
Bot stops responding (409 Conflict)
Bot stops responding (409 Conflict)
- Bot works initially, then stops mid-session
- Log shows:
Conflict: terminated by other getUpdates request - Health check still shows
"running": true
- Since PR #4197, the cross-uid cause of this conflict is removed on POSIX: a gateway owned by another user is now treated as running, so its lock is preserved and a second gateway is refused instead of being started on the same token.
Error starting gateway: invalid attr name 'connections' (psutil 7)
Error starting gateway: invalid attr name 'connections' (psutil 7)
praisonai gateway start with a busy port on psutil ≥ 6.Cause: Older versions used the removed Process.connections attribute to identify the process holding the port.Fix: PR #4197 switches to net_connections() (with a connections() fallback) and wraps the lookup so a diagnostic can never break startup. Upgrade praisonai-bot to the merged version — the friendly port-collision message (Another gateway may be running (PID ...). Stop it: praisonai gateway stop) renders again.25-30 second response delay
25-30 second response delay
- Telegram typing indicator disappears after 5 seconds
- Reply comes 20-30 seconds later
- No error messages
- Do not send duplicate messages during wait
- Do not restart gateway during response window
- Typing indicator renewal fix is pending in PraisonAI
gateway install fails: 'startup folder path still contains an unexpanded variable'
gateway install fails: 'startup folder path still contains an unexpanded variable'
RuntimeError from install():install()’s aggregated result as {"ok": False, "error": "..."}:APPDATA is not set in the current shell. The autostart installer builds the Startup-folder path from %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup, and %APPDATA% only expands on Windows with the variable set. This is the norm on macOS/Linux, common in WSL where APPDATA isn’t inherited from the Windows host, and can happen inside containerised CI runners.Solution:On native Windows, verify APPDATA is set
C:\Users\<user>\AppData\Roaming.Off Windows, use the native autostart mechanism
praisonai gateway install on macOS/Linux — use launchd (macOS) or systemd --user (Linux) instead. See Platform-Specific Notes.Clean up a stray directory from a pre-fix install
%APPDATA%\Microsoft\... in the working tree. On Windows this is an invalid path that breaks actions/checkout if committed.%APPDATA%\Microsoft\... directory in the current working directory, the installer now refuses cleanly and writes nothing.APPDATA unset, uninstall() no longer tries to os.remove a literal %APPDATA%\... path. It reports Startup script location unresolved (unexpanded variable); skipped and moves on.Windows-Specific Debugging
Enable detailed logging:Performance Optimization
Windows Resource Configuration
Optimize for Windows deployment:Production Deployment
Windows Server Configuration
For production Windows Server deployment:Best Practices
Use Windows Task Scheduler for monitoring
Use Windows Task Scheduler for monitoring
Configure Windows Event Logging
Configure Windows Event Logging
Use Windows Subsystem for Linux (WSL) alternative
Use Windows Subsystem for Linux (WSL) alternative

