Check QQ login status, NapCat connection, and monitored targets.

Returns the bot's QQ account, online status, uptime, list of monitored groups and friends, and buffer statistics. Use this to verify the server is running correctly before calling other tools. Not the same as get_group_list or get_friend_list — this is a health check, not a query.

Read-only. No side effects. Safe to call at any time.

List all QQ groups the bot has joined.

Returns group IDs, names, and member counts for every group the bot is a member of. Use this to discover valid group IDs for send_message, get_recent_context, or other group-targeting tools. For friend list use get_friend_list instead. For batch name resolution use batch_get_recent_context.

Read-only. No side effects.

List all QQ friends of the bot account.

Returns user IDs and nicknames. Use this to discover valid friend IDs for send_message or get_recent_context with target_type="private". For group list use get_group_list instead.

Read-only. No side effects.

Retrieve recent messages for one group or friend from the in-memory buffer.

Returns buffered messages (backfill from history + real-time via WebSocket) as raw message objects with sender info, content, timestamps, and image URLs. This is the primary tool for reading chat context. For multiple targets at once, use batch_get_recent_context instead (fewer API calls). To archive old messages and free buffer space, use compress_context.

Messages older than the buffer window are lost. Call compress_context periodically to preserve important conversations.

Read-only. No side effects on the chat.

Query recent messages for multiple groups/friends in one call.

More efficient than calling get_recent_context multiple times: uses at most 2 OneBot API calls (one for group names, one for friend names) regardless of how many targets you query. Each target's messages are returned independently with errors for unmonitored targets.

Use this when you need to read context from 2+ conversations at once. For a single target, use get_recent_context instead (simpler).

Read-only. No side effects.

Send a text message to a QQ group or friend, optionally waiting for a reply.

This is the primary tool for sending text messages. It supports message splitting via </分段> tags or punctuation-based chunking. The message is sent immediately and the bot's own message is written to the buffer.

To split a reply into multiple messages, insert </分段> at split points. For example: "Hi</分段>How are you?" sends two separate messages.

Behavior: rate-limited (60s dedup window), duplicate content within 60s is blocked. After sending, blocks until a reply arrives (unless wait_reply=False). The reply includes the full message objects.

Use send_image for images, send_voice for audio, send_file for files. For a standalone wait without sending, use wait_for_reply.

Block until a new message arrives from a specific group or friend.

