10. AI Bot

This chapter is for the server’s owner and admins. It covers the three settings tabs of the AI bot service: Overview, Tool Management, and Usage Log. Click the gear icon on the right side of the tab bar (tooltip: User Settings) to open the settings panel. In the list of settings groups on the left is an AI Settings group, with an Experimental badge right next to the group title. Inside the group are three tabs, from top to bottom: Overview, Tool Management, and Usage Log. This chapter describes each one in turn. The owner and admins see exactly the same content.

This feature is experimental. Its interface and behavior may change in future versions. Evaluate it carefully before enabling it in production.

Together, the three tabs let you set up the AI bot service and see how it is used. This chapter describes what you can see and click in the interface.

10.1 Overview

Overview is the first tab in the AI Settings group. When you open it, the title at the top of the content page is AI Settings. From top to bottom, the tab has six blocks, and each block is a card. In order, the card titles are: General, API Keys, Bot, Limits, System Prompt, and Bash Execution. The Bash Execution card is shown only to people who hold the Administrator permission (the owner and admins are always included; for permissions, see §4.3).

These six blocks share two ways of saving, explained once here. For fields where you type or choose something, your change is written only when you click the Save button next to the field. You can’t click this button when nothing has changed or while it is saving. After a successful save, the button text briefly changes to Saved, then back to Save. Switches work differently: click one to turn it on or off, and the change takes effect immediately, with no separate save.

Change one field at a time, and click Save next to it as soon as you finish: whenever any field is saved successfully (flipping a switch counts too), unsaved changes in the other fields go back to their saved content.

General

The card titled General contains three items: AI Enabled, Provider, and Model. When Provider is set to OpenRouter, three more OpenRouter-specific items appear further down (see below).

AI Enabled is a switch, and the description next to it reads “Enable or disable the AI bot service.” Click it to turn it on or off; the change takes effect immediately.

Provider is a drop-down menu with four options: Anthropic, OpenAI, Google Gemini, and OpenRouter. Anthropic is selected by default. After you choose, click Save next to it to write the setting.

The AI bot works only when AI Enabled is on and a key for the currently saved provider has been saved in the API Keys card. If you change the provider to one that has no saved key and save that change, the AI bot stops replying. It resumes automatically once you save a key for that provider.

Model decides which model the AI bot uses. The model field follows the provider currently selected in the Provider drop-down menu, and you can fill it in two ways:

• Choose a model from the list: when a key for this provider has been saved in the API Keys card (OpenRouter doesn’t need a saved key first), the model field loads the list of models this provider offers. While the list loads, Loading model list… appears under the field. When loading finishes, the field becomes a drop-down list. After you choose, click Save next to it.
• Enter a model ID by hand: once the model list appears, a line of small text, Enter manually, appears at the top right of the model field. Click it to replace the drop-down list with a single-line text box, where you can type a model ID directly, and then click Save next to it. Click Choose from list to switch back to the list. Use this method when the model you want isn’t in the list.

In the drop-down list:

• The first option is Provider default (…), with this provider’s default model in the parentheses: claude-sonnet-4-20250514 for Anthropic, gpt-4o for OpenAI, gemini-2.0-flash for Google Gemini, and z-ai/glm-5.3-flash for OpenRouter. If you select it and save, you don’t specify a model, and the server uses the model in the parentheses.
• When the list is long, a Filter models… box appears above it. Type part of a model ID or name to narrow the list.
• OpenRouter’s list is grouped by the vendor name at the start of the model ID (for example, “z-ai”), and it lists only models that support tool calling.
• When the current model setting isn’t in this provider’s list, an extra option appears: Current setting: … (not in list). This setting is kept: until you choose again and save, the AI bot keeps sending requests with this model. After you change providers, the original model usually isn’t in the new list, so this is when you see this option. Choose one of this provider’s models, or choose “Provider default”.

In two other cases, the model field appears as a single-line text box:

• When no API key has been saved for this provider yet, a hint below reads “Save this provider’s API key to choose from its model list.” The list appears only after you click Save in the API Keys card to write the key.
• When the list fails to load, a hint below reads “Could not load the model list (…). Enter the model manually.” The parentheses contain the reason for the failure.

Saving with the text box left empty has the same effect as choosing “Provider default”. When you change providers, first click Save next to Provider, and then choose a model and click Save next to Model. After you choose a model, you can use Test in the API Keys card to confirm that a connection works (see API Keys below).

When OpenRouter is selected in the Provider drop-down menu, these three items appear below the model field:

