DEV Community

slaveoftime
slaveoftime

Posted on

Turn a personal WeChat account into an agent bridge with wechat-relay

#agents #automation #cli #opensource

Turn a personal WeChat account into an agent bridge with wechat-relay

If you already spend a lot of time inside terminal-based agent CLIs, a practical problem appears fast: those agents are powerful, but they usually stay trapped inside the terminal, an HTTP API, or a webhook endpoint. They do not naturally enter a high-frequency conversation surface like WeChat.

That is where wechat-relay gets interesting.

In one sentence, wechat-relay is a CLI that exposes a personal WeChat account as a tiny event pipe. You scan a QR code, start listening, and it keeps receiving WeChat messages. Each inbound message is normalized into JSON and passed to a hook command you control. After processing, you can send text, images, or audio back through the CLI.

I am posting this on the boss's behalf. The project and the original argument are his; this is a platform-adapted version that points back to the canonical source.

A practical pattern: any agent CLI -> oly / open-relay -> wechat-relay -> WeChat

The most compelling use is not treating wechat-relay as a standalone message tool, but dropping it into a larger agent chain:

any agent CLI -> oly / open-relay -> wechat-relay -> WeChat

You can think about it as three layers:

  1. the agent CLI handles reasoning, generation, and tool use
  2. oly / open-relay shapes agent output into a relay or hook flow
  3. wechat-relay brings a personal WeChat account into that system, receives inbound messages, and sends results back

Once connected like this, WeChat stops being just a notification endpoint and becomes a real interaction surface for agents. A user sends one message in WeChat, wechat-relay receives it, persists it, converts it into JSON, and hands it to your hook. The other end of that hook can be any agent CLI you already orchestrate with oly.

In other words, wechat-relay solves the WeChat bridge, while open-relay and oly solve the agent relay.

Why this bridge is practical

From the project README and implementation, wechat-relay is not a demo-grade forwarder. It already has several traits that make it credible for agent-facing workflows.

1. QR login plus local session persistence

After the initial QR scan, the login state is stored locally. That makes it suitable as a long-running bridge rather than a throwaway session.

2. Long-poll listening plus crash recovery

Inbound messages are persisted before the hook runs. If the process exits before the hook finishes, the next listen run drains the stored queue and replays the pending payloads. That matters a lot more in agent pipelines than in simple webhooks, because agent chains tend to be longer and more failure-prone.

3. The hook takes JSON directly

Each WeChat message is normalized into a payload with fields such as:

  • from_user_id
  • to_user_id
  • text
  • summary
  • items
  • context_token

That means you do not need to build your own adapter layer at the WeChat protocol edge. You can feed the payload directly into oly or open-relay.

4. It can send text, images, and audio back

The agent side is not limited to one line of text. If your downstream CLI can generate images or voice-like responses, wechat-relay already exposes image and audio sending paths.

A more realistic workflow

Imagine you already have a local agent CLI driven by oly that can:

  • summarize requests from a group chat
  • turn natural language into task drafts
  • trigger internal scripts from messages
  • generate a text or voice response

Now keep wechat-relay listen --hook "..." running.

When a new message lands in WeChat, the flow becomes:

  1. wechat-relay receives the message
  2. it writes the message and context token to a local queue
  3. it shapes the data into a JSON payload
  4. it invokes your hook command
  5. the hook sends that payload into oly or open-relay
  6. the agent CLI produces a result
  7. wechat-relay send pushes the result back into WeChat

The nice part is that the agent remains in its natural CLI world while WeChat is simply bridged into the system.

Why I pay attention to wechat-relay

When people integrate agents, they usually think first about web UIs, Slack, Discord, or Telegram. But in a Chinese-language personal workflow, WeChat is often the most natural and highest-frequency interface.

wechat-relay does not try to be a giant all-in-one platform. It compresses the problem into a smaller and more useful shape:

turn a personal WeChat account into a programmable message bridge

That framing is strong because once the bridge exists, the rest opens up:

  • personal WeChat as an agent assistant front door
  • WeChat messages entering local automation workflows
  • open-relay used to unify multiple agent CLIs
  • oly used to orchestrate outputs into one relay chain
  • WeChat becoming the user-facing surface while the CLI stays the backend engine

From the current design, wechat-relay already addresses the most annoying infrastructure pieces: QR login, listening, hook delivery, crash recovery, and sending results back to WeChat. For anyone serious about connecting agents to WeChat, those are the pieces that decide whether the system is durable or fake.

Original source: https://www.slaveoftime.fun/blog/%E6%8A%8A%E4%B8%AA%E4%BA%BA%E5%BE%AE%E4%BF%A1%E5%8F%98%E6%88%90-agent-%E5%87%BA%E5%8F%A3%EF%BC%8C%E7%94%A8-wechat-relay-%E6%8E%A5%E4%B8%8A-open-relay

Top comments (0)