LogalDeveloper/Owlbot
0
Fork 0
Code Issues 13 Actions Packages Releases 3 Wiki Activity
Page: Configuration
Pages
Clips Command Reference Configuration Custom Commands Emoji Wall Home Logging Modules Commands Modules Config Modules Context Modules Events Modules HTTP Client Modules Lifecycle Modules Logger Modules Owncast API Modules Routes Modules Storage Modules Testing Modules Polls Quotes Timers
Clone
8
Configuration
Logan Fick edited this page 2026-04-04 18:39:10 -04:00
Table of Contents

Configuration

All configuration lives in a single YAML file (default config.yaml). It has three top-level sections: owlbot for core bot settings, owncast for the Owncast server connection, and modules for per-module settings.

Run owlbot init to generate a default config.yaml if one does not already exist, then adjust the values for your setup.

Configuration Priority

Both owlbot and owncast settings can be configured in the config file, environment variables, or CLI flags. When the same setting is specified in multiple places, the highest-priority source wins:

  1. CLI flag (highest)
  2. Environment variable
  3. Config file
  4. Default value (lowest)

Module settings are config-file-only and do not support environment variables or CLI flags.

CLI-Only Flags

These flags control runtime behavior and exist outside the priority hierarchy. They do not correspond to config file settings.

Flag Description
-c, --config Path to config file (default: config.yaml).
-v, --verbose Enable verbose (DEBUG) logging.
--skip-api-check Skip Owncast API accessibility checks during startup.
--webhook-path Print the full webhook URL from config and exit.
--version Print the Owlbot version and exit.

Owlbot Settings

These control the bot's web server, command system, storage, and handler behavior.

owlbot:
  host: "127.0.0.1"
  port: 8081
  command_prefix: "!"
  handler_timeout: 30.0
  storage_dir: "data"
  modules_dir: "modules"
  log_dir: ""
  webhook_secret: ""
  public_base_url: ""
Key Default Env Var CLI Flag Description
host "127.0.0.1" OWLBOT_HOST --host Address to bind the web server. Set to "0.0.0.0" to listen on all interfaces.
port 8081 OWLBOT_PORT --port Port for the web server.
command_prefix "!" OWLBOT_COMMAND_PREFIX Prefix character for chat commands (e.g., !help).
handler_timeout 30.0 OWLBOT_HANDLER_TIMEOUT Maximum seconds a handler can run before it is cancelled.
storage_dir "data" OWLBOT_STORAGE_DIR -s, --storage-dir Directory for per-module SQLite database files. Each module gets a <module_name>.db file here. Relative paths are resolved from the working directory.
modules_dir "modules" OWLBOT_MODULES_DIR -m, --modules Directory for user-written modules. Built-in modules are loaded from the package regardless of this setting. Relative paths are resolved from the working directory.
log_dir (unset) OWLBOT_LOG_DIR -l, --log-dir Directory for the owlbot.log file. When set, logs are written to this directory in addition to stdout. When unset, logs go to stdout only.
webhook_secret (auto-generated) OWLBOT_WEBHOOK_SECRET Secret token for the webhook URL path (/webhook/<secret>). A cryptographically secure value is generated on first run and saved back to the config file automatically.
public_base_url owncast.url OWLBOT_PUBLIC_BASE_URL Public base URL for generated links (e.g., "https://owlbot.example.com"). Set this if Owlbot is hosted on a different domain than your Owncast instance.

Owncast Settings

These configure how Owlbot connects to the Owncast server.

owncast:
  url: ""
  access_token: ""
  admin:
    enabled: false
    username: "admin"
    password: "abc123"
Key Default Env Var Description
url required OWLBOT_OWNCAST_URL Base URL of your Owncast server. Used to connect to the Owncast API.
access_token "" OWLBOT_OWNCAST_ACCESS_TOKEN Integration API token. Generate one in Owncast Admin under Integrations > Access Tokens. Required for sending messages, hiding messages, listing clients, etc.
admin.enabled false OWLBOT_OWNCAST_ADMIN_ENABLED Enable the optional Admin API client, which grants modules access to more parts of Owncast than what the main integrations API allows.
admin.username "admin" OWLBOT_OWNCAST_ADMIN_USERNAME Username for Owncast Admin API authentication.
admin.password "abc123" OWLBOT_OWNCAST_ADMIN_PASSWORD Password for Owncast Admin API authentication.

Module Settings

Per-module configuration lives under the modules key. Each subkey is a module name. Unlike Owlbot settings, module settings can only be configured in the config file. Environment variables and CLI flags are not supported for module configuration.

Enabling and Disabling Modules

Modules are enabled by default. To disable one, set enabled: false under its name:

modules:
  ping:
    enabled: false

Module-Specific Keys

Modules may add their own config keys under their name. These appear in the config file after the module's first run:

modules:
  custom_commands:
    enabled: true
    max_nesting_depth: 4

Clips

Key Default Description
cache_duration 300 How far back (in seconds) viewers can clip from the live stream.
min_clip_length 5 Minimum clip length in seconds.
max_clip_length 120 Maximum clip length in seconds.
clips_dir "data/clips" Directory where saved clip files are stored.
session_expiry 900 Seconds before a clip editing session expires if unused.
grace_period 120 Seconds to keep stream footage available after the stream stops.

Custom Commands

Key Default Description
default_cooldown 5 Default cooldown in seconds for newly created custom commands.
max_nesting_depth 4 Maximum nesting depth for placeholders in command responses.

Built-in Modules

Creating New Modules