Clawbolt is configured via environment variables. Copy .env.example to .env and fill in the values.
All available settings are listed in .env.example with defaults and comments. This page documents every setting by category.
| Variable | Description |
|---|
TELEGRAM_BOT_TOKEN | Telegram bot token from @BotFather |
LLM_PROVIDER | Provider name (any provider supported by any-llm) |
LLM_MODEL | Model identifier for the agent loop (e.g. the model name your provider expects) |
| LLM API key | The API key env var for your chosen provider (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY) |
TELEGRAM_ALLOWED_CHAT_IDS or TELEGRAM_ALLOWED_USERNAMES | Who can message the bot. Set to * to allow everyone, or a comma-separated list. Empty = deny all |
| Variable | Default | Description |
|---|
LOG_LEVEL | INFO | Python log level (DEBUG, INFO, WARNING, ERROR) |
CORS_ORIGINS | http://localhost:3000,http://localhost:8000 | Comma-separated list of allowed CORS origins |
JWT_SECRET | change-me-in-production | Secret key for JWT signing. Change this in production |
JWT_EXPIRY_MINUTES | 15 | JWT token expiry time in minutes |
PREMIUM_PLUGIN | (empty) | Python import path for premium auth plugin. Leave empty for OSS single-tenant mode |
| Variable | Default | Description |
|---|
LLM_PROVIDER | (required) | LLM provider name (any provider supported by any-llm) |
LLM_MODEL | (required) | Model to use for the agent loop |
LLM_API_BASE | (none) | Custom API base URL (e.g. http://localhost:1234/v1 for LM Studio) |
VISION_MODEL | (same as LLM_MODEL) | Model to use for image/document analysis. Falls back to LLM_MODEL if not set |
ANY_LLM_KEY | | any-llm.ai managed platform key (replaces individual provider keys) |
Set the API key env var for your chosen provider, or set ANY_LLM_KEY to use the any-llm.ai managed platform as a key vault for all providers.
| Variable | Default | Description |
|---|
MESSAGING_PROVIDER | telegram | Messaging backend (currently only telegram is supported) |
TELEGRAM_BOT_TOKEN | | Bot token from @BotFather |
TELEGRAM_WEBHOOK_SECRET | (auto-derived) | Webhook validation secret. Auto-derived from bot token if not set |
TELEGRAM_ALLOWED_CHAT_IDS | (empty) | Comma-separated allowlist of Telegram chat IDs, or * to allow all. Empty = deny all |
TELEGRAM_ALLOWED_USERNAMES | (empty) | Comma-separated allowlist of Telegram usernames, or * to allow all. Empty = deny all |
| Variable | Default | Description |
|---|
STORAGE_PROVIDER | local | Storage backend: local, dropbox, or google_drive |
DROPBOX_ACCESS_TOKEN | | Dropbox access token (when using Dropbox) |
GOOGLE_DRIVE_CREDENTIALS_JSON | | Google Drive OAuth credentials JSON (when using Google Drive) |
PDF_STORAGE_DIR | data/estimates | Directory for generated PDF estimates |
FILE_STORAGE_BASE_DIR | data/storage | Base directory for local file storage |
DEFAULT_ESTIMATE_TERMS | Payment due within 30 days of project completion. | Default terms printed on estimates |
See Storage Providers for setup instructions.
| Variable | Default | Description |
|---|
DATABASE_URL | | PostgreSQL connection string. Set automatically by Docker Compose |
When running with Docker Compose, the DATABASE_URL is set automatically. You don’t need to configure it.
| Variable | Default | Description |
|---|
LLM_MAX_TOKENS_AGENT | 500 | Max tokens per agent loop LLM response |
LLM_MAX_TOKENS_HEARTBEAT | 300 | Max tokens per heartbeat LLM response |
LLM_MAX_TOKENS_VISION | 1000 | Max tokens per vision/image analysis response |
| Variable | Default | Description |
|---|
WHISPER_MODEL_SIZE | base | faster-whisper model size (tiny, base, small, medium, large) |
WHISPER_DEVICE | cpu | Device for inference (cpu or cuda) |
WHISPER_COMPUTE_TYPE | int8 | Quantization type (int8, float16, float32) |
| Variable | Default | Description |
|---|
MAX_TOOL_ROUNDS | 10 | Maximum tool-calling rounds per agent invocation |
MAX_INPUT_TOKENS | 120000 | Max input token budget before context trimming |
CONTEXT_TRIM_TARGET_TOKENS | 80000 | Target token count after trimming |
RATE_LIMIT_RETRY_DELAY | 2.0 | Seconds to wait before retrying after a rate limit |
| Variable | Default | Description |
|---|
CONVERSATION_TIMEOUT_HOURS | 4 | Hours of inactivity before starting a new conversation |
CONVERSATION_HISTORY_LIMIT | 20 | Max messages included in LLM context |
MEMORY_RECALL_LIMIT | 20 | Max memory facts recalled per query |
COMPACTION_ENABLED | true | Enable automatic conversation compaction |
COMPACTION_MODEL | (same as LLM_MODEL) | Model used for compaction |
COMPACTION_PROVIDER | (same as LLM_PROVIDER) | Provider used for compaction |
COMPACTION_MAX_TOKENS | 500 | Max tokens per compaction response |
HEARTBEAT_STALE_ESTIMATE_HOURS | 24 | Hours before an unsent estimate is considered stale |
| Variable | Default | Description |
|---|
WEBHOOK_RATE_LIMIT_MAX_REQUESTS | 30 | Max webhook requests per window |
WEBHOOK_RATE_LIMIT_WINDOW_SECONDS | 60 | Rate limit window in seconds |
RATE_LIMIT_TRUST_PROXY | false | Trust X-Forwarded-For for client IP (set true behind a reverse proxy) |
| Variable | Default | Description |
|---|
HEARTBEAT_ENABLED | true | Enable proactive check-in messages |
HEARTBEAT_INTERVAL_MINUTES | 30 | Minutes between heartbeat evaluation ticks |
HEARTBEAT_MAX_DAILY_MESSAGES | 5 | Max proactive messages per contractor per day |
HEARTBEAT_QUIET_HOURS_START | 20 | Hour (24h) to stop sending heartbeats |
HEARTBEAT_QUIET_HOURS_END | 7 | Hour (24h) to resume sending heartbeats |
HEARTBEAT_IDLE_DAYS | 3 | Days of inactivity before flagging a contractor |
HEARTBEAT_MODEL | (same as LLM_MODEL) | Model used for heartbeat messages |
HEARTBEAT_PROVIDER | (same as LLM_PROVIDER) | Provider used for heartbeat messages |
HEARTBEAT_CONCURRENCY | 5 | Max concurrent contractor evaluations per tick |
HEARTBEAT_RECENT_MESSAGES_COUNT | 5 | Number of recent messages included in heartbeat context |
CHECKLIST_DAILY_INTERVAL_HOURS | 20 | Hours between daily checklist heartbeat evaluations |
| Variable | Default | Description |
|---|
HTTP_TIMEOUT_SECONDS | 30.0 | Default timeout for outbound HTTP requests |
CLOUDFLARED_METRICS_TIMEOUT_SECONDS | 5.0 | Timeout for cloudflared tunnel metrics check |
TELEGRAM_WEBHOOK_TIMEOUT_SECONDS | 10.0 | Timeout for Telegram webhook registration |
| Variable | Default | Description |
|---|
MAX_MEDIA_SIZE_BYTES | 20971520 | Max upload size (20 MB default) |
