AstrBot 完整配置指南

前言

最近就一时兴起 于是安装了一个Asrtbot玩玩 现在记录一下配置

一、接入消息平台

AstrBot 支持同时接入多个平台。具体见官方文档

方式 A：QQ 官方机器人（推荐新手，WebSocket）
  1. 访问 QQ 开放平台 注册并创建机器人。
  2. 获取 AppID 和 AppSecret。
  3. 在 AstrBot WebUI -> 机器人 -> + 创建机器人 -> 选择 QQ 官方机器人（WebSocket）。
  4. 填入 ID/Secret，勾选启用，保存。
  5. 回到 QQ 开放平台，在 沙箱配置 中添加测试 QQ 号或群。
方式 B：OneBot v11 协议（推荐进阶用户，NapCat 连接）

即：通过 NapCat协议端连接真实 QQ 账号。

1. AstrBot 端配置（作为服务端）

  • WebUI -> 机器人 -> + 创建机器人 -> 选择 OneBot v11。
  • 配置项：
    • 反向 WebSocket 主机：0.0.0.0
    • 端口：6199（默认）
    • Token：留空或与协议端保持一致。

2. 协议端配置（以 NapCat 为例）

  • 部署 NapCat（Docker 或一键脚本）。
  • 进入 NapCat WebUI（默认端口 6099）。
  • 点击 网络配置 -> 新建 -> WebSockets 客户端。
  • URL 填写：ws://astrbot服务IP:6199/ws（若同机部署填 127.0.0.1）。
  • 保存后，AstrBot 控制台出现 aiocqhttp 适配器已连接 即成功。

二、配置模型

用途：没Token玩什么Agent？其它可用于图像识别、知识库嵌入。

在模型配置这一栏 我们可以加入硅基流动的模型通过这个注册https://cloud.siliconflow.cn/i/YgYBvXpG这就是我的邀请链接 你注册实名后就可以获得16元的免费额度 玩玩AstrBot还是可以的 你可以用以下参考模型。

配置项 对话模型 语音转文字 (STT) 嵌入模型 (Embedding)
模型名称 deepseek-ai/DeepSeek-V3.2 FunAudioLLM/SenseVoiceSmall BAAI/bge-large-zh-v1.5
提供商类型 OpenAI 通用格式 OpenAI TTS / STT 格式 OpenAI 嵌入格式
API Key 你的 SiliconFlow API Key 你的 SiliconFlow API Key 你的 SiliconFlow API Key
Base URL https://api.siliconflow.cn/v1 https://api.siliconflow.cn/v1 https://api.siliconflow.cn/v1
用途说明 核心聊天、逻辑推理 语音消息转文字输入 知识库向量化、长期记忆检索

三、Agent 电脑控制（Computer Use）

让 AstrBot 能够执行 Shell 命令、读写文件、运行 Python。

1. 配置路径：WebUI -> 配置 -> 点击上方 管理配置文件 向下拉 找到使用电脑能力。

2. 关键设置：

  • 使用电脑能力：选择 Local。
    • None：禁用。
    • Local：在宿主机直接执行（权限大，适合个人使用）。
    • Sandbox：沙盒隔离执行（更安全，适合多用户）。
  • 需要 AstrBot 管理员权限：建议开启。开启后只有管理员 ID 列表中的用户才能调用 Shell/Python。

3. 权限授予：

  • 在聊天窗口发送 /sid 获取用户 ID。
  • 回到 WebUI -> 其他配置 -> 管理员 ID -> 粘贴该 ID。

4. 工作区逻辑：

  • 文件操作默认发生在 data/workspaces/{会话ID}/ 下，防止文件系统污染。
  • Shell 命令若遇 rm -rf / 等危险操作会自动拦截（非绝对安全边界）。

四、Skills 技能包机制

Skills 是给 Agent 的说明书，Computer Use 是执行的手脚。

1. 安装 Skills

2. 使用逻辑

  • Local 模式：Agent 直接读取宿主机 data/skills/ 下的指令并执行。
  • Sandbox 模式：AstrBot 会自动将 Skills 同步到沙箱环境内执行。

五、知识库搭建

  1. WebUI -> 知识库 -> 创建知识库。
  2. 嵌入模型：选择硅基流动的 任意嵌入模型🆔。
  3. 进入详情页 -> 文档管理 -> 上传 PDF/Word/Markdown。系统自动向量化。
  4. 在机器人配置中勾选该知识库，保存。

九、验证与排障

检查点 预期现象 异常处理
消息连接 WebUI 控制台出现 适配器已连接 日志 检查 URL 格式、端口开放、Token 一致性
模型调用 /模型列表 返回正常 检查 Base URL 是否带 /v1、API Key 余额
电脑控制 /shell ls 返回目录列表 确认用户 ID 在管理员列表、模式非 None

如需查看详细报错，进入 日志 页面，将报错信息发给大模型辅助分析。当然你也可以加入AstrBot的群聊里面 群友们还是很乐意帮助的。