• A line of description: “OpenRouter model IDs look like vendor/model (e.g. z-ai/glm-5.3-flash). Pick a model that supports tool calling; the Test button checks this.”
• Reasoning effort (OpenRouter): a drop-down menu whose description reads “How much a reasoning model may think per reply. Thinking counts toward the max token budget and the 120-second reply timeout; Low keeps replies fast.” It has four options: Model default, Low, Medium, and High. The default is Low. With Model default, the model decides for itself how much to think. After you choose, click Save next to it.
• Deny data collection (OpenRouter): a switch that is off by default, with a description next to it that reads “Only route to providers that do not retain prompts or train on them. Some models may become unavailable.” Click it to turn it on or off; the change takes effect immediately.

API Keys

The card titled API Keys provides four key fields and a test button.

From top to bottom, the four key fields are Anthropic API Key, OpenAI API Key, Gemini API Key, and OpenRouter API Key. All four are masked boxes: as you type, they show dots instead of the plain text, and their hint is a row of dots, ••••••••. Each field has its own Save button next to it that writes that field. You need to fill in only the field for the provider chosen in the General card. You can leave the other fields empty.

At the very bottom, a Test button checks the connection. After you click it, its text changes to Testing…. If the connection works, “Connection successful!” appears next to it in the success color. If it doesn’t, Connection failed appears in red, followed by a colon and an error message that tells you why this attempt failed.

Test uses the provider currently selected in the General card, the current content of the Model field, and this provider’s key field. You can test a key that you’ve typed into the field but not saved yet; when the field is unchanged, the saved key is used. When the provider is OpenAI, Google Gemini, or OpenRouter and the model field is empty (“Provider default” is chosen), the test uses this provider’s default model. When the provider is Anthropic, first choose a model other than “Provider default” from the Model list, or type a model ID in the text box, and then click Test. When the provider is OpenRouter, Test applies the saved Reasoning effort (OpenRouter) and Deny data collection (OpenRouter) settings, and it also checks whether the model supports tool calling. If that check fails, Connection failed and the reason appear in the same way.

Bot

The card titled Bot contains two items.

Bot Name is a single-line text box with the hint hako-ai. After you change the name, click Save next to it to write it.

Member Access is a switch, with a description next to it that reads “Allow non-admin members to use the AI bot.” Click it to turn it on or off; the change takes effect immediately. This switch is off by default. While it is off, only people who hold the Administrator permission (the owner and admins are always included) can talk with the AI bot. When anyone else sends the AI bot a message, it replies “⚠️ AI access is restricted to admins and owners.” When the switch is on, all members can talk with the AI bot. For which tools it can use when it acts for a member, see §10.2.

Limits

The card titled Limits provides four number boxes. The minimum value for each is 1, and each has its own hint and its own Save button.

From top to bottom, the four fields are: Context Messages (hint 50), Max Tokens (hint 4096), Token Limit/Day (hint 100000), and Rate Limit (hint 10). After you change any field, click Save next to that field to write it.

What the four fields mean:

• Context Messages: how many of the most recent messages in the direct message conversation the AI bot refers to each time it replies (including its own replies).
• Max Tokens: the maximum length of the reply each time the AI bot calls the model (counted in tokens).
• Token Limit/Day: the daily token usage limit for the whole server (across all members), with the day changing at midnight UTC. When the AI bot starts working again after it has stopped (for example, after the server restarts, or after AI Enabled is turned off and on again), the count for that day’s usage starts over. The AI bot checks usage before every call to the model. After the limit is reached, a member who sends the AI bot another message gets the reply “⚠️ Daily token limit reached. AI will be available again tomorrow.”
• Rate Limit: the maximum number of messages from each member that the AI bot will handle within one minute. A member who goes over it gets the reply “⚠️ Rate limit exceeded. Please wait a moment before sending another message.”

Uses that are stopped by Token Limit/Day or Rate Limit are all recorded in Usage Log with the status Blocked (see §10.3).

System Prompt

The card is titled System Prompt. It holds a tall multi-line text box (about 8 lines) that you can drag to make taller, where you enter the system prompt for the AI bot.

Below it are two buttons. Save writes the current content; you can’t click it when nothing has changed. Reset to Default opens a system confirmation dialog that reads “Reset the system prompt to the default?” After you confirm, the system prompt is cleared and saved.

Bash Execution

