dsh-wechat-suite

Chat with, monitor, and approve your DSH agents from WeChat.

Two-way text · images · voice · files · video over Tencent's clawbot iLink gateway — no public IP, no port forwarding, no browser.

What it is · 60-second setup · Features · Configuration · Commands · Admin console · Memory · Changelog · 中文说明

🧭 What it is

A DeepSeek Harness bundle that connects a DSH profile to a WeChat personal account over Tencent's clawbot iLink gateway (ilinkai.weixin.qq.com) — the protocol behind Tencent's own WeChat bot clients, driven here against a personal account with no official support.

you (WeChat)  ⇄  iLink  ⇄  wechat-gateway  ⇄  wechat-conversation-node  ⇄  DSH agent session

⚡ 60-second setup

Prerequisites: Node ≥ 22, pnpm, a dedicated WeChat account, and a DSH profile.

dsh plugin --profile <your-profile> add github:PRTS168/dsh-wechat-suite  # 1 install into the profile
pnpm login                                                             # 2 scan the QR, store credentials
pnpm setup                                                             # 3 fill in the allowlist and the rest

Restart dsh web, send the bot a WeChat message, and you should get a reply. Other install paths (Release tarball, build from a checkout) and the step-by-step version live in Quickstart; if something is off, the admin console health report names what is missing.

[!WARNING] One poller per account. iLink allows exactly ONE authenticated poller per bot token. Running a second instance of this bridge — or any other iLink client — against the same WeChat account causes HTTP 403 and dropped messages. Use a dedicated WeChat account, and treat the account as disposable: Tencent may restrict it at any time.

[!IMPORTANT] Two things must be filled in. An allowFrom allowlist entry, and the WEIXIN_BOT_TOKEN / WEIXIN_ACCOUNT_ID / WEIXIN_BASE_URL credentials. Without them the bridge stays safely idle — it never feeds a non-allowlisted message to the model. Everything that looks like <...> is a placeholder you must fill in, and persona presets are not shipped: point agentPreset at a preset of your own under $DSH_HOME/.agent-presets/<name>/.

✨ v5.0 highlights

• QQ is a second platform, not a fork — the bridge now speaks both WeChat and QQ. The platform seam (src/platform/index.ts) is the only place that knows which channel a session belongs to, and each platform keeps its own allowlist, memory file, problem ledger and session namespace. Two conversations on two channels never share a context, and nothing is mirrored between them.
• One console, both platforms — the admin console serves several profiles under one URL (--profiles wechat,qq) with a platform switcher. Every path the console looks at is derived from the platform id, so a profile named web that serves WeChat finds wechat-memory/MEMORY.md and wechat-* sessions instead of rendering empty pages over data that is right there.
• The console can no longer be walked out of its directory — ?platform= used to reach the path builder unchecked, so a crafted name read and wrote cordis.patch.yml files outside profiles/. It is now validated at one choke point, with regression tests that assert the refusal.
• Front-end edits land immediately — admin/index.html is read per request, so a change shows up on refresh instead of hiding until the next console restart.
• A save can no longer break a profile — YAML scalars are quoted by field kind: a QQ AppID like "1234567890" stays a string instead of being written as a number and rejected by the schema on the next load.

The previous release's headline work (gateway transport self-healing, long-poll window cap, earlier long-turn progress) is in the v4.1 release notes. Every change: CHANGELOG.md · older: releases/

🚀 Quickstart

Prerequisites — Node ≥ 22, pnpm, a dedicated WeChat account, a DSH profile.

One-command install

dsh plugin … add runs one pnpm add inside your profile, so any pnpm target works — a git repository, a release tarball, an npm package name, or a local path:

# straight from the repository (no registry needed)
dsh plugin --profile <your-profile> add github:PRTS168/dsh-wechat-suite

# from a release tarball
dsh plugin --profile <your-profile> add \
  https://github.com/PRTS168/dsh-wechat-suite/releases/download/v4.0/dsh-cowork-chatnode-wechat-4.0.0.tgz

# from an npm registry, once published
dsh plugin --profile <your-profile> add <package-name>

