Built-in Commands

AstrBot commands are registered through the plugin system. To keep the core lightweight, only a small set of basic commands are loaded with AstrBot itself. Other management and extended commands have been moved into a separate plugin.

Use /help to view currently enabled commands.

NOTE

/help, /set, and /unset are not shown in the /help command list by default, but they are still available.
If you change the wake prefix and remove the default /, commands must use the new wake prefix as well. For example, after changing the wake prefix to !, use !help and !reset instead of /help and /reset.

Core Built-in Commands

The following commands are shipped with AstrBot and loaded by default:

/help: View currently enabled commands and AstrBot version information.
/sid: View current message source information, including UMO, user ID, platform ID, message type, and session ID. This is commonly used when configuring admins, allowlists, or routing rules.
/name: Set a display alias for the current UMO, which means one concrete group or private-chat message source on a platform, so it is easier to recognize in WebUI. This command requires admin permission.
/reset: Create and switch to a new conversation, just like /new.
/stop: Stop Agent tasks currently running in the current session.
/new: Create and switch to a new conversation.
/stats: View token usage statistics for the current conversation.
/provider: View or switch LLM Provider. This command requires admin permission.
/dashboard_update: Update AstrBot WebUI. This command requires admin permission.
/set: Set a session variable, commonly used for Agent Runner input variables such as Dify, Coze, or DashScope.
/unset: Remove a session variable.

These commands are located in:

text

astrbot/builtin_stars/builtin_commands

Core Command Details

`/sid`

/sid shows information about the current message source. It mainly returns:

UMO: The unified message origin of the current message. It is commonly used for allowlists and per-session config routing.
UID: The sender's user ID. It is commonly used when adding AstrBot admins.
Bot ID: The platform instance ID of the current bot.
Message Type: The message type, such as private chat or group chat.
Session ID: The platform-side session ID.

In group chats, if unique_session is enabled, /sid also shows the current group ID. This group ID can be used to allowlist the entire group.

Common uses:

Add an admin: run /sid to get the UID, then add it in WebUI under Config -> Other Config -> Admin ID.
Configure allowlists: use UMO or group ID to control which sessions can use the bot.
Configure routing rules: use UMO to distinguish different platforms, groups, or private chats.

`/name`

/name sets a human-readable display alias for the current UMO. UMO stands for Unified Message Origin. It identifies one concrete message source in the form platform ID:message type:session ID, such as a QQ group, a Telegram group, or a private chat on a specific platform.

Raw UMOs are often long and are not always easy to recognize at a glance. After setting /name, AstrBot shows this alias first in WebUI UMO lists, session source selectors, cron delivery targets, conversation data, and other places where administrators need to identify or select a target session. This reduces the chance of choosing the wrong source when configuring routing rules, cron delivery targets, or per-session rules.

/name also records the readable auto name provided by the current platform when available, such as a group name in group chats or a sender nickname/ID in private chats. This lets WebUI show a readable name even when no manual alias has been set.

Usage:

/name <alias>: Set or update the alias for the current UMO. This command can be used repeatedly; the latest value overwrites the previous alias.
/name: With no argument, it does not modify the alias. It only shows usage, the current UMO, the current auto name, and the saved alias.

Display rules:

If both alias and auto name exist, AstrBot displays alias (auto name).
If only the auto name exists, AstrBot displays the auto name.
If neither exists, AstrBot displays the raw UMO.

/name requires admin permission.

`/reset` and `/new`

/reset and /new use the same restart flow. Both command entries and their individual command management settings are retained.

For AstrBot's built-in Agent Runner, it:

Marks other active events in the current session as stopped, without waiting for every task to exit.
Creates and selects an empty conversation, preserving previous history and inheriting the current persona.
Clears the current session's group context cache after the reply is sent.

For third-party Agent Runners such as dify, coze, dashscope, and deerflow, it:

Stops running tasks in the current session.
Removes the saved third-party conversation ID for this session, so the next turn starts a new conversation.

DeerFlow also attempts to delete the old remote thread. Third-party runners do not guarantee retention of previous history.

Permission notes:

In private chat, regular users can use it by default.
Group chats default to Follow Conversation Isolation: everyone can use the commands when Isolate Conversation is enabled and isolation is applied by the platform; otherwise, only AstrBot administrators can use them. Administrators are configured administrator IDs, not automatically detected group administrators. Platforms without isolation support retain the shared-group restriction.
In WebUI, open Extensions → Handlers → Command and select Show System Plugin Commands. Configure new and reset individually using Everyone, Administrators Only, Administrators Only in Group Chats, or Follow Conversation Isolation. The selected permission applies across all configuration profiles. Follow Conversation Isolation evaluates isolation using the incoming message's profile; the other three choices remain fixed when isolation settings change.
Administrators Only restricts both private and group chats. Administrators Only in Group Chats allows everyone in private chats but requires administrator permission in groups.
With Isolate Conversation disabled, the command switches the conversation for the whole group; with isolation enabled and applied, it affects only the sender's conversation. Select Everyone to allow regular members to use the command in shared group conversations.
Command disabling and renaming are also managed here.

Upgrade note: commands without explicitly saved permissions default to Follow Conversation Isolation. Permissions saved in command management and Isolate Conversation settings are preserved. Select Follow Conversation Isolation to restore automatic permission checks. If you customized the legacy group_unique_on, group_unique_off, or private values under alter_cmd.astrbot.reset, these values are no longer read; select the desired permission in command management instead.

`/stop`

/stop stops Agent tasks currently running in the current session.

It does not clear conversation history and does not create a new conversation. It only sends a stop request to tasks currently executing in this session.

For the built-in Agent Runner, /stop asks the Agent Runner to stop the current task.
For third-party Agent Runners such as dify, coze, dashscope, and deerflow, /stop directly stops registered running tasks in the current session.

If there are no running tasks in the current session, AstrBot will report that no task is running.

`/stats`

/stats shows token usage statistics for the current conversation.

It queries the database for all Provider call records in the current conversation and displays:

Total tokens (input + output).
Input tokens (cached) — input tokens that were cached by the provider and skipped for billing.
Input tokens (other) — input tokens that were not cached and billed normally.
Output tokens — tokens generated by the model.

If you are not in a conversation, AstrBot will prompt you to create one with /new.

`/provider`

/provider views or switches the Provider (LLM / TTS / STT) used by the current UMO.

Viewing the Provider list:

With no arguments, /provider lists all configured Providers grouped by LLM, TTS, and STT. Each Provider shows:

An index number for switching.
Provider ID and the model currently in use (LLM type).
Reachability status: ✅ means the connection is healthy, ❌ means a connection failure (with an error code).
The currently active Provider is marked with (currently in use) at the end.

NOTE

Reachability checks must be enabled in WebUI under Config -> General Config -> AI Config, expand the "More Settings" section at the bottom, and enable "Provider Reachability Check". When disabled, reachability markers are not shown and the list loads faster.

Switching Providers:

Use /provider <index> to switch the current session's LLM Provider to the Provider at the given index in the list.

/provider <index>: Switch to the LLM Provider at the given index.
/provider tts <index>: Switch to the TTS Provider at the given index.
/provider stt <index>: Switch to the STT Provider at the given index.

This command requires admin permission.