玩法参考 nonebot-plugin-steam-info：群友绑定 Xbox 账号后，有人开始、停止或切换游戏时自动在群里播报；也可以随时查看全群的在线状态。
数据来自官方 Xbox Live 接口，不经过第三方服务。
效果
| 开始游戏播报 | xboxcheck 状态总览 |
|---|---|
 |
 |
播报文字示例：
MajorNelson (老王) 开始玩 Forza Horizon 5 了
SpartanJoe 玩了 1 小时 5 分钟 Halo Infinite 后不玩了
安装
使用 nb-cli 安装：
nb plugin install nonebot-plugin-xbox-status
使用包管理器安装
在 nonebot2 项目的根目录下执行：
pip install nonebot-plugin-xbox-status
# 或 pdm add / poetry add / uv add nonebot-plugin-xbox-status
然后在 pyproject.toml 的 [tool.nonebot] 中的 plugins 里追加 "nonebot_plugin_xbox_status"。
准备工作
Xbox 没有 Steam 那样的开发者 API Key，插件需要以一个微软账号（下称「查询账号」）的身份调用接口。一次性配置如下：
1. 注册 Azure 应用（免费）
- 打开 Azure 门户 - 应用注册，点击「新注册」
- 名称随意；受支持的帐户类型选「仅限个人 Microsoft 帐户」；重定向 URI 留空
- 注册后在「概述」页复制「应用程序(客户端) ID」
- 进入「身份验证」，将「允许公共客户端流」设为「是」并保存
2. 配置并登录
- 在
.env中填写XBOX_CLIENT_ID=<客户端 ID>，重启机器人 - 超级用户私聊机器人发送
xboxlogin，按提示打开链接、输入代码，用查询账号登录授权 - 机器人回复「Xbox 登录成功」即完成。令牌会自动续期，之后无需再登录
建议使用单独的小号作为查询账号。该账号需要已创建 Xbox 档案（登录一次 xbox.com 即可）。
3. 让查询账号看得到你
Xbox 隐私设置默认只对好友公开在线状态，每位被绑定的玩家都需要与查询账号互加好友，否则会一直显示为离线。
若已是好友仍显示离线，请检查：设置 → 帐户 → 隐私和联机安全 → Xbox 隐私 → 查看详细信息并自定义 → 联机状态和历史记录。
配置
在 nonebot2 项目的 .env 文件中添加：
| 配置项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
XBOX_CLIENT_ID |
是 | 无 | Azure 应用的客户端 ID。未填写时插件仍可加载，但无法登录 |
XBOX_REQUEST_INTERVAL |
否 | 300 |
轮询间隔（秒） |
XBOX_PROXY |
否 | 无 | HTTP 代理，如 http://127.0.0.1:7890 |
XBOX_LANGUAGE |
否 | zh-CN |
游戏名等文本的语言 |
XBOX_FONT_REGULAR_PATH |
否 | 自动查找 | 常规字体路径（需支持中文） |
XBOX_FONT_BOLD_PATH |
否 | 自动查找 | 粗体字体路径，缺失时使用常规字体 |
未配置字体时，依次尝试 fonts/MiSans-*.ttf（与 steam-info 插件共用）、Noto Sans CJK、文泉驿微米黑、微软雅黑、苹方。都找不到时启动日志会给出警告。
使用
| 指令 | 别名 | 权限 | 范围 | 说明 |
|---|---|---|---|---|
xboxbind <玩家代号或 XUID> |
绑定xbox |
所有人 | 群聊 | 绑定 Xbox 账号 |
xboxunbind |
解绑xbox |
所有人 | 群聊 | 解绑 |
xboxcheck |
查看xbox 查xbox |
所有人 | 群聊 | 查看本群已绑定玩家的状态 |
xboxnickname <昵称> |
xbox昵称 |
所有人 | 群聊 | 设置播报中显示的昵称 |
xboxenable |
启用xbox |
群管理 | 群聊 | 开启本群播报（默认开启） |
xboxdisable |
禁用xbox |
群管理 | 群聊 | 关闭本群播报 |
xboxlogin |
登录xbox |
超级用户 | 私聊 | 登录查询账号 |
xboxhelp |
xbox帮助 |
所有人 | 全部 | 查看帮助 |
指令前缀取决于你的 COMMAND_START 配置。
说明
- 仅支持 OneBot V11 适配器
- 绑定按群隔离：同一 QQ 在不同群可绑定不同账号，播报只发到绑定所在的群
- 在主机主页、Xbox App 中挂机不算玩游戏，不会触发播报
- 机器人启动和新绑定时只记录当前状态、不播报，避免重启后误报和时长错误
- 查询账号的令牌保存在 localstore 数据目录的
token.json中，请勿泄露。长时间停机（约 90 天未刷新）或修改密码后需重新xboxlogin
开发
pip install -e . "nonebot2[fastapi]"
python tests/test_plugin.py # 零配置加载、状态判定、绘图自检，不访问网络
发布：更新 pyproject.toml 中的版本号，推送 v<版本号> 标签，GitHub Actions 会通过 PyPI Trusted Publishing 自动发布。
致谢
- nonebot-plugin-steam-info：玩法与交互参考
- xbox-webapi-python：Xbox Live 接口资料
许可
1 maintainer
Metadata
1 maintainer
Release files for nonebot-plugin-xbox-status 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| nonebot_plugin_xbox_status-0.1.0.tar.gz | 20.9 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nonebot_plugin_xbox_status-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 45.8 kB
Release files / nonebot_plugin_xbox_status-0.1.0.tar.gz
| Download URL | nonebot_plugin_xbox_status-0.1.0.tar.gz |
|---|---|
| Size | 20.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d52f0daf32bffdf844767c589a685aa31f9e1f454e71bb5f537185800e0462b5
|
|
BLAKE2b-256 checksum How to use checksums |
4cc250b286ab12d7c2d017a090f0522ae12b0b7f8049150fb8667d61197afb89
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / nonebot_plugin_xbox_status-0.1.0-py3-none-any.whl
| Download URL | nonebot_plugin_xbox_status-0.1.0-py3-none-any.whl |
|---|---|
| Size | 24.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
382ff9a3fcaff2c5c280ce3f4d47ab3d607063dcc2219cb5e197c0998612d767
|
|
BLAKE2b-256 checksum How to use checksums |
f38af2c80dd18c8d1f82c23462be7c30b5455d5baa5fa971aef656e519f2a86f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logSecurity for nonebot-plugin-xbox-status 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for nonebot_plugin_xbox_status-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
