Telegram扫码后卡在“等待授权”是因SSL验证失败、网关初始化异常或网络拦截，需依次禁用SSL校验、修正网关HTTP参数、修复DNS/代理、启用DEBUG日志定位阻断点。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已完成Telegram机器人扫码登录，但Hermes Agent界面持续停留在“等待授权”状态且无后续响应，则极可能源于SSL证书验证失败、Telegram网关初始化异常或本地网络策略拦截。以下是解决此问题的步骤：
一、禁用SSL证书验证（全局补丁法）
内网或自签名环境会触发requests与httpx库的SSL验证失败，导致Telegram Bot API连接中断，表现为扫码后无回调。需通过运行时补丁强制跳过证书校验。
1、创建补丁脚本文件：在~/.hermes/hermes-agent/目录下新建hermes_agent_ssl_patch.py文件。
2、将以下完整代码粘贴保存：
import httpx<br>import ssl<br>import warnings<br>import requests<br>from requests.adapters import HTTPAdapter<br><br>class NoVerifySession(requests.Session):<br> """继承 requests.Session,默认禁用 SSL 验证"""<br> def request(self, *args, **kwargs):<br> kwargs.setdefault('verify', False)<br> return super().request(*args, **kwargs)<br><br># 替换默认 session<br>requests.sessions.Session = NoVerifySession<br><br>def _make_ssl_patch(init_method):<br> """为指定的 httpx 类创建独立的 SSL patch wrapper(闭包)"""<br> def wrapper(self, *args, **kwargs):<br> if 'verify' not in kwargs:<br> kwargs['verify'] = False<br> init_method(self, *args, **kwargs)<br> return wrapper<br><br>def patch_httpx_disable_ssl():<br> """全局禁用 httpx SSL 验证"""<br> warnings.filterwarnings('ignore', message='Unverified HTTPS request')<br> httpx.Client.__init__ = _make_ssl_patch(httpx.Client.__init__)<br> httpx.AsyncClient.__init__ = _make_ssl_patch(httpx.AsyncClient.__init__)<br> print("✅ httpx SSL verification globally disabled for hermes-agent")<br><br>patch_httpx_disable_ssl()
3、确认该脚本已被Agent启动时自动导入：检查main.py或gateway/telegram.py中是否存在import hermes_agent_ssl_patch语句。
4、重启Hermes Agent服务，观察日志是否输出✅ httpx SSL verification globally disabled for hermes-agent。
二、手动注入Telegram网关配置参数
默认网关未显式传入verify=False时，即使补丁生效也可能被上层调用覆盖。需直接修改Telegram网关初始化逻辑，确保所有HTTP请求携带禁用验证标识。
1、定位文件：gateway/telegram.py，查找TelegramBotGateway类定义。
2、在__init__方法中，找到初始化self.client或self.session的位置。
3、将原初始化语句如self.client = httpx.AsyncClient()替换为：
self.client = httpx.AsyncClient(verify=False)
4、若使用requests发起同步请求（如Webhook注册），在对应位置添加verify=False参数，例如：
requests.post(url, json=payload, verify=False)
5、保存文件后重启Agent，重新扫码测试。
三、绕过本地DNS与代理干扰
Windows或企业内网常启用DNS劫持或强制代理，导致Telegram Bot API域名（api.telegram.org）解析失败或路由异常，扫码回调URL无法抵达本地服务。
1、以管理员身份打开命令提示符，执行ping api.telegram.org，确认能否获取到IPv4地址且延迟正常。
2、若返回超时或错误IP，编辑C:\Windows\System32\drivers\etc\hosts文件，在末尾添加：
149.154.167.220 api.telegram.org
3、关闭所有代理软件（包括系统代理、Clash、Surge等），在终端执行set HTTP_PROXY=与set HTTPS_PROXY=清空环境变量。
4、检查防火墙是否放行Agent监听端口（默认8080或18789），并确保Telegram Webhook回调地址（如https://your-domain.com/webhook）可被公网访问。
四、启用调试模式捕获扫码事件流
扫码无响应常因事件未进入Telegram消息处理管道，启用详细日志可定位阻断点。
1、在environments/default.yaml中将log_level设为DEBUG。
2、启动Agent时附加--debug参数，例如：python main.py --debug。
3、扫码后立即查看控制台输出，重点检索包含webhook、update、auth、callback的关键字。
4、若日志中完全缺失Received Telegram update类记录，说明请求未到达网关；若出现SSLCertVerificationError或ConnectionResetError，则确认SSL补丁未生效。
5、在gateway/telegram.py的handle_update函数入口处插入临时日志：logger.debug(f"Raw update received: {update}")，验证是否成功接收原始数据。
