Setup

This page walks through a clean AIO Agent setup from install to first customer use. For every individual option, see Configuration.

Requirements

• AthenaBot with the core plugin enabled
• Optional: AthenaBot’s tickets plugin for ticket support automation
• AthenaBot’s moderation plugin for AIO warnings, timeouts, kicks, bans, reversals, and punishment history
• AthenaBot’s security plugin when AIO anti-raid lockdown is enabled
• Optional: dashboard access for easier configuration
• A Discord bot token with permissions for the modules you enable
• An LLM API key for Gemini, OpenAI, Anthropic, OpenRouter, or a compatible API
• If using local knowledgebase files, filesystem access to the AthenaBot server

Installation

1. Place the plugin folder at plugins/aio_agent.
2. Start AthenaBot once so it generates configuration/aio_agent.json5 and configuration/aio_agent_lang.json5.
3. If the dependency installer does not run automatically, stop AthenaBot and install the Gemini SDK:

npm install @google/genai

4. Open the dashboard, go to Configuration -> AIO Agent, and save your settings.
5. Restart AthenaBot after changing provider keys, permissions, plugin enablement, or environment variables.

Minimum Working Config

Start with owner-only access. This proves the provider key works before tickets, chat, moderation, or automation are enabled.

{
  config: {
    enabled: true,
    mode: "owner_only",
    llm_provider: "gemini",
    llm_api_key: "YOUR_API_KEY",
    llm_model: "gemini-2.5-flash",
    owner_id: "YOUR_DISCORD_USER_ID",
    admin_users: [],
    moderator_users: [],
    allowed_users: [],
    blocked_users: [],
    tickets: {
      enabled: false
    },
    chat: {
      enabled: false,
      respond_to_mentions: true
    },
    moderation: {
      enabled: false,
      mode: "ask"
    }
  }
}

Save, restart, then mention the bot from the owner account:

@Athena Dev where can I find Athena docs?

Then test a safe owner action:

@Athena Dev summarize the last 20 messages here

Choose A Provider

You can paste the key into llm_api_key, but production servers should usually use environment 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=...

Separate Reasoning Profile

Use a second profile when heavier agent tasks should use a different provider, model, or API key from normal chat and ticket replies:

reasoning_llm: {
  enabled: true,
  provider: "openai",
  api_key: "", // Or AIO_AGENT_REASONING_API_KEY
  model: "gpt-5.6",
  api_base_url: "",
  use_for_owner_tools: true,
  use_for_self_improvement: true,
  use_for_response_classifier: false,
  use_for_knowledgebase_search: true
}

Blank provider, model, and base URL values inherit the primary profile. A blank key falls back to the reasoning environment variable, the matching provider environment variable, or the primary key.

Prompt Caching

Prompt caching depends on the provider and model. Enable AIO’s controls only after the primary provider works normally:

prompt_caching: {
  enabled: true,
  openai: { mode: "automatic", cache_key: "" },
  anthropic: { mode: "automatic", ttl: "5m" },
  gemini: { mode: "automatic", ttl_seconds: 300 }
}

Automatic mode is the safest starting point. Explicit OpenAI caching requires GPT-5.6 or later. Explicit Gemini caching creates a managed cache and may have storage charges. /aio usage reports cache reads and writes, but its dollar estimate uses base prices and does not calculate provider-specific cache rates.

Dashboard Setup

The dashboard version of AIO Agent is meant to be customer-editable.

1. Open Configuration -> AIO Agent.
2. Enable only the sections the customer wants.
3. Enter exact model names, docs URLs, folder paths, prompt filenames, timezones, locales, and base URLs as free text.
4. Use dropdowns only for fixed choices such as provider, mode, personality, moderation mode, moderation sensitivity, permission tier, and booleans.
5. Save the config.
6. Restart AthenaBot if you changed keys, provider, enabled modules, or environment variables.

Good customer values:

docs_url: "https://docs.havendevelopment.net/"
llm_model: "gemini-2.5-flash"
datetime_timezone: "America/Winnipeg"
datetime_locale: "en-CA"
datetime_timezone_label: "Central Time"

Addon Setup

AIO Agent can load customer-owned addons from:

plugins/aio_agent/data/addons/

Use addons for custom prompt behavior, custom defaults, extra prompt variables, or extra knowledgebase text that should survive AIO updates. Do not edit core files in plugins/aio_agent/src/ for customer-specific work unless the change belongs in the official plugin for everyone.

Each addon has its own folder with an addon.json, optional config.json5, and an entry file such as index.js.

See Addons for the full addon format and update rules.

Knowledgebase Setup

Create a folder:

plugins/aio_agent/data/knowledgebase/

Add focused .md or .txt files. Good examples:

• setup.md
• pricing.md
• rules.md
• troubleshooting.md
• ticket-process.md

Then configure:

knowledgebase_dir: "knowledgebase",
knowledgebase_recursive: true,
knowledgebase_mode: "search",
knowledgebase_search_top_k: 6,
knowledgebase_search_max_chars: 12000,
athenabot_brain_enabled: true

Reload after changing files:

/aio reload

How The Knowledgebase Reaches The AI

AIO Agent does not give the model direct filesystem access.

The flow is:

1. AthenaBot starts or /aio reload runs.
2. AIO Agent reads .md and .txt knowledgebase files.
3. It also loads built-in AthenaBot docs if athenabot_brain_enabled is true.
4. It optionally snapshots configured channels/forums from knowledgebase_channels.
5. It stores those sources in memory.
6. When someone talks to the AI, AIO Agent builds the prompt, adds variables such as bot name, owner ID, current time, and the knowledgebase_block variable.
7. The selected knowledgebase block is sent to the LLM as context with the user’s message.

For small knowledgebases, knowledgebase_mode: "full" sends one capped block of all loaded knowledge. For normal or large knowledgebases, search sends only the chunks that match the current request. For very large knowledgebases, hybrid can rerank local search results with embeddings.

Recommended customer defaults:

knowledgebase_mode: "search",
knowledgebase_embeddings_enabled: false

Recommended for large customer docs:

knowledgebase_mode: "hybrid",
knowledgebase_embeddings_enabled: true,
knowledgebase_embedding_provider: "llm",
knowledgebase_embedding_candidate_count: 30

Confirmed Memory Setup

Confirmed memory is disabled by default. It only saves AIO knowledge after a review-channel approval; it cannot edit code, server configuration, Discord permissions, or other systems.

self_improvement: {
  enabled: true,
  auto_detect: false,
  source_scope: "selected",
  channel_ids: [],
  category_ids: [],
  excluded_channel_ids: [],
  review_channel_id: "YOUR_PRIVATE_REVIEW_CHANNEL_ID",
  approver_user_ids: [],
  approver_role_ids: [],
  minimum_requester_tier: "ADMIN",
  memory_file: "agent-memory.md",
  min_confidence: 0.88,
  cooldown_seconds: 60,
  max_proposals_per_hour: 10,
  review_timeout_minutes: 30
}

Start with auto_detect: false and test an authorized remember this request. After the proposal is approved, AIO saves it and reloads its knowledgebase. If automatic proposals are enabled later, choose all, staff, or selected scope and keep sensitive channels in excluded_channel_ids.

Ticket Support Setup

Enable the tickets module:

mode: "general",
tickets: {
  enabled: true,
  response_mode: "smart",
  auto_activate: false,
  cooldown_seconds: 2,
  human_phrases: ["i need a human", "talk to a human", "human please"],
  owner_stop_phrases: ["stop responding", "pause", "go silent"]
}

Recommended first test:

1. Open a test ticket.
2. Run /aio handle in the ticket.
3. Ask a normal support question as the customer.
4. Ask for a human using one of the handoff phrases.
5. Confirm the session pauses and staff are notified if configured.

Turn on automatic activation only after manual handling works:

tickets: {
  auto_activate: true,
  auto_activate_categories: []
}

Use auto_activate_categories if only certain ticket categories should use the AI. Category indexes come from the tickets plugin category list.

Strict Ticket Workflow Setup

Strict workflow is enabled by default. It collects configured fields before the LLM can improvise a handoff or claim staff were notified.

Recommended default:

tickets: {
  strict_workflow: {
    enabled: true,
    notify_requires_customer_approval: true,
    pause_after_notify: true,
    use_llm_extractor: false
  }
}

