给小白的AstrBot部署和使用指南

本教程仅适用于零基础小白，如果你有一定的计算机基础或已有独立部署AstrBot的经历，这将浪费你的时间

AstrBot 是一个多平台支持的开源机器人框架，它可以：

情感陪伴/角色扮演
接入QQ、微信、飞书、telegram等多平台
群聊管理
使用电脑能力

AstrBot具有强大的能力，你几乎可以像看待真人一样看待AstrBot

部署AstrBot

这里介绍三种部署方式

桌面端

这是最新手友好的部署方式，无需配置任何环境，下载安装包，进入引导程序，完成安装即可
安装包下载地址:

https://github.com/AstrBotDevs/AstrBot-desktop/releases

你需要根据自己电脑的操作系统和处理器型号选择安装包

包管理器

AstrBot基于Python开发，如果你的电脑上已经有了Python3.10+的环境，你可以用一行简单的命令直接完成部署:

1	`pip install astrbot`

这个过程通常会很慢，如果使用uv会快很多：

1	`uv tool install astrbot --python 3.12`

雨云一键部署

本地部署AstrBot有一些弊端:

占用内存资源
电脑关机后就无法与你的AstrBot聊天

你可以简单的把云服务器理解为一台永不关机的电脑，使用云服务器部署AstrBot就没有以上弊端
在雨云购买服务器可享受一键部署的便利：
前往雨云

AstrBot官方推荐至少使用2核4GB内存的服务器，购买时勾选预装软件AstrBot和NapCat(后面要用)即可

购买后等待一段时间，进入云服务器管理页面即可看到

WebUI管理页面

桌面端用户直接打开AstrBot桌面端软件即可

Windows包管理器本地部署用户需要提前为AstrBot创建一个根目录，如D:\AstrBot
在该目录下打开终端，输入命令:

1 2	`astrbot init #仅首次使用需要初始化 astrbot run`

不要关闭这个Shell窗口，它是AstrBot的生命

后续运行AstrBot都需要在根目录下进行，根目录下有AstrBot的全部用户数据

云服务器部署用户通过 http://[你的服务器ip]:6185 访问WebUI管理界面(需要放行6185端口)

访问localhost:6185即可打开WebUI管理页面，初始用户名和密码均为astrbot
如果你忘记了你修改后的密码，只需打开根目录/data/cmd_config.json，找到dashboard字段下的password字段，整行删除，然后重新运行AstrBot，就可以在终端中看到新生成的随机密码

接入消息平台

个人QQ

接入个人QQ前，你需要一个名为NapCat的工具软件(雨云用户一键安装可跳过)

NapCatQQ 是现代化的基于 NTQQ 的 Bot 协议端实现

AstrBot对个人QQ的操作都是通过NapCat实现的

NapCat下载地址:
https://github.com/NapNeko/NapCatQQ/releases

Windows用户下载NapCat.Shell.Windows.OneKey.zip即可，解压后双击运行NapCatInstaller.exe进入NapCat安装程序

完成安装后目录下会自动创建NapCat.*****.Shell文件夹( * 是5个数字)，进入该文件夹双击打开napcat.bat即可

完成登录后不要关闭这个窗口，否则会断开QQ的连接

NapCat的WebUI默认通过6099端口访问，而且需要token鉴权，token可以在刚刚打开的napcat.bat中找到，或直接访问含有token参数的url跳过鉴权

Windows系统下NapCat的WebUI配置文件在NapCat.Shell.Windows.OneKey\NapCat.*****.Shell\versions\*.*.**-*****\resources\app\napcat\config\webui.json，你可以自由查看和修改其中的port(端口)和token(秘钥)字段

雨云用户进入服务器管理页面可以看到：

雨云一键部署的WebUI配置文件在/root/Napcat/opt/QQ/resources/app/app_launcher/napcat/config/webui.json

进入NapCat的WebUI管理界面并登录自己的QQ后，左侧进入网络配置，新建Websocket客户端

然后回到AstrBot的WebUI管理页面，从左侧菜单进入机器人页面，点击新建机器人
消息平台类别要选OneBot v11，不要选QQ官方机器人

完成配置后可在下方的平台日志中看到适配器已连接字样

微信

AstrBot支持通过微信官方为OpenClaw开放的插件接入微信，但不支持像QQ一样控制个人微信号，而是以一个机器人好友的形式存在于你的通讯录中

微信平台的配置非常简单，新建机器人，消息平台类别选择个人微信，机器人名称自定义，其他参数保持默认即可