The card titled Bash Execution is shown only to people who hold the Administrator permission (the owner and admins are always included). At the very top is a main switch, Bash Execution, with a description next to it that reads “Allow the AI bot to execute bash commands on the server.” Click it to turn it on or off; the change takes effect immediately. When it is on, the AI bot runs Bash commands only when the owner personally is talking with it.

After you turn on the Bash Execution switch, the following four items appear below it.

Bash Mode is a drop-down menu with three options: Confirm (the default), Whitelist, and Blacklist. After you choose, click Save next to it to write the setting.

Allow Sudo is a switch, with a description next to it that reads “Allow the AI bot to run commands with sudo.” Click it to turn it on or off; the change takes effect immediately.

Bash Timeout (s) is a number box with the hint 30. You can enter 5 to 300 seconds. After you change it, click Save next to it to write it.

Under the Bash Whitelist label, a line of description reads “Comma-separated list of allowed commands.” Below it is a multi-line text box (about 3 lines, and you can drag it taller). Enter the allowed commands, and then click Save next to it to write them.

10.2 Tool Management

Tool Management is the second tab in the AI Settings group. When you open it, the title at the top of the content page is Tool Management. The whole tab is a single card.

To the right of the card title Tool Management is a count that shows how many tools are currently enabled out of the total, followed by active (for example, 3/8 active). The description under the title reads “Toggle which tools the AI bot can use. Disabled tools will not be available to the bot.”

Below the description is a list of tools, one row for each tool. On the left of each row is the tool name, with a smaller line of tool description under it (long descriptions are cut off). On the right is a switch that you click to enable or disable the tool. While a change is in progress, that switch turns semi-transparent and you can’t click it for the moment. It returns to normal once the change finishes.

The tool list is shown only while the AI bot is working (for when it works, see General in §10.1). At other times the list is empty, and the count shows 0/0 active. The bash_execute row appears only after the Bash Execution switch in §10.1 is turned on. Only people who hold the Administrator permission can flip its switch; everyone else sees that switch semi-transparent, and they can’t click it.

When the AI bot acts for a member, it uses only tools that are switched on and that the member has permission to use themselves; for example, creating or changing a channel requires the Manage channels permission. It checks the permission again each time before it uses a tool. The three tools delete_channel, kick_user, and bash_execute are used only when the owner personally is talking with the AI bot.

10.3 Usage Log

Usage Log is the third tab in the AI Settings group. When you open it, the title at the top of the content page is AI Usage Log. This page records who used the AI bot and when: while the AI bot is working (see General in §10.1), each direct message from a member that it handles is recorded as one use, including the ones stopped by Rate Limit, Token Limit/Day, or Member Access.

From top to bottom, the page contains: time range and filters, summary cards, the usage chart, rankings, each-use records, and each-use record retention. When the server still has tool call records from before the usage log feature was added, there is also a collapsible block at the very bottom.

Time Range and Filters

At the very top is a card. The description in its top-left corner reads “Who used the AI assistant, when, and with which provider and model. What members send to the AI is not recorded; tool calls are shown with their arguments and results.” In the top-right corner are two buttons:

• Refresh: reloads the summary, chart, rankings, and each-use records.
• Export CSV: downloads the each-use records as a CSV file, based on the current time range and filters (including the Status of the each-use records). The newest records come first, and times in the file are recorded in UTC. When too many records match, only the newest part is exported, with the message “Only the newest 10,000 uses were exported. Narrow the range to export the rest.” If the export fails, “Could not export the usage log.” appears.

Under Time range is a row of buttons: Today, 7 days, 30 days, 90 days, All, and Custom. When you open the page, 7 days is selected. 7 days, 30 days, and 90 days all include today. Choosing Custom adds two date fields, From and To. If the dates don’t make sense, a hint reads “Pick a valid date range, from 2000-01-01 on, with the start before the end.” At the very bottom of the time range area, a line of small text reads “Days follow UTC, the same day boundary as the daily token limit.”

Further down are three drop-down menus, Member, Provider, and Model, all set to All by default. Once you choose an option, the summary, chart, rankings, and each-use records show only the matching data. Providers are shown by their English identifiers, for example openrouter.

If the data fails to load, this card shows “Could not load the usage log.”

Summary Cards

Below the filters is a row of summary cards:

• Uses: the number of uses in this period, including failed and blocked ones.
• Tokens: the total of input and output tokens, with small text below that reads … in · … out.
• Members: the number of members who have usage records in this period.
• Failed / blocked: the number of failed uses and the number of blocked uses, separated by “/”. For what the two statuses mean, see “Each-Use Records” below.

