⚙️ Configuration

Config File Structure

VexAI stores its configuration in data/config.json. The file is auto-created on first boot with all default values when you run the setup wizard. The schema is validated at startup using Zod, so any invalid values will prevent the bot from starting.

Complete Example

{
  "discord": {
    "token": "MTIz...your-bot-token",
    "adminUserIds": ["123456789012345678"]
  },
  "llm": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "gpt-4o",
    "baseUrl": "https://api.openai.com/v1"
  },
  "security": {
    "enabled": true,
    "exemptTools": [],
    "alertChannelId": "987654321098765432",
    "llm": {
      "provider": "openai",
      "apiKey": "sk-...",
      "model": "gpt-4o-mini"
    }
  },
  "conversationWindow": 50,
  "integrations": {
    "webhookServer": {
      "enabled": false,
      "port": 3847,
      "baseUrl": "https://hooks.example.com"
    },
    "github": {
      "token": "ghp_..."
    },
    "openmail": {
      "enabled": false,
      "apiKey": "om_...",
      "inboxId": "inbox-id",
      "approvalChannelId": "111222333444555666",
      "autoCreateApprovalChannel": true,
      "wsEnabled": false
    }
  },
  "voice": {
    "enabled": false,
    "tts": {
      "enabled": false,
      "provider": "openai",
      "apiKey": "sk-...",
      "model": "tts-1",
      "voice": "alloy"
    },
    "stt": {
      "enabled": false,
      "provider": "whisper-api",
      "apiKey": "sk-...",
      "model": "whisper-1"
    },
    "assistant": {
      "enabled": false,
      "wakeWord": "hey vex",
      "wakeAliases": [],
      "respondWithText": false,
      "maxHistoryTurns": 10,
      "idleTimeout": 300
    }
  },
  "database": {
    "type": "sqlite",
    "url": "postgresql://user:pass@localhost:5432/vexai",
    "pool": { "min": 2, "max": 10 }
  },
  "embeddings": {
    "enabled": false,
    "provider": "builtin",
    "model": "Xenova/all-MiniLM-L6-v2",
    "dimensions": 384,
    "batchSize": 50
  },
  "subAgents": { "enabled": false },
  "workflows": { "enabled": false },
  "thinking": {
    "enabled": true,
    "pollIntervalMs": 4000,
    "model": null
  }
}

Runtime Configuration Commands

VexAI exposes a /config slash command for live configuration management without editing files.

Examples

# View the full config (masked)
/config view

# View just the voice section
/config view voice

# Change the LLM model
/config set llm.model gpt-4o

# Enable the security observer
/config set security.enabled true

# Reset conversation window to default (50)
/config reset conversationWindow

All Configuration Paths

Complete reference for every configurable path. Paths use dot notation for nested values. A dash (-) in the Default column means the value is required or has no default.

Discord

LLM

Security

Security LLM

Optional separate LLM provider for the security observer. If omitted, the main LLM is used.

General

Webhooks

GitHub

OpenMail

Voice

TTS (Text-to-Speech)

STT (Speech-to-Text)

Voice Assistant

Database

Embeddings

Sub-Agents

Workflows

Thinking

Voice Configuration Example

Full voice setup with local TTS (Kokoro), local STT (faster-whisper), and the voice assistant.

{
  "voice": {
    "enabled": true,
    "tts": {
      "enabled": true,
      "provider": "local",
      "baseUrl": "http://localhost:8880",
      "model": "kokoro",
      "voice": "af_heart"
    },
    "stt": {
      "enabled": true,
      "provider": "local",
      "baseUrl": "http://localhost:8000",
      "model": "large-v3-turbo"
    },
    "assistant": {
      "enabled": true,
      "wakeWord": "hey vex",
      "wakeAliases": ["yo vex", "okay vex"],
      "respondWithText": true,
      "textChannelId": "123456789012345678",
      "maxHistoryTurns": 15,
      "idleTimeout": 600
    }
  }
}

Provider Comparison

Database & Embeddings

VexAI supports SQLite (default, zero-config) and PostgreSQL for multi-instance deployments. Embeddings enable semantic search over conversation history and documents.

{
  "database": {
    "type": "sqlite"
  },
  "embeddings": {
    "enabled": true,
    "provider": "builtin",
    "model": "Xenova/all-MiniLM-L6-v2",
    "dimensions": 384,
    "batchSize": 50
  }
}

{
  "database": {
    "type": "postgres",
    "url": "postgresql://vexai:secret@localhost:5432/vexai",
    "pool": {
      "min": 2,
      "max": 10
    }
  },
  "embeddings": {
    "enabled": true,
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "text-embedding-3-small",
    "dimensions": 1536,
    "batchSize": 100,
    "dailyLimit": 10000
  }
}

Embedding Provider Comparison

Integration Configuration

Webhook Server

The inbound webhook server lets external services trigger VexAI actions via HTTP.

{
  "integrations": {
    "webhookServer": {
      "enabled": true,
      "port": 3847,
      "baseUrl": "https://hooks.example.com"
    }
  }
}

GitHub

A personal access token enables GitHub tools (repository management, issue tracking, PR reviews).

{
  "integrations": {
    "github": {
      "token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}

OpenMail

OpenMail integration adds email management with approval workflows, including send, reply, and manage emails through Discord.

{
  "integrations": {
    "openmail": {
      "enabled": true,
      "apiKey": "om_xxxxxxxxxxxxxxxxxxxx",
      "inboxId": "inbox_abc123",
      "approvalChannelId": "111222333444555666",
      "autoCreateApprovalChannel": true,
      "wsEnabled": true
    }
  }
}