Then jump to Pair the WeChat account below. Building from a checkout works the same way:

# 1. install from a checkout
git clone https://github.com/PRTS168/dsh-wechat-suite.git
cd dsh-wechat-suite
pnpm install && pnpm build
dsh plugin --profile <your-profile> add .

# 2. pair the WeChat account once (prints a QR URL to scan)
pnpm login            # → WEIXIN_BOT_TOKEN / WEIXIN_ACCOUNT_ID / WEIXIN_BASE_URL

# 3. fill the remaining placeholders (backup first, then patch the profile)
pnpm setup            # interactive
# or non-interactive; siliconflowKey fills OCR / image-gen / STT / TTS at once
pnpm setup --yes --set allowFrom=<your-wechat-id>@im.wechat --set siliconflowKey=sk-...

Then restart dsh web and send the bot a WeChat message. To bring up the console too:

node admin/server.ts          # or admin/start-admin.bat on Windows
# → http://127.0.0.1:8790/    (token minted into admin/.admin-token)

🎯 Features

[!TIP] /早安 test answering fetch failed? That is almost always a local or system proxy swallowing api.open-meteo.com. The request is retried directly (bypassing the proxy), and when both attempts fail the error names the real cause (ENOTFOUND, ECONNREFUSED, TLS).

🧠 Long-term memory

A cross-session facts file at ${DSH_HOME}/wechat-memory/MEMORY.md, with five sections plus a retired-facts ledger:

## 关于主人
- 主人有两个邮箱：主 primary@example.com、副 secondary@example.com

## 偏好与习惯
## 常用设备与环境
## 待办与承诺
## 重要决定
## 已过期
- 主人在 Example City（已作废）

• How facts get in: ① the model calls remember_fact when the owner says "记一下…", which writes immediately; ② a scheduled consolidation (04:30 by default) folds that day's owner utterances in. Both paths use the same writer: atomic replace + backup first + a 4000-character cap + one audit line per change (memory-log.md).
• How it comes out: injected as background, placed outside the user-message fence — the persona's hard rule is that only fenced content is the owner speaking, so memory can never be mistaken for a command. A file with no facts is not injected at all.
• It is not forgotten: it survives session switches, restarts and compaction; after a compaction the bridge re-injects it on the next message.
• The owner can read and edit it any time: /memory prints it, and the file is plain Markdown — edit it in Notepad and the next injection picks it up.

[!NOTE] Writes are bounded: only facts the owner stated himself and that stay true over time (name, city, schedule, habits, devices and paths, promises, decisions). Passwords / tokens / API keys, one-off arrangements, small talk and the model's own words are never written. One fact is capped at 300 characters (a longer one is truncated, and the receipt says so) and the whole file at 4000 (past that the write is refused outright rather than silently dropped).

⚙️ Configuration

# profile patch (cordis.patch.yml)
plugins:
  dsh-chatnode-wechat:
    allowFrom: ["<your-wechat-id>@im.wechat"] # hard allowlist, REQUIRED, no default
    digestIntervalSec: 300            # heartbeat spacing; the first line lands after ~20s, then this interval
    approvalTimeoutSec: 600           # approval timeout -> default deny
    maxMessageChars: 2000             # WeChat bubble cap (protocol limit)
    sendChunkDelayMs: 1500            # throttle between outbound bubbles
    imageInput: auto                  # auto | native | ocr
    contextPolicy: '{"scheme":"manual"}'   # see releases/v0.3.0-release-notes.md
    # imageInputModel: amd/DeepSeek-V4-Flash-Vision-Exp  # vision route for pictures only
    # agentPreset: wechat             # optional persona preset (lives outside this repo)
    # agentProvider / agentModel: ... # model route for the WeChat agent
    # esp32BaseUrl: http://<esp32-ip>:80   # light control (optional; no built-in default, fill it in to use it)

    # ---- media helpers (all optional; each capability degrades gracefully) ----
    # ocrApiKey / ocrModel: deepseek-ai/DeepSeek-OCR / ocrBaseUrl
    # imageGenApiKey / imageGenModel: Kwai-Kolors/Kolors / imageGenDir
    # sttApiKey / sttModel: XingChenAGI/XingChenASR-V3.2-Ultra
    # ttsApiKey / ttsModel: FunAudioLLM/CosyVoice2-0.5B / ttsVoice: speech:<voice-uri>
    # mediaDir: <dir>     # inbound media (default $DSH_HOME/attachments/wechat)
    # reminderFile / morningFile: <paths, default under $DSH_HOME>

    # ---- email (optional; host + username + password must all be set to send) ----
    # smtpHost: smtp.example.com
    # smtpPort: 465                     # implicit TLS
    # smtpUsername: you@example.com     # also the From address
    # smtpPassword: <app password>
    # smtpFromName: <display name>

    # ---- long-term memory (optional, every key has a default) ----
    # memoryFile: $DSH_HOME/wechat-memory/MEMORY.md
    # memoryInjectEvery: 10             # re-inject the briefing every N messages
    # memoryConsolidateTime: "04:30"    # daily consolidation; empty = never
    # problemFile: $DSH_HOME/wechat-problems.log   # problem ledger

    # ---- gateway tuning (optional) ----
    # gateway tuning keys; longPollTimeoutMs also caps the server's suggested long-poll window
