Configuration

AIO Agent is configured through aio_agent. If the Athena dashboard is enabled, use the dashboard first because the live config may be stored in MongoDB instead of only reading configuration/aio_agent.json5.

How Values Are Entered

Most customer-specific fields are free text in the dashboard so you can enter real values instead of being limited to a dropdown. This includes model names, API base URLs, docs URLs, knowledgebase paths, prompt file names, timezone values, locale values, and the forum thread header template.

Dropdowns are used only for true fixed choices such as mode, llm_provider, permission tiers, personality, moderation mode, moderation sensitivity, boolean toggles, and other enum-style settings.

Use Discord snowflake IDs for users, roles, and channels. Enable Developer Mode in Discord, right-click the item, then copy the ID.

Addon Configuration

Customer-specific addon configuration belongs under:

plugins/aio_agent/data/addons/<addon-id>/config.json5

Addon defaults are applied only when the normal AIO config does not already set that value. Dashboard/config values win over addon defaults. This lets updates keep customer addons intact while still letting server owners override settings from the normal AIO config.

See Addons for the addon manifest, API, and update rules.

Core

mode behavior:

LLM Provider

Separate reasoning profile

The reasoning profile can use a second provider, model, base URL, and API key for heavier tasks while normal chat and ticket replies continue using the primary profile. Blank provider/model/base URL values inherit the primary settings. A blank reasoning key uses AIO_AGENT_REASONING_API_KEY, the matching provider environment variable, or the primary key.

Prompt caching

Prompt caching depends on the provider and model. These options apply to the primary LLM and the optional reasoning profile according to the provider used for each request.

OpenAI uses a fixed 30-minute TTL for explicit caching. If explicit mode is selected with an older OpenAI model, AIO safely uses automatic caching instead. Gemini also falls back to an ordinary request when its provider rejects an explicit cache, including prompts below the model’s minimum cache size.

/aio usage shows cached-input and cache-write token counts. The dollar estimate uses the configured base input/output prices and does not include provider-specific cache discounts, write premiums, or cache-storage charges.

Environment variable priority:

1. AIO_AGENT_LLM_API_KEY
2. Provider-specific variable such as AIO_AGENT_OPENAI_API_KEY
3. llm_api_key
4. gemini_api_key when using Gemini

Provider-specific variables:

AIO_AGENT_LLM_API_KEY=...
AIO_AGENT_GEMINI_API_KEY=...
AIO_AGENT_OPENAI_API_KEY=...
AIO_AGENT_ANTHROPIC_API_KEY=...
AIO_AGENT_OPENROUTER_API_KEY=...

Recommended starting models:

Identity And Branding

Permission Tiers

AIO Agent resolves each speaker into one tier.

Abuse Protection

Repeated rate-limit, spam, or extreme-length strikes can automatically add a user to blocked_users.

Confirmations And Audit Logging

Recommended confirmed tools:

require_confirmation_for: [
  "ban_user",
  "unban_user",
  "kick_user",
  "delete_messages",
  "delete_role",
  "remove_warning",
  "set_channel_permissions",
  "delete_channel",
  "close_ticket",
  "run_athena_command"
]

For normal AI tool confirmations, only a valid button click approves the action. Plain text such as ok after a timeout does not approve an expired action.

Multi-Step Agent Limits

When a request reaches either limit, AIO stops safely and reports what it completed instead of claiming the entire task finished.

Personality And Context

Reply Modes And Smart Gate

Chat and tickets can use separate reply modes:

Smart is the default for both chat.response_mode and tickets.response_mode. It uses local rules first, so normal conversation, clear help, and direct calls using the bot’s username, nickname, or a configured alias do not require a classifier request. If an ambiguous message does need classification, AIO sends a short JSON-only request with limited history and fails closed when the provider is unavailable or unsure.

Classifier calls are included in /aio usage. The normal chat request limit still applies after Smart decides to answer. Direct mentions and intentional bot-name calls bypass the channel cooldown so they are not dropped behind an earlier response; per-user limits still apply.

Knowledgebase

AIO Agent can load knowledge from three places:

1. .md and .txt files in knowledgebase_dir
2. Built-in AthenaBot docs when athenabot_brain_enabled is true
3. Configured channel or forum snapshots from knowledgebase_channels

The plugin reads the sources on startup or /aio reload, stores them in memory, then builds a knowledgebase_block for each AI request. The request does not read the filesystem again unless you reload or restart.

Retrieval Mode

Mode guide:

Embeddings

Embeddings are optional. With the default config, search mode uses local token matching only and does not call a separate embedding API. Turn embeddings on when the knowledgebase is large enough that semantic matching is worth the extra API calls.

Default embedding models:

Embedding vectors are cached in plugins/aio_agent/data/cache/knowledgebase-embeddings.json. If the content changes, the source hash changes and stale cached vectors are not reused.

Recommended setups:

// Small knowledgebase, lowest complexity
knowledgebase_mode: "full"
 
// Normal customer knowledgebase
knowledgebase_mode: "search"
knowledgebase_search_top_k: 6
knowledgebase_search_max_chars: 12000
 
// Large knowledgebase with semantic rerank
knowledgebase_mode: "hybrid"
knowledgebase_embeddings_enabled: true
knowledgebase_embedding_provider: "llm"
knowledgebase_embedding_candidate_count: 30

Run this after changing files or channel knowledge:

/aio reload

Confirmed Memory

Confirmed memory lets authorized users say remember this, or lets AIO propose useful server facts from configured conversations. Every proposal is posted to the review channel and must be approved before it is written to the configured knowledgebase file. It only updates AIO’s own knowledge, terminology, personality, server facts, and support guidance; it cannot edit code, configuration, permissions, or unrelated systems.

