5分钟完成Hermes-Agent接入微信完整教程

郭智满
Docker
2026年4月15日

如何将自进化 AI Agent 接入微信生态

从零开始、一步一步、手把手带你跑通全流程

目录

一、Hermes Agent 项目概述

1.1 什么是 Hermes Agent

Hermes Agent 是由 Nous Research 团队开发的一款自进化 AI Agent（智能体）。它是目前唯一内置学习闭环的 AI Agent——能够从使用经验中自动创建技能（Skills）、在使用过程中持续优化技能、主动提醒自己保存知识、搜索过往对话历史，并在跨会话间构建对你的深度理解模型。

简单来说，Hermes Agent 就像一个「越用越聪明的 AI 助手」，它不仅能执行任务，还能记住你的偏好、学习新技能，并通过各种消息平台与你保持联系。

1.2 核心特性一览

特性	说明
自学习闭环	Agent 自动管理记忆，任务完成后自动创建技能，技能在使用中自我优化
多平台接入	支持 Telegram、Discord、Slack、WhatsApp、微信、企业微信、钉钉、飞书等 18+ 平台
多模型支持	OpenRouter（200+ 模型）、OpenAI、Anthropic、DeepSeek、阿里云、智谱 AI 等
终端操作能力	可以直接执行终端命令，进行文件操作、代码编写、系统管理等
定时任务	内置 cron 调度器，支持自然语言配置定时任务并投递到任意平台
子 Agent 委派	可生成隔离的子 Agent 进行并行任务处理
灵活部署	支持本地、Docker、SSH、Daytona、Singularity、Modal 等 6 种终端后端
MCP 集成	支持 Model Context Protocol，可连接任意 MCP 服务器扩展能力
语音模式	支持语音输入/输出，包括麦克风模式和消息平台的 TTS 语音回复
技能系统	程序化记忆系统，支持技能市场、自定义技能、技能自动改进

1.3 为什么要将 Hermes Agent 接入微信

微信是中国最核心的通讯和社交平台，将 Hermes Agent 接入微信意味着：

•随时随地对话：在手机微信中直接与 AI Agent 交流，无需打开电脑终端
•无缝工作流：Agent 可以在后台执行任务（如监控服务器、定时报告），结果直接推送到微信
•语音交互：支持微信语音消息的自动转录和 TTS 语音回复
•媒体支持：图片、视频、文件的收发一应俱全
•群组能力：可配置 Agent 在微信群中响应，实现团队协作 AI 助手

1.4 整体架构概览

在深入操作之前，先理解 Hermes Agent 微信接入的整体架构。以下是系统各组件之间的关系：

【系统架构图】

层级	组件	职责
用户层	微信客户端（手机/PC）	用户发送消息、语音、图片等
传输层	腾讯 iLink Bot API	提供 HTTP Long-Polling 消息收发接口
适配层	Weixin Adapter（hermes-weixin）	协议适配、AES 加解密、消息格式转换
网关层	Hermes Gateway	统一会话管理、cron 调度、多平台路由
核心层	AI Agent（大模型 + 工具集）	对话理解、工具调用、技能执行、记忆管理
模型层	LLM Provider（可切换）	提供推理能力（GPT、Claude、Qwen 等）
工具层	Terminal / Web / MCP Tools	执行具体任务（命令行、网页搜索、外部 API）
存储层	Memory / Skills / Session DB	持久化记忆、技能库、会话历史

消息流转路径：微信客户端发送消息 → 腾讯 iLink Bot API → Hermes Gateway（Weixin Adapter 通过 Long-Polling 拉取消息）→ AI Agent 处理 → 生成回复 → 通过 iLink API 发回微信。

二、环境准备与前置条件

2.1 硬件与操作系统要求