Test flow:

1. Open a test ticket as a customer.
2. Ask what info do you need from me?.
3. Answer each missing question.
4. Confirm the generated brief.
5. Confirm AIO asks whether to notify staff.
6. Reply yes.
7. Confirm a real staff notification is sent and the AI pauses.

Edit tickets.strict_workflow.required_fields when a server needs a different intake checklist. Edit tickets.strict_workflow.replies to change the exact wording sent to customers.

External Ticket Bot Setup

If the server uses a third-party ticket bot instead of AthenaBot’s native tickets plugin, enable the external fallback:

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",
      "Question 1",
      "Powered by tickets.bot"
    ]
  }
}

Keep this disabled unless you need it. When enabled, AIO only starts a fallback session if a human mentions the bot and the channel looks like a configured external ticket channel.

Ticket Close Setup

By default, AIO Agent cannot close tickets:

tickets: {
  allow_ai_ticket_close: false
}

To let staff ask the AI to close tickets with confirmation:

tickets: {
  allow_ai_ticket_close: true,
  ticket_close_requires_confirmation: true,
  ticket_close_minimum_tier: "MODERATOR",
  ticket_close_allow_creator: false
}

To let the ticket creator request close using Athena’s native close-request buttons:

tickets: {
  allow_ai_ticket_close: true,
  ticket_close_requires_confirmation: true,
  ticket_close_allow_creator: true
}

Supported customer intents include:

close ticket
please close this ticket
!tclose

To close directly without any confirmation:

tickets: {
  allow_ai_ticket_close: true,
  ticket_close_requires_confirmation: false
}

Direct close mode should be reserved for servers that explicitly want that behavior. The close reason is [aio-agent] close_ticket.

Chat Setup

Use Smart chat mode when AIO should watch selected channels for questions and help without joining normal conversation.

mode: "general",
chat: {
  enabled: true,
  channels: ["123456789012345678"],
  response_mode: "smart",
  respond_to_mentions: true,
  respond_to_name: true,
  wake_words: [],
  personality: "",
  custom_personality: "",
  allowed_topics: "server support, Minecraft, product questions",
  max_messages_per_user_per_hour: 20,
  cooldown_seconds: 3
}

Smart behavior can be tuned separately from the main reply model:

response_gate: {
  use_llm_classifier: true,
  classifier_model: "", // Empty uses llm_model
  context_messages: 8,
  confidence_threshold: 0.72,
  max_output_tokens: 80,
  max_message_chars: 1200,
  cache_ttl_seconds: 120,
  max_checks_per_user_per_hour: 12
}

Smart handles clear cases locally:

• Normal conversation, greetings, and acknowledgements are ignored.
• Clear help and failure messages can proceed without a classifier request.
• Direct calls using the bot’s username, nickname, or a configured alias proceed immediately without a classifier request.
• Ambiguous questions get one small AI check.
• Duplicate events reuse the decision, and each user has a separate hourly classifier limit.
• Provider errors or low confidence make AIO stay quiet.

Use response_mode: "always" only when every message in the configured channel should receive a reply. Use response_mode: "mentions" for strict ping/reply behavior; name aliases do not activate mention-only mode.

If channels is empty, Smart can still wake on a bot mention, Discord reply, or a direct call using the bot’s username, nickname, or a configured wake_words alias. Disable respond_to_name if only real mentions should wake it outside watched channels.

Owner/Admin Tool Setup

Set the owner first:

owner_id: "YOUR_DISCORD_USER_ID",
admin_users: [],
moderator_users: [],
allowed_users: [],
blocked_users: []

Then add staff gradually.

Keep confirmations on for destructive actions:

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"
],
confirm_destructive_tools: true

Moderation Setup

Start in review mode:

moderation: {
  enabled: true,
  mode: "ask",
  review_channel_id: "123456789012345678",
  server_rules: "No slurs, harassment, threats, spam, scams, or NSFW content.",
  enforce_discord_tos: true,
  sensitivity: "medium",
  min_confidence: 0.75,
  actions: {
    warn: true,
    timeout: true,
    timeout_max_minutes: 60,
    kick: false,
    ban: false,
    delete_message: true
  }
}

