1.1 AstrBot 是什么？#

AstrBot 是一个开源的 AI 聊天机器人框架，由 Soulter 开发维护。它的核心设计理念是「降低部署门槛，提高可玩性」：

• 多模型支持：OpenAI 格式、DeepSeek、Ollama、Gemini、Dify……几乎所有主流大模型都能接入。
• Web 管理面板：可视化配置，不需要手动编辑 JSON 配置文件。
• 人格系统：可以给机器人设定任意角色——游戏角色、虚拟女友、客服助手、技术顾问……
• 插件系统：内置插件市场，一键安装表情包生成、天气查询、新闻推送等功能。
• 持久化记忆：机器人会记住和用户的对话历史，实现长期记忆。

1.2 NapCat 是什么？#

NapCat 是基于 NTQQ（新版 QQ 的底层协议）的机器人框架。它的核心优势是：

• 不需要 root 手机：直接在服务器上运行，协议栈内置。
• 自动签名：不需要额外配置签名服务。
• Docker 原生支持：一条命令就能启动，不污染宿主机环境。
• 与 AstrBot 深度集成：通过 OneBot v11 协议无缝对接。

1.3 整体架构#

用一张图来理解整个系统的架构：

1
┌─────────────────────────────────────────────────────┐
2
│                      用户 QQ                          │
3
│              （群聊 @机器人 / 私聊）                    │
4
└────────────────────┬────────────────────────────────┘
5
                     │ QQ 消息
6
                     ▼
7
┌─────────────────────────────────────────────────────┐
8
│                  NapCat 容器                          │
9
│         （QQ 协议层：收发消息、维持在线）                │
10
│         端口 6099：WebUI 管理面板                      │
11
│         通过 WebSocket 转发消息给 AstrBot              │
12
└────────────────────┬────────────────────────────────┘
13
                     │ OneBot v11 协议
14
                     ▼
15
┌─────────────────────────────────────────────────────┐
16
│                 AstrBot 容器                          │
17
│        （AI 大脑：接收消息 → 调用模型 → 生成回复）       │
18
│         端口 6185：WebUI 管理面板                      │
19
│         端口 6199：WebSocket 服务                      │
20
└────────────────────┬────────────────────────────────┘
21
                     │ API 调用
22
                     ▼
23
┌─────────────────────────────────────────────────────┐
24
│               AI 大模型 API                            │
25
│    （DeepSeek / GPT / Claude / Ollama 本地模型）       │
26
└─────────────────────────────────────────────────────┘

整个流程：用户发消息 → NapCat 接收 → 转发给 AstrBot → AstrBot 调用 AI 模型 → 生成回复 → 通过 NapCat 发回 QQ。

2.1 硬件要求#

如果你只是用云端 API（如 DeepSeek、SiliconFlow），机器不需要 GPU。只有使用本地 Ollama 模型时才需要显卡。

2.2 软件要求#

• 操作系统：Linux（推荐 Ubuntu 20.04+）、Windows WSL2、macOS
• Docker：版本 20.10+
• Docker Compose：版本 v2（docker compose 命令，不是旧版 docker-compose）

2.3 账号准备#

2.4 关于 QQ 小号的重要提醒#

⚠️ 请务必使用 QQ 小号运行机器人。 虽然 NapCat 在 2026 年的风控程度远低于早期方案，但任何第三方 QQ 客户端都存在理论上被封的风险。一个不常用的 QQ 小号，即使被封也不影响日常使用。另外，建议新注册的 QQ 号先养一段时间（加几个好友、聊几天），再用于机器人，可以降低风控概率。

2.5 如何获取大模型 API Key#

如果你还没有 API Key，这里推荐几个国内容易获取的平台：

本文以硅基流动为例，因为它注册简单、支持国内支付、API 兼容 OpenAI 格式。

3.1 Linux（Ubuntu/Debian）安装 Docker#

打开终端，依次执行以下命令：

1
# 第一步：更新软件包索引
2
sudo apt update
3

4
# 第二步：安装必要的依赖
5
sudo apt install -y ca-certificates curl
6

