Skip to main content
The config.yaml file is the main configuration file for Agentic AI. It defines all service connections, behavior settings, and integrations.

​
File Location

By default, the config file is loaded from:
  • ./config.yaml in your current directory
  • Or specify a custom path: agenticai server --config /path/to/config.yaml

​
Configuration Structure

The config file is organized into logical sections for each service and feature.

​
Twilio Configuration

Controls how Agentic AI connects to Twilio for phone calls. 
twilio:
  account_sid: ${TWILIO_ACCOUNT_SID}
  auth_token: ${TWILIO_AUTH_TOKEN}
  from_number: ${TWILIO_PHONE_NUMBER:+1XXXXXXXXXX}
​
twilio.account_sid
string
required
Your Twilio Account SID from environment variable.References: ${TWILIO_ACCOUNT_SID}
​
twilio.auth_token
string
required
Your Twilio Auth Token from environment variable.References: ${TWILIO_AUTH_TOKEN}
​
twilio.from_number
string
required
The phone number to make calls from (E.164 format).References: ${TWILIO_PHONE_NUMBER:+1XXXXXXXXXX}Example: +15551234567

​
Gemini Configuration

Controls the Gemini AI model for intent analysis and system instructions. 
gemini:
  api_key: ${GEMINI_API_KEY}
  model: "models/gemini-2.5-flash-native-audio-latest"
  voice: "Zephyr"
  system_instruction: |
    You are a helpful AI assistant making phone calls on behalf of the user.
    Be concise, professional, and friendly. Listen carefully and respond appropriately.
    When the conversation is complete, summarize any key information or action items.
​
gemini.api_key
string
required
Your Gemini API key from environment variable.References: ${GEMINI_API_KEY}
​
gemini.model
string
default:"models/gemini-2.5-flash-native-audio-latest"
The Gemini model to use for intent analysis.Available models:
  • models/gemini-2.5-flash-native-audio-latest (recommended)
  • models/gemini-2.5-flash-preview-native-audio-dialog
​
gemini.voice
string
default:"Zephyr"
The voice for Gemini TTS (when not using OpenAI Realtime).Available voices: Zephyr, Coral, Breeze, Nova
​
gemini.system_instruction
string
The system prompt that defines the AI’s behavior and personality.This is used for intent analysis and determining what actions to take.Example:
system_instruction: |
  You are a helpful AI assistant.
  Analyze user requests and determine if they require ClawdBot execution.

​
Telegram Configuration

Controls real-time transcript delivery to Telegram. 
telegram:
  enabled: true
  bot_token: ${TELEGRAM_BOT_TOKEN}
  chat_id: ${TELEGRAM_CHAT_ID}
​
telegram.enabled
boolean
default:true
Enable or disable Telegram integration.Set to false to disable sending transcripts to Telegram.
​
telegram.bot_token
string
required
Your Telegram bot token from environment variable.References: ${TELEGRAM_BOT_TOKEN}
​
telegram.chat_id
string
required
The Telegram chat ID where transcripts will be sent.References: ${TELEGRAM_CHAT_ID}

​
Gateway Configuration

Controls connection to the OpenClaw Gateway for ClawdBot integration. 
gateway:
  url: "ws://127.0.0.1:18789"
  reconnect_max_attempts: 10
  reconnect_base_delay: 1.0
  reconnect_max_delay: 60.0
​
gateway.url
string
default:"ws://127.0.0.1:18789"
The WebSocket URL of the OpenClaw Gateway.Default assumes ClawdBot Gateway is running locally on port 18789.For remote gateways: ws://remote-host:18789
​
gateway.reconnect_max_attempts
integer
default:10
Maximum number of reconnection attempts if the gateway disconnects.Set to -1 for unlimited attempts.
​
gateway.reconnect_base_delay
float
Initial delay in seconds before first reconnection attempt.Uses exponential backoff: base_delay * 2^attempt
​
gateway.reconnect_max_delay
float
Maximum delay in seconds between reconnection attempts.Caps the exponential backoff to prevent extremely long waits.

​
Server Configuration

Controls the FastAPI server that handles Twilio webhooks and WebSocket connections. 
server:
  host: "0.0.0.0"
  port: 8080
  webhook_path: "/twilio/voice"
  websocket_path: "/twilio/media-stream"
​
server.host
string
default:"0.0.0.0"
The host to bind the server to.
  • 0.0.0.0 - Listen on all interfaces (default)
  • 127.0.0.1 - Listen only on localhost
​
server.port
integer
default:8080
The port to run the server on.Must match the port in your tunnel configuration.
​
server.webhook_path
string
default:"/twilio/voice"
The URL path for Twilio voice webhooks.Full webhook URL: https://your-tunnel-url.com/twilio/voice
​
server.websocket_path
string
default:"/twilio/media-stream"
The URL path for Twilio Media Streams WebSocket.Full WebSocket URL: wss://your-tunnel-url.com/twilio/media-stream

​
Logging Configuration

Controls logging output format and level. 
logging:
  level: "INFO"
  format: "json"
​
logging.level
string
default:"INFO"
The log level to use.Options:
  • DEBUG - Very verbose, all details
  • INFO - Standard operation logs (recommended)
  • WARNING - Only warnings and errors
  • ERROR - Only errors
  • CRITICAL - Only critical errors
