Hermes Agent在内网启动时SSL证书验证失败，表现为CERTIFICATE_VERIFY_FAILED错误，需通过hermes doctor诊断、时间校准、临时禁用验证或永久更新certifi证书包修复。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在内网或私有环境中安装并启动 Hermes Agent 时，遇到类似 [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1006) 的报错，说明 Python 正在尝试校验 HTTPS 连接的 SSL 证书，但本地信任库中找不到对应根证书——这在自签名证书、内网 CA 或飞书/微信网关代理场景下极为常见，且会直接导致 hermes gateway start 失败、模型调用中断或授权流程卡死。
确认是否为 SSL 验证失败引发的报错
第一步：执行 hermes doctor，观察输出末尾是否有 SSL error、CERTIFICATE_VERIFY_FAILED 或 unable to get local issuer certificate 字样。
第二步：若无明确提示，手动测试底层请求是否通达目标服务端。运行：python -c "import requests; print(requests.get('https://dashscope.aliyuncs.com/compatible-mode/v1/models', headers={'Authorization': 'Bearer sk-test'}, timeout=5).status_code)"（将 sk-test 替换为你实际的 Key）——若抛出 SSLError 而非 401/403，则确认是 SSL 层拦截。
第三步：检查系统时间是否准确。执行 date，若偏差超过 3 分钟，证书验证必然失败，【必须先校准系统时间】。
临时绕过验证（仅限开发/内网调试）
方法一：启用全局 SSL 补丁脚本（推荐）
创建补丁文件：mkdir -p ~/.hermes/hermes-agent && nano ~/.hermes/hermes-agent/hermes_agent_ssl_patch.py，粘贴以下内容并保存：
import httpx, ssl, warnings, requests<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>def _make_ssl_patch(init_method):<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>httpx.Client.__init__ = _make_ssl_patch(httpx.Client.__init__)<br>httpx.AsyncClient.__init__ = _make_ssl_patch(httpx.AsyncClient.__init__)<br>warnings.filterwarnings('ignore', message='Unverified HTTPS request')
方法二：强制环境变量禁用（单次生效）
启动时加前缀：HERMES_SSL_NO_VERIFY=1 hermes gateway run。该变量会被 Hermes 主程序识别并自动注入 httpx 和 requests 的 verify=False 参数。
⚠️ 注意：此方式不修改任何库行为，仅作用于当前进程，适合快速验证是否为 SSL 问题根源。
永久修复：替换 certifi 证书包
第一步：升级 certifi 到最新版：pip install --upgrade certifi。旧版 certifi（如 2023.7.22 之前）不含部分新 CA 根证书，尤其缺失国内主流云厂商中间链。
第二步：获取当前 certifi 证书路径：python -c "import certifi; print(certifi.where())"，记下输出路径（如 /home/user/.pyenv/versions/3.11.9/lib/python3.11/site-packages/certifi/cacert.pem）。
第三步：将你的内网 CA 根证书（PEM 格式）追加到该文件末尾：cat your-company-root-ca.crt >> $(python -c "import certifi; print(certifi.where())")。【务必用 >> 追加，不可用 > 覆盖，否则丢失全部公共根证书】
第四步：验证是否生效。运行：curl --cacert $(python -c "import certifi; print(certifi.where())") -I https://your-internal-gateway.example.com，返回 HTTP/2 200 即表示证书链已识别。
