企业微信部署hermes agent需五步：一、创建自建应用获取corpid/agentid/secret；二、配置可信ip、开启接收消息并设置token与aeskey；三、在config.yaml中正确填写wecom网关参数；四、设置可见范围及im:message:read等必要权限；五、执行hermes gateway setup并测试配对。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望在企业微信中部署 Hermes Agent 作为办公自动化 AI 助理，但尚未完成基础配置或遇到接入失败问题，则可能是由于应用凭证未正确获取、消息回调未启用或网关配置不匹配所致。以下是解决此问题的步骤：
一、创建企业微信自建应用并获取凭证
该步骤用于在企业微信侧注册可信应用，生成唯一身份标识，使 Hermes Agent 能被平台识别并授权通信权限。缺少 CorpID、AgentID 或 Secret 将导致后续所有配置无法生效。
1、登录企业微信管理后台，使用管理员账号进入。
2、点击左侧菜单栏“应用管理” → “自建” → “创建应用”。
3、填写应用名称（如“Hermes AI 助理”）与应用描述，点击“创建”。
4、在新创建的应用详情页中，进入“凭证与基础信息”，记录以下三项关键参数：CorpID、AgentID、Secret。
二、配置消息接收与可信服务器设置
该步骤确保企业微信可将用户消息安全投递至 Hermes Agent 所在服务器，并验证请求来源合法性。若未配置可信 IP 或回调 URL 不可达，消息将被平台拦截。
1、在应用详情页中，进入“功能设置” → “接收消息”，开启“接收消息”开关。
2、点击“配置”按钮，在弹出窗口中填写：Token（需与 Hermes 配置文件中一致）、EncodingAESKey（推荐使用平台自动生成）、消息回调 URL（格式为 https://你的公网域名/webhook/wecom）。
3、返回“应用管理” → “管理工具” → “可信 IP”，添加 Hermes Agent 所在服务器的公网 IP 地址。
4、保存全部配置后，点击“验证 URL”按钮，确认回调地址响应成功状态码 200。
三、配置 Hermes Agent 的企业微信网关
该步骤将企业微信侧的凭证与 Hermes Agent 内部网关模块绑定，使其能解析加密消息、完成签名验证并路由至核心处理逻辑。YAML 配置错误会导致消息解密失败或身份校验拒绝。
1、登录 Hermes Agent 所在服务器，打开配置文件 config.yaml。
2、在 gateways 节点下添加或修改 wecom 段落，内容如下：
gateways:
wecom:
enabled: true
corp_id: "ww_your_corp_id"
agent_id: 1000002
secret: "your_app_secret"
token: "your_callback_token"
aes_key: "your_encoding_aes_key"
3、确保 server.webhook_path 设置为 /webhook/wecom，且端口已对外暴露并映射到公网。
4、重启 Hermes Agent 服务以加载新配置。
四、设置机器人可见范围与成员权限
该步骤控制哪些企业微信成员可以与 Hermes Agent 交互，避免因权限隔离导致消息无法送达或功能受限。默认情况下新创建应用对全员不可见。
1、返回企业微信管理后台，进入该应用的“设置”页面。
2、点击“可见范围”，勾选目标部门或成员，点击“保存”。
3、在“功能设置” → “权限管理”中，确认已启用以下权限：im:message:send_as_bot、im:message:read、contact:user.base:readonly。
4、若需支持群聊@触发，还需在“接收消息”设置中启用“群消息”选项。
五、启动服务并完成首次配对验证
该步骤通过真实消息流测试端到端链路是否畅通，验证 Hermes Agent 是否能正常接收、处理并响应企业微信消息。未完成配对将无法建立会话上下文。
1、在服务器终端执行 hermes gateway setup 命令。
2、在交互式向导中选择 wecom，依次输入 CorpID、AgentID、Secret、Token 和 AESKey。
3、运行 hermes start 启动服务，观察日志中是否出现 “wecom gateway started” 及 “listening on /webhook/wecom” 提示。
4、在企业微信客户端中搜索该应用名称，点击“去使用”，发送任意文本（如“你好”），等待 Hermes Agent 回复。
5、若收到回复且日志显示 “received message from user_xxx” 和 “sent reply to user_xxx”，则配对成功。
