LangBot/docs/event-based-agents/adapters/aiocqhttp.md

OneBot v11 / aiocqhttp EBA Adapter

Status

OneBot v11 has been migrated to the EBA adapter directory:

src/langbot/pkg/platform/adapters/aiocqhttp/
├── adapter.py
├── api_impl.py
├── event_converter.py
├── manifest.yaml
├── message_converter.py
├── platform_api.py
├── types.py
└── onebot.svg

The EBA adapter is registered as aiocqhttp-eba. The legacy adapter remains at src/langbot/pkg/platform/sources/aiocqhttp.py.

Configuration

Field	Required	Default	Description
host	Yes	0.0.0.0	Host for the reverse WebSocket server that the OneBot endpoint connects to.
port	Yes	2280	Reverse WebSocket listen port.
access-token	No	""	OneBot access token, if the endpoint is configured to use one.

Events

The adapter declares these EBA events:

• message.received
• message.deleted
• group.member_joined
• group.member_left
• group.member_banned
• friend.request_received
• friend.added
• bot.invited_to_group
• bot.removed_from_group
• bot.muted
• bot.unmuted
• platform.specific

platform.specific is used for OneBot notice/request/meta events that do not yet have a common EBA event type, such as group admin changes, group file uploads, pokes, honor changes, and group join requests from non-bot users.

Common APIs

API	Status	Notes
send_message	Supported	Supports private and group text, mentions, images, voice, files, faces, and flattened forwards. Group merged forwards are sent through OneBot forward APIs when possible.
reply_message	Supported	Uses the original OneBot event and can prepend a reply segment.
edit_message	Not supported	OneBot v11 has no standard message edit action.
delete_message	Supported	Uses delete_msg; permission depends on endpoint and group role.
forward_message	Supported	Emulates forward by fetching the source message with get_msg and sending its content to the target chat.
get_message	Supported	Uses get_msg and converts the response into MessageReceivedEvent.
get_group_info	Supported	Uses get_group_info.
get_group_list	Supported	Uses get_group_list.
get_group_member_list	Supported	Uses get_group_member_list.
get_group_member_info	Supported	Uses get_group_member_info.
set_group_name	Supported	Uses set_group_name; may be unsupported by mock endpoints.
get_user_info	Supported	Uses get_stranger_info.
get_friend_list	Supported	Uses get_friend_list.
approve_friend_request	Supported	Uses set_friend_add_request.
approve_group_invite	Supported	Uses set_group_add_request with sub_type=invite.
upload_file	Not supported	OneBot v11 has endpoint-specific file upload extensions but no portable standalone upload action.
get_file_url	Not supported	OneBot v11 file URL resolution is endpoint-specific. Use call_platform_api("get_image"), get_record, or endpoint extensions when available.
mute_member	Supported	Uses set_group_ban.
unmute_member	Supported	Uses set_group_ban with duration 0.
kick_member	Supported	Destructive; test only with disposable members.
leave_group	Supported	Destructive; should run last in live tests.
call_platform_api	Supported	See below.

Platform-Specific APIs

call_platform_api(action, params) supports:

• get_login_info
• get_status
• get_version_info
• get_group_honor_info
• set_group_card
• set_group_special_title
• set_group_admin
• set_group_whole_ban
• send_group_forward_msg
• get_forward_msg
• get_record
• get_image
• can_send_image
• can_send_record

Message Conversion Notes

Incoming OneBot segments are converted into common MessageChain components before LangBot core/plugin dispatch:

• text -> Plain
• at -> At / AtAll
• image -> Image or Face for OneBot emoji-package images
• record -> Voice
• file -> File
• reply -> Quote
• face, rps, dice -> Face
• unsupported segments -> Unknown

Outgoing MessageChain components are converted back into aiocqhttp.Message segments. Base64 media strings are normalized to OneBot base64://... format.

Live Test Record

The direct live probe is:

PYTHONPATH=/Users/qinjunyan/code/projects/langbot/langbot-plugin-sdk/src \
uv run python tests/e2e/live_aiocqhttp_eba_probe.py --host 127.0.0.1 --port 2280

It starts the reverse WebSocket adapter directly, records observed EBA events to data/temp/aiocqhttp_eba_live_probe.jsonl, waits for a real Matcha or OneBot message, then tries reply/send/get/delete/group/user/platform API calls as far as the endpoint supports them.

Verified on May 10, 2026 with local Matcha connected to ws://127.0.0.1:2280/ws:

• Real inbound group message converted to MessageReceivedEvent.
• Real lifecycle connection converted to PlatformSpecificEvent.
• Real reply API succeeded and rendered a quoted bot reply in Matcha.
• Real proactive send API succeeded and rendered a bot group message in Matcha.
• Real outgoing component sweep succeeded for text, At, AtAll, Face, and base64 Image.
• Real get_message, get_group_info, get_login_info, get_status, get_version_info, can_send_image, and can_send_record calls succeeded against Matcha.
• Unit conversion and API-shape tests passed for Plain, At, AtAll, Image, Voice, File, Quote, Face, rps, dice, Forward, Unknown, private/group message events, delete notices, group join/leave/ban notices, bot mute notices, friend requests, group invites, friend added notices, dispatch specificity, send, reply, delete, forward, get message, group APIs, user APIs, request approval APIs, moderation APIs, leave group, unsupported file APIs, and all declared call_platform_api actions.

Skipped or residual live-test items:

• edit_message: not implemented because OneBot v11 has no standard edit action.
• upload_file and get_file_url: not implemented as common APIs because portable OneBot v11 file upload/download URL semantics are endpoint-specific.
• kick_member and leave_group: destructive; run only with explicit --destructive and disposable Matcha/OneBot state.
• group.info_updated, message reactions, and message edits are not declared because OneBot v11 does not provide standard equivalents for them.
• Matcha returned ActionFailed for outgoing File segment rendering and did not support merged-forward actions in this run. The adapter keeps the conversion/API implementations because they are valid OneBot/NapCat-style capabilities, but the Matcha live probe records them as skipped.
• Matcha returned an empty get_group_member_list for the test group, so get_group_member_info, mute/unmute, kick, and leave were covered by unit/API-shape tests only in this run.