Discord机器人网关连接失败需依次验证Token有效性、配置项完整性、网络连通性及依赖兼容性：检查Developer Portal中Bot Token与Privileged Intents启用状态；确认config.yaml中token、enabled、application_id字段正确无误；测试HTTPS及WebSocket到gateway.discord.gg的连通性；确保使用discord.py为误装，实际应通过npm安装@discordjs/ws等Node.js依赖。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试启动Hermes Agent的Discord机器人网关，但始终无法连接Discord服务器，则可能是由于API凭证无效、网络策略拦截或客户端配置缺失所致。以下是解决此问题的步骤：
一、验证Discord Bot Token有效性与权限配置
Discord机器人必须通过有效的Bot Token进行身份认证，且该Token需绑定具备必要权限的Bot应用。若Token过期、被撤销或未启用Privileged Intents，将导致连接建立失败或握手阶段中断。
1、登录Discord Developer Portal，进入对应应用的Bot页面。
2、确认Token字段已生成并点击Copy按钮复制最新Token（切勿使用Client Secret）。
3、在Privileged Gateway Intents区域，必须启用“SERVER MEMBERS INTENT”和“MESSAGE CONTENT INTENT”两项，否则机器人无法接收消息事件。
4、返回OAuth2 → URL Generator页面，在Scopes中勾选bot，在Bot Permissions中至少勾选“Send Messages”、“Read Message History”、“Use Application Commands”，生成URL并添加机器人至测试服务器。
二、检查Hermes Agent Discord网关配置项
Hermes Agent需通过YAML配置显式声明Discord网关参数，任何字段缺失或格式错误均会导致初始化失败，表现为日志中出现KeyError: 'token'或Invalid token。
1、打开~/.hermes/config.yaml文件，定位到gateways: discord:区块。
2、确认存在且仅存在以下必需字段：token（值为上一步复制的Bot Token）、enabled: true、application_id（可在Developer Portal应用设置页获取）。
3、检查token值是否被引号包裹，且无前后空格、换行或中文标点；若含特殊字符（如斜杠、等号），须用双引号包围。
4、保存文件后执行hermes gateway restart discord强制重载配置，避免缓存残留。
三、排查本地网络与防火墙对Discord API的访问限制
Discord网关依赖WebSocket长连接（wss://gateway.discord.gg），若出口链路主动重置连接、DNS污染或UDP阻断，将导致心跳超时、Connection closed或EOF occurred in violation of protocol错误。
1、在Agent运行节点执行curl -I https://discord.com，确认HTTP状态码为200且无重定向异常。
2、测试WebSocket连通性：echo -e "GET /?v=10&encoding=json HTTP/1.1\r\nHost: gateway.discord.gg\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n\r\n" | nc -w 5 gateway.discord.gg 443 | head -n 1，预期返回HTTP/1.1 101。
3、若测试失败，临时关闭主机防火墙：sudo ufw disable（Ubuntu）或sudo systemctl stop firewalld（CentOS），再重试连接。
4、在Kubernetes环境中，检查Pod Security Policy或NetworkPolicy是否显式拒绝目标域名或443端口出向流量。
四、确认Discord.js客户端版本兼容性与依赖完整性
Hermes Agent内置Discord网关基于Discord.js v14+构建，若运行时加载了旧版discord.js或缺失@discordjs/rest、@discordjs/ws等对等依赖，将引发TypeError: Cannot read properties of undefined类错误。
1、进入Hermes Agent安装目录，执行pip show discord.py，确认输出中Name为discord.py而非discord.js——此处应为Python生态的discord.py库，非Node.js的discord.js。
2、若显示discord.py，则需卸载：pip uninstall discord.py，因Hermes Agent实际使用的是其自包含的TypeScript/Node.js子系统调用Discord.js。
3、执行hermes gateway logs discord，观察启动日志末尾是否出现Failed to load @discordjs/ws或Cannot find module 'undici'。
4、若存在缺失模块，进入~/.hermes/node_modules目录，运行npm install @discordjs/ws @discordjs/rest undici补全依赖。