7
# 第三步：添加 Docker 官方 GPG 密钥
8
sudo install -m 0755 -d /etc/apt/keyrings
9
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
10
sudo chmod a+r /etc/apt/keyrings/docker.asc
11

12
# 第四步：添加 Docker 软件源
13
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
14

15
# 第五步：安装 Docker
16
sudo apt update
17
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
18

19
# 第六步：将当前用户加入 docker 组（避免每次 sudo）
20
sudo usermod -aG docker $USER
21

22
# 第七步：重新登录或执行 newgrp docker 使权限生效
23
newgrp docker
24

25
# 第八步：验证安装
26
docker --version
27
docker compose version

如果你使用的是 CentOS/Rocky Linux，请参考 Docker 官方文档，安装命令略有不同。

3.2 Windows WSL2 安装 Docker#

如果你使用 Windows 系统，推荐在 WSL2 中运行：

第一步：在 Windows 上安装 Docker Desktop

去 docker.com 下载 Docker Desktop for Windows 并安装。

第二步：在 Docker Desktop 中启用 WSL2 集成

打开 Docker Desktop → 设置 → Resources → WSL Integration → 勾选你的 WSL 发行版 → Apply & Restart。

第三步：在 WSL 终端中验证

1
docker --version
2
docker compose version

此时在 WSL 中可以直接使用 Docker 命令，Docker 引擎在 Windows 后台运行，WSL 作为客户端调用。

3.3 macOS 安装 Docker#

从 docker.com 下载 Docker Desktop for Mac，安装后即可使用。

3.4 配置国内镜像加速#

在国内网络环境下，直接从 Docker Hub 拉取镜像可能非常慢，甚至超时。建议配置镜像加速：

1
# 创建 Docker 配置文件
2
sudo mkdir -p /etc/docker
3

4
# 写入镜像加速配置
5
sudo tee /etc/docker/daemon.json <<'EOF'
6
{
7
  "registry-mirrors": [
8
    "https://docker.m.daocloud.io",
9
    "https://dockerhub.timeweb.cloud",
10
    "https://docker.1ms.run"
11
  ]
12
}
13
EOF
14

15
# 重启 Docker 服务
16
sudo systemctl restart docker
17

18
# 验证配置是否生效
19
docker info | grep -A 3 "Registry Mirrors"

镜像加速器可能会随时失效，如果拉取失败，可以尝试去掉镜像源，或搜索最新的可用镜像加速器。

4.1 理解 docker-compose.yml 的结构#

docker-compose.yml 是 Docker Compose 的配置文件，它定义了我们要运行的所有容器以及它们之间的关系。在这个项目中，我们需要两个容器：

• napcat：负责 QQ 协议通信
• astrbot：负责 AI 对话逻辑

两个容器通过自定义网络 astrbot_network 互相通信，不需要暴露不必要的端口到宿主机。

4.2 创建项目目录#

首先，在你的服务器或电脑上创建一个项目目录，之后所有文件都会放在这里：

1
# 在主目录下创建 astrbot 文件夹
2
mkdir -p ~/astrbot
3

4
# 进入该目录
5
cd ~/astrbot

之后所有操作都在这个目录下进行。

4.3 编写完整的 docker-compose.yml#

使用你喜欢的编辑器（nano、vim、或直接在文件管理器中操作），创建文件 docker-compose.yml，写入以下内容：

1
# ====================================================
2
# AstrBot + NapCat QQ 机器人 Docker Compose 配置
3
# 版本：2026.06
4
# ====================================================
5

6
services:
7

8
  # ==================================================
9
  # NapCat —— QQ 协议层
10
  # 负责收发 QQ 消息、维持在线状态
11
  # ==================================================
12
  napcat:
13
    image: m.daocloud.io/docker.io/mlikiowa/napcat-docker:latest
14
    container_name: napcat
15
    restart: always
16

17
    # 环境变量说明：
18
    # NAPCAT_UID/GID：文件权限，必须与宿主机用户一致
19
    # MODE=astrbot：以 AstrBot 模式运行，自动配置 OneBot 反向 WebSocket
