Hermes 走「AI Bot 长连接 / WebSocket」模式接企微，本机无需公网入口。整个流程的瓶颈只有一个：从企微管理台拿到两个值
WECOM_BOT_ID + WECOM_SECRET。本页讲清楚三条获取路径、踩坑与最终落地命令。
.env + 重启 + 验证
常见坑
参考资料
在动手之前，先确认这三件事，否则会卡在中途没退路：
~/.hermes/hermes-agent/，gateway 由 launchd 拉起。本文假设你已经按 Hermes 文档完成基础安装；如果还没，先跑 setup-hermes.sh。同样目的有三个入口，按推荐度排序：
本机跑 hermes gateway setup → 选 WeCom → 终端出二维码 → 手机企微扫一下 → 自动建好并写入 .env。
打开企微 app/Mac 客户端 → 工作台 → 智能机器人 → 创建机器人 → API 模式 → 长连接 → 复制 Bot ID / Secret。
3 分钟web 后台登录 → 应用管理 → 智能机器人 → 创建。客户端找不到入口时走这里。
5–15 分钟Hermes 的 gateway setup 向导内置了"在终端渲染二维码、手机扫码授权后自动建 bot 并取凭据"的逻辑。这条路最快也最不容易出错，因为完全不用手输 Bot ID / Secret。
cd /Users/gloom/.hermes/hermes-agent
./venv/bin/python -m hermes_cli.main gateway setup菜单出现后用方向键选 WeCom，回车。
终端会以 ASCII / 半 block 字符渲染一张二维码。打开手机企业微信 → 右上角"+"号 → 扫一扫 → 扫向终端。屏幕模糊或字号过小时可以缩小终端窗口让二维码更紧凑。
企微 app 会弹出"是否允许 [你的企业] 创建 AI 机器人"。点确认。Hermes 会自动在企微侧创建 bot 应用并把 Bot ID / Secret 写进 ~/.hermes/.env。
扫码成功后向导继续追问几个问题：
open（任何人）；想限制选 allowlist 然后填 user_id 列表。open，想限制选 allowlist 然后填群 ID。不确定就全选 open，后面随时改 .env 调整。
.env 已经有真值了，可以直接跳到 第 6 节"拿到凭据之后"。这是 2026 年的真实流程。Hermes 文档里那条"管理后台 → 应用管理 → 创建应用 → AI Bot"是老路子，今天打开会找不到对应入口；现在主入口在客户端。
手机或 Mac 客户端的企业微信，底部进 工作台 tab，往下找 「智能机器人」。如果没看到——往下翻"我的应用"末尾通常有个"添加应用"或"探索更多"，里面会有"智能机器人"分类。
填基本信息：名字、头像、一句话简介。这些都是员工侧看到的展示信息，不影响接入。
页面会问你机器人怎么响应消息。常见三类：
| 选项 | 用于 | Hermes 是否能用 |
|---|---|---|
| 对话模式 | 纯腾讯托管的预置话术 bot | 不行 —— 没有 Bot ID/Secret |
| API 模式 | 消息中转到第三方系统处理 | 就是这个 |
| 知识库模式 | 挂腾讯文档当 RAG | 不行 |
API 模式内部又分两种握手方式：
| 方式 | 需要的东西 | 对应 Hermes |
|---|---|---|
| 长连接 | 无需公网，本机持久 WebSocket 出去拉消息 | ✅ 这条 |
| 短连接 / 回调 | 需要公网 HTTPS 域名 + 证书 + Token + EncodingAESKey | 另一个 adapter wecom_callback |
选完长连接，页面会立刻渲染出两个字段：
客户端入口被隐藏 / 你只有 PC 端没装企微 app / 大企业有专门的应用管理流程，走这里：
顶栏选 应用管理 → 左侧导航里找 「智能机器人」 或 「AI 机器人」 子项。点 创建机器人 / 新建机器人。
web 后台的表单跟客户端 B.3 / B.4 / B.5 完全对齐 —— 选 API 模式 → 长连接 → 复制 Bot ID + Secret。
把两个值写入 ~/.hermes/.env。如果走的路径 A 扫码，这一步 Hermes 已经替你做了，直接跳到验证。
.env# ~/.hermes/.env 末尾或 TELEGRAM 段后追加：
WECOM_BOT_ID=你的 Bot ID
WECOM_SECRET=你的 Secret
# 可选：访问控制
# WECOM_DM_POLICY=allowlist # open | allowlist | disabled | pairing
# WECOM_ALLOWED_USERS=alice,bob,charlie # 仅 allowlist 模式生效
# WECOM_HOME_CHANNEL= # cron 通知默认输出的 chat_id__FILL_ME_IN__ 之类占位字符串！Hermes 的 gateway/config.py:1669 检查 if WECOM_BOT_ID and WECOM_SECRET ——任何非空字符串都会被当真值，导致 wecom 适配器尝试用垃圾凭据握手并刷错误日志。要么填真值，要么注释掉整行。# macOS / launchd 已加载的场景：
launchctl kickstart -k gui/$(id -u)/ai.hermes.gateway
# 或如果还没加载：
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.hermes.gateway.plist等 10–20 秒，gateway 完成 WebSocket 握手。
cat ~/.hermes/gateway_state.json | python3 -m json.tool看 platforms.wecom.state 字段：
connected —— 成功 ✅disconnected 或 error —— 看 ~/.hermes/logs/gateway.error.log 尾部用手机企微给机器人发条 「ping」。期待：
~/.hermes/channel_directory.json 里 wecom 数组出现一条新 entry（你的 user_id）。跑通这步 = 端到端打通，下班。
企业没开通这个特性。让管理员在 web 后台 → "我的企业" → "权限管理"或专门的"AI 套件"页里启用。或者升级套餐 —— 部分免费版企微限制 AI Bot 数量。
设计如此。Secret 是单次显示的敏感凭据。丢了只能重新点"随机生成"得到新值（旧值失效）。建议建好就贴 1Password / Bitwarden / Lark 私人多维表。
本页只用 Bot ID + Secret 这一对，其它三个出现说明你看错教程了。
是的。WebSocket 握手失败时 Hermes 走指数退避（RECONNECT_BACKOFF = [2, 5, 10, 30, 60]）但不会自动停。如果你确认凭据有问题，把 .env 的两行注释掉再 launchctl kickstart -k，让 wecom adapter 不启动比刷错误日志好。
不行。Bot ID + Secret 绑死到创建时的企业。换企业必须在企业 B 里重新走一遍创建流程，拿新的一对凭据。
# 看 gateway 当前是否运行
ps -ef | grep hermes_cli | grep -v grep
# 看每个平台的连接状态
cat ~/.hermes/gateway_state.json | python3 -m json.tool
# 看启动错误（最后 80 行）
tail -80 ~/.hermes/logs/gateway.error.log
# 看 wecom adapter 实时心跳
tail -f ~/.hermes/logs/gateway.log | grep -i wecom
# 强制重启（kill + launchd 自动拉起）
launchctl kickstart -k gui/$(id -u)/ai.hermes.gateway
# 完全卸载平台（保留 .env，只是 unload launchd）
launchctl bootout gui/$(id -u)/ai.hermes.gatewaywebsite/docs/user-guide/messaging/wecom.md（仓库内）gateway/platforms/wecom.py