排错指南

Agent 不响应

症状：向 Agent 发送消息后长时间无回复。

排查步骤：

1. 检查 Agent 进程存活：

   ps aux | grep cococat
   # Windows: tasklist | findstr python

   CocoCat v2 运行在单一进程中，如果主进程不在，所有 Agent 均停止。

2. 检查 AgentPool 状态： 查看控制台输出，是否有 [ERROR] Agent X failed health check。

3. 手动测试：

   curl -X POST http://localhost:8000/api/scenes/default/chat \
     -H "Content-Type: application/json" \
     -d '{"message": "ping", "user_id": "debug"}'

   如果 Agent 存在但不响应，说明 AgentLoop 卡死或死锁。

4. 检查子 agent semaphore： Agent 的 _subagent_semaphore 限制为 5 个并发子 agent。如果超过限制，后续子 agent 会等待。

LLM API 错误

症状：Agent 返回 LLM 调用失败错误。

排查步骤：

1. 检查 .env 配置：

   # 确认 API Key 已设置
   grep OPENAI_API_KEY .env
   grep OPENAI_BASE_URL .env

2. 检查 API 可达性：

   curl -v https://api.deepseek.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"

3. 检查 API key 余额和权限

4. 检查网络：服务器是否能访问外网？是否需要代理？

5. 检查 model 名称：LLM_MODEL 是否正确？

Web 面板 401 未授权

症状：登录后仍然看到 401 错误。

排查步骤：

1. 检查 JWT_SECRET：是否已正确配置？
2. 检查 Token 过期：JWT_EXPIRE_MINUTES 设置是否太短？重新登录。
3. 清除浏览器缓存：LocalStorage 中的过期 token 可能产生冲突。
4. 检查 auth middleware：cococat/auth.py 中的 auth_required 依赖是否正确配置？

文件权限拒绝

症状：Agent 报 Error: path is outside workspace 或 Permission denied。

排查步骤：

1. 检查 PathValidator：

   # 手动测试
   from cococat.core.sandbox_path import PathValidator
   pv = PathValidator()
   print(pv.validate("/etc/passwd", "/opt/cococat"))
   # 应返回 (False, "Path is outside workspace")

2. 检查 COCOCAT_WORKSPACE：环境变量是否设置？工作目录是否正确？

3. 检查文件系统权限：运行用户是否有读写权限？

知识库搜索无结果

症状：search_kb 返回空结果。

排查步骤：

1. 检查 KB 是否挂载：cat scenes/{scene_id}/mounted_kbs.json
2. 检查 KB 是否有 wiki 页面：ls knowledge/{kb_id}/wiki/
3. 检查 KB 路径：knowledge/{kb_id}/purpose.md 是否存在？
4. 检查搜索索引：knowledge/{kb_id}/index.md 是否已更新？

Dispatch 任务卡住

症状：Agent A 分发任务给 Agent B，但 B 未处理。

排查步骤：

1. 检查 EventBus 状态：查看日志中是否有 dispatch 事件被发布和消费
2. 检查 Agent B 是否存活：AgentPool 中 Agent B 必须处于运行状态
3. 检查 runs/ 目录：ls runs/ 查看是否有未完成的任务

Dream 不执行

症状：Agent 历史记录增长但记忆未更新。

排查步骤：

1. 检查 cursor：cat agents/{id}/memory/.dream_cursor
2. 检查历史条目数：wc -l agents/{id}/memory/history.jsonl
3. 手动触发：调用 dream 工具
4. 检查 Git 提交：如果 GitStore 启用，检查 git log