常见问题
故障排查与常见问答。
安装与启动
Q: 应用启动后白屏/无法加载？
Go Sidecar 引擎可能未正常启动。检查步骤：
- 查看 日志 页面是否有错误信息
- 确认端口
16060未被占用 - 尝试重启应用，Sidecar 会自动在启动时拉起（最多等待 30 秒）
Q: macOS 提示 "无法打开，因为无法验证开发者"？
右键点击应用 → "打开"，在弹出的对话框中再次点击 "打开"。或者执行：
xattr -cr /Applications/HexClaw.appQ: 如何开机自启动？
进入 设置 → 通用 → 开机自启动，开启即可。macOS 使用 LaunchAgent 实现。
模型与对话
Q: API 请求返回 401 / 403 错误？
API Key 无效或过期。进入 设置 → 模型服务商，检查 Key 是否正确，确认账户余额充足。
Q: 如何使用本地模型（不联网）？
安装 Ollama 后，在 HexClaw 中添加 Ollama 服务商：
- Base URL:
http://localhost:11434/v1 - API Key: 留空
- 模型: 手动添加已下载的模型名（如
llama3.1、qwen2.5）
Q: 流式输出卡住不动了？
可能是网络超时。按 Esc 停止生成，重新发送消息即可。
数据与隐私
Q: 我的数据存在哪里？
所有数据存储在本地：
- 会话和消息：SQLite 数据库（
hexclaw.db） - 设置：Tauri Store（本地 JSON 文件）
- API Key：操作系统安全密钥库
- 数据目录：可在 设置 → 通用 → 数据目录 查看
Q: 数据会发送到第三方服务器吗？
不会。HexClaw 仅与你配置的 AI API 端点通信。如果使用 Ollama 本地模型，所有数据完全离线。
工作流与 Agent
Q: 工作流执行失败了怎么办？
查看失败节点的错误信息。常见原因：Agent 未配置模型、MCP 工具连接断开、Token 超限。
Q: 多 Agent 会议最多支持几个 Agent？
没有硬性限制，但建议 2~5 个 Agent 参与，过多会导致对话变长，Token 消耗增大。
MCP 与工具
Q: MCP 服务器连接失败？
- 确认服务器进程已启动
- 检查协议类型是否匹配（stdio / sse / streamable_http）
- 查看 日志 页面获取详细错误信息
性能与优化
Q: 应用占用内存较高？
HexClaw 使用 WebView 渲染界面。正常内存占用约 200~400MB。如果超过 1GB，尝试：
- 关闭不必要的会话标签
- 清理日志缓存（日志页面 → 清除）
- 重启应用
Q: 如何查看引擎运行状态？
仪表盘页面显示 Sidecar 引擎健康状态，包括连接状态、API 端口等信息。引擎每 5 秒自动检测一次。