项目	最低要求	推荐配置
操作系统	Linux / macOS / WSL2	Ubuntu 22.04+ / macOS 14+
CPU	2 核	4 核+
内存	2 GB	4 GB+
磁盘	5 GB 可用空间	20 GB+ SSD
网络	可访问微信 API 及 LLM Provider	稳定网络连接
Python	3.10+	3.11（推荐）
Node.js	18+	20+ LTS
Git	2.0+	最新版

⚠️ Windows 用户注意

Hermes Agent 不支持原生 Windows 运行。请先安装 WSL2（Windows Subsystem for Linux），然后在 WSL2 终端中执行所有操作。安装命令：wsl –install

2.2 微信账号准备

微信接入使用的是腾讯 iLink Bot API，这是针对个人微信账号的接口。你需要准备：

1.一个可正常使用的个人微信账号（用于扫码登录 Agent）
2.确保微信账号未被限制或封禁
3.手机上安装最新版微信客户端（用于扫描二维码确认登录）

✅ 提示

如果你需要的是企业微信（WeCom）集成，请参考 Hermes Agent 文档中的 WeCom 适配器章节，配置方式有所不同。本文专注于个人微信（Weixin）接入。

2.3 LLM 模型 Provider 准备

Hermes Agent 需要一个 LLM（大语言模型）提供方来驱动 AI 对话能力。Agent 要求模型至少支持 64K tokens 上下文窗口。以下是常用的 Provider 及其配置方式：

Provider	获取方式	适用场景
Nous Portal	hermes model 内 OAuth 登录	订阅制，零配置，推荐新手使用
OpenRouter	openrouter.ai 注册获取 API Key	200+ 模型可选，灵活切换
智谱 AI（Z.AI）	open.bigmodel.cn 注册	国内服务，延迟低
阿里云 DashScope	dashscope.aliyun.com 注册	通义千问系列，国内部署
DeepSeek	platform.deepseek.com 注册	高性价比，推理能力强
Anthropic	console.anthropic.com 注册	Claude 系列模型
OpenAI	platform.openai.com 注册	GPT 系列模型
MiniMax（国内）	minimax.chat 注册	国内镜像端点
Kimi / Moonshot	platform.moonshot.cn 注册	长文本处理能力强

✅ 国内用户推荐

如果你在中国大陆使用，推荐优先选择腾讯AI 大模型、智谱 AI、阿里云 DashScope、DeepSeek 或 MiniMax（国内版）智谱 AI，延迟更低且无需FQ。

三、安装 Hermes Agent

3.1 一键安装（推荐）

Hermes Agent 提供了一键安装脚本，自动处理 Python、Node.js、依赖和 hermes 命令的安装。只需一行命令：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后，重新加载 shell 环境：

# 如果使用 bash

source ~/.bashrc

# 如果使用 zsh

source ~/.zshrc

3.2 验证安装

运行以下命令确认 Hermes Agent 已正确安装：

hermes –version

# 如果安装正确，会显示版本号

# 例如：hermes-agent v0.7.x

如果遇到问题，可以运行诊断命令：

hermes doctor

3.3 手动安装（高级用户）

如果你需要从源码安装或进行自定义配置：

# 1. 克隆仓库

git clone https://github.com/dockercore/hermes-agent.git

cd hermes-agent

# 2. 安装 uv（Python 包管理器）

curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. 创建虚拟环境

uv venv venv –python 3.11

source venv/bin/activate

# 4. 安装依赖

uv pip install -e “.[all,dev]”

# 5. 验证安装

python -m pytest tests/ -q

3.4 安装微信专属依赖

微信适配器需要额外的 Python 包：aiohttp（异步 HTTP）和 cryptography（AES 加解密）。这是微信消息和媒体传输的必要依赖：

pip install aiohttp cryptography

# 可选：用于终端显示二维码（推荐安装）

pip install qrcode

⚠️ 重要提醒

如果不安装 aiohttp 和 cryptography，微信适配器将无法启动，会报错 “Weixin startup failed: aiohttp and cryptography are required”。请务必安装。

四、配置 LLM 模型提供方

4.1 交互式配置（推荐）

