From 6be8a4302dc93aa4556daa90eddcf0e30c8e678b Mon Sep 17 00:00:00 2001 From: Soulter <905617992@qq.com> Date: Tue, 17 Mar 2026 19:56:08 +0800 Subject: [PATCH] docs: add aiocqhttp and satori protocol documentation; remove outdated lagrange and napcat guides --- docs/.vitepress/config.mjs | 10 +- docs/en/platform/aiocqhttp.md | 44 ++++++++ docs/en/platform/aiocqhttp/lagrange.md | 55 ---------- docs/en/platform/aiocqhttp/napcat.md | 141 ------------------------- docs/en/platform/aiocqhttp/others.md | 1 - docs/en/platform/satori/guide.md | 32 ++++++ docs/en/platform/satori/llonebot.md | 73 ------------- docs/zh/platform/aiocqhttp.md | 50 ++++++++- 8 files changed, 123 insertions(+), 283 deletions(-) create mode 100644 docs/en/platform/aiocqhttp.md delete mode 100644 docs/en/platform/aiocqhttp/lagrange.md delete mode 100644 docs/en/platform/aiocqhttp/napcat.md delete mode 100644 docs/en/platform/aiocqhttp/others.md create mode 100644 docs/en/platform/satori/guide.md delete mode 100644 docs/en/platform/satori/llonebot.md diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index ea96183ea..9932d7a70 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -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" }, ], }, diff --git a/docs/en/platform/aiocqhttp.md b/docs/en/platform/aiocqhttp.md new file mode 100644 index 000000000..a05a31dcc --- /dev/null +++ b/docs/en/platform/aiocqhttp.md @@ -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)://: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. diff --git a/docs/en/platform/aiocqhttp/lagrange.md b/docs/en/platform/aiocqhttp/lagrange.md deleted file mode 100644 index c2be79b68..000000000 --- a/docs/en/platform/aiocqhttp/lagrange.md +++ /dev/null @@ -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: -- Config file guide: - -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`. diff --git a/docs/en/platform/aiocqhttp/napcat.md b/docs/en/platform/aiocqhttp/napcat.md deleted file mode 100644 index bc081721a..000000000 --- a/docs/en/platform/aiocqhttp/napcat.md +++ /dev/null @@ -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 `. -> -> 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) - -xinjianya - - -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`. - -jiaochenXJY - - -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. diff --git a/docs/en/platform/aiocqhttp/others.md b/docs/en/platform/aiocqhttp/others.md deleted file mode 100644 index 8d1c560ce..000000000 --- a/docs/en/platform/aiocqhttp/others.md +++ /dev/null @@ -1 +0,0 @@ -AstrBot can connect to any bot protocol client that supports OneBot v11 reverse WebSocket (AstrBot acts as the server side). diff --git a/docs/en/platform/satori/guide.md b/docs/en/platform/satori/guide.md new file mode 100644 index 000000000..7c9b0b044 --- /dev/null +++ b/docs/en/platform/satori/guide.md @@ -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`. diff --git a/docs/en/platform/satori/llonebot.md b/docs/en/platform/satori/llonebot.md deleted file mode 100644 index 3fc8df55f..000000000 --- a/docs/en/platform/satori/llonebot.md +++ /dev/null @@ -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: - -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). diff --git a/docs/zh/platform/aiocqhttp.md b/docs/zh/platform/aiocqhttp.md index a13fc4a89..0d2033720 100644 --- a/docs/zh/platform/aiocqhttp.md +++ b/docs/zh/platform/aiocqhttp.md @@ -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 适配器已被关闭` 则为连接超时（失败），请检查配置是否正确。 \ No newline at end of file +前往 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 的端口。 \ No newline at end of file