laoxong/AstrBot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: transfer AstrBotDevs/AstrBot-docs to AstrBotDevs/AstrBot (#5960)

Browse Source 
* docs: transfer AstrBotDevs/AstrBot-docs to AstrBotDevs/AstrBot
* refactor: reorder imports and improve type hints in sync_docs_to_wiki.py and upload_doc_images_to_r2.py
* feat: add GitHub Actions workflow to sync wiki with documentation

Co-authored-by: Soulter <37870767+Soulter@users.noreply.github.com>
Co-authored-by: anka-afk <110004162+anka-afk@users.noreply.github.com>
Co-authored-by: zouyonghe <62183434+zouyonghe@users.noreply.github.com>
Co-authored-by: shuiping233 <49360196+shuiping233@users.noreply.github.com>
Co-authored-by: LIghtJUNction <106986785+LIghtJUNction@users.noreply.github.com>
Co-authored-by: Sjshi763 <179909421+Sjshi763@users.noreply.github.com>
Co-authored-by: xiewoc <70128845+xiewoc@users.noreply.github.com>
Co-authored-by: QingFeng-awa <151742581+QingFeng-awa@users.noreply.github.com>
Co-authored-by: PaloMiku <96452465+PaloMiku@users.noreply.github.com>
Co-authored-by: shangxueink <138397030+shangxueink@users.noreply.github.com>
Co-authored-by: IGCrystal-A <244300990+IGCrystal-A@users.noreply.github.com>
Co-authored-by: RC-CHN <67079377+RC-CHN@users.noreply.github.com>
Co-authored-by: MC090610 <113341105+MC090610@users.noreply.github.com>
Co-authored-by: Waterwzy <196913419+Waterwzy@users.noreply.github.com>
Co-authored-by: Lanhuace-Wan <186303160+Lanhuace-Wan@users.noreply.github.com>
Co-authored-by: LiAlH4qwq <61769640+LiAlH4qwq@users.noreply.github.com>
Co-authored-by: HSOS6 <209910899+HSOS6@users.noreply.github.com>
Co-authored-by: th-dd <162813557+th-dd@users.noreply.github.com>
Co-authored-by: miaoxutao123 <81676466+miaoxutao123@users.noreply.github.com>
Co-authored-by: nuomicici <143102889+nuomicici@users.noreply.github.com>
Co-authored-by: nasyt233 <210103278+nasyt233@users.noreply.github.com>
Co-authored-by: jlugjb <7426462+jlugjb@users.noreply.github.com>
Co-authored-by: Raven95676 <176760093+Raven95676@users.noreply.github.com>
Co-authored-by: Futureppo <180109455+Futureppo@users.noreply.github.com>
Co-authored-by: MliKiowa <61873808+MliKiowa@users.noreply.github.com>
Co-authored-by: Fridemn <150212937+Fridemn@users.noreply.github.com>
Co-authored-by: BakaCookie520 <138355736+BakaCookie520@users.noreply.github.com>
Co-authored-by: YumeYuka <125112916+YumeYuka@users.noreply.github.com>
Co-authored-by: xming521 <32786500+xming521@users.noreply.github.com>
Co-authored-by: ywh555hhh <121592812+ywh555hhh@users.noreply.github.com>
Co-authored-by: stevessr <89645372+stevessr@users.noreply.github.com>
Co-authored-by: roeseth <41995115+roeseth@users.noreply.github.com>
Co-authored-by: ikun-1145141 <265925499+ikun-1145141@users.noreply.github.com>
Co-authored-by: evpeople <54983536+evpeople@users.noreply.github.com>
Co-authored-by: Yue-bin <60509781+Yue-bin@users.noreply.github.com>
Co-authored-by: W1ndys <109416673+W1ndys@users.noreply.github.com>
Co-authored-by: TheFurina <218887821+TheFurina@users.noreply.github.com>
Co-authored-by: Seayon <12275933+Seayon@users.noreply.github.com>
Co-authored-by: OnlyblackTea <38585636+OnlyblackTea@users.noreply.github.com>
Co-authored-by: ocetars <74854972+ocetars@users.noreply.github.com>
Co-authored-by: railgun19457 <117180744+railgun19457@users.noreply.github.com>
Co-authored-by: JunieXD <107397009+JunieXD@users.noreply.github.com>
Co-authored-by: advent259141 <197440256+advent259141@users.noreply.github.com>
Co-authored-by: Doge2077 <91442300+Doge2077@users.noreply.github.com>
Co-authored-by: Bocity <23430545+Bocity@users.noreply.github.com>
Co-authored-by: Aurora-xk <192227833+Aurora-xk@users.noreply.github.com>
This commit is contained in:
Soulter
2026-03-09 23:38:21 +08:00
committed by GitHub
parent 795aec9578
commit fc33b3eb68
219 changed files with 20618 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.gitignore
+6
View File
@@ -0,0 +1,6 @@
__pycache__/
venv/
.DS_Store
node_modules/
.vitepress/cache
*dist
docs/.vitepress/config.mjs
+530
View File
@@ -0,0 +1,530 @@
import { defineConfig } from "vitepress";
import { head } from "./config/head";
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: "AstrBot",
description: "AstrBot",
head: head,
rewrites: {
'zh/:rest*': ':rest*'
},
sitemap: {
hostname: "https://docs.astrbot.app",
},
lastUpdated: true,
ignoreDeadLinks: true,
locales: {
root: {
label: "简体中文",
lang: "zh-Hans",
themeConfig: {
nav: [
{ text: "主页", link: "https://astrbot.app" },
{ text: "博客", link: "https://blog.astrbot.app" },
{ text: "路线图", link: "https://astrbot.featurebase.app/roadmap" },
{ text: "HTTP API", link: "https://docs.astrbot.app/scalar.html" },
],
sidebar: [
{
text: "简介",
items: [
{ text: "关于 AstrBot", link: "/what-is-astrbot" },
{ text: "社区", link: "/community" },
{ text: "常见问题", link: "/faq" },
],
},
{
text: "部署",
base: "/deploy",
collapsed: false,
items: [
{ text: "包管理器部署", link: "/astrbot/package" },
{ text: "雨云一键云部署", link: "/astrbot/rainyun" },
{ text: "桌面客户端部署", link: "/astrbot/desktop" },
{ text: "启动器一键部署", link: "/astrbot/launcher" },
{ text: "Docker 部署", link: "/astrbot/docker" },
{ text: "Kubernetes 部署", link: "/astrbot/kubernetes" },
{ text: "宝塔面板部署", link: "/astrbot/btpanel" },
{ text: "1Panel 部署", link: "/astrbot/1panel" },
{ text: "手动部署", link: "/astrbot/cli" },
{
text: "其他部署方式",
link: "/astrbot/other-deployments",
collapsed: true,
items: [
{ text: "CasaOS 部署", link: "/astrbot/casaos" },
{ text: "优云智算 GPU 部署", link: "/astrbot/compshare" },
{ text: "社区提供的部署方式", link: "/astrbot/community-deployment" },
],
},
{
text: "支持我们",
link: "/when-deployed",
},
],
},
{
text: "接入消息平台",
base: "/platform",
items: [
{
text: "快速接入指南",
link: "/start",
},
{
text: "QQ 官方机器人",
link: "/qqofficial",
collapsed: true,
items: [
{ text: "Websockets 方式(推荐)", link: "/qqofficial/websockets" },
{ text: "Webhook 方式", link: "/qqofficial/webhook" },
],
},
{
text: "OneBot v11",
base: "/platform/aiocqhttp",
collapsed: true,
items: [
{ text: "NapCat", link: "/napcat" },
{ text: "Lagrange", link: "/lagrange" },
{ text: "其他端", link: "/others" },
],
},
{ text: "企微应用", link: "/wecom" },
{ text: "企微智能机器人", link: "/wecom_ai_bot" },
{ text: "微信公众号", link: "/weixin-official-account" },
{ text: "飞书", link: "/lark" },
{ text: "钉钉", link: "/dingtalk" },
{ text: "Telegram", link: "/telegram" },
{ text: "LINE", link: "/line" },
{ text: "Slack", link: "/slack" },
{ text: "Misskey", link: "/misskey" },
{ text: "Discord", link: "/discord" },
{ text: "KOOK", link: "/kook" },
{
text: "Satori",
base: "/platform/satori",
collapsed: true,
items: [
{ text: "使用 LLOneBot", link: "/llonebot" },
{ text: "使用 server-satori", link: "/server-satori" },
],
},
{
text: "社区提供",
collapsed: false,
items: [
{ text: "Matrix", link: "/matrix" },
{ text: "VoceChat", link: "/vocechat" },
],
},
],
},
{
text: "接入 AI",
base: "/providers",
items: [
{
text: "✨ 接入模型服务",
link: "/start",
collapsed: true,
items: [
{ text: "NewAPI", link: "/newapi" },
{ text: "AIHubMix", link: "/aihubmix" },
{ text: "PPIO 派欧云", link: "/ppio" },
{ text: "硅基流动", link: "/siliconflow" },
{ text: "小马算力", link: "/tokenpony" },
{ text: "302.AI", link: "/302ai" },
{ text: "Ollama", link: "/provider-ollama" },
{ text: "LMStudio", link: "/provider-lmstudio" },
]
},
{
text: "⚙️ Agent 执行器",
link: "/agent-runners",
collapsed: false,
items: [
{ text: "内置 Agent 执行器", link: "/agent-runners/astrbot-agent-runner" },
{ text: "Dify", link: "/agent-runners/dify" },
{ text: "扣子 Coze", link: "/agent-runners/coze" },
{ text: "阿里云百炼应用", link: "/agent-runners/dashscope" },
{ text: "DeerFlow", link: "/agent-runners/deerflow" },
]
},
],
},
{
text: "使用",
base: "/use",
items: [
{ text: "WebUI", link: "/webui" },
{ text: "插件", link: "/plugin" },
{ text: "内置指令", link: "/command" },
{ text: "工具使用 Tools", link: "/function-calling" },
{ text: "技能 Skills", link: "/skills" },
{ text: "SubAgent 编排", link: "/subagent" },
{ text: "主动型 Agent 能力", link: "/proactive-agent" },
{ text: "MCP", link: "/mcp" },
{ text: "网页搜索", link: "/websearch" },
{ text: "知识库", link: "/knowledge-base" },
{ text: "自定义规则", link: "/custom-rules" },
{ text: "Agent 执行器", link: "/agent-runner" },
{ text: "统一 Webhook 模式", link: "/unified-webhook" },
{ text: "自动上下文压缩", link: "/context-compress" },
{ text: "Agent 沙箱环境", link: "/astrbot-agent-sandbox" },
],
},
{
text: "开发",
base: "/dev",
collapsed: true,
items: [
{
text: "插件开发",
base: "/dev/star",
collapsed: true,
items: [
{ text: "🌠 从这里开始", link: "/plugin-new" },
{ text: "最小实例", link: "/guides/simple" },
{ text: "接收消息事件", link: "/guides/listen-message-event" },
{ text: "发送消息", link: "/guides/send-message" },
{ text: "插件配置", link: "/guides/plugin-config" },
{ text: "调用 AI", link: "/guides/ai" },
{ text: "存储", link: "/guides/storage" },
{ text: "文转图", link: "/guides/html-to-pic" },
{ text: "会话控制器", link: "/guides/session-control" },
{ text: "杂项", link: "/guides/other" },
{ text: "发布插件", link: "/plugin-publish" },
{ text: "插件指南（旧）", link: "/plugin" },
],
},
{
text: "接入平台适配器",
link: "/plugin-platform-adapter",
},
{
text: "AstrBot HTTP API",
link: "/openapi",
},
{
text: "AstrBot 配置文件",
link: "/astrbot-config",
},
],
},
{
text: "其他",
base: "/others",
collapsed: true,
items: [
{ text: "自部署文转图", link: "/self-host-t2i" },
{ text: "插件下载不了?试试自建 GitHub 加速服务", link: "/github-proxy" },
],
},
{
text: "开源之夏",
base: "/ospp",
collapsed: true,
items: [{ text: "OSPP 2025", link: "/2025" }],
},
],
outline: {
level: 'deep',
label: '目录',
},
darkModeSwitchLabel: '切换日光/暗黑模式',
sidebarMenuLabel: '文章',
returnToTopLabel: '返回顶部',
docFooter: {
prev: '上一篇',
next: '下一篇'
},
editLink: {
pattern: 'https://github.com/AstrBotdevs/AstrBot-docs/edit/v4/:path',
text: '发现文档有问题？在 GitHub 上编辑此页',
},
logo: '/logo_prod.png',
socialLinks: [
{ icon: "github", link: "https://github.com/AstrBotDevs/AstrBot" },
],
footer: {
message: 'Deployed on&nbsp' +
'<a href="https://www.rainyun.com/NjY3OTQ5_" class="deployment-link" style="display: inline-flex; align-items: center;">' +
'<img src="https://www.rainyun.com/img/logo.d193755d.png" width="50" alt="Rainyun Logo">' +
'</a>',
}
}
},
en: {
label: "English",
lang: "en-US",
themeConfig: {
nav: [
{ text: "Home", link: "https://astrbot.app" },
{ text: "Blog", link: "https://blog.astrbot.app" },
{ text: "Roadmap", link: "https://astrbot.featurebase.app/roadmap" },
{ text: "HTTP API", link: "https://docs.astrbot.app/scalar.html" },
],
sidebar: [
{
text: "Introduction",
items: [
{ text: "What is AstrBot", link: "/en/what-is-astrbot" },
{ text: "Community", link: "/en/community" },
{ text: "FAQ", link: "/en/faq" },
],
},
{
text: "Deployment",
base: "/en/deploy",
collapsed: false,
items: [
{ text: "Package Manager", link: "/astrbot/package" },
{ text: "One-click Launcher", link: "/astrbot/launcher" },
{ text: "Docker", link: "/astrbot/docker" },
{ text: "Kubernetes", link: "/astrbot/kubernetes" },
{ text: "BT Panel", link: "/astrbot/btpanel" },
{ text: "1Panel", link: "/astrbot/1panel" },
{ text: "Manual", link: "/astrbot/cli" },
{
text: "Other Deployments",
link: "/astrbot/other-deployments",
collapsed: true,
items: [
{ text: "CasaOS", link: "/astrbot/casaos" },
{ text: "Compshare GPU", link: "/astrbot/compshare" },
{ text: "Community-provided Deployment", link: "/astrbot/community-deployment" },
],
},
{
text: "Support Us",
link: "/when-deployed",
},
],
},
{
text: "Messaging Platforms",
base: "/en/platform",
collapsed: false,
items: [
{
text: "Quick Start",
link: "/start",
},
{
text: "QQ Official Bot",
link: "/qqofficial",
collapsed: true,
items: [
{ text: "Websockets", link: "/qqofficial/websockets" },
{ text: "Webhook", link: "/qqofficial/webhook" },
],
},
{
text: "OneBot v11",
base: "/en/platform/aiocqhttp",
collapsed: true,
items: [
{ text: "NapCat", link: "/napcat" },
{ text: "Lagrange", link: "/lagrange" },
{ text: "Other Clients", link: "/others" },
],
},
{ text: "WeCom Application", link: "/wecom" },
{ text: "WeCom AI Bot", link: "/wecom_ai_bot" },
{ text: "WeChat Official Account", link: "/weixin-official-account" },
{ text: "Lark", link: "/lark" },
{ text: "DingTalk", link: "/dingtalk" },
{ text: "Telegram", link: "/telegram" },
{ text: "LINE", link: "/line" },
{ text: "Slack", link: "/slack" },
{ text: "Misskey", link: "/misskey" },
{ text: "Discord", link: "/discord" },
{
text: "Satori",
base: "/en/platform/satori",
collapsed: true,
items: [
{ text: "Using LLOneBot", link: "/llonebot" },
{ text: "Using server-satori", link: "/server-satori" },
],
},
{
text: "Community-provided",
collapsed: false,
items: [
{ text: "Matrix", link: "/matrix" },
{ text: "KOOK", link: "/kook" },
{ text: "VoceChat", link: "/vocechat" },
],
},
],
},
{
text: "AI Integration",
base: "/en/providers",
collapsed: false,
items: [
{
text: "✨ Model Providers",
link: "/start",
collapsed: true,
items: [
{ text: "NewAPI", link: "/newapi" },
{ text: "AIHubMix", link: "/aihubmix" },
{ text: "PPIO Cloud", link: "/ppio" },
{ text: "SiliconFlow", link: "/siliconflow" },
{ text: "TokenPony", link: "/tokenpony" },
{ text: "302.AI", link: "/302ai" },
{ text: "Ollama", link: "/provider-ollama" },
{ text: "LMStudio", link: "/provider-lmstudio" },
],
},
{
text: "⚙️ Agent Runners",
link: "/agent-runners",
collapsed: false,
items: [
{ text: "Built-in Agent Runner", link: "/agent-runners/astrbot-agent-runner" },
{ text: "Dify", link: "/agent-runners/dify" },
{ text: "Coze", link: "/agent-runners/coze" },
{ text: "Alibaba Bailian", link: "/agent-runners/dashscope" },
{ text: "DeerFlow", link: "/agent-runners/deerflow" },
],
},
],
},
{
text: "Usage",
base: "/en/use",
collapsed: true,
items: [
{ text: "WebUI", link: "/webui" },
{ text: "Plugins", link: "/plugin" },
{ text: "Built-in Commands", link: "/command" },
{ text: "Tool Use", link: "/function-calling" },
{ text: "Anthropic Skills", link: "/skills" },
{ text: "SubAgent Orchestration", link: "/subagent" },
{ text: "Proactive Tasks", link: "/proactive-agent" },
{ text: "MCP", link: "/mcp" },
{ text: "Web Search", link: "/websearch" },
{ text: "Knowledge Base", link: "/knowledge-base" },
{ text: "Custom Rules", link: "/custom-rules" },
{ text: "Agent Runner", link: "/agent-runner" },
{ text: "Unified Webhook Mode", link: "/unified-webhook" },
{ text: "Auto Context Compression", link: "/context-compress" },
{ text: "Agent Sandbox", link: "/astrbot-agent-sandbox" },
],
},
{
text: "Development",
base: "/en/dev",
collapsed: true,
items: [
{
text: "Plugin Development",
base: "/en/dev/star",
collapsed: true,
items: [
{ text: "🌠 Getting Started", link: "/plugin-new" },
{ text: "Minimal Example", link: "/guides/simple" },
{ text: "Listen to Message Events", link: "/guides/listen-message-event" },
{ text: "Send Messages", link: "/guides/send-message" },
{ text: "Plugin Configuration", link: "/guides/plugin-config" },
{ text: "AI", link: "/guides/ai" },
{ text: "Storage", link: "/guides/storage" },
{ text: "HTML to Image", link: "/guides/html-to-pic" },
{ text: "Session Control", link: "/guides/session-control" },
{ text: "Publish Plugin", link: "/plugin-publish" },
],
},
{
text: "Platform Adapter Integration",
link: "/plugin-platform-adapter",
},
{
text: "AstrBot HTTP API",
link: "/openapi",
},
{
text: "AstrBot Configuration File",
link: "/astrbot-config",
},
],
},
{
text: "Others",
base: "/en/others",
collapsed: true,
items: [
{ text: "Self-hosted HTML to Image", link: "/self-host-t2i" },
],
},
{
text: "Open Source Summer",
base: "/en/ospp",
collapsed: true,
items: [{ text: "OSPP 2025", link: "/2025" }],
},
],
outline: {
level: 'deep',
label: 'On this page',
},
darkModeSwitchLabel: 'Toggle dark mode',
sidebarMenuLabel: 'Menu',
returnToTopLabel: 'Return to top',
docFooter: {
prev: 'Previous',
next: 'Next'
},
editLink: {
pattern: 'https://github.com/AstrBotdevs/AstrBot-docs/edit/v4/:path',
text: 'Edit this page on GitHub',
},
logo: '/logo_prod.png',
socialLinks: [
{ icon: "github", link: "https://github.com/AstrBotDevs/AstrBot" },
],
footer: {
message: 'Deployed on&nbsp' +
'<a href="https://www.rainyun.com/NjY3OTQ5_" class="deployment-link" style="display: inline-flex; align-items: center;">' +
'<img src="https://www.rainyun.com/img/logo.d193755d.png" width="50" alt="Rainyun Logo">' +
'</a>',
}
}
},
},
themeConfig: {
search: {
provider: "local",
options: {
locales: {
root: {
translations: {
button: {
buttonText: "搜索文档",
buttonAriaLabel: "搜索文档",
},
modal: {
noResultsText: "无法找到相关结果",
resetButtonTitle: "清除查询条件",
footer: {
selectText: "选择",
navigateText: "切换",
closeText: "关闭",
},
},
},
},
},
},
},
}
});
docs/.vitepress/config/head.ts
+47
View File
@@ -0,0 +1,47 @@
import type { HeadConfig } from "vitepress";
export const head: HeadConfig[] = [
// --- Google Fonts ---
["link", { rel: "preconnect", href: "https://fonts.googleapis.cn", crossorigin: "" }],
["link", { rel: "dns-prefetch", href: "https://fonts.googleapis.cn" }],
["link", { rel: "preconnect", href: "https://fonts.gstatic.cn", crossorigin: "" }],
["link", { rel: "dns-prefetch", href: "https://fonts.gstatic.cn" }],
["link", { rel: "stylesheet", href: "https://fonts.googleapis.com/css2?family=Outfit:wght@100..900&display=swap" }],
// --- 基础和SEO元数据 ---
["link", { rel: "icon", href: "/logo.png" }],
["meta", { name: "description", content: "AstrBot" }],
[
"meta",
{ name: "viewport", content: "width=device-width, initial-scale=1.0" },
],
/* // --- Open Graph (OG) 协议元数据 (用于社交媒体分享) ---
["meta", { property: "og:type", content: "website" }],
["meta", { property: "og:locale", content: "zh_CN" }],
["meta", { property: "og:title", content: "AstrBot" }],
["meta", { property: "og:description", content: "AstrBot" }],
["meta", { property: "og:url", content: "https://docs.astrbot.app" }],
["meta", { property: "og:site_name", content: "AstrBot" }],
[
"meta",
{
property: "og:image",
content: "/",
},
],
[
"meta",
{ property: "og:image:alt", content: "AstrBot" },
],
["meta", { property: "og:image:width", content: "1200" }],
["meta", { property: "og:image:height", content: "630" }],
["meta", { property: "og:image:type", content: "image/png" }],
// --- Twitter Card 元数据 ---
["meta", { name: "twitter:card", content: "summary_large_image" }],
["meta", { name: "twitter:site", content: "@AstrBot" }],*/
// --- Umami Analytics ---
["script", { defer: "", src: "https://cloud.umami.is/script.js", "data-website-id": "9c3f777e-9f4a-4b79-a5c3-ff94f5dca8f9" }],
];
docs/.vitepress/theme/components/ArticleShare.vue
+194
View File
@@ -0,0 +1,194 @@
<script setup lang="ts">
import { ref, computed, onMounted } from "vue"
const props = defineProps({
shareText: {
type: String,
default: "分享链接",
},
copiedText: {
type: String,
default: "已复制!",
},
includeQuery: {
type: Boolean,
default: false,
},
includeHash: {
type: Boolean,
default: false,
},
copiedTimeout: {
type: Number,
default: 2000,
},
})
defineOptions({ name: "ArticleShare" })
const copied = ref(false)
const isClient =
typeof window !== "undefined" && typeof document !== "undefined"
const shareLink = computed(() => {
if (!isClient) return ""
const { origin, pathname, search, hash } = window.location
const finalSearch = props.includeQuery ? search : ""
const finalHash = props.includeHash ? hash : ""
return `${origin}${pathname}${finalSearch}${finalHash}`
})
async function copyToClipboard() {
if (copied.value || !isClient) return
try {
if (navigator.clipboard) {
await navigator.clipboard.writeText(shareLink.value)
} else {
const input = document.createElement("input")
input.setAttribute("readonly", "readonly")
input.setAttribute("value", shareLink.value)
document.body.appendChild(input)
input.select()
document.execCommand("copy")
document.body.removeChild(input)
}
copied.value = true
setTimeout(() => {
copied.value = false
}, props.copiedTimeout)
} catch (error) {
console.error("复制链接失败:", error)
}
}
const shareIconSvg = `
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M4 12v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8"></path>
<polyline points="16 6 12 2 8 6"></polyline>
<line x1="12" y1="2" x2="12" y2="15"></line>
</svg>
`
const copiedIconSvg = `
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M20 6 9 17l-5-5"></path>
</svg>
`
// onMounted(() => {
// const script = document.createElement('script')
// script.src = 'https://cdn.wwads.cn/js/makemoney.js'
// script.async = true
// document.head.appendChild(script)
// })
</script>
<template>
<div style="display: flex; justify-content: center; align-items: center; flex-direction: column;">
<div class="article-share">
<button :class="['article-share__button', { copied: copied }]"
:aria-label="copied ? props.copiedText : props.shareText" aria-live="polite" @click="copyToClipboard">
<div v-if="!copied" class="content-wrapper">
<span class="icon" v-html="shareIconSvg"></span>
{{ props.shareText }}
</div>
<div v-else class="content-wrapper">
<span class="icon" v-html="copiedIconSvg"></span>
{{ props.copiedText }}
</div>
</button>
</div>
<!-- <div class="wwads-cn wwads-vertical sponsors" data-id="380" style="max-width:180px"></div> -->
</div>
</template>
<style scoped>
.article-share {
padding: 14px 0;
width: 100%;
}
.article-share__button {
display: flex;
justify-content: center;
align-items: center;
font-weight: 500;
font-size: 14px;
position: relative;
z-index: 1;
transition: all 0.4s var(--ease-out-cubic, cubic-bezier(0.33, 1, 0.68, 1));
cursor: pointer;
border: 1px solid transparent;
border-radius: 14px;
padding: 7px 14px;
width: 100%;
overflow: hidden;
color: var(--vp-c-text-1, #333);
background-color: var(--vp-c-bg-alt, #f6f6f7);
box-shadow: 0 2px 5px rgba(0, 0, 0, 0.02);
will-change: transform, box-shadow;
}
.article-share__button::before {
content: "";
position: absolute;
top: 0;
left: -100%;
z-index: -1;
transition: left 0.6s ease;
background-color: var(--vp-c-brand-soft, #ddf4ff);
width: 100%;
height: 100%;
}
.article-share__button:hover {
transform: translateY(-1px);
border-color: var(--vp-c-brand-soft, #ddf4ff);
background-color: var(--vp-c-brand-soft, #ddf4ff);
}
.article-share__button:active {
transform: scale(0.9);
}
.article-share__button.copied {
color: var(--vp-c-brand-1, #007acc);
/* 增加了备用颜色 */
background-color: var(--vp-c-brand-soft, #ddf4ff);
}
.article-share__button.copied::before {
left: 0;
background-color: var(--vp-c-brand-soft, #ddf4ff);
}
.content-wrapper {
display: flex;
align-items: center;
justify-content: center;
}
.icon {
display: inline-flex;
align-items: center;
margin-right: 6px;
}
.sponsors {
max-width: 100%;
margin: 0 !important;
background-color: transparent !important;
}
.sponsors .wwads-text {
color: var(--vp-c-text-1) !important;
transition-property: color;
transition-duration: 500ms;
transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
}
</style>
docs/.vitepress/theme/components/HomeFeaturesAfter.vue
+7
View File
@@ -0,0 +1,7 @@
<template>
<div style="display: flex; justify-content: center; align-items: center; margin-top: 16px; gap: 12px;">
<span style="font-size: 13px; color: #666; font-style: italic;;">Deployed on</span>
<a href="https://www.rainyun.com/NjY3OTQ1_"><img src="https://www.rainyun.com/img/logo.d193755d.png" width="50" alt="Rainyun Logo"></a>
</div>
</template>
docs/.vitepress/theme/components/Layout.vue
+131
View File
@@ -0,0 +1,131 @@
<script setup>
import { useRoute } from 'vitepress'
import { computed, provide, useSlots, watch } from 'vue'
import VPBackdrop from 'vitepress/dist/client/theme-default/components/VPBackdrop.vue'
import VPContent from 'vitepress/dist/client/theme-default/components/VPContent.vue'
import VPFooter from 'vitepress/dist/client/theme-default/components/VPFooter.vue'
import VPLocalNav from 'vitepress/dist/client/theme-default/components/VPLocalNav.vue'
import VPNav from 'vitepress/dist/client/theme-default/components/VPNav.vue'
import VPSidebar from 'vitepress/dist/client/theme-default/components/VPSidebar.vue'
import VPSkipLink from 'vitepress/dist/client/theme-default/components/VPSkipLink.vue'
import { useData } from 'vitepress/dist/client/theme-default/composables/data'
import { useCloseSidebarOnEscape, useSidebar } from 'vitepress/dist/client/theme-default/composables/sidebar'
import SectionTabs from './SectionTabs.vue'
const {
isOpen: isSidebarOpen,
open: openSidebar,
close: closeSidebar
} = useSidebar()
const route = useRoute()
watch(() => route.path, closeSidebar)
useCloseSidebarOnEscape(isSidebarOpen, closeSidebar)
const { frontmatter } = useData()
const sidebarScopeClass = computed(() => {
const path = route.path
const normalizedPath = path
.replace(/\.html$/, '')
.replace(/\/$/, '') || '/'
if (
normalizedPath === '/what-is-astrbot' || normalizedPath === '/community' || normalizedPath === '/faq'
|| path.startsWith('/deploy/') || path.startsWith('/others/') || path.startsWith('/ospp/')
|| normalizedPath === '/en/what-is-astrbot' || normalizedPath === '/en/community' || normalizedPath === '/en/faq'
|| path.startsWith('/en/deploy/') || path.startsWith('/en/others/') || path.startsWith('/en/ospp/')
)
return 'sidebar-scope-intro-deploy'
if (path.startsWith('/platform/') || path.startsWith('/en/platform/'))
return 'sidebar-scope-platform'
if (path.startsWith('/providers/') || path.startsWith('/en/providers/'))
return 'sidebar-scope-providers'
if (path.startsWith('/use/') || path.startsWith('/en/use/'))
return 'sidebar-scope-use'
if (path.startsWith('/dev/') || path.startsWith('/en/dev/'))
return 'sidebar-scope-dev'
return ''
})
const slots = useSlots()
const heroImageSlotExists = computed(() => !!slots['home-hero-image'])
provide('hero-image-slot-exists', heroImageSlotExists)
</script>
<template>
<div
v-if="frontmatter.layout !== false"
class="Layout"
:class="[frontmatter.pageClass, sidebarScopeClass]"
>
<slot name="layout-top" />
<VPSkipLink />
<VPBackdrop class="backdrop" :show="isSidebarOpen" @click="closeSidebar" />
<VPNav>
<template #nav-bar-title-before><slot name="nav-bar-title-before" /></template>
<template #nav-bar-title-after><slot name="nav-bar-title-after" /></template>
<template #nav-bar-content-before><slot name="nav-bar-content-before" /></template>
<template #nav-bar-content-after><slot name="nav-bar-content-after" /></template>
<template #nav-screen-content-before><slot name="nav-screen-content-before" /></template>
<template #nav-screen-content-after><slot name="nav-screen-content-after" /></template>
</VPNav>
<SectionTabs />
<VPLocalNav :open="isSidebarOpen" @open-menu="openSidebar" />
<VPSidebar :open="isSidebarOpen">
<template #sidebar-nav-before><slot name="sidebar-nav-before" /></template>
<template #sidebar-nav-after><slot name="sidebar-nav-after" /></template>
</VPSidebar>
<VPContent>
<template #page-top><slot name="page-top" /></template>
<template #page-bottom><slot name="page-bottom" /></template>
<template #not-found><slot name="not-found" /></template>
<template #home-hero-before><slot name="home-hero-before" /></template>
<template #home-hero-info-before><slot name="home-hero-info-before" /></template>
<template #home-hero-info><slot name="home-hero-info" /></template>
<template #home-hero-info-after><slot name="home-hero-info-after" /></template>
<template #home-hero-actions-after><slot name="home-hero-actions-after" /></template>
<template #home-hero-image><slot name="home-hero-image" /></template>
<template #home-hero-after><slot name="home-hero-after" /></template>
<template #home-features-before><slot name="home-features-before" /></template>
<template #home-features-after><slot name="home-features-after" /></template>
<template #doc-footer-before><slot name="doc-footer-before" /></template>
<template #doc-before><slot name="doc-before" /></template>
<template #doc-after><slot name="doc-after" /></template>
<template #doc-top><slot name="doc-top" /></template>
<template #doc-bottom><slot name="doc-bottom" /></template>
<template #aside-top><slot name="aside-top" /></template>
<template #aside-bottom><slot name="aside-bottom" /></template>
<template #aside-outline-before><slot name="aside-outline-before" /></template>
<template #aside-outline-after><slot name="aside-outline-after" /></template>
<template #aside-ads-before><slot name="aside-ads-before" /></template>
<template #aside-ads-after><slot name="aside-ads-after" /></template>
</VPContent>
<VPFooter />
<slot name="layout-bottom" />
</div>
<Content v-else />
</template>
<style scoped>
.Layout {
display: flex;
flex-direction: column;
min-height: 100vh;
}
</style>
docs/.vitepress/theme/components/NotFound.vue
+73
View File
@@ -0,0 +1,73 @@
<script setup>
import { useRouter } from 'vitepress'
const router = useRouter()
const goHome = () => {
router.go('/')
}
</script>
<template>
<div class="NotFound">
<img src="/404-seio.png" alt="404 Not Found" class="not-found-image" />
<h1 class="not-found-title">😢 你来到了未知的领域，页面不存在！</h1>
<p class="not-found-desc">请点击左上角 Logo 返回首页，或点击下方按钮。</p>
<button @click="goHome" class="not-found-button">返回首页</button>
</div>
</template>
<style scoped>
.NotFound {
padding: 4rem 2rem;
text-align: center;
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
min-height: 60vh;
}
.not-found-image {
max-width: 400px;
width: 100%;
margin-bottom: 2rem;
}
.not-found-title {
font-size: 1.5rem;
margin-bottom: 1rem;
color: var(--vp-c-text-1);
}
.not-found-desc {
font-size: 1rem;
margin-bottom: 2rem;
color: var(--vp-c-text-2);
}
.not-found-button {
padding: 0.75rem 1.5rem;
font-size: 1rem;
color: #fff;
background-color: var(--vp-c-brand-1);
border: none;
border-radius: 8px;
cursor: pointer;
transition: background-color 0.2s;
}
.not-found-button:hover {
background-color: var(--vp-c-brand-2);
}
@media (max-width: 768px) {
.not-found-image {
max-width: 300px;
}
.not-found-title {
font-size: 1.25rem;
}
}
</style>
docs/.vitepress/theme/components/SectionTabs.vue
+121
View File
@@ -0,0 +1,121 @@
<script setup>
import { computed } from 'vue'
import { useData, useRoute } from 'vitepress'
const route = useRoute()
const { frontmatter } = useData()
const isEnglish = computed(() => route.path.startsWith('/en/'))
const zhTabs = [
{
text: '简介和部署',
link: '/what-is-astrbot',
matchers: ['/what-is-astrbot', '/community', '/faq', '/deploy/', '/others/', '/ospp/']
},
{ text: '接入消息平台', link: '/platform/start', matchers: ['/platform/'] },
{ text: '接入 AI', link: '/providers/start', matchers: ['/providers/'] },
{ text: '使用', link: '/use/webui', matchers: ['/use/'] },
{ text: '开发', link: '/dev/star/plugin-new', matchers: ['/dev/'] }
]
const enTabs = [
{
text: 'Intro & Deploy',
link: '/en/what-is-astrbot',
matchers: ['/en/what-is-astrbot', '/en/community', '/en/faq', '/en/deploy/', '/en/others/', '/en/ospp/']
},
{ text: 'Messaging Platforms', link: '/en/platform/start', matchers: ['/en/platform/'] },
{ text: 'AI Integration', link: '/en/providers/start', matchers: ['/en/providers/'] },
{ text: 'Usage', link: '/en/use/webui', matchers: ['/en/use/'] },
{ text: 'Development', link: '/en/dev/star/plugin-new', matchers: ['/en/dev/'] }
]
const tabs = computed(() => (isEnglish.value ? enTabs : zhTabs))
const isHome = computed(() => route.path === '/' || route.path === '/en/')
const shouldShow = computed(() => frontmatter.value.layout !== false && frontmatter.value.layout !== 'home' && !isHome.value)
function isActive(tab) {
return tab.matchers.some(prefix => route.path.startsWith(prefix))
}
</script>
<template>
<template v-if="shouldShow">
<div class="VPSectionTabsPlaceholder" aria-hidden="true" />
<div class="VPSectionTabs">
<div class="container">
<a
v-for="tab in tabs"
:key="tab.link"
class="tab"
:class="{ active: isActive(tab) }"
:href="tab.link"
>
{{ tab.text }}
</a>
</div>
</div>
</template>
</template>
<style scoped>
.VPSectionTabs {
display: none;
}
.VPSectionTabsPlaceholder {
display: none;
}
@media (min-width: 1280px) {
.VPSectionTabsPlaceholder {
display: block;
height: var(--vp-section-tabs-height, 44px);
}
.VPSectionTabs {
display: block;
position: fixed;
left: 0;
right: 0;
top: calc(var(--vp-layout-top-height, 0px) + var(--vp-nav-height));
z-index: 26;
border-bottom: 1px solid var(--vp-c-gutter);
background-color: var(--vp-nav-bg-color);
}
.container {
margin: 0 auto;
max-width: var(--vp-layout-max-width);
display: flex;
align-items: flex-end;
gap: 10px;
box-sizing: border-box;
height: var(--vp-section-tabs-height, 44px);
padding: 0 32px 8px;
}
.tab {
border-radius: 999px;
padding: 6px 12px;
font-size: 13px;
line-height: 20px;
color: var(--vp-c-text-2);
white-space: nowrap;
transition: color 0.2s ease, background-color 0.2s ease;
}
.tab:hover {
color: var(--vp-c-text-1);
background-color: var(--vp-c-default-soft);
}
.tab.active {
color: var(--vp-c-brand-1);
background-color: var(--vp-c-brand-soft);
}
}
</style>
docs/.vitepress/theme/index.js
+21
View File
@@ -0,0 +1,21 @@
// https://vitepress.dev/guide/custom-theme
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import './styles/style.css'
import './styles/custom-block.css'
import './styles/font.css'
import Layout from './components/Layout.vue'
import ArticleShare from './components/ArticleShare.vue'
import NotFound from './components/NotFound.vue'
/** @type {import('vitepress').Theme} */
export default {
extends: DefaultTheme,
Layout() {
return h(Layout, null, {
// https://vitepress.dev/guide/extending-default-theme#layout-slots
'aside-outline-after': () => h(ArticleShare),
'not-found': () => h(NotFound)
})
}
}
docs/.vitepress/theme/styles/custom-block.css
+185
View File
@@ -0,0 +1,185 @@
/* .vitepress/theme/style/custom-block.css */
/* 深浅色卡 */
:root {
--custom-block-info-left: #cccccc;
--custom-block-info-bg: #fafafa;
--custom-block-tip-left: #009400;
--custom-block-tip-bg: #b6dcc7;
--custom-block-warning-left: #e6a700;
--custom-block-warning-bg: #ffe69d;
--custom-block-danger-left: #e13238;
--custom-block-danger-bg: #ffebec;
--custom-block-note-left: #4cb3d4;
--custom-block-note-bg: #d6eff7;
--custom-block-important-left: #a371f7;
--custom-block-important-bg: #f4eefe;
--custom-block-caution-left: #e0575b;
--custom-block-caution-bg: #fde4e8;
}
.dark {
--custom-block-info-left: #cccccc;
--custom-block-info-bg: #474748;
--custom-block-tip-left: #009400;
--custom-block-tip-bg: #003100;
--custom-block-warning-left: #e6a700;
--custom-block-warning-bg: #4d3800;
--custom-block-danger-left: #e13238;
--custom-block-danger-bg: #4b1113;
--custom-block-note-left: #4cb3d4;
--custom-block-note-bg: #193c47;
--custom-block-important-left: #a371f7;
--custom-block-important-bg: #230555;
--custom-block-caution-left: #e0575b;
--custom-block-caution-bg: #391c22;
}
/* 标题字体大小 */
.custom-block-title {
font-size: 16px;
}
/* info容器:背景色、左侧 */
.custom-block.info {
background-color: var(--custom-block-info-bg);
}
/* info容器:svg图 */
.custom-block.info [class*="custom-block-title"]::before {
content: '';
background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 22C6.477 22 2 17.523 2 12S6.477 2 12 2s10 4.477 10 10-4.477 10-10 10zm-1-11v6h2v-6h-2zm0-4v2h2V7h-2z' fill='%23ccc'/%3E%3C/svg%3E");
width: 20px;
height: 20px;
display: inline-block;
vertical-align: middle;
position: relative;
margin-right: 4px;
left: -5px;
top: -1px;
}
/* 提示容器:边框色、背景色、左侧 */
.custom-block.tip {
background-color: var(--custom-block-tip-bg);
}
/* 提示容器:svg图 */
.custom-block.tip [class*="custom-block-title"]::before {
content: '';
background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='%23009400' d='M7.941 18c-.297-1.273-1.637-2.314-2.187-3a8 8 0 1 1 12.49.002c-.55.685-1.888 1.726-2.185 2.998H7.94zM16 20v1a2 2 0 0 1-2 2h-4a2 2 0 0 1-2-2v-1h8zm-3-9.995V6l-4.5 6.005H11v4l4.5-6H13z'/%3E%3C/svg%3E");
width: 20px;
height: 20px;
display: inline-block;
vertical-align: middle;
position: relative;
margin-right: 4px;
left: -5px;
top: -2px;
}
/* 警告容器:背景色、左侧 */
.custom-block.warning {
background-color: var(--custom-block-warning-bg);
}
/* 警告容器:svg图 */
.custom-block.warning [class*="custom-block-title"]::before {
content: '';
background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1024 1024'%3E%3Cpath d='M576.286 752.57v-95.425q0-7.031-4.771-11.802t-11.3-4.772h-96.43q-6.528 0-11.3 4.772t-4.77 11.802v95.424q0 7.031 4.77 11.803t11.3 4.77h96.43q6.528 0 11.3-4.77t4.77-11.803zm-1.005-187.836 9.04-230.524q0-6.027-5.022-9.543-6.529-5.524-12.053-5.524H456.754q-5.524 0-12.053 5.524-5.022 3.516-5.022 10.547l8.538 229.52q0 5.023 5.022 8.287t12.053 3.265h92.913q7.032 0 11.803-3.265t5.273-8.287zM568.25 95.65l385.714 707.142q17.578 31.641-1.004 63.282-8.538 14.564-23.354 23.102t-31.892 8.538H126.286q-17.076 0-31.892-8.538T71.04 866.074q-18.582-31.641-1.004-63.282L455.75 95.65q8.538-15.57 23.605-24.61T512 62t32.645 9.04 23.605 24.61z' fill='%23e6a700'/%3E%3C/svg%3E");
width: 20px;
height: 20px;
display: inline-block;
vertical-align: middle;
position: relative;
margin-right: 4px;
left: -5px;
}
/* 危险容器:背景色、左侧 */
.custom-block.danger {
background-color: var(--custom-block-danger-bg);
}
/* 危险容器:svg图 */
.custom-block.danger [class*="custom-block-title"]::before {
content: '';
background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 2c5.523 0 10 4.477 10 10v3.764a2 2 0 0 1-1.106 1.789L18 19v1a3 3 0 0 1-2.824 2.995L14.95 23a2.5 2.5 0 0 0 .044-.33L15 22.5V22a2 2 0 0 0-1.85-1.995L13 20h-2a2 2 0 0 0-1.995 1.85L9 22v.5c0 .171.017.339.05.5H9a3 3 0 0 1-3-3v-1l-2.894-1.447A2 2 0 0 1 2 15.763V12C2 6.477 6.477 2 12 2zm-4 9a2 2 0 1 0 0 4 2 2 0 0 0 0-4zm8 0a2 2 0 1 0 0 4 2 2 0 0 0 0-4z' fill='%23e13238'/%3E%3C/svg%3E");
width: 20px;
height: 20px;
display: inline-block;
vertical-align: middle;
position: relative;
margin-right: 4px;
left: -5px;
top: -1px;
}
/* 提醒容器:背景色、左侧 */
.custom-block.note {
background-color: var(--custom-block-note-bg);
}
/* 提醒容器:svg图 */
.custom-block.note [class*="custom-block-title"]::before {
content: '';
background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 22C6.477 22 2 17.523 2 12S6.477 2 12 2s10 4.477 10 10-4.477 10-10 10zm-1-11v6h2v-6h-2zm0-4v2h2V7h-2z' fill='%234cb3d4'/%3E%3C/svg%3E");
width: 20px;
height: 20px;
display: inline-block;
vertical-align: middle;
position: relative;
margin-right: 4px;
left: -5px;
top: -1px;
}
/* 重要容器:背景色、左侧 */
.custom-block.important {
background-color: var(--custom-block-important-bg);
}
/* 重要容器:svg图 */
.custom-block.important [class*="custom-block-title"]::before {
content: '';
background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1024 1024'%3E%3Cpath d='M512 981.333a84.992 84.992 0 0 1-84.907-84.906h169.814A84.992 84.992 0 0 1 512 981.333zm384-128H128v-42.666l85.333-85.334v-256A298.325 298.325 0 0 1 448 177.92V128a64 64 0 0 1 128 0v49.92a298.325 298.325 0 0 1 234.667 291.413v256L896 810.667v42.666zm-426.667-256v85.334h85.334v-85.334h-85.334zm0-256V512h85.334V341.333h-85.334z' fill='%23a371f7'/%3E%3C/svg%3E");
width: 20px;
height: 20px;
display: inline-block;
vertical-align: middle;
position: relative;
margin-right: 4px;
left: -5px;
top: -1px;
}
/* 注意容器:背景色、左侧 */
.custom-block.caution {
background-color: var(--custom-block-caution-bg);
}
/* 注意容器:svg图 */
.custom-block.caution [class*="custom-block-title"]::before {
content: '';
background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 2c5.523 0 10 4.477 10 10v3.764a2 2 0 0 1-1.106 1.789L18 19v1a3 3 0 0 1-2.824 2.995L14.95 23a2.5 2.5 0 0 0 .044-.33L15 22.5V22a2 2 0 0 0-1.85-1.995L13 20h-2a2 2 0 0 0-1.995 1.85L9 22v.5c0 .171.017.339.05.5H9a3 3 0 0 1-3-3v-1l-2.894-1.447A2 2 0 0 1 2 15.763V12C2 6.477 6.477 2 12 2zm-4 9a2 2 0 1 0 0 4 2 2 0 0 0 0-4zm8 0a2 2 0 1 0 0 4 2 2 0 0 0 0-4z' fill='%23e13238'/%3E%3C/svg%3E");
width: 20px;
height: 20px;
display: inline-block;
vertical-align: middle;
position: relative;
margin-right: 4px;
left: -5px;
top: -1px;
}
docs/.vitepress/theme/styles/font.css
+5
View File
@@ -0,0 +1,5 @@
/* Keep only the top-left navbar title in Outfit; use VitePress defaults elsewhere. */
.VPNavBarTitle .title,
.VPNavBarTitle .title .text {
font-family: "Outfit", sans-serif !important;
}
docs/.vitepress/theme/styles/style.css
+358
View File
@@ -0,0 +1,358 @@
/**
* Customize default theme styling by overriding CSS variables:
* https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
*/
/**
* Colors
*
* Each colors have exact same color scale system with 3 levels of solid
* colors with different brightness, and 1 soft color.
*
* - `XXX-1`: The most solid color used mainly for colored text. It must
* satisfy the contrast ratio against when used on top of `XXX-soft`.
*
* - `XXX-2`: The color used mainly for hover state of the button.
*
* - `XXX-3`: The color for solid background, such as bg color of the button.
* It must satisfy the contrast ratio with pure white (#ffffff) text on
* top of it.
*
* - `XXX-soft`: The color used for subtle background such as custom container
* or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
* on top of it.
*
* The soft color must be semi transparent alpha channel. This is crucial
* because it allows adding multiple "soft" colors on top of each other
* to create a accent, such as when having inline code block inside
* custom containers.
*
* - `default`: The color used purely for subtle indication without any
* special meanings attached to it such as bg color for menu hover state.
*
* - `brand`: Used for primary brand colors, such as link text, button with
* brand theme, etc.
*
* - `tip`: Used to indicate useful information. The default theme uses the
* brand color for this by default.
*
* - `warning`: Used to indicate warning to the users. Used in custom
* container, badges, etc.
*
* - `danger`: Used to show error, or dangerous message to the users. Used
* in custom container, badges, etc.
* -------------------------------------------------------------------------- */
:root {
--vp-c-default-1: var(--vp-c-gray-1);
--vp-c-default-2: var(--vp-c-gray-2);
--vp-c-default-3: var(--vp-c-gray-3);
--vp-c-default-soft: var(--vp-c-gray-soft);
--vp-c-brand-1: var(--vp-c-indigo-1);
--vp-c-brand-2: var(--vp-c-indigo-2);
--vp-c-brand-3: var(--vp-c-indigo-3);
--vp-c-brand-soft: var(--vp-c-indigo-soft);
--vp-c-tip-1: var(--vp-c-brand-1);
--vp-c-tip-2: var(--vp-c-brand-2);
--vp-c-tip-3: var(--vp-c-brand-3);
--vp-c-tip-soft: var(--vp-c-brand-soft);
--vp-c-warning-1: var(--vp-c-yellow-1);
--vp-c-warning-2: var(--vp-c-yellow-2);
--vp-c-warning-3: var(--vp-c-yellow-3);
--vp-c-warning-soft: var(--vp-c-yellow-soft);
--vp-c-danger-1: var(--vp-c-red-1);
--vp-c-danger-2: var(--vp-c-red-2);
--vp-c-danger-3: var(--vp-c-red-3);
--vp-c-danger-soft: var(--vp-c-red-soft);
}
/**
* Component: Button
* -------------------------------------------------------------------------- */
:root {
--vp-button-brand-border: transparent;
--vp-button-brand-text: var(--vp-c-white);
--vp-button-brand-bg: var(--vp-c-brand-3);
--vp-button-brand-hover-border: transparent;
--vp-button-brand-hover-text: var(--vp-c-white);
--vp-button-brand-hover-bg: var(--vp-c-brand-2);
--vp-button-brand-active-border: transparent;
--vp-button-brand-active-text: var(--vp-c-white);
--vp-button-brand-active-bg: var(--vp-c-brand-1);
}
/**
* Component: Home
* -------------------------------------------------------------------------- */
:root {
--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: -webkit-linear-gradient(
120deg,
#bd34fe 30%,
#41d1ff
);
--vp-home-hero-image-background-image: linear-gradient(
-45deg,
#bd34fe 50%,
#47caff 50%
);
--vp-home-hero-image-filter: blur(44px);
}
@media (min-width: 640px) {
:root {
--vp-home-hero-image-filter: blur(56px);
}
}
@media (min-width: 960px) {
:root {
--vp-home-hero-image-filter: blur(68px);
}
}
/**
* Component: Custom Block
* -------------------------------------------------------------------------- */
:root {
--vp-custom-block-tip-border: transparent;
--vp-custom-block-tip-text: var(--vp-c-text-1);
--vp-custom-block-tip-bg: var(--vp-c-brand-soft);
--vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
}
/**
* Component: Sidebar
* -------------------------------------------------------------------------- */
:root {
--vp-sidebar-bg-color: transparent;
--vp-section-tabs-height: 44px;
}
@media (max-width: 959px) {
:root {
--vp-sidebar-bg-color: var(--vp-c-bg-alt);
}
.VPSidebar {
background-color: var(--vp-c-bg-alt) !important;
}
}
.VPSidebarItem.is-link > .item > .link {
margin: 2px 0;
border-radius: 8px;
padding: 0 10px;
transition: none;
}
.VPSidebarItem,
.VPSidebarItem > .item,
.VPSidebarItem > .item > .link {
border-bottom: none !important;
}
.VPSidebar .group + .group {
border-top: none !important;
}
.VPSidebar {
scrollbar-width: thin;
scrollbar-color: var(--vp-c-divider) transparent;
}
.VPSidebar::-webkit-scrollbar {
width: 10px;
}
.VPSidebar::-webkit-scrollbar-track {
background: transparent;
}
.VPSidebar::-webkit-scrollbar-thumb {
border: 2px solid transparent;
border-radius: 999px;
background-clip: padding-box;
background-color: var(--vp-c-divider);
}
.VPSidebar::-webkit-scrollbar-thumb:hover {
background-color: var(--vp-c-text-3);
}
.VPSidebarItem.is-link > .item > .link:hover {
background-color: var(--vp-c-default-soft);
}
.VPSidebarItem.is-link.is-active > .item > .link {
background-color: var(--vp-c-brand-soft);
}
/**
* Component: Algolia
* -------------------------------------------------------------------------- */
.DocSearch {
--docsearch-primary-color: var(--vp-c-brand-1) !important;
}
/**
* Component: Nav
* -------------------------------------------------------------------------- */
.VPNavBarTitle .logo {
width: 40px;
height: 40px;
}
.VPNavBarTitle .title > span {
font-size: 26px;
color: var(--vp-c-text-1);
}
@media (min-width: 960px) {
.VPNavBar.has-sidebar .wrapper {
padding: 0 32px !important;
background-color: var(--vp-nav-bg-color) !important;
}
.VPNavBar.has-sidebar .container {
max-width: calc(var(--vp-layout-max-width) - 64px) !important;
justify-content: flex-start !important;
gap: 24px !important;
background-color: var(--vp-nav-bg-color) !important;
}
.VPNavBar.has-sidebar .container > .title {
position: relative !important;
z-index: 3 !important;
padding: 0 !important;
width: auto !important;
max-width: none !important;
background-color: var(--vp-nav-bg-color) !important;
}
.VPNavBar.has-sidebar .content {
padding-left: 0 !important;
padding-right: 0 !important;
}
.VPNavBar.has-sidebar .content-body {
justify-content: flex-start !important;
}
.VPNavBar.has-sidebar .menu {
margin-right: auto !important;
}
.VPNavBar.has-sidebar .divider {
padding-left: 0 !important;
}
.VPNavBar.has-sidebar .VPNavBarTitle .title {
border-bottom: none !important;
background-color: var(--vp-nav-bg-color);
}
}
@media (min-width: 1440px) {
.VPNavBar.has-sidebar .container > .title {
padding-left: 0 !important;
width: auto !important;
}
.VPNavBar.has-sidebar .content {
padding-right: 0 !important;
padding-left: 0 !important;
}
.VPNavBar.has-sidebar .divider {
padding-left: 0 !important;
}
}
/**
* Component: Local Nav
* -------------------------------------------------------------------------- */
@media (min-width: 960px) {
.VPLocalNav.has-sidebar {
border-bottom: none !important;
}
.VPLocalNav.has-sidebar::after {
content: "";
position: absolute;
left: var(--vp-sidebar-width);
right: 0;
bottom: 0;
height: 1px;
background-color: var(--vp-c-gutter);
}
}
@media (min-width: 1440px) {
.VPLocalNav.has-sidebar::after {
left: calc((100vw - var(--vp-layout-max-width)) / 2 + var(--vp-sidebar-width));
}
}
.VPDocAsideOutline.has-outline .content {
border-left: none !important;
}
@media (min-width: 1280px) {
.VPNavBar.has-sidebar .divider {
display: none !important;
}
.VPSidebar {
padding-top: calc(var(--vp-nav-height) + var(--vp-section-tabs-height)) !important;
}
.Layout.sidebar-scope-intro-deploy .VPSidebar .group,
.Layout.sidebar-scope-platform .VPSidebar .group,
.Layout.sidebar-scope-providers .VPSidebar .group,
.Layout.sidebar-scope-use .VPSidebar .group,
.Layout.sidebar-scope-dev .VPSidebar .group {
display: none;
}
.Layout.sidebar-scope-intro-deploy .VPSidebar .group:nth-of-type(1),
.Layout.sidebar-scope-intro-deploy .VPSidebar .group:nth-of-type(2),
.Layout.sidebar-scope-intro-deploy .VPSidebar .group:nth-of-type(7),
.Layout.sidebar-scope-intro-deploy .VPSidebar .group:nth-of-type(8),
.Layout.sidebar-scope-platform .VPSidebar .group:nth-of-type(3),
.Layout.sidebar-scope-providers .VPSidebar .group:nth-of-type(4),
.Layout.sidebar-scope-use .VPSidebar .group:nth-of-type(5),
.Layout.sidebar-scope-dev .VPSidebar .group:nth-of-type(6) {
display: block;
}
}
.VPHomeHero:not(.has-image) .container {
text-align: center;
}
.VPHomeHero:not(.has-image) .heading {
align-items: center;
}
.VPHomeHero:not(.has-image) .name,
.VPHomeHero:not(.has-image) .text,
.VPHomeHero:not(.has-image) .tagline {
margin: 0 auto;
}
.VPHomeHero:not(.has-image) .actions {
justify-content: center;
}
docs/README.md
+10
View File
@@ -0,0 +1,10 @@
# AstrBot
_✨ 易上手的多平台 LLM 聊天机器人及开发框架（的官方文档） ✨_
[查看文档](https://docs.astrbot.app/) ｜ [问题提交](https://github.com/AstrBotDevs/AstrBot/issues)
[AstrBot](https://github.com/AstrBotDevs/AstrBot) 是一个松耦合、异步、支持多消息平台部署、具有易用的插件系统和完善的大语言模型（LLM）接入功能的聊天机器人及开发框架。
![image](https://github.com/user-attachments/assets/48f72a71-9456-4166-bbd2-f2a6c8cd740f)
docs/en/community.md
+34
View File
@@ -0,0 +1,34 @@
# Community
## Community Channels
This documentation may not cover all features comprehensively. If you have any questions or suggestions regarding AstrBot or this documentation, please feel free to reach out to us through the community channels below.
### Discord
<https://discord.gg/PxgzhmxJ>
### GitHub
Welcome to submit Issues or Pull Requests:
- [AstrBotDevs/AstrBot](https://github.com/AstrBotDevs/AstrBot)
- [AstrBotDevs/AstrBot-Docs](https://github.com/AstrBotDevs/AstrBot-docs)
### Tencent QQ Groups
> - All groups are available to join. If you find that the group size is below the limit, please feel free to join.
- Group 1: 322154837 (2000-member group)
- Group 3: 630166526 (2000-member group)
- Group 4: 1077826412 (1000-member group)
- Group 5: 822130018 (2000-member group)
- Group 6: 753075035 (2000-member group)
- Group 7: 743746109 (500-member group)
- Group 8: 1030353265 (500-member group)
- **AstrBot Core Development Group: 975206796** (AstrBot development members are usually active here. Welcome to anyone interested in programming/AI technology~)
## Become an AstrBot Organization Member
We welcome you to join us!
docs/en/config/model-config.md
+12
View File
@@ -0,0 +1,12 @@
# 配置自定义的模型参数
请手动修改位于 `data/cmd_config.json` 下的配置文件。
找到 `provider`，并找到你想要修改的提供商的模型配置：
![alt text](https://files.astrbot.app/docs/source/images/model-config/image-2.png)
然后在 `model_config` 中添加新的参数即可。
具体的参数请参看对应的提供商的文档。
docs/en/deploy/astrbot/1panel.md
+27
View File
@@ -0,0 +1,27 @@
# Deploy AstrBot on 1Panel
[1Panel](https://1panel.cn/) is an open-source next-generation Linux server operation and management panel.
AstrBot has been published to the [1Panel App Store](https://apps.fit2cloud.com/1panel) by the 1Panel team, allowing users to quickly deploy and use it directly through 1Panel.
## Install 1Panel
If you haven't installed 1Panel yet, please refer to the [1Panel official website](https://1panel.cn/) for one-click installation.
> International users can refer to the [1Panel official site](https://github.com/1Panel-dev/1Panel) for tutorials.
## Install AstrBot
Open the 1Panel panel, go to the 1Panel App Store, and search for `AstrBot`, as shown below.
![image](https://files.astrbot.app/docs/source/images/1panel/image.png)
Click `Install` and wait for the installation to complete.
After successful installation, open the corresponding AstrBot port (default is 6185) in the 1Panel System-Firewall page.
If you are using cloud servers from providers like AWS, Alibaba Cloud, Tencent Cloud, etc., make sure their security groups also allow port 6185.
## Access AstrBot
Visit `http://IP:6185` to access the AstrBot dashboard.
docs/en/deploy/astrbot/btpanel.md
+48
View File
@@ -0,0 +1,48 @@
# Deploy AstrBot on BT Panel
[BT Panel](https://www.bt.cn/new/index.html) is a secure, efficient, and production-ready Linux/Windows server operation panel.
AstrBot has been published to BT Panel's Docker App Store, supporting one-click installation.
## Install BT Panel
If you haven't installed BT Panel yet, please refer to [Install BT Products](https://www.bt.cn/new/download.html) for one-click installation.
## Set Acceleration URL (For Users in Mainland China)
After entering the BT Panel page, click `Docker` on the left sidebar, click Settings, and modify the `Acceleration URL`.
![alt text](https://files.astrbot.app/docs/source/images/btpanel/image-1.png)
## Install AstrBot
Go to Docker's App Store and search for `AstrBot`, as shown below.
![image](https://files.astrbot.app/docs/source/images/btpanel/image.png)
Click Install and wait for the installation to complete.
After successful installation, click `Security` on the left sidebar and open the corresponding AstrBot port (default is 6185).
If you are using cloud servers from providers like AWS, Alibaba Cloud, Tencent Cloud, etc., make sure their security groups also allow the corresponding port.
## Access AstrBot
Visit `http://IP:6185` to access the AstrBot dashboard.
> [!TIP]
> By default, the above method only opens port 6185. If you need to deploy messaging platforms, you need to additionally open the corresponding ports. Click `Container` in the top bar, find the AstrBot container, click `Manage`, click `Edit Container`, and add the corresponding ports.
>
> ![image](https://files.astrbot.app/docs/source/images/btpanel/image-2.png)
>
> For specific messaging platform port mappings, refer to the table below:
>
>| Port | Description | Type
>| -------- | ------- | ------- |
>| 6185 | AstrBot WebUI `default` port | Required |
>| 6195 | WeCom `default` port | Optional |
>| 6199 | QQ Personal Account(aiocqhttp) `default` port | Optional |
>| 6196 | QQ Official API(Webhook) `default` port | Optional |
>
> Platforms not listed do not require additional port opening.
docs/en/deploy/astrbot/casaos.md
+39
View File
@@ -0,0 +1,39 @@
# Deploy AstrBot on CasaOS
## Install CasaOS
```bash
curl -fsSL https://get.casaos.io | sudo bash
```
## Add CasaOS-AppStore-Play App Store Source
![image](https://files.astrbot.app/docs/source/images/casaos/image.png)
Click `More Apps`, then enter:
```txt
https://play.cuse.eu.org/Cp0204-AppStore-Play.zip
```
And add it, wait for the addition to complete.
If your network environment is in mainland China, please search for and add `dkTurbo` first, otherwise you may not be able to pull the AstrBot image.
![image](https://files.astrbot.app/docs/source/images/casaos/image-1.png)
Enter `Astrbot` to find AstrBot.
![image](https://files.astrbot.app/docs/source/images/casaos/image-2.png)
Click the icon (not the install button), then hover over the `Install` button and click Custom Install.
![image](https://files.astrbot.app/docs/source/images/casaos/image-3.png)
In the Network section, select `host`.
![image](https://files.astrbot.app/docs/source/images/casaos/image-4.png)
Then click `Install` to start the installation.
After installation is complete, the AstrBot APP will appear on the main interface. Click it to open the dashboard.
docs/en/deploy/astrbot/cli.md
+92
View File
@@ -0,0 +1,92 @@
# Deploy AstrBot from Source Code
> [!WARNING]
> You are deploying this project directly from source code. This tutorial requires you to have some technical background.
>
> This tutorial assumes Python is already installed on your device with version `>=3.10`
## Download/Clone Repository
If you have `git` installed on your computer, you can download the source code with the following command:
```bash
git clone https://github.com/AstrBotDevs/AstrBot.git
# The above code will pull the latest commit of the source code, if you need to pull the latest stable release version of the source code, you can use the following command:
# git clone --depth=1 --branch $(git ls-remote --tags --sort='-v:refname' https://github.com/AstrBotDevs/AstrBot.git | head -n1 | awk -F/ '{print $3}') https://github.com/AstrBotDevs/AstrBot.git
cd AstrBot
```
If you don't have `git` installed, please download and install it first.
Alternatively, download the source code directly from GitHub and extract it:
![image](https://files.astrbot.app/docs/source/images/cli/image.png)
## Install Dependencies and Run
::: details 【🥳Recommended】Use `uv` to Manage Dependencies
> If `uv` is not installed, please refer to [Installing uv](https://docs.astral.sh/uv/getting-started/installation/) for installation.
2. Execute in terminal (in the AstrBot directory)
```bash
uv sync
uv run main.py
```
If you have installed some plugins, it is recommended to add the `--no-sync` parameter for subsequent startups to avoid reinstalling plugin dependencies. We are working on solving this issue, so stay tuned.
```bash
uv run --no-sync main.py
```
:::
::: details Install Dependencies with Python Built-in venv
In the AstrBot source code directory, run the following command in the terminal:
> If on Windows and you downloaded and extracted the source code directly, please open the extracted folder and enter in the address bar:
> ![image](https://files.astrbot.app/docs/source/images/cli/image-1.png)
```bash
python3 -m venv ./venv
```
> It might be `python` instead of `python3`
The above steps will create and activate a virtual environment (to avoid disrupting your local Python environment).
Next, install the dependencies with the following command, which may take some time:
Execute on Mac/Linux/WSL:
```bash
source venv/bin/activate
python -m pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
python main.py
```
Execute on Windows:
```bash
venv\Scripts\activate
python -m pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
python main.py
```
:::
## 🎉 All Done!
If everything goes well, you will see logs printed by AstrBot.
If there are no errors, you will see a log message similar to `🌈 Dashboard started, accessible at` with several links. Open one of the links to access the AstrBot dashboard. The link is `http://localhost:6185`.
> [!TIP]
> If you are deploying AstrBot on a server, you need to replace `localhost` with your server's IP address.
>
> The default username and password are `astrbot` and `astrbot`.
Next, you need to deploy any messaging platform to use AstrBot on that platform.
docs/en/deploy/astrbot/community-deployment.md
+52
View File
@@ -0,0 +1,52 @@
# Community-Provided Deployment Methods
> [!WARNING]
> AstrBot official does not guarantee the security and stability of these deployment methods.
## Linux One-Click Deployment Script
Use `curl` to download the script and execute it using `bash`:
```bash
bash <(curl -sSL https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh)
```
If your system does not have `curl`, you can use `wget`:
```bash
wget -qO- https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh | bash
```
Repository Address: [zhende1113/Antlia](https://github.com/zhende1113/Antlia/)
## Linux One-Click Deployment Script (Based on Docker)
Supports AstrBot / NapCat.
> [!TIP]
> Use `sudo` for elevated permissions if you have insufficient privileges.
### Using `curl`
```bash
curl -sSL https://raw.githubusercontent.com/railgun19457/AstrbotScript/main/AstrbotScript.sh -o AstrbotScript.sh
chmod +x AstrbotScript.sh
sudo ./AstrbotScript.sh
```
### Using `wget`
```bash
wget -qO AstrbotScript.sh https://raw.githubusercontent.com/railgun19457/AstrbotScript/main/AstrbotScript.sh
chmod +x AstrbotScript.sh
sudo ./AstrbotScript.sh
```
> [!note]
> `sudo ./AstrbotScript.sh --no-color (Optional: disable color output)`
__Repository Address: [railgun19457/AstrbotScript](https://github.com/railgun19457/AstrbotScript)__
## AstrBot Android Deployment
Refer to [zz6zz666/AstrBot-Android-App](https://github.com/zz6zz666/AstrBot-Android-App)
docs/en/deploy/astrbot/compshare.md
+92
View File
@@ -0,0 +1,92 @@
# Deploy via Compshare
Compshare is UCloud's GPU compute rental and LLM API platform, offering compute resources for AI, deep learning, and scientific workloads.
AstrBot provides an Ollama + AstrBot one-click self-deployment image on Compshare, and also supports Compshare model APIs.
## Use the Ollama + AstrBot One-Click Image
> Default image spec: RTX 3090 24GB + Intel 16-core + 64GB RAM + 200GB system disk. Billing is pay-as-you-go, so please monitor your balance.
1. Register a Compshare account via [this link](https://passport.compshare.cn/register?referral_code=FV7DcGowN4hB5UuXKgpE74).
2. Open the [AstrBot image page](https://www.compshare.cn/images/0oX7xoGrzfre) and create an instance.
3. After deployment, open `JupyterLab` from the [console](https://console.compshare.cn/light-gpu/console/resources).
4. In JupyterLab, create a new terminal and run:
```bash
cd
./astrbot_booter.sh
```
If startup succeeds, you should see output similar to:
```txt
(py312) root@f8396035c96d:/workspace# cd
./astrbot_booter.sh
Starting AstrBot...
Starting ollama...
Both services started in the background.
```
After startup, open `http://<instance-public-ip>:6185` in your browser to access the AstrBot dashboard.
You can find the public IP in Console -> Basic Network (Public).
> It may take around 30 seconds before the page becomes reachable.
![WebUI](https://www-s.ucloud.cn/2025/07/7e9fc6edc1dfa916abc069f4cecc24cf_1753940381771.png)
Login with username `astrbot` and password `astrbot`.
After logging in, you can reset your password and continue setup.
The instance imports `Ollama-DeepSeek-R1-32B` by default.
## Use Other Models
### Pull Models with Ollama
The image includes Ollama. You can pull any model and host it locally on the instance.
1. Choose a model from [Ollama Search](https://ollama.com/search).
2. Connect to the instance terminal via SSH (from Compshare Console -> Instance List -> Console Command and Password).
3. Run `ollama pull <model-name>` and wait for completion.
4. In AstrBot Dashboard -> Providers, edit `ollama_deepseek-r1`, update the model name, and save.
![image](https://files.astrbot.app/docs/source/images/compshare/image-1.png)
### Use Compshare Model API
AstrBot supports direct access to model APIs provided by Compshare.
1. Find the model you want at [Compshare Model Center](https://console.compshare.cn/light-gpu/model-center).
2. In AstrBot Dashboard -> Providers, click `+ Add Provider`, then choose Compshare.
If Compshare is not listed, choose OpenAI-compatible access and set API Base URL to `https://api.modelverse.cn/v1`.
Enter the model name in model configuration and save.
### Test
In AstrBot Dashboard, click `Chat` and run `/provider` to view and switch your active provider.
Then send a normal message to test whether the model works.
![image](https://files.astrbot.app/docs/source/images/compshare/image-2.png)
## Connect to Messaging Platforms
You can follow the latest platform integration guides in the [AstrBot Documentation](https://docs.astrbot.app/en/what-is-astrbot.html).
Open the docs and check the left sidebar under Messaging Platforms.
- Lark: [Connect to Lark](https://docs.astrbot.app/en/platform/lark.html)
- LINE: [Connect to LINE](https://docs.astrbot.app/en/platform/line.html)
- DingTalk: [Connect to DingTalk](https://docs.astrbot.app/en/platform/dingtalk.html)
- WeCom: [Connect to WeCom](https://docs.astrbot.app/en/platform/wecom.html)
- WeChat Official Account: [Connect to WeChat Official Account](https://docs.astrbot.app/en/platform/weixin-official-account.html)
- QQ Official Bot: [Connect to QQ Official API](https://docs.astrbot.app/en/platform/qqofficial/webhook.html)
- KOOK: [Connect to KOOK](https://docs.astrbot.app/en/platform/kook.html)
- Slack: [Connect to Slack](https://docs.astrbot.app/en/platform/slack.html)
- Discord: [Connect to Discord](https://docs.astrbot.app/en/platform/discord.html)
- More methods: [AstrBot Documentation](https://docs.astrbot.app/en/what-is-astrbot.html)
## More Features
For more capabilities, see the [AstrBot Documentation](https://docs.astrbot.app/en/what-is-astrbot.html).
docs/en/deploy/astrbot/docker.md
+91
View File
@@ -0,0 +1,91 @@
# Deploy AstrBot with Docker
> [!WARNING]
> Docker provides a convenient way to deploy AstrBot on Windows, Mac, and Linux.
>
> This tutorial assumes you have Docker installed in your environment. If not, please refer to the [Docker official documentation](https://docs.docker.com/get-docker/) for installation.
## Deploy with Docker Compose
::: details Deploy AstrBot Only (General Method)
First, clone the AstrBot repository to your local machine:
```bash
git clone https://github.com/AstrBotDevs/AstrBot
cd AstrBot
```
Then, run Compose:
```bash
sudo docker compose up -d
```
> [!TIP]
> If your network environment is in mainland China, the above command will not pull properly. You may need to modify the compose.yml file and replace `image: soulter/astrbot:latest` with `image: m.daocloud.io/docker.io/soulter/astrbot:latest`.
:::
::: details Deploy with Agent Sandbox Environment
Supports native Python code execution, Shell code execution, and other features.
Deployment method:
```bash
git clone https://github.com/AstrBotDevs/AstrBot
cd AstrBot
# Modify the environment variable configuration in the compose-with-shipyard.yml file, such as Shipyard's access token, etc.
docker compose -f compose-with-shipyard.yml up -d
docker pull soulter/shipyard-ship:latest
```
For configuration and usage details, see the [Agent Sandbox Environment](/en/use/astrbot-agent-sandbox.md) documentation.
:::
## Deploy with Docker
```bash
mkdir astrbot
cd astrbot
sudo docker run -itd -p 6185:6185 -p 6199:6199 -v $PWD/data:/AstrBot/data -v /etc/localtime:/etc/localtime:ro -v /etc/timezone:/etc/timezone:ro --name astrbot soulter/astrbot:latest
```
> [!TIP]
> If your network environment is in mainland China, the above command will not pull properly. Please use the following command to pull the image:
>
> ```bash
> sudo docker run -itd -p 6185:6185 -p 6199:6199 -v $PWD/data:/AstrBot/data -v /etc/localtime:/etc/localtime:ro -v /etc/timezone:/etc/timezone:ro --name astrbot m.daocloud.io/docker.io/soulter/astrbot:latest
> ```
>
> (Thanks to DaoCloud ❤️)
> No need to add sudo on Windows, same below
> Sync Host Time on Windows (requires WSL2)
```
-v \\wsl.localhost\(your-wsl-os)\etc\timezone:/etc/timezone:ro
-v \\wsl.localhost\(your-wsl-os)\etc\localtime:/etc/localtime:ro
```
View AstrBot logs with the following command:
```bash
sudo docker logs -f astrbot
```
## 🎉 All Done
If everything goes well, you will see logs printed by AstrBot.
If there are no errors, you will see a log message similar to `🌈 Dashboard started, accessible at` with several links. Open one of the links to access the AstrBot dashboard.
> [!TIP]
> Since Docker isolates the network environment, you cannot use `localhost` to access the dashboard.
>
> The default username and password are `astrbot` and `astrbot`.
>
> If deployed on a cloud server, you need to open ports `6180-6200` and `11451` in the cloud provider's console.
Next, you need to deploy any messaging platform to use AstrBot on that platform.
docs/en/deploy/astrbot/kubernetes.md
+197
View File
@@ -0,0 +1,197 @@
# Deploy AstrBot with Kubernetes
> [!WARNING]
> You can deploy AstrBot in a high-availability setup using Kubernetes (K8s), allowing it to automatically recover from failures.
>
> Due to the current use of an SQLite database, this deployment does not support horizontal scaling with multiple replicas. Additionally, if using the Sidecar mode, pay special attention to the persistence of NapCat's login state.
>
> The following tutorial assumes that you have `kubectl` installed and configured, and that you can connect to your K8s cluster.
## Prerequisites
Before you begin, make sure your Kubernetes cluster meets the following conditions:
1. **Default StorageClass**: Used to dynamically create `PersistentVolumeClaim` (PVC). You can check this with `kubectl get sc`. If you don't have one, you need to manually create a `PersistentVolume` (PV) or install a corresponding storage plugin (e.g., `nfs-client-provisioner`).
2. **Network Access**: Ensure that your cluster nodes can pull images from `docker.io` or your specified image repository.
## Deployment Methods
We offer two deployment options:
* **Integrated Deployment (Sidecar Mode)**: Deploy AstrBot and NapCat in the same Pod. Recommended for personal QQ accounts.
* **Standalone Deployment**: Deploy only AstrBot. Suitable for other platforms or if you want to manage NapCat independently.
---
### Method 1: Deploy with NapCatQQ (Sidecar)
This method is located in the `k8s/astrbot_with_napcat` directory.
#### 1. Deploy
```bash
# 1. Create namespace
kubectl apply -f k8s/astrbot_with_napcat/00-namespace.yaml
# 2. Create Persistent Volume Claim
# Note: astrbot-data-shared-pvc requires ReadWriteMany (RWX) access mode.
# If your cluster does not support RWX, you need to configure shared storage such as NFS and modify the storageClassName in 01-pvc.yaml.
kubectl apply -f k8s/astrbot_with_napcat/01-pvc.yaml
# 3. Deploy the application
kubectl apply -f k8s/astrbot_with_napcat/02-deployment.yaml
```
#### 2. Expose Service (Choose one)
* **Option A: NodePort**
```bash
kubectl apply -f k8s/astrbot_with_napcat/03-service-nodeport.yaml
```
The service will be exposed via the node IP and a port automatically assigned by Kubernetes. You can find the port with the following command:
```bash
kubectl get svc -n astrbot-ns
```
In the output, find the `PORT(S)` column for `astrbot-webui-svc` and `napcat-web-svc`. The format is `<internal-port>:<NodePort>/TCP`. For example, if you see `8080:30185/TCP`, the access address is `http://<NodeIP>:30185`.
* **Option B: LoadBalancer**
If your cluster supports `LoadBalancer` type services (usually provided in K8s services from cloud providers), you can use this method.
```bash
kubectl apply -f k8s/astrbot_with_napcat/04-service-loadbalancer.yaml
```
After execution, check the assigned external IP (EXTERNAL-IP) with `kubectl get svc -n astrbot-ns`.
#### 3. Configure Connection
Since AstrBot and NapCat are in the same Pod, they can communicate directly via `localhost`.
1. **Add a message platform in AstrBot:**
* Go to the AstrBot WebUI, select `Settings` -> `Message Platform` -> `Add`.
* **Select Message Platform Category**: `aiocqhttp`
* **Bot Name**: `napcat` (or custom)
* **Reverse Websocket Host**: `0.0.0.0`
* **Reverse Websocket Port**: `6199`
* Save the configuration.
2. **Configure Websocket Client in NapCat:**
* Go to the NapCat WebUI, select `Settings` -> `Reverse WS` -> `Add`.
* **Enable**: On
* **URL**: `ws://localhost:6199/ws`
* **Message Format**: `Array`
* Save the configuration.
---
### Method 2: Deploy AstrBot Only (General Purpose)
This method is located in the `k8s/astrbot` directory.
#### 1. Deploy
```bash
# 1. Create namespace
kubectl apply -f k8s/astrbot/00-namespace.yaml
# 2. Create Persistent Volume Claim
kubectl apply -f k8s/astrbot/01-pvc.yaml
# 3. Deploy the application
kubectl apply -f k8s/astrbot/02-deployment.yaml
```
#### 2. Expose Service (Choose one)
* **Option A: NodePort**
```bash
kubectl apply -f k8s/astrbot/03-service-nodeport.yaml
```
The service will be exposed via the node IP and a port automatically assigned by Kubernetes. You can find the port with the following command:
```bash
kubectl get svc -n astrbot-standalone-ns
```
In the output, find the `PORT(S)` column for `astrbot-webui-svc`. The format is `<internal-port>:<NodePort>/TCP`. For example, if you see `8080:30185/TCP`, the access address is `http://<NodeIP>:30185`.
* **Option B: LoadBalancer**
```bash
kubectl apply -f k8s/astrbot/04-service-loadbalancer.yaml
```
After execution, check the assigned external IP (EXTERNAL-IP) with `kubectl get svc -n astrbot-standalone-ns`.
---
## Advanced Configuration
### Image Mirror (for users in mainland China)
If you have difficulty pulling the `soulter/astrbot:latest` or `mlikiowa/napcat-docker:latest` images, you can manually edit the corresponding `02-deployment.yaml` file and replace the `image` field with a domestic mirror address, for example:
```yaml
# Example:
# image: soulter/astrbot:latest
# Replace with:
image: m.daocloud.io/docker.io/soulter/astrbot:latest
```
### Enable Docker Sandbox Code Executor
If you need to use the sandbox code executor, you need to mount the Docker socket file into the Pod.
Edit the `02-deployment.yaml` file and add `volumes` and `volumeMounts` under `spec.template.spec`:
1. **Add the following to the `volumeMounts` list of the `astrbot` container:**
```yaml
- name: docker-sock
mountPath: /var/run/docker.sock
```
2. **Add the following to the `spec.template.spec.volumes` list:**
```yaml
- name: docker-sock
hostPath:
path: /var/run/docker.sock
type: Socket
```
> [!WARNING]
> Mounting the Docker socket into a Pod poses a security risk. Please ensure you understand the implications.
## View Logs
* **Sidecar Deployment Mode:**
```bash
# View AstrBot logs
kubectl logs -f -n astrbot-ns deployment/astrbot-stack -c astrbot
# View NapCat logs
kubectl logs -f -n astrbot-ns deployment/astrbot-stack -c napcat
```
* **Standalone Deployment Mode:**
```bash
kubectl logs -f -n astrbot-standalone-ns deployment/astrbot-standalone
```
## 🎉 All Done!
After deploying and exposing the service, you can access the AstrBot admin panel through the corresponding IP and port.
> The default username and password are `astrbot` and `astrbot`.
docs/en/deploy/astrbot/launcher.md
+98
View File
@@ -0,0 +1,98 @@
# Deploy AstrBot with AstrBot Launcher
## Recommended Method 1: AstrBot One-Click Launcher
AstrBot One-Click Launcher supports Windows, macOS, and Linux.
0. Open [AstrBotDevs/astrbot-launcher](https://github.com/AstrBotDevs/astrbot-launcher)
1. **Optional but recommended**: give this project a [**Star ⭐**](https://github.com/AstrBotDevs/astrbot-launcher). Your support helps maintainers keep improving it.
2. Find **Releases** on the right, open the latest release, then download the installer for your system from **Assets**.
For example:
- Windows x86 users: `AstrBot.Launcher_0.2.1_x64-setup.exe`
- Windows on Arm users: `AstrBot.Launcher_0.2.1_arm64-setup.exe`
- macOS Apple Silicon users: `AstrBot.Launcher_0.2.1_aarch64.dmg`
For macOS users, if you see "damaged and can't be opened", it is caused by macOS security restrictions on unsigned apps. Fix it with:
1. Open Terminal.
2. Run:
`xattr -dr com.apple.quarantine /Applications/AstrBot\ Launcher.app`
3. Reopen AstrBot Launcher.
## Method 2: Legacy Windows Installer
We still recommend the One-Click Launcher above because it is simpler, more automated, and better for most users.
The legacy installer is a `PowerShell` script, very small (<20KB). It requires `PowerShell` (usually built in on `Windows 10` and newer).
> [!WARNING]
> `Python 3.10` or later must be installed, and environment variables must be configured.
> [!TIP]
> If deployment fails, try Docker deployment or manual deployment instead.
## Download the Legacy Installer
Open <https://github.com/AstrBotDevs/AstrBotLauncher/releases/latest>
Download `Source code (zip)` and extract it.
## Run the Legacy Installer
> The video may be outdated. Follow the steps here.
After extraction, open the folder.
Type `PowerShell` in the address bar and press Enter:
![image](https://files.astrbot.app/docs/source/images/windows/image-4.png)
Drag `launcher_astrbot_en.bat` into the PowerShell window and press Enter.
> [!WARNING]
> - The script is safe. If you see `Windows protected your PC`, click `More info` and then `Run anyway`.
> - By default, it uses `python`. If you want to specify another interpreter path/command, edit `launcher_astrbot_en.bat`, find `set PYTHON_CMD=python`, and replace `python` with your own command/path.
If Python is not detected, the script exits with a prompt.
The script checks whether an `AstrBot` folder exists. If not, it downloads the latest AstrBot source from [GitHub](https://github.com/AstrBotDevs/AstrBot/releases/latest), installs dependencies, and runs it automatically.
## Done
If everything works, you will see AstrBot logs.
Without errors, you should see a log like `🌈 Management panel started, accessible at` with several URLs. Open one URL to access AstrBot WebUI.
> [!TIP]
> Default username and password: `astrbot` / `astrbot`.
>
> If WebUI returns 404:
> Download `dist.zip` from [release](https://github.com/AstrBotDevs/AstrBot/releases), extract it into `AstrBot/data`, then restart the computer if needed.
Then deploy at least one messaging platform adapter to start using AstrBot in IM apps.
## Error: Python is not installed
If you still get this error after installing Python and restarting, your PATH is likely incorrect.
**Method 1**
Search for Python in Windows and open its file location:
![image](https://files.astrbot.app/docs/source/images/windows/image.png)
Right-click the shortcut below and open file location:
![alt text](https://files.astrbot.app/docs/source/images/windows/image-1.png)
Copy the file path:
![image](https://files.astrbot.app/docs/source/images/windows/image-2.png)
Edit `launcher_astrbot_en.bat` in Notepad, find `set PYTHON_CMD=python`, and replace `python` with your interpreter command/path. Keep quotes if your path contains spaces.
**Method 2**
Reinstall Python, check `Add Python to PATH` during installation, then restart your computer.
docs/en/deploy/astrbot/other-deployments.md
+5
View File
@@ -0,0 +1,5 @@
# Other Deployments
- [CasaOS Deployment](./casaos.md)
- [Compshare GPU Deployment](./compshare.md)
- [Community Deployments](./community-deployment.md)
docs/en/deploy/astrbot/package.md
+17
View File
@@ -0,0 +1,17 @@
# Package Manager Deployment (uv)
Use `uv` to install and run AstrBot quickly.
## Before You Start
If `uv` is not installed, install it first by following the official guide:
<https://docs.astral.sh/uv/>
`uv` supports Linux, Windows, and macOS.
## Install and Start
```bash
uv tool install astrbot
astrbot
```
docs/en/deploy/astrbot/sys-pm.md
+41
View File
@@ -0,0 +1,41 @@
# Installation via System Package Manager
> [!WARNING]
> Currently, only the AUR version is provided.
> If you are a Windows/macOS user, it is recommended to install via `uv`.
> If you are a Linux user, it is highly recommended to install via a package manager.
# Preparation
## What is AUR?
AUR (Arch User Repository) allows users to install software from community-maintained software repositories. AUR packages are typically maintained by community members rather than official maintainers.
Common AUR helpers include `yay` and `paru`.
The following tutorial uses `paru` as an example; `yay` works similarly, just replace `paru` with `yay`.
# Installation Process
## AUR
```bash
paru -S astrbot-git
# Note:
# The review step will begin; press 'q' to exit review and continue installation.
# After installation, the data directory is fixed at: ~/.local/share/astrbot
```
# Starting
>[!TIP]
> You can directly use `astrbot init` (for the first run) to initialize.
> Use `astrbot run` to run the bot.
> However, it is highly recommended to use `systemctl` for starting, as it provides features like automatic restart and log rotation.
```bash
systemctl --user start astrbot.service
```
# Auto-start on Boot
```bash
# For security reasons, it is designed to run as a user.
systemctl --user enable astrbot.service
# If you need to start it immediately, add --now
# systemctl --user enable --now astrbot.service
```
docs/en/deploy/when-deployed.md
+16
View File
@@ -0,0 +1,16 @@
# Preface
After successful deployment... of course, don't forget to give [AstrBot](https://github.com/AstrBotDevs/AstrBot) a Star!
AstrBot Main Repository: [![wakatime](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018e705a-a1a7-409a-a849-3013485e6c8e.svg)](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018e705a-a1a7-409a-a849-3013485e6c8e)
AstrBot Dashboard: [![wakatime](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018c440f-c177-45f8-8224-292cdf5926f3.svg)](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018c440f-c177-45f8-8224-292cdf5926f3)
AstrBot Documentation: [![wakatime](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018c9619-e195-4b94-bd7b-2ca61679145b.svg)](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018c9619-e195-4b94-bd7b-2ca61679145b)
❤️ Contributions to this project are warmly welcomed, including Issues and Pull Requests.
## Next...
If you're reading this, it means you have successfully deployed the messaging platform and sent/received your first command. Next, you can configure large language models or add plugins. Please refer to the `Configuration - Integrating LLM Services` section.
docs/en/dev/astrbot-config.md
+557
View File
@@ -0,0 +1,557 @@
---
outline: deep
---
# AstrBot Configuration File
## data/cmd_config.json
AstrBot's configuration file is a JSON format file. AstrBot reads this file at startup and initializes based on the settings within. Its path is `data/cmd_config.json`.
> Since AstrBot v4.0.0, we introduced the concept of [multiple configuration files](https://blog.astrbot.app/posts/what-is-changed-in-4.0.0/#%E5%A4%9A%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6). `data/cmd_config.json` serves as the default configuration `default`. Other configuration files you create in the WebUI are stored in the `data/config/` directory, starting with `abconf_`.
The default AstrBot configuration is as follows:
```jsonc
{
"config_version": 2,
"platform_settings": {
"unique_session": False,
"rate_limit": {
"time": 60,
"count": 30,
"strategy": "stall", # stall, discard
},
"reply_prefix": "",
"forward_threshold": 1500,
"enable_id_white_list": True,
"id_whitelist": [],
"id_whitelist_log": True,
"wl_ignore_admin_on_group": True,
"wl_ignore_admin_on_friend": True,
"reply_with_mention": False,
"reply_with_quote": False,
"path_mapping": [],
"segmented_reply": {
"enable": False,
"only_llm_result": True,
"interval_method": "random",
"interval": "1.5,3.5",
"log_base": 2.6,
"words_count_threshold": 150,
"regex": ".*?[。？！~…]+|.+$",
"content_cleanup_rule": "",
},
"no_permission_reply": True,
"empty_mention_waiting": True,
"empty_mention_waiting_need_reply": True,
"friend_message_needs_wake_prefix": False,
"ignore_bot_self_message": False,
"ignore_at_all": False,
},
"provider": [],
"provider_settings": {
"enable": True,
"default_provider_id": "",
"default_image_caption_provider_id": "",
"image_caption_prompt": "Please describe the image using Chinese.",
"provider_pool": ["*"], # "*" means use all available providers
"wake_prefix": "",
"web_search": False,
"websearch_provider": "default",
"websearch_tavily_key": [],
"web_search_link": False,
"display_reasoning_text": False,
"identifier": False,
"group_name_display": False,
"datetime_system_prompt": True,
"default_personality": "default",
"persona_pool": ["*"],
"prompt_prefix": "{{prompt}}",
"max_context_length": -1,
"dequeue_context_length": 1,
"streaming_response": False,
"show_tool_use_status": False,
"streaming_segmented": False,
"max_agent_step": 30,
"tool_call_timeout": 60,
},
"provider_stt_settings": {
"enable": False,
"provider_id": "",
},
"provider_tts_settings": {
"enable": False,
"provider_id": "",
"dual_output": False,
"use_file_service": False,
},
"provider_ltm_settings": {
"group_icl_enable": False,
"group_message_max_cnt": 300,
"image_caption": False,
"active_reply": {
"enable": False,
"method": "possibility_reply",
"possibility_reply": 0.1,
"whitelist": [],
},
},
"content_safety": {
"also_use_in_response": False,
"internal_keywords": {"enable": True, "extra_keywords": []},
"baidu_aip": {"enable": False, "app_id": "", "api_key": "", "secret_key": ""},
},
"admins_id": ["astrbot"],
"t2i": False,
"t2i_word_threshold": 150,
"t2i_strategy": "remote",
"t2i_endpoint": "",
"t2i_use_file_service": False,
"t2i_active_template": "base",
"http_proxy": "",
"no_proxy": ["localhost", "127.0.0.1", "::1"],
"dashboard": {
"enable": True,
"username": "astrbot",
"password": "77b90590a8945a7d36c963981a307dc9",
"jwt_secret": "",
"host": "0.0.0.0",
"port": 6185,
},
"platform": [],
"platform_specific": {
# Platform-specific settings: categorized by platform, then by feature group
"lark": {
"pre_ack_emoji": {"enable": False, "emojis": ["Typing"]},
},
"telegram": {
"pre_ack_emoji": {"enable": False, "emojis": ["✍️"]},
},
},
"wake_prefix": ["/"],
"log_level": "INFO",
"trace_enable": False,
"pip_install_arg": "",
"pypi_index_url": "https://mirrors.aliyun.com/pypi/simple/",
"persona": [], # deprecated
"timezone": "Asia/Shanghai",
"callback_api_base": "",
"default_kb_collection": "", # Default knowledge base name
"plugin_set": ["*"], # "*" means use all available plugins, empty list means none
}
```
## Field Details
### `config_version`
Configuration version, do not modify.
### `platform_settings`
General settings for message platform adapters.
#### `platform_settings.unique_session`
Whether to enable session isolation. Default is `false`. When enabled, each person's conversation context in groups or channels is independent.
#### `platform_settings.rate_limit`
Strategy when message rate exceeds limits. `time` is the window, `count` is the number of messages, and `strategy` is the limit strategy. `stall` means wait, `discard` means drop.
#### `platform_settings.reply_prefix`
Fixed prefix string when replying to messages. Default is empty.
#### `platform_settings.forward_threshold`
> Currently only applicable to the QQ platform adapter.
Message forwarding threshold. When the reply content exceeds a certain number of characters, the bot will fold the message into a QQ group "forwarded message" to prevent spamming.
#### `platform_settings.enable_id_white_list`
Whether to enable the ID whitelist. Default is `true`. When enabled, only messages from IDs in the whitelist will be processed.
#### `platform_settings.id_whitelist`
ID whitelist. If filled, only message events from the specified IDs will be processed. Empty means the whitelist filter is not enabled. You can use the `/sid` command to get the session ID on a platform.
Session IDs can also be found in AstrBot logs; when a message fails the whitelist, an INFO level log is output, e.g., `aiocqhttp:GroupMessage:547540978`.
#### `platform_settings.id_whitelist_log`
Whether to print logs for messages that fail the ID whitelist. Default is `true`.
#### `platform_settings.wl_ignore_admin_on_group` & `platform_settings.wl_ignore_admin_on_friend`
- `wl_ignore_admin_on_group`: Whether group messages from admins bypass the ID whitelist. Default is `true`.
- `wl_ignore_admin_on_friend`: Whether private messages from admins bypass the ID whitelist. Default is `true`.
#### `platform_settings.reply_with_mention`
Whether to @ mention the user when replying. Default is `false`.
#### `platform_settings.reply_with_quote`
Whether to quote the user's message when replying. Default is `false`.
#### `platform_settings.path_mapping`
*This configuration item has been deprecated since v4.0.0.*
List of path mappings. Used to replace file paths in messages. Each mapping item contains `from` and `to` fields, indicating that `from` in the message path is replaced with `to`.
#### `platform_settings.segmented_reply`
Segmented reply settings.
- `enable`: Whether to enable segmented replies. Default is `false`.
- `only_llm_result`: Whether to only segment replies generated by the LLM. Default is `true`.
- `interval_method`: Method for segmentation intervals. Options are `random` and `log`. Default is `random`.
- `interval`: Interval time for segmentation. For `random`, fill in two comma-separated numbers representing min and max intervals (seconds). For `log`, fill in one number representing the log base. Default is `"1.5,3.5"`.
- `log_base`: Log base, only applicable when `interval_method` is `log`. Default is `2.6`.
- `words_count_threshold`: Character limit for segmented replies. Only messages shorter than this value will be segmented; longer messages will be sent directly (unsegmented). Default is `150`.
- `regex`: Used to split a message. By default, it splits based on punctuation like periods and question marks. `re.findall(r'<regex>', text)`. Default is `".*?[。？！~…]+|.+$"`.
- `content_cleanup_rule`: Removes specified content from segments. Supports regex. For example, `[。？！]` will remove all periods, question marks, and exclamation points. `re.sub(r'<regex>', '', text)`.
#### `platform_settings.no_permission_reply`
Whether to reply with a "no permission" prompt when a user lacks authority. Default is `true`.
#### `platform_settings.empty_mention_waiting`
Whether to enable the empty @ waiting mechanism. Default is `true`. When enabled, if a user sends a message containing only an @ mention of the bot, the bot waits for the user to send the next message within 60 seconds and merges the two for processing. This is particularly useful on platforms that don't support sending @ and voice/images simultaneously.
#### `platform_settings.empty_mention_waiting_need_reply`
In the above item (`empty_mention_waiting`), if waiting is triggered, enabling this will make the bot immediately generate an LLM reply. Otherwise, it just waits without replying. Default is `true`.
#### `platform_settings.friend_message_needs_wake_prefix`
Whether private messages on platforms require a wake prefix. Default is `false`. When enabled, users must use a wake prefix to trigger a bot response in private chats.
#### `platform_settings.ignore_bot_self_message`
Whether to ignore messages sent by the bot itself. Default is `false`. When enabled, the bot won't process its own messages, preventing infinite loops on some platforms.
#### `platform_settings.ignore_at_all`
Whether to ignore @all messages. Default is `false`. When enabled, the bot won't respond to messages containing @all.
### `provider`
> This item only takes effect in `data/cmd_config.json`; AstrBot does not read this from configuration files in the `data/config/` directory.
List of configured model service provider settings.
### `provider_settings`
General settings for LLM providers.
#### `provider_settings.enable`
Whether to enable LLM chat. Default is `true`.
#### `provider_settings.default_provider_id`
Default conversation model provider ID. Must be a provider ID already configured in the `provider` list. If empty, the first provider in the list is used.
#### `provider_settings.default_image_caption_provider_id`
Default image captioning model provider ID. Must be a provider ID already configured in the `provider` list. If empty, image captioning is disabled.
This means when a user sends an image, AstrBot uses this provider to generate a text description, which is then used as part of the conversation context. This is useful when the conversation model doesn't support multimodal input.
#### `provider_settings.image_caption_prompt`
Prompt template for image captioning. Default is `"Please describe the image using Chinese."`.
#### `provider_settings.provider_pool`
*This configuration item is not yet in actual use.*
#### `provider_settings.wake_prefix`
Extra trigger condition for LLM chat. For example, if `chat` is filled, messages must start with `/chat` to trigger LLM chat, where `/` is the bot's wake prefix. This is a measure to prevent abuse.
#### `provider_settings.web_search`
Whether to enable AstrBot's built-in web search capability. Default is `false`. When enabled, the LLM may automatically search the web and answer based on the content.
#### `provider_settings.websearch_provider`
Web search provider type. Default is `default`. Currently supports `default` and `tavily`.
- `default`: Works best when Google is accessible. If Google fails, it tries Bing and Sogou in order.
- `tavily`: Uses the Tavily search engine.
#### `provider_settings.websearch_tavily_key`
API Key list for the Tavily search engine. Required when using `tavily` as the web search provider.
#### `provider_settings.web_search_link`
Whether to prompt the model to include links to search results in the reply. Default is `false`.
#### `provider_settings.display_reasoning_text`
Whether to display the model's reasoning process in the reply. Default is `false`.
#### `provider_settings.identifier`
Whether to prepend the group member's name to the prompt so the model better understands the group chat state. Default is `false`. Enabling this slightly increases token usage.
#### `provider_settings.group_name_display`
Whether to let the model know the name of the group it's in. Default is `false`. This currently only takes effect in the QQ platform adapter.
#### `provider_settings.datetime_system_prompt`
Whether to include the current machine date and time in the system prompt. Default is `true`.
#### `provider_settings.default_personality`
ID of the default personality to use. Configure personalities in the WebUI.
#### `provider_settings.persona_pool`
*This configuration item is not yet in actual use.*
#### `provider_settings.prompt_prefix`
User prompt. You can use `{{prompt}}` as a placeholder for user input. If no placeholder is provided, it's prepended to the user input.
#### `provider_settings.max_context_length`
When the conversation context exceeds this number, the oldest parts are discarded. One round of chat counts as 1. -1 means no limit.
#### `provider_settings.dequeue_context_length`
The number of conversation rounds to discard each time the `max_context_length` limit is triggered.
#### `provider_settings.streaming_response`
Whether to enable streaming responses. Default is `false`. When enabled, the model's reply is sent to the user in real-time with a typewriter effect. This only takes effect on WebChat, Telegram, and Lark platforms.
#### `provider_settings.show_tool_use_status`
Whether to show tool usage status. Default is `false`. When enabled, the model displays the tool name and input parameters when using a tool.
#### `provider_settings.streaming_segmented`
Whether platforms that don't support streaming responses should fall back to segmented replies. Default is `false`. This means if streaming is enabled but the platform doesn't support it, segmented multiple replies are used instead.
#### `provider_settings.max_agent_step`
Limit on the maximum number of Agent steps. Default is `30`. Each tool call by the model counts as one step.
#### `provider_settings.tool_call_timeout`
Added in `v4.3.5`
Maximum timeout for tool calls (seconds), default is `60` seconds.
#### `provider_stt_settings`
General settings for Speech-to-Text (STT) providers.
#### `provider_stt_settings.enable`
Whether to enable STT services. Default is `false`.
#### `provider_stt_settings.provider_id`
STT provider ID. Must be an STT provider ID already configured in the `provider` list.
#### `provider_tts_settings`
General settings for Text-to-Speech (TTS) providers.
#### `provider_tts_settings.enable`
Whether to enable TTS services. Default is `false`.
#### `provider_tts_settings.provider_id`
TTS provider ID. Must be a TTS provider ID already configured in the `provider` list.
#### `provider_tts_settings.dual_output`
Whether to enable dual output. Default is `false`. When enabled, the bot sends both text and voice messages.
#### `provider_tts_settings.use_file_service`
Whether to enable the file service. Default is `false`. When enabled, the bot provides the output voice file as an external HTTP link to the message platform. This depends on the `callback_api_base` configuration.
#### `provider_ltm_settings`
General settings for group chat context awareness providers.
#### `provider_ltm_settings.group_icl_enable`
Whether to enable group chat context awareness. Default is `false`. When enabled, the bot records group chat conversations to better understand context.
The context content is placed in the conversation's system prompt.
#### `provider_ltm_settings.group_message_max_cnt`
Maximum number of group chat messages to record. Default is `100`. Messages exceeding this count are discarded.
#### `provider_ltm_settings.image_caption`
Whether to record images in group chats and automatically generate text descriptions using an image captioning model. Default is `false`. This depends on the `provider_settings.default_image_caption_provider_id` configuration. Use with caution as it can significantly increase API calls and token usage.
#### `provider_ltm_settings.active_reply`
- `enable`: Whether to enable active replies. Default is `false`.
- `method`: Method for active replies. Option is `possibility_reply`.
- `possibility_reply`: Probability of an active reply. Default is `0.1`. Only applicable when `method` is `possibility_reply`.
- `whitelist`: ID whitelist for active replies. Only IDs in this list will trigger active replies. Empty means no whitelist filter. You can use the `/sid` command to get the session ID on a platform.
### `content_safety`
Content safety settings.
#### `content_safety.also_use_in_response`
Whether to also perform content safety checks on LLM replies. Default is `false`. When enabled, bot-generated replies also undergo safety checks to prevent inappropriate content.
#### `content_safety.internal_keywords`
Internal keyword detection settings.
- `enable`: Whether to enable internal keyword detection. Default is `true`.
- `extra_keywords`: List of extra keywords, supports regex. Default is empty.
#### `content_safety.baidu_aip`
Baidu AI content moderation settings.
- `enable`: Whether to enable Baidu AI content moderation. Default is `false`.
- `app_id`: App ID for Baidu AI content moderation.
- `api_key`: API Key for Baidu AI content moderation.
- `secret_key`: Secret Key for Baidu AI content moderation.
> [!TIP]
> To enable Baidu AI content moderation, please `pip install baidu-aip` first.
### `admins_id`
List of administrator IDs. Additionally, you can use `/op` and `/deop` commands to add or remove admins.
### `t2i`
Whether to enable Text-to-Image (T2I) functionality. Default is `false`. When enabled, if a user's message exceeds a certain character count, the bot renders the message as an image to improve readability and prevent spamming. Supports Markdown rendering.
### `t2i_word_threshold`
Character threshold for T2I. Default is `150`. When a message exceeds this count, the bot renders it as an image.
### `t2i_strategy`
Rendering strategy for T2I. Options are `local` and `remote`. Default is `remote`.
- `local`: Uses AstrBot's local T2I service for rendering. Lower quality but doesn't depend on external services.
- `remote`: Uses a remote T2I service for rendering. Uses the official AstrBot service by default, which offers better quality.
### `t2i_endpoint`
AstrBot API address. Used for rendering Markdown images. Effective when `t2i_strategy` is `remote`. Default is empty, meaning the official AstrBot service is used.
### `t2i_use_file_service`
Whether to enable the file service. Default is `false`. When enabled, the bot provides the rendered image as an external HTTP link to the message platform. This depends on the `callback_api_base` configuration.
### `http_proxy`
HTTP proxy. E.g., `http://localhost:7890`.
### `no_proxy`
List of addresses that bypass the proxy. E.g., `["localhost", "127.0.0.1"]`.
### `dashboard`
AstrBot WebUI configuration.
Please do not change the `password` value arbitrarily. It is an `md5` encoded password. Change the password in the control panel.
- `enable`: Whether to enable the AstrBot WebUI. Default is `true`.
- `username`: Username for the AstrBot WebUI. Default is `astrbot`.
- `password`: Password for the AstrBot WebUI. Default is the `md5` encoded value of `astrbot`. Do not modify directly unless you know what you are doing.
- `jwt_secret`: JWT secret key. AstrBot generates this randomly at initialization. Do not modify unless you know what you are doing.
- `host`: Address the AstrBot WebUI listens on. Default is `0.0.0.0`.
- `port`: Port the AstrBot WebUI listens on. Default is `6185`.
### `platform`
> This item only takes effect in `data/cmd_config.json`; AstrBot does not read this from configuration files in the `data/config/` directory.
List of configured AstrBot message platform adapter settings.
### `platform_specific`
Platform-specific settings. Categorized by platform, then by feature group.
#### `platform_specific.<platform>.pre_ack_emoji`
When enabled, AstrBot sends a pre-reply emoji before requesting the LLM to inform the user that the request is being processed. This currently only takes effect in the Lark and Telegram platform adapters.
##### lark
- `enable`: Whether to enable pre-reply emojis for Lark messages. Default is `false`.
- `emojis`: List of pre-reply emojis. Default is `["Typing"]`. Refer to [Emoji Documentation](https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce) for emoji names.
##### telegram
- `enable`: Whether to enable pre-reply emojis for Telegram messages. Default is `false`.
- `emojis`: List of pre-reply emojis. Default is `["✍️"]`. Telegram only supports a fixed set of reactions; refer to [reactions.txt](https://gist.github.com/Soulter/3f22c8e5f9c7e152e967e8bc28c97fc9).
### `wake_prefix`
Wake prefix. Default is `/`. When a message starts with `/`, AstrBot is awakened.
> [!TIP]
> If the awakened session is not in the ID whitelist, AstrBot will not respond.
### `log_level`
Log level. Default is `INFO`. Can be set to `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.
### `trace_enable`
Whether to enable trace recording. Default is `false`. When enabled, AstrBot records execution traces, which can be viewed on the Trace page of the admin panel.
### `pip_install_arg`
Arguments for `pip install`. E.g., `-i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple`.
### `pypi_index_url`
PyPI index URL. Default is `https://mirrors.aliyun.com/pypi/simple/`.
### `persona`
*This configuration item has been deprecated since v4.0.0. Please use the WebUI to configure personalities.*
List of configured personalities. Each personality contains `id`, `name`, `description`, and `system_prompt` fields.
### `timezone`
Timezone setting. Please fill in an IANA timezone name, such as Asia/Shanghai. If empty, the system default timezone is used. See all timezones at: [IANA Time Zone Database](https://data.iana.org/time-zones/tzdb-2021a/zone1970.tab).
### `callback_api_base`
Base address for the AstrBot API. Used for file services, plugin callbacks, etc. E.g., `http://example.com:6185`. Default is empty, meaning file services and plugin callbacks are disabled.
### `default_kb_collection`
Default knowledge base name. Used for RAG. If empty, no knowledge base is used.
### `plugin_set`
List of enabled plugins. `*` means all available plugins are enabled. Default is `["*"]`.
docs/en/dev/openapi.md
+51
View File
@@ -0,0 +1,51 @@
---
outline: deep
---
# AstrBot HTTP API
Starting from v4.18.0, AstrBot provides API Key based HTTP APIs for programmatic access.
## Quick Start
1. Create an API key in WebUI - Settings.
2. Include the API key in request headers:
```http
Authorization: Bearer abk_xxx
```
Also supported:
```http
X-API-Key: abk_xxx
```
3. For chat endpoints, `username` is required:
- `POST /api/v1/chat`: request body must include `username`
- `GET /api/v1/chat/sessions`: query params must include `username`
## Common Endpoints
- `POST /api/v1/chat`: send chat message (SSE stream, server generates UUID when `session_id` is omitted)
- `GET /api/v1/chat/sessions`: list sessions for a specific `username` with pagination
- `GET /api/v1/configs`: list available config files
- `POST /api/v1/file`: upload attachment
- `POST /api/v1/im/message`: proactive message via UMO
- `GET /api/v1/im/bots`: list bot/platform IDs
## Example
```bash
curl -N 'http://localhost:6185/api/v1/chat' \
-H 'Authorization: Bearer abk_xxx' \
-H 'Content-Type: application/json' \
-d '{"message":"Hello","username":"alice"}'
```
## Full API Reference
Use the interactive docs:
- https://docs.astrbot.app/scalar.html
docs/en/dev/plugin-platform-adapter.md
+185
View File
@@ -0,0 +1,185 @@
---
outline: deep
---
# 开发一个平台适配器
AstrBot 支持以插件的形式接入平台适配器，你可以自行接入 AstrBot 没有的平台。如飞书、钉钉甚至是哔哩哔哩私信、Minecraft。
我们以一个平台 `FakePlatform` 为例展开讲解。
首先，在插件目录下新增 `fake_platform_adapter.py` 和 `fake_platform_event.py` 文件。前者主要是平台适配器的实现，后者是平台事件的定义。
## 平台适配器
假设 FakePlatform 的客户端 SDK 是这样：
```py
import asyncio
class FakeClient():
'''模拟一个消息平台，这里 5 秒钟下发一个消息'''
def __init__(self, token: str, username: str):
self.token = token
self.username = username
# ...
async def start_polling(self):
while True:
await asyncio.sleep(5)
await getattr(self, 'on_message_received')({
'bot_id': '123',
'content': '新消息',
'username': 'zhangsan',
'userid': '123',
'message_id': 'asdhoashd',
'group_id': 'group123',
})
async def send_text(self, to: str, message: str):
print('发了消息:', to, message)
async def send_image(self, to: str, image_path: str):
print('发了消息:', to, image_path)
```
我们创建 `fake_platform_adapter.py`：
```py
import asyncio
from astrbot.api.platform import Platform, AstrBotMessage, MessageMember, PlatformMetadata, MessageType
from astrbot.api.event import MessageChain
from astrbot.api.message_components import Plain, Image, Record # 消息链中的组件，可以根据需要导入
from astrbot.core.platform.astr_message_event import MessageSesion
from astrbot.api.platform import register_platform_adapter
from astrbot import logger
from .client import FakeClient
from .fake_platform_event import FakePlatformEvent
# 注册平台适配器。第一个参数为平台名，第二个为描述。第三个为默认配置。
@register_platform_adapter("fake", "fake 适配器", default_config_tmpl={
"token": "your_token",
"username": "bot_username"
})
class FakePlatformAdapter(Platform):
def __init__(self, platform_config: dict, platform_settings: dict, event_queue: asyncio.Queue) -> None:
super().__init__(event_queue)
self.config = platform_config # 上面的默认配置，用户填写后会传到这里
self.settings = platform_settings # platform_settings 平台设置。
async def send_by_session(self, session: MessageSesion, message_chain: MessageChain):
# 必须实现
await super().send_by_session(session, message_chain)
def meta(self) -> PlatformMetadata:
# 必须实现，直接像下面一样返回即可。
return PlatformMetadata(
"fake",
"fake 适配器",
)
async def run(self):
# 必须实现，这里是主要逻辑。
# FakeClient 是我们自己定义的，这里只是示例。这个是其回调函数
async def on_received(data):
logger.info(data)
abm = await self.convert_message(data=data) # 转换成 AstrBotMessage
await self.handle_msg(abm)
# 初始化 FakeClient
self.client = FakeClient(self.config['token'], self.config['username'])
self.client.on_message_received = on_received
await self.client.start_polling() # 持续监听消息，这是个堵塞方法。
async def convert_message(self, data: dict) -> AstrBotMessage:
# 将平台消息转换成 AstrBotMessage
# 这里就体现了适配程度，不同平台的消息结构不一样，这里需要根据实际情况进行转换。
abm = AstrBotMessage()
abm.type = MessageType.GROUP_MESSAGE # 还有 friend_message，对应私聊。具体平台具体分析。重要！
abm.group_id = data['group_id'] # 如果是私聊，这里可以不填
abm.message_str = data['content'] # 纯文本消息。重要！
abm.sender = MessageMember(user_id=data['userid'], nickname=data['username']) # 发送者。重要！
abm.message = [Plain(text=data['content'])] # 消息链。如果有其他类型的消息，直接 append 即可。重要！
abm.raw_message = data # 原始消息。
abm.self_id = data['bot_id']
abm.session_id = data['userid'] # 会话 ID。重要！
abm.message_id = data['message_id'] # 消息 ID。
return abm
async def handle_msg(self, message: AstrBotMessage):
# 处理消息
message_event = FakePlatformEvent(
message_str=message.message_str,
message_obj=message,
platform_meta=self.meta(),
session_id=message.session_id,
client=self.client
)
self.commit_event(message_event) # 提交事件到事件队列。不要忘记！
```
`fake_platform_event.py`：
```py
from astrbot.api.event import AstrMessageEvent, MessageChain
from astrbot.api.platform import AstrBotMessage, PlatformMetadata
from astrbot.api.message_components import Plain, Image
from .client import FakeClient
from astrbot.core.utils.io import download_image_by_url
class FakePlatformEvent(AstrMessageEvent):
def __init__(self, message_str: str, message_obj: AstrBotMessage, platform_meta: PlatformMetadata, session_id: str, client: FakeClient):
super().__init__(message_str, message_obj, platform_meta, session_id)
self.client = client
async def send(self, message: MessageChain):
for i in message.chain: # 遍历消息链
if isinstance(i, Plain): # 如果是文字类型的
await self.client.send_text(to=self.get_sender_id(), message=i.text)
elif isinstance(i, Image): # 如果是图片类型的
img_url = i.file
img_path = ""
# 下面的三个条件可以直接参考一下。
if img_url.startswith("file:///"):
img_path = img_url[8:]
elif i.file and i.file.startswith("http"):
img_path = await download_image_by_url(i.file)
else:
img_path = img_url
# 请善于 Debug！
await self.client.send_image(to=self.get_sender_id(), image_path=img_path)
await super().send(message) # 需要最后加上这一段，执行父类的 send 方法。
```
最后，main.py 只需这样，在初始化的时候导入 fake_platform_adapter 模块。装饰器会自动注册。
```py
from astrbot.api.star import Context, Star
class MyPlugin(Star):
def __init__(self, context: Context):
from .fake_platform_adapter import FakePlatformAdapter # noqa
```
搞好后，运行 AstrBot：
![image](https://files.astrbot.app/docs/source/images/plugin-platform-adapter/QQ_1738155926221.png)
这里出现了我们创建的 fake。
![image](https://files.astrbot.app/docs/source/images/plugin-platform-adapter/QQ_1738155982211.png)
启动后，可以看到正常工作：
![image](https://files.astrbot.app/docs/source/images/plugin-platform-adapter/QQ_1738156166893.png)
有任何疑问欢迎加群询问~
docs/en/dev/plugin.md
+1
View File
@@ -0,0 +1 @@
This page has moved to [AstrBot Plugin Development Guide](/en/dev/star/plugin-new).
docs/en/dev/star/guides/ai.md
+489
View File
@@ -0,0 +1,489 @@
# AI
AstrBot provides built-in support for multiple Large Language Model (LLM) providers and offers a unified interface, making it convenient for plugin developers to access various LLM services.
You can use the LLM / Agent interfaces provided by AstrBot to implement your own intelligent agents.
Starting from version `v4.5.7`, we've made significant improvements to the way LLM providers are invoked. We recommend using the new approach, which is more concise and supports additional features. The legacy invocation method remains documented in the previous Chinese-only guide.
## Getting the Chat Model ID for the Current Session
> [!TIP]
> Added in v4.5.7
```py
umo = event.unified_msg_origin
provider_id = await self.context.get_current_chat_provider_id(umo=umo)
```
## Invoking Large Language Models
> [!TIP]
> Added in v4.5.7
```py
llm_resp = await self.context.llm_generate(
chat_provider_id=provider_id, # Chat model ID
prompt="Hello, world!",
)
# print(llm_resp.completion_text) # Get the returned text
```
## Defining Tools
Tools enable large language models to invoke external capabilities.
```py
from pydantic import Field
from pydantic.dataclasses import dataclass
from astrbot.core.agent.run_context import ContextWrapper
from astrbot.core.agent.tool import FunctionTool, ToolExecResult
from astrbot.core.astr_agent_context import AstrAgentContext
@dataclass
class BilibiliTool(FunctionTool[AstrAgentContext]):
name: str = "bilibili_videos" # Tool name
description: str = "A tool to fetch Bilibili videos." # Tool description
parameters: dict = Field(
default_factory=lambda: {
"type": "object",
"properties": {
"keywords": {
"type": "string",
"description": "Keywords to search for Bilibili videos.",
},
},
"required": ["keywords"],
}
)
async def call(
self, context: ContextWrapper[AstrAgentContext], **kwargs
) -> ToolExecResult:
return "1. Video Title: How to Use AstrBot\nVideo Link: xxxxxx"
```
## Invoking Agents
> [!TIP]
> Added in v4.5.7
An Agent can be defined as a combination of system_prompt + tools + llm, enabling more sophisticated intelligent behavior.
After defining the Tool above, you can invoke an Agent as follows:
```py
llm_resp = await self.context.tool_loop_agent(
event=event,
chat_provider_id=prov_id,
prompt="Search for videos related to AstrBot on Bilibili.",
tools=ToolSet([BilibiliTool()]),
max_steps=30, # Maximum agent execution steps
tool_call_timeout=60, # Tool invocation timeout
)
# print(llm_resp.completion_text) # Get the returned text
```
`tool_loop_agent()` method automatically handles the loop of tool invocations and LLM requests until the model stops calling tools or the maximum number of steps is reached.
## Multi-Agent
> [!TIP]
> Added in v4.5.7
Multi-Agent systems decompose complex applications into multiple specialized agents that collaborate to solve problems. Unlike relying on a single agent to handle every step, multi-agent architectures allow smaller, more focused agents to be composed into coordinated workflows. We implement multi-agent systems using the `agent-as-tool` pattern.
In the example below, we define a Main Agent responsible for delegating tasks to different Sub-Agents based on user queries. Each Sub-Agent focuses on specific tasks, such as retrieving weather information.
![multi-agent-example-1](https://files.astrbot.app/docs/en/dev/star/guides/multi-agent-example-1.svg)
Define Tools:
```py
@dataclass
class AssignAgentTool(FunctionTool[AstrAgentContext]):
"""Main agent uses this tool to decide which sub-agent to delegate a task to."""
name: str = "assign_agent"
description: str = "Assign an agent to a task based on the given query"
parameters: dict = field(
default_factory=lambda: {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The query to call the sub-agent with.",
},
},
"required": ["query"],
}
)
async def call(
self, context: ContextWrapper[AstrAgentContext], **kwargs
) -> str | CallToolResult:
# Here you would implement the actual agent assignment logic.
# For demonstration purposes, we'll return a dummy response.
return "Based on the query, you should assign agent 1."
@dataclass
class WeatherTool(FunctionTool[AstrAgentContext]):
"""In this example, sub agent 1 uses this tool to get weather information."""
name: str = "weather"
description: str = "Get weather information for a location"
parameters: dict = field(
default_factory=lambda: {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city to get weather information for.",
},
},
"required": ["city"],
}
)
async def call(
self, context: ContextWrapper[AstrAgentContext], **kwargs
) -> str | CallToolResult:
city = kwargs["city"]
# Here you would implement the actual weather fetching logic.
# For demonstration purposes, we'll return a dummy response.
return f"The current weather in {city} is sunny with a temperature of 25°C."
@dataclass
class SubAgent1(FunctionTool[AstrAgentContext]):
"""Define a sub-agent as a function tool."""
name: str = "subagent1_name"
description: str = "subagent1_description"
parameters: dict = field(
default_factory=lambda: {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The query to call the sub-agent with.",
},
},
"required": ["query"],
}
)
async def call(
self, context: ContextWrapper[AstrAgentContext], **kwargs
) -> str | CallToolResult:
ctx = context.context.context
event = context.context.event
logger.info(f"the llm context messages: {context.messages}")
llm_resp = await ctx.tool_loop_agent(
event=event,
chat_provider_id=await ctx.get_current_chat_provider_id(
event.unified_msg_origin
),
prompt=kwargs["query"],
tools=ToolSet([WeatherTool()]),
max_steps=30,
)
return llm_resp.completion_text
@dataclass
class SubAgent2(FunctionTool[AstrAgentContext]):
"""Define a sub-agent as a function tool."""
name: str = "subagent2_name"
description: str = "subagent2_description"
parameters: dict = field(
default_factory=lambda: {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The query to call the sub-agent with.",
},
},
"required": ["query"],
}
)
async def call(
self, context: ContextWrapper[AstrAgentContext], **kwargs
) -> str | CallToolResult:
return "I am useless :(, you shouldn't call me :("
```
Then, similarly, invoke the Agent using the `tool_loop_agent()` method:
```py
@filter.command("test")
async def test(self, event: AstrMessageEvent):
umo = event.unified_msg_origin
prov_id = await self.context.get_current_chat_provider_id(umo)
llm_resp = await self.context.tool_loop_agent(
event=event,
chat_provider_id=prov_id,
prompt="Test calling sub-agent for Beijing's weather information.",
system_prompt=(
"You are the main agent. Your task is to delegate tasks to sub-agents based on user queries."
"Before delegating, use the 'assign_agent' tool to determine which sub-agent is best suited for the task."
),
tools=ToolSet([SubAgent1(), SubAgent2(), AssignAgentTool()]),
max_steps=30,
)
yield event.plain_result(llm_resp.completion_text)
```
## Conversation Manager
### Getting the Current LLM Conversation History for a Session
```py
from astrbot.core.conversation_mgr import Conversation
uid = event.unified_msg_origin
conv_mgr = self.context.conversation_manager
curr_cid = await conv_mgr.get_curr_conversation_id(uid)
conversation = await conv_mgr.get_conversation(uid, curr_cid) # Conversation
```
::: details Conversation 类型定义
```py
@dataclass
class Conversation:
"""The conversation entity representing a chat session."""
platform_id: str
"""The platform ID in AstrBot"""
user_id: str
"""The user ID associated with the conversation."""
cid: str
"""The conversation ID, in UUID format."""
history: str = ""
"""The conversation history as a string."""
title: str | None = ""
"""The title of the conversation. For now, it's only used in WebChat."""
persona_id: str | None = ""
"""The persona ID associated with the conversation."""
created_at: int = 0
"""The timestamp when the conversation was created."""
updated_at: int = 0
"""The timestamp when the conversation was last updated."""
```
:::
### Main Methods
#### `new_conversation`
- **Usage**
Create a new conversation in the current session and automatically switch to it.
- **Arguments**
- `unified_msg_origin: str` – In the format `platform_name:message_type:session_id`
- `platform_id: str | None` – Platform identifier, defaults to parsing from `unified_msg_origin`
- `content: list[dict] | None` – Initial message history
- `title: str | None` – Conversation title
- `persona_id: str | None` – Associated persona ID
- **Returns**
`str` – Newly generated UUID conversation ID
#### `switch_conversation`
- **Usage**
Switch the session to a specified conversation.
- **Arguments**
- `unified_msg_origin: str`
- `conversation_id: str`
- **Returns**
`None`
#### `delete_conversation`
- **Usage**
Delete a conversation from the session; if `conversation_id` is `None`, deletes the current conversation.
- **Arguments**
- `unified_msg_origin: str`
- `conversation_id: str | None`
- **Returns**
`None`
#### `get_curr_conversation_id`
- **Usage**
Get the conversation ID currently in use by the session.
- **Arguments**
- `unified_msg_origin: str`
- **Returns**
`str | None` – Current conversation ID, returns `None` if it doesn't exist
#### `get_conversation`
- **Usage**
Get the complete object for a specified conversation; automatically creates it if it doesn't exist and `create_if_not_exists=True`.
- **Arguments**
- `unified_msg_origin: str`
- `conversation_id: str`
- `create_if_not_exists: bool = False`
- **Returns**
`Conversation | None`
#### `get_conversations`
- **Usage**
Retrieve the complete list of conversations for a user or platform.
- **Arguments**
- `unified_msg_origin: str | None` – When `None`, does not filter by user
- `platform_id: str | None`
- **Returns**
`List[Conversation]`
#### `update_conversation`
- **Usage**
Update the title, history, or persona_id of a conversation.
- **Arguments**
- `unified_msg_origin: str`
- `conversation_id: str | None` – Uses the current conversation when `None`
- `history: list[dict] | None`
- `title: str | None`
- `persona_id: str | None`
- **Returns**
`None`
## Persona Manager
`PersonaManager` is responsible for unified loading, caching, and providing CRUD interfaces for all Personas, while maintaining compatibility with the legacy persona format (v3) from before AstrBot 4.x.
During initialization, it automatically reads all personas from the database and generates v3-compatible data for seamless use with legacy code.
```py
persona_mgr = self.context.persona_manager
```
### Main Methods
#### `get_persona`
- **Usage**
Get persona data by persona ID.
- **Arguments**
- `persona_id: str` – Persona ID
- **Returns**
`Persona` – Persona data, returns None if it doesn't exist
- **Raises**
`ValueError` – Raised when it doesn't exist
#### `get_all_personas`
- **Usage**
Retrieve all personas from the database at once.
- **Returns**
`list[Persona]` – Persona list, may be empty
#### `create_persona`
- **Usage**
Create a new persona and immediately write it to the database; automatically refreshes the local cache upon success.
- **Arguments**
- `persona_id: str` – New persona ID (unique)
- `system_prompt: str` – System prompt
- `begin_dialogs: list[str]` – Optional, opening dialogs (even number of entries, alternating user/assistant)
- `tools: list[str]` – Optional, list of allowed tools; `None`=all tools, `[]`=disable all
- **Returns**
`Persona` – Newly created persona object
- **Raises**
`ValueError` – If `persona_id` already exists
#### `update_persona`
- **Usage**
Update any fields of an existing persona and synchronize to database and cache.
- **Arguments**
- `persona_id: str` – Persona ID to update
- `system_prompt: str` – Optional, new system prompt
- `begin_dialogs: list[str]` – Optional, new opening dialogs
- `tools: list[str]` – Optional, new tool list; semantics same as `create_persona`
- **Returns**
`Persona` – Updated persona object
- **Raises**
`ValueError` – If `persona_id` doesn't exist
#### `delete_persona`
- **Usage**
Delete the specified persona and clean up both database and cache.
- **Arguments**
- `persona_id: str` – Persona ID to delete
- **Raises**
`ValueError` – If `persona_id` doesn't exist
#### `get_default_persona_v3`
- **Usage**
Get the default persona (v3 format) to use based on the current session configuration.
Falls back to `DEFAULT_PERSONALITY` if configuration doesn't specify one or the specified persona doesn't exist.
- **Arguments**
- `umo: str | MessageSession | None` – Session identifier, used to read user-level configuration
- **Returns**
`Personality` – Default persona object in v3 format
::: details Persona / Personality 类型定义
```py
class Persona(SQLModel, table=True):
"""Persona is a set of instructions for LLMs to follow.
It can be used to customize the behavior of LLMs.
"""
__tablename__ = "personas"
id: int = Field(primary_key=True, sa_column_kwargs={"autoincrement": True})
persona_id: str = Field(max_length=255, nullable=False)
system_prompt: str = Field(sa_type=Text, nullable=False)
begin_dialogs: Optional[list] = Field(default=None, sa_type=JSON)
"""a list of strings, each representing a dialog to start with"""
tools: Optional[list] = Field(default=None, sa_type=JSON)
"""None means use ALL tools for default, empty list means no tools, otherwise a list of tool names."""
created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
updated_at: datetime = Field(
default_factory=lambda: datetime.now(timezone.utc),
sa_column_kwargs={"onupdate": datetime.now(timezone.utc)},
)
__table_args__ = (
UniqueConstraint(
"persona_id",
name="uix_persona_id",
),
)
class Personality(TypedDict):
"""LLM Persona class.
Starting from v4.0.0 and later, it's recommended to use the Persona class above. Additionally, the mood_imitation_dialogs field has been deprecated.
"""
prompt: str
name: str
begin_dialogs: list[str]
mood_imitation_dialogs: list[str]
"""Mood imitation dialog preset. Deprecated since v4.0.0 and later."""
tools: list[str] | None
"""Tool list. None means use all tools, empty list means don't use any tools"""
```
:::
docs/en/dev/star/guides/env.md
+48
View File
@@ -0,0 +1,48 @@
# 开发环境准备
## 获取插件模板
1. 打开 AstrBot 插件模板: [helloworld](https://github.com/Soulter/helloworld)
2. 点击右上角的 `Use this template`
3. 然后点击 `Create new repository`。
4. 在 `Repository name` 处填写您的插件名。插件名格式:
- 推荐以 `astrbot_plugin_` 开头；
- 不能包含空格；
- 保持全部字母小写；
- 尽量简短。
5. 点击右下角的 `Create repository`。
![New repo](https://files.astrbot.app/docs/source/images/plugin/image.png)
## Clone 插件和 AstrBot 项目
Clone AstrBot 项目本体和刚刚创建的插件仓库到本地。
```bash
git clone https://github.com/AstrBotDevs/AstrBot
mkdir -p AstrBot/data/plugins
cd AstrBot/data/plugins
git clone 插件仓库地址
```
然后，使用 `VSCode` 打开 `AstrBot` 项目。找到 `data/plugins/<你的插件名字>` 目录。
更新 `metadata.yaml` 文件，填写插件的元数据信息。
> [!NOTE]
> AstrBot 插件市场的信息展示依赖于 `metadata.yaml` 文件。
## 调试插件
AstrBot 采用在运行时注入插件的机制。因此，在调试插件时，需要启动 AstrBot 本体。
您可以使用 AstrBot 的热重载功能简化开发流程。
插件的代码修改后，可以在 AstrBot WebUI 的插件管理处找到自己的插件，点击右上角 `...` 按钮，选择 `重载插件`。
## 插件依赖管理
目前 AstrBot 对插件的依赖管理使用 `pip` 自带的 `requirements.txt` 文件。如果你的插件需要依赖第三方库，请务必在插件目录下创建 `requirements.txt` 文件并写入所使用的依赖库，以防止用户在安装你的插件时出现依赖未找到(Module Not Found)的问题。
> `requirements.txt` 的完整格式可以参考 [pip 官方文档](https://pip.pypa.io/en/stable/reference/requirements-file-format/)。
docs/en/dev/star/guides/html-to-pic.md
+66
View File
@@ -0,0 +1,66 @@
# Text to Image
> [!TIP]
> For easier development, you can use the [AstrBot Text2Image Playground](https://t2i-playground.astrbot.app/) for online visual editing and testing of HTML templates.
## Basic Usage
AstrBot supports rendering text into images.
```python
@filter.command("image") # Register an /image command that accepts a text parameter.
async def on_aiocqhttp(self, event: AstrMessageEvent, text: str):
url = await self.text_to_image(text) # text_to_image() is a method of the Star class.
# path = await self.text_to_image(text, return_url = False) # If you want to save the image locally
yield event.image_result(url)
```
![image](https://files.astrbot.app/docs/source/images/plugin/image-3.png)
## Customization (HTML-Based)
If you find the default rendered images insufficiently aesthetic, you can use custom HTML templates to render images.
AstrBot supports rendering text-to-image templates using `HTML + Jinja2`.
```py{7}
# Custom Jinja2 template with CSS support
TMPL = '''
<div style="font-size: 32px;">
<h1 style="color: black">Todo List</h1>
<ul>
{% for item in items %}
<li>{{ item }}</li>
{% endfor %}
</div>
'''
@filter.command("todo")
async def custom_t2i_tmpl(self, event: AstrMessageEvent):
options = {} # Optionally pass rendering options.
url = await self.html_render(TMPL, {"items": ["Eat", "Sleep", "Play Genshin"]}, options=options) # The second parameter is the data for Jinja2 rendering
yield event.image_result(url)
```
The result:
![image](https://files.astrbot.app/docs/source/images/plugin/fcc2dcb472a91b12899f617477adc5c7.png)
This is just a simple example. Thanks to the powerful capabilities of HTML and DOM renderers, you can create more complex and visually appealing designs. Additionally, Jinja2 supports syntax for loops, conditionals, and more to accommodate data structures like lists and dictionaries. You can learn more about Jinja2 online.
**Image Rendering Options (options)**:
Please refer to Playwright's [screenshot](https://playwright.dev/python/docs/api/class-page#page-screenshot) API.
- `timeout` (float, optional): Screenshot timeout duration.
- `type` (Literal["jpeg", "png"], optional): Screenshot image type.
- `quality` (int, optional): Screenshot quality, only applicable to JPEG format images.
- `omit_background` (bool, optional): Whether to hide the default white background, allowing transparent screenshots. Only applicable to PNG format.
- `full_page` (bool, optional): Whether to capture the entire page rather than just the viewport size. Defaults to True.
- `clip` (dict, optional): The region to crop after taking the screenshot. Refer to Playwright's screenshot API.
- `animations`: (Literal["allow", "disabled"], optional): Whether to allow CSS animations to play.
- `caret`: (Literal["hide", "initial"], optional): When set to hide, the text cursor will be hidden during the screenshot. Defaults to hide.
- `scale`: (Literal["css", "device"], optional): Page scaling setting. When set to css, device resolution maps one-to-one with CSS pixels, which may result in smaller screenshots on high-DPI screens. When set to device, scaling is based on the device's screen scaling settings or the device_scale_factor parameter in the current Playwright Page/Context.
docs/en/dev/star/guides/listen-message-event.md
+348
View File
@@ -0,0 +1,348 @@
# Handling Message Events
Event listeners can receive message content delivered by the platform and implement features such as commands, command groups, and event listening.
Event listener decorators are located in `astrbot.api.event.filter` and must be imported first. Please make sure to import it, otherwise it will conflict with Python's built-in `filter` higher-order function.
```py
from astrbot.api.event import filter, AstrMessageEvent
```
## Messages and Events
AstrBot receives messages delivered by messaging platforms and encapsulates them as `AstrMessageEvent` objects, which are then passed to plugins for processing.
![message-event](https://files.astrbot.app/docs/en/dev/star/guides/message-event.svg)
### Message Events
`AstrMessageEvent` is AstrBot's message event object, which stores information about the message sender, message content, etc.
### Message Object
`AstrBotMessage` is AstrBot's message object, which stores the specific content of messages delivered by the messaging platform. The `AstrMessageEvent` object contains a `message_obj` attribute to retrieve this message object.
```py{11}
class AstrBotMessage:
'''AstrBot's message object'''
type: MessageType # Message type
self_id: str # Bot's identification ID
session_id: str # Session ID. Depends on the unique_session setting.
message_id: str # Message ID
group_id: str = "" # Group ID, empty if it's a private chat
sender: MessageMember # Sender
message: List[BaseMessageComponent] # Message chain. For example: [Plain("Hello"), At(qq=123456)]
message_str: str # The most straightforward plain text message string, concatenating Plain messages (text messages) from the message chain
raw_message: object
timestamp: int # Message timestamp
```
Here, `raw_message` is the **raw message object** from the messaging platform adapter.
### Message Chain
![message-chain](https://files.astrbot.app/docs/en/dev/star/guides/message-chain.svg)
A `message chain` describes the structure of a message. It's an ordered list where each element is called a `message segment`.
Common message segment types include:
- `Plain`: Text message segment
- `At`: Mention message segment
- `Image`: Image message segment
- `Record`: Audio message segment
- `Video`: Video message segment
- `File`: File message segment
Most messaging platforms support the above message segment types.
Additionally, the OneBot v11 platform (QQ personal accounts, etc.) also supports the following common message segment types:
- `Face`: Emoji message segment
- `Node`: A node in a forward message
- `Nodes`: Multiple nodes in a forward message
- `Poke`: Poke message segment
In AstrBot, message chains are represented as lists of type `List[BaseMessageComponent]`.
## Commands
![message-event-simple-command](https://files.astrbot.app/docs/en/dev/star/guides/message-event-simple-command.svg)
```python
from astrbot.api.event import filter, AstrMessageEvent
from astrbot.api.star import Context, Star
class MyPlugin(Star):
def __init__(self, context: Context):
super().__init__(context)
@filter.command("helloworld") # from astrbot.api.event.filter import command
async def helloworld(self, event: AstrMessageEvent):
'''This is a hello world command'''
user_name = event.get_sender_name()
message_str = event.message_str # Get the plain text content of the message
yield event.plain_result(f"Hello, {user_name}!")
```
> [!TIP]
> Commands cannot contain spaces, otherwise AstrBot will parse them as a second parameter. You can use the command group feature below, or use a listener to parse the message content yourself.
## Commands with Parameters
![command-with-param](https://files.astrbot.app/docs/en/dev/star/guides/command-with-param.svg)
AstrBot will automatically parse command parameters for you.
```python
@filter.command("add")
def add(self, event: AstrMessageEvent, a: int, b: int):
# /add 1 2 -> Result is: 3
yield event.plain_result(f"Wow! The answer is {a + b}!")
```
## Command Groups
Command groups help you organize commands.
```python
@filter.command_group("math")
def math(self):
pass
@math.command("add")
async def add(self, event: AstrMessageEvent, a: int, b: int):
# /math add 1 2 -> Result is: 3
yield event.plain_result(f"Result is: {a + b}")
@math.command("sub")
async def sub(self, event: AstrMessageEvent, a: int, b: int):
# /math sub 1 2 -> Result is: -1
yield event.plain_result(f"Result is: {a - b}")
```
The command group function doesn't need to implement any logic; just use `pass` directly or add comments within the function. Subcommands of the command group are registered using `command_group_name.command`.
When a user doesn't input a subcommand, an error will be reported and the tree structure of the command group will be rendered.
![image](https://files.astrbot.app/docs/source/images/plugin/image-1.png)
![image](https://files.astrbot.app/docs/source/images/plugin/898a169ae7ed0478f41c0a7d14cb4d64.png)
![image](https://files.astrbot.app/docs/source/images/plugin/image-2.png)
Theoretically, command groups can be nested infinitely!
```py
'''
math
├── calc
│ ├── add (a(int),b(int),)
│ ├── sub (a(int),b(int),)
│ ├── help (command with no parameters)
'''
@filter.command_group("math")
def math():
pass
@math.group("calc") # Note: this is group, not command_group
def calc():
pass
@calc.command("add")
async def add(self, event: AstrMessageEvent, a: int, b: int):
yield event.plain_result(f"Result is: {a + b}")
@calc.command("sub")
async def sub(self, event: AstrMessageEvent, a: int, b: int):
yield event.plain_result(f"Result is: {a - b}")
@calc.command("help")
def calc_help(self, event: AstrMessageEvent):
# /math calc help
yield event.plain_result("This is a calculator plugin with add and sub commands.")
```
## Command Aliases
> Available after v3.4.28
You can add different aliases for commands or command groups:
```python
@filter.command("help", alias={'帮助', 'helpme'})
def help(self, event: AstrMessageEvent):
yield event.plain_result("This is a calculator plugin with add and sub commands.")
```
### Event Type Filtering
#### Receive All
This will receive all events.
```python
@filter.event_message_type(filter.EventMessageType.ALL)
async def on_all_message(self, event: AstrMessageEvent):
yield event.plain_result("Received a message.")
```
#### Group Chat and Private Chat
```python
@filter.event_message_type(filter.EventMessageType.PRIVATE_MESSAGE)
async def on_private_message(self, event: AstrMessageEvent):
message_str = event.message_str # Get the plain text content of the message
yield event.plain_result("Received a private message.")
```
`EventMessageType` is an `Enum` type that contains all event types. Current event types are `PRIVATE_MESSAGE` and `GROUP_MESSAGE`.
#### Messaging Platform
```python
@filter.platform_adapter_type(filter.PlatformAdapterType.AIOCQHTTP | filter.PlatformAdapterType.QQOFFICIAL)
async def on_aiocqhttp(self, event: AstrMessageEvent):
'''Only receive messages from AIOCQHTTP and QQOFFICIAL'''
yield event.plain_result("Received a message")
```
In the current version, `PlatformAdapterType` includes `AIOCQHTTP`, `QQOFFICIAL`, `GEWECHAT`, and `ALL`.
#### Admin Commands
```python
@filter.permission_type(filter.PermissionType.ADMIN)
@filter.command("test")
async def test(self, event: AstrMessageEvent):
pass
```
Only admins can use the `test` command.
### Multiple Filters
Multiple filters can be used simultaneously by adding multiple decorators to a function. Filters use `AND` logic, meaning the function will only execute if all filters pass.
```python
@filter.command("helloworld")
@filter.event_message_type(filter.EventMessageType.PRIVATE_MESSAGE)
async def helloworld(self, event: AstrMessageEvent):
yield event.plain_result("Hello!")
```
### Event Hooks
> [!TIP]
> Event hooks do not support being used together with @filter.command, @filter.command_group, @filter.event_message_type, @filter.platform_adapter_type, or @filter.permission_type.
#### On Bot Initialization Complete
> Available after v3.4.34
```python
from astrbot.api.event import filter, AstrMessageEvent
@filter.on_astrbot_loaded()
async def on_astrbot_loaded(self):
print("AstrBot initialization complete")
```
#### On LLM Request
In AstrBot's default execution flow, the `on_llm_request` hook is triggered before calling the LLM.
You can obtain the `ProviderRequest` object and modify it.
The ProviderRequest object contains all information about the LLM request, including the request text, system prompt, etc.
```python
from astrbot.api.event import filter, AstrMessageEvent
from astrbot.api.provider import ProviderRequest
@filter.on_llm_request()
async def my_custom_hook_1(self, event: AstrMessageEvent, req: ProviderRequest): # Note there are three parameters
print(req) # Print the request text
req.system_prompt += "Custom system_prompt"
```
> You cannot use yield to send messages here. If you need to send, please use the `event.send()` method directly.
#### On LLM Response Complete
After the LLM request completes, the `on_llm_response` hook is triggered.
You can obtain the `ProviderResponse` object and modify it.
```python
from astrbot.api.event import filter, AstrMessageEvent
from astrbot.api.provider import LLMResponse
@filter.on_llm_response()
async def on_llm_resp(self, event: AstrMessageEvent, resp: LLMResponse): # Note there are three parameters
print(resp)
```
> You cannot use yield to send messages here. If you need to send, please use the `event.send()` method directly.
#### Before Sending Message
Before sending a message, the `on_decorating_result` hook is triggered.
You can implement some message decoration here, such as converting to voice, converting to image, adding prefixes, etc.
```python
from astrbot.api.event import filter, AstrMessageEvent
@filter.on_decorating_result()
async def on_decorating_result(self, event: AstrMessageEvent):
result = event.get_result()
chain = result.chain
print(chain) # Print the message chain
chain.append(Plain("!")) # Add an exclamation mark at the end of the message chain
```
> You cannot use yield to send messages here. This hook is only for decorating event.get_result().chain. If you need to send, please use the `event.send()` method directly.
#### After Message Sent
After a message is sent to the messaging platform, the `after_message_sent` hook is triggered.
```python
from astrbot.api.event import filter, AstrMessageEvent
@filter.after_message_sent()
async def after_message_sent(self, event: AstrMessageEvent):
pass
```
> You cannot use yield to send messages here. If you need to send, please use the `event.send()` method directly.
### Priority
Commands, event listeners, and event hooks can have priority set to execute before other commands, listeners, or hooks. The default priority is `0`.
```python
@filter.command("helloworld", priority=1)
async def helloworld(self, event: AstrMessageEvent):
yield event.plain_result("Hello!")
```
## Controlling Event Propagation
```python{6}
@filter.command("check_ok")
async def check_ok(self, event: AstrMessageEvent):
ok = self.check() # Your own logic
if not ok:
yield event.plain_result("Check failed")
event.stop_event() # Stop event propagation
```
When event propagation is stopped, all subsequent steps will not be executed.
Assuming there's a plugin A, after A terminates event propagation, all subsequent operations will not be executed, such as executing other plugins' handlers or requesting the LLM.
docs/en/dev/star/guides/plugin-config.md
+211
View File
@@ -0,0 +1,211 @@
# Plugin Configuration
As plugin functionality grows, you may need to define configurations to allow users to customize plugin behavior.
AstrBot provides "powerful" configuration parsing and visualization features. Users can configure plugins directly in the management panel without modifying code.
## Configuration Definition
To register configurations, first add a `_conf_schema.json` JSON file in your plugin directory.
The file content is a `Schema` that represents the configuration. The Schema is in JSON format, for example:
```json
{
"token": {
"description": "Bot Token",
"type": "string",
},
"sub_config": {
"description": "Test nested configuration",
"type": "object",
"hint": "xxxx",
"items": {
"name": {
"description": "testsub",
"type": "string",
"hint": "xxxx"
},
"id": {
"description": "testsub",
"type": "int",
"hint": "xxxx"
},
"time": {
"description": "testsub",
"type": "int",
"hint": "xxxx",
"default": 123
}
}
}
}
```
- `type`: **Required**. The type of the configuration. Supports `string`, `text`, `int`, `float`, `bool`, `object`, `list`, `dict`, `template_list`, `file`. When the type is `text`, it will be visualized as a larger resizable textarea component to accommodate large text.
- `description`: Optional. Description of the configuration. A one-sentence description of the configuration's behavior is recommended.
- `hint`: Optional. Hint information for the configuration, displayed in the question mark button on the right in the image above, shown when hovering over it.
- `obvious_hint`: Optional. Whether the configuration hint should be prominently displayed, like `token` in the image above.
- `default`: Optional. The default value of the configuration. If the user hasn't configured it, the default value will be used. Default values: int is 0, float is 0.0, bool is False, string is "", object is {}, list is [].
- `items`: Optional. If the configuration type is `object`, the `items` field needs to be added. The content of `items` is the sub-Schema of this configuration item. Theoretically, it can be nested infinitely, but excessive nesting is not recommended.
- `invisible`: Optional. Whether the configuration is hidden. Default is `false`. If set to `true`, it will not be displayed in the management panel.
- `options`: Optional. A list, such as `"options": ["chat", "agent", "workflow"]`. Provides dropdown list options.
- `editor_mode`: Optional. Whether to enable code editor mode. Requires AstrBot >= `v3.5.10`. Versions below this won't report errors but won't take effect. Default is false.
- `editor_language`: Optional. The code language for the code editor, defaults to `json`.
- `editor_theme`: Optional. The theme for the code editor. Options are `vs-light` (default) and `vs-dark`.
- `_special`: Optional. Used to call AstrBot's visualization features for provider selection, persona selection, knowledge base selection, etc. See details below.
When the code editor is enabled, it looks like this:
![editor_mode](https://files.astrbot.app/docs/source/images/plugin/image-6.png)
![editor_mode_fullscreen](https://files.astrbot.app/docs/source/images/plugin/image-7.png)
The **_special** field is only available after v4.0.0. Currently supports `select_provider`, `select_provider_tts`, `select_provider_stt`, `select_persona`, allowing users to quickly select model providers, personas, and other data already configured in the WebUI. Results are all strings. Using select_provider as an example, it will present the following effect:
![image](https://files.astrbot.app/docs/source/images/plugin/image-select-provider.png)
### `file` type schema
Introduced in v4.13.0, this allows plugins to define file-upload configuration items to guide users to upload files required by the plugin.
```json
{
"demo_files": {
"type": "file",
"description": "Uploaded files for demo",
"default": [],
"file_types": ["pdf", "docx"]
}
}
```
### `dict` type schema
Used to visualize editing a Python `dict` type configuration. For example, AstrBot Core's custom extra body parameter configuration:
```py
"custom_extra_body": {
"description": "Custom request body parameters",
"type": "dict",
"items": {},
"hint": "Used to add extra parameters to requests, such as temperature, top_p, max_tokens, etc.",
"template_schema": {
"temperature": {
"name": "Temperature",
"description": "Temperature parameter",
"hint": "Controls randomness of output, typically 0-2. Higher is more random.",
"type": "float",
"default": 0.6,
"slider": {"min": 0, "max": 2, "step": 0.1},
},
"top_p": {
"name": "Top-p",
"description": "Top-p sampling",
"hint": "Nucleus sampling parameter, typically 0-1. Controls probability mass considered.",
"type": "float",
"default": 1.0,
"slider": {"min": 0, "max": 1, "step": 0.01},
},
"max_tokens": {
"name": "Max Tokens",
"description": "Maximum tokens",
"hint": "Maximum number of tokens to generate.",
"type": "int",
"default": 8192,
},
},
}
```
### `template_list` type schema
> [!NOTE]
> Introduced in v4.10.4. For more details see: [#4208](https://github.com/AstrBotDevs/AstrBot/pull/4208)
Plugin developers can add a template-style configuration to `_conf_schema` in the following format (somewhat similar to nested configs):
```json
"field_id": {
"type": "template_list",
"description": "Template List Field",
"templates": {
"template_1": {
"name": "Template One",
"hint":"hint",
"items": {
"attr_a": {
"description": "Attribute A",
"type": "int",
"default": 10
},
"attr_b": {
"description": "Attribute B",
"hint": "This is a boolean attribute",
"type": "bool",
"default": true
}
}
},
"template_2": {
"name": "Template Two",
"hint":"hint",
"items": {
"attr_c": {
"description": "Attribute A",
"type": "int",
"default": 10
},
"attr_d": {
"description": "Attribute B",
"hint": "This is a boolean attribute",
"type": "bool",
"default": true
}
}
}
}
}
```
Saved config example:
```json
"field_id": [
{
"__template_key": "template_1",
"attr_a": 10,
"attr_b": true
},
{
"__template_key": "template_2",
"attr_c": 10,
"attr_d": true
}
]
```
<img width="1000" alt="image" src="https://github.com/user-attachments/assets/74876d30-11a4-491b-a7a0-8ebe8d603782" />
## Using Configuration in Plugins
When loading plugins, AstrBot will check if there's a `_conf_schema.json` file in the plugin directory. If it exists, it will automatically parse the configuration and save it under `data/config/<plugin_name>_config.json` (a configuration file entity created according to the Schema), and pass it to `__init__()` when instantiating the plugin class.
```py
from astrbot.api import AstrBotConfig
class ConfigPlugin(Star):
def __init__(self, context: Context, config: AstrBotConfig): # AstrBotConfig inherits from Dict and has all dictionary methods
super().__init__(context)
self.config = config
print(self.config)
# Supports direct configuration saving
# self.config.save_config() # Save configuration
```
## Configuration Updates
When you update the Schema across different versions, AstrBot will recursively inspect the configuration items in the Schema, automatically adding default values for missing items and removing those that no longer exist.
docs/en/dev/star/guides/send-message.md
+131
View File
@@ -0,0 +1,131 @@
# Sending Messages
## Passive Messages
Passive messages refer to the bot responding to messages reactively.
```python
@filter.command("helloworld")
async def helloworld(self, event: AstrMessageEvent):
yield event.plain_result("Hello!")
yield event.plain_result("你好！")
yield event.image_result("path/to/image.jpg") # Send an image
yield event.image_result("https://example.com/image.jpg") # Send an image from URL, must start with http or https
```
## Active Messages
Active messages refer to the bot proactively pushing messages. Some platforms may not support active message sending.
For scheduled tasks or when you don't want to send messages immediately, you can use `event.unified_msg_origin` to get a string and store it, then use `self.context.send_message(unified_msg_origin, chains)` to send messages when needed.
```python
from astrbot.api.event import MessageChain
@filter.command("helloworld")
async def helloworld(self, event: AstrMessageEvent):
umo = event.unified_msg_origin
message_chain = MessageChain().message("Hello!").file_image("path/to/image.jpg")
await self.context.send_message(event.unified_msg_origin, message_chain)
```
With this feature, you can store the `unified_msg_origin` and send messages when needed.
> [!TIP]
> About unified_msg_origin.
> `unified_msg_origin` is a string that records the unique ID of a session. AstrBot uses it to identify which messaging platform and which session it belongs to. This allows messages to be sent to the correct session when using `send_message`. For more about MessageChain, see the next section.
## Rich Media Messages
AstrBot supports sending rich media messages such as images, audio, videos, etc. Use `MessageChain` to construct messages.
```python
import astrbot.api.message_components as Comp
@filter.command("helloworld")
async def helloworld(self, event: AstrMessageEvent):
chain = [
Comp.At(qq=event.get_sender_id()), # Mention the message sender
Comp.Plain("Check out this image:"),
Comp.Image.fromURL("https://example.com/image.jpg"), # Send image from URL
Comp.Image.fromFileSystem("path/to/image.jpg"), # Send image from local file system
Comp.Plain("This is an image.")
]
yield event.chain_result(chain)
```
The above constructs a `message chain`, which will ultimately send a message containing both images and text while preserving the order.
> [!TIP]
> In the aiocqhttp message adapter, for messages of type `plain`, the `strip()` method is used during sending to remove spaces and line breaks. You can add zero-width spaces `\u200b` before and after the message to resolve this issue.
Similarly,
**File**
```py
Comp.File(file="path/to/file.txt", name="file.txt") # Not supported by some platforms
```
**Audio Record**
```py
path = "path/to/record.wav" # Currently only accepts wav format, please convert other formats yourself
Comp.Record(file=path, url=path)
```
**Video**
```py
path = "path/to/video.mp4"
Comp.Video.fromFileSystem(path=path)
Comp.Video.fromURL(url="https://example.com/video.mp4")
```
## Sending Video Messages
```python
from astrbot.api.event import filter, AstrMessageEvent
@filter.command("test")
async def test(self, event: AstrMessageEvent):
from astrbot.api.message_components import Video
# fromFileSystem requires the user's protocol client and bot to be on the same system.
music = Video.fromFileSystem(
path="test.mp4"
)
# More universal approach
music = Video.fromURL(
url="https://example.com/video.mp4"
)
yield event.chain_result([music])
```
![Sending video messages](https://files.astrbot.app/docs/source/images/plugin/db93a2bb-671c-4332-b8ba-9a91c35623c2.png)
## Sending Group Forward Messages
> Most platforms do not support this message type. Current support: OneBot v11
You can send group forward messages as follows.
```py
from astrbot.api.event import filter, AstrMessageEvent
@filter.command("test")
async def test(self, event: AstrMessageEvent):
from astrbot.api.message_components import Node, Plain, Image
node = Node(
uin=905617992,
name="Soulter",
content=[
Plain("hi"),
Image.fromFileSystem("test.jpg")
]
)
yield event.chain_result([node])
```
![Sending group forward messages](https://files.astrbot.app/docs/source/images/plugin/image-4.png)
docs/en/dev/star/guides/session-control.md
+113
View File
@@ -0,0 +1,113 @@
# Session Control
> v3.4.36 and above
Why do we need session control? Consider a Chinese idiom chain game plugin where a user or group needs to have multiple conversations with the bot rather than a one-time command. This is when session control becomes necessary.
```txt
User: /idiom-chain
Bot: Please send an idiom
User: One horse takes the lead (一马当先)
Bot: Foresight (先见之明)
User: Keen observation (明察秋毫)
...
```
AstrBot provides out-of-the-box session control functionality:
Import:
```py
import astrbot.api.message_components as Comp
from astrbot.core.utils.session_waiter import (
session_waiter,
SessionController,
)
```
Code within the handler can be written as follows:
```python
from astrbot.api.event import filter, AstrMessageEvent
@filter.command("idiom-chain")
async def handle_empty_mention(self, event: AstrMessageEvent):
"""Idiom chain game implementation"""
try:
yield event.plain_result("Please send an idiom~")
# How to use the session controller
@session_waiter(timeout=60, record_history_chains=False) # Register a session controller with a 60-second timeout, without recording message history
async def empty_mention_waiter(controller: SessionController, event: AstrMessageEvent):
idiom = event.message_str # The idiom sent by the user, e.g., "one horse takes the lead"
if idiom == "exit": # If the user wants to exit the idiom chain game by typing "exit"
await event.send(event.plain_result("Exited the idiom chain game~"))
controller.stop() # Stop the session controller, which will end immediately.
return
if len(idiom) != 4: # If the user's input is not a 4-character idiom
await event.send(event.plain_result("The idiom must be four characters~")) # Send a reply, cannot use yield
return
# Exit the current method without executing subsequent logic, but the session is not interrupted; subsequent user input will still enter the current session
# ...
message_result = event.make_result()
message_result.chain = [Comp.Plain("Foresight")] # import astrbot.api.message_components as Comp
await event.send(message_result) # Send a reply, cannot use yield
controller.keep(timeout=60, reset_timeout=True) # Reset timeout to 60s. If not reset, it will continue the previous timeout countdown.
# controller.stop() # Stop the session controller, which will end immediately.
# If history chains are recorded, you can retrieve them via controller.get_history_chains()
try:
await empty_mention_waiter(event)
except TimeoutError as _: # When timeout occurs, the session controller will raise TimeoutError
yield event.plain_result("You timed out!")
except Exception as e:
yield event.plain_result("An error occurred, please contact the administrator: " + str(e))
finally:
event.stop_event()
except Exception as e:
logger.error("handle_empty_mention error: " + str(e))
```
Once the session controller is activated, messages subsequently sent by that sender will first be processed by the `empty_mention_waiter` function you defined above, until the session controller is stopped or times out.
## SessionController
Used by developers to control whether a session should end, and to retrieve message history chains.
- keep(): Keep this session alive
- timeout (float): Required. Session timeout duration.
- reset_timeout (bool): When set to True, it resets the timeout; timeout must be > 0, if <= 0 the session ends immediately. When set to False, it maintains the original timeout; new timeout = remaining timeout + timeout (can be < 0)
- stop(): End this session
- get_history_chains() -> List[List[Comp.BaseMessageComponent]]: Retrieve message history chains
## Custom Session ID Filter
By default, the AstrBot session controller uses `sender_id` (the sender's ID) as the identifier for distinguishing different sessions. If you want to treat an entire group as one session, you need to customize the session ID filter.
```py
import astrbot.api.message_components as Comp
from astrbot.core.utils.session_waiter import (
session_waiter,
SessionFilter,
SessionController,
)
# Using the handler from above
# ...
class CustomFilter(SessionFilter):
def filter(self, event: AstrMessageEvent) -> str:
return event.get_group_id() if event.get_group_id() else event.unified_msg_origin
await empty_mention_waiter(event, session_filter=CustomFilter()) # Pass in session_filter here
# ...
```
After this setup, when a user in a group sends a message, the session controller will treat the entire group as one session, and messages from other users in the group will also be considered part of the same session.
You can even use this feature to enable team-based activities within groups!
docs/en/dev/star/guides/simple.md
+58
View File
@@ -0,0 +1,58 @@
# Minimal Example
The `main.py` file in the plugin template is a minimal plugin instance.
```python
from astrbot.api.event import filter, AstrMessageEvent, MessageEventResult
from astrbot.api.star import Context, Star
from astrbot.api import logger # Use the logger interface provided by AstrBot
class MyPlugin(Star):
def __init__(self, context: Context):
super().__init__(context)
# Decorator to register a command. The command name is "helloworld". Once registered, sending `/helloworld` will trigger this command and respond with `Hello, {user_name}!`
@filter.command("helloworld")
async def helloworld(self, event: AstrMessageEvent):
'''This is a hello world command''' # This is the handler's description, which will be parsed to help users understand the plugin's functionality. Highly recommended to provide.
user_name = event.get_sender_name()
message_str = event.message_str # Get the plain text content of the message
logger.info("Hello world command triggered!")
yield event.plain_result(f"Hello, {user_name}!") # Send a plain text message
async def terminate(self):
'''Optionally implement the terminate function, which will be called when the plugin is uninstalled/disabled.'''
```
Explanation:
- Plugins must inherit from the `Star` class.
- The `Context` class is used for plugin interaction with AstrBot Core, allowing you to call various APIs provided by AstrBot Core.
- Specific handler functions are defined within the plugin class, such as the `helloworld` function here.
- `AstrMessageEvent` is AstrBot's message event object, which stores information about the message sender, message content, etc.
- `AstrBotMessage` is AstrBot's message object, which stores the specific content of messages delivered by the messaging platform. It can be accessed via `event.message_obj`.
> [!TIP]
>
> Handlers must be registered within the plugin class, with the first two parameters being `self` and `event`. If the file becomes too long, you can write services externally and call them from the handler.
>
> The file containing the plugin class must be named `main.py`.
All handler functions must be written within the plugin class. To keep content concise, in subsequent sections, we may omit the plugin class definition.
```
解释如下：
- 插件需要继承 `Star` 类。
- `Context` 类用于插件与 AstrBot Core 交互，可以由此调用 AstrBot Core 提供的各种 API。
- 具体的处理函数 `Handler` 在插件类中定义，如这里的 `helloworld` 函数。
- `AstrMessageEvent` 是 AstrBot 的消息事件对象，存储了消息发送者、消息内容等信息。
- `AstrBotMessage` 是 AstrBot 的消息对象，存储了消息平台下发的消息的具体内容。可以通过 `event.message_obj` 获取。
> [!TIP]
>
> `Handler` 一定需要在插件类中注册，前两个参数必须为 `self` 和 `event`。如果文件行数过长，可以将服务写在外部，然后在 `Handler` 中调用。
>
> 插件类所在的文件名需要命名为 `main.py`。
所有的处理函数都需写在插件类中。为了精简内容，在之后的章节中，我们可能会忽略插件类的定义。
docs/en/dev/star/guides/storage.md
+31
View File
@@ -0,0 +1,31 @@
# Plugin Storage
## Simple KV Storage
> [!TIP]
> Requires AstrBot version >= 4.9.2.
Plugins can use AstrBot's simple key-value store to persist configuration or temporary data. The storage is scoped per plugin, so each plugin has its own isolated space.
```py
class Main(star.Star):
@filter.command("hello")
async def hello(self, event: AstrMessageEvent):
"""Aloha!"""
await self.put_kv_data("greeted", True)
greeted = await self.get_kv_data("greeted", False)
await self.delete_kv_data("greeted")
```
## Large File Storage Convention
To keep large file handling consistent, store large files under `data/plugin_data/{plugin_name}/`.
You can fetch the plugin data directory with:
```py
from astrbot.core.utils.astrbot_path import get_astrbot_data_path
plugin_data_path = get_astrbot_data_path() / "plugin_data" / self.name # self.name is the plugin name; available in v4.9.2 and above. For lower versions, specify the plugin name yourself.
```
docs/en/dev/star/plugin-new.md
+128
View File
@@ -0,0 +1,128 @@
---
outline: deep
---
# AstrBot Plugin Development Guide 🌠
Welcome to the AstrBot Plugin Development Guide! This section will guide you through developing AstrBot plugins. Before we begin, we hope you have the following foundational knowledge:
1. Some experience with Python programming.
2. Some experience with Git and GitHub.
## Environment Setup
### Obtain the Plugin Template
1. Open the AstrBot plugin template: [helloworld](https://github.com/Soulter/helloworld)
2. Click `Use this template` in the upper right corner
3. Then click `Create new repository`.
4. Fill in your plugin name in the `Repository name` field. Plugin naming conventions:
- Recommended to start with `astrbot_plugin_`;
- Must not contain spaces;
- Keep all letters lowercase;
- Keep it concise.
5. Click `Create repository` in the lower right corner.
### Clone the Project Locally
Clone both the AstrBot main project and the plugin repository you just created to your local machine.
```bash
git clone https://github.com/AstrBotDevs/AstrBot
mkdir -p AstrBot/data/plugins
cd AstrBot/data/plugins
git clone <your-plugin-repository-url>
```
Then, use `VSCode` to open the `AstrBot` project. Navigate to the `data/plugins/<your-plugin-name>` directory.
Update the `metadata.yaml` file with your plugin's metadata information.
> [!WARNING]
> Please make sure to modify this file, as AstrBot relies on the `metadata.yaml` file to recognize plugin metadata.
### Set Plugin Logo (Optional)
You can add a `logo.png` file in the plugin directory as the plugin's logo. Please maintain an aspect ratio of 1:1, with a recommended size of 256x256.
![Plugin logo example](https://files.astrbot.app/docs/source/images/plugin/plugin_logo.png)
### Plugin Display Name (Optional)
You can modify (or add) the `display_name` field in the `metadata.yaml` file to serve as the plugin's display name in scenarios like the plugin marketplace, making it easier for users to read.
### Declare Supported Platforms (Optional)
You can add a `support_platforms` field (`list[str]`) to `metadata.yaml` to declare which platform adapters your plugin supports. The WebUI plugin page will display this field.
```yaml
support_platforms:
- telegram
- discord
```
The values in `support_platforms` must be keys from `ADAPTER_NAME_2_TYPE`. Currently supported:
- `aiocqhttp`
- `qq_official`
- `telegram`
- `wecom`
- `lark`
- `dingtalk`
- `discord`
- `slack`
- `kook`
- `vocechat`
- `weixin_official_account`
- `satori`
- `misskey`
- `line`
### Declare AstrBot Version Range (Optional)
You can add an `astrbot_version` field in `metadata.yaml` to declare the required AstrBot version range for your plugin. The format follows dependency specifiers in `pyproject.toml` (PEP 440), and must not include a `v` prefix.
```yaml
astrbot_version: ">=4.16,<5"
```
Examples:
- `>=4.17.0`
- `>=4.16,<5`
- `~=4.17`
If you only want to declare a minimum version, use:
- `>=4.17.0`
If the current AstrBot version does not satisfy this range, the plugin will be blocked from loading with a compatibility error.
In the WebUI installation flow, you can choose to "Ignore Warning and Install" to bypass this check.
### Debugging Plugins
AstrBot uses a runtime plugin injection mechanism. Therefore, when debugging plugins, you need to start the AstrBot main application.
You can use AstrBot's hot reload feature to streamline the development process.
After modifying the plugin code, you can find your plugin in the AstrBot WebUI's plugin management section, click the `...` button in the upper right corner, and select `Reload Plugin`.
If the plugin fails to load due to code errors or other reasons, you can also click **"Try one-click reload fix"** in the error prompt on the admin panel to reload it.
### Plugin Dependency Management
Currently, AstrBot manages plugin dependencies using pip's built-in `requirements.txt` file. If your plugin requires third-party libraries, please be sure to create a `requirements.txt` file in the plugin directory and list the dependencies used, to prevent Module Not Found errors when users install your plugin.
> For the complete format of `requirements.txt`, please refer to the [pip official documentation](https://pip.pypa.io/en/stable/reference/requirements-file-format/).
## Development Principles
Thank you for contributing to the AstrBot ecosystem. Please follow these principles when developing plugins, which are also good programming practices:
- Features must be tested.
- Include comprehensive comments.
- Store persistent data in the `data` directory, not in the plugin's own directory, to prevent data loss when updating/reinstalling the plugin.
- Implement robust error handling mechanisms; don't let a single error crash the plugin.
- Before committing, please use the [ruff](https://docs.astral.sh/ruff/) tool to format your code.
- Do not use the `requests` library for network requests; use asynchronous network request libraries such as `aiohttp` or `httpx`.
- If you're extending functionality for an existing plugin, please prioritize submitting a PR to that plugin rather than creating a separate one (unless the original plugin author has stopped maintaining it).
docs/en/dev/star/plugin-publish.md
+9
View File
@@ -0,0 +1,9 @@
# Publishing Plugins to the Plugin Marketplace
After completing your plugin development, you can choose to publish it to the AstrBot Plugin Marketplace, allowing more users to benefit from your work.
AstrBot uses GitHub to host plugins, so you'll need to push your plugin code to the GitHub plugin repository you created earlier.
You can submit your plugin by visiting the [AstrBot Plugin Marketplace](https://plugins.astrbot.app). Once on the website, click the `+` button in the bottom-right corner, fill in the basic information, author details, repository information, and other required fields. Then click the `Submit to GITHUB` button. You will be redirected to the AstrBot repository's Issue submission page. Please verify that all information is correct, then click the `Create` button to complete the plugin publication process.
![fill out the form](https://files.astrbot.app/docs/source/images/plugin-publish/image.png)
docs/en/faq.md
+79
View File
@@ -0,0 +1,79 @@
# FAQ
## Dashboard Related
### Encountering 404 Error When Opening the Dashboard
Download `dist.zip` from the [release](https://github.com/AstrBotDevs/AstrBot/releases) page, extract it, and move it to `AstrBot/data`. If it still doesn't work, try restarting your computer (based on community feedback).
### Forgot Dashboard Password
If you forgot your AstrBot dashboard password, you can modify the `"dashboard"` field in the `AstrBot/data/cmd_config.json` configuration file, where `"username"` is your username and `"password"` is your password encrypted with MD5.
To modify your account credentials, follow these steps:
1. Modify the `"username"` field, keeping the `""` quotation marks. If you don't want to change the username, skip this step
2. Visit the website: [Online MD5 Generator](https://www.metools.info/code/c26.html)
3. Enter your new password in the input text box
4. Select MD5 encryption (32-bit), make sure to choose the 32-bit option
5. Paste the converted string into the configuration file, keeping the `""` quotation marks
## Bot Core Related
### How to Let AstrBot Control My Mac / Windows / Linux Computer?
1. In AstrBot WebUI's `Config -> General Config`, find `Use Computer Capabilities`, and select `local` for the runtime environment.
2. In `Config -> Other Config`, find `Admin ID List`, and add your user ID (you can get it through the `/sid` command).
> [!TIP]
> For security reasons, when runtime environment is set to `local`, AstrBot only allows AstrBot administrators to use computer capabilities by default.
> You can select `sandbox` for the runtime environment, which allows all users to use computer capabilities (in an isolated sandbox). For more details, see [AstrBot Sandbox Environment](/en/use/astrbot-agent-sandbox.md)
### Bot Cannot Chat in Group Conversations
1. In group chats, to prevent message flooding, the bot will not respond to every monitored message. Please try mentioning (@) the bot or using a wake word to chat, such as the default `/`, for example: `/hello`.
### No Permission to Execute Admin Commands
1. `/reset, /persona, /dashboard_update, /op, /deop, /wl, /dewl` are the default admin commands. You can use the `/sid` command to get a user's ID, then add it to the admin ID list in Settings -> Other Settings.
### Chinese Characters Garbled When Locally Rendering Markdown Images (t2i)
You can customize the font. See details -> [#957](https://github.com/AstrBotDevs/AstrBot/issues/957#issuecomment-2749981802)
Recommended font: [Maple Mono](https://github.com/subframe7536/maple-font).
### Cannot Parse API Returned Completion & LLM Returns `<empty content>`
This is because the provider's API returned empty text. Try the following steps:
1. Check if the API key is still valid
2. Check if the API call limit or quota has been reached
3. Check network connection
4. Try reset
5. Lower the maximum conversation count setting
6. Switch to another model from the same provider / a different provider
## Plugin Related
### Cannot Install Plugin
1. Plugins are installed via GitHub. Access to GitHub from mainland China can indeed be unstable. You can use a proxy, then go to Other Settings -> HTTP Proxy to configure it. Alternatively, download the plugin archive directly and upload it.
### Error `No module named 'xxx'` After Installing Plugin
![image](https://files.astrbot.app/docs/source/images/faq/image.png)
This is because the plugin's dependencies were not installed properly. Normally, AstrBot automatically installs plugin dependencies after installing the plugin, but installation may fail in the following situations:
1. Network issues preventing dependency downloads
2. Plugin author did not include a `requirements.txt` file
3. Python version incompatibility
Solution:
Based on the error message, refer to the plugin's README to manually install dependencies. You can install dependencies in the AstrBot WebUI under `Console` -> `Install Pip Package`.
![image](https://files.astrbot.app/docs/source/images/faq/image-1.png)
If you find that the plugin author did not include a `requirements.txt` file, please submit an issue in the plugin repository to remind the author to add it.
docs/en/index.md
+31
View File
@@ -0,0 +1,31 @@
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home
hero:
name: >-
<a href="https://trendshift.io/repositories/12875" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12875" alt="Soulter%2FAstrBot | Trendshift" style="width: 250px; height: 55px; margin-bottom: 16px;" width="250" height="55"/></a>
text: "Agentic AI assistant for personal and group chats"
tagline: Connect any IM / 1000+ plugins / General Agent Orchestration
actions:
- theme: brand
text: Quick Start
link: /en/what-is-astrbot
- theme: alt
text: GitHub Repository
link: https://github.com/AstrBotDevs/AstrBot
features:
- icon: ✨
title: Multi-Platform Support
details: Seamlessly supports multiple messaging platforms including QQ, WeCom, Telegram, Discord, and more with multi-instance deployment.
- icon: 😌
title: User-Friendly
details: Easy deployment via Docker or Windows one-click installer with no complex configuration required. Features a highly visual management dashboard.
- icon: 🧩
title: Highly Extensible
details: Built on event bus and pipeline architecture with full modularity. All features can be enabled or disabled, with comprehensive plugin development support.
- icon: 🌟
title: Large Language Models
details: Compatible with multiple model providers including OpenAI, Anthropic, Google, Ollama, Deepseek, and more, supporting diverse LLM integrations.
---
docs/en/ospp/2025.md
+31
View File
@@ -0,0 +1,31 @@
# 开源之夏 2025
**开源之夏**是由中国科学院软件研究所“开源软件供应链点亮计划”发起并长期支持的一项暑期开源活动，旨在鼓励在校学生积极参与开源软件的开发维护，培养和发掘更多优秀的开发者，促进优秀开源软件社区的蓬勃发展，助力开源软件供应链建设。具体活动信息请参考 [开源之夏官网](https://summer-ospp.ac.cn/)。
AstrBot 社区有幸作为开源社区参与了本次活动，下面列出了目前我们已经发布的项目，欢迎感兴趣的同学们参与。
## 插件数据存储逻辑优化
目前，AstrBot 插件系统在数据存储方面缺乏一致的架构。部分插件使用 SharedPreference 存储机制和 JSON 格式进行数据持久化。这种多样化的存储方式导致了存储逻辑的不统一，既影响了数据的安全性，也增加了插件间的兼容性问题。此外，缺乏标准化的接口使得插件的数据存储和访问方式各异，给系统的维护和扩展带来挑战。本项目旨在重构当前存储方案，引入更安全且高效的数据存储机制，并设计一个统一的插件数据接口模型，规范插件的数据存储与访问，提升系统的安全性、可扩展性和可维护性，为未来插件的开发与管理提供坚实基础。
**项目链接**：[插件数据存储逻辑优化](https://summer-ospp.ac.cn/org/prodetail/253550342?lang=zh&list=pro)
**难度**：进阶
**导师**：[Soulter](https://github.com/Soulter)
**期望完成时间**：210 小时
**项目产出要求**：
1. 设计并实现统一且高效的插件数据存储接口模型，规范插件的数据存储；
2. 重构当前 SharedPreference 的存储逻辑，采用更安全的存储方式；
3. 补充相关技术文档。
**项目技术要求**：
1. 熟悉 Python、Javascript 语言及 asyncio 异步编程技术；
2. 熟悉 SQLite 等关系型数据库相关开发；
3. 熟悉 AstrBot 框架及插件开发。
**成果仓库**：[https://github.com/AstrBotDevs/AstrBot](https://github.com/AstrBotDevs/AstrBot)
docs/en/others/self-host-t2i.md
+28
View File
@@ -0,0 +1,28 @@
# Self-host the Text-to-Image Service
AstrBot uses [AstrBotDevs/astrbot-t2i-service](https://github.com/AstrBotDevs/astrbot-t2i-service) as the default text-to-image service. The default service endpoints are:
```plain
https://t2i.soulter.top/text2img
https://t2i.rcfortress.site/text2img
```
This interface can ensure normal response for most of the time. However, due to the deployment of servers in New York, the response speed may be slower in some areas.
> [!TIP]
> If you'd like to support us to help pay for server costs, please consider supporting us on [Afdian](https://afdian.com/a/astrbot_team).
You can choose to self-host the text-to-image service to improve response speed.
```bash
docker run -itd -p 8999:8999 soulter/astrbot-t2i-service:latest
```
After deployment, go to AstrBot Dashboard -> Config -> System, and change `Text-to-Image Service API Endpoint` to the URL you deployed (as shown below).
> If you deployed AstrBot using the Docker tutorial in this documentation, the URL should be `http://<t2i-service-container-name>:8999`.
> If you deployed on the same machine as AstrBot, the URL should be `http://localhost:8999`.
<img width="589" height="255" alt="image" src="https://github.com/user-attachments/assets/5ef09db2-1a33-440c-9986-c7b544325e34" />
docs/en/platform/aiocqhttp/lagrange.md
+55
View File
@@ -0,0 +1,55 @@
# Connect to Lagrange
> [!TIP]
> - Please control message frequency responsibly. Sending messages too frequently may trigger risk control.
> - This project must not be used for illegal purposes.
> - For the latest deployment steps, always refer to the official [Lagrange Docs](https://lagrangedev.github.io/Lagrange.Doc/Lagrange.OneBot/Config/#%E4%B8%8B%E8%BD%BD%E5%AE%89%E8%A3%85).
## Download
Download the latest `Lagrange.OneBot` from [GitHub Releases](https://github.com/LagrangeDev/Lagrange.Core/releases).
- Windows: `Lagrange.OneBot_win-x64_xxxx`
- Linux x86_64: `Lagrange.OneBot_linux-x64_xxx`
- Linux ARM64: `Lagrange.OneBot_linux-arm64_xxx`
- macOS Apple Silicon: `Lagrange.OneBot_osx-arm64_xxx`
- macOS Intel: `Lagrange.OneBot_osx-x64_xxx`
## Deploy
Follow the official docs:
- Run guide: <https://lagrangedev.github.io/Lagrange.Doc/Lagrange.OneBot/Config/#%E8%BF%90%E8%A1%8C>
- Config file guide: <https://lagrangedev.github.io/Lagrange.Doc/Lagrange.OneBot/Config/#%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6>
In your config file, add this under `Implementations`:
```json
{
"Type": "ReverseWebSocket",
"Host": "127.0.0.1",
"Port": 6199,
"Suffix": "/ws",
"ReconnectInterval": 5000,
"HeartBeatInterval": 5000,
"AccessToken": ""
}
```
Make sure `Suffix` is exactly `/ws`.
## Connect to AstrBot
### Configure `aiocqhttp` Adapter
1. Open AstrBot Dashboard.
2. Click `Bots` in the left sidebar.
3. Click `+ Create Bot`.
4. Select `aiocqhttp (OneBot v11)`.
Fill in:
- ID (`id`): any unique identifier.
- Enable (`enable`): checked.
- Reverse WebSocket host: your machine IP (usually `0.0.0.0`).
- Reverse WebSocket port: an available port, for example `6199`.
docs/en/platform/aiocqhttp/napcat.md
+141
View File
@@ -0,0 +1,141 @@
# Using NapCat
> [!TIP]
>
> - Please control usage frequency appropriately. Sending messages too frequently may be identified as abnormal behavior, increasing the risk of triggering risk control mechanisms.
> - This project is strictly prohibited from being used for any purpose that violates laws and regulations. If you intend to use AstrBot for illegal industries or activities, we **explicitly oppose and refuse** your use of this project.
> - AstrBot connects to the OneBot v11 protocol through the `aiocqhttp` adapter. OneBot v11 protocol is an open communication protocol and does not represent any specific software or service.
NapCat's GitHub Repository: [NapCat](https://github.com/NapNeko/NapCatQQ)
NapCat's Documentation: [NapCat Documentation](https://napcat.napneko.icu/)
NapCat provides multiple deployment methods, including Docker, Windows one-click installation packages, and more.
## Deploy via One-Click Script
This deployment method is recommended.
### Windows
Refer to this article: [NapCat.Shell - Windows Manual Start Tutorial](https://napneko.github.io/guide/boot/Shell#napcat-shell-win%E6%89%8B%E5%8A%A8%E5%90%AF%E5%8A%A8%E6%95%99%E7%A8%8B)
### Linux
Refer to this article: [NapCat.Installer - Linux One-Click Script (Supports Ubuntu 20+/Debian 10+/Centos9)](https://napneko.github.io/guide/boot/Shell#napcat-installer-linux%E4%B8%80%E9%94%AE%E4%BD%BF%E7%94%A8%E8%84%9A%E6%9C%AC-%E6%94%AF%E6%8C%81ubuntu-20-debian-10-centos9)
> [!TIP]
> **Where to open Napcat WebUI**:
> The WebUI link will be displayed in napcat's logs.
>
> If napcat is deployed via Linux command line one-click deployment: `docker log <account>`.
>
> For Docker-deployed NapCat: `docker logs napcat`.
## Deploy via Docker Compose
> [!TIP]
> If deploying with Docker Compose, no configuration is needed on the NapCat side. Just log in via NapCat WebUI (running on port 6099) or `docker logs napcat`, enable the aiocqhttp adapter on the AstrBot side to connect, and you can directly implement normal receiving and sending of `voice data` and `file data`.
1. Download or copy the content of [astrbot.yml](https://github.com/NapNeko/NapCat-Docker/blob/main/compose/astrbot.yml)
2. Rename the downloaded file to `astrbot.yml`
3. Modify `astrbot.yml`, change `#- "6199:6199` to `- "6199:6199"`, remove the flag of "#"
4. Execute in the directory where the `astrbot.yml` file is located:
```bash
NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker compose -f ./astrbot.yml up -d
```
## Deploy via Docker
> [!TIP]
> If deploying with Docker, you will not be able to properly receive `voice data` and `file data`. This means voice-to-text and sandbox file input functions will not be available. You can receive text messages, image messages, and other types of messages.
This tutorial assumes you have Docker installed.
Execute the following command in the terminal for one-click deployment.
```bash
docker run -d \
-e NAPCAT_GID=$(id -g) \
-e NAPCAT_UID=$(id -u) \
-p 3000:3000 \
-p 3001:3001 \
-p 6099:6099 \
--name napcat \
--restart=always \
mlikiowa/napcat-docker:latest
```
After successful execution, you need to check the logs to get the login QR code and the management panel URL.
```bash
docker logs napcat
```
Please copy the management panel URL and open it in your browser.
Then use the account you want to log in with to scan the QR code that appears.
If there are no issues during the login stage, deployment is successful.
## Connect to AstrBot
## Configure aiocqhttp in AstrBot
1. Enter AstrBot's management panel
2. Click `Bots` in the left sidebar
3. Then in the interface on the right, click `+ Create Bot`
4. Select `OneBot v11`
Fill in the configuration items that appear:
- ID(id): Fill in arbitrarily, only used to distinguish different messaging platform instances.
- Enable: Check this.
- Reverse WebSocket Host Address: Please fill in your machine's IP address, generally fill in `0.0.0.0` directly
- Reverse WebSocket Port: Fill in a port, default is `6199`.
- Reverse Websocket Token: Only needs to be filled when a token is configured in NapCat's network settings.
Example image: (At the fastest, just check Enable, then save)
<img width="818" height="799" alt="xinjianya" src="https://github.com/user-attachments/assets/813ac338-2fd7-4add-bde4-8b0f6d0bda95" />
Click `Save`.
### Configure Administrator
After filling in, go to the `Configuration File` page, click the `Platform Configuration` tab, find `Administrator ID`, and fill in your account number (not the bot's account number).
Remember to click `Save` in the lower right corner, AstrBot will restart and apply the configuration.
### Add WebSocket Client in NapCat
Switch back to NapCat's management panel, click `Network Configuration->New->WebSockets Client`.
<img width="649" height="751" alt="jiaochenXJY" src="https://github.com/user-attachments/assets/5044f96a-a81f-407a-a3b1-0c518499eda4" />
In the newly opened window:
- Check `Enable`.
- Fill in `URL` with `ws://HostIP:Port/ws`. For example, `ws://localhost:6199/ws` or `ws://127.0.0.1:6199/ws`.
> [!IMPORTANT]
> 1. If deploying with Docker and both AstrBot and NapCat containers are connected to the same network, use `ws://astrbot:6199/ws` (refer to the Docker script in this documentation).
> 2. Due to Docker network isolation, when not on the same network, please use the internal network IP address or public network IP address ***(unsafe)*** to connect, i.e., `ws://(internal/public IP):6199/ws`.
- Message Format: `Array`
- Heartbeat Interval: `5000`
- Reconnection Interval: `5000`
> [!WARNING]
>
> 1. Remember to add `/ws` at the end!
> 2. The IP here cannot be `0.0.0.0`
Click `Save`.
Go to AstrBot WebUI `Console`, if you see the blue log ` aiocqhttp(OneBot v11) adapter connected.`, it means the connection is successful. If not, and after several seconds ` aiocqhttp adapter has been closed` appears, it indicates connection timeout (failed), please check if the configuration is correct.
## 🎉 All Done
At this point, your AstrBot and NapCat should be successfully connected! Use `private message` to send `/help` to the bot to check if the connection is successful.
docs/en/platform/aiocqhttp/others.md
+1
View File
@@ -0,0 +1 @@
AstrBot can connect to any bot protocol client that supports OneBot v11 reverse WebSocket (AstrBot acts as the server side).
docs/en/platform/dingtalk.md
+65
View File
@@ -0,0 +1,65 @@
# Connect to DingTalk
## Supported Basic Message Types
> Version v4.15.0.
| Message Type | Receive | Send | Notes |
| --- | --- | --- | --- |
| Text | Yes | Yes | |
| Image | Yes | Yes | |
| Voice | No | Yes | |
| Video | No | Yes | |
| File | No | Yes | |
Proactive message push: Supported.
## Create and Configure the App
Go to the [DingTalk Open Platform](https://open-dev.dingtalk.com/fe/app), then create an app:
![image](https://files.astrbot.app/docs/source/images/dingtalk/image-4.png)
After creation, add app capability and choose Bot:
![image](https://files.astrbot.app/docs/source/images/dingtalk/image-5.png)
Open Bot settings and fill in bot information:
![image](https://files.astrbot.app/docs/source/images/dingtalk/image-7.png)
After confirming all settings, click Publish.
Go to Credentials & Basic Information, then copy `ClientID` and `ClientSecret`.
## Connect in AstrBot
Open AstrBot Dashboard -> `Bots` -> `+ Create Bot`, then create a DingTalk adapter.
Fill in `ClientID` and `ClientSecret`, then click Save. AstrBot will request authorization from DingTalk Open Platform automatically.
Back in DingTalk Open Platform, open Event Subscriptions, select `Stream mode push`, and click Save. If successful, you will see a connected status.
![image](https://files.astrbot.app/docs/source/images/dingtalk/image-8.png)
Save the configuration.
## Publish a Version
In the left sidebar, open Version Management and Release, then create a new version.
Fill in version number, description, and visibility scope (all employees or as needed), then save and publish.
![alt text](https://files.astrbot.app/docs/source/images/dingtalk/image-11.png)
Open a DingTalk group chat and click the top-right settings:
![image](https://files.astrbot.app/docs/source/images/dingtalk/image-12.png)
Scroll down to Add Bot, select the bot you just created, and add it:
![image](https://files.astrbot.app/docs/source/images/dingtalk/image-9.png)
## Done
In a group chat, mention the bot and send `/help`. If the bot replies, the integration is successful.
docs/en/platform/discord.md
+74
View File
@@ -0,0 +1,74 @@
# Connecting to Discord
## Create AstrBot Discord Platform Adapter
Navigate to the messaging platform, click to add a new adapter, find Discord and click to enter the Discord configuration page.
![Click to create bot, select discord type](https://files.astrbot.app/docs/source/images/discord/image.png)
![Options from top to bottom: 1. Bot name 2. Enable 3. Bot token 4. Discord proxy address 5. Auto-register plugin commands as Discord slash commands 6. discord_guild_id_for_debug 7. Discord activity name](https://files.astrbot.app/docs/source/images/discord/image-3.png)
> For this tutorial, you only need to configure items 1, 2, 3, and 5
- Bot Name: Customize this to easily distinguish between different adapters
- Enable: Check to enable this adapter
- Bot Token: Token obtained after creating an App in Discord (see below)
- Discord Proxy Address: If you need to use a proxy to access Discord, you can enter the proxy address here (optional)
- Auto-register Plugin Commands as Discord Slash Commands: When checked, AstrBot will automatically register commands from installed plugins as Discord slash commands for user convenience.
## Create an App in Discord
1. Go to [Discord Developer Portal](https://discord.com/developers/applications), click the blue button in the top right corner, enter an application name, and create the application.
![Create bot (enter name)](https://files.astrbot.app/docs/source/images/discord/image-1.png)
2. Click on Bot in the left sidebar, click the Reset Token button. After the token is created, click the Copy button and paste the token into the Discord Bot Token field in the configuration.
![Token options](https://files.astrbot.app/docs/source/images/discord/image-4.png)
3. Scroll down and enable all three of these options:
![Presence Intent, Server Members Intent, Message Content Intent screenshot](https://files.astrbot.app/docs/source/images/discord/image-2.png)
- Presence Intent: Allows the bot to access user online status
- Server Members Intent: Allows the bot to access server member information
- Message Content Intent: Allows the bot to read message content
4. Click OAuth2 in the left sidebar, and in the OAuth2 URL Generator, select `Bot`
Like this:
![OAuth2 URL Generator](https://files.astrbot.app/docs/source/images/discord/image-6.png)
Then in the Bot Permissions section that appears below, select the allowed permissions. Generally, it's recommended to add the following permissions:
- Send Messages
- Create Public Threads
- Create Private Threads
- Send TTS Messages
- Manage Messages
- Manage Threads
- Embed Links
- Attach Files
- Read Message History
- Add Reactions
If you find this tedious, you can directly use administrator permissions, but it's still recommended to use the permissions configured above (or the permissions you specifically need) in your production environment.
> Remember, the higher the permissions, the greater the risk.
5. Copy the Generated URL that appears below. Open this URL to add the bot to your desired server.
![Generated URL location](https://files.astrbot.app/docs/source/images/discord/image-5.png)
6. Enter your Discord server, your bot should now show as online
![Bot online](https://files.astrbot.app/docs/source/images/discord/image-7.png)
@ mention the bot you just created (or don't mention it), type `/help`. If it responds successfully, the test is successful.
## Pre-acknowledgment Emoji
Discord supports the pre-acknowledgment emoji feature. When enabled, the bot will add an emoji reaction when processing a message, letting users know the bot is working on their request.
In the admin panel's "Configuration" page, find `Platform Specific -> Discord -> Pre-acknowledgment Emoji`:
- **Enable Pre-acknowledgment Emoji**: When enabled, the bot will automatically add an emoji reaction upon receiving a message
- **Emoji List**: Enter Unicode emoji symbols, e.g., 👍, 🤔, ⏳. You can add multiple emojis, and the bot will randomly select one to use
# Troubleshooting
- If you're stuck at the final step and the bot is not online, please ensure your server can directly connect to Discord
If you have any questions, please [submit an Issue](https://github.com/AstrBotDevs/AstrBot/issues).
docs/en/platform/kook.md
+46
View File
@@ -0,0 +1,46 @@
# Connect to KOOK
## Supported Message Types
> Version v4.19.2
| Message Type | Receive | Send | Remarks |
| ------------ | ------- | ---- | -------------------------------------------------- |
| Text | Yes | Yes | Supports official [kmarkdown] syntax |
| Image | Yes | Yes | Supports external links; `jpeg`, `gif`, `png` only |
| Audio | Yes | Yes | Supports external links |
| Video | Yes | Yes | Supports external links; `mp4`, `mov` only |
| File | Yes | Yes | Supports external links |
| Card (JSON) | Yes | Yes | See [Kook Docs - Card Messages] |
Proactive message push: Supported
Message receiving mode: WebSocket
## Create a Bot on Kook
1. Go to the [Kook Developer Center] and follow these steps:
2. Log in and complete identity verification.
3. Click "Create Application" and customize your Bot's nickname.
4. Enter the application dashboard, select the **Bot** module, and enable **WebSocket connection mode**. Make sure to save the generated **Token**, as you will need it for the subsequent AstrBot configuration.
5. Under the "Bot" page in the left sidebar, click "Invite Link" and set the role permissions (full permissions are recommended to ensure all features work).
6. Copy the invite link, open it in your browser, and add the bot to your desired server.
![image](https://files.astrbot.app/docs/source/images/kook/image-1.png)
## Configure in AstrBot
1. Access the AstrBot management panel.
2. Click **Bots** in the left sidebar.
3. Click `+ Create Bot` on the right side of the interface.
4. Select the `kook` adapter.
5. Fill in the configuration fields:
- ID (id): Any name to identify this specific instance.
- Enable (enable): Check the box.
- Bot Token: Paste the Token generated from the [Kook Developer Center].
6. Click `Save` after filling in the details.
7. Finally, in a Kook server channel (create one first if you haven't), @ the bot and type `/sid`. If the bot responds, the configuration is successful.
[Kook Developer Center]: https://developer.kookapp.cn/app
[kmarkdown]: https://developer.kookapp.cn/doc/kmarkdown
[Kook Docs - Card Messages]: https://developer.kookapp.cn/doc/cardmessage
docs/en/platform/lark.md
+115
View File
@@ -0,0 +1,115 @@
# Connecting to Lark
## Supported Message Types
> Version v4.15.0.
| Message Type | Receive Support | Send Support | Notes |
| --- | --- | --- | --- |
| Text | Yes | Yes | |
| Image | Yes | Yes | |
| Voice | No | Yes | |
| Video | No | Yes | |
| File | No | Yes | |
Proactive message push: Supported.
## Creating a Bot
Navigate to the [Developer Console](https://open.feishu.cn/app) and create a custom enterprise application.
![Create Custom Enterprise Application](https://files.astrbot.app/docs/source/images/lark/image.png)
Add the Bot capability to your application.
![Add Bot Capability](https://files.astrbot.app/docs/source/images/lark/image-1.png)
Click on "Credentials & Basic Info" to obtain your app_id and app_secret.
![Get app_id and app_secret](https://files.astrbot.app/docs/source/images/lark/image-4.png)
## Configuring AstrBot
1. Access the AstrBot management panel
2. Click on `Bots` in the left sidebar
3. In the right panel, click `+ Create Bot`
4. Select `lark`
Fill in the configuration fields as follows:
- ID: Choose any identifier to distinguish between different messaging platform instances
- Enable: Check this option
- app_id: The app_id you obtained earlier
- app_secret: The app_secret you obtained earlier
- Bot name: Your Lark bot's name
For the domain field, if you're using Lark China, keep the default value. If you're using Lark International, set it to `https://open.larksuite.com`. If you're using a self-hosted enterprise Lark instance, enter your Lark instance's domain.
For the subscription method, `socket` uses a long connection subscription approach, while `webhook` sends events to your developer server and requires a public server. Generally, `socket` is recommended. However, if you're using Lark International or a self-hosted Lark instance, choose `webhook`. The subsequent configuration steps will differ accordingly.
If you selected the `webhook` method, navigate to the Lark Developer Console, click on "Events & Callbacks," then "Encryption Policy," and fill in the Encrypt Key. While not mandatory, AstrBot takes your data security seriously, so we strongly recommend setting this up. After filling it in, copy the `Encrypt Key` and `Verification Token` to the corresponding `encrypt_key` and `verification_token` fields in AstrBot's configuration.
Click `Save`.
## Setting up Callbacks and Permissions
The following steps vary depending on the subscription method you selected above. Please proceed to the corresponding section based on your choice.
### `socket` Long Connection Method
Next, click on "Events & Callbacks," select "Receive events using long connection," and click Save. **If the previous step didn't start successfully, you won't be able to save here.**
![Configure Events & Callbacks](https://files.astrbot.app/docs/source/images/lark/image-6.png)
### `webhook` Send Events to Developer Server Method
> [!TIP]
> To make better use of this method, please refer to [Unified Webhook Mode](/en/use/unified-webhook.md#how-to-use-unified-webhook-mode) for the necessary configuration.
After clicking `Save`, the bot card will display "View Webhook URL." Click to view and copy the callback URL.
![](https://files.astrbot.app/docs/source/images/lark/webhook.png)
Next, return to Lark's Events & Callbacks page, click "Event Configuration," select "Send events to developer server," enter the callback URL you just copied as the "Request URL," and click Save. If everything is correct, no errors will appear.
### Setting up Events
After completing the event configuration in the previous step, click "Add Event," navigate to "Messages & Groups," scroll down to find `Receive Message`, and add it.
![Add Event](https://files.astrbot.app/docs/source/images/lark/image-7.png)
Click to enable the following permissions.
![Enable Permissions](https://files.astrbot.app/docs/source/images/lark/image-8.png)
Then click the `Save` button at the top.
Next, click on "Permission Management," click "Enable Permissions," and enter `im:message:send,im:message,im:message:send_as_bot`. Add the filtered permissions.
Enter `im:resource:upload,im:resource` again to enable image upload permissions.
The final set of permissions should look like this:
![Final Permissions](https://files.astrbot.app/docs/source/images/lark/image-11.png)
## Creating a Version
Create a new version.
![Create Version](https://files.astrbot.app/docs/source/images/lark/image-2.png)
Fill in the version number, update notes, and visibility scope, then click Save and confirm the release.
## Adding the Bot to a Group
Open the Lark app (the web version doesn't support adding bots), enter a group chat, click the button in the upper right corner → Group Bots → Add Bot.
Search for the bot you just created. For example, if you created the `AstrBot` bot as shown in this tutorial:
![Add Bot](https://files.astrbot.app/docs/source/images/lark/image-9.png)
## 🎉 All Done!
Send a `/help` command in the group, and the bot will respond.
![Success](https://files.astrbot.app/docs/source/images/lark/image-13.png)
docs/en/platform/line.md
+79
View File
@@ -0,0 +1,79 @@
# Connecting to LINE
## Supported Message Types
> Version v4.17.0.
| Message Type | Receive Support | Send Support | Notes |
| --- | --- | --- | --- |
| Text | Yes | Yes | |
| Image | Yes | Yes | |
| Voice | Yes | Yes | |
| Video | Yes | Yes | |
| File | Yes | Yes | |
| Sticker | Yes | No | |
Proactive message push: Supported.
## Create a LINE Messaging API Channel
1. Open the [LINE Developers Console](https://developers.line.biz/console/)
2. Create or select a Provider
3. Create a `Messaging API` channel (not a `LINE Login` channel)
4. Complete bot initialization on the `Messaging API` page
## Get Credentials
You need the following values:
- `channel_secret`
- `channel_access_token`
How to get them:
1. Open your channel settings page
2. Get `Channel secret` from `Basic settings`
3. Issue a `Channel access token` on the `Messaging API` page
![](https://files.astrbot.app/docs/source/images/line/7ecee0a9102f191245330f8408eb0493.png)
## Configure AstrBot
1. Open the AstrBot admin panel
2. Click `Bots` in the left sidebar
3. Click `+ Create Bot`
4. Select `line`
Fill in these fields:
- `ID`: Custom identifier to distinguish instances
- `Enable`: Checked
- `LINE Channel Access Token`: your `channel_access_token`
- `LINE Channel Secret`: your `channel_secret`
- `LINE Bot User ID`: optional; if empty, AstrBot uses webhook `destination`
Click Save.
## Configure Callback URL (Unified Webhook)
The LINE adapter supports **unified webhook mode only**.
After saving, click `View Webhook URL` on the bot card and copy the URL.
Then in LINE Developers Console:
1. Open `Messaging API`
2. Paste the URL into `Webhook settings` -> `Webhook URL`
3. Click `Verify`
4. Enable `Use webhook`
> [!TIP]
> If AstrBot is not publicly reachable, set up a public domain and reverse proxy first so LINE can access your webhook URL.
## Test
1. Add your Official Account as a friend in LINE
2. Send a message to the bot (for example, `hi`)
3. If the bot replies, setup is successful
If you want to use it in a group, invite the Official Account to the group first.
docs/en/platform/matrix.md
+20
View File
@@ -0,0 +1,20 @@
# Connecting to Matrix
> [!TIP]
> This platform adapter is maintained by the community ([stevessr](https://github.com/stevessr)). If you find it helpful, please support the developer by giving the repository a Star. ❤️
## Installing the astrbot_plugin_matrix_adapter Plugin
Go to the AstrBot WebUI plugin marketplace, search for `astrbot_plugin_matrix_adapter`, and click Install.
After installation, navigate to Messaging Platforms → Add Adapter → Select Matrix (if the option is missing, try restarting AstrBot or check the plugin installation status).
Click `Enable` in the configuration dialog that appears.
## Configuration
Please refer to the repository's [README.md](https://github.com/stevessr/astrbot_plugin_matrix_adapter?tab=readme-ov-file#astrbot-matrix-adapter-%E6%8F%92%E4%BB%B6) for configuration instructions.
## Issue Reporting
If you have any questions, please submit an issue to the [plugin repository](https://github.com/stevessr/astrbot_plugin_matrix_adapter/issues).
docs/en/platform/misskey.md
+113
View File
@@ -0,0 +1,113 @@
# Connecting to Misskey Platform
> [!WARNING]
>
> 1. We recommend that before deploying a bot on a Misskey instance you don't manage, you should review the instance rules or seek approval from the instance administration or moderation team, and enable the `Bot` identifier for the bot account after deployment.
> 2. This project is strictly prohibited from being used for any illegal purposes. If you intend to use AstrBot for illegal industries or activities, we explicitly oppose and refuse your use of this project.
## Create AstrBot Misskey Platform Adapter
Navigate to the messaging platform, click to add a new adapter, find Misskey and click to enter the Misskey configuration page.
![Create Misskey Platform Adapter](https://files.astrbot.app/docs/source/images/misskey/create.png)
## Configure Platform Adapter Settings
On the AstrBot Misskey platform adapter configuration page, we need to fill in the Misskey connection information and configure some adapter behaviors.
::: tip Note
Don't forget to click `Enable` before saving to activate the Misskey platform adapter!
:::
How to obtain the Misskey connection information is described below.
![Misskey Platform Adapter Configuration](https://files.astrbot.app/docs/source/images/misskey/config.png)
## Misskey Instance URL
This is the frontend address of the Misskey instance where your bot account is located, in standard domain format. For example, `https://misskey.example`.
## Obtain Bot Account Access Token
1. First, open the Misskey Web frontend page, find and open the `Settings > Connected Services` page in the frontend sidebar.
![Open Misskey Connected Services Page](https://files.astrbot.app/docs/source/images/misskey/pat-1.png)
2. Click "Generate Access Token" to generate an account access token.
![Generate Misskey Account Token](https://files.astrbot.app/docs/source/images/misskey/pat-2.png)
3. On the access token configuration page that appears, give the token a name, such as `AstrBot`.
4. Then we need to configure the relevant permissions for the token to allow the bot to interact with the Misskey instance.
::: tip Note
If third-party AstrBot plugins you use require additional permissions, please refer to their documentation to add the corresponding permissions. If you fully trust the bot's deployment environment, you can temporarily enable all permissions to simplify debugging, but we still recommend limiting the bot's permissions in production environments.
:::
![Configure Access Token Permissions](https://files.astrbot.app/docs/source/images/misskey/pat-3.png)
**Permissions Required by Default**
| Permission Name | Description | Purpose |
|---|---:|---|
| Read account information | View basic account information | Obtain bot's own user information and account ID |
| Compose or delete posts | Create, edit, and delete note content | Send message replies and publish content |
| Compose or delete messages | Create, edit, and delete direct messages | Handle direct message conversations |
| View notifications | Receive system notifications and reminders | Obtain mention, reply, and other notification information |
| View messages | Read direct messages and chat history | Receive and process user direct messages |
| View reactions | View replies and reactions to posts | Handle user responses to bot messages |
5. After completing the permission configuration, click "Done" to view the account access token. Copy the obtained token and paste it into the Access Token input box on the AstrBot configuration page.
![View Account Token](https://files.astrbot.app/docs/source/images/misskey/pat-4.png)
## Default Post Visibility
Modify the default visibility when the bot posts
| Name | Description |
|---|---|
| public | Anyone can see the bot's posts |
| home | Publish bot posts to the instance home timeline |
| followers | Only users who follow the bot account can see bot posts in the home timeline |
## Local Only (Do Not Federate)
When enabled, all posts sent by the bot will not participate in Fediverse federation. This is very suitable for scenarios where you only want to use and distribute the bot's posts within your own instance.
## Enable Chat Message Response
::: tip Note
Misskey's "Chat" component feature is not supported by all Misskey Fork versions! It cannot federate across instances.
Misskey added "Chat" component support in `v2025.4.0` and later versions, and it is only supported by its web frontend, not well-supported by third-party apps.
:::
Enabled by default. When enabled, the bot will respond to private chat messages sent by users in Misskey chat.
## History Records
Conversation history for individual users in chat and posts will be recorded in the AstrBot WebUI console "Conversation History" with the ID `chat:UserID`, while traditional posts will be recorded with the ID `note:UserID`.
::: tip Where is the Misskey user's UserID?
It can be found on the user's personal page in the `Raw` section. UserID is the unique key identifier for Misskey users within a single instance.
:::
![UserID](https://files.astrbot.app/docs/source/images/misskey/userid.png)
## Test the Connection
After completing the configuration and enabling it, go to Misskey to create a new post and mention the bot (@mention) to test. If the bot account successfully triggers a reply, the configuration is successful.
![Demo Example](https://files.astrbot.app/docs/source/images/misskey/demo.png)
## Additional Notes
We recommend enabling the Misskey `Bot` identifier for bot accounts to respect the relevant regulations and rate limits of various Misskey instances, which can also effectively help Misskey instance administrators manage and identify bot usage.
**How to Enable**
Enable "This is a bot account" in the advanced settings of the bot account's profile page.
![This is a bot account](https://files.astrbot.app/docs/source/images/misskey/botset.png)
docs/en/platform/qqofficial.md
+8
View File
@@ -0,0 +1,8 @@
# Connect QQ Official Bot
QQ Official Bot is Tencent's official bot platform. It lets you connect bots to QQ group chats and private chats through official APIs.
Currently, the main integration method is Webhook.
- [Webhook Method](/en/platform/qqofficial/webhook)
- [Websockets Method](/en/platform/qqofficial/websockets)
docs/en/platform/qqofficial/webhook.md
+93
View File
@@ -0,0 +1,93 @@
# Connect QQ via QQ Official Bot (Webhook)
> [!WARNING]
> 1. QQ Official Bot currently requires an IP whitelist.
> 2. It supports group chat, private chat, channel chat, and channel private chat.
> 3. You need a server with a public IP and a domain.
## Supported Basic Message Types
> Version v4.15.0.
| Message Type | Receive | Send | Notes |
| --- | --- | --- | --- |
| Text | Yes | Yes | |
| Image | Yes | Yes | |
| Voice | No | No | |
| Video | No | No | |
| File | No | No | |
Proactive message push: Not supported.
## Apply for a Bot
Open [QQ Official Bot](https://q.qq.com) and sign in.
Create a bot, fill in name/description/avatar, then submit for review. After security verification passes, creation is complete.
Open the created bot to enter its management page:
![image](https://files.astrbot.app/docs/source/images/qqofficial/image.png)
## Allow Bot in Channel / Group / Private Chat
Open `Sandbox Configuration` to set a sandbox channel / QQ group / QQ private chat (up to 20 members).
Then configure QQ groups, private chat QQ accounts, and QQ channels as needed.
![image](https://files.astrbot.app/docs/source/images/qqofficial/image-1.png)
## Get `appid` and `secret`
After adding the bot where you need it, open `Development -> Development Settings`, then copy `appid` and `secret`.
## Add IP Whitelist
Open `Development -> Development Settings`, find IP whitelist, and add your server IP.
![image](https://files.astrbot.app/docs/source/images/qqofficial/image-3.png)
## Configure in AstrBot
1. Open AstrBot Dashboard.
2. Click `Bots` in the left sidebar.
3. Click `+ Create Bot`.
4. Select `qq_official_webhook`.
Fill in:
- ID (`id`): any unique identifier.
- Enable (`enable`): checked.
- `appid`: from QQ Official Bot platform.
- `secret`: from QQ Official Bot platform.
Click `Save`.
## Configure Callback URL
In `Development -> Callback Configuration`, configure callback URL.
Set request URL to `<your-domain>/astrbot-qo-webhook/callback`.
Your domain should reverse-proxy traffic to AstrBot port `6196` using `Caddy`, `Nginx`, or `Apache`.
Then add callback events and select all four event categories (private, group, channel, etc.).
![image](https://files.astrbot.app/docs/source/images/webhook/image.png)
After entering values, move focus out of the input box to trigger validation. If validation passes, the confirm button on the right becomes clickable.
Then restart AstrBot.
## Done
AstrBot should now be connected. If messages do not respond immediately, wait 1-2 minutes, restart AstrBot, and test again.
## Appendix: Reverse Proxy Setup
If you are new to reverse proxy, Caddy is recommended:
1. Install Caddy: <https://caddy2.dengxiaolong.com/docs/install>
2. Configure reverse proxy: <https://caddy2.dengxiaolong.com/docs/quick-starts/reverse-proxy>
Caddy can automatically apply TLS certificates for Webhook access.
docs/en/platform/qqofficial/websockets.md
+87
View File
@@ -0,0 +1,87 @@
# Connect QQ via QQ Official Bot (Websockets)
## Supported Basic Message Types
> Version v4.15.0.
| Message Type | Receive | Send | Notes |
| --- | --- | --- | --- |
| Text | Yes | Yes | |
| Image | Yes | Yes | |
| Voice | No | No | |
| Video | No | No | |
| File | No | No | |
Proactive message push: Not supported.
## Quick Deployment Steps
> Updated: `2026/03/06`. This method only supports `private chat`.
1. Open [QQ Open Platform](https://q.qq.com/qqbot/openclaw/). Register an account if you don't have one.
2. Click the `Create Bot` button on the right.
3. Obtain your `AppID` and `AppSecret`.
4. In AstrBot WebUI, click `Bots` in the left sidebar, then click `+ Create Bot`, select `QQ Official Bot (WebSocket)`, paste the `AppID` and `AppSecret` into the form, click `Enable`, then click `Save`.
5. Back on the QQ Open Platform page, click `Scan QR Code to Chat` next to your bot, then scan with your mobile QQ to start chatting.
To use the bot in group chats, refer to the `Allow Bot in Channel / Group / Private Chat` section below.
---
## Apply for a Bot
> [!WARNING]
> 1. QQ Official Bot currently requires an IP whitelist.
> 2. It supports group chat, private chat, channel chat, and channel private chat.
> 3. Tencent is phasing out Websockets access, so this method is no longer recommended. Please use [Webhook](/en/platform/qqofficial/webhook) instead.
Open [QQ Official Bot](https://q.qq.com) and sign in.
Create a bot, fill in name/description/avatar, then submit for review. After security verification passes, creation is complete.
Open the created bot to enter its management page:
![image](https://files.astrbot.app/docs/source/images/qqofficial/image.png)
## Allow Bot in Channel / Group / Private Chat
Open `Sandbox Configuration` to set a sandbox channel / QQ group / QQ private chat (up to 20 members).
Then configure QQ groups, private chat QQ accounts, and QQ channels as needed.
![image](https://files.astrbot.app/docs/source/images/qqofficial/image-1.png)
## Get `appid` and `secret`
After adding the bot where you need it, open `Development -> Development Settings`, then copy `appid` and `secret`.
## Add IP Whitelist
Open `Development -> Development Settings`, find IP whitelist, and add your server IP.
![image](https://files.astrbot.app/docs/source/images/qqofficial/image-3.png)
> [!TIP]
> If you do not know your server IP, run `curl ifconfig.me` or check [ip138.com](https://ip138.com/).
>
> In NAT environments without a public IP, the observed IP may change depending on your carrier. Use proxy/tunnel if needed.
## Configure in AstrBot
1. Open AstrBot Dashboard.
2. Click `Bots` in the left sidebar.
3. Click `+ Create Bot`.
4. Select `qq_official`.
Fill in:
- ID (`id`): any unique identifier.
- Enable (`enable`): checked.
- `appid`: from QQ Official Bot platform.
- `secret`: from QQ Official Bot platform.
Click `Save`.
## Done
AstrBot should now be connected. Send `/help` to the bot in QQ private chat to verify.
docs/en/platform/satori/llonebot.md
+73
View File
@@ -0,0 +1,73 @@
# Connect LLTwoBot (Satori)
> [!TIP]
> LLTwoBot is a multi-protocol implementation based on QQNT (OneBot v11 + Satori), allowing AstrBot to communicate with QQ via Satori.
> [!TIP]
> - Please control message frequency responsibly.
> - This project must not be used for illegal purposes.
## Preparation
First complete basic setup using official LLTwoBot documentation:
[LLTwoBot Docs](https://llonebot.com/guide/getting-started)
Make sure you have:
1. Installed LLTwoBot.
2. Logged into a QQ account successfully.
## Configure Satori in LLTwoBot
After QQ login succeeds, open LLTwoBot WebUI:
> Default WebUI URL: <http://localhost:3080/>
In the WebUI sidebar, open the `Satori` tab and configure:
1. Enable Satori protocol.
2. Port defaults to `5600`.
3. Set Satori token if needed.
4. Click Save.
![image](https://files.astrbot.app/docs/source/images/satori/2025-10-10_15-52-32.png)
## Configure Satori Adapter in AstrBot
1. Open AstrBot Dashboard.
2. Click `Bots`.
3. Click `+ Create Bot`.
4. Select `satori`.
Fill in:
- Bot ID (`id`): `LLTwoBot`
- Enable (`enable`): checked
- Satori API endpoint (`satori_api_base_url`): `http://localhost:5600/v1`
- Satori WebSocket endpoint (`satori_endpoint`): `ws://localhost:5600/v1/events`
- Satori token (`satori_token`): from LLTwoBot config if set
> [!NOTE]
> - LLTwoBot Satori service defaults to port `5600`.
> - The complete API base path is `http://localhost:5600/v1`.
> - If your Satori service runs on another port/path, adjust these values.
![image](https://files.astrbot.app/docs/source/images/satori/2025-10-10_16-10-54.png)
Click `Save`.
## Done
AstrBot should now be connected to LLTwoBot via Satori.
Send `/help` in QQ to verify.
## Troubleshooting
If connection fails, check:
1. LLTwoBot is running.
2. Satori service is enabled.
3. Port/path are configured correctly.
4. Token matches (if configured).
docs/en/platform/satori/server-satori.md
+65
View File
@@ -0,0 +1,65 @@
# Connect server-satori (Koishi)
> [!TIP]
> `server-satori` is a Koishi plugin that exposes Koishi as a Satori server, so AstrBot can connect to Koishi through Satori.
## Preparation
Make sure you already have a running Koishi instance.
If not, follow official docs first:
- Koishi starter docs: <https://koishi.chat/zh-CN/manual/starter/windows.html>
- Koishi community: <https://koishi.chat/zh-CN/about/contact.html>
## Enable `server-satori` in Koishi
1. Open Koishi admin panel.
2. Go to `Plugin Config`.
3. Install and enable `server-satori` (defaults usually work).
After enabling, `server-satori` serves Satori API under `/satori`.
![image](https://files.astrbot.app/docs/source/images/satori/2025-09-07_17-14-55.png)
## Configure Satori Adapter in AstrBot
1. Open AstrBot Dashboard.
2. Click `Bots`.
3. Click `+ Create Bot`.
4. Select `satori`.
Fill in:
- Bot ID (`id`): `server-satori`
- Enable (`enable`): checked
- Satori API endpoint (`satori_api_base_url`): `http://localhost:5140/satori/v1`
- Satori WebSocket endpoint (`satori_endpoint`): `ws://localhost:5140/satori/v1/events`
- Satori token (`satori_token`): usually empty unless configured in Koishi
> [!NOTE]
> - Koishi default port is `5140`.
> - `server-satori` default path is `/satori`.
> - So the full API base is `http://localhost:5140/satori/v1`.
> - If your Koishi runs on different host/port/path, change accordingly.
![image](https://files.astrbot.app/docs/source/images/satori/2025-10-10_16-16-25.png)
Click `Save`.
## Done
AstrBot should now be connected to Koishi via `server-satori`.
Test by sending an AstrBot command (for example `/help`) in Koishi sandbox.
![image](https://files.astrbot.app/docs/source/images/satori/2025-09-07_17-19-04.png)
## Troubleshooting
If connection fails, check:
1. Koishi is running.
2. `server-satori` is installed and enabled.
3. Port/path are configured correctly.
4. Firewall is not blocking related ports.
docs/en/platform/slack.md
+94
View File
@@ -0,0 +1,94 @@
# Connecting to Slack
## Create AstrBot Slack Platform Adapter
Navigate to the `Bots` page, click `+ Create Bot`, find Slack and click to enter the Slack configuration page.
![image](https://files.astrbot.app/docs/source/images/slack/image-1.png)
In the configuration dialog that appears, click `Enable`.
## Create an App in Slack
Slack supports two connection methods: `Webhook` and `Socket`. If you don't have a public server and your message volume is relatively small, we recommend using the `socket` method. If you have a public server (or have technical knowledge about setting up tunnels, such as Cloudflare Tunnel), you can choose the `webhook` method. The `socket` method is relatively simpler to deploy.
1. Create a [Slack](https://slack.com/signin) account and a Workspace.
2. Go to [Apps Management](https://api.slack.com/apps), click "Create New App" -> "From Scratch", enter the `App Name` and the workspace to add it to, then click "Create App".
3. (Webhook only) Obtain the `Signing Secret`. In the Basic Information page on the left sidebar, find `Signing Secret` under App Credentials, click Show and copy it to the signing_secret field in the platform adapter configuration.
![image](https://files.astrbot.app/docs/source/images/slack/image.png)
4. In the Basic Information page on the left sidebar, find App-Level Tokens and click "Generate Token and Scopes". Enter any Token Name, click Add Scope, select `connections:write`, then click "Generate". Click Copy and paste the result into the app_token field on the AstrBot configuration page.
![image](https://files.astrbot.app/docs/source/images/slack/image-2.png)
5. In the OAuth & Permissions page on the left sidebar, add the following permissions under Bot Token Scopes:
- channels:history
- channels:read
- channels:write.invites
- chat:write
- chat:write.customize
- chat:write.public
- files:read
- files:write
- groups:history
- groups:read
- groups:write
- im:history
- im:read
- im:write
- reactions:read
- reactions:write
- users:read
6. In the OAuth & Permissions page on the left sidebar, click `Install to xxx` under OAuth Token (where xxx is your workspace name). Then copy the generated Bot User OAuth Token to the bot_token field in the platform adapter configuration.
7. (Socket only) In the Socket Mode page on the left sidebar, enable Socket Mode.
![image](https://files.astrbot.app/docs/source/images/slack/image-3.png)
## Start the Platform Adapter
The configuration is now complete. If you're using Socket mode, simply click the Save button in the bottom right corner of the configuration.
If you're using Webhook mode, please keep `Unified Webhook Mode (unified_webhook_mode)` enabled.
> [!TIP]
> Before v4.8.0, there is no `Unified Webhook Mode`. You need to fill in the following configuration items:
> Slack Webhook Host, Slack Webhook Port, and Slack Webhook Path
## Enable Event Subscriptions
After successfully creating the platform adapter, return to the Slack settings. In the Event Subscriptions page on the left sidebar, click Enable Events to enable event reception.
If you're using Webhook mode:
- If `Unified Webhook Mode` is enabled, after clicking save, AstrBot will automatically generate a unique Webhook callback URL for you. You can find it in the logs or on the bot card in the WebUI's Bots page. Enter this URL in the `Request URL` field.
![unified_webhook](https://files.astrbot.app/docs/source/images/use/unified-webhook.png)
- If `Unified Webhook Mode` is not enabled, enter `https://your-domain/astrbot-slack-webhook/callback` in the `Request URL` field.
> [!TIP]
> In Webhook mode, you need to first set up your domain with your DNS provider, then use reverse proxy software to forward requests to port `6185` on the AstrBot server (if Unified Webhook Mode is enabled) or the port specified in your configuration (if Unified Webhook Mode is not enabled). Alternatively, you can use Cloudflare Tunnel. For detailed tutorials, please refer to online resources; this tutorial will not cover these in detail.
After enabling, under Subscribe to bot events below, click Add Bot User Event and add the following events:
1. channel_created
2. channel_deleted
3. channel_left
4. member_joined_channel
5. member_left_channel
6. message.channels
7. message.groups
8. message.im
9. reaction_added
10. reaction_removed
11. team_join
## Test the Connection
Enter the Slack workspace you just added, navigate to the channel where you want to use the bot, then @ mention the app you just created. Click the Add button in the message subsequently sent by Slackbot to add it to the workspace. Then, @ mention the app and type `/help`. If it responds successfully, the test is successful.
If you have any questions, please [submit an Issue](https://github.com/AstrBotDevs/AstrBot/issues).
docs/en/platform/start.md
+6
View File
@@ -0,0 +1,6 @@
# Messaging Platforms
AstrBot supports integration with many mainstream instant messaging platforms, so you can use AstrBot on the IM platform your team already uses.
In WebUI, click **Bots** in the left sidebar to open the messaging platform integration page.
Then click **Create Bot** in the top-right corner, choose the platform you want to connect, and follow the platform-specific guide in the left sidebar of this documentation.
docs/en/platform/telegram.md
+55
View File
@@ -0,0 +1,55 @@
# Connecting to Telegram
## Supported Message Types
> Version v4.15.0.
| Message Type | Receive Support | Send Support | Notes |
| --- | --- | --- | --- |
| Text | Yes | Yes | |
| Image | Yes | Yes | |
| Voice | Yes | Yes | |
| Video | Yes | Yes | |
| File | Yes | Yes | |
Proactive message push: Supported.
## 1. Create a Telegram Bot
First, open Telegram and search for `BotFather`. Click `Start`, then send `/newbot` and follow the prompts to enter your bot's name and username.
After successful creation, `BotFather` will provide you with a `token`. Please keep it secure.
If you need to use the bot in group chats, you must disable the bot's [Privacy mode](https://core.telegram.org/bots/features#privacy-mode). Send the `/setprivacy` command to `BotFather`, select your bot, and then choose `Disable`.
## 2. Configure AstrBot
1. Enter the AstrBot admin panel
2. Click `Bots` in the left sidebar
3. In the interface on the right, click `+ Create Bot`
4. Select `telegram`
Fill in the configuration fields that appear:
- ID: Enter any value to distinguish between different messaging platform instances.
- Enable: Check this option.
- Bot Token: Your Telegram bot's `token`.
Please ensure your network environment can access Telegram. You may need to configure a proxy using `Configuration -> Other Settings -> HTTP Proxy`.
## Streaming Output
The Telegram platform supports streaming output. Enable the "Streaming Output" switch in "AI Configuration" -> "Other Settings".
### Private Chat Streaming
In private chats, AstrBot uses the `sendMessageDraft` API (added in Telegram Bot API v9.3) for streaming output. This displays a "typing" draft preview animation in the chat interface, creating a more natural "typewriter" effect. It avoids issues with the traditional approach such as message flickering, push notification interference, and API edit frequency limits.
### Group Chat Streaming
In group chats, since the `sendMessageDraft` API only supports private chats, AstrBot automatically falls back to the traditional `send_message` + `edit_message_text` approach.
:::warning
`sendMessageDraft` requires `python-telegram-bot>=22.6`.
:::
docs/en/platform/vocechat.md
+44
View File
@@ -0,0 +1,44 @@
# Connect to VoceChat
> [!TIP]
> AstrBot does not include this adapter by default. Install [astrbot_plugin_vocechat](https://github.com/HikariFroya/astrbot_plugin_vocechat), developed by [HikariFroya](https://github.com/HikariFroya).
> [!WARNING]
> This adapter is community-maintained and not officially maintained by AstrBot.
## Deploy VoceChat
VoceChat is an open-source instant messaging platform with simple multi-platform deployment.
See deployment methods on the [VoceChat official website](https://voce.chat/en-US).
## Install `astrbot_plugin_vocechat`
In AstrBot Dashboard Plugin Market, search for `astrbot_plugin_vocechat` and install it.
![image](https://files.astrbot.app/docs/source/images/vocechat/image.png)
After installation, go to `Bots` -> `+ Create Bot` -> `VoceChat`.
If VoceChat is missing, restart AstrBot or verify plugin installation.
Enable the adapter in the configuration dialog.
## Configuration
- `vocechat_server_url` (required): full VoceChat server URL, e.g. `http://localhost:3009` or `https://your.vocechat.domain` (no trailing `/`).
- `api_key` (required): API key generated for the bot account in VoceChat.
- `webhook_path` (recommended default/custom): webhook path used by AstrBot to receive VoceChat messages, e.g. `/vocechat_webhook`.
- `webhook_listen_host` (usually `0.0.0.0`): listen host for AstrBot webhook server.
- `webhook_port` (required): listen port for AstrBot webhook server, e.g. `8080`.
- `get_user_nickname_from_api` (boolean, default `true`): fetch nickname via VoceChat API.
- `send_plain_as_markdown` (boolean, default `false`): send plain text in markdown format.
- `default_bot_self_uid` (required): UID of your VoceChat bot account.
After configuration, click Save and test in VoceChat.
## Issue Reporting
If needed, report issues to:
- Plugin repo: <https://github.com/HikariFroya/astrbot_plugin_vocechat/issues>
- AstrBot repo: <https://github.com/AstrBotDevs/AstrBot/issues/new?template=bug-report.yml>
docs/en/platform/wecom.md
+137
View File
@@ -0,0 +1,137 @@
# Connect AstrBot to WeCom
AstrBot supports both WeCom Applications and WeCom Customer Service.
## Supported Basic Message Types
> Version v4.15.0.
| Message Type | Receive | Send | Notes |
| --- | --- | --- | --- |
| Text | Yes | Yes | |
| Image | Yes | Yes | |
| Voice | Yes | Yes | |
| Video | No | Yes | |
| File | No | Yes | |
Proactive message push: Supported for WeCom Application. Not fully tested for WeCom Customer Service.
## Before You Start
1. Open AstrBot Dashboard.
2. Click `Bots` in the left sidebar.
3. Click `+ Create Bot`.
4. Select `wecom`.
A configuration dialog will appear. Keep it open and continue with the steps below.
## Method 1: WeCom Customer Service
> [!NOTE]
> 1. Requires AstrBot >= v3.5.7.
> 2. This method works directly inside WeChat.
1. Open [WeCom Customer Service Console](https://kf.weixin.qq.com/) and sign in with WeCom QR login.
2. Create a customer service account in `Customer Service Account`, then copy its **name** (not account ID) to AstrBot field `wechat_kf_account_name`.
3. Go to [WeCom Enterprise Info](https://work.weixin.qq.com/wework_admin/frame#profile), copy `Corpid`, and fill AstrBot `corpid`.
4. Configure callback verification:
- If this is your first customer service bot, open `Development Configuration`, click `Start` next to internal access.
- If you used it before, open `Callback Configuration` directly and click edit.
![image](https://files.astrbot.app/docs/source/images/wecom/8287fd9fec5823847e6b590dc3f0f545.png)
5. Click random generation buttons to get `Token` and `EncodingAESKey`, then fill AstrBot `token` and `encoding_aes_key`.
6. Keep `Unified Webhook Mode (unified_webhook_mode)` enabled, click `Save`, and wait for adapter reload.
For callback URL:
- If unified mode is enabled, AstrBot generates a unique webhook callback URL after save. Copy it from logs or bot card in WebUI.
- If unified mode is disabled, use `http://<your-public-server-ip>:6195/callback/command`.
![unified_webhook](https://files.astrbot.app/docs/source/images/use/unified-webhook.png)
> If unified mode is enabled, forward external requests to AstrBot port `6185`; otherwise forward to configured adapter port (default `6195`).
Back in WeCom Customer Service callback settings, click `Complete`. If successful, status shows completed.
7. In `Development Configuration`, get `Secret`, edit your WeCom adapter in AstrBot, set `secret`, then save again.
> [!TIP]
> Based on [#571](https://github.com/Soulter/AstrBot/issues/571), for newly registered enterprises, `corp_id` may take about 30 minutes to become valid.
Then open AstrBot `Console`, you should see logs asking you to open a WeChat scan link.
```txt
Please open the following link and scan with WeChat ...
```
![image](https://files.astrbot.app/docs/source/images/wecom/image-13.png)
Open the link, scan with WeChat, then send `help` in the customer service chat to test connectivity.
## Method 2: WeCom Application
Open: <https://work.weixin.qq.com/wework_admin/frame#apps>
1. Click `My Company`, copy enterprise ID (`Corpid`), and fill AstrBot `corpid`.
> [!TIP]
> For newly registered enterprises, `corp_id` may take time to become valid. See [#571](https://github.com/Soulter/AstrBot/issues/571).
![image](https://files.astrbot.app/docs/source/images/wecom/image-5.png)
2. Create a custom app (`Custom App`) and fill name/avatar/visibility scope.
3. Open the app, copy `Secret`, and fill AstrBot `secret`.
![image](https://files.astrbot.app/docs/source/images/wecom/image-4.png)
4. In app settings, find `Receive Messages`, click `Set API Receive`.
![image](https://files.astrbot.app/docs/source/images/wecom/image-6.png)
![image](https://files.astrbot.app/docs/source/images/wecom/image-9.png)
5. Generate `Token` and `EncodingAESKey`, fill AstrBot `token` and `encoding_aes_key`.
6. Keep `Unified Webhook Mode (unified_webhook_mode)` enabled (recommended), then click Save in AstrBot and wait for restart.
For callback URL:
- If unified mode is enabled, use the generated unique callback URL from logs or bot card.
- If unified mode is disabled, use `http://<your-public-server-ip>:6195/callback/command`.
![unified_webhook](https://files.astrbot.app/docs/source/images/use/unified-webhook.png)
> If unified mode is enabled, forward to port `6185`; otherwise forward to configured adapter port (default `6195`).
7. Configure trusted enterprise IP in WeCom.
![image](https://files.astrbot.app/docs/source/images/wecom/image-10.png)
Add your public IP and confirm.
![image](https://files.astrbot.app/docs/source/images/wecom/image-12.png)
After AstrBot restart, return to API receive page and click save. If you see callback verification errors, re-check all required fields.
If save succeeds, AstrBot can receive messages from WeCom.
## Test
In WeCom Workbench, open the app you just created and send `/help`.
If AstrBot replies, integration is successful.
## Reverse Proxy (Custom API Base)
AstrBot supports custom WeCom endpoint (`api_base_url`) for environments without stable public IP.
Set your custom endpoint in `api_base_url`.
## Voice Input
Install `ffmpeg` for voice input support.
- Linux: `apt install ffmpeg`
- Windows: download from [FFmpeg website](https://ffmpeg.org/download.html)
- macOS: `brew install ffmpeg`
docs/en/platform/wecom_ai_bot.md
+87
View File
@@ -0,0 +1,87 @@
# Connect to WeCom AI Bot Platform
WeCom AI Bot is an official AI-friendly bot platform by WeCom. It can be used directly in one-on-one chats and internal group chats, and supports streaming responses.
AstrBot supports this platform since v4.3.5.
## Supported Basic Message Types
| Message Type | Receive | Send | Notes |
| --- | --- | --- | --- |
| Text | Yes | Yes | |
| Image | Yes | Yes | Requires message push Webhook URL to be configured. |
| Voice | No | Yes | Requires message push Webhook URL to be configured. |
| Video | No | Yes | Requires message push Webhook URL to be configured. |
| File | No | Yes | Requires message push Webhook URL to be configured. |
Proactive message push: Supported, but requires a message push Webhook URL.
## Configure WeCom AI Bot
1. Sign in to [WeCom Admin Console](https://work.weixin.qq.com/wework_admin).
2. In the left sidebar, open `Management Tools` -> `AI Bot`, then click Create Bot.
![Management Tools - AI Bot](https://files.astrbot.app/docs/source/images/wecom_ai_bot/image-1.png)
3. On the create page, choose `Create via API Mode`. Fill bot name/avatar and other basic info.
Generate `Token` and `EncodingAESKey` using random generation, but do not click Create yet.
![Create AI Bot Account](https://files.astrbot.app/docs/source/images/wecom_ai_bot/image.png)
## Configure AstrBot
1. Open AstrBot Dashboard, click `Messaging Platforms`, then click `+ Add Adapter`, choose `WeCom AI Bot`.
![Add Adapter](https://files.astrbot.app/docs/source/images/wecom_ai_bot/image-2.png)
2. Fill AstrBot fields with values from the WeCom AI Bot create page:
- Bot name
- `token`
- `encoding_aes_key`
- `id` (any unique value)
- `port` (default `6198`, change if needed)
Keep `Unified Webhook Mode (unified_webhook_mode)` enabled and click `Save`.
3. Return to WeCom AI Bot create page and set `URL`:
- If unified mode is enabled, AstrBot generates a unique callback URL after save. Copy it from logs or bot card in WebUI.
- If unified mode is disabled, use `http://IP:port/webhook/wecom-ai-bot`.
![unified_webhook](https://files.astrbot.app/docs/source/images/use/unified-webhook.png)
> It is recommended to use a domain + reverse proxy + HTTPS. You can also use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/).
4. Click `Create`. If successful, you will enter bot details page.
If you see `Service did not respond correctly`, re-check AstrBot config and firewall rules.
![Bot Details](https://files.astrbot.app/docs/source/images/wecom_ai_bot/image-3.png)
5. Optional (recommended): Configure WeCom message push Webhook URL.
By default, WeCom AI Bot replies only when users send messages first. Configuring message push enables proactive notifications.
6. Optional (recommended): Enable `Send messages via Webhook only` for richer multi-message output and to bypass single-bubble reply limits.
This option requires the message push Webhook URL from step 5.
## Use the Bot
### Add Bot to Group Chat
In WeCom client internal group chat, click Add Member -> AI Bot, select the bot you created, and add it.
![Add Member](https://files.astrbot.app/docs/source/images/wecom_ai_bot/image-4.png)
![Added Successfully](https://files.astrbot.app/docs/source/images/wecom_ai_bot/image-5.png)
### Chat with the Bot
Send a message in private chat or group chat to talk to the bot.
If you need typing-like streaming effect, enable `Streaming Reply` in AstrBot.
![Streaming Reply](https://files.astrbot.app/docs/source/images/wecom_ai_bot/image-6.png)
## Help & Support
If you have issues during setup/use or need enterprise support, contact: [community@astrbot.app](mailto:community@astrbot.app).
docs/en/platform/weixin-official-account.md
+78
View File
@@ -0,0 +1,78 @@
# Connect AstrBot to WeChat Official Account Platform
AstrBot supports WeChat Official Account integration (version >= v3.5.8). After setup, you can chat with AstrBot directly in the WeChat Official Account chat interface.
## Before You Start
1. Open AstrBot Dashboard.
2. Click `Bots` in the left sidebar.
3. Click `+ Create Bot`.
4. Select `weixin_official_account`.
A configuration dialog will appear. Keep it open and continue.
## Create / Sign In to WeChat Official Account Platform
Open [WeChat Official Account Platform](https://mp.weixin.qq.com/).
- If you already have an account, sign in.
- If not, register a new account and choose `Official Account`.
> [!NOTE]
> A newly registered account may require 1-2 days for review before it can be used.
## Configure Callback Service
Open `Settings & Development` -> `Development Interface Management`.
![Development Interface Management](https://files.astrbot.app/docs/source/images/weixin-official-account/image.png)
Copy AppID and AppSecret from WeChat platform to AstrBot fields `appid` and `secret`.
Open IP whitelist and add your public IP(s), one per line if multiple.
In server configuration, click modify.
- `Token`: create any string with length 3-32, and fill the same value in AstrBot `token`.
- `EncodingAESKey`: click random generate and fill AstrBot `encoding_aes_key`.
Keep `Unified Webhook Mode (unified_webhook_mode)` enabled (recommended), then save AstrBot config and wait for restart.
For `URL`:
- If unified mode is enabled, use the unique callback URL generated by AstrBot (from logs or bot card).
- If unified mode is disabled, use `http://<your-domain>/callback/command`.
![unified_webhook](https://files.astrbot.app/docs/source/images/use/unified-webhook.png)
> [!NOTE]
> WeChat Official Account callback supports only ports 80 or 443. You usually need a domain and reverse proxy:
> - Unified mode enabled: forward to AstrBot port `6185`
> - Unified mode disabled: forward to adapter port `6194`
Set message encryption mode to `Security Mode`.
Wait a moment and click `Submit`. If configuration is correct, you will see success.
## Test
In WeChat Official Account platform, open account profile and find your QR code.
Scan it with WeChat, send `help`, and check whether AstrBot replies.
If it replies, integration is successful.
> [!NOTE]
> If console shows `ip xxxxx not in whitelist`, your public IP is not in WeChat whitelist yet. Add it and wait a few minutes for WeChat to refresh.
## Reverse Proxy (Custom API Base)
AstrBot supports custom endpoint via `api_base_url` for environments without stable public IP.
## Voice Input
Install `ffmpeg` for voice input support.
- Linux: `apt install ffmpeg`
- Windows: download from [FFmpeg website](https://ffmpeg.org/download.html)
- macOS: `brew install ffmpeg`
docs/en/providers/302ai.md
+21
View File
@@ -0,0 +1,21 @@
# 接入 302.AI
302.AI 是企业级 AI 应用平台，支持快捷接入全球各类 AI 模型。
## 使用
点击[此链接](https://share.302.ai/rr1M3l) 注册账户。
注册完毕之后，点击[此链接](https://302.ai/apis/)选择需要接入的模型。
根据需求，进入[此链接](https://dash.302.ai/charge) 充值对应的金额。
## 接入
打开 AstrBot 控制台 -> 服务提供商页面，点击新增提供商，找到并点击 `302.AI`(需要版本 >= 3.5.18)
修改 ID，并将 API Key 和模型名称填入对话框表单，点击保存，即可完成创建。
## 使用
对机器人输入 `/provider` 指令，将提供商切换到刚刚添加的 302.AI 提供商，即可使用。
docs/en/providers/agent-runners.md
+19
View File
@@ -0,0 +1,19 @@
# Agent Runners
## What Is an Agent Runner?
An Agent Runner is the component in AstrBot that executes Agent capabilities and handles AI-related workflows.
AstrBot includes a powerful built-in Agent Runner. You can also integrate third-party Agent Runner services like Dify, Coze, Alibaba Bailian, and DeerFlow, or build your own.
If you already have a model provider that handles single requests, you still need an execution layer for multi-turn conversations, tool calling, and orchestration. That is exactly what an Agent Runner does.
For more details, see [Usage · Agent Runner](/en/use/agent-runner).
## Quick Links
- [Built-in Agent Runner](/en/providers/agent-runners/astrbot-agent-runner)
- [Dify](/en/providers/agent-runners/dify)
- [Coze](/en/providers/agent-runners/coze)
- [Alibaba Bailian](/en/providers/agent-runners/dashscope)
- [DeerFlow](/en/providers/agent-runners/deerflow)
docs/en/providers/agent-runners/astrbot-agent-runner.md
+8
View File
@@ -0,0 +1,8 @@
# Built-in Agent Runner
By default, AstrBot uses the built-in Agent Runner as the default executor. You don't need to configure anything to use AstrBot's powerful built-in Agent Runner.
![image](https://files.astrbot.app/docs/source/images/astrbot-agent-runner/image.png)
With the built-in Agent Runner, you can use AstrBot's [MCP Server](/use/mcp), [Knowledge Base](/use/knowledge-base), [Web Search](/use/websearch), and persona features.
docs/en/providers/agent-runners/coze.md
+65
View File
@@ -0,0 +1,65 @@
# Connect to Coze
AstrBot v4.2.1 and later versions support connecting to [Coze](https://www.coze.cn/) Agent service.
## Preparation: Get API Key
First, register and log in to your [Coze](https://www.coze.cn/) account, then go to the [API Key Management Page](https://www.coze.cn/open/oauth/pats) to create a new API Key.
You can follow the steps in the image to reach the API Key management page, or click the link above to go directly.
![Create API Key](https://files.astrbot.app/docs/source/images/coze/image_1.png)
Then, click "Create", fill in your API Key name on the following page, select an expiration time (permanent tokens are not recommended), click "Select All" under "Permissions", select a workspace, and then click "Confirm".
![Create Token](https://files.astrbot.app/docs/source/images/coze/image_2.png)
After that, we will get a new API Key. Please copy and save it, as it will be needed later.
![New API Key](https://files.astrbot.app/docs/source/images/coze/image_3.png)
## Preparation: Configure the Agent
Go to the [Project Development](https://www.coze.cn/space/develop) page, click "+Project" in the upper right corner to create a new project, and select to create an agent.
![Create Project](https://files.astrbot.app/docs/source/images/coze/image_4.png)
![Create Project](https://files.astrbot.app/docs/source/images/coze/image_5.png)
**Note**: After creating the agent, you must first click the **Publish** button in the upper right corner to publish the agent. In the "Select Publishing Platform" section, check all API options, then click "Publish".
> If you don't publish or don't check the API options during publishing, you won't be able to call the agent via API.
![Publish Agent](https://files.astrbot.app/docs/source/images/coze/image_6.png)
After clicking publish, the agent creation is complete. You can see the publish history on the left side of the publish button on the agent development page to confirm the agent has been published successfully.
Next, note the URL on the agent development page:
![Agent Development](https://files.astrbot.app/docs/source/images/coze/image_7.png)
For example, if the URL in the example is: "https://www.coze.cn/space/7553214941005004863/bot/7553248674860826660"
Then the `bot_id` is the string of numbers after `bot/` in the URL: `7553248674860826660`
We need to record the `bot_id` for later use.
## Configure Coze in AstrBot
After completing all the preparation work, we can now configure Coze in AstrBot.
Go to AstrBot Admin Panel -> Service Provider -> Add Service Provider -> Coze to enter the configuration page.
![Coze Provider](https://files.astrbot.app/docs/source/images/coze/image_8.png)
Fill in the API Key and bot_id you just created, then click Save.
> Other configuration notes:
>
> - API Base URL: Generally no modification is needed. If you are using the international version of Coze, change this to: "https://api.coze.com"
> - Let Coze manage conversation history: As described.
## Select Agent Runner
Go to the Configuration page in the left sidebar, click "Agent Execution Method", select "Coze", then select the ID of the Coze Agent Runner you just created in the new configuration options that appear below, and click "Save" in the bottom right corner to complete the configuration.
docs/en/providers/agent-runners/dashscope.md
+52
View File
@@ -0,0 +1,52 @@
# Connect to Alibaba Cloud Bailian Application
Since v3.4.30, AstrBot supports connecting to Alibaba Cloud Bailian Application.
## Configure Alibaba Cloud Bailian Application in AstrBot
On the [Alibaba Cloud Bailian Application](https://bailian.console.aliyun.com/app-center#/app-center) website, click to add a new application. Create an agent application, workflow application, or agent orchestration application according to your needs, and build the agent or workflow as required.
Record the Application ID:
![image](https://files.astrbot.app/docs/source/images/dashscope/image-1.png)
Click to enter the application, click Publishing Channel -> API Call -> API KEY, create and copy the API KEY:
![alt text](https://files.astrbot.app/docs/source/images/dashscope/image-2.png)
In the WebUI, click "Model Provider" -> "Add Provider", select "Agent Runner", select "Alibaba Cloud Bailian Application", and enter the Alibaba Cloud Bailian Application configuration page.
According to Alibaba Cloud Bailian Application, there are four application types:
- Agent Application (agent)
- Task Workflow Application (task-workflow)
- Dialog Workflow Application (dialog-workflow)
- Agent Orchestration Application (agent-arrange)
> [!TIP]
> Multi-turn conversations are only supported for agent applications and dialog workflow applications. AstrBot will automatically attach conversation history for these two types of applications to support multi-turn conversations.
Please ensure that the `Application Type` configured in AstrBot matches the application type created in Alibaba Cloud Bailian Application.
Then fill in the Application ID in `dashscope_app_id` and the API KEY in `dashscope_api_key`.
After filling in these three items, click Save.
## Select Agent Runner
Go to the Configuration page in the left sidebar, click "Agent Execution Method", select "Alibaba Cloud Bailian Application", then select the ID of the Alibaba Cloud Bailian Application Agent Runner you just created in the new configuration options that appear below, and click "Save" in the bottom right corner to complete the configuration.
## Appendix: Dynamically Set Workflow Input Variables During Chat (Optional)
For the two workflow applications, you can dynamically set input variables in the chat area.
Use the `/set` command to dynamically set input variables, as shown in the figure below:
![alt text](https://files.astrbot.app/docs/source/images/dify/image-5.png)
After setting variables, AstrBot will attach the variables you set in the next request to Alibaba Cloud Bailian Application, flexibly adapting to your Workflow.
Of course, you can use the `/unset` command to cancel the variables you set. For example, `/unset name`
Variables are permanently valid in the current session.
docs/en/providers/agent-runners/deerflow.md
+53
View File
@@ -0,0 +1,53 @@
# Connect to DeerFlow
Starting from v4.19.2, AstrBot supports connecting to the [DeerFlow](https://github.com/bytedance/deer-flow) Agent Runner.
## Preparation: Deploy DeerFlow
If you have not deployed DeerFlow yet, please complete installation and startup by following the official DeerFlow documentation:
- [DeerFlow GitHub Repository](https://github.com/bytedance/deer-flow)
- [DeerFlow Official Website](https://deerflow.tech/)
- [DeerFlow Configuration Guide](https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md)
Make sure DeerFlow is running properly and that AstrBot can reach the DeerFlow gateway. By default, the DeerFlow gateway address is `http://127.0.0.1:2026`.
> [!TIP]
> - `API Base URL` must start with `http://` or `https://`.
> - If AstrBot and DeerFlow run in different containers or on different hosts, replace `127.0.0.1` with the actual reachable LAN address, hostname, or domain of your DeerFlow service.
## Configure DeerFlow in AstrBot
In the WebUI, click "Model Provider" -> "Add Provider", select "Agent Runner", select "DeerFlow", and enter the DeerFlow configuration page.
Fill in the following fields:
- `API Base URL`: DeerFlow API gateway URL. Default: `http://127.0.0.1:2026`
- `DeerFlow API Key`: Optional. Fill this if your DeerFlow gateway is protected by Bearer auth
- `Authorization Header`: Optional. Custom Authorization header value. This takes precedence over `DeerFlow API Key`
- `Assistant ID`: Maps to LangGraph `assistant_id`. Default: `lead_agent`
- `Model name override`: Optional. Overrides the default model configured in DeerFlow
- `Enable thinking mode`: Whether to enable DeerFlow thinking mode
- `Enable plan mode`: Maps to DeerFlow `is_plan_mode`
- `Enable subagent`: Maps to DeerFlow `subagent_enabled`
- `Max concurrent subagents`: Maps to `max_concurrent_subagents`. Effective only when subagents are enabled. Default: `3`
- `Recursion limit`: Maps to LangGraph `recursion_limit`. Default: `1000`
After filling in the configuration, click Save.
> [!TIP]
> - If DeerFlow already has a default model configured on its side, you can leave `Model name override` empty.
> - Only enable `plan mode` or `subagent` related options when the corresponding DeerFlow capabilities are already configured on the DeerFlow side.
## Select Agent Runner
Go to the Configuration page in the left sidebar, click "Agent Execution Method", select "DeerFlow", then select the ID of the DeerFlow Agent Runner you just created in the new configuration option below, and click "Save" in the bottom right corner to complete the configuration.
## Common Checks
If requests are not being executed through DeerFlow correctly, check the following first:
- whether the DeerFlow service is running properly
- whether `API Base URL` is reachable from the AstrBot environment
- whether the authentication settings are correct
- whether `Assistant ID` matches an actual available assistant in DeerFlow
docs/en/providers/agent-runners/dify.md
+82
View File
@@ -0,0 +1,82 @@
# Connect to Dify
## Install Dify
If you haven't installed Dify yet, please refer to the [Dify Installation Documentation](https://docs.dify.ai/getting-started/install-self-hosted) to install it.
## Configure Dify in AstrBot
In the WebUI, click "Model Provider" -> "Add Provider", select "Agent Runner", select "Dify", and enter the Dify configuration page.
![image](https://files.astrbot.app/docs/source/images/dify/image.png)
In Dify, one `API Key` uniquely corresponds to one Dify application. Therefore, you can create multiple Providers to adapt to multiple Dify applications.
According to the current Dify project, there are three types:
- chat
- agent
- workflow
>[!TIP]
>Please ensure that the APP type you set in AstrBot matches the application type created in Dify.
>![image](https://files.astrbot.app/docs/source/images/dify/image-3.png)
### Chat and Agent Applications
Create your Dify Chat and Agent application keys as shown in the figure below:
![image](https://files.astrbot.app/docs/source/images/dify/chat-agent-api-key.png)
![image](https://files.astrbot.app/docs/source/images/dify/chat-agent-api-key-2.png)
Copy the key and paste it into the `API Key` field in the configuration, then click "Save".
### Workflow Applications
#### Configure Input and Output Variable Names
Workflow applications receive input variables, execute the workflow, and output the results.
![image](https://files.astrbot.app/docs/source/images/dify/workflow-io-key.png)
For Workflow applications, AstrBot will attach two variables with each request:
- `astrbot_text_query`: Input variable name. This is the text content entered by the user.
- `astrbot_session_id`: Session ID
You can customize the input variable name in the configuration, which is the "Prompt Input Variable Name" shown in the figure above.
You need to modify the input variable name of your Workflow to adapt to AstrBot's input.
Finally, the Workflow will output a result. You can customize the variable name of this result, which is the "Dify Workflow Output Variable Name" in the configuration above, with a default value of `astrbot_wf_output`. You need to configure this variable name in the output node of the Dify Workflow, otherwise AstrBot cannot parse it correctly.
#### Create API Key
Create your Dify Workflow application's API Key as shown in the figure below:
Click the Publish button in the upper right corner -> Access API -> click API Key in the upper right corner -> Create Key, then copy the API Key.
![image](https://files.astrbot.app/docs/source/images/dify/workflow-api-key.png)
Copy the key and paste it into the `API Key` field in the configuration, then click "Save".
### Select Agent Runner
Go to the Configuration page in the left sidebar, click "Agent Execution Method", select "Dify", then select the ID of the Dify Agent Runner you just created in the new configuration options that appear below, and click "Save" in the bottom right corner to complete the configuration.
## Appendix: Dynamically Set Workflow Input Variables During Chat (Optional)
You can use the `/set` command to dynamically set input variables, as shown in the figure below:
![alt text](https://files.astrbot.app/docs/source/images/dify/image-5.png)
After setting variables, AstrBot will attach the variables you set in the next request to Dify, flexibly adapting to your Workflow.
![alt text](https://files.astrbot.app/docs/source/images/dify/image-4.png)
Of course, you can use the `/unset` command to cancel the variables you set.
Variables are permanently valid in the current session.
docs/en/providers/aihubmix.md
+70
View File
@@ -0,0 +1,70 @@
# Connect AIHubMix
[AIHubMix](https://aihubmix.com/?aff=4bfH) is a multi-model AI API gateway that provides unified access to OpenAI, Claude, Gemini, DeepSeek, Kimi and more through a single API key. Beyond LLM, it also supports speech, embedding, reranking and other capabilities.
Fully compatible with the OpenAI API format — just change the API Base and Key to get started. **Some models are completely free for development and testing.**
## Get an API Key
1. Sign up at [AIHubMix](https://aihubmix.com/?aff=4bfH)
2. Go to Console → API Keys to create a new key
![Get an API Key](https://github.com/user-attachments/assets/d717f21b-2805-4aff-ac90-f5c98f17cb79)
## Configure in AstrBot
Open the AstrBot dashboard , click **Providers → Add Provider → OpenAI**.
Fill in the following:
| Field | Value |
|-------|-------|
| API Base URL | `https://aihubmix.com/v1` |
| API Key | Your AIHubMix key |
After saving, click the provider card to add models.
![Configure in AstrBot](https://github.com/user-attachments/assets/ee2fb8ba-652c-4e97-a781-42a9082ad7eb)
## Recommended Models
### Free Models 🆓
These models are completely free, great for development and testing:
| Model ID | Description |
|----------|-------------|
| `gpt-4.1-free` | GPT-4.1 free tier |
| `gemini-3-flash-preview-free` | Gemini 3 Flash free tier |
| `coding-glm-5-free` | GLM-5 coding model, free |
| `coding-minimax-m2.5-free` | MiniMax M2.5 coding model, free |
### Paid Models (Popular)
| Model ID | Provider | Description |
|----------|----------|-------------|
| `gpt-5.4` | OpenAI | Latest flagship model |
| `claude-sonnet-4-6` | Anthropic | Great for reasoning and code |
| `gpt-5.3-chat-latest` | OpenAI | High-performance chat |
| `deepseek-v3.2` | DeepSeek | Cost-effective |
| `kimi-k2.5` | Moonshot | Long context |
| `gemini-3.1-pro-preview` | Google | Multimodal |
> See the full model list at [AIHubMix Docs](https://doc.aihubmix.com).
## More Than Chat Models
AIHubMix also supports the following capabilities, all configurable in AstrBot:
| Capability | AstrBot Config Location |
|------------|------------------------|
| Speech-to-Text (STT) | Providers → Speech to Text |
| Text-to-Speech (TTS) | Providers → Text to Speech |
| Embedding | Providers → Embedding |
| Reranking | Providers → Rerank |
All capabilities use the same API Key and API Base — no extra setup needed.
## Set as Default
Go to **Settings → Provider Settings**, set "Default Chat Model Provider" to your AIHubMix provider, and save.
docs/en/providers/coze.md
+1
View File
@@ -0,0 +1 @@
This page is deprecated. Please refer to [Coze Agent Runner](../agent-runners/coze.md).
docs/en/providers/dashscope.md
+1
View File
@@ -0,0 +1 @@
This page is deprecated. Please refer to [Alibaba Cloud Bailian Application Agent Runner](../agent-runners/dashscope.md).
docs/en/providers/dify.md
+1
View File
@@ -0,0 +1 @@
This page is deprecated. Please refer to [Dify Agent Runner](../agent-runners/dify.md).
docs/en/providers/llm.md
+13
View File
@@ -0,0 +1,13 @@
# 大语言模型提供商
你可在管理面板->服务提供商->+新增服务提供商 处配置各种大语言模型服务。
> [!TIP]
> 如果没有你希望接入的模型服务，你可以试着查看您希望接入的服务提供商处是否支持 兼容 OpenAI API，如果支持，那么你可以选择上面截图中的第一项 `OpenAI` 然后通过修改 API Base URL 的方式接入。
![image](https://files.astrbot.app/docs/source/images/llm/image.png)
![image](https://files.astrbot.app/docs/source/images/llm/image-1.png)
> 相应的配置保存在 `data/cmd_config.json` 的 `provider` 字段中。
docs/en/providers/newapi.md
+40
View File
@@ -0,0 +1,40 @@
# NewAPI
[NewAPI](http://newapi.ai/) is a next-generation LLM gateway and AI asset management system built on top of One API. It provides a unified interface for managing and using multiple AI model services, including OpenAI, Anthropic, Gemini, Midjourney, and more.
AstrBot can integrate with NewAPI as a model provider, so you can access those model services through AstrBot.
## Setup Steps
### 1. Create a NewAPI API Key
After registering and signing in to NewAPI, open `Console` in the top navigation bar, go to `Token Management`, then click `Add Token` to create a new API key with appropriate permissions.
![create-api-key](https://files.astrbot.app/docs/source/images/newapi/image.png)
After creation, copy the generated API key.
![copy-api-key](https://files.astrbot.app/docs/source/images/newapi/image-1.png)
### 2. Configure NewAPI in AstrBot
Open AstrBot WebUI, go to `Service Providers`, and click `Add Provider`.
NewAPI fully supports OpenAI Chat Completion and Responses APIs, so select `OpenAI` and open its provider configuration.
Set `API Base URL` to your NewAPI endpoint:
- Self-hosted NewAPI example: `http://localhost:3000/v1`
- Hosted service example: `https://api.example.com/v1`
Then paste your API key into `API Key` and click `Save`.
![astrbot-provider-config](https://files.astrbot.app/docs/source/images/newapi/image-2.png)
### 3. Apply the Provider
Go to `Configuration`, find the model section, set `Default Chat Model` to the NewAPI-based provider you just created, and click `Save`.
![apply](https://files.astrbot.app/docs/source/images/newapi/image-3.png)
You have now successfully configured NewAPI as an AstrBot model provider.
docs/en/providers/ppio.md
+43
View File
@@ -0,0 +1,43 @@
# 接入 PPIO 派欧云
PPIO 派欧云是中国领先的独立分布式云计算服务商，您可以在派欧云上使用稳定、低价甚至免费的模型服务。
## 准备
打开 [PPIO 派欧云官网](https://ppio.cn/user/register?invited_by=AIOONE)，并注册账户（通过此链接注册的账户将会获得 15 元人民币的代金券）。
进入 [模型 API 服务](https://ppio.cn/model-api/console)，找到你想接入的模型。你可以通过筛选器选择不同厂商或者免费的模型。
![image](https://files.astrbot.app/docs/source/images/ppio/image-1.png)
找到你想要接入的模型后，点击模型卡片，侧边会展开一个模型详情卡片，找到下方的 API 接入指南，如果您还没创建过 Key 可以点击创建。
![image](https://files.astrbot.app/docs/source/images/ppio/image-3.png)
打开 AstrBot 控制台 -> 服务提供商页面，点击新增提供商，找到并点击 `PPIO派欧云`(需要版本 >= 3.5.10，旧版本也可使用，见下文)。
![image](https://files.astrbot.app/docs/source/images/ppio/image.png)
将 API Key 和模型名称填入对话框表单，点击保存，即可完成创建。
> [!TIP]
> 如果您是 AstrBot 旧版本（< 3.5.10）的用户，请打开 AstrBot 控制台 -> 服务提供商页面，点击新增提供商，找到 `OpenAI`，点击进入。
> 1. 将 ID 命名为 `ppio`（随意）
> 2. 然后将 `API Base URL` 设置为 `https://api.ppinfra.com/v3/openai`
> 3. 然后将 API Key 和模型名称填入对话框表单，点击保存，即可完成创建。
## 使用
对机器人输入 `/provider` 指令，将提供商切换到刚刚添加的 PPIO 派欧云提供商，即可使用。
## 常见问题
#### 显示 `400` 错误
```log
Error code: 400 - {'code': 400, 'message': '"auto" tool choice requires --enable-auto-tool-choice and --tool-call-parser to be set', 'type': 'BadRequestError'}
```
请暂时使用 `/tool off_all` 禁用所有的函数调用工具即可使用，或者换用其他模型。
docs/en/providers/provider-lmstudio.md
+38
View File
@@ -0,0 +1,38 @@
# 接入 LM Studio 使用 DeepSeek-R1 等模型
LMStudio 允许在本地电脑上部署模型（需要电脑硬件配置符合要求）
### 下载并安装 LMStudio
https://lmstudio.ai/download
### 下载并运行模型
https://lmstudio.ai/models
跟随 LMStudio 下载并运行想要的模型，如 deepseek-r1-qwen-7b:
```bash
lms get deepseek-r1-qwen-7b
```
### 配置 AstrBot
在 AstrBot 上：
点击 配置->服务提供商配置->加号->openai
API Base URL 填写 `http://localhost:1234/v1`
API Key 填写 `lm-studio`
> 对于 Mac/Windows 使用 Docker Desktop 部署 AstrBot 部署的用户，API Base URL 请填写为 `http://host.docker.internal:1234/v1`。
> 对于 Linux 使用 Docker 部署 AstrBot 部署的用户，API Base URL 请填写为 `http://172.17.0.1:1234/v1`，或者将 `172.17.0.1` 替换为你的公网 IP IP（确保宿主机系统放行了 1234 端口）。
如果 LM Studio 使用了 Docker 部署，请确保 1234 端口已经映射到宿主机。
模型名填写上一步选好的
保存配置即可。
> 输入 /provider 查看 AstrBot 配置的模型
docs/en/providers/provider-ollama.md
+46
View File
@@ -0,0 +1,46 @@
# Integrating Ollama
🦙 Ollama is a free, open-source tool that lets you run large language models (LLMs) on your own computer. (hardware must meet requirements)
## Download and Install Ollama
You can download Ollama from [https://ollama.com](https://ollama.com/download).
## Select and Pull a Model
Choose the model you want to use at [https://ollama.com/search](https://ollama.com/search).
In the terminal (PowerShell on Windows), enter `ollama pull <model_name>` to download the model.
model_name format: `<model_name>:<model_version>`. For example, `deepseek-r1:8b`.
> The 8b parameter model requires at least 16GB of video memory (VRAM). Refer to other documentation for detailed information on configurations and parameter sizes.
After pulling is complete, use `ollama list` to view the models you have pulled.
Then use `ollama run <model_name>` to run the model.
## Configure AstrBot
Open the AstrBot WebUI, locate Service Provider Management, click on Add Provider, find and click on `Ollama`.
![image](https://files.astrbot.app/docs/source/images/ollama/image.png)
Save the configuration.
::: tip
For Mac/Windows users deploying AstrBot with Docker Desktop, enter `http://host.docker.internal:11434/v1` for the API Base URL.\
For Linux users deploying AstrBot with Docker, enter `http://172.17.0.1:11434/v1` for the API Base URL, or replace `172.17.0.1` with your public IP address (ensure that port 11434 is allowed by the host system).\
If Ollama is deployed using Docker, ensure that port 11434 is mapped to the host.
:::
## FAQ
Error:
```
AstrBot request failed.
Error type: NotFoundError
Error message: Error code: 404 - {'error': {'message': 'model "llama3.1-8b" not found, try pulling it first', 'type': 'api_error', 'param': None, 'code': None}}
```
Please refer to the instructions above and use `ollama pull <model_name>` to pull the model, then use `ollama run <model_name>` to run the model.
docs/en/providers/siliconflow.md
+15
View File
@@ -0,0 +1,15 @@
# Connecting to SiliconFlow
SiliconFlow leverages its proprietary inference engine to deliver efficient acceleration for large language model inference. It provides high-performance, cost-effective API services for a wide range of large models with pay-as-you-go pricing, making application development a breeze.
## Configuring the Chat Model
Navigate to the SiliconFlow [API Keys](https://cloud.siliconflow.cn/me/account/ak) page and create a new API Key. Save it for later use.
Visit the SiliconFlow [Models page](https://cloud.siliconflow.cn/me/models) to select your desired model. Note down the model name for later use.
Open the AstrBot WebUI, click `Service Providers` in the left sidebar -> `Add Provider` -> select `SiliconFlow`.
Paste the `API Key` and `Model Name` you obtained earlier, then click Save to complete the setup. You can click the `Refresh` button under `Service Provider Availability` to verify whether the configuration is successful.
![Configuring Chat Model](https://files.astrbot.app/docs/source/images/siliconflow/image.png)
docs/en/providers/start.md
+41
View File
@@ -0,0 +1,41 @@
# Connecting Model Services
AstrBot supports the native API formats of OpenAI, Google GenAI, and Anthropic. You can connect any model service provider that conforms to one of these three API formats.
> [!NOTE]
> If you are located in mainland China, we strongly recommend using **official model providers** or compliant providers that follow local laws and regulations, for example:
>
> - [MoonshotAI](https://moonshot.cn/)
> - [GLM](https://bigmodel.cn/)
> - [MiniMax](https://www.minimax.io/)
> - [Qwen](https://qwen.ai/apiplatform)
> - [DeepSeek](https://deepseek.com/)
>
> These providers support the OpenAI API format. You can find the API Base URL and API Key from their documentation and fill them into AstrBot provider settings.
>
> Please note that using non-compliant third-party model services may introduce availability, privacy, or legal risks. For details, see the [EULA](https://github.com/AstrBotDevs/AstrBot/blob/master/EULA.md).
For example, you may choose to connect model services provided by (but not limited to):
- Official OpenAI model services ([OpenAI](https://openai.com/))
- Official Anthropic model services ([Anthropic](https://www.anthropic.com/))
- Google's Gemini model services via Google Cloud ([Google Cloud](https://cloud.google.com/))
- OpenRouter model services ([OpenRouter](https://openrouter.ai/))
## Integration Steps Using DeepSeek as an Example
Using DeepSeek as an example, assuming you have registered and logged in to a DeepSeek account, the steps to connect are:
1. Go to the DeepSeek Console (https://platform.deepseek.com/).
2. Click the "API Keys" menu in the left sidebar, create a new API Key, and copy the key.
3. Click the "API Documentation" link near the bottom of the left sidebar to open the API documentation page.
4. On the API documentation page, find the section about the "OpenAI-compatible interface" and note the API Base URL, for example `https://api.deepseek.com/v1`. (If there is no `/v1`, please add `/v1`.)
5. Open the AstrBot Console -> Service Providers page, click Add Provider, find and click `OpenAI` (if the provider type you want to connect is listed, prefer clicking that type; for some providers like DeepSeek we provide optimized adapter support). Paste the API Key into the `API Key` field of the form and paste the API Base URL into the `API Base URL` field.
6. Click Get Model List, find the model you want to use, click the + button on the right, then toggle the switch that appears on the right to enable it.
7. Go to the Configuration page, find the conversational model, click the selection button on the right, choose the provider and model you just added, then click the Save Configuration button at the bottom-right of the screen.
## Using Environment Variables to Load Keys
> Introduced in v4.13.0.
You can use environment variables to load provider API keys. In the provider configuration page, set the API Key field to `$ENV_VARIABLE_NAME`, for example: `$DEESEEK_API_KEY`.
docs/en/providers/tokenpony.md
+23
View File
@@ -0,0 +1,23 @@
# Connecting to TokenPony
## Configuring the Chat Model
Register and log in to [TokenPony](https://www.tokenpony.cn/3YPyf).
Navigate to the TokenPony [API Keys](https://www.tokenpony.cn/#/user/keys) page and create a new API Key. Save it for later use.
Visit the TokenPony [Models page](https://www.tokenpony.cn/#/model) to select your desired model. Note down the model name for later use.
Open the AstrBot WebUI, click `Service Providers` in the left sidebar -> `Add Provider` -> select `TokenPony` (requires version >= 4.3.3)
![Configuring Chat Model](https://files.astrbot.app/docs/source/images/tokenpony/image.png)
> If you don't see the `TokenPony` option, you can also click `Connect to OpenAI` as shown in the image and change the `API Base URL` to `https://api.tokenpony.cn/v1`.
Paste the `API Key` and `Model Name` you obtained earlier, then click Save to complete the setup. You can click the `Refresh` button under `Service Provider Availability` to verify whether the configuration is successful.
## Applying the Chat Model
In the AstrBot WebUI, click `Configuration` in the left sidebar, find `Default Chat Model` under AI Configuration, select the `tokenpony` (TokenPony) provider you just created, and click Save.
![Configuring Chat Model 2](https://files.astrbot.app/docs/source/images/tokenpony/image_1.png)
docs/en/use/agent-runner.md
+52
View File
@@ -0,0 +1,52 @@
# Agent Runner
The Agent Runner is a component in AstrBot used to execute Agents.
Starting from version v4.7.0, we have migrated three providers—Dify, Coze, and Alibaba Cloud Bailian Application—to the Agent Runner layer, reducing some conflicts with AstrBot's existing features. Rest assured, if you upgrade from an older version to v4.7.0, you don't need to take any action as AstrBot will automatically migrate for you. Later versions also added DeerFlow support as an Agent Runner provider.
AstrBot currently supports five Agent Runners:
- AstrBot Built-in Agent Runner
- Dify Agent Runner
- Coze Agent Runner
- Alibaba Cloud Bailian Application Agent Runner
- DeerFlow Agent Runner
By default, the AstrBot Built-in Agent Runner is the default runner.
## Why Abstract the Agent Runner
In earlier versions, platforms with "built-in Agent capabilities" like Dify, Coze, and Alibaba Cloud Bailian Application were integrated into AstrBot as regular Chat Providers. In practice, we found that they are fundamentally different from traditional Chat Providers that "only handle text completion". Forcing them into the same layer caused many design and usage conflicts. Therefore, starting from v4.7.0, we abstracted them into independent Agent Runners.
From an architectural perspective, you can understand it as:
- Chat Provider is responsible for "talking";
- Agent Runner is responsible for "thinking + doing".
The Agent Runner calls the Chat Provider's interface and, based on the Chat Provider's response, performs multi-turn "perceive → plan → execute action → observe result → re-plan" loops.
A Chat Provider is essentially a `single-turn completion interface`, taking prompt + conversation history + tool list as input and outputting model responses (text, tool call instructions, etc.).
An Agent Runner is typically a `loop` that receives user intent, context, and environment state, makes plans based on strategy/model (Plan), selects and invokes tools (Act), reads results from the environment (Observe), understands the results again, updates internal state, decides the next action, and repeats this process until the task is completed or times out.
![image](https://files.astrbot.app/docs/source/images/use/agent-runner/agent-arch.svg)
Platforms like Dify, Coze, Bailian Application, and DeerFlow have this loop built-in. If you treat them as regular Chat Providers, it will conflict with AstrBot's built-in Agent Runner functionality.
## Usage
By default, the AstrBot Built-in Agent Runner is the default runner. Using the default runner can already meet most needs, and you can use AstrBot's MCP, knowledge base, web search, and other features.
If you need to use the capabilities of platforms like Dify, Coze, Bailian Application, or DeerFlow, you can create an Agent Runner and select the corresponding provider.
## Creating an Agent Runner
![image](https://files.astrbot.app/docs/source/images/use/agent-runner/image-1.png)
In the WebUI, click "Model Provider" -> "Add Provider", select "Agent Runner", choose the platform or runner type you want to connect to, and fill in the relevant information.
## Changing the Default Agent Runner
![image](https://files.astrbot.app/docs/source/images/use/agent-runner/image.png)
In the WebUI, click "Configuration" -> "Agent Execution Method", change the runner type to the Agent Runner type you just created, then select `XX Agent Runner Provider ID` as the ID of the Agent Runner provider you just created, and click save.
docs/en/use/astrbot-agent-sandbox.md
+76
View File
@@ -0,0 +1,76 @@
# Agent Sandbox Environment ⛵️
> [!TIP]
> This feature is currently in technical preview and may have some bugs. If you encounter any issues, please submit an issue on [GitHub](https://github.com/AstrBotDevs/AstrBot/issues).
Starting from version `v4.12.0`, AstrBot introduced the Agent sandbox environment to replace the previous code executor functionality. The sandbox environment provides Agents with safer and more flexible code execution and automation capabilities.
![](https://files.astrbot.app/docs/source/images/astrbot-agent-sandbox/image.png)
## Enabling the Sandbox Environment
Currently, the sandbox environment only supports running through Docker. We are currently using the [Shipyard](https://github.com/AstrBotDevs/shipyard) project as AstrBot's sandbox environment driver. In the future, we will support more types of sandbox environment drivers, such as e2b.
### Deploying AstrBot and Shipyard with Docker Compose
If you haven't deployed AstrBot yet, or want to switch to our recommended deployment method with sandbox environment, we recommend using Docker Compose to deploy AstrBot with the following code:
```bash
git clone https://github.com/AstrBotDevs/AstrBot
cd AstrBot
# Modify the environment variable configuration in the compose-with-shipyard.yml file, such as Shipyard's access token, etc.
docker compose -f compose-with-shipyard.yml up -d
docker pull soulter/shipyard-ship:latest
```
This will start a Docker Compose service that includes AstrBot main program and the sandbox environment.
### Deploying Shipyard Separately
If you have already deployed AstrBot but haven't deployed the sandbox environment, you can deploy Shipyard separately.
Code as follows:
```bash
mkdir astrbot-shipyard
cd astrbot-shipyard
wget https://raw.githubusercontent.com/AstrBotDevs/shipyard/refs/heads/main/pkgs/bay/docker-compose.yml -O docker-compose.yml
# Modify the environment variable configuration in the compose-with-shipyard.yml file, such as Shipyard's access token, etc.
docker compose -f docker-compose.yml up -d
# pull the latest Shipyard ship image
docker pull soulter/shipyard-ship:latest
```
After successful deployment, the above command will start a Shipyard service that listens on `http://<your-host>:8156` by default.
> [!TIP]
> If you deploy AstrBot using Docker, you can also modify the Compose file above to place Shipyard's network in the same Docker network as AstrBot, so you don't need to expose Shipyard's port to the host machine.
## Configuring AstrBot to Use the Sandbox Environment
In the AstrBot console, go to the "Configuration Files" page and find "Agent Sandbox Environment", then enable the sandbox environment switch.
In the configuration options that appear:
For `Shipyard API Endpoint`, if you use the Docker Compose deployment method above, fill in `http://shipyard:8156`. If you deployed Shipyard separately, please fill in the corresponding address, such as `http://<your-host>:8156`.
For `Shipyard Access Token`, please fill in the access token you configured when deploying Shipyard.
For `Shipyard Ship Lifetime (seconds)`, this defines the lifetime of each sandbox environment instance, with a default value of 3600 seconds (1 hour). You can adjust this value as needed.
For `Shipyard Ship Session Reuse Limit`, this defines the maximum number of sessions that each sandbox environment instance can reuse, with a default value of 10. This means that 10 sessions will share the same sandbox environment instance. You can adjust this value as needed.
After configuring, click the "Save" button at the bottom of the page to save the configuration.
## About `Shipyard Ship Lifetime (seconds)`
The lifetime of a sandbox environment instance defines the maximum time each instance can exist before being destroyed. This setting needs to be determined based on your usage scenario and resources.
- When a new session joins an existing sandbox environment instance, the instance will automatically extend its lifetime to the TTL requested by this session.
- When an operation is performed on a sandbox environment instance, the instance will automatically extend its lifetime to the current time plus the TTL.
## About Data Persistence in the Sandbox Environment
Shipyard allocates a working directory for each session under the `/home/<unique session ID>` directory.
Shipyard automatically mounts the /home directory in the sandbox environment to the `${PWD}/data/shipyard/ship_mnt_data` directory on the host machine. When a sandbox environment instance is destroyed, if a session continues to request the sandbox, Shipyard will recreate a new sandbox environment instance and remount the previously persisted data to ensure data continuity.
docs/en/use/astrbot-sandbox.md
View File
docs/en/use/code-interpreter.md
+96
View File
@@ -0,0 +1,96 @@
# Docker-based Code Interpreter
> [!WARNING]
> Deprecated, please refer to the latest [Agent Sandbox Environment](/en/use/astrbot-agent-sandbox.md) documentation. This feature will be unavailable after v4.12.0.
Starting from version `v3.4.2`, AstrBot supports a code interpreter to enhance LLM capabilities and enable various automated operations.
> [!TIP]
> This feature is currently in experimental stage and may have some issues. If you encounter any problems, please submit an issue on [GitHub](https://github.com/AstrBotDevs/AstrBot/issues). Join our discussion group: [322154837](https://qm.qq.com/cgi-bin/qm/qr?k=EYGsuUTfe00_iOu9JTXS7_TEpMkXOvwv&jump_from=webapi&authKey=uUEMKCROfsseS+8IzqPjzV3y1tzy4AkykwTib2jNkOFdzezF9s9XknqnIaf3CDft).
To use this feature, ensure that `Docker` is installed on your machine. This feature requires a dedicated Docker sandbox environment to execute code and prevent malicious code generated by the LLM from harming your machine.
## Running AstrBot with Docker on Linux
If you've deployed AstrBot using Docker, some additional setup is required.
1. When starting the Docker container, mount `/var/run/docker.sock` inside the container. This allows AstrBot to launch sandbox containers.
```bash
sudo docker run -itd -p 6180-6200:6180-6200 -p 11451:11451 -v $PWD/data:/AstrBot/data -v /var/run/docker.sock:/var/run/docker.sock --name astrbot soulter/astrbot:latest
```
2. Use the `/pi absdir <absolute-path>` command during chat to set the absolute path of AstrBot's data directory on your host machine.
Example:
![image](https://files.astrbot.app/docs/source/images/code-interpreter/image-4.png)
## Running AstrBot from Source on Linux
**If your Docker commands require sudo privileges**, you need to start AstrBot with `sudo`, otherwise the code interpreter won't be able to invoke Docker due to insufficient permissions.
```bash
sudo -E python3 main.py
```
## Usage
This feature uses the `soulter/astrbot-code-interpreter-sandbox` image. You can view detailed information about the image on [Docker Hub](https://hub.docker.com/r/soulter/astrbot-code-interpreter-sandbox).
The image includes commonly used Python libraries:
- Pillow
- requests
- numpy
- matplotlib
- scipy
- scikit-learn
- beautifulsoup4
- pandas
- opencv-python
- python-docx
- python-pptx
- pymupdf
- mplfonts
Tasks that can be accomplished include:
- Image editing
- Web scraping
- Data analysis and simple machine learning
- Document processing, such as reading and writing Word, PPT, PDF files
- Mathematical calculations, such as plotting graphs and solving equations
Since Docker Hub is inaccessible from mainland China, if you're in that region, use `/pi mirror` to view/set the mirror source. For example, as of this writing, you can use `cjie.eu.org` as the mirror source by setting `/pi mirror cjie.eu.org`.
When the code interpreter is triggered for the first time, AstrBot will automatically pull the image, which may take some time. Please be patient.
The image may be updated periodically to provide more features, so check for updates regularly. If you need to update the image, use the `/pi repull` command to re-pull it.
> [!TIP]
> If the feature doesn't start properly initially, after successful startup, execute `/tool on python_interpreter` to enable this feature.
> You can use `/tool ls` to view all tools and their enabled status.
![image](https://files.astrbot.app/docs/source/images/code-interpreter/image-3.png)
## Image and File Input
In addition to recognizing and processing images and text tasks, the code interpreter can also recognize files you send and send files back.
After v3.4.34, use the `/pi file` command to start uploading files. After uploading, you can use `/pi list` to view your uploaded files and `/pi clean` to clear your uploaded files.
Uploaded files will be used as input for the code interpreter.
For example, if you want to add rounded corners to an image, you can upload the image using `/pi file`, then ask: `Please run code to add rounded corners to this image`.
## Demo
![image](https://files.astrbot.app/docs/source/images/code-interpreter/a3cd3a0e-aca5-41b2-aa52-66b568bd955b.png)
![alt text](https://files.astrbot.app/docs/source/images/code-interpreter/image.png)
![image](https://files.astrbot.app/docs/source/images/code-interpreter/image-1.png)
![image](https://files.astrbot.app/docs/source/images/code-interpreter/image-2.png)
docs/en/use/command.md
+5
View File
@@ -0,0 +1,5 @@
# Built-in Commands
AstrBot has many built-in commands that are imported as plugins. They are located in the `packages/astrbot` directory.
Use `/help` to view all built-in commands.
docs/en/use/context-compress.md
+40
View File
@@ -0,0 +1,40 @@
# Context Compression
Starting from v4.11.0, AstrBot introduced an automatic context compression feature.
![alt text](https://files.astrbot.app/docs/source/images/context-compress/image.png)
AstrBot automatically compresses the context when the conversation context **reaches 82% of the maximum context window length of the conversation model being used**, ensuring that as much conversation content as possible is retained without losing key information.
## Compression Strategies
There are currently two compression strategies:
1. Truncate by conversation rounds. This strategy simply removes the earliest conversation content until the context length meets the requirements. You can specify the number of conversation rounds to discard at once, with a default of 1 round. This is the **default strategy**.
2. LLM-based context compression. This strategy calls the model itself to summarize and compress the conversation content, thereby retaining more key information. You can specify the conversation model to use for compression; if not selected, it will automatically fall back to the "truncate by conversation rounds" strategy. You can set the number of recent conversation rounds to retain during compression, with a default of 4. You can also customize the prompt used during compression. The default prompt is:
```
Based on our full conversation history, produce a concise summary of key takeaways and/or project progress.
1. Systematically cover all core topics discussed and the final conclusion/outcome for each; clearly highlight the latest primary focus.
2. If any tools were used, summarize tool usage (total call count) and extract the most valuable insights from tool outputs.
3. If there was an initial user goal, state it first and describe the current progress/status.
4. Write the summary in the user's language.
```
After one round of compression, AstrBot will perform a secondary check to verify if the current context length meets the requirements. If it still doesn't meet the requirements, it will adopt a halving strategy, cutting the current context content in half until the requirements are met.
- AstrBot will invoke the compressor for checking before each conversation request.
- In the current version, AstrBot does not perform context compression during tool invocations. We will support this feature in the future, so stay tuned.
## ‼️ Important: Model Context Window Settings
By default, when you add a model, AstrBot automatically retrieves the model's context window size from the API provided by [MODELS.DEV](https://models.dev/) based on the model's ID. However, due to the wide variety of models and the fact that some providers even modify the model IDs, AstrBot cannot automatically infer the context window size for all models you add.
You can manually set the model's context window size in the model configuration, as shown in the image below:
![alt text](https://files.astrbot.app/docs/source/images/context-compress/image1.png)
> [!NOTE]
> If you don't see the configuration option shown in the image above, please delete the model and re-add it.
When the model context window size is set to 0, AstrBot will still automatically retrieve the model's context window size from MODELS.DEV for each request. If it remains 0, context compression will not be enabled for that request.
docs/en/use/custom-rules.md
+17
View File
@@ -0,0 +1,17 @@
# Custom Rules
> [!NOTE]
> The "unified message origin" mentioned below refers to UMO. A UMO uniquely identifies a specific conversation on a messaging platform.
Since version v4.7.0, we have refactored AstrBot's original "Session Management" feature into the "Custom Rules" feature to reduce conflicts with configuration files.
You can think of custom rules as more flexible, mandatory processing rules for specified message sources, which have higher priority than configuration files.
For example, if a messaging platform originally uses the "default" configuration file, all conversations under this platform are processed according to the rules in the configuration file. If you want to apply special processing to a specific session source A, previously you would need to create a separate configuration file and bind A to it. Now, you simply need to create a custom rule in the WebUI's Custom Rules page and select message source A. You can define the following rules:
1. Whether to enable message processing for this unified message origin. If disabled, the effect is equivalent to blacklisting this unified message origin.
2. Whether to enable LLM for messages from this unified message origin. If disabled, AI capabilities will not be used.
3. Whether to enable TTS for messages from this unified message origin. If disabled, TTS capabilities will not be used.
4. Configure specific chat models, speech recognition models (STT), and text-to-speech models (TTS) for this unified message origin.
5. Configure a specific persona for this unified message origin.
docs/en/use/function-calling.md
+54
View File
@@ -0,0 +1,54 @@
---
outline: deep
---
# Function Calling
## Introduction
Function calling aims to provide large language models with **the ability to invoke external tools**, enabling various Agentic functionalities.
For example, when you ask the LLM: "Help me search for information about cats", the model will call external search tools, such as search engines, and return the search results.
Here is the revised text, updated to reflect your new content while maintaining a formal documentation tone:
Currently, supported models include but are not limited to:
- GPT-5.x series
- Gemini 3.x series
- Claude 4.x series
- DeepSeek v3.2 (deepseek-chat)
- Qwen 3.x series
Mainstream models released after 2025 typically support function calling.
Commonly unsupported models include older models such as DeepSeek-R1 and Gemini 2.0 thinking-type models.
In AstrBot, web search, todo reminders, and code interpreter tools are provided by default. Many plugins, such as:
- astrbot_plugin_cloudmusic
- astrbot_plugin_bilibili
- ...
In addition to providing traditional command invocation, also offer function calling capabilities.
Related commands:
- `/tool ls` - View the list of available tools
- `/tool on` - Enable a specific tool
- `/tool off` - Disable a specific tool
- `/tool off_all` - Disable all tools
Some models may not support function calling and will return errors such as `tool call is not supported`, `function calling is not supported`, `tool use is not supported`, etc. In most cases, AstrBot can detect these errors and automatically remove function calling tools for you. If you find that a model doesn't support function calling, you can also use the `/tool off_all` command to disable all tools and try again, or switch to a model that supports function calling.
Below are some common tool calling demos:
![image](https://files.astrbot.app/docs/source/images/function-calling/image.png)
![image](https://files.astrbot.app/docs/source/images/function-calling/image-1.png)
## MCP
Please refer to this documentation: [AstrBot - MCP](/use/mcp).
docs/en/use/knowledge-base.md
+59
View File
@@ -0,0 +1,59 @@
# AstrBot Knowledge Base
> [!TIP]
> Requires AstrBot version >= 4.5.0.
![Knowledge Base Preview](https://files.astrbot.app/docs/en/use/image-3.png)
## Configuring Embedding Model
Open the service provider page, click "Add Service Provider", and select Embedding.
Currently, AstrBot supports embedding vector services compatible with OpenAI API and Gemini API.
Click on the provider card above to enter the configuration page and fill in the configuration.
After completing the configuration, click Save.
## Configuring Reranker Model (Optional)
A reranker model can improve the precision of final retrieval results to some extent.
Similar to configuring the embedding model, open the service provider page, click "Add Service Provider", and select Reranker. For more information about reranker models, please refer to online resources.
## Creating a Knowledge Base
AstrBot supports multiple knowledge base management. During chat, you can **freely specify which knowledge base to use**.
Enter the knowledge base page and click "Create Knowledge Base", as shown below:
![image](https://files.astrbot.app/docs/source/images/knowledge-base/image.png)
Fill in the relevant information. In the embedding model dropdown menu, you will see the embedding model and reranker model you just created (reranker model is optional).
> [!TIP]
> Once you've selected an embedding model for a knowledge base, do not modify the **model** or **vector dimension information** of that provider, as this will **seriously affect** the retrieval accuracy of the knowledge base or even **cause errors**.
## Uploading Files
After creating a knowledge base, you can upload documents to it. Up to 10 files can be uploaded simultaneously, with a maximum size of 128 MB per file.
![Upload Files](https://files.astrbot.app/docs/en/use/image-4.png)
## Using the Knowledge Base
In the configuration file, you can specify different knowledge bases for different configuration profiles.
## Appendix 2: Applying for Free Embedding Models
### PPIO Cloud
1. Open the [PPIO Cloud website](https://ppio.cn/user/register?invited_by=AIOONE) and register an account (accounts registered through this link will receive a 15 RMB voucher).
2. Go to the [Model Marketplace](https://ppio.cn/model-api/console) and click on Embedding Models.
3. Click on BAAI:BGE-M3 (as of 2025-06-02, this model is free on this platform).
4. Find the API integration guide and apply for a Key.
5. Fill in the AstrBot OpenAI Embedding model provider configuration:
1. API Key is the PPIO API Key you just applied for
2. embedding api base: enter `https://api.ppinfra.com/v3/openai`
3. model: enter the model you selected, in this example `baai/bge-m3`.
docs/en/use/mcp.md
+102
View File
@@ -0,0 +1,102 @@
# MCP
MCP (Model Context Protocol) is a new open standard protocol for establishing secure bidirectional connections between large language models and data sources. Simply put, it extracts function tools as independent services, allowing AstrBot to remotely invoke these function tools via the MCP protocol, which then return results to AstrBot.
![image](https://files.astrbot.app/docs/source/images/function-calling/image3.png)
AstrBot v3.5.0 supports the MCP protocol, enabling you to add multiple MCP servers and use function tools from MCP servers.
![image](https://files.astrbot.app/docs/source/images/function-calling/image2.png)
## Initial Configuration
MCP servers are typically launched using `uv` or `npm`, so you need to install these two tools.
For `uv`, you can install it directly via pip. Quick installation via AstrBot WebUI:
![image](https://files.astrbot.app/docs/en/use/image.png)
Just enter `uv`.
If you're deploying AstrBot with Docker, you can also execute the following command for quick installation:
```bash
docker exec astrbot python -m pip install uv
```
If you're deploying AstrBot from source, please install it within the created virtual environment.
For `npm`, you need to install `node`.
If you're deploying AstrBot from source or using one-click installation, please refer to [Download Node.js](https://nodejs.org/en/download) to download to your local machine.
If you're using Docker to deploy AstrBot, you need to install `node` in the container (future AstrBot Docker images will include `node` by default). Please execute the following commands:
```bash
sudo docker exec -it astrbot /bin/bash
apt update && apt install curl -y
export NVM_NODEJS_ORG_MIRROR=http://nodejs.org/dist
# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash
\. "$HOME/.nvm/nvm.sh"
nvm install 22
# Verify version:
node -v
nvm current
npm -v
npx -v
```
After installing `node`, you need to restart `AstrBot` to apply the new environment variables.
## Installing MCP Servers
If you're deploying AstrBot with Docker, please install MCP servers in the data directory.
### An Example
I want to install an MCP server for querying papers on Arxiv and found this repository: [arxiv-mcp-server](https://github.com/blazickjp/arxiv-mcp-server). Referring to its README,
We extract the necessary information:
```json
{
"command": "uv",
"args": [
"tool",
"run",
"arxiv-mcp-server",
"--storage-path", "data/arxiv"
]
}
```
If the MCP server you need requires environment variables to configure something (e.g. access token), you could use the command-line tool `env`:
```json
{
"command": "env",
"args": [
"XXX_RESOURCE_FROM=local",
"XXX_API_URL=https://xxx.com",
"XXX_API_TOKEN=sk-xxxxx",
"uv",
"tool",
"run",
"xxx-mcp-server",
"--storage-path", "data/res"
]
}
```
Configure it in the AstrBot WebUI:
![image](https://files.astrbot.app/docs/en/use/image-2.png)
That's it.
Reference links:
1. Learn how to use MCP here: [Model Context Protocol](https://modelcontextprotocol.io/introduction)
2. Get commonly used MCP servers here: [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README-zh.md#what-is-mcp), [Model Context Protocol servers](https://github.com/modelcontextprotocol/servers), [MCP.so](https://mcp.so)
docs/en/use/plugin.md
+7
View File
@@ -0,0 +1,7 @@
# AstrBot Star
Starting from version `3.4.0`, AstrBot renamed plugins to `Star`. AstrBot is a highly modular project, and plugins leverage this modularity to implement various functionalities.
Use `/plugin` to view all plugins. You can also manage installed plugins in the admin panel.
If you want to develop your own plugin, see [AstrBot Plugin Development Guide](/en/dev/star/plugin-new).
docs/en/use/proactive-agent.md
+52
View File
@@ -0,0 +1,52 @@
# Proactive Capabilities
AstrBot introduces a Proactive Agent system, enabling AstrBot to not only respond passively to users but also schedule future tasks and proactively execute them at specified times, delivering results (text, images, files, etc.) to users.
![](https://files.astrbot.app/docs/source/images/proactive-agent/image.png)
Introduced in v4.14.0, this is currently an **experimental feature** and not yet stable.
## Future Tasks (FutureTask)
The Main Agent can now manage a global **Cron Job List**, setting tasks for its future self.
### Features
- **Self-Wakeup**: AstrBot automatically wakes up at the scheduled time to execute tasks.
- **Task Feedback**: After execution, AstrBot reports the results back to the task creator.
- **WebUI Management**: You can view, edit, or delete scheduled tasks in the "Future Tasks" page of the WebUI.
### How to Use
> [!TIP]
> First, ensure that "Proactive Capabilities" is enabled in the configuration.
The Main Agent has the ability to manage scheduled tasks. You can tell it:
- "Remind me to have a meeting at 8 AM tomorrow."
- "Summarize this week's work log every Friday at 5 PM."
- "Set a timer for 10 minutes."
The Main Agent will call built-in scheduling tools to arrange these plans.
You can view and manage all future tasks by clicking **Future Tasks** in the left navigation bar of the AstrBot WebUI.
![](https://files.astrbot.app/docs/source/images/proactive-agent/image-1.png)
### Supported Platforms
Scheduling tasks is supported on all platforms. However, due to some platforms not providing APIs for proactive message pushing, only the following platforms support AstrBot proactively pushing results to users:
- Telegram
- OneBot (QQ)
- Slack
- Feishu (Lark)
- Discord
- Misskey
- Satori
## Sending Multimedia Messages
To make it easier for Agents to send images, audio, video, and other files directly to users, AstrBot provides a `send_message_to_user` tool by default.
### Features
- **Direct Sending**: Agents can send generated or retrieved multimedia files directly to users without complex text conversions.
- **Multiple Formats**: Supports images, files, audio, video, etc.

Some files were not shown because too many files have changed in this diff Show More