# 故障排除

常见问题及解决方法。

---

## 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 聊天小部件联系支持