Astral Bridge

Astral Bridge connects QQ, through NapCat's OneBot v11 reverse WebSocket, and optionally Telegram, through the Telegram Bot API, to one long-lived Astral Code app-server session. It also exposes MCP tools so the agent can reply back to chat platforms, send files, mention people, recall/delete messages, and fetch recent conversation context when needed.

This project is intended for self-hosted personal or team automation. It is not affiliated with QQ, Tencent, NapCat, OneBot, Telegram, or Astral Code.

Features

• Receive QQ private and group messages from NapCat over OneBot v11.

• Receive Telegram private, group, supergroup, and channel-post messages through long polling.

• Route every accepted message into one Astral app-server thread, either configured explicitly or auto-created on first startup.

• Trigger group messages only when the bot is mentioned, replied to, or the chat is configured as always-trigger.

• Trigger every message from configured private QQ or Telegram users/chats.

• Store allowed conversation history locally in SQLite for later MCP lookups.

• Include compact inbound context: platform, chat/group name/id, sender id, nickname, username/card, message id, reply id, trigger kind, unread count, and attachment metadata.

• Support app-server turn/steer when the current Astral thread already has an active turn.

• Expose Streamable HTTP or stdio MCP tools for QQ and Telegram replies, history, media, files, mentions, and replies to specific message ids.

• Accept generic external event webhooks and forward them into the current Astral session.

• Expose a read-only Web UI for connection status, routing, recent messages, recent conversations, and recent bridge logs.

• Add a random 3-5 second delay before outbound QQ send actions.

Related MCP server: NapCat MCP Server

Requirements

• Node.js 26 or newer. The bridge uses node:sqlite.

• pnpm 10 or newer.

• A running Astral Code app-server.

• NapCat configured with OneBot v11 reverse WebSocket.

• Optional: a Telegram bot token from BotFather if Telegram support is enabled.

Quick Start

pnpm install
cp examples/config.example.json config.json
pnpm dev -- --config ./config.json

Build for production:

pnpm build
pnpm start -- --config ./config.json

Point NapCat's OneBot v11 reverse WebSocket to:

ws://127.0.0.1:6701/onebot/v11/ws

If the bridge is running in Docker or on another host, replace the host and port with the address reachable from NapCat, for example:

ws://bridge:6701/onebot/v11/ws

Configuration

Start from examples/config.example.json:

{
  "onebot": {
    "host": "127.0.0.1",
    "port": 6701,
    "path": "/onebot/v11/ws",
    "accessToken": null,
    "actionTimeoutMs": 10000
  },
  "mcp": {
    "transport": "stdio",
    "host": "127.0.0.1",
    "port": 6710,
    "path": "/mcp"
  },
  "astral": {
    "appServerUrl": "ws://127.0.0.1:4222",
    "authToken": null,
    "threadId": "auto",
    "cwd": null,
    "modelConfigPath": null,
    "modelProvider": null,
    "model": null,
    "includeImageInputs": false,
    "rotateThreadOnStart": false
  },
  "qq": {
    "enabled": true,
    "botUserId": "REPLACE_WITH_BOT_QQ",
    "allowedGroupIds": ["REPLACE_GROUP_ID"],
    "alwaysTriggerGroupIds": [],
    "allowedPrivateUserIds": ["REPLACE_USER_ID"],
    "triggerKeywords": ["astral", "bot"],
    "recordUntriggered": true
  },
  "telegram": {
    "enabled": false,
    "botToken": "REPLACE_WITH_TELEGRAM_BOT_TOKEN",
    "botUsername": "REPLACE_WITH_TELEGRAM_BOT_USERNAME",
    "allowedChatIds": ["REPLACE_TELEGRAM_CHAT_ID"],
    "alwaysTriggerChatIds": [],
    "triggerKeywords": ["astral", "bot"],
    "recordUntriggered": true,
    "pollTimeoutSeconds": 25,
    "pollIntervalMs": 1000,
    "apiBaseUrl": "https://api.telegram.org"
  },
  "tts": {
    "enabled": false,
    "protocol": "openai_speech",
    "apiKey": null,
    "baseUrl": "http://127.0.0.1:8765/v1",
    "model": "mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16",
    "voice": null,
    "format": "mp3",
    "language": "Chinese",
    "referenceAudioPath": "/absolute/path/on/tts-server/atri.wav",
    "referenceText": "参考音频中准确说出的文字",
    "timeoutMs": 60000
  },
  "embedding": {
    "enabled": false,
    "baseUrl": "http://127.0.0.1:8766/v1",
    "apiKey": null,
    "model": "qwen3-embedding-0.6b",
    "dimensions": 1024,
    "batchSize": 32,
    "timeoutMs": 60000,
    "queryInstruction": "Given a user query about instant-message history, retrieve messages that answer the query or express the same meaning."
  },
  "externalEvents": {
    "enabled": true,
    "path": "/api/events",
    "authToken": "REPLACE_WITH_EVENT_API_TOKEN",
    "maxBodyBytes": 65536,
    "debounceMs": 2000,
    "maxBatchEvents": 20,
    "maxBatchBodyChars": 6000
  },
  "storage": {
    "dbPath": "./data/astral-bridge.db",
    "mediaDir": "./media",
    "downloadMedia": false
  }
}

