Oopz Bot 接入教程：如何将 OlivOS 接入 Oopz
本文档将教你如何把 Oopz 平台账号通过民间协议端 Oopzbot SDK 接入 OlivOS 使用。
参考资料：
1. 准备 Oopz 小号
先用手机号注册一个专门给机器人使用的 Oopz 小号，并设置密码。
建议不要使用主账号作为机器人账号。
2. 安装运行环境
电脑需要先安装 Python 3.10 或以上版本。
安装 SDK：
pip install oopz-sdk
如果需要使用语音相关能力，再安装 Chromium：
python -m playwright install chromium
Linux 服务器如果缺少浏览器依赖，可继续执行：
python -m playwright install-deps chromium
验证 SDK 是否安装成功：
python -c "import oopz_sdk; print(oopz_sdk.__version__)"
能正常输出版本号即可。
3. 创建 bot.py
新建一个文件夹，新创建一个文件 bot.py，内容如下。
import asyncio
from oopz_sdk import OopzBot, OopzConfig, OneBotV11Config, setup_logging
setup_logging("INFO")
# 从环境变量读取 Oopz 登录信息：
config = OopzConfig.from_env()
# OneBot v11 适配器配置，用于对接 OlivOS
config.onebot_v11 = OneBotV11Config(
enabled=True,
host="127.0.0.1",
port=9881, # 这里以 9881 为例子，可以更改为任意端口，和 OlivOS 端配置一致即可，建议 10000-49999 之间
# Oopz SDK 提供给 OlivOS 调用的 HTTP action 服务
enable_http=True,
# 本文档使用 HTTP POST 上报，不启用正向 WebSocket
enable_ws=False,
# HTTP TOKEN 必须与 OlivOS 端配置保持一致
access_token="114514",
# HTTP POST 上报签名密钥（可不填）
secret="114514",
# Oopz SDK 将 OneBot v11 事件上报给 OlivOS
enable_http_post=True,
http_post_urls=[
# 若不多开固定为这个
"http://127.0.0.1:55001/OlivOSMsgApi/qq/onebot/default",
],
# 本文档使用 HTTP POST 上报，不启用反向 WebSocket
enable_ws_reverse=False,
# 保存 Oopz ID 与 OneBot 数字 ID 的映射，保持账号和消息 ID 稳定
db_path="./data/onebot_v11.sqlite3",
)
bot = OopzBot(config)
@bot.on_ready
async def handle_ready(ctx):
print("Oopz SDK connected successfully!")
async def main() -> None:
try:
await bot.run()
finally:
await bot.stop()
if __name__ == "__main__":
asyncio.run(main())
本配置里的关键地址和端口：
| 项目 | 值 | 说明 |
|---|
| Oopz SDK OneBot HTTP API | http://127.0.0.1:9881 | OlivOS 调用 send_msg、get_status 等 action 的地址 |
| Oopz SDK HTTP API 端口 | 9881 | bot.py 中 OneBotV11Config.port，可自定义，和 OlivOS 端配置一致即可，建议 10000-49999 之间 |
| OlivOS HTTP POST 上报地址 | http://127.0.0.1:55001/OlivOSMsgApi/qq/onebot/default | Oopz SDK 将消息事件推给 OlivOS 的地址 |
| ID 映射数据库 | ./data/onebot_v11.sqlite3 | 保存 Oopz 与 OneBot v11 的 ID 映射 |
其中 9881 只是使用的示例端口，可以改成其他未被占用的端口。修改后需要同时改 bot.py 里的 OneBotV11Config.port，以及 OlivOS 中填写的 OneBot HTTP API 端口。
4. 启动脚本
Windows 在同文件夹下创建 start.bat 文件：
@echo off
chcp 65001 > nul
echo 正在配置环境变量并启动机器人...
reg add "HKCU\Console" /v VirtualTerminalLevel /t REG_DWORD /d 1 /f > nul 2>&1
set OOPZ_LOGIN_PHONE=你的电话号码
set OOPZ_LOGIN_PASSWORD=你的密码
python bot.py
echo.
pause
Linux 在同文件夹下创建 start.sh 文件：
#!/bin/bash
echo "正在配置环境变量并启动机器人..."
export OOPZ_LOGIN_PHONE="你的电话号码"
export OOPZ_LOGIN_PASSWORD="你的密码"
python3 bot.py
echo ""
read -n 1 -s -r -p "按任意键退出 . . ."
echo ""
Linux 首次使用前给脚本添加执行权限：
chmod +x start.sh
然后启动：
./start.sh
5. 首次连接 OlivOS
- 启动 OlivOS。
- 启动对应启动脚本。
- 让主号在机器人小号所在的频道内随便发送一条消息。
- 在 OlivOS 中查看是否有上报信息，并查看上报的 id 是多少（注意，这个 id 并不是你机器人的 id，具体原因见下）。
↑ 图中打码的部分即为你的 ID
注意：因为 Oopz 和 OneBot 的 ID 模型不同，不能把所有 ID 原样透传。Oopz 的 area + channel + message_id 会映射成 OneBot v11 里的数字 group_id、message_id 等字段。因此首次收到事件后，应以 OlivOS 里实际看到的账号和频道 ID 为准。
本项目将映射数据保存到：
./data/onebot_v11.sqlite3
搭建完成后不要随意删除该文件。删除后 OneBot 数字 ID 可能重新生成，已有配置可能需要重新确认。
6. 退出 OVO 后进行配置
确认 OlivOS 已经识别到账号后，先退出 OlivOS，再按实际看到的账号信息进行配置。
需要确认的配置项：
| 配置项 | 推荐值 |
|---|
| 账号类型 | onebotv11/Http/NapCat |
| 账号 | 上图中你的 ID |
| 地址 | http://127.0.0.1 |
| 端口 | 9881，可自定义，但必须与 bot.py 中你所填写的一致 |
| access token | 与 bot.py 中 access_token 一致 |
配置完成后重新启动 OlivOS 即可。OOPZ Bot 在此期间可以不关闭（当然你关了再开也行）
7. 验证搭建完成
启动顺序建议：
- 先启动 OlivOS。
- 再启动
start.bat 或 start.sh。
- 在 Oopz 频道发送测试消息（例如）。
- 确认 OlivOS 能收到消息并且能 OOPZ 端能正常发送。
8. 常见问题
OlivOS 收不到上报
检查 bot.py 中的 http_post_urls 的上报地址填写正确。
OlivOS 能收到消息但发不出去
检查 OlivOS 配置的 OneBot HTTP API 地址是否为 http://127.0.0.1（注意不是https！！），并确认 access_token 与 bot.py 一致。
有部分功能无法使用
目前仅实现了部分 API，有功能无法使用（例如更改名片）是正常的，请随时检查 SDK 是否需要更新。
目前已经实现的 API 可以查看此文档进行查阅：OOPZ SDK OneBot v11 适配
重启后频道/BOT ID 变了
检查 ./data/onebot_v11.sqlite3 是否被删除或未能写入。该文件用于保存 Oopz 与 OneBot v11 的数字 ID 映射。
BOT 突然没反应了
重新启动 start.bat 或者 start.sh 就行，刷新一下鉴权
如果有其他问题可以在本帖中进行回复哦！
