NapCat Implementation

NapCat Implementation

NapCat is a OneBot V11 implementation based on NTQQ. Lingchu Bot's napcat/ extension package adds NapCat-specific capabilities on top of the default OneBot V11 handlers.

Minimum version

The bot detects NapCat via get_version_info() where app_name == "NapCat.Onebot". Commands below the minimum version are hidden from the menu.

Extension modules

Group announcement

NapCat supports both text and image announcements via the _send_group_notice API:

发送群公告 <内容> [图片]
send-announcement <content> [image]

The image argument accepts UniImage from nonebot-plugin-alconna. The implementation resolves raw bytes, local paths, or downloadable URLs into cached files before passing a filesystem path to the API.

NapCat currently requires the announcement image field to be readable from the NapCat side. If Lingchu Bot and NapCat run in different filesystems, configure the announcement image path bridge as described in the user configuration guide.

For WSL2 (Debian / Ubuntu) deployments, or when migrating to WSL2 and seeing retcode=1200, image field format may be incorrect, see the NapCat Docker WSL2 deployment section. The most common root cause is that \\wsl.localhost\Debian\ (use your distro name) is not in Docker Desktop Settings → Resources → File sharing; adding it, clicking Apply & restart, and recreating the NapCat container fixes the issue.

Group avatar

NapCat supports setting group avatars via the standard set_group_portrait API:

设置群头像 <图片>
set-group-avatar <image>

Remote announcement

The remote announcement command (远程公告) uses the same _send_group_notice API as the local announcement command, but targets a different group:

远程公告 <群号|群名称> <内容> [图片]
remote-announcement <group_id|group_name> <content> [image]

See Default Implementation for group ID resolution and context validation logic.

Configuration

NapCat does not require additional Lingchu Bot configuration beyond the standard OneBot V11 setup for text-only announcements. Image announcements across Docker or separate hosts require the announcement image path bridge. Ensure NapCat is running and connected to NoneBot via WebSocket or HTTP reverse proxy.

DRIVER=~fastapi+~httpx+~websockets
ONEBOT_ACCESS_TOKEN=your-token

Source reference

See handle/qq/adapters/onebot11/napcat/ in the repository.