执行 hermes gateway start 后显示“Gateway not online”表明网关启动后健康检查失败，需先运行 hermes gateway status 确认真实状态，再依次检查端口监听（3000）、防火墙、微信/飞书凭证有效性、SSL 证书校验及运行时上下文。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你执行 hermes gateway start 后终端只显示 Gateway not online 并立即退出，说明网关进程未能完成初始化或健康检查失败，不是单纯没启动，而是启动后立刻判定自身不可用。
确认网关是否真在运行
别信终端输出的那行字——它可能是启动脚本提前退出导致的误判。先查真实状态：
运行 hermes gateway status，观察返回值。若输出 inactive (dead) 或无响应，说明进程确实没起来；若返回 active (running) 但仍有 not online 提示，则是健康检查环节失败。
这一步必须做，否则后续所有操作都建立在错误前提上。
检查网关端口监听与防火墙
网关默认监听 3000 端口（非8080），很多用户卡在这一步却去查8080。
执行 lsof -i :3000（Linux/macOS）或 netstat -ano | findstr :3000（Windows），确认是否有进程绑定该端口。
若端口空闲但网关仍报 not online，立刻检查系统防火墙是否拦截了入站连接：Ubuntu/Debian 用户执行 sudo ufw status，若显示 Status: active，则必须放行：sudo ufw allow 3000/tcp。
【注意：Windows 防火墙默认阻止新服务监听，即使你没手动开过防火墙，也要进“高级安全 Windows 防火墙”新建入站规则】
验证微信/飞书凭证有效性
Gateway not online 最常出现在微信或飞书网关场景，根本原因不是代码问题，而是凭证已失效或未完成首次授权闭环。
方法一：强制重置微信账户凭证
删除整个凭证目录：rm -rf ~/.hermes/weixin/accounts/，然后重新运行 hermes gateway setup，严格使用手机版微信扫码 → 点击“确认登录” → 等待终端明确输出 account_id=xxx 才算成功。中途切后台、锁屏、扫码超时都会导致 JSON 文件写入不全。
方法二：跳过扫码直连测试
临时绕过扫码流程，用已知有效的 account_id 直接启动：hermes gateway run --weixin-account-id your_real_account_id_here。如果此时能正常监听并输出 Listening on http://localhost:3000，就坐实了是凭证问题。
以 CLI 为先的表单构建器，采用 BYOK 理念。通过JSON Schema 生成美观的 HTML 表单，使用您自己的 SMTP 服务器处理提交，存储响应...
修复 SSL 证书校验失败（内网/企业环境必做）
第一步：确认是否触发 SSL 错误
运行 hermes gateway logs，滚动到最顶部，找包含 CERTIFICATE_VERIFY_FAILED 或 ssl.SSLCertVerificationError 的行。只要出现，就必须打补丁。
第二步：注入 SSL 绕过补丁
创建补丁文件：mkdir -p ~/.hermes/hermes-agent && nano ~/.hermes/hermes-agent/hermes_agent_ssl_patch.py，粘贴以下内容：
import requests, httpx<br>from requests.adapters import HTTPAdapter<br>class NoVerifySession(requests.Session):<br> def request(self, *args, **kwargs):<br> kwargs.setdefault('verify', False)<br> return super().request(*args, **kwargs)<br>requests.sessions.Session = NoVerifySession<br>httpx.Client.__init__ = lambda self, *a, **kw: super(httpx.Client, self).__init__(*a, verify=False, **kw)
第三步：确保补丁生效
编辑 ~/.hermes/hermes-agent/__init__.py（若不存在则新建），写入一行：import hermes_agent_ssl_patch。这行必须存在，否则补丁不会加载。
【关键点：补丁文件名必须和 import 语句完全一致，且不能有 .py 后缀出现在 import 中】
重建网关运行时上下文
① 终止所有残留进程：pkill -f "hermes.*gateway"
② 清空网关缓存与运行时数据：rm -rf ~/.hermes/run/gateway/ ~/.hermes/logs/gateway.log
③ 强制重新加载配置并前台启动：hermes gateway run --debug
④ 观察日志首行是否出现 Starting Hermes Gateway v2.4.1，紧接着是否有 auxiliary_client connected 或 auth endpoint reachable 类提示。只要这两项任一缺失，not online 就必然发生。
⑤ 若第④步卡在 Waiting for auxiliary_client... 超过15秒，说明辅助客户端启动失败，需单独运行 hermes auxiliary-client start --debug 查看具体报错。