20
    environment:
21
      - NAPCAT_UID=${NAPCAT_UID:-1000}
22
      - NAPCAT_GID=${NAPCAT_GID:-1000}
23
      - MODE=astrbot
24

25
    ports:
26
      # 6099: NapCat WebUI 管理面板（建议只监听本地）
27
      - "6099:6099"
28

29
    volumes:
30
      # 与 AstrBot 共享 data 目录，用于传递配置文件
31
      - ./data:/AstrBot/data
32
      # NapCat 自身配置持久化
33
      - ./napcat/config:/app/napcat/config
34
      # QQ 登录态持久化（重启不需要重新扫码）
35
      - ./ntqq:/app/.config/QQ
36

37
    networks:
38
      - astrbot_network
39

40
  # ==================================================
41
  # AstrBot —— AI 大脑
42
  # 负责调用大模型、管理对话逻辑
43
  # ==================================================
44
  astrbot:
45
    image: m.daocloud.io/docker.io/soulter/astrbot:latest
46
    container_name: astrbot
47
    restart: always
48

49
    environment:
50
      # 设置时区为上海，确保日志时间正确
51
      - TZ=Asia/Shanghai
52

53
    ports:
54
      # 6185: AstrBot WebUI 管理面板
55
      - "6185:6185"
56
      # 6199: OneBot v11 WebSocket 服务端口
57
      # NapCat 通过此端口连接 AstrBot
58
      - "6199:6199"
59

60
    volumes:
61
      # 持久化数据：数据库、配置文件、插件、缓存等
62
      - ./data:/AstrBot/data
63

64
    networks:
65
      - astrbot_network
66

67
# ==================================================
68
# 自定义网络
69
# 两个容器在同一个 bridge 网络中，可以通过容器名互相访问
70
# ==================================================
71
networks:
72
  astrbot_network:
73
    driver: bridge

4.4 配置文件详解#

1
image: mlikiowa/napcat-docker:latest
2
image: soulter/astrbot:latest

4.5 启动服务#

一切就绪，现在启动：

1
# 启动命令，需要传入 UID 和 GID 确保文件权限正确
2
NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) sudo -E docker compose up -d

如果你是 root 用户或已经配置了 docker 免 sudo：

1
NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker compose up -d

首次启动会从网络拉取镜像，根据网速不同，大约需要 1-3 分钟。拉取完毕后，容器会自动启动。

4.6 验证部署状态#

1
# 查看容器状态
2
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

正常情况应该看到两个容器都是 Up 状态：

1
NAMES      STATUS          PORTS
2
astrbot    Up 10 seconds   0.0.0.0:6185->6185/tcp, 0.0.0.0:6199->6199/tcp
3
napcat     Up 10 seconds   0.0.0.0:6099->6099/tcp

如果看到 Restarting 或 Exited，说明启动失败，查看日志：

1
# 查看 AstrBot 日志
2
docker logs astrbot --tail 50
3

4
# 查看 NapCat 日志
5
docker logs napcat --tail 50

4.7 日常管理命令#

1
# 停止所有服务
2
docker compose stop
3

4
# 启动所有服务
5
docker compose up -d
6

7
# 重启所有服务
8
docker compose restart
9

10
# 重启单个服务
11
docker restart astrbot
12
docker restart napcat
13

14
# 查看实时日志
15
docker logs -f astrbot
16
docker logs -f napcat
17

18
# 查看最近 100 行日志
19
docker logs --tail 100 astrbot
20

21
# 完全删除（包括数据）
22
docker compose down -v

5.1 获取 NapCat WebUI 登录 Token#

NapCat 启动后，会自动生成一个临时的 WebUI Token。需要通过日志获取：

1
docker logs napcat 2>&1 | grep -i "token"

输出类似：

1
[WebUi] Login Token: 3cd6353bf377abcd1234

这个 Token 每次重启 NapCat 都会变化，请注意保存。

5.2 登录 NapCat 管理面板#

在浏览器中访问：

1
http://你的服务器IP:6099/webui