Use this as a standalone follow-up after send_message (with wait_reply=False) or when you need to wait for a reply without sending first. Returns only messages from others (not the bot's own). Times out after timeout seconds (max 300).

If you want to send a message AND wait for a reply in one call, use send_message with wait_reply=True instead — it's simpler.

Read-only. No side effects on the chat.

Send a base64-encoded image to a QQ group or friend.

For text messages use send_message. For audio use send_voice. For files use send_file. This tool only sends images.

Behavior: same rate limiting and dedup as send_message. The image is sent as a QQ-native image (not a file attachment).

Mutates the chat by sending an image.

Send a base64-encoded voice message to a QQ group or friend.

NapCat auto-converts common audio formats (MP3, WAV, AMR, OGG, FLAC) to SILK for QQ voice playback. For text use send_message, for images use send_image, for files use send_file.

Behavior: same rate limiting as send_message. Voice messages cannot be replied to (no reply_to parameter).

Mutates the chat by sending a voice message.

Download a file from a URL and send it to a QQ group or friend.

Downloads the file to a temporary directory, uploads it to QQ, then cleans up. Supports any file type. For text use send_message, for images use send_image, for audio use send_voice.

Behavior: requires a publicly accessible URL (no auth). Download timeout is 60 seconds. The file is sent as a QQ file attachment.

Mutates the chat by sending a file.

Compress all buffered messages for a target into a single summary, freeing buffer space.

This is destructive: raw messages are replaced by a compressed summary. Once compressed, individual messages cannot be recovered from the buffer. Use this after get_recent_context when you want to archive old conversations and make room for new messages.

The compression uses the client LLM (via MCP sampling) to generate a concise summary. Falls back to rule-based compression if LLM is unavailable.

Destructive: permanently replaces raw messages with a summary.

Render a QQ-style dark-mode chat screenshot starting from a given message.

Uses Playwright to render messages as an iPhone-style QQ chat screenshot and returns a base64-encoded PNG image. The screenshot starts from the given message_id and renders downward. If messages fit on one screen, earlier messages are prepended to fill it (bottom-aligned). If they overflow, later messages are cut off.

Requires: Playwright browser (lazy-started on first call). If the message_id is not found in the buffer, returns an error.

Use get_recent_context first to find valid message_ids. The screenshot is read-only and does not modify the chat.

Read-only. No side effects on the chat.

Manually trigger the wake activation sequence to verify it works.

Sends a test keystroke to the opencode window. Use this to verify the wake system is functional. On Linux, this always returns False (wake is Windows-only). Does not affect any QQ messages.

Read-only with respect to QQ. May type text into opencode window.

Simulate a wake trigger to debug the wake pipeline.

Creates a fake message from the given target_id and target_type and checks: is the callback registered, does any rule match the fake message, is the monitor currently pending or running. Then invokes the callback to exercise the full activation pipeline. The response fields (callback_set, matches_rules, pending, running, callback_invoked) tell you exactly where the pipeline is broken. Use diagnose_wake for a read-only snapshot without triggering the callback.

Read-only with respect to QQ. May invoke the wake callback.

Return the current state of the wake monitor for debugging.

Shows: whether the monitor is running, all active rules (with target_type, target_id, keywords, enabled state, ignore_if_focused), whether the message callback is registered on the context manager, and total buffered messages across all targets. Use this as the first step when wake is not working — if monitor_created or callback_set is False, the monitor was never initialized. For a more aggressive test that injects a fake message, use debug_wake_pipeline instead.

Read-only. No side effects.

Add a wake rule: when a matching message arrives, opencode wakes up.

When a message matches this rule, the agent is activated and the message context is made available. Use add_wake_rule to create rules, list_wake_rules to see them, remove_wake_rule to delete, and set_wake_enabled to toggle.

Rules are persisted to disk and survive restarts. Keywords are optional: empty list matches any message. target_id=None matches any source.

Mutates the wake rule configuration.

List all configured wake rules.

Shows each rule's target type, ID, keywords, enabled state, and focus-ignoring setting. Use add_wake_rule to create rules, remove_wake_rule to delete, and set_wake_enabled to toggle.

Read-only. No side effects.

Remove a wake rule by index.

Use list_wake_rules to get the current indices. Rules are renumbered after removal. This permanently deletes the rule; to temporarily disable, use set_wake_enabled instead.

Destructive: permanently removes a wake rule.

Enable or disable a specific wake rule (or all rules if index is None).

Use list_wake_rules to see current indices and states. Disabled rules are skipped during wake matching but remain in the configuration. Use remove_wake_rule to permanently delete a rule.

Mutates the wake rule configuration.

Manually set the wake pending state to block or allow new wakes.

When pending=True, incoming messages will NOT trigger wake even if they match a rule. When pending=False, messages trigger wake normally. Use this to prevent duplicate wakes while the agent is already working.

Mutates the wake monitor state.

Return the current wake configuration (window title patterns, shortcut).

Use set_wake_config to modify these settings. Changes take effect immediately for future wake activations.

Read-only. No side effects.

Configure the wake target window and focus shortcut.

window_title_patterns: substrings to match against the window title (e.g., ["opencode", "cursor"]). The wake system focuses the first matching window. focus_shortcut: keyboard shortcut to focus the input box (e.g., "ctrl+l"). Changes take effect immediately.

Mutates the wake configuration. Persisted across restarts.

Mute a member in a QQ group.

group_id: the QQ group number. user_id: the QQ number to mute. duration: mute time in seconds (default 600 = 10 minutes). Requires bot to have admin privileges in the group. Use unmute_member to reverse.

Mutates the group by muting a member.

Unmute a member in a QQ group (set mute duration to 0).

group_id: the QQ group number. user_id: the QQ number to unmute. Requires bot to have admin privileges. Use mute_member to mute. Unmuting a member who is not muted is a no-op (returns success). Call get_group_member_list first to verify a member is currently muted before deciding to unmute.

Mutates the group by unmuting a member.

Kick a member from a QQ group.

group_id: the QQ group number. user_id: the QQ number to kick. reject_add_request: if True, rejects future join requests from this user. Requires bot to have admin privileges. This is irreversible for the current session — the user can re-join if not rejected. Consider using mute_member (temporary) as a less drastic alternative. The bot cannot kick group owners or admins of equal rank; returns error in those cases.

Destructive: removes a member from the group.

Set a member's group nickname (card). Empty string clears it.

group_id: the QQ group number. user_id: the QQ number. card: the new nickname text. Requires bot to have admin privileges.

Mutates the member's group card.

Send a group announcement (notice) to a QQ group.

group_id: the QQ group number. content: the announcement text (plain text only, no rich media). Requires bot to have admin privileges. The notice appears in the group's announcement bar for all members. Unlike send_message, this is persistent and visible to members who join later. Avoid posting notices too frequently — QQ may rate-limit or throttle excessive notices.

Mutates the group by posting an announcement.

Recall (delete) a message sent by the bot.

message_id: the message ID to recall (obtained from send_message's or send_image's message_id in the response). Only works for messages sent by the bot itself within approximately 2 minutes of sending, or anytime if the bot has admin/owner privileges in the group. Cannot recall messages sent by other users. Use this to undo accidental sends. The message is permanently deleted for all members.

Destructive: permanently deletes a message.

List all members of a QQ group.

Returns for each member: user_id (QQ number), nickname, card (group nickname), role (owner/admin/member), join_time (unix timestamp), last_sent_time, level, and title (group honorific). Use get_group_member_info for a single member's detailed info. Use get_group_list to discover valid group_id values. The response includes a count field for the number of members. Large groups (>200 members) may be paginated by QQ; the result includes all members QQ returns in one call.

Read-only. No side effects.

Get detailed info for a specific QQ group member.

Returns: user_id, nickname, card (group nickname), role (owner/ admin/member), join_time (unix timestamp), last_sent_time, level, title (group honorific), and age/gender if available. Unlike get_group_member_list which returns all members, this gives a single member's full profile. Use this to look up a specific user before deciding to mute, kick, or set their card. Use get_group_member_list when you need to enumerate all members.

Read-only. No side effects.

Add a timer task that triggers a wake with the given message at scheduled times.

Supports cron expressions and fixed-interval scheduling:

• cron_expr: "0 8 * * *" = every day at 8am

• interval_seconds: 3600 = every hour

• once: if True, auto-removes after first trigger

At least one of cron_expr or interval_seconds must be provided. Use list_timers to see active timers, remove_timer to cancel.

Mutates the timer configuration. Timers persist across restarts.

Remove a timer task by index.

Use list_timers to get current indices. Timers are renumbered after removal. This permanently deletes the timer.

Destructive: permanently removes a timer.

List all configured timer tasks.

Shows each timer's index, message, cron expression, interval, once flag, and next run time. Use add_timer to create timers, remove_timer to cancel.

Read-only. No side effects.