hxa-channel-daemon

Lightweight local daemon that bridges external chat channels (Telegram today, WeChat soon) to an HXA Connect bot identity. Run on your own machine — your Telegram bot token and WeChat session never touch the hub.

Useful when you already have an AI agent in an HXA org (for example a local @slock-ai/daemon running Claude Code) and want that same agent to receive and answer messages coming in from Telegram or WeChat.

How it works

  Telegram / WeChat   ⇄   hxa-channel-daemon   ⇄   HXA Connect hub   ⇄   your agent
       (external)             (your machine)         (organization)        (also local)

The daemon authenticates to the hub as a bridge bot (its own bot token), and every inbound message is DMed from the bridge bot to a forward-to bot (your agent). Agent replies are delivered back to the originating chat.

Install

npm install -g hxa-channel-daemon
# or just run it on demand:
npx hxa-channel-daemon --help

Usage

Create one bot in your HXA org for the bridge itself, grab its token, and have the name of the agent bot you want to forward to. Then:

Telegram

npx hxa-channel-daemon \
  --channel telegram \
  --telegram-token   1234567890:ABCDEFGH... \
  --hxa-url          https://your.hub/connect \
  --hxa-key          <bridge_bot_token> \
  --forward-to       <agent_bot_name>

On first start, send any message from Telegram to the bot and the daemon binds that chat as the owner. Subsequent messages from the same chat are forwarded to the agent; messages from other chats are ignored.

Optionally pass --owner-chat-id <id> to pre-bind.

WeChat

Login is via QR code printed in the terminal on first run — scan with your personal WeChat account to bind. The session is cached under ~/.hxa-channel-daemon/weixin/accounts/<label>.json, so subsequent launches skip the QR until the session expires.

npx hxa-channel-daemon \
  --channel weixin \
  --hxa-url      https://your.hub/connect \
  --hxa-key      <bridge_bot_token> \
  --forward-to   <agent_bot_name>

Optional --weixin-account <label> lets you run multiple bridges against different WeChat accounts on the same host (e.g. personal and work). Default label is default.

Override the session cache dir with HXA_CHANNEL_WEIXIN_STATE_DIR=/path.

MVP scope: text-only. Images / voice / files received from WeChat are ignored (they still arrive at the hub as nothing). Replies from the agent are flattened from Markdown to plain text before delivery (WeChat doesn't render markup).

Environment

| Variable | Effect | |---|---| | HXA_CHANNEL_DEBUG=1 | verbose logs | | HTTPS_PROXY / ALL_PROXY | honored when talking to api.telegram.org |

Design notes

• Single DM conversation per daemon instance. Run a second daemon (with a separate bridge bot + separate Telegram bot) if you need a second user to share the agent. This keeps identity unambiguous — the hub never sees a message whose origin it can't attribute.
• MVP scope: DM only. Group-chat @mention routing is designed into the shape of InboundMessage but not wired up yet.
• No state file. Agent reply → external routing uses the last inbound chat id; if the daemon restarts mid-conversation, the owner auto-binds again on the first new message.

License

MIT