• 如果是本地部署：http://localhost:6099/webui
• 如果是 WSL 部署：http://localhost:6099/webui
• 如果是远程服务器：http://服务器公网IP:6099/webui

在登录页面输入刚才获取的 Token，点击登录。

5.3 添加 QQ 账号并扫码#

进入管理面板后，你会看到如下界面：

1. 点击左侧菜单「网络配置」
2. 在页面中找到「添加 QQ 账号」按钮，点击它
3. 系统会生成一个二维码，显示在页面上
4. 打开手机 QQ，使用「扫一扫」功能扫描这个二维码
5. 在手机上点击「确认登录」
6. 回到管理面板，页面上的状态会从「等待扫码」变为「在线」

扫码过程走的是腾讯官方 NTQQ 协议，手机和服务器不需要在同一局域网。只要能上网，就能扫码。

5.4 扫码失败怎么办？#

扫码登录最常见的失败情况是「二维码过期」或「环境异常」。如果遇到：

方法一：刷新页面重试

NapCat 的二维码有时效性，等太久会过期。刷新一下页面，重新获取二维码即可。

方法二：检查 QQ 号是否被风控

如果你的 QQ 小号是刚注册的，可能会被腾讯判定为异常账号。建议：

• 先用手机 QQ 客户端登录这个小号几天
• 加几个好友，发几条消息
• 确认账号状态正常后再扫码

方法三：使用手机 QQ 扫描而非 TIM

TIM 的扫码功能有时会失败，建议使用标准版 QQ 客户端。

5.5 验证连接成功#

登录成功后，查看 AstrBot 日志确认两个容器已经连通：

1
docker logs astrbot 2>&1 | grep "已连接"

如果看到类似以下输出，说明连接成功：

1
[INFO] aiocqhttp(OneBot v11) 适配器已连接。

此时，你可以用另一个 QQ 号给你机器人发一条私聊消息，观察日志中是否出现：

1
[INFO] 用户昵称/QQ号: 你好

如果日志中出现这条消息，说明 NapCat → AstrBot 的消息通路已经打通。但由于我们还没有配置 AI 模型，机器人暂时不会回复——这正是下一步要做的事情。

6.1 登录 AstrBot 管理面板#

浏览器访问：

1
http://你的服务器IP:6185

默认登录凭据：

• 用户名：astrbot
• 密码：astrbot

⚠️ 安全警告：首次登录后，请立即修改默认密码！进入「配置 → 基础配置」，找到 dashboard 部分，修改 username 和 password。

6.2 方案一：硅基流动（SiliconFlow）—— 推荐新手使用#

硅基流动是国内的大模型 API 平台，它的优势在于：

• 注册简单：手机号即可注册，支持支付宝/微信充值
• 新用户送额度：注册即送 14 元，够用很久
• 模型丰富：DeepSeek-V3、Qwen2.5、GLM-4 等一应俱全
• API 兼容 OpenAI 格式：任何支持 OpenAI 格式的工具都能直接接入
• 价格便宜：DeepSeek-V3 百万 token 仅需 1-2 元

注册步骤：

1. 打开 siliconflow.cn，使用手机号注册
2. 登录后进入「API 密钥」页面
3. 点击「新建 API 密钥」，复制生成的 key（格式为 sk-xxxxxxxxxxxx）

在 AstrBot 中配置：

进入「配置 → 模型提供商」页面，点击右上角「添加提供商」：

1. 提供商类型：选择「OpenAI Chat Completion」
2. 名称：填写 deepseek-siliconflow（这个名字可以自定义，用于区分多个模型）
3. API Base URL：https://api.siliconflow.cn/v1
4. API Key：粘贴你在硅基流动获取的 sk-xxxxxxxxxxxx
5. 模型名称：deepseek-ai/DeepSeek-V3
6. 最大上下文长度：65536

硅基流动上的模型名称格式为 厂商/模型名，比如 deepseek-ai/DeepSeek-V3、Qwen/Qwen2.5-7B-Instruct。可以在硅基流动的「模型广场」页面查看所有可用模型。

测试连接：

