把 AI Agent 接上微信：能力邊界、帳號風險與完整步驟（Chinese original）

這篇文章教你把 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 等同密碼：不進聊天視窗、不進版本庫。

步驟

1/6啟動精靈，選 Weixin

把 Agent 接上微信的流程示意（六步）

步驟一：啟動設定精靈，選 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 安全與紅隊測試