Hermes Agent 提供了便捷的交互式配置命令：

hermes model

运行后，系统会引导你选择 Provider 和具体模型。使用方向键选择，回车确认即可。

4.2 常用 Provider 配置示例

4.2.1 OpenRouter（200+ 模型推荐）

# 在 ~/.hermes/.env 中添加

OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxxxxxx

4.2.2 智谱 AI（国内推荐）

# 在 ~/.hermes/.env 中添加

GLM_API_KEY=xxxxxxxxxxxxxxxx

# 或

ZAI_API_KEY=xxxxxxxxxxxxxxxx

4.2.3 阿里云 DashScope

# 在 ~/.hermes/.env 中添加

DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx

4.2.4 DeepSeek

# 在 ~/.hermes/.env 中添加

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx

4.3 验证模型配置

配置完成后，启动 Hermes CLI 验证模型是否正常工作：

hermes

# 进入对话界面后，输入一条测试消息

# 例如：你好，请介绍一下你自己

# 如果 Agent 能正常回复，说明模型配置成功

# 按 Ctrl+C 退出

4.4 切换模型

Hermes Agent 支持随时切换模型，无需修改代码：

# 方法一：命令行切换

hermes model

# 方法二：在对话中使用斜杠命令切换

/model openrouter:anthropic/claude-sonnet-4

五、微信接入完整流程（核心章节）

这是本文最核心的章节，将详细介绍如何将 Hermes Agent 接入微信。整个流程分为四个阶段：

阶段	操作	预计耗时
阶段一	运行 Gateway Setup 向导	2 分钟
阶段二	微信扫码登录	1 分钟
阶段三	配置环境变量	3 分钟
阶段四	启动 Gateway 并验证	2 分钟

5.1 阶段一：运行 Gateway Setup 向导

Hermes Agent 提供了统一的消息平台配置向导。运行以下命令：

hermes gateway setup

运行后，系统会显示所有可用的消息平台列表，使用方向键导航，选择 Weixin（微信）并按回车确认。

向导会依次执行以下步骤：

4.向腾讯 iLink Bot API 请求一个登录二维码
5.在终端中显示二维码（如果安装了 qrcode 包）或提供一个 URL 链接
6.等待你使用微信手机客户端扫描二维码
7.等待你在手机上确认登录
8.自动保存账号凭证到 ~/.hermes/weixin/accounts/ 目录

5.2 阶段二：微信扫码登录

当终端显示二维码后，操作步骤如下：

5.2.1 扫码步骤

9.打开手机微信，进入「发现」→「扫一扫」
10.对准终端中的二维码进行扫描
11.手机上会显示「确认登录」的提示
12.点击「确认」按钮
13.终端会显示成功消息：微信连接成功，account_id=your-account-id

✅ 二维码显示问题

如果终端无法正确渲染二维码，系统会同时提供一个 URL 链接。你可以在浏览器中打开该链接查看二维码，然后用微信扫描。也可以通过安装 qrcode 包（pip install qrcode）来改善终端二维码显示。

5.2.2 二维码过期处理

二维码有有效期限制。如果扫码前二维码已过期，系统会自动刷新（最多 3 次）。如果持续过期，请检查网络连接是否正常。

5.3 阶段三：配置环境变量

扫码成功后，需要配置环境变量以完善微信接入。编辑 ~/.hermes/.env 文件：

5.3.1 必需配置

# ~/.hermes/.env

# 微信账号 ID（扫码登录后自动生成，也可手动填写）

WEIXIN_ACCOUNT_ID=your-account-id

# 微信 Token（通常扫码登录后自动保存）

# WEIXIN_TOKEN=your-bot-token

测试验证：

问题1：帮我看下我在看什么网页

问题2：我电脑开机多久了

问题3：帮我看下磁盘占用

问题4：我的电脑是否安装docker了么?

5.3.2 访问控制配置

# DM（私聊）访问策略：open / allowlist / disabled / pairing