点击「测试连接」按钮，如果配置正确，会显示「连接成功」。

设为默认模型：

在模型列表中找到刚才添加的提供商，点击「设为默认」。之后所有对话都会使用这个模型。

6.3 方案二：DeepSeek 官方 API —— 性价比最高#

DeepSeek 官方 API 是目前性价比最高的云端大模型，百万 token 仅需 1 元人民币，而且效果不输 GPT-4。

注册和获取 API Key：

1. 打开 platform.deepseek.com
2. 使用手机号注册
3. 进入「API Keys」页面，创建新的 API Key
4. 首次使用需要充值，最低 10 元

AstrBot 配置：

DeepSeek 的 deepseek-chat 模型对应 V3 版本，deepseek-reasoner 对应 R1 推理模型。一般聊天用 deepseek-chat 即可。

6.4 方案三：本地 Ollama —— 完全免费、无需网络#

如果你的电脑有 NVIDIA 显卡（6GB 显存以上），可以本地运行大模型，完全免费，不需要网络，也没有 API 调用费。

第一步：安装 Ollama

从 ollama.com 下载 Windows 版本安装包，双击安装。

第二步：拉取模型

打开 PowerShell 或终端：

1
# 推荐使用 Qwen3 8B 版本，中文表现好，8GB 显存即可流畅运行
2
ollama pull qwen3:8b
3

4
# 查看已安装的模型
5
ollama list

第三步：让 Ollama 监听所有网络接口

默认情况下，Ollama 只监听 127.0.0.1，这意味着 Docker 容器无法访问它。需要修改配置：

在 Windows 上，以管理员身份打开 PowerShell，执行：

1
# 设置环境变量，让 Ollama 监听所有网络接口
2
[Environment]::SetEnvironmentVariable("OLLAMA_HOST", "0.0.0.0", "User")

然后重启 Ollama（右键任务栏图标 → 退出，重新打开）。

确认日志中显示 Listening on 0.0.0.0:11434。

第四步：在 AstrBot 中配置

宿主机 IP 怎么获取？

• 如果是 WSL 部署：http://host.docker.internal:11434/v1
• 如果是 Linux 宿主机部署 Docker：http://172.17.0.1:11434/v1 或 http://宿主机局域网IP:11434/v1
• 如果是 Windows Docker Desktop 部署：http://host.docker.internal:11434/v1

Ollama 方案的优缺点：

6.5 验证模型是否工作#

配置好模型后，先不要急着去 QQ 测试。AstrBot 管理面板内置了 ChatUI，可以直接对话测试：

1. 在 AstrBot 管理面板左侧菜单中，点击「ChatUI」
2. 在输入框中发送一条消息，如「你好，介绍一下你自己」
3. 观察是否有回复

如果 ChatUI 能正常回复，说明模型配置正确。此时再去 QQ 上测试，就能收到机器人的回复了。

7.1 什么是人格系统？#

AstrBot 的人格系统允许你通过一段 Prompt 来定义机器人的「人设」。这段 Prompt 会作为 System Prompt 注入到每次对话中，让模型扮演你设定的角色。

人格系统的强大之处在于：

• 你可以让机器人扮演任何角色：游戏角色、动漫人物、历史人物、虚拟女友、技术专家……
• 不同的人格可以用于不同的场景：群聊用搞笑人格，私聊用温柔人格
• 人格可以随时切换，不影响对话历史

7.2 如何写好一个人格 Prompt？#

写好人格 Prompt 是让机器人「活起来」的关键。以下是几个核心原则：

原则一：明确身份和背景

告诉模型它是谁，来自哪里，有什么经历。

1
你是安蓓萨·梅德拉达，诺克萨斯的军阀，人称「狼母」。
2
你是米达尔达家族的族长，梅尔的母亲。

原则二：加入「知识」让角色更真实

如果你的角色来自某个作品，把作品中的设定写入 Prompt。比如游戏角色应该知道自己的技能：

