NoneBot Adapter WxClaw

May 5, 2026 · View on GitHub

NoneBot Adapter WxClaw

✨ 基于 openclaw-weixin 协议的 NoneBot2 微信智能体适配器 ✨

基于 @tencent-weixin/openclaw-weixin 协议实现的 NoneBot2 适配器，用于对接微信智能体（企微客服 iLink 通道）。

📦 安装

nb-cli（推荐）

nb adapter install nonebot-adapter-wxclaw

uv

uv add nonebot-adapter-wxclaw

PDM

pdm add nonebot-adapter-wxclaw

Poetry

poetry add nonebot-adapter-wxclaw

pip（不推荐）

pip install nonebot-adapter-wxclaw

注意: 本适配器需要支持 HTTP 客户端类型的驱动器。请参阅 NoneBot 驱动器文档选择并安装合适的驱动器。

⚙️ 配置

在 NoneBot 项目的 .env 或环境变量中配置：

DRIVER=~xxx  # 需要 HTTP 客户端类型的驱动器，参阅 https://nonebot.dev/docs/advanced/driver

# 账号列表（JSON 数组）
WXCLAW_ACCOUNTS='[{"account_id": "你的bot_id", "token": "你的token", "base_url": "https://ilinkai.weixin.qq.com"}]'

配置项

配置项	类型	默认值	说明
`wxclaw_accounts`	`list[WxClawAccountInfo]`	`[]`	账号列表
`wxclaw_ilink_app_id`	`str`	`"bot"`	iLink App ID
`wxclaw_channel_version`	`str`	`"2.4.1"`	通道版本号
`wxclaw_long_poll_timeout`	`int`	`35000`	长轮询超时（毫秒）
`wxclaw_api_timeout`	`int`	`15000`	API 请求超时（毫秒）
`wxclaw_cdn_base_url`	`str`	`"https://novac2c.cdn.weixin.qq.com/c2c"`	CDN 基础 URL
`wxclaw_bot_agent`	`str`	`""`	Bot 标识（类似 User-Agent），为空时默认 `"OpenClaw"`

账号配置 (`WxClawAccountInfo`)

字段	类型	默认值	说明
`account_id`	`str`	必填	Bot ID
`token`	`str`	`""`	认证 Token（可通过 QR 登录获取）
`base_url`	`str`	`"https://ilinkai.weixin.qq.com"`	API 基础 URL
`enabled`	`bool`	`True`	是否启用

🚀 快速开始

📝 基本回复

from nonebot import on_message
from nonebot.adapters.wxclaw import TextMessageEvent

echo = on_message()

@echo.handle()
async def handle_echo(event: TextMessageEvent):
    await echo.send(event.get_message())

🖼️ 发送媒体

from nonebot import on_command
from nonebot.adapters.wxclaw import Bot, ImageMessageEvent

send_img = on_command("img")

@send_img.handle()
async def handle_send_img(bot: Bot, event: ImageMessageEvent):
    # 发送图片
    await bot.send_image(event.from_user_id, b"<image bytes>")

    # 发送文件
    await bot.send_file(event.from_user_id, b"<file bytes>", "report.pdf")

    # 发送视频
    await bot.send_video(event.from_user_id, b"<video bytes>")

🔐 QR 码登录

适配器支持在插件中发起扫码登录，无需预先配置 token：

from nonebot import on_command
from nonebot.adapters.wxclaw import Adapter

login = on_command("login")

@login.handle()
async def handle_login():
    adapter = Adapter.get_adapter()  # type: ignore

    async with adapter.qr_login(auto_connect=True) as session:
        # session.qrcode_url 是二维码图片 URL，展示给用户扫描
        print(f"请扫描二维码: {session.qrcode_url}")

        # 等待扫描确认
        result = await session.wait()

        if result.connected:
            print(f"登录成功! account_id={result.account_id}")
        else:
            print(f"登录失败: {result.message}")

设置 auto_connect=True 后，登录成功会自动注册 Bot 并开始消息轮询。

📨 支持的消息类型

类型	接收	发送	事件类 / 方法	说明
文本	✅	✅	`TextMessageEvent` / `bot.send_text()`
图片	✅	✅	`ImageMessageEvent` / `bot.send_image()`	CDN 引用可直接转发
文件	✅	✅	`FileMessageEvent` / `bot.send_file()`	转发需先 `fetch_media()`
视频	✅	✅	`VideoMessageEvent` / `bot.send_video()`	转发需先 `fetch_media()`
语音	✅	❌	`VoiceMessageEvent`	协议不支持发送语音
引用	✅	❌	消息段 `type="ref"`	协议不支持发送引用

🔄 转发媒体

图片的 CDN 引用可以直接转发，无需重新上传：

@matcher.handle()
async def handle_forward(bot: Bot, event: ImageMessageEvent):
    await bot.send(event, event.get_message())

文件和视频的 CDN 引用不可直接转发（服务器会静默丢弃），需先通过 bot.fetch_media() 下载后再发送：

@matcher.handle()
async def handle_forward(bot: Bot, event: FileMessageEvent):
    msg = await bot.fetch_media(event.get_message())
    await bot.send(event, msg)

fetch_media() 也可用于下载图片内容进行本地处理：

msg = await bot.fetch_media(event.get_message())
for seg in msg:
    if seg.data.get("content"):
        raw_bytes = seg.data["content"]

🧩 消息段

from nonebot.adapters.wxclaw import MessageSegment

# 文本
MessageSegment.text("Hello")

# 图片（从 CDN 媒体引用构建）
MessageSegment.image(media=cdn_media)

# 文件
MessageSegment.file(media=cdn_media, file_name="doc.pdf")

# 视频
MessageSegment.video(media=cdn_media)

📡 Bot API

所有 API 方法通过 NoneBot 的 call_api 钩子系统路由，支持中间件拦截：

方法	说明
`bot.get_updates()`	长轮询获取消息
`bot.send_message(msg=...)`	发送原始协议消息
`bot.send_typing(to_user_id=...)`	发送正在输入状态
`bot.get_config(user_id=...)`	获取会话配置
`bot.get_upload_url(req=...)`	获取 CDN 上传地址
`bot.download_media(media)`	下载并解密 CDN 媒体
`bot.fetch_media(message)`	下载消息中所有 CDN 媒体到本地 bytes
`bot.prepare_and_upload_file(...)`	加密并上传文件到 CDN

🛠️ 开发

# 安装开发依赖
uv sync --group dev

# 运行测试
uv run pytest tests/

# 代码检查
uv run ruff check nonebot/ tests/
uv run ruff format nonebot/ tests/

# 类型检查
uv run basedpyright nonebot/

许可证

本项目尚未设置许可证。