WEIXIN_DM_POLICY=open

# 如果设置为 allowlist，需要指定允许的用户 ID

# WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

# 群组访问策略：open / allowlist / disabled（默认 disabled）

# WEIXIN_GROUP_POLICY=disabled

# 如果群组策略为 allowlist，指定允许的群组 ID

# WEIXIN_GROUP_ALLOWED_USERS=group_id_1,group_id_2

5.3.3 可选高级配置

# iLink API 基础 URL（一般不需要修改）

# WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com

# CDN 基础 URL（媒体文件传输，一般不需要修改）

# WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c

# 主频道配置（用于 cron 任务和通知投递）

# WEIXIN_HOME_CHANNEL=chat_id

# WEIXIN_HOME_CHANNEL_NAME=Home

# 是否将多行消息拆分为多条发送（旧版行为）

# WEIXIN_SPLIT_MULTILINE_MESSAGES=true

5.4 环境变量完整参考

变量名	必需	默认值	说明
WEIXIN_ACCOUNT_ID	是	—	iLink Bot 账号 ID
WEIXIN_TOKEN	是	—	iLink Bot Token（自动保存）
WEIXIN_BASE_URL	否	ilinkai.weixin.qq.com	iLink API 地址
WEIXIN_CDN_BASE_URL	否	novac2c.cdn…	CDN 媒体传输地址
WEIXIN_DM_POLICY	否	open	私聊策略
WEIXIN_GROUP_POLICY	否	disabled	群组策略
WEIXIN_ALLOWED_USERS	否	空	私聊白名单
WEIXIN_GROUP_ALLOWED_USERS	否	空	群组白名单
WEIXIN_HOME_CHANNEL	否	—	主频道 chat ID
WEIXIN_HOME_CHANNEL_NAME	否	Home	主频道显示名

5.5 阶段四：启动 Gateway 并验证

5.5.1 前台启动（用于调试）

首次使用建议在前台运行，方便观察日志和排查问题：

hermes gateway

启动后，你会看到适配器连接日志，确认微信适配器成功连接后，尝试用另一个微信号向已登录的账号发送一条消息，观察 Agent 是否正常回复。

5.5.2 后台服务安装（生产环境推荐）

确认功能正常后，将 Gateway 安装为系统服务，实现开机自启和后台运行：

Linux（systemd）：

# 安装为用户级服务

hermes gateway install

# 启动服务

hermes gateway start

# 查看状态

hermes gateway status

# 查看日志

journalctl –user -u hermes-gateway -f

# 启用 lingering（退出登录后服务继续运行）

sudo loginctl enable-linger $USER

# 或安装为系统级服务（VPS/无头服务器推荐）

sudo hermes gateway install –system

sudo hermes gateway start –system

macOS（launchd）：

# 安装为 launchd agent

hermes gateway install

# 启动服务

hermes gateway start

# 查看状态

hermes gateway status

# 查看日志

tail -f ~/.hermes/logs/gateway.log

5.5.3 服务管理命令速查

操作	命令
前台运行	hermes gateway
安装服务	hermes gateway install
启动服务	hermes gateway start
停止服务	hermes gateway stop
查看状态	hermes gateway status
交互式配置	hermes gateway setup

六、微信适配器深度解析

6.1 消息通信机制：Long-Poll

Hermes Agent 的微信适配器采用 HTTP Long-Polling（长轮询）方式接收消息。与 WebSocket 或 Webhook 不同，Long-Polling 不需要公网 IP 或域名，这是其最大优势。

6.1.1 工作原理

14.连接：适配器启动后，验证凭证并启动轮询循环
15.轮询：调用 iLink API 的 getupdates 接口，设置 35 秒超时。服务器持有请求直到有新消息到达或超时
16.分发：收到的消息通过 asyncio.create_task 并发分发给 AI Agent 处理
17.同步游标：持久化的同步游标（get_updates_buf）保存到磁盘，确保重启后从正确位置恢复