Environment overrides:

When astral.threadId / ASTRAL_BRIDGE_THREAD_ID is empty or auto, bridge creates one Astral thread on first use and stores the id in SQLite store_meta. To rotate an auto-managed thread manually, call POST /api/astral/thread/rotate with the same bearer token as the external event API. If a turn is currently active, the endpoint returns 409 instead of interrupting it.

recordUntriggered controls whether non-triggering messages from allowed conversations are stored. Keeping it enabled lets the agent fetch surrounding context without forwarding every group message into Astral. For QQ this also stores member-to-member poke notices in allowed groups; only pokes targeting the bot trigger an Astral turn.

Telegram uses long polling. On startup the bridge calls deleteWebhook so Telegram will allow getUpdates. Send /chatid to the bot in a private chat, group, supergroup, or topic to get the exact chat_id; this command works even before the chat is allowlisted. All other Telegram interaction requires the chat id to be present in telegram.allowedChatIds or telegram.alwaysTriggerChatIds.

Web UI

When HTTP MCP is enabled, open:

GET /ui

The dashboard polls GET /api/dashboard/state and shows NapCat/Astral connection status, the active Astral turn id when one is running, configured routing, external event API status, recent conversations, recent stored messages, and recent bridge logs.

Astral MCP Setup

For stdio MCP, build first and point Astral at the compiled entrypoint:

[mcp_servers.bridge]
command = "node"
args = ["/path/to/astral-bridge/dist/index.js", "--config", "/path/to/astral-bridge/config.json"]

Use node directly instead of a package-manager wrapper. stdio MCP requires stdout to contain only JSON-RPC messages.

For container or multi-process deployments, run HTTP MCP:

{
  "mcp": {
    "transport": "http",
    "host": "0.0.0.0",
    "port": 6710,
    "path": "/mcp"
  }
}

Then configure Astral:

[mcp_servers.bridge]
url = "http://bridge:6710/mcp"

The bridge exposes both QQ and Telegram tools from the same MCP endpoint, so register it once. Tool names remain platform-specific, for example mcp__bridge__qq_send_group_message and mcp__bridge__telegram_send_message. QQ tools are registered only when qq.enabled is true, Telegram tools only when telegram.enabled is true, and voice tools only when tts.enabled is true.

MCP Tools

query_messages is intended for complex recall and analysis rather than ordinary recent-message lookups. Its code argument is an async JavaScript function body that must return JSON. Each invocation runs in a separate process against a read-only SQLite connection and is terminated after 30 seconds. Helper limit values are defaults rather than hard maxima; Astral applies its normal MCP-output context limit after the bridge returns the result.