When this period includes uses for which OpenRouter reported a cost, an extra Cost (OpenRouter) card appears below. It shows the cost in US dollars, with a note inside the card: “Only OpenRouter reports what each call cost; for other providers only tokens are shown.”

Usage Chart

Below the summary cards is a bar chart of usage. Depending on the length of the time range, its title shows Usage per day, Usage per week, or Usage per month. For longer ranges, each bar represents a week or a month. In the top-right corner, you can switch the bars between showing Uses and Tokens.

The bars are colored by model. When there are two or more models, a legend appears, and models with less usage are combined into Other.

Move the mouse over a bar to see the values for that time. When this period has no data, “No AI use in this range.” appears.

Rankings

When there is data, two cards appear below the chart: Top members and Models. Each row is one member or one model (under a model, a line of small text shows the provider’s identifier), followed by the number of uses, … uses, and the number of tokens, … tok.

Each-Use Records

The Each use card lists every use in this period, with the newest at the top. The Status drop-down menu on the right of the title row has five options: All, Answered, Failed, Blocked, and In progress. It affects only this card’s list and Export CSV. The summary, chart, and rankings above stay the same.

What the four statuses mean:

• Answered: the AI bot finished its reply.
• Failed: the AI bot couldn’t finish its reply, for example because the provider returned an error. A message stopped by the provider’s content moderation and a response that timed out also fall into this category.
• Blocked: HakoSpace’s own limits stopped this use. This includes a member going over Rate Limit, the server reaching Token Limit/Day, Member Access not being open to this member, or the member being removed or losing permission to use it while the conversation was in progress.
• In progress: the AI bot is still working on it.

From left to right, each row shows: the time (in your device’s time zone), the member’s name, the provider and model (separated by “·”), the number of tokens this use took, and the status. A member whose account has been deleted appears as Deleted member, followed by an identifier in parentheses. When no records match, “No AI use matches these filters.” appears. When Load more appears at the bottom of the list, click it to list more.

Click any row to expand it. First comes a one-line summary, for example Model calls: 2 · tool calls: 1, followed by the input and output token counts, the cost (when reported), and the time taken. For a failed or blocked use, the next line states the reason. For a failure, the reason may also be followed by an error code and an error message. The possible reasons are:

• Blocked: “The member hit the per-minute request limit.”, “The server-wide daily token limit was reached.”, “The AI is not open to this member.”, and “Stopped midway: the member was removed or lost AI access.”
• Failed: “The provider returned an error.”, “HakoSpace could not prepare the request.”, “Stopped after the maximum number of tool rounds.”, and “The server restarted before the reply finished.”

Further down, each step of this use is listed in the order it happened:

• Each model call gets its own box, titled Model call 1, Model call 2, and so on, with the model that actually responded and the time taken next to it. With OpenRouter, served by … also appears, which shows the provider that OpenRouter actually handed this call to. Below that are the token counts, … in / … out, and, when present, … cached and … reasoning (counted within input and output, respectively), the cost, and finish: …. The bottom line is Response ID ….
• Each tool call gets its own row, which shows the tool name, a summary of the arguments, the time taken, and the time. Click it to expand it and see the Arguments and Result of this call.

For a use that never called the model (for example, one stopped by Rate Limit or Member Access), the expanded view shows “The model was not called.” If the details fail to load, “Could not load the details of this use.” appears.

Each-Use Record Retention

Below the each-use records is a card. The Keep each-use records for drop-down menu has four options, 30 days, 90 days, 180 days, and 365 days, and the default is 90 days. Your choice is saved as soon as you make it. On success, Saved. appears; on failure, “Could not save the retention period.” appears. The description under the drop-down menu reads “Older records are deleted automatically; the totals, chart and rankings keep counting them.”

When you shorten the period, a system confirmation dialog appears first. For example, when you change it to 30 days, the dialog reads “Keep records for 30 days only? Records older than 30 days will be deleted at the next daily cleanup and cannot be recovered.” The change is saved only after you confirm. This period also applies to “Tool Calls from Before Usage Logging” below.

Tool Calls from Before Usage Logging

When the server still has tool call records from before the usage log feature was added, an extra collapsible block, Tool calls from before usage logging, appears at the very bottom of the page. When you open it, a line of description comes first: “Recorded before this log existed, so they are not grouped under a use. They are deleted with the retention period.” Below it, the most recent records of this kind are listed. Each row shows the tool name, a summary of the arguments, the member, the time taken, and the time. Click a row to expand it and see the Arguments and Result. The time range and filters above don’t affect this block.