6.1.2 重试与容错策略

情况	行为
首次/第二次临时错误	2 秒后重试
连续 3 次以上错误	退避 30 秒，然后重置计数器
会话过期（errcode=-14）	暂停 10 分钟（可能需要重新登录）
超时	立即重新轮询（正常 Long-Poll 行为）

6.1.3 消息去重

适配器使用消息 ID 在 5 分钟滑动窗口内进行去重，防止网络抖动或重叠的轮询响应导致重复处理。

6.2 媒体文件处理

微信的媒体文件通过加密 CDN 传输，适配器自动处理加解密过程。

6.2.1 接收媒体（入站）

类型	处理方式
图片	从 CDN 下载，AES 解密，缓存为 JPEG
视频	从 CDN 下载，AES 解密，缓存为 MP4
文件	从 CDN 下载，AES 解密，保留原始文件名
语音	优先提取文字转录；否则下载音频（SILK 格式）

6.2.2 发送媒体（出站）

所有出站媒体都经过加密 CDN 上传流程：

18.生成随机 AES-128 密钥
19.使用 AES-128-ECB + PKCS#7 填充加密文件
20.向 iLink API 请求上传 URL（getuploadurl）
21.将密文上传到 CDN
22.发送包含加密媒体引用的消息

6.3 Markdown 格式适配

微信个人聊天不支持完整的 Markdown 渲染。适配器会自动进行格式转换：

•一级标题（# Title）→ 转换为【Title】格式
•二级及以下标题（## Title）→ 转换为 **Title** 加粗格式
•表格 → 重新格式化为标签式键值对列表
•代码块 → 保持原样（微信可以较好地渲染代码块）
•过多空行 → 压缩为双换行

6.4 消息分段策略

微信单条消息的最大长度为 4000 个字符。Hermes Agent 的处理策略如下：

•如果消息在限制内，即使包含多段落或换行，也保持为单条消息发送
•超长消息在逻辑边界处（段落、空行、代码块边界）进行分割
•代码块尽可能保持完整（不在代码块中间切分）
•分段消息之间有 0.3 秒延迟，避免触发微信频率限制

6.5 打字指示器

当 Agent 处理消息时，微信客户端中会显示「对方正在输入…」的状态。适配器通过 iLink API 的 getconfig 接口获取 typing_ticket，缓存 10 分钟，在处理消息期间发送 typing-start/stop 信号。

七、访问控制与安全配置

7.1 私聊访问策略（DM Policy）

策略值	行为说明
open（默认）	任何人都可以与 Agent 私聊
allowlist	仅 WEIXIN_ALLOWED_USERS 中列出的用户 ID 可以私聊
disabled	忽略所有私聊消息
pairing	配对模式（用于初始设置）

7.2 群组访问策略（Group Policy）

策略值	行为说明
open	Agent 在所有群组中响应
allowlist	仅在指定群组 ID 中响应
disabled（默认）	忽略所有群组消息

⚠️ 安全建议

个人微信账号通常加入了很多群组，群组策略默认为 disabled 是有意为之的。如果需要开启群组响应，强烈建议使用 allowlist 模式，仅允许特定群组。

7.3 DM 配对机制

除了手动配置白名单，Hermes Agent 还支持 DM 配对模式。未知用户首次私聊 Agent 时，会收到一个一次性配对码：

# 用户看到：配对码：XKGH5N7P

# 管理员在终端中批准：

hermes pairing approve weixin XKGH5N7P

# 其他配对命令：

hermes pairing list # 查看待批准和已批准用户

hermes pairing revoke weixin user_id # 撤销用户访问权限

配对码在 1 小时后过期，有频率限制，并使用加密随机数生成。

7.4 Token 锁机制

同一个微信 Token 同时只能被一个 Gateway 实例使用。适配器在启动时获取锁，关闭时释放。如果另一个 Gateway 已在使用相同 Token，启动将失败并提示信息错误。

八、高级功能与实战场景