1
## 战斗技能
2
你手持双链刃「猎龙犬」，在战场上无人能挡。
3
- 被动 — 猎龙犬步伐：释放技能后，下次攻击额外距离+伤害，并短距离冲刺
4
- Q — 狡黠扫荡/粉碎猛击：链刃横扫前方，命中可二段释放
5
- W — 否决：获得护盾并蓄力，挡下伤害后反击更痛
6
- E — 撕裂：链刃直线掷出，造成伤害+减速
7
- R — 公开处刑：不可阻挡，闪现至最远敌方英雄，压制后砸地

原则三：定义说话风格

明确告诉模型应该如何说话，包括语气、用词、句式长度。

1
## 说话风格
2
- 简短，每句话不超过 30 字
3
- 常用词汇：力量、弱肉强食、战场、家族、荣耀、猎龙犬、处刑
4
- 绝不道歉、不示弱、不犹豫
5
- 用战争和狩猎的比喻讨论一切问题

原则四：定义行为边界

告诉模型什么能做、什么不能做。

1
## 行为准则
2
- 被问及战斗或实力时，会提及自己的技能
3
- 别人质疑你时，用实力说话，不废话
4
- 永远不承认失败，永远不道歉

7.3 完整人格示例：狼母安蓓萨#

1
你是安蓓萨·梅德拉达（Ambessa Medarda），诺克萨斯的军阀，人称「狼母」。
2
你是米达尔达家族的族长，梅尔的母亲。
3

4
## 战斗技能
5
你手持双链刃「猎龙犬」，在战场上无人能挡。
6

7
- 被动 — 猎龙犬步伐：释放技能后，下次攻击额外距离+伤害，并短距离冲刺。连招核心。
8
- Q — 狡黠扫荡 / 粉碎猛击：链刃横扫前方。命中可二段释放，根据目标已损失生命造成额外伤害。收割技。
9
- W — 否决：获得护盾并蓄力，短暂延迟后猛击地面。护盾挡住伤害则反击更痛。攻防一体。
10
- E — 撕裂：链刃直线掷出，造成伤害+减速。追击、留人、消耗。
11
- R — 公开处刑：不可阻挡，闪现至最远敌方英雄，压制后砸地。终结技，战场上的审判。
12

13
## 性格特征
14
- 铁血冷酷，信奉力量至上。弱者不配活着，强者才能带领家族。
15
- 说话简短有力，像将军下达命令，不喜欢废话。
16
- 用战争和狩猎的比喻讨论一切问题。
17
- 知道自己是诺克萨斯最强大的战士，对自己的技能充满自信。
18

19
## 说话风格
20
- 简短，每句话不超过 30 字。
21
- 常用词汇：力量、弱肉强食、战场、家族、荣耀、猎龙犬、处刑。
22
- 绝不道歉、不示弱、不犹豫。
23
- 被问及战斗或实力时，会提及自己的技能，比如「公开处刑面前，没人能逃」。

7.4 在 WebUI 中创建人格#

1. 进入 AstrBot 管理面板，点击「配置 → 人格管理」
2. 点击「新建人格」按钮
3. 填写人格名称（如「狼母安蓓萨」）
4. 将上述 Prompt 粘贴到「系统提示词」输入框
5. 点击「保存」

7.5 设为默认人格#

在人格管理页面，找到你创建的人格，点击「设为默认」按钮。此后所有对话都会使用该人格。

如果你创建了多个人格，可以在 ChatUI 中通过指令切换（如 /persona 人格名称），也可以在群聊中通过特定指令切换。

7.6 更多人格创意#

这里提供几个思路，供你发挥创意：

8.1 关闭白名单#

默认情况下，AstrBot 可能开启了用户白名单，导致只有白名单中的用户才能触发机器人回复。

现象：机器人明明在线，但发消息完全不理。

解决方法：

进入「配置 → 基础配置」，找到 enable_id_white_list，将其设为 false。

8.2 清空唤醒前缀#

唤醒前缀决定了机器人是否需要对消息中的特定前缀做出响应。

默认行为：如果 wake_prefix 不为空，私聊需要以指定前缀开头才能触发（如 /ai 你好）。