​
logging.format
string
default:"json"
The format for log output.Options:
  • json - Structured JSON logs (recommended for production)
  • console - Human-readable console output (good for development)

​
Tunnel Configuration

Controls automatic tunnel setup for public webhook URLs. 
tunnel:
  enabled: false
  provider: "ngrok"
  url: ${NGROK_URL:}
​
tunnel.enabled
boolean
default:false
Enable automatic tunnel startup.
Set to true only if you want Agentic AI to manage the tunnel process.
Most users should start tunnels manually and set enabled: false.
​
tunnel.provider
string
default:"ngrok"
The tunnel provider to use.Options:
  • ngrok - Use ngrok (most common)
  • cloudflare - Use Cloudflare Tunnel
See Tunnel Setup for detailed instructions.
​
tunnel.url
string
A fixed tunnel URL (if using paid plans with reserved domains).References: ${NGROK_URL:} (empty default if not set)Example: https://myapp.ngrok.ioIf empty, tunnel will generate a random URL each time.

​
Whisper Configuration

Controls OpenAI Whisper for speech-to-text transcription. 
whisper:
  enabled: false
  api_key: ${OPENAI_API_KEY:}
  model: "whisper-1"
Whisper is automatically disabled when using OpenAI Realtime API, which has built-in Whisper transcription.
​
whisper.enabled
boolean
default:false
Enable standalone Whisper for accurate STT.Only needed if NOT using OpenAI Realtime API.
​
whisper.api_key
string
OpenAI API key for Whisper.References: ${OPENAI_API_KEY:} (optional)
​
whisper.model
string
default:"whisper-1"
The Whisper model to use.Currently only whisper-1 is available.

​
OpenAI Realtime Configuration

Controls the OpenAI Realtime API for natural voice conversations. 
openai_realtime:
  enabled: true
  api_key: ${OPENAI_API_KEY}
  model: "gpt-4o-realtime-preview-2024-12-17"
  voice: "alloy"
​
openai_realtime.enabled
boolean
default:true
Enable OpenAI Realtime API as the primary voice engine.When enabled, this replaces Gemini Live for voice conversations.
Requires access to OpenAI Realtime API (gpt-4o-realtime)
​
openai_realtime.api_key
string
required
OpenAI API key for Realtime API.References: ${OPENAI_API_KEY}
​
openai_realtime.model
string
default:"gpt-4o-realtime-preview-2024-12-17"
The OpenAI Realtime model to use.Current available model:
  • gpt-4o-realtime-preview-2024-12-17
​
openai_realtime.voice
string
default:"alloy"
The voice to use for OpenAI TTS.See Voice Options for all available voices and their characteristics.

​
Complete Example

Here’s a complete config.yaml file with all sections: 
# Agentic AI Configuration
# Environment variables can be referenced with ${VAR_NAME}

twilio:
  account_sid: ${TWILIO_ACCOUNT_SID}
  auth_token: ${TWILIO_AUTH_TOKEN}
  from_number: ${TWILIO_PHONE_NUMBER:+1XXXXXXXXXX}

gemini:
  api_key: ${GEMINI_API_KEY}
  model: "models/gemini-2.5-flash-native-audio-latest"
  voice: "Zephyr"
  system_instruction: |
    You are a helpful AI assistant making phone calls on behalf of the user.
    Be concise, professional, and friendly. Listen carefully and respond appropriately.
    When the conversation is complete, summarize any key information or action items.

telegram:
  enabled: true
  bot_token: ${TELEGRAM_BOT_TOKEN}
  chat_id: ${TELEGRAM_CHAT_ID}

gateway:
  url: "ws://127.0.0.1:18789"
  reconnect_max_attempts: 10
  reconnect_base_delay: 1.0
  reconnect_max_delay: 60.0

server:
  host: "0.0.0.0"
  port: 8080
  webhook_path: "/twilio/voice"
  websocket_path: "/twilio/media-stream"

logging:
  level: "INFO"
  format: "json"

tunnel:
  enabled: false
  provider: "ngrok"
  url: ${NGROK_URL:}

whisper:
  enabled: false
  api_key: ${OPENAI_API_KEY:}
  model: "whisper-1"

openai_realtime:
  enabled: true
  api_key: ${OPENAI_API_KEY}
  model: "gpt-4o-realtime-preview-2024-12-17"
  voice: "alloy"

​
Loading Configuration

Configuration is loaded automatically when you run: 
agenticai server
Or specify a custom config file: 
agenticai server --config /path/to/config.yaml

​
Configuration Validation

The configuration is validated using Pydantic models at startup. If any required fields are missing or invalid, you’ll see a clear error message. See config.py:18-111 for the validation schemas.

​
Troubleshooting

​
Config file not found

# Check if config.yaml exists
ls -la config.yaml

# Or specify explicit path
agenticai server --config ./config.yaml

​
Environment variables not expanding

If you see ${VAR_NAME} literally in error messages:
  • Check that variables are set in .env
  • Verify the .env file is in the correct location
  • Check for typos in variable names (case-sensitive)

​
Invalid configuration

If you see Pydantic validation errors:
  • Check that all required fields are present
  • Verify data types (strings, numbers, booleans)
  • Check YAML syntax (indentation, colons, quotes)

Build docs developers (and LLMs) love

Get started for freeTalk to us