zclaw_openfang/docs/knowledge-base/troubleshooting.md

故障排查指南

记录开发过程中遇到的问题、根因分析和解决方案。

---

1. 连接问题

1.1 WebSocket 连接失败

症状: WebSocket connection failed 或 Unexpected server response: 400

排查步骤:

# 1. 检查 OpenFang 是否运行
curl http://127.0.0.1:50051/api/health

# 2. 检查端口是否正确
netstat -ano | findstr "50051"

# 3. 验证 Agent ID
curl http://127.0.0.1:50051/api/agents

常见原因:

原因	解决方案
OpenFang 未启动	./openfang.exe start
端口错误	OpenFang 使用 50051，不是 4200
Agent ID 无效	使用 /api/agents 获取真实 UUID

1.2 端口被占用

症状: Port 1420 is already in use

解决方案:

# Windows - 查找并终止进程
netstat -ano | findstr "1420"
taskkill /PID <PID> /F

# 或使用 PowerShell
Stop-Process -Id <PID> -Force

1.3 Vite 代理不工作

症状: 前端请求返回 404 或 CORS 错误

检查清单:

• vite.config.ts 中配置了 /api 代理
• ws: true 已启用（WebSocket 需要）
• changeOrigin: true 已设置
• 重启 Vite 开发服务器

---

2. 聊天问题

2.1 LLM API Key 未配置

症状:

Missing API key: No LLM provider configured.
Set an API key (e.g. GROQ_API_KEY) and restart

根本原因: Agent 使用的 LLM 提供商没有配置 API Key

解决方案:

1. 检查 Agent 使用的提供商：

curl -s http://127.0.0.1:50051/api/status | jq '.agents[] | {name, model_provider}'

2. 配置对应的 API Key：

# 编辑 ~/.openfang/.env
echo "ZHIPU_API_KEY=your_key" >> ~/.openfang/.env
echo "BAILIAN_API_KEY=your_key" >> ~/.openfang/.env
echo "GEMINI_API_KEY=your_key" >> ~/.openfang/.env

3. 重启 OpenFang：

./openfang.exe restart

快速解决: 使用已配置的 Agent

Agent	提供商	状态
General Assistant	zhipu	通常已配置

2.2 流式响应不显示

症状: 消息发送后无响应或响应不完整

排查步骤:

1. 确认 WebSocket 连接状态：

console.log(client.getState()); // 应为 'connected'

2. 检查事件处理：

// 确保处理了 text_delta 事件
ws.on('message', (data) => {
  const event = JSON.parse(data.toString());
  if (event.type === 'text_delta') {
    console.log('Delta:', event.content);
  }
});

3. 验证消息格式：

// ✅ 正确
{ type: 'message', content: 'Hello', session_id: 'xxx' }

// ❌ 错误
{ type: 'chat', message: { role: 'user', content: 'Hello' } }

2.3 消息格式错误

症状: WebSocket 连接成功，但发送消息后收到错误

根本原因: 使用了文档中的格式，而非实际格式

正确的消息格式:

{
  "type": "message",
  "content": "你的消息内容",
  "session_id": "唯一会话ID"
}

---

3. 前端问题

3.1 Zustand 状态不更新

症状: UI 不反映状态变化

检查:

1. 确保使用 selector：

// ✅ 正确 - 使用 selector
const messages = useChatStore((state) => state.messages);

// ❌ 错误 - 可能导致不必要的重渲染
const store = useChatStore();
const messages = store.messages;

2. 检查 immer/persist 配置

3.2 流式消息累积错误

症状: 流式内容显示不正确或重复

解决方案:

onDelta: (delta: string) => {
  set((state) => ({
    messages: state.messages.map((m) =>
      m.id === assistantId
        ? { ...m, content: m.content + delta }  // 累积内容
        : m
    ),
  }));
}

---

4. Tauri 桌面端问题

4.1 Tauri 编译失败

常见错误:

• Rust 版本不兼容
• 依赖缺失
• Cargo.toml 配置错误

解决方案:

# 更新 Rust
rustup update

# 清理并重新构建
cd desktop/src-tauri
cargo clean
cargo build

4.2 Tauri 窗口白屏

原因: Vite 开发服务器未启动或连接失败

解决方案:

1. 确保 pnpm dev 在运行
2. 检查 tauri.conf.json 中的 beforeDevCommand
3. 检查浏览器控制台错误

4.3 Tauri 热重载不工作

检查:

• beforeDevCommand 配置正确
• 文件监听未超出限制（Linux: fs.inotify.max_user_watches）

---

5. 调试技巧

5.1 启用详细日志

// gateway-client.ts
private log(level: string, message: string, data?: unknown) {
  if (this.debug) {
    console.log(`[GatewayClient:${level}]`, message, data || '');
  }
}

5.2 WebSocket 抓包

# 使用 wscat 测试
npm install -g wscat
wscat -c ws://127.0.0.1:50051/api/agents/{agentId}/ws

5.3 检查 OpenFang 状态

# 完整状态
curl -s http://127.0.0.1:50051/api/status | jq

# Agent 状态
curl -s http://127.0.0.1:50051/api/agents | jq '.[] | {id, name, state}'

# Hands 状态
curl -s http://127.0.0.1:50051/api/hands | jq '.[] | {id, name, requirements_met}'

---

6. 错误代码参考

错误信息	原因	解决方案
Port 1420 is already in use	Vite 服务器已运行	终止现有进程
Unexpected server response: 400	Agent ID 无效	使用真实 UUID
Missing API key	LLM 提供商未配置	配置 API Key
Connection refused	OpenFang 未运行	启动服务
CORS error	代理未配置	检查 vite.config.ts

---

更新历史

日期	变更
2026-03-14	初始版本