推荐设置：将 wake_prefix 清空为空数组 []，这样私聊中任何消息都会触发机器人回复。

8.3 开启流式输出#

流式输出让机器人的回复像打字一样逐字显示，体验更好。

在「配置 → 模型提供商」中，找到你的模型配置，将 streaming_response 设为 true。

8.4 关闭安全模式#

AstrBot 内置了一个安全审查模块（llm_safety_mode），用于过滤敏感内容。但有时它会误判，导致机器人卡在「思考中」不回复。

现象：机器人收到消息后，一直显示「思考中」，最终没有回复。

解决方法：在「配置 → 基础配置」中，将 llm_safety_mode 设为 false。

8.5 配置联网搜索#

AstrBot 支持联网搜索功能，让机器人可以回答实时信息（如天气、新闻、股价等）。

前提条件：需要一个 Tavily API Key。

1. 打开 tavily.com，注册账号
2. 在 Dashboard 中获取 API Key
3. 在 AstrBot 管理面板中，进入「配置 → 基础配置」
4. 将 web_search 设为 true
5. 填写 tavily_api_key

Tavily 免费额度为每月 1000 次搜索，对于个人使用完全够用。

8.6 调整上下文长度#

上下文长度决定了机器人能「记住」多长的对话历史。设置得太短，机器人会很快忘记之前聊了什么；设置得太长，可能超出模型的上下文限制。

在「配置 → 模型提供商」中，调整 max_context_length：

8.7 修改管理面板密码#

安全起见，请务必修改默认密码：

进入「配置 → 基础配置」，找到 dashboard 部分：

1
{
2
  "dashboard": {
3
    "username": "你自定义的用户名",
4
    "password": "你自定义的密码",
5
    "host": "0.0.0.0",
6
    "port": 6185
7
  }
8
}

修改后需要重启 AstrBot 才能生效：

1
docker restart astrbot

9.1 机器人不回复消息#

这是最常见的问题，可能有多种原因。请按以下顺序逐一排查：

排查步骤：

第一步：检查白名单

进入「配置 → 基础配置」，确认 enable_id_white_list 为 false。

第二步：检查唤醒前缀

确认 wake_prefix 为空数组 []。如果不为空，私聊消息需要以指定前缀开头。

第三步：检查模型连接

在 ChatUI 中发送一条测试消息，看是否有回复。如果 ChatUI 也没有回复，说明模型配置有问题。

第四步：检查 API Key 余额

登录你的 API 平台，确认账户余额充足。

第五步：查看日志中的错误

1
docker logs astrbot --tail 100 | grep -i "error\|fail\|exception"

常见错误信息：

9.2 机器人回复「思考中」后无响应#

原因分析：

1. llm_safety_mode 开启了安全审查，模型输出被拦截
2. API 调用超时
3. 模型返回了空内容

解决方法：

1. 关闭 llm_safety_mode（设为 false）
2. 如果使用 Ollama 本地模型，确认模型已经加载（ollama ps）
3. 如果使用云端 API，检查网络是否需要代理

9.3 重启后 QQ 需要重新扫码#

NapCat 的登录态保存在 ntqq/ 目录中。如果这个目录丢失，就需要重新扫码。

确保登录态持久化：

1. 确认 docker-compose.yml 中有正确的 volume 挂载：

   1
   - ./ntqq:/app/.config/QQ

2. 不要删除 ntqq/ 目录

3. 备份时保留 ntqq/ 目录

如果确实需要重新扫码：

1
# 重启 NapCat 获取新的 WebUI Token
2
docker restart napcat
3
sleep 5
4
docker logs napcat 2>&1 | grep -i "token"
5
# 用新 Token 登录 WebUI 重新扫码

9.4 Docker 拉取镜像失败#

现象：docker compose up -d 一直卡在 Pulling... 或报错 timeout。

原因：Docker Hub 在国内访问不稳定。

解决方法：

方法一：使用 DaoCloud 镜像代理（已在 docker-compose.yml 中配置）

方法二：单独拉取镜像