8.1 定时任务（Cron）

Hermes Agent 内置 cron 调度器，可以用自然语言配置定时任务。配合微信接入，你可以实现：

# 在 Hermes 对话中直接说：

“每天早上 9 点，检查 Hacker News 的 AI 新闻并发送摘要到微信”

# Agent 会自动创建 cron 任务

# 结果通过 WEIXIN_HOME_CHANNEL 投递到微信

其他定时任务场景举例：

•每天定时检查服务器健康状态，异常告警推送到微信
•每周自动生成项目进度报告，发送到微信群
•每日天气预报推送
•定期数据库备份状态通知

8.2 后台任务

在微信对话中使用 /background 命令，可以启动后台任务。Agent 在后台独立执行，不阻塞你的主对话：

/background 检查集群中所有服务器，报告宕机的服务器

# Agent 立即确认：

# 🔄 后台任务已启动: “检查集群中所有服务器…”

# Task ID: bg_143022_a1b2c3

# 任务完成后，结果自动推送到微信

8.3 技能系统（Skills）

Hermes Agent 的技能系统是其自进化能力的核心。你可以：

•浏览和安装社区技能：hermes skills search kubernetes
•Agent 完成复杂任务后自动创建新技能
•技能在使用过程中自动改进
•在微信对话中直接调用技能：/

8.4 MCP 服务器集成

通过 Model Context Protocol（MCP），你可以扩展 Agent 的能力边界。例如连接 GitHub MCP 服务器：

# 在 ~/.hermes/config.yaml 中添加

mcp_servers:

github:

command: npx

args: [“-y”, “@modelcontextprotocol/server-github”]

env:

GITHUB_PERSONAL_ACCESS_TOKEN: “ghp_xxx”

配置后，Agent 就可以在微信对话中帮你查看 GitHub Issues、创建 PR、管理仓库等。

8.5 语音模式

微信适配器支持语音消息的收发：

•接收语音：如果微信提供了文字转录，自动使用转录文本；否则下载 SILK 格式音频
•发送语音：需要安装语音扩展包（pip install “hermes-agent[voice]”）
•可选安装 faster-whisper 用于本地语音转文字

8.6 微信对话中的常用命令

命令	功能说明
/new 或 /reset	开始全新对话
/model [provider:model]	查看或切换模型
/personality [name]	设置 Agent 人格
/retry	重试上一条消息
/undo	撤销上一轮对话
/stop	中断当前正在执行的任务
/compress	手动压缩对话上下文
/background	启动后台任务
/usage	查看本次会话的 Token 使用情况
/voice [on\|off]	控制语音回复开关
/help	显示所有可用命令
/	调用已安装的技能

九、故障排查指南

9.1 常见问题与解决方案

问题	解决方案
Weixin startup failed: aiohttp and cryptography are required	运行 pip install aiohttp cryptography 安装依赖
WEIXIN_TOKEN is required	运行 hermes gateway setup 完成扫码登录，或手动设置 WEIXIN_TOKEN
WEIXIN_ACCOUNT_ID is required	在 .env 中设置 WEIXIN_ACCOUNT_ID，或运行 hermes gateway setup
Another local Hermes gateway is already using this Weixin token	先停止另一个 Gateway 实例，每个 Token 只允许一个轮询
Session expired (errcode=-14)	登录会话已过期，重新运行 hermes gateway setup 扫码
QR code expired during setup	系统会自动刷新二维码（最多 3 次），检查网络连接
Bot doesn’t respond to DMs	检查 WEIXIN_DM_POLICY，若为 allowlist 需确认发送者在白名单中
Bot ignores group messages	群组策略默认 disabled，需设置 WEIXIN_GROUP_POLICY=open 或 allowlist
Media download/upload fails	确认已安装 cryptography，检查是否能访问 novac2c.cdn.weixin.qq.com
Messages appear duplicated	检查是否有多个 Gateway 实例在运行
Blocked unsafe URL (SSRF protection)	出站媒体 URL 指向内网地址，仅允许公网 URL