# longPollTimeoutMs / apiTimeoutMs / pollIdleDelayMs / retryDelayMs
    # backoffDelayMs / maxConsecutiveFailures / sessionExpiredPauseMs
    # sendChunkRetries / sendChunkRetryDelayMs
    # rateLimitCircuitOpenMs / rateLimitCircuitWindowMs / rateLimitCircuitThreshold
    # allowCdnHosts: [...]              # SSRF allowlist for media downloads

allowFrom is mandatory and has no permissive default: missing it fails startup, and messages from non-allowlisted senders are logged and ignored — never fed to the model.

[!TIP] Every one of these can be edited in the admin console (beginner mode shows the handful that matter, advanced mode lists them all). The gateway tuning keys used to be a trap: they were declared but never forwarded, so setting them changed nothing, silently. All four key sets (bundle schema / forwarding list / node schema / console fields) must now be equal, and a config-surface test enforces it — which is how the send_email "SMTP 未配置" bug was caught.

llm-deepseek:
  models:
    - id: deepseek-flash
      inputModalities: [text, image]

/识图                 # current mode + routed model
/识图 native          # force image blocks
/识图 ocr             # force OCR text

🎛️ Commands and tools

✅ Approvals

WeChat has no buttons, so permission requests arrive as numbered text and are answered in chat:

#1 needs your confirmation
tool: bash
reason: run a destructive command
reply /yes to allow, /no to reject (1/2 while exactly one is pending)
no reply within 10 minutes -> automatically denied

/yes grants allowed-once; /no rejects; a timeout falls back to the DSH default deny. The bridge answers only requests for the agent it currently drives; everything else is delegated down the answerer chain.

🖥️ Standalone admin console

node admin/server.ts [--port 8790] (admin/start-admin.bat on Windows) starts a loopback-only HTTP console that is not part of the DSH plugin tree — it cannot affect profile boot, and stopping it cannot stop the bridge.

The page has two modes, switched in the top-left corner (the choice is remembered):

Beginner mode — one glance at whether it can work right now; a red dot names what is missing and where to put it:

Advanced mode — every config key, grouped into required / optional, with secret fields masked:

Both screenshots come from a demo instance: every value, path and persona is placeholder data.

