OpenClaw 故障排除指南
本目录包含常见 OpenClaw 运行时问题的实用故障排除指南。每个指南都按症状而非模块组织,便于根据观察到的现象进行诊断。
可用指南
WebSocket 连接失败
诊断和解决 WebSocket 连接问题,包括立即断开、握手超时和过早关闭。基于网关服务器连接处理逻辑。
常见症状:
- 客户端连接后立即断开
- 日志中出现"handshake timeout"错误
- 出现"closed before connect"警告
压缩/摘要失败
排除代理对话过长时的对话摘要问题。涵盖渐进式降级系统和上下文窗口处理。
常见症状:
- "Full summarization failed"错误
- 上下文窗口超限消息
- 长对话时代理停止响应
会话记录损坏
修复包含孤立或重复工具结果的损坏会话记录。解释自动修复系统以及如何诊断 tool_use 配对问题。
常见症状:
- "unexpected tool_use_id found" API 错误
- 工具调用后代理停止响应
- 记录中出现重复的工具结果
嵌入向量提供者失败
解决由嵌入向量提供者失败引起的内存搜索问题。涵盖降级链和优雅降级到纯 FTS 模式。
常见症状:
- "No API key found for provider"错误
- 内存搜索仅返回文本匹配
- 缺少向量搜索结果
配置验证错误
调试阻止 OpenClaw 启动的配置验证失败。包括插件配置模式不匹配和重复代理目录问题。
常见症状:
- OpenClaw 启动失败
- Zod 模式验证错误
- 插件配置不匹配警告
指南结构
每个指南遵循一致的结构:
- 症状: 可观察的行为和错误消息
- 根本原因: 源代码中的技术原因
- 恢复机制: 自动和手动恢复步骤
- 诊断步骤: 实用的调试工作流
- 流程图: 恢复逻辑的可视化表示