9.2 诊断工具

Hermes Agent 提供了内置诊断工具：

# 全面诊断

hermes doctor

# 检查 Gateway 服务状态

hermes gateway status

# 查看 Gateway 日志（Linux）

journalctl –user -u hermes-gateway -f

# 查看 Gateway 日志（macOS）

tail -f ~/.hermes/logs/gateway.log

9.3 日志级别调整

如果需要更详细的日志来排查问题，可以在 ~/.hermes/config.yaml 中调整：

display:

tool_progress: verbose # off | new | all | verbose

十、最佳实践与优化建议

10.1 安全最佳实践

23.生产环境务必设置访问白名单（WEIXIN_DM_POLICY=allowlist）
24.使用 Docker 或 SSH 后端实现终端隔离，防止 Agent 执行危险命令
25.定期检查配对列表，撤销不再需要的用户访问权限
26.不要在 .env 文件中存储敏感的业务数据
27.使用系统服务（systemd/launchd）运行，而非 screen/tmux

10.2 性能优化建议

28.选择低延迟的 LLM Provider（国内用户优先选择国内模型服务商）
29.合理设置会话重置策略，避免上下文过长导致响应变慢
30.利用 /compress 命令手动压缩长对话上下文
31.复杂任务使用 /background 后台执行，避免阻塞主对话
32.VPS 部署时启用 systemd lingering，确保退出终端后服务持续运行

10.3 微信特有注意事项

•个人微信群组策略默认 disabled，这是有意设计，避免 Agent 在大量群组中意外响应
•微信消息长度限制 4000 字符，超长消息会自动分段
•微信不完整支持 Markdown，表格和部分格式会被适配器自动转换
•语音消息会优先使用微信自带的文字转录
•媒体文件传输通过加密 CDN，依赖 cryptography 库
•会话过期后需要重新扫码，建议关注 Gateway 日志中的过期提醒

10.4 推荐部署架构

场景	推荐方案	说明
个人使用	本地 macOS/Linux + launchd/systemd	成本低，适合日常使用
稳定运行	$5/月 VPS + systemd system 服务	7×24 在线，低成本高可用
团队使用	Docker 部署 + 反向代理	隔离性好，便于管理
弹性伸缩	Modal / Daytona 无服务器模式	空闲时几乎零成本

十一、完整操作速查卡

以下是从零到完成微信接入的全部命令汇总，可作为速查参考：

# ==========================================

# Hermes Agent 微信接入速查卡 dockercore

# ==========================================

# 第一步：安装 Hermes Agent

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

source ~/.bashrc

# 第二步：安装微信依赖

pip install aiohttp cryptography qrcode

# 第三步：配置 LLM Provider

hermes model

# 第四步：验证基础功能

hermes

# 输入测试消息后 Ctrl+C 退出

# 第五步：配置微信接入

hermes gateway setup

# 选择 Weixin → 扫码登录

# 第六步：编辑环境变量（按需）

nano ~/.hermes/.env

# 第七步：前台测试

hermes gateway

# 第八步：安装为服务

hermes gateway install

hermes gateway start

# 验证服务状态

hermes gateway status

十二、总结与展望

通过本文的详细指导，你已经完成了 Hermes Agent 与个人微信的完整接入。让我们回顾一下整个流程的关键节点：

步骤	关键操作	状态检查
环境准备	确认 OS、Python、Node.js 版本	hermes doctor
安装 Agent	一键脚本安装	hermes –version
安装依赖	pip install aiohttp cryptography	import aiohttp（无报错）
配置模型	hermes model 选择 Provider	hermes 中发送测试消息
微信接入	hermes gateway setup + 扫码	终端显示连接成功
环境变量	编辑 ~/.hermes/.env	检查配置项
启动服务	hermes gateway start	hermes gateway status
功能验证	通过微信发送消息测试	Agent 正常回复