Skip to main content

​
Telegram Connection

These variables define how your bot connects to the Telegram platform. A TELEGRAM_BOT_TOKEN is always required.
VariableDescriptionDefault
TELEGRAM_BOT_TOKENRequired. Your Telegram Bot API token from @BotFather. This is the key to your bot’s identity.-
BOT_NAMEThe name the bot uses for itself in prompts and messages. Helps in personalizing the bot’s identity.Chibi
TELEGRAM_BASE_URLFor advanced use cases, like running a local Telegram Bot API server. This directs API traffic to your server instead of Telegram’s.https://api.telegram.org/bot
TELEGRAM_BASE_FILE_URLSimilar to the above, but for file downloads. Change this only if you have a local Bot API server.https://api.telegram.org/file/bot
PROXYIf your server is behind a proxy, specify it here to ensure the bot can communicate with the Telegram API.None
[!WARNING] Security Advisory Your TELEGRAM_BOT_TOKEN is highly sensitive. Treat it like a password. Do not expose it in public repositories or client-side code.

​
Access Control

Control who can interact with your bot. By default, the bot is private.
VariableDescriptionDefault
USERS_WHITELISTA comma-separated list of Telegram usernames (e.g., @user1,user2) or numeric IDs. Only these users can interact with the bot.None (disabled)
GROUPS_WHITELISTA comma-separated list of Telegram group chat IDs. The bot will only operate in these groups.None (disabled)
ANSWER_DIRECT_MESSAGES_ONLYIf True, the bot will not respond to messages in groups it’s added to unless the group is whitelisted.True
MESSAGE_FOR_DISALLOWED_USERSThe specific message sent to a user who tries to interact with the bot but is not on the whitelist.Standard rejection message
ALLOW_BOTSIf True, the bot will respond to messages sent by other bots.False

​
Pre-start Security Checks

Starting from version 1.6.1, Chibi performs automatic security validations before starting the bot to prevent dangerous configurations.

​
Security Rules

  1. Private Mode Requires User Whitelist
    • If PUBLIC_MODE=False (default), you must configure USERS_WHITELIST.
    • Without a whitelist, unauthorized users could access your bot and incur API costs.
    • The bot will refuse to start if this condition is not met.
  2. Public Mode Blocks Filesystem Access
    • If PUBLIC_MODE=True, you cannot enable FILESYSTEM_ACCESS=True.
    • Running a public bot with filesystem access is a severe security risk, as any user could potentially read or write files on your server.
    • The bot will refuse to start if this combination is detected.
  3. Warning: Filesystem Access in Groups
    • If FILESYSTEM_ACCESS=True and the bot is added to groups (via GROUPS_WHITELIST), a warning is displayed.
    • Consider whether your group members need filesystem access before enabling this combination.

​
Example Secure Configuration

# Private bot with whitelisted users
PUBLIC_MODE=False
USERS_WHITELIST=123456789,@myusername
FILESYSTEM_ACCESS=True

# Public bot (users provide their own keys)
PUBLIC_MODE=True
USERS_WHITELIST=123456789,@myusername
FILESYSTEM_ACCESS=False

​
General Behavior

These settings control the bot’s core functionality and user interface elements.
VariableDescriptionDefault
PUBLIC_MODEIf True, the bot won’t use its master API keys. Instead, each user must provide their own API key via the /key command. This is ideal for public-facing bots to shift API costs to the user.False
LOG_PROMPT_DATASet to True to log the full prompt data sent to the AI provider. Useful for debugging but can be verbose.False
HIDE_MODELSIf True, hides the model selection buttons from the user interface. Simplifies the UI if you want users to stick to the default model.False
HIDE_IMAGINEIf True, hides the /image and other image generation commands.False
SHOW_LLM_THOUGHTSWhen enabled, the bot will show its internal reasoning or “thoughts” before providing a final answer. Great for transparency and debugging.False
WORKING_DIRThe default directory the bot’s filesystem tools will operate in.~/chibi
HOME_DIRThe directory considered as the “home” for the AI agent.~/chibi
SKILLS_DIRAbsolute path to the directory containing LLM skills/prompts../skills
MODERATION_PROVIDEROptional. Specifies the AI provider to use for command moderation. If a moderation provider is not explicitly set by the user, it will be chosen automatically. The system attempts to select a moderation provider that DOES NOT coincide with the default primary provider. If the default primary provider is taken from the beginning of the list of available providers, the moderation provider will be taken from the end of that list.None
MODERATION_MODELOptional. Specifies the AI model to use for command moderation. If a model is not specified, a default model specifically recommended for moderation will be used (rather than the current model of the primary provider).None

​
Agent Capabilities

These settings define what the AI agent is allowed to do.
VariableDescriptionDefault
FILESYSTEM_ACCESSHigh Risk. If True, allows the bot to use tools that can read from and write to the local filesystem. See Agent Mode for details.False
ALLOW_DELEGATIONIf True, the agent can spawn sub-agents to handle complex tasks in the background.True
TOOLS_WHITELISTA comma-separated list of specific tools the agent is allowed to use. If not set, all available tools are enabled (subject to other flags like FILESYSTEM_ACCESS).None (All allowed)

​
MCP (Model Context Protocol)

Settings for the Model Context Protocol integration.
VariableDescriptionDefault
ENABLE_MCP_SSEEnable MCP servers via Server-Sent Events (SSE).True
ENABLE_MCP_STDIOEnable MCP servers via Standard I/O (stdio).False

​
Next Steps