Only use mode: "instant" after the customer has tested their rules and trusts the review output. AIO sends moderation actions through Athena’s moderation plugin, so configure Athena’s punishment log, notifications, thresholds, and permissions there.

Member Events Setup

Basic welcome:

member_events: {
  enabled: true,
  welcome_channel_id: "123456789012345678",
  welcome_message: "Welcome {{user_mention}} to {{server_name}}!",
  welcome_ai_personalize: false,
  goodbye_channel_id: "",
  goodbye_message: "",
  auto_roles: [],
  log_channel_id: ""
}

If the server verifies members before they receive a role, wait before sending the welcome:

member_events: {
  welcome_wait_for_any_role: true,
  welcome_wait_timeout_seconds: 60
}

Personalized Welcomes In Dutch

Requires AIO Agent v1.4.2. In AIO Agent > Member Events, select your welcome channel, enable member events and AI Personalize Welcome, then save:

• AI Welcome Language: Dutch
• AI Welcome Prefix: Welkom bij {{server_name}}!

Equivalent settings inside your existing member_events section:

enabled: true,
welcome_channel_id: "123456789012345678",
welcome_ai_personalize: true,
welcome_ai_language: "Dutch",
welcome_ai_prefix: "Welkom bij {{server_name}}!",
welcome_mention_mode: "user"

The bot adds the new member’s mention, uses the prefix you entered, and generates a short Dutch sentence. Set both the language and prefix: changing the language alone leaves the default English prefix in place. Other language names or codes, such as German or nl-NL, can also be used.

If AI generation fails, the prefix is still sent. Select No mention if you do not want to ping the member. If the new fields are missing, install the full v1.4.2 plugin, restart AthenaBot and the dashboard process, and refresh the page.

For a fixed Dutch message without an AI request, disable AI Personalize Welcome and set Welcome Message to:

Welkom {{user_mention}} bij {{server_name}}! Leuk dat je er bent!

FAQ Setup

FAQ answers are free because they do not call the LLM.

faq: {
  enabled: true,
  entries: [
    {
      triggers: ["docs", "documentation", "where are the docs"],
      answer: "Docs: https://docs.havendevelopment.net/"
    },
    {
      triggers: ["server ip", "minecraft ip"],
      answer: "The server IP is play.example.net."
    }
  ]
}

Prompt Customization

Prompt files live in:

plugins/aio_agent/data/prompts/

Use prompt_append_ticket, prompt_append_owner, and prompt_append_chat for small customer-specific additions. Use full prompt files when the customer needs a different support style, product vocabulary, or workflow.

Example:

prompt_variables: {
  product_name: "RadiantSMP",
  support_hours: "10 AM to 10 PM Central"
},
prompt_append_ticket: "If the user asks about refunds, point them to the refund policy first."

Recommended Bot Permissions

Give the Discord bot only what enabled modules need:

• Send Messages and Embed Links for chat, ticket, FAQ, logs, and summaries
• Read Message History for context, summaries, tickets, and knowledge snapshots
• Manage Messages for delete_messages and moderation deletion
• Manage Roles for role tools and auto roles
• Moderate Members for timeouts
• Kick Members or Ban Members only if those actions are enabled
• Manage Channels for lock, unlock, slowmode, topic, channel creation, permission overwrites, and confirmed channel deletion
• Add Reactions and Manage Messages for reaction cleanup or button/review flows

Safe Launch Checklist

• Set owner_id before enabling tools.
• Keep admin_users, moderator_users, and allowed_users empty until you know who should have access.
• Keep destructive tools confirmed.
• Test private channel creation, permission edits, and deletion in a disposable category before allowing them on a live server.
• Keep confirmed memory automatic detection off until its private review channel and source scope have been tested.
• Start tickets with /aio handle before enabling tickets.auto_activate.
• Start moderation with mode: "ask" before considering instant.
• Keep moderation.actions.kick and moderation.actions.ban disabled until reviewed.
• Use FAQ entries for fixed answers.
• Use knowledgebase_mode: "search" for most customer docs.
• Test ticket close behavior in a private ticket before enabling it for customers.