return search("电路图", { platform: "qq", context_limit: 2 });

When embeddings are enabled, search() defaults to hybrid FTS5 plus semantic recall. Semantic and hybrid searches are asynchronous, while explicit lexical searches retain the synchronous FTS5 path:

return await search("上次谁说显卡坏了", { mode: "hybrid", platform: "qq", context_limit: 2 });

For custom KNN joins, use await embed(text) and bind the returned float32 vector directly to sql(). The vector is never printed into the tool result:

const vector = await embed("串流画面问题");
return sql(
  "SELECT m.id AS row_id, m.text, e.distance FROM message_embeddings e JOIN messages m ON m.id = e.message_row_id WHERE e.embedding MATCH ? AND e.k = ? ORDER BY e.distance",
  vector,
  20,
);

Message writes and FTS5 updates never wait for the embedding service. New and historical messages are queued in SQLite and indexed in the background. If the local model is unavailable, semantic/hybrid calls return a clear error and mode: "lexical" remains available.

Use schema() from inside the query when exact table fields are needed. Use sql() only for joins, grouping, time buckets, and other shapes not covered naturally by the higher-level helpers.

Group Administration

Group administration tools are grouped to keep the MCP tool list small. Call qq_group_admin_help to discover action names and required fields. Disbanding groups is intentionally not implemented; leave_group only makes the bot leave the group.

All group-specific administration tools reject group_id values outside qq.allowedGroupIds when that allowlist is configured. Actions that mutate group state require confirm: true; use that only after the user explicitly asks for the operation.

Mentions, Images, and Replies

Use parts when a group message needs exact ordering of text, mentions, and images:

[
  { "type": "text", "text": "请 " },
  { "type": "at", "user_id": "TARGET_QQ" },
  { "type": "text", "text": " 看一下 " },
  { "type": "image", "file": "/workspace/result.png" }
]

Reply to a specific QQ message by passing reply_to_message_id with the OneBot message_id from the inbound prompt or one of the history tools.

Images in outbound messages use OneBot image segments. Non-image files use NapCat-compatible upload_group_file and upload_private_file actions.

Telegram text messages use ordered parts for mentions:

[
  { "type": "text", "text": "请 " },
  { "type": "mention", "username": "alice" },
  { "type": "text", "text": " 看一下；也同步给 " },
  { "type": "mention", "user_id": "123456789", "text": "Bob" }
]

Use telegram_send_rich_message when a Telegram reply needs structured formatting such as headings, lists, tables, collapsible details, code blocks, or formulas. Pass exactly one of html or markdown:

{
  "chat_id": "-1001234567890",
  "html": "<h2>Summary</h2><ul><li>Done</li><li>Next step</li></ul>",
  "reply_to_message_id": "123",
  "message_thread_id": "456"
}

For Telegram files, call telegram_send_file for images and non-images alike. This sends through Telegram sendDocument, preserving the original file quality. Telegram rich message media blocks are intended for HTTP/HTTPS URLs; local /workspace and /app/media files should still be sent with telegram_send_file:

{
  "chat_id": "-1001234567890",
  "file": "/workspace/result.png",
  "caption": "结果图",
  "reply_to_message_id": "123",
  "message_thread_id": "456"
}

Message Routing

The bridge only forwards messages from configured QQ targets or Telegram chat ids:

• Group messages: forwarded when the bot is at-mentioned or the message replies to a bot message.

• Keyword messages: in any allowed QQ/Telegram group or private chat, messages containing any configured trigger keyword are forwarded. Keyword matching is case-insensitive.

• Always-trigger group messages: for group ids in qq.alwaysTriggerGroupIds, every non-bot message is forwarded, even without an @mention or reply.

• Private messages: forwarded for every message from configured private users.

• Other allowed conversation messages: optionally stored when recordUntriggered is true, but not forwarded to Astral.

• Telegram /chatid: always answered directly so you can discover the current Telegram chat.id before editing the allowlist.

