Runtime Config

Freesona exposes a set of runtime-mutable configuration keys you can change live with /config commands. These persist across restarts in config.json and take effect immediately. No bot restart is required.

Using /config Commands

/config list                               — list all keys with descriptions
/config show                               — show all current values
/config show mvsep_poll_interval           — show one specific key
/config set generation_rate_limit 2.0      — update a value
/config reset generation_rate_limit        — reset to default

All /config commands are restricted to the Bot Owner.

All Configurable Keys

Values are automatically type-converted based on the default type for each key (int, float, bool, or string). Invalid values are rejected with an error message.

Key	Type	Default	Description
`prefix`	string	`~`	Command prefix for text commands
`conversation_response_mode`	string	`all`	How the bot responds in conversations: `all`, `mention`, `reply`
`provider`	string	`gemini`	AI provider to use: `gemini`, `openai`, `ollama`, `nim`, `azure`, `groq`, `openrouter`
`provider_model`	string	“	Model name for the selected provider (empty = use env default)
`chroma_collection`	string	`freesona`	ChromaDB collection name
`chroma_persist_directory`	string	`./.chroma`	ChromaDB persistence directory
`debounce_seconds`	float	`1.2`	Debounce time for message processing in seconds
`autonomy_cooldown_seconds`	int	`120`	Cooldown between autonomous actions in seconds
`autonomy_user_cooldown`	int	`60`	Per-user cooldown for autonomous actions in seconds
`mvsep_poll_interval`	int	`10`	Seconds between MVSEP API polling checks
`mvsep_poll_timeout`	int	`600`	Max seconds to wait for MVSEP task completion
`ytdlp_subprocess_timeout`	int	`300`	Max seconds for yt-dlp subprocess to complete
`ytdlp_compress_target_mb`	float	`9.5`	Target size in MB for video compression
`generation_split_min_length`	int	`280`	Minimum message length before splitting into segments
`generation_split_delay_base`	float	`1.2`	Base delay in seconds between message segments
`generation_split_delay_per_char`	float	`0.012`	Additional delay per character in segment
`generation_split_delay_max`	float	`3.5`	Maximum delay between segments in seconds
`generation_rate_limit`	float	`5`	Minimum seconds between AI generation calls
`model_temperature`	float	`0.7`	Sampling temperature for AI generation
`log_enabled`	bool	`false`	Enable optional logging
`log_channel_id`	int	`0`	Discord channel ID for log messages (0 = disabled)
`log_level`	string	`INFO`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`log_file_path`	string	`logs/freesona.log`	Log file path with monthly rotation
`log_file_max_months`	int	`3`	Log file rotation period in months
`log_include_discord`	bool	`true`	Also send logs to Discord channel
`log_section_general`	bool	`true`	Log general bot events (startup, shutdown, cogs)
`log_section_config`	bool	`false`	Log configuration changes
`log_section_ai`	bool	`true`	Log AI provider calls, generation, prompts
`log_section_memory`	bool	`false`	Log memory operations (conversation, facts, character, KB)
`log_section_media`	bool	`false`	Log media operations (MVSEP, yt-dlp, search)
`log_section_moderation`	bool	`false`	Log moderation actions (kick, ban, warn)
`log_section_security`	bool	`true`	Log security checks (injection detection, URL validation)
`log_section_webhook`	bool	`false`	Log webhook events (FastAPI/MVSEP)

Notes on Specific Keys

generation_rate_limit — Increase this on free-tier AI provider plans to avoid rate limit errors. The default of 5 works well for most paid tiers. Example: /config set generation_rate_limit 3.0.
ytdlp_compress_target_mb — Keep this below Discord’s upload limit (10 MB for free servers). Reduce it if you are seeing file-too-large errors after compression. Example: /config set ytdlp_compress_target_mb 8.0.
mvsep_poll_timeout — Increase this for very long audio files if the bot times out before MVSEP finishes the separation job. Example: /config set mvsep_poll_timeout 600.
generation_split_min_length — If the AI produces very long responses and you want them split into smaller chunks earlier, reduce this value. Example: /config set generation_split_min_length 1500.
model_temperature — Controls randomness in AI generation. Lower values (0.1–0.3) make output more deterministic; higher values (0.8–1.5) increase creativity. Default is 0.7. Example: /config set model_temperature 0.9.

config.json Managed Fields

Beyond the /config keys above, config.json also stores bot state that other commands manage. You do not edit these directly — use the Discord commands listed below.

Key	Set by
`prefix`	`~prefix <symbol>`
`chat_channel_id`	`/setchannel`
`conversation_response_mode`	`/chatmode <all/mention/reply>`
`provider`	`/provider set <name>`
`provider_model`	`/model set <name>`
`model_name`	`/model set <name>`
`model_temperature`	`/model temperature <value>`
`timezone`	`/settimezone <timezone>`
`enabled_modules`	`/module enable <name>` / `/module disable <name>`
`whitelist_bot_ids`	`/botwhitelist add <bot_id>` / `/botwhitelist remove <bot_id>`
`rss_feeds`	`/rss add <name> <url>` / `/rss remove <name>`
`log_*`	`/logging` command group

config.json is loaded fresh on every command call to avoid stale state across module reloads. Do not edit it manually while the bot is running. Use the Discord commands above so changes are validated and applied cleanly.

Get Started

Features

Guides

Reference

Changelog

Using /config Commands

All Configurable Keys

Notes on Specific Keys

config.json Managed Fields

​Using /config Commands

​All Configurable Keys

​Notes on Specific Keys

​config.json Managed Fields

Using /config Commands

All Configurable Keys

Notes on Specific Keys

config.json Managed Fields