這篇文章教你把 AI Agent 接進個人微信(WeChat)。做完你會得到：一個能在微信私訊裡對話的 agent——支援語音、圖片、檔案，回覆帶「輸入中」提示,Hermes 平台名稱叫 weixin。全程不需要公網 IP 或 webhook:訊息走 long polling,由你機器上的 gateway 主動拉。預計耗時 20–30 分鐘，其中掃碼配對本身只要幾秒。
先把醜話說在前面，細節在下一節：個人微信的自動化處於平台條款的灰色地帶，帳號存在被限制的風險。這不是恐嚇，是這個渠道的真實屬性，決定接之前請先讀完「服務條款與帳號風險」一節。另外，如果你要接的是企業微信(WeCom),那是另一個 adapter、另一套規則，不在本文範圍。
這裡用 Hermes Agent 當範例，概念(取得憑證、決定誰能說話、常駐程序、驗證第一則訊息)對任何渠道通用。如果你還沒接過任何渠道，建議先做 Telegram 這篇——它最簡單，適合先證明整條鏈路。
這個渠道的能力邊界
Hermes 官方文件為每個平台列了能力矩陣，微信這行是這樣:
| 平台 | 語音 | 圖片 | 檔案 | 主題 | 表情回應 | 輸入中 | 串流 |
|---|---|---|---|---|---|---|---|
| Telegram | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
| WhatsApp(橋接) | — | ✅ | ✅ | — | — | ✅ | ✅ |
| WhatsApp Cloud API | ✅ | ✅ | ✅ | — | — | ✅ | — |
| Weixin(微信) | ✅ | ✅ | ✅ | — | — | ✅ | — |
| Feishu / Lark | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
(取自官方 Messaging Gateway 文件的平台對比表。「語音」指 TTS 語音回覆與/或語音訊息轉錄。)
支援的：語音訊息(微信提供轉錄文字時直接使用，否則下載原始音訊)、圖片、影片、檔案——媒體經微信的加密 CDN 傳輸,adapter 自動完成 AES-128 加解密，不需要你配置;Markdown 原樣保留(標題、表格、程式碼區塊);超過 4,000 字元的訊息在邏輯邊界自動分段；處理時顯示「輸入中」狀態；入站訊息以 5 分鐘滑動視窗去重。不支援的：主題(thread)、表情回應、串流輸出。
還有一條比矩陣更重要的邊界,官方文件用警告框寫著：掃碼登入建立的是騰訊 iLink Bot API 的 bot 身分(形如 a5ace6fd482e@im.bot),不是一個可以隨意腳本化的普通個人帳號。實際後果:
- 這個 bot 身分通常無法像普通聯絡人一樣被拉進普通微信群;
- 對多數 bot 型帳號,iLink 不會把普通微信群的訊息事件(包括對你掃碼那個個人帳號的 @)送給 gateway;
- @你掃碼用的個人帳號，不等於 @這個 bot——它們是兩個身分;
- 實務上，多數部署只有私訊能穩定運作。群組訊息收不到時，限制在 iLink 這一側，不是 Hermes 壞了。
所以對微信渠道的合理期待是：一個私訊為主、能力完整的 agent;不是一個能在所有群裡暢所欲言的群組 bot。
服務條款與帳號風險
誠實版評估，不含法律意見:
- 微信對個人帳號自動化的執法向來嚴格，使用非官方自動化手段的帳號有被限制的先例與風險。你的帳號能不能用、怎麼用，最終由騰訊的條款與風控決定，不由任何工具決定。
- Hermes 這條路走的是騰訊自己的 iLink Bot API(官方文件中對個人微信的 bot 通道),並且如上所述，它給你的是一個獨立的 bot 身分,而不是把你本人的帳號變成機器人。這與「用非官方用戶端直接操縱個人帳號」是不同的形態。
- 即便如此，請把帳號風險當作真實存在:掃碼的帳號與 bot 身分都受騰訊風控約束；登入 session 會過期(錯誤碼
-14),過期後要重新掃碼；行為異常(高頻訊息、大量主動觸達)在任何平台上都是風控信號。 - 務實的做法：不要用你唯一的、承載全部人脈的主帳號去掃碼；不要批量發訊息、不要對沒先聯繫你的人主動觸達；接之前自己讀一遍騰訊當期的相關條款。這篇文章只負責把技術事實擺出來，風險決策在你。
如果這些約束你不能接受，選擇其他渠道:Telegram 有成熟的官方 Bot API,飛書/Lark 有完整的開放平台，企業微信走企業管理——都比個人微信的灰色地帶安穩。
前置需求
- 一個個人微信帳號，以及裝了微信的手機(掃碼用)。
- Hermes Agent 已安裝(安裝步驟見這篇),模型已配置。
- 依賴套件:
aiohttp與cryptography。官方安裝路徑下，用文件給的這行補齊(含 terminal QR 渲染):
python -c "import pm; pm.sync_venv(['messaging'], explicit=True)"
- 知道憑證會落在哪裡：掃碼後
account_id、token、base_url 自動存進~/.hermes/weixin/accounts/,環境變數在~/.hermes/.env。環境變數與 .env 裡的 token 等同密碼：不進聊天視窗、不進版本庫。
步驟
步驟一：啟動設定精靈，選 Weixin
hermes gateway setup
預期輸出:方向鍵操作的互動清單，已配置的平台會有標記。選擇 Weixin 後，精靈向 iLink Bot API 請求 QR code,並把它渲染在 Terminal（終端機） 裡(或給出一個 URL)。QR 過期會自動刷新，最多 3 次。
步驟二：用手機微信掃碼並確認
打開手機微信的掃一掃，掃描 terminal 裡的 QR code,並在手機上確認登入。
預期輸出(官方文件的字樣):
微信连接成功,account_id=your-account-id
精靈會把 account_id、token、base_url 自動存到 ~/.hermes/weixin/accounts/,不需要手抄。記下你的 account_id,以及精靈顯示的 bot 身分——之後別人要私訊的是這個 bot,不是你掃碼的個人帳號。
步驟三：設定環境變數，先把門關小
在 ~/.hermes/.env 至少寫入 account ID,並立刻收緊存取政策:
WEIXIN_ACCOUNT_ID=your-account-id # 掃碼登入回傳的 ID
WEIXIN_DM_POLICY=allowlist # 預設是 open(任何人都能私訊),務必改掉
WEIXIN_ALLOWED_USERS=user_id_1 # 逗號分隔的微信使用者 ID
# 選用:排程與通知的首頁渠道
WEIXIN_HOME_CHANNEL=chat_id
WEIXIN_HOME_CHANNEL_NAME=Home
預期輸出:無——存檔即可。注意 WEIXIN_DM_POLICY 的出廠預設是 open:這比 gateway 層級的「預設拒絕一切」寬得多,微信 adapter 自己的政策放著不管，就是誰都能跟你的 Bot 說話。下一節會講怎麼取得要放進 allowlist 的使用者 ID。
步驟四：啟動 gateway,發第一則訊息
hermes gateway
預期輸出:日誌顯示 weixin adapter 恢復已存憑證、連上 iLink API、開始 long polling。然後用一個微信帳號(例如你自己的)私訊那個 bot 聯絡人,發一句話:
預期行為:先看到「輸入中」狀態，然後收到回覆。回覆保留 Markdown 格式；超過 4,000 字元會分成多段。到這裡，渠道→gateway→模型→渠道這條鏈路就通了。
步驟五：收集並登記要放行的使用者 ID
WEIXIN_ALLOWED_USERS 是入站過濾器，不是邀請系統——你不能替別人掃碼，只能過濾誰的訊息會被處理。官方文件給的實務流程:
- 先用精靈完成配對，記下連上的 iLink bot 帳號;
- 請每個要放行的人私訊那個 bot(不是私訊你掃碼的個人帳號);
- 從
~/.hermes/logs/gateway.log或 inbound 事件裡讀出傳送者的使用者 ID; - 把 ID 加進
WEIXIN_ALLOWED_USERS,重啟 gateway。
預期輸出:日誌中能看到每則入站訊息的傳送者 ID;重啟後，名單外的人發來的私訊不再被處理。
步驟六：裝成常駐服務(選用)
hermes gateway install # Linux systemd / macOS launchd / Windows 排程工作
hermes gateway start
hermes gateway status
預期輸出:status 回報服務執行中。Linux 要開機自啟用 sudo hermes gateway install --system。macOS 注意:launchd plist 記錄的是安裝當下的 PATH,之後新裝的工具(ffmpeg、新版 Node)要重跑 hermes gateway install 刷新。gateway 是一個程序服務所有平台，之後再接 Telegram、飛書都不用多開程序。
誰可以跟你的 Bot 說話
微信這一路的存取控制有三個層面，層層都要你自己動手:
渠道政策(adapter 層):WEIXIN_DM_POLICY 四個值——open(任何人都能私訊，出廠預設)、allowlist(只處理 WEIXIN_ALLOWED_USERS 名單內的 ID)、disabled(忽略所有私訊)、pairing(配對模式)。群組另有 WEIXIN_GROUP_POLICY,預設 disabled——官方刻意如此，因為個人微信群多、而 iLink bot 身分多半也收不到群事件；你若把它設成其他值，啟動日誌會出現 WARNING。
gateway 層:Hermes 的通用安全預設是拒絕所有不在 allowlist、也未經 DM 配對的使用者；配對流程是陌生人私訊 Bot 拿到一次性配對碼，你在機器上核准:
hermes pairing approve weixin <CODE>
hermes pairing list
hermes pairing revoke weixin <id>
配對碼 1 小時過期、有速率限制、密碼學亂數產生。全域的 GATEWAY_ALLOW_ALL_USERS=true 可以一次全開——官方自己標明不建議；對一個能執行終端機指令的 Bot,這等於把機器交給所有陌生人，不要這樣做。
分級(admin / 一般使用者):進了門的人再做權限切分。admin 能跑所有已註冊的斜槓指令，一般使用者能自由聊天、但只能跑你開放的指令，保底永遠有 /help 與 /whoami。設定在 ~/.hermes/config.yaml 的 gateway.platforms.weixin.extra(allow_from、allow_admin_from、user_allowed_commands,群組 scope 另有對應鍵);沒設 allow_admin_from 時該 scope 不啟用分級。
最後是內容層：接上渠道的 agent 會讀到不可信的第三方文字,Prompt Injection（提示詞注入） 是真實威脅——私訊內容、檔案內容都可能夾帶操縱指令的文字。allowlist 收得越緊，這個攻擊面越小；危險指令則靠聊天內的 /approve、/deny 關卡。Sandbox（沙箱） 不是可選項。
常見錯誤與修法
| 症狀 | 原因 | 修法 |
|---|---|---|
啟動報 aiohttp and cryptography are required | 依賴沒裝齊 | 跑前置需求裡的 pm.sync_venv(['messaging']) 指令 |
啟動報 WEIXIN_TOKEN is required | 沒完成掃碼登入 | 重跑 hermes gateway setup 掃碼，或手動設定 token |
Another local Hermes gateway is already using this Weixin token | 同一 token 只允許一個 gateway 實例輪詢 | 先停掉另一個實例 |
一段時間後無回應，日誌有 errcode=-14 | 登入 session 過期,adapter 暫停 10 分鐘 | 重跑 hermes gateway setup 掃新 QR code |
主動發訊(cron/通知)失敗:ret=-2、prepare failed | 對方的 context token 過期(太久沒 inbound 訊息) | 請對方先私訊 bot 一句話(或重新配對),之後主動發訊恢復 |
| Bot 不回私訊 | WEIXIN_DM_POLICY=allowlist 但傳送者不在名單 | 按步驟五把對方 ID 加進 WEIXIN_ALLOWED_USERS 後重啟 |
| 群組訊息全被無視 | 群政策預設 disabled;且 iLink bot 身分多半收不到普通群事件 | 日誌完全沒有入站群事件的話，限制在 iLink 側，換渠道或接受私訊形態 |
| 語音訊息變成文字 | 微信提供轉錄時 adapter 直接用文字 | 預期行為，不需修 |
憑證在 .env,adapter 卻沒啟動 | platforms.weixin.enabled: false 明確停用，優先級高於環境變數憑證 | 移除該鍵或改 true;啟動日誌會有 WARNING 說明憑證被忽略 |
/platform list 顯示 paused-by-breaker | 連續可重試失敗觸發熔斷，且刻意不自動恢復 | 確認上游(iLink)恢復後 /platform resume weixin |
日誌永遠是第一現場:~/.hermes/logs/gateway.log。
下一步
- 想接更安穩的渠道:Telegram(官方 Bot API,最簡單)、飛書/Lark(能力矩陣全勾)、WhatsApp(橋接與官方 Cloud API 兩條路)
- 群組場景是硬需求、微信這條路走不通：考慮企業微信(WeCom)adapter,或改用飛書群組 + @mention 的模式
- 接完渠道想驗證整條鏈路:裝好 Agent 工具的頭十分鐘
- Bot 能執行指令，圍欄就不能省:Sandbox（沙箱）、AI 安全與紅隊測試