• Telegram group/supergroup/channel messages: forwarded when the bot is mentioned, the message replies to a bot message, or the chat id is in telegram.alwaysTriggerChatIds.

• Telegram private messages: forwarded for every message from configured private chat ids.

• /stop: in any allowed QQ/Telegram group or private chat, interrupts the active Astral turn and replies in the same conversation.

Every forwarded turn includes conversation_unread_count, the number of stored messages in the same group/private conversation since the previous Astral prompt, including the current trigger message. The agent can call qq_get_unread_messages or telegram_get_unread_messages when that context is useful; it does not need to call it for every message.

External Event API

When HTTP MCP is enabled, the same HTTP server can accept generic external events:

GET /api/events/schema

Returns a machine-readable OpenAPI 3.1 schema with examples and curl usage.

POST /api/events
Authorization: Bearer REPLACE_WITH_EVENT_API_TOKEN
Content-Type: application/json

{
  "source": "minecraft:survival-main",
  "event_type": "player_join",
  "title": "Player joined",
  "body": "Steve joined the server",
  "actor": { "id": "uuid", "name": "Steve" },
  "metadata": { "world": "world", "x": 120, "y": 64, "z": -33 }
}

The bridge queues attention-worthy events, merges short bursts into one bounded Astral turn, and submits that merged event to the current Astral thread using the same queue as QQ messages. Set wants_agent_attention to false to validate and accept an event without forwarding it into Astral. Batching is controlled by externalEvents.debounceMs, externalEvents.maxBatchEvents, and externalEvents.maxBatchBodyChars.

Request fields:

Successful requests return 202 Accepted with { ok, accepted_for_astral, event }. Unauthorized requests return 401 when externalEvents.authToken is configured.

Astral App-Server Behavior

The bridge talks to Astral app-server over WebSocket and uses:

• initialize

• thread/resume

• turn/start

• turn/steer when the current thread already has an active turn

When starting a turn, the bridge requests approvalPolicy = "never" and sandboxPolicy = { type = "dangerFullAccess" }. If you use this mode, isolate Astral at the container, VM, or host level and only mount directories you are willing to expose.

Server approval requests for command execution and file changes are canceled by default. QQ sending should happen through the MCP tools and Astral MCP tool approval settings, not through the bridge approving arbitrary app-server actions.

Docker and OrbStack

The generic bridge image is defined by Dockerfile.

OrbStack deployment templates live under deploy/orbstack. They include:

• bridge: OneBot reverse WebSocket plus Streamable HTTP MCP.

• astral-code: an Ubuntu-based Astral app-server runtime with mapped config, binary, source, workspace, and build cache directories.

• napcat: NapCat Docker service.

Copy deploy/orbstack/.env.example to .env, fill in your local values, and read the Chinese deployment guide at deploy/orbstack/README.md before running the compose stack. It covers required QQ/Telegram/Astral settings, persistent volumes, memory storage, and the memory phase2 sandbox option.

Security Notes

• Do not commit real QQ ids, app-server tokens, API keys, NapCat WebUI tokens, SQLite databases, downloaded media, or local config files.

• Bind services to loopback unless you intentionally need LAN access.

• The app-server danger-full-access mode is powerful. Use a dedicated container or host account and mount only the workspace/config directories needed by the agent.

• Review allowed groups and private users before exposing the bot to busy chats.

Development

pnpm install
pnpm typecheck
pnpm build

Project layout:

src/                 Bridge source
examples/            Example JSON config
deploy/orbstack/     Self-hosted OrbStack deployment template
data/                Runtime SQLite state, ignored by git
media/               Runtime media cache, ignored by git

Acknowledgements

The design of query_messages was inspired by Obelisk and its agent-first approach to retrieval: give the agent a programmable query surface over a local SQLite index, then let the agent decide how to search, inspect context, and follow the evidence. Thank you for showing how much more capable retrieval becomes when the agent owns the query plan.

License

Licensed under the Apache License, Version 2.0. See LICENSE.