OneBot Adapter

Connect OpenClaw to OneBot protocol for QQ bot integration. Use when receiving or sending QQ messages via NapCat or other OneBot servers.

Connect OpenClaw to OneBot protocol servers like NapCat for QQ bot functionality.

Quick Start

1. Configure Connection

Set OneBot server URL in environment or config:

export ONEBOT_WS_URL="ws://127.0.0.1:3001"
export ONEBOT_HTTP_URL="http://127.0.0.1:3000"
export ONEBOT_TOKEN="your-token"

2. Receive Messages

Use the WebSocket listener script to receive QQ messages:

python scripts/onebot_ws_listener.py

3. Send Messages

Use HTTP API to send messages:

from scripts.onebot_client import OneBotClient

client = OneBotClient()
client.send_private_msg(user_id=123456, message="Hello!")
client.send_group_msg(group_id=789012, message="Group message")

Connection Modes

WebSocket (Recommended)

• Real-time bidirectional communication
• Receives events instantly
• Supports both sending and receiving

HTTP

• Request-response model
• Good for simple sending
• Requires polling for receiving

Common Tasks

Get Login Info

client.get_login_info()

Get Friend/Group List

client.get_friend_list()
client.get_group_list()

Handle Messages

See references/message-handling.md for message parsing and response patterns.

NapCat Specific

NapCat is a OneBot11 implementation based on NTQQ.

Default ports:

• WebSocket: 3001
• HTTP: 3000
• WebUI: 6099

Token authentication is optional but recommended for public deployments.

Troubleshooting

Connection refused: Check if OneBot server is running and ports are correct.

Authentication failed: Verify token matches OneBot server configuration.

Message not delivered: Check user_id/group_id exists and bot has permission.