After approval, AIO writes the memory safely and reloads its knowledgebase so new conversations can use it immediately.

Tickets

Ticket support requires AthenaBot’s tickets plugin.

Per-category overrides:

tickets: {
  category_settings: [
    {
      category_index: 0,
      tone: "friendly",
      custom_tone: "",
      handoff_phrases: ["staff please"],
      staff_notify_channel_id: "123456789012345678",
      staff_notify_user_ids: [],
      staff_notify_role_ids: ["123456789012345678"],
      staff_notify_on_handoff: true,
      staff_notify_pause_session: true,
      allow_ai_ticket_close: true,
      ticket_close_requires_confirmation: true,
      ticket_close_minimum_tier: "MODERATOR",
      ticket_close_allow_creator: true,
      ticket_close_approver_role_ids: []
    }
  ]
}

Ticket close behavior:

Expired close prompts cannot be approved with plain text. A user must send a new explicit close intent or click a fresh native button.

Strict Workflow

Strict workflow keeps ticket intake and staff notification deterministic. The model may still help with normal support replies, but it does not decide whether a brief is complete, whether staff were notified, or whether a handoff happened.

Default flow:

1. Customer asks what information is needed.
2. AIO sends the configured checklist and asks the first missing field.
3. Customer answers one field at a time or sends a larger brief.
4. AIO stores answers in workflowData.fields.
5. Once all required_fields are filled, AIO sends brief_summary.
6. Customer confirms the brief.
7. AIO asks whether to notify staff.
8. Only explicit notify approval sends the real staff notification.
9. If pause_after_notify is true, the AI pauses after notifying staff.

Example required field:

{
  key: "deadline",
  label: "Deadline / urgency",
  question: "What is the deadline or urgency?",
  aliases: ["deadline", "urgency", "deadline / urgency", "due", "due date"]
}

Example strict workflow config:

tickets: {
  strict_workflow: {
    enabled: true,
    notify_requires_customer_approval: true,
    pause_after_notify: true,
    use_llm_extractor: false,
    required_fields: [
      { key: "service", label: "Service", question: "What type of service do you need?", aliases: ["service", "type of service"] },
      { key: "title", label: "Project title or text", question: "What is the project title or exact text?", aliases: ["project title", "title", "text"] },
      { key: "description", label: "Description", question: "Please describe the project, style, and important details.", aliases: ["description", "details", "theme", "style"] },
      { key: "deadline", label: "Deadline / urgency", question: "What is the deadline or urgency?", aliases: ["deadline", "urgency"] },
      { key: "budget", label: "Budget range", question: "What is the budget range?", aliases: ["budget", "budget range"] },
      { key: "references", label: "References", question: "Do you have any references, links, or images?", aliases: ["references", "links", "images"] }
    ]
  }
}

External Ticket Bot Fallback

Use this only when another ticket system creates the ticket channel and AthenaBot’s native tickets plugin cannot resolve the channel.

tickets: {
  external_ticket_fallback: {
    enabled: true,
    require_bot_mention: true,
    channel_name_patterns: ["ticket", "order"],
    recent_message_limit: 12,
    form_text_contains: [
      "Your order ticket has been created",
      "While you are waiting, please fill out this question form",
      "Question 1",
      "Question 2",
      "Question 3",
      "Powered by tickets.bot"
    ]
  }
}

When enabled, AIO starts a session only when:

• the message is from a human
• the customer mentions the bot, unless require_bot_mention is false
• the message looks related to the strict ticket workflow
• the channel name or recent bot ticket form messages match the fallback config

The first matching human is treated as the ticket creator for the AIO session.

Chat

Moderation

Scam Detection

Scam detection is separate from text moderation and is disabled by default. It can scan image attachments, links, sender age, join age, roles, trust lists, and recent context before normal AIO replies.

Raw images are not stored locally. AIO stores image hashes, attachment URLs, domains, scores, decisions, and short evidence text in AIOScamScanLog.

See Scam Detection for setup steps, provider requirements, and review behavior.

Member Events

Welcome Language

In v1.4.2, both dashboards expose AI Welcome Language and AI Welcome Prefix under Member Events. Enable AI Personalize Welcome to use them.

For Dutch welcomes, set the language to Dutch and the prefix to Welkom bij {{server_name}}!. The bot adds the member mention, then asks the AI for a short continuation in Dutch. The language setting affects only the AI sentence; it does not translate the prefix or change chat/ticket languages.

With AI Welcome Mention set to No mention, the bot does not add a mention, and a {{user_mention}} placeholder in the prefix becomes the username. Role and everyone mentions cannot notify anyone. If the provider fails or returns no usable text, the bot sends only the configured prefix.

Existing configurations keep the English defaults. For a fixed translated message, disable AI Personalize Welcome and edit Welcome Message instead. See the Dutch setup example.

Anti-Raid

FAQ

FAQ replies are matched before an LLM request. Use FAQ entries for fixed answers such as docs links, pricing links, or server IPs.

Example:

faq: {
  enabled: true,
  entries: [
    {
      triggers: ["docs", "documentation", "where are the docs"],
      answer: "You can find the docs at https://docs.havendevelopment.net/"
    }
  ]
}

Prompt Files

Prompt files live under plugins/aio_agent/data/prompts/ unless you provide an absolute path. They are re-read when prompts are built, so reload/restart after editing them if you are unsure which config backend is active.

Prompt Variables And Appends

Built-in prompt variables include:

Time And Locale

What To Restart Or Reload