调试和修复常见的 Clawdbot AI 助手问题。了解如何诊断连接问题、消息失败和网关错误。

Clawdbot 故障排除概述

本指南帮助您诊断和修复 Clawdbot 部署中的常见问题。查找连接问题、消息失败和网关错误的解决方案。

常见问题

网关无法启动

症状：网关无法启动或立即退出。

解决方案：

检查端口可用性：

lsof -i :3010

验证配置：

clawdbot config validate

检查日志：

clawdbot gateway logs

WhatsApp 连接失败

症状：QR 码不显示或连接断开。

解决方案：

清除 WhatsApp 会话：

rm -rf ~/.clawdbot/providers/whatsapp/session

重启网关：

clawdbot gateway restart

检查网络连接

消息未送达

症状：消息已发送但未收到。

解决方案：

检查会话状态：

clawdbot sessions list

验证提供商连接：

clawdbot providers status

检查速率限制

代理无响应

症状：代理不生成响应。

解决方案：

检查代理状态：

clawdbot agents status

验证 API 密钥：

echo $ANTHROPIC_API_KEY

检查模型可用性

诊断命令

网关状态

# 检查网关健康
clawdbot gateway status

# 查看活动连接
clawdbot gateway connections

# 显示资源使用
clawdbot gateway stats

会话诊断

# 列出所有会话
clawdbot sessions list

# 查看会话详情
clawdbot sessions get <session-key>

# 清除卡住的会话
clawdbot sessions clear <session-key>

提供商诊断

# 检查提供商状态
clawdbot providers status

# 测试提供商连接
clawdbot providers test whatsapp

# 重新连接提供商
clawdbot providers reconnect telegram

日志分析

启用调试日志

clawdbot gateway start --log-level debug

日志位置

日志	位置
网关	`~/.clawdbot/logs/gateway.log`
提供商	`~/.clawdbot/logs/providers/`
代理	`~/.clawdbot/logs/agents/`

日志级别

级别	描述
`error`	仅错误
`warn`	警告和错误
`info`	一般信息
`debug`	详细调试信息

错误代码

连接错误

代码	描述	解决方案
`ECONNREFUSED`	端口未开放	检查网关是否运行
`ETIMEDOUT`	网络超时	检查网络
`EAUTH`	认证失败	验证凭证

提供商错误

代码	描述	解决方案
`WA_DISCONNECTED`	WhatsApp 断开	重新扫描 QR
`TG_INVALID_TOKEN`	Telegram 令牌无效	检查令牌
`DC_MISSING_INTENTS`	Discord intents	启用 intents

性能问题

响应缓慢

原因：

高消息量
大上下文大小
网络延迟

解决方案：

启用流式传输
减少上下文大小
检查网络

内存使用

检查内存：

clawdbot gateway stats --memory

减少内存：

{
  "gateway": {
    "messageBuffer": 500,
    "maxHistory": 50
  }
}

恢复程序

重置网关

# 停止网关
clawdbot gateway stop

# 清除状态
clawdbot gateway reset --state

# 重启
clawdbot gateway start

重置提供商

# 断开提供商
clawdbot providers disconnect whatsapp

# 清除提供商数据
rm -rf ~/.clawdbot/providers/whatsapp

# 重新配置
clawdbot providers setup whatsapp

重置代理

# 清除代理会话
clawdbot agents reset main --sessions

# 清除代理工作区
clawdbot agents reset main --workspace

获取帮助

支持资源

文档：https://docs.clawdbotai.app
GitHub Issues：https://github.com/clawdbot/clawdbot/issues
社区 Discord：https://discord.gg/clawdbot

错误报告

错误报告中包含：

Clawdbot 版本
操作系统
错误消息
重现步骤

下一步

Clawdbot 配置 - 配置指南
Clawdbot 安全 - 安全设置
Clawdbot 网关 - 网关概述

Clawdbot 故障排除

On this page