创建完成后点击查看二维码，使用手机微信扫码(要求微信版本>=8.0.70)就成功接入啦

接入大模型

大模型是AstrBot的大脑，AstrBot支持通过API调用大模型
在此之前你需要有一家大模型提供商的API key并保证有一定余额，或者你有ollama本地部署的大模型

从左侧菜单中进入模型提供商页面，在对话栏目下点击新增，找到你的模型提供商，填入你的API key(部分站点需自行填入base_url)，然后点击保存并获取模型，从下方的模型列表中勾选你需要的即可

音色克隆

AstrBot内置了TTS(文本转语音)功能，配置好TTS提供商后可以让AstrBot给你发语音
硅基流动提供了简单的音色克隆服务，你可以据此赋予你的AstrBot任何人的声音(仅供学习，切勿用于非法场景)
前往硅基流动
首先你需要准备好一段不太短的语音文件，一个硅基流动账号及API key
然后运行以下Python脚本：

import requests

API_KEY = "" #这里填入你的API key
url = "https://api.siliconflow.cn/v1/uploads/audio/voice"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

        # 👇改成你本地的音频路径
with open("嘎子.wav", "rb") as f:
    files = {"file": ("嘎子.wav", f, "audio/wav")} #mp3文件最后一个参数改为"audio/mpeg"

data = {
    "model": "FunAudioLLM/CosyVoice2-0.5B",
    "customName": "嘎子",  # 你给音色起的名字
    "text": "给我拿好了呀..."  # 参考音频对应的文本
}

resp = requests.post(url, headers=headers, files=files, data=data)
print(resp.json())

执行后会输出以下格式的JSON:

1	`{"uri":"speech:嘎子:xxxxxxxxxx"}`

你需要保存好uri字段下的全部内容

来到AstrBot的WebUI页面，新建文字转语音提供商，选择openaiTTS，填入你的API key，API Base Url填入https://api.siliconflow.cn/v1，模型ID填入FunAudioLLM/CosyVoice2-0.5B，Voice填写刚刚保存的uri

保存即可

记得在配置中打开TTS总开关

配置

AstrBot提供了很多可选的配置，左侧菜单进入普通配置，可自定义选择Agent执行器(如果你配置了提供商)，默认对话模型，回退对话模型，图片转述模型，TTS、STT开关(你需要自行配置TTS、STT服务提供商)

人格

你可以为你的AstrBot预设一个人格，人格将会以System Prompt的形式发送给LLM，欢迎访问人格市场
https://jiupamiao.asia/
你还可以上传若干个skills，对于每个人格，你都可以使你任意指定的skill生效

网页搜索

某些情境下AstrBot需要联网搜索信息，比如当你询问明天的天气怎么样
配置合适的网络搜索提供商可以提高搜索内容的质量

使用电脑能力

AstrBot具有调用工具运行终端命令的能力，运行环境可选local和sandbox(推荐)
sandbox是安全的沙箱环境，使AstrBot在沙箱环境里运行命令可有效降低未知的安全风险

命令

对你的AstrBot发送”/help”，他会秒回你类似这样的消息：

AstrBot v4.24.2(WebUI: v4.24.2)
/new - Create new conversation
/provider - View or switch LLM Provider
/reset - Reset conversation history
/sid - Get session ID and other related information
/stats - Show token usage statistics for the current conversation
/stop - Stop agent execution

是的，AstrBot支持通过固定格式的命令控制行为，例如你向他抛出了一个问题，在他回复你之前再次发送”/stop”命令，他就会停止正在生成的回复并告诉你：

1	`✅ Requested to stop 1 running tasks.`

AstrBot支持通过插件注册命令，很多插件功能的实现都需要使用类似的命令

插件

插件系统是AstrBot可拓展性的核心，AstrBot插件市场提供了1000+插件一键下载
但事实上开源插件数量远不止如此，在github上搜索astrbot_plugin能找到更多插件

安装插件

除了从插件市场一键下载之外，AstrBot插件可以直接下载源文件安装
AstrBot插件的源文件通常是一个以astrbot_plugin_为前缀的文件夹，该文件夹下至少包含一个main.py主程序入口和一个metadata.yml元数据
AstrBot所有插件都位于根目录/data/plugins目录下，包括你在插件市场下载的插件，因此，你可以自由地阅读和学习插件源码并根据你的需求对插件源码作出一些改动
只需将合法的插件文件夹(来自github或自己开发的)放到data/plugins目录下即可完成一个插件的安装，WebUI会自动更新插件数据