故障排除

常见问题及解决方法。

Gateway 问题

Gateway 无法启动

• 端口冲突 -- 另一个进程可能正在使用端口 18789。使用 lsof -i :18789 检查。
• 配置错误 -- neotask.json 中的 JSON 无效。Gateway 在启动时验证配置并报告具体错误。
• Gateway 锁 -- 之前的实例可能留下了过时的锁文件。诊断工具可以检测并修复此问题。
• Node.js 版本 -- Neotask 需要 Node 22+。

Gateway 启动但没有频道连接

• 缺少凭据 -- 每个频道需要自己的认证（bot token、QR 扫描、API key）。
• 网络问题 -- 频道需要互联网访问才能连接到消息平台 API。
• 速率限制 -- 某些平台限制新连接的速率。等待后重试。

无法从桌面应用连接

• 端口错误 -- 确保桌面应用连接到正确的 Gateway 端口。
• 认证不匹配 -- Gateway token 必须匹配。
• 防火墙 -- 如果 Gateway 在另一台机器上，确保端口可访问。

频道问题

WhatsApp 无法连接

• QR 过期 -- QR 码约 60 秒后过期。快速重新扫描。
• 多设备限制 -- WhatsApp 限制链接设备数量。
• 会话损坏 -- 删除 WhatsApp 会话目录并重新配对。

Telegram 机器人未接收消息

• Bot token 无效 -- 通过 BotFather 验证您的 bot token。
• 隐私模式 -- 默认情况下，机器人在群组中只能看到提及它的消息。
• Webhook 冲突 -- 另一个服务可能正在消费消息。

Discord 机器人无响应

• 缺少意图 -- 在 Discord Developer Portal 中启用所需的 Gateway Intents。
• 缺少权限 -- 机器人需要在目标频道中的读取和发送权限。

模型问题

认证错误

• Key 未配置 -- 确保已设置提供商的 API key。
• Key 过期 -- 某些 OAuth token 会过期。重新认证。
• 速率限制 -- 如果您有多个 key，key 轮换会自动切换。

响应缓慢

• 模型选择 -- 较大的模型更慢。对于快速任务尝试较快的模型。
• 上下文大小 -- 长对话会减慢处理速度。尝试 /compact。
• 网络延迟 -- 检查与模型提供商的连接。

节点问题

伴侣应用找不到 Gateway

• 绑定模式 -- Gateway 必须绑定到 LAN 或 Tailnet（不是回环），外部设备才能访问。
• 相同网络 -- 对于 Bonjour 发现，两个设备必须在同一网络上。
• 手动输入 -- 在应用设置中手动输入 Gateway 主机和端口。

会话问题

上下文窗口超出

• 压缩 -- 使用 /compact 总结并重置上下文。
• 启用自动压缩 -- 在配置中设置压缩阈值。
• 新会话 -- 使用 /new 重新开始。

诊断

内置诊断工具检查常见问题并可以自动修复许多：

• 配置验证
• 文件权限
• 频道连接性
• 模型认证状态
• Node.js 兼容性
• 网络配置

检查 Gateway 日志获取详细的错误信息。/health 端点提供所有组件的机器可读状态。

获取帮助

1. 运行诊断工具进行自动修复
2. 检查 Gateway 日志获取详细错误消息
3. 通过桌面应用中的 Intercom 聊天小部件联系支持