Menu
NapCat QQ bot messaging — send messages, read events, manage groups, handle friends via CLI
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
| name | napcat-cli |
| description | NapCat QQ bot messaging — send messages, read events, manage groups, handle friends via CLI |
| version | 2.0.0 |
| author | Ezra |
| license | MIT |
| platforms | ["linux"] |
| allowed-tools | ["terminal","read_file","write_file"] |
| metadata | {"category":"messaging","source":"napcat-cli"} |
Access QQ bot capabilities via the napcat CLI tool (Python-based, installed on PATH). No FUSE mount required — commands talk directly to the NapCat daemon.
Use this skill when you need to interact with a QQ bot instance:
napcat CLI is installed (on PATH after uv tool install napcat-cli or pip install).napcat daemon status).:18800, HTTP on :18801).napcat status).All operations are CLI commands. No FUSE mount needed.
# Check status
napcat status
# Read events and alerts
napcat events
napcat alerts
# Send messages
napcat send private <user_id> -m "message"
napcat send group <group_id> -m "message"
# Poke a group member
napcat group poke <group_id> <user_id>
# Read group/friend lists
napcat group list
napcat group members <group_id>
napcat friend list
# Manage daemon
napcat daemon start
napcat daemon stop
napcat daemon status
| Command | Description |
|---|---|
napcat status | Bot login status |
napcat events | Recent 50 events from cache (JSON array) |
napcat alerts | Pending alert categories |
napcat friend list | Friend list with metadata |
napcat group list | Bot's group membership |
napcat group members <gid> | Members of a group |
napcat group info <gid> | Group info |
napcat group essence <gid> | Essence messages |
napcat file list-group <gid> | Group file list |
| Command | Description |
|---|---|
napcat send private <uid> -m "msg" | Send private message |
napcat send group <gid> -m "msg" | Send group message |
napcat send group <gid> --at <uid> -m "msg" | @ someone in group |
napcat send <type> <target> --image <path> | Send image (PIL-generated, local file, or URL) |
napcat send <type> <target> --file <path> | Send file |
| Command | Description |
|---|---|
napcat group poke <gid> <uid> | Poke a member ✅ |
napcat group mute <gid> <uid> [seconds] | Mute a member |
napcat group unmute <gid> <uid> | Unmute |
napcat group kick <gid> <uid> | Kick a member |
napcat group admin <gid> <uid> [set/remove] | Set/remove admin |
napcat group rename <gid> <uid> <card> | Set group card |
napcat group remark <gid> <remark> | Set group remark |
napcat group announce <gid> -m "msg" | Send announcement |
| Command | Description |
|---|---|
napcat friend info <uid> | User info |
napcat friend remark <uid> <remark> | Set remark |
napcat friend add <uid> | Send friend request |
napcat friend delete <uid> | Remove friend |
| Command | Description |
|---|---|
napcat recall <msg_id> --group <gid> | Recall group message |
napcat recall <msg_id> | Recall private message |
| Command | Description |
|---|---|
napcat api <endpoint> | Call raw NapCat HTTP API |
napcat api <endpoint> -o value | Extract value field |
napcat api <endpoint> -o raw | Raw JSON output |
| Command | Description |
|---|---|
napcat daemon start/stop/status | Manage watch daemon |
napcat config get <key> | Read config key |
napcat config set <key> <value> | Set config key |
napcat translate --from zh --to en "text" | QQ translation (may not work) |
napcat ocr <image_path> | OCR on image |
napcat fs | Show skills-fs FUSE mount status |
| Command | Description |
|---|---|
napcat setup | Interactive wizard: configure NapCat connection, skills-fs, and wake agent |
napcat setup --non-interactive | Non-interactive setup with all defaults (useful in scripts) |
napcat setup --yes | Auto-accept all prompts without confirmation |
napcat wake [reason] | Trigger the configured wake_command (e.g. wake Hermes) |
napcat wake --dry-run | Print the rendered wake command without executing it |
napcat config get <key> | Read a config key (api_url, token, wake_command, etc.) |
napcat config set <key> <value> | Set a config key |
napcat setup)Runs an interactive wizard that configures:
http://127.0.0.1:18801) and token (validated against the running instance).~/.napcat-data.hermes (default), custom, or none. For Hermes, sets hermes -c <session> -z '<prompt>' -s napcat-cli --yolo as the wake command.~/.hermes/skills/napcat-cli/ for Hermes to discover.Use --non-interactive to skip all prompts (uses defaults). Use --yes to auto-confirm actions.
napcat wake)Triggers the configured wake_command from ~/.napcat-data/config.json. Typical use: wake Hermes to process new QQ messages.
napcat wake — triggers with reason "MANUAL".napcat wake "NEW_MESSAGE" — passes a specific reason into the template ($REASON, ${REASON}, or {reason}).napcat wake --dry-run — prints the rendered command without executing (useful for debugging).wake_command is configured, the command fails with a suggestion to run napcat setup.The daemon also calls napcat wake automatically when wake_on_event is enabled and new events arrive.
napcat config)Reads and writes configuration stored in ~/.napcat-data/config.json.
napcat config get <key> — prints the current value of a config key.napcat config set <key> <value> — updates a config key.Common keys: api_url, token, wake_command, wake_on_event, ws_port, http_port, group_trigger_word, private_trigger, skills_fs_enabled, skills_fs_mountpoint, skills_fs_binary, skills_fs_config.
When replying to QQ messages via the napcat-cli, load the persona file first:
~/.napcat-data/skills/persona.md
You become 吉他张 (CartierRR) — NOT an AI assistant. Use the persona's tone, slang (法, 中英混杂), and emotional style. Do NOT say "我是AI", "请问", "谢谢" on QQ.
Activate persona when:
Do NOT activate persona on: Weixin, Discord, Web, and other non-QQ Hermes channels.
napcat status to verify the bot is online.napcat daemon status to verify the daemon is running.napcat subcommand.napcat recall may return "NapCat 内核响应超时" (kernel timeout). This is a NapCat kernel issue, not a bot-offline issue. The bot stays online (verify with napcat status). Workaround: retry after a delay or use the raw API directly.
napcat translate fails with "API 'qq_translate' is not supported by this NapCat instance". NapCat needs a translation plugin for this. Do not retry — it's a feature gap, not a bug.
napcat group poke works. The same operation via HTTP API (send_group_poke) fails. Always use the CLI for poke operations.
napcat daemon only supports start, stop, and status. There is no log, restart, or reload. To restart, stop then start.
napcat config get/set works with internal NapCat config keys, not environment variables. NAPCAT_API_URL etc. are env vars, not config keys.
napcat events returns the last 50 cached events from memory. Most are heartbeat meta_events. Filter them:
events = json.loads(subprocess.check_output(["napcat", "events"]))
messages = [e for e in events if e.get('post_type') != 'meta_event']
napcat alerts shows pending alert categories. To read actual alert data, read the alert files directly from ~/.napcat-data/alerts/:
NAPCAT_CLI_NEW_MESSAGE.alert — new messagesNAPCAT_CLI_NEW_POKE.alert — poke eventsNAPCAT_CLI_NOTICE.alert — system noticesNAPCAT_CLI_NEED_WAKE_UP.alert — wake-up triggersnapcat send returns the message_id on success (e.g., Sent message_id=123456).--at <uid> to @ someone in group messages.--image or --file for media. For local paths, the CLI handles them directly (no file:/// prefix needed via CLI).send_like (via napcat group liking) is rate-limited by QQ. Error 1400 = rate limit.QQ has a maximum message length (~200 chars). Long text (e.g., command output, logs) will be truncated or fail to send. Workarounds:
--image--fileBefore issuing API calls, check napcat status. If offline:
napcat daemon statusnapcat daemon startA FUSE mount is available at ~/.napcat-data/skills (check with napcat fs).
It provides a virtual filesystem view of all napcat operations, alerts, events,
and per-group/per-friend message directories. The CLI is the primary interface;
the FUSE mount is supplementary and useful for Agent filesystem access patterns.
napcat status — confirms bot is online.napcat daemon status — confirms daemon is running.napcat events — shows recent events (filter out heartbeats).napcat alerts — shows pending alerts.message_id.napcat group members <gid> to verify changes.