Security posture — binds to 127.0.0.1 only · token minted on first start into admin/.admin-token (override with WECHAT_ADMIN_TOKEN) · every API call needs that token · mutations additionally need the x-wechat-admin: 1 guard header, which is a real second factor now (it used to sit behind two return true branches and was therefore unreachable) · the Host header must be a loopback authority, so a DNS-rebinding page cannot reach it · a config file that cannot be read is refused rather than overwritten (that used to replace the whole patch, taking every other plugin's entries with it) · numeric fields are validated server-side, because a quoted "25 分钟" in an integer key makes the plugin fail its schema and takes the whole profile down. Session commands are queued on disk ($DSH_HOME/wechat-admin/queue/) and executed by the bridge within ≤ 2 s; the console also shows the bridge's last reports. The token file is git-ignored.

[!NOTE] Since v0.3.0 there is no in-GUI settings page — the config-api plugin row was removed (see v0.3.0 → Fixed). Configure through cordis.patch.yml or this console.

🧪 Development

pnpm install
pnpm build          # src/ -> lib/ (tsc)
pnpm typecheck
pnpm test           # node --test test/*.test.ts — 255 tests, no WeChat account
pnpm smoke          # manual live-account check
pnpm setup          # interactive config wizard

• test/fake-ilink-server.ts implements the iLink endpoints (long-poll, sendmessage, sendtyping, getconfig, QR login, encrypted CDN download) and replays test/fixtures/inbound.ndjson, so the inbound → session → outbound loop runs offline in CI (.github/workflows/ci.yml).
• Coverage includes gateway dedup (message id and payload fingerprint), inbound routing / media-failure paths / the message envelope, the command surface, the approval bridge, context rotation policies (including the token-budget fallback chain), light control, preset compatibility across both host versions, and boot-safety.test.ts, which pins the "never produce an unhandled rejection" property that used to crash the host.
• Honest gaps (not unit-tested): OCR success/failure branches, the voice-download-to-ASR flow, outbound media upload (the fake server has no /upload), /send, /help, restart resume, and the native-image block itself (vision.test.ts covers the mode/policy decision against a stub catalog; attachments.saveImage runs only on a live host). Live smoke covers the happy paths.
• Test spread (255): memory 36 · node 33 · context-policy 21 · gateway 18 · light 15 · vision 10 · commands 11 · problems 10 · approvals 9 · morning 9 · markdown 9 · outbound-guard 8 · context-report 8 · robustness 8 · patch-config 7 · dedup 6 · inbound-media 6 · resume 5 · config-surface 5 · user-message-envelope 5 · reminders 4 · email 4 · picker 4 · packaging 3 · boot-safety 1
• Guard tests added in v4.0: config-surface (the four config key sets must be equal — this is what stops the "SMTP config dropped by the host" class of bug), problems (ledger dedup, notification rate limiting, log rotation), robustness (refused writes, atomic writes, backup pruning by time, log rotation) and outbound-guard, whose cases are the real text from the 2026-09-13 incident.

⚠️ Known limits

• Reference only — verified on one specific environment (2026-09); portability is not promised. The protocol was reconstructed from existing iLink clients, with synthetic fixtures in-repo.

• Outbound voice/video arrive as file attachments (mp3/mp4), not native bubbles (iLink limitation). silk.ts and gateway.sendVoice() exist as unused spares (silk needs external ffmpeg + pilk).

• Some command receipts still contain emoji that are not stripped to match an emoji-free persona.

• Generated images/voice accumulate under mediaDir/generated (no auto-cleanup yet).

• WeChat silk-encoded voice needs real-device verification (m4a verified).

• Only 1:1 text messaging is targeted; group chats are ignored by design (MVP).

• The rotate-pressure context size is a proxy (serialized event characters), not model tokens; rotate-tokens is the accurate one when the host exposes session projections.

🛡️ Risks

📚 Version history

Full changelog: CHANGELOG.md · all announcements: releases/

🗺️ Roadmap

• Next — group chats (opt-in, risk-heavy), multi-account, a shared-poller proxy to coexist with hermes-agent / OpenClaw.
• Later — WeCom / DingTalk / Feishu bundles reusing the node/ layer.

🙏 Acknowledgements

• Protocol references — the iLink wire details were reconstructed from existing WeChat bot clients (hermes-agent and OpenClaw); synthetic fixtures live in test/fixtures/inbound.ndjson (no real account data), so CI never needs a live account.
• Platform — DeepSeek Harness and the Cordis plugin model (cordis, schemastery) that this bundle extends.
• Services used by the optional media helpers — SiliconFlow (DeepSeek-OCR, Kwai-Kolors, XingChenASR, CosyVoice2) and Open-Meteo (morning weather).
• Thanks — to the DeepSeek Harness and Cordis communities whose plugins this bundle builds on.

📄 License

MIT — see LICENSE.