在 Windows 环境下，Hermes Agent 主要支持通过 WSL2 进行安装和运行。按照正确的方式配置后，CLI 与微信通道都可以正常接入和验证。
本文介绍如何在 WSL2 中安装 Hermes Agent，并接入微信通道，实现本地调试与移动端收发。
为什么 Windows 场景优先走 WSL2
Hermes 官方安装脚本主要面向 Linux、macOS 和 WSL2，Windows 原生终端不在常用安装路径里。进入 WSL2 可减少环境分叉和兼容性变量，后续升级、迁移和问题定位也更省时间。
- 安装路径统一：官方一行脚本直接可用，避免额外适配层
- 依赖管理更稳：Python、pip、shell 工具链在 Linux 语义下更一致
- 文档对齐成本低：大部分命令示例无需二次改写
- 后续扩展顺滑：消息网关、定时任务、容器隔离等能力都能沿同一环境推进
安装前检查：先把基础环境跑通
先把最关键的四个条件确认完，再执行安装命令，成功率会明显提高。系统层错误就在系统层处理，不要带进 Hermes 配置阶段。
- Windows 侧：确认已启用 WSL2，并且已有可用发行版（例如 Ubuntu）
- WSL2 侧：确认 python3 与 pip 可用，终端能正常访问外网
- 模型侧：准备好可用 provider（例如 OpenAI、Anthropic、MiniMax、Qwen 等）及对应凭据
- 上下文窗口：目标模型需支持至少 64K context，避免启动后被拒绝
可先在 WSL2 里做一次快速检测：
python3 --version
pip --version
curl --versionWSL2 内安装 Hermes Agent
安装流程按安装 → 重新加载 shell → 首次配置顺序执行即可。这样每一步都有明确的验证点，出现异常时更容易定位到具体阶段。
执行安装命令
在 WSL2 终端执行安装脚本：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash安装过程中，会自动检测是否已安装 OpenClaw，并提示是否要将 OpenClaw 的配置 import 进来。
首次配置模型与工具
安装完成后，提示配置 Hermes（这里选择 quick setup）：
选择模型 provider：
选择消息平台（这里先跳过）：
配置完成后，提示是否进入 hermes chat（在终端 CLI 发起聊天）：
在终端的交互聊天：
后续也可以执行以下命令，对模型、工具等内容进行再次配置，或进入会话聊天：
hermes model
hermes tools
hermeshermes model：选择 provider 与模型hermes tools：确认工具开关，避免默认能力过宽或过窄hermes：进入会话，检查欢迎信息、模型与工具列表是否正常展示
微信通道接入：从 CLI 到手机可用
Hermes 的 Weixin 适配器基于腾讯 iLink Bot API，消息通过长轮询接收，不需要公网 endpoint 或 webhook（适用于个人微信）。这意味着本地 WSL2 环境就能完成接入验证，适合先在个人环境完成首次联通测试。
补充一点：Hermes 虽然提供了 WEIXIN_GROUP_POLICY 等群聊配置项，但按当前微信 clawbot 的实际能力，群聊暂不支持；落地时建议先按私聊通道设计。
安装微信适配器依赖
先在当前环境安装必需依赖，qrcode 按需安装即可。这一步的价值是提前补齐微信适配器运行所需组件，避免网关启动后再回头补依赖。
pip install aiohttp cryptography
pip install qrcode- aiohttp + cryptography：微信适配器必需依赖
- qrcode：用于终端内显示二维码，属于可选增强
运行网关向导完成扫码登录
hermes gateway setup在向导里选择 Weixin 后，流程通常是：请求二维码 → 手机扫码 → 手机确认登录 → 自动保存账号信息。完成后，系统会输出连接成功提示并写入账号凭据。
选择信息平台 - 微信：
微信扫码登录成功后，选择消息授权方式（按个人需要选择，可选择白名单方式 only allowed listed user IDs）：
配置关键环境变量并启动网关
至少需要配置 WEIXIN_ACCOUNT_ID。生产或日常自用更推荐白名单策略，先放行指定账号，再决定是否开放：
# ~/.hermes/.env
WEIXIN_ACCOUNT_ID=your-account-id
WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=your_weixin_user_id
# 仅用于临时测试，不建议长期开启
# GATEWAY_ALLOW_ALL_USERS=true配置文件位置与查看方式：
- 文件路径：~/.hermes/.env（这里的 ~ 代表当前 Linux 用户 home 目录）
- 在 WSL2 中查看：cat ~/.hermes/.env
- 文件不存在时：可先执行 touch ~/.hermes/.env，再用编辑器写入配置
这几个配置项分别控制：
- WEIXIN_ACCOUNT_ID：微信账号 ID，扫码登录后生成；网关启动微信通道时必须存在
- WEIXIN_DM_POLICY：私聊授权策略。allowlist 表示仅白名单可触发；open 表示所有私聊可触发
- WEIXIN_ALLOWED_USERS：私聊白名单用户 ID，多个 ID 用英文逗号分隔（仅在 allowlist 策略下生效）
- GATEWAY_ALLOW_ALL_USERS：网关级全量放行开关。设为 true 时会绕过平台白名单，适合临时联调，不建议长期开启
补充：若暂时不知道对方的 user id，可先把 WEIXIN_DM_POLICY 临时改为 open，让对方先发一条消息，再从网关日志里取回该 user id，填入 WEIXIN_ALLOWED_USERS 后切回 allowlist。
然后启动网关：
hermes gateway微信侧聊天测试
网关跑起来之后，可以直接在微信里发几条消息，看是否能收到 Hermes 的回复。下面给一组从基础到进阶的示例，便于先确认链路通，再逐步增加测试范围；私聊若启用白名单，需用已写入 WEIXIN_ALLOWED_USERS 的账号来发。
- 基础连通测试：发送"你好"，确认 5-10 秒内有回复，先验证收发链路是否打通
- 上下文连续测试：连续发两条有关联的问题（例如"我在用什么系统？"→"刚才提到的系统有什么限制？"），确认会话上下文可用
- 工具调用测试：发送一个需要工具参与的请求（如"给一份三天待办清单"），观察响应是否明显慢于纯聊天，并检查网关日志是否有工具调用痕迹
- 白名单策略测试：用白名单账号发消息应正常回复；用未授权账号发消息应被拒绝，用于确认 allowlist 生效
- 异常恢复测试：重启一次 hermes gateway 后再次发消息，确认会话与路由仍然正常，避免只在首次启动可用
聊天测试：
整理硬盘使用情况：
整理 Python 环境信息和安装的包，并形成文件发送给自己：
常见故障与处理顺序
把故障按依赖 → 凭据 → 会话状态 → 策略配置顺序排查，会更省时间。原因是前一层不通时，后一层问题经常只是表象。
- 缺依赖报错：看到 aiohttp and cryptography are required，先补装依赖再重启网关
- 账号变量缺失：看到 WEIXIN_ACCOUNT_ID is required，先检查 ~/.hermes/.env
- 用户被拒绝访问：看到 No user allowlists configured 或 Unauthorized user，优先配置 WEIXIN_DM_POLICY=allowlist + WEIXIN_ALLOWED_USERS=...；仅在临时联调时使用 GATEWAY_ALLOW_ALL_USERS=true
- Token 失效：遇到会话过期（如 errcode=-14），重新执行 hermes gateway setup 扫码
- 重复实例冲突：同一 token 只允许一个网关实例，先停掉旧进程
从"能安装"到"能长期运行"的建议
安装成功只是第一步，稳定运行取决于配置习惯和日常巡检。推荐把本地验证、消息通道、任务调度拆成三个阶段推进，避免一次性堆太多变量。
- 阶段一：本地验证：只开 CLI，验证模型切换与工具调用稳定性
- 阶段二：微信验证：接入 Weixin，只保留最小权限策略，观察 3-7 天
- 阶段三：自动化运行：再引入 cron 与通知通道，补齐备份和告警策略
参考资料
- https://hermes-agent.nousresearch.com/docs/getting-started/quickstart
- https://hermes-agent.nousresearch.com/docs/user-guide/messaging/weixin