mirror of
https://github.com/AstrBotDevs/AstrBot
synced 2026-07-15 17:30:13 +08:00
docs: add aiocqhttp and satori protocol documentation; remove outdated lagrange and napcat guides
This commit is contained in:
Soulter
@@ -321,13 +321,7 @@ export default defineConfig({
|
||||
},
|
||||
{
|
||||
text: "OneBot v11",
|
||||
base: "/en/platform/aiocqhttp",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: "NapCat", link: "/napcat" },
|
||||
{ text: "Lagrange", link: "/lagrange" },
|
||||
{ text: "Other Clients", link: "/others" },
|
||||
],
|
||||
link: "/aiocqhttp",
|
||||
},
|
||||
{ text: "WeCom Application", link: "/wecom" },
|
||||
{ text: "WeCom AI Bot", link: "/wecom_ai_bot" },
|
||||
@@ -344,7 +338,7 @@ export default defineConfig({
|
||||
base: "/en/platform/satori",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: "Using LLOneBot", link: "/llonebot" },
|
||||
{ text: "Connect Satori", link: "/guide" },
|
||||
{ text: "Using server-satori", link: "/server-satori" },
|
||||
],
|
||||
},
|
||||
|
||||
44
docs/en/platform/aiocqhttp.md
Normal file
44
docs/en/platform/aiocqhttp.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Connect OneBot v11 Protocol Implementations
|
||||
|
||||
OneBot is a standardized bot application interface designed to unify bot development across different chat platforms, so developers can write business logic once and use it on multiple platforms.
|
||||
|
||||
AstrBot supports all client implementations that implement OneBot v11 reverse WebSocket (AstrBot acts as the server).
|
||||
|
||||
Common OneBot v11 implementation projects are listed below:
|
||||
|
||||
- [NapCat](https://github.com/NapNeko/NapCatQQ)
|
||||
- [OneDisc](https://github.com/ITCraftDevelopmentTeam/OneDisc)
|
||||
- [Tele-KiraLink](https://github.com/Echomirix/Tele-KiraLink)
|
||||
|
||||
Please refer to each implementation project's deployment documentation.
|
||||
|
||||
## 1. Configure OneBot v11
|
||||
|
||||
1. Open AstrBot's WebUI
|
||||
2. Click `Bots` in the left sidebar
|
||||
3. In the right panel, click `+ Create Bot`
|
||||
4. Select `OneBot v11`
|
||||
|
||||
Fill in the form:
|
||||
|
||||
- ID (`id`): any value, used only to distinguish instances of different platforms.
|
||||
- Enable (`enable`): check it.
|
||||
- Reverse WebSocket host: fill your machine IP, usually `0.0.0.0`.
|
||||
- Reverse WebSocket port: choose any port, default is `6199`.
|
||||
- Reverse WebSocket token: fill this only when NapCat network configuration has a token set.
|
||||
|
||||
Click `Save`.
|
||||
|
||||
## 2. Configure the protocol implementation side
|
||||
|
||||
Please refer to each protocol implementation project's deployment documentation.
|
||||
|
||||
Notes:
|
||||
|
||||
1. The implementation must support `Reverse WebSocket`, with AstrBot acting as the server and the implementation client as the client.
|
||||
2. The reverse WebSocket URL is `ws(s)://<your-host>:6199/ws`.
|
||||
|
||||
## 3. Verify
|
||||
|
||||
Go to AstrBot WebUI `Console`. If a blue log appears saying `aiocqhttp(OneBot v11) adapter connected.`, the connection is successful.
|
||||
If after a few seconds you see `aiocqhttp adapter has been closed`, it means the connection timed out (failed). Please double-check your configuration.
|
||||
@@ -1,55 +0,0 @@
|
||||
# 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`.
|
||||
@@ -1,141 +0,0 @@
|
||||
# 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.
|
||||
@@ -1 +0,0 @@
|
||||
AstrBot can connect to any bot protocol client that supports OneBot v11 reverse WebSocket (AstrBot acts as the server side).
|
||||
32
docs/en/platform/satori/guide.md
Normal file
32
docs/en/platform/satori/guide.md
Normal file
@@ -0,0 +1,32 @@
|
||||
# Connect to Satori Protocol
|
||||
|
||||
## Satori protocol overview
|
||||
|
||||
> Excerpt from: https://satori.chat/introduction.html
|
||||
|
||||
Satori is a unified chat protocol. It aims to reduce differences between chat platforms and let developers build cross-platform, extensible, high-performance chat applications with lower cost.
|
||||
|
||||
The protocol is named after [Komeiji Satori](https://satori.js.org) in Touhou Project. The idea is that Satori can serve as a bridge between chat platforms, as Komeiji Satori communicates telepathically.
|
||||
|
||||
The development team behind Satori has long worked on bot development and is familiar with the communication patterns of many platforms. After about 4 years, Satori now has a mature design and implementation. The official project currently provides adapters for more than 15 platforms, covering major messaging services worldwide such as QQ, Discord, WeCom, KOOK, and others.
|
||||
|
||||
## 1. Configure the protocol server side
|
||||
|
||||
Please refer to the deployment documentation of the chosen implementation project.
|
||||
|
||||
## 2. Configure Satori protocol in AstrBot
|
||||
|
||||
1. Open AstrBot WebUI.
|
||||
2. Click `Bots` in the left sidebar.
|
||||
3. In the right panel, click `+ Create Bot`.
|
||||
4. Select `satori`.
|
||||
|
||||
Fill in the form:
|
||||
|
||||
- Bot ID (`id`): e.g. `satori` (any value is fine).
|
||||
- Enable (`enable`): check it.
|
||||
- Satori API base URL (`satori_api_base_url`): `http://localhost:5600/v1` (same port as the protocol implementation).
|
||||
- Satori WebSocket endpoint (`satori_endpoint`): `ws://localhost:5600/v1/events` (same port as the protocol implementation).
|
||||
- Satori token (`satori_token`): fill according to implementation settings.
|
||||
|
||||
Click `Save`.
|
||||
@@ -1,73 +0,0 @@
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
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).
|
||||
@@ -1,17 +1,19 @@
|
||||
# 接入 OneBot v11 协议实现
|
||||
|
||||
OneBot 是一个聊天机器人应用接口标准，旨在统一不同聊天平台上的机器人应用开发接口，使开发者只需编写一次业务逻辑代码即可应用到多种机器人平台。
|
||||
OneBot 是一个**聊天机器人应用接口标准**，旨在统一不同聊天平台上的机器人应用开发接口。
|
||||
|
||||
AstrBot 支持接入所有适配了 OneBotv11 反向 Websockets（AstrBot 做服务器端）的机器人协议端。
|
||||
|
||||
下文给出一些常见的 OneBot v11 协议实现端项目。
|
||||
|
||||
- [NapCat](https://github.com/NapNeko/NapCatQQ)
|
||||
- [OneDisc](https://github.com/ITCraftDevelopmentTeam/OneDisc)
|
||||
- [Tele-KiraLink](https://github.com/Echomirix/Tele-KiraLink)
|
||||
- [NapCat](https://github.com/NapNeko/NapCatQQ) (连接到 QQ)
|
||||
- [OneDisc](https://github.com/ITCraftDevelopmentTeam/OneDisc) (连接到 Discord)
|
||||
- [Tele-KiraLink](https://github.com/Echomirix/Tele-KiraLink) (连接到 Telegram)
|
||||
|
||||
请参阅对应的协议实现端项目的部署文档。
|
||||
|
||||
对于 Napcat 项目，请参考下文的 `附录：部署 Napcat`
|
||||
|
||||
## 1. 配置 OneBot v11
|
||||
|
||||
1. 进入 AstrBot 的 WebUI
|
||||
@@ -40,4 +42,42 @@ AstrBot 支持接入所有适配了 OneBotv11 反向 Websockets（AstrBot 做服
|
||||
|
||||
## 3. 验证
|
||||
|
||||
前往 AstrBot WebUI `控制台`，如果出现 ` aiocqhttp(OneBot v11) 适配器已连接。` 蓝色的日志，说明连接成功。如果没有，若干秒后出现` aiocqhttp 适配器已被关闭` 则为连接超时（失败），请检查配置是否正确。
|
||||
前往 AstrBot WebUI `控制台`，如果出现 ` aiocqhttp(OneBot v11) 适配器已连接。` 蓝色的日志，说明连接成功。如果没有，若干秒后出现` aiocqhttp 适配器已被关闭` 则为连接超时（失败），请检查配置是否正确。
|
||||
|
||||
## 附录：部署 Napcat
|
||||
|
||||
### 通过一键启动脚本部署
|
||||
|
||||
推荐采用这种方式部署。
|
||||
|
||||
#### Windows
|
||||
|
||||
看这篇文章：[NapCat.Shell - Win手动启动教程](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
|
||||
|
||||
看这篇文章：[NapCat.Installer - Linux一键使用脚本(支持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]
|
||||
> **Napcat WebUI 在哪打开**：
|
||||
> 在 napcat 的日志里会显示 WebUI 链接。
|
||||
>
|
||||
> 如果是 linux 命令行一键部署的napcat：`docker log <账号>`。
|
||||
>
|
||||
> Docker部署的 NapCat：`docker logs napcat`。
|
||||
|
||||
## 通过 Docker Compose 部署
|
||||
|
||||
1. 下载或复制 [astrbot.yml](https://github.com/NapNeko/NapCat-Docker/blob/main/compose/astrbot.yml) 内容
|
||||
2. 将刚刚下载的文件重命名为 `astrbot.yml`
|
||||
3. 编辑 `astrbot.yml`，将 `# - "6199:6199"` 修改为 `- "6199:6199"`，移除开头的 `#`
|
||||
4. 在 `astrbot.yml` 文件所在目录执行:
|
||||
|
||||
```bash
|
||||
NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker compose -f ./astrbot.yml up -d
|
||||
```
|
||||
|
||||
部署完毕之后，可以去 Napcat 的 WebUI（默认端口 6099）中新增 OneBot 连接实例：点击`网络配置->新建->WebSockets客户端`，在新弹出的窗口中：勾选`启用`，
|
||||
URL 填写 `ws://宿主机IP:端口/ws`。如 `ws://127.0.0.1:6199/ws`。如果采用上面的 Docker Compose 部署，可以填写 `ws://astrbot:6199/ws`（参考本文档的 Docker 脚本）。心跳间隔和重连间隔可以改为 `1000`(1 秒)。点击保存，然后去 AstrBot WebUI 的控制台中检查是否连接成功，出现 `aiocqhttp(OneBot v11) 适配器已连接` 日志即代表成功。
|
||||
|
||||
如果您对部署、网络配置不了解，请千万不要在公网暴露 Napcat 的端口。
|
||||
Reference in New Issue
Block a user