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_ID | Your numeric Telegram user ID. Set to * to allow everyone. Empty = deny all |
| Variable | Default | Description |
|---|
LOG_LEVEL | INFO | Python log level (DEBUG, INFO, WARNING, ERROR) |
DATA_DIR | data/users | Directory for file-based user data storage |
DATABASE_URL | postgresql://clawbolt:clawbolt@localhost:5432/clawbolt | PostgreSQL connection URL |
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) |
REASONING_EFFORT | auto | Reasoning effort level: none, minimal, low, medium, high, xhigh, or auto |
VISION_MODEL | (same as LLM_MODEL) | Model to use for image/document analysis. Falls back to LLM_MODEL if not set |
VISION_PROVIDER | (same as LLM_PROVIDER) | Provider for the vision model. Falls back to LLM_PROVIDER 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 | Default messaging backend. Telegram and iMessage channels can run simultaneously; only one iMessage backend (Linq OR BlueBubbles) may be configured at a time |
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_ID | (empty) | Your numeric Telegram user ID, or * to allow all. Only a single ID is allowed per user. Empty = deny all |
Clawbolt’s user-facing “iMessage” channel is powered by one of two interchangeable
backends. Choose one: configuring both at once will cause the app to refuse to start.
End users see a single “iMessage” option regardless of which backend you pick.
| Variable | Default | Description |
|---|
LINQ_API_TOKEN | | Linq Partner API V3 bearer token |
LINQ_FROM_NUMBER | | Your Linq-provisioned phone number in E.164 format |
LINQ_WEBHOOK_SIGNING_SECRET | | HMAC signing secret from webhook subscription creation |
LINQ_ALLOWED_NUMBERS | (empty) | E.164 phone number, * for all, or empty to deny all |
LINQ_PREFERRED_SERVICE | iMessage | Preferred messaging service: iMessage, SMS, or RCS |
When LINQ_API_TOKEN is set, the iMessage channel is powered by Linq and users can text their assistant from their phone’s native messaging app. Linq provides iMessage, RCS, and SMS access via linqapp.com.
| Variable | Default | Description |
|---|
BLUEBUBBLES_SERVER_URL | | URL of your BlueBubbles server (e.g. https://my-mac.ngrok.io) |
BLUEBUBBLES_PASSWORD | | BlueBubbles server password (used as query param for API auth) |
BLUEBUBBLES_ALLOWED_NUMBERS | (empty) | E.164 phone number or email, * for all, or empty to deny all |
BLUEBUBBLES_SEND_METHOD | apple-script | Send method: apple-script (default) or private-api |
BLUEBUBBLES_IMESSAGE_ADDRESS | (empty) | iCloud email or phone number displayed in the UI for users to text |
When BLUEBUBBLES_SERVER_URL and BLUEBUBBLES_PASSWORD are set, the iMessage channel is powered by BlueBubbles. BlueBubbles is a free, open-source iMessage bridge that runs on any Mac with iMessage signed in.
| 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) |
CLAWBOLT_DATA_DIR | ./data | Host path bind-mounted to /app/data (Docker Compose only) |
FILE_STORAGE_BASE_DIR | data/storage | Base directory for local file storage |
See Storage Providers for setup instructions.
| 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 |
|---|
APPROVAL_TIMEOUT_SECONDS | 120 | Seconds to wait for user approval of a tool call before automatically denying |
AGENT_PROCESSING_TIMEOUT_SECONDS | 300 | Maximum seconds for a single message’s agent processing (includes waiting for the per-user lock). Prevents one hung LLM call from blocking all subsequent messages for the same user |
MESSAGE_BATCH_WINDOW_MS | 1500 | Milliseconds to wait for more messages before processing. Groups rapid-fire messages into one agent call. Set to 0 to disable |
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 |
LLM_MAX_RETRIES | 3 | Maximum number of retry attempts on rate limit errors |
| Variable | Default | Description |
|---|
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 |
| 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_DEFAULT_FREQUENCY | 30m | Default check-in frequency shown to new users (e.g. 15m, 1h, daily) |
HEARTBEAT_INTERVAL_MINUTES | 30 | Minutes between heartbeat evaluation ticks |
HEARTBEAT_MAX_DAILY_MESSAGES | 5 | Max proactive messages per user 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_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 user evaluations per tick |
HEARTBEAT_RECENT_MESSAGES_COUNT | 5 | Number of recent messages included in heartbeat context |
| Variable | Default | Description |
|---|
LOG_REQUEST_TIMING | false | Log method, path, status code, and duration for every HTTP request |
| Variable | Default | Description |
|---|
APP_BASE_URL | http://localhost:8000 | Public URL where the server is reachable, used for OAuth callback URLs |
ENCRYPTION_KEY | | Encrypts OAuth tokens at rest in the database. Generate with python -c "import secrets; print(secrets.token_urlsafe(32))". Required for production. |
| Variable | Default | Description |
|---|
QUICKBOOKS_CLIENT_ID | | OAuth client ID from the Intuit developer console |
QUICKBOOKS_CLIENT_SECRET | | OAuth client secret from the Intuit developer console |
QUICKBOOKS_ENVIRONMENT | sandbox | sandbox for testing or production for live data |
When QUICKBOOKS_CLIENT_ID and QUICKBOOKS_CLIENT_SECRET are set, users can connect their QuickBooks account via the web dashboard. Once connected, the agent gains specialist QuickBooks tools (qb_query, qb_create, qb_update, qb_send).
| Variable | Default | Description |
|---|
GOOGLE_CALENDAR_CLIENT_ID | | OAuth client ID from the Google Cloud console |
GOOGLE_CALENDAR_CLIENT_SECRET | | OAuth client secret from the Google Cloud console |
When GOOGLE_CALENDAR_CLIENT_ID and GOOGLE_CALENDAR_CLIENT_SECRET are set, users can connect their Google Calendar via the web dashboard. Once connected, the agent gains specialist calendar tools (calendar_list_events, calendar_create_event, calendar_update_event, calendar_delete_event, calendar_check_availability).
| Variable | Default | Description |
|---|
COMPANYCAM_CLIENT_ID | | CompanyCam OAuth 2.0 client ID. Register at docs.companycam.com/docs/oauth |
COMPANYCAM_CLIENT_SECRET | | CompanyCam OAuth 2.0 client secret |
When both are set, users can connect CompanyCam via OAuth on the Tools page or through chat. This enables tools like companycam_search_projects, companycam_upload_photo, and companycam_create_project.
| Variable | Default | Description |
|---|
SERPAPI_API_KEY | | SerpApi API key for Home Depot product price lookups. Free tier: 250 searches/month at serpapi.com |
When SERPAPI_API_KEY is set, the agent gains a supplier_search_products specialist tool that looks up Home Depot product prices, ratings, and links by keyword and zip code.
| 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) |