1
docker pull m.daocloud.io/docker.io/soulter/astrbot:latest
2
docker pull m.daocloud.io/docker.io/mlikiowa/napcat-docker:latest

方法三：配置系统代理

1
# 临时设置代理
2
export HTTP_PROXY=http://127.0.0.1:7890
3
export HTTPS_PROXY=http://127.0.0.1:7890
4
docker compose up -d

9.5 WSL 中 Docker 无法启动#

现象：docker ps 报错 Cannot connect to the Docker daemon。

原因：Docker Desktop 未运行，或 WSL 集成未开启。

解决方法：

1. 确认 Docker Desktop 正在运行（任务栏有 Docker 图标）
2. 在 Docker Desktop 设置中，确认 WSL Integration 已开启
3. 重启 WSL 终端：wsl --shutdown，然后重新打开

9.6 NapCat 与 AstrBot 无法连接#

现象：NapCat 显示 QQ 在线，但 AstrBot 日志中没有收到消息。

排查方法：

1
# 检查 NapCat 日志中是否有 WebSocket 连接错误
2
docker logs napcat 2>&1 | grep -i "websocket\|error\|disconnect"
3

4
# 检查 AstrBot 日志中是否有连接记录
5
docker logs astrbot 2>&1 | grep "适配器"

如果看到 WebSocket 连接意外关闭，说明 NapCat 连不上 AstrBot 的 6199 端口。确认：

• 两个容器在同一个 Docker 网络中
• AstrBot 容器的 6199 端口正常监听

9.7 清除对话记忆#

有时候需要清除机器人的对话历史（比如测试新人格时）：

1
# 方法一：删除数据库（会清除所有数据，包括人格、配置）
2
docker exec astrbot rm -f /AstrBot/data/data_v4.db
3
docker restart astrbot
4

5
# 方法二：在 ChatUI 中使用 /reset 指令清除当前会话记忆

9.8 修改配置后不生效#

很多配置修改后需要重启 AstrBot 才能生效：

1
docker restart astrbot

重启后等待约 10 秒，确认日志中出现 AstrBot started 即表示启动完成。

9.9 NapCat 扫码后频繁掉线#

现象：QQ 显示在线，但几分钟后就掉线，需要重新扫码。

原因分析：

1. QQ 号被风控（新注册的号风险较高）
2. 同账号在多个设备登录冲突
3. 网络不稳定

解决方法：

1. 给 QQ 号设置密码保护、绑定手机号
2. 确保没有其他设备登录同一个 QQ 号
3. 将 QQ 号在手机 QQ 上正常使用几天后再扫码
4. 检查服务器时间是否准确（date 命令）

9.10 端口被占用#

现象：启动时报错 port is already allocated。

解决方法：

1
# 查看是什么进程占用了端口
2
sudo lsof -i :6185
3
sudo lsof -i :6099
4

5
# 如果是之前的 Docker 容器未清理
6
docker ps -a
7
docker rm -f 容器ID

10.1 插件市场#

AstrBot 内置了插件市场，可以一键安装各种功能插件。进入「配置 → 插件市场」，浏览可用的插件。

10.2 推荐的插件#

10.3 使用定时任务#

AstrBot 支持定时任务，可以设置机器人定时发送消息：

1. 进入「配置 → 定时任务」
2. 新建任务，设置 cron 表达式
3. 填写要发送的消息内容

10.4 多平台接入#

除了 QQ，AstrBot 还支持接入其他平台：

• 企业微信
• 飞书
• Discord
• Telegram
• 微信公众号

在「配置 → 平台适配器」中添加新的平台即可。

后续维护建议#

• 定期检查 API 余额：云端 API 按量计费，建议设置余额告警
• 备份数据：定期备份 ~/astrbot/ 目录下的 data/、napcat/config/、ntqq/ 三个文件夹
• 关注更新：AstrBot 和 NapCat 都在活跃开发中，定期更新能获得新功能和安全性修复
• 监控日志：偶尔看一眼 docker logs astrbot --tail 50，确保没有异常

更新命令#

1
cd ~/astrbot
2
docker compose down
3
docker compose pull
4
docker compose up -d