常见问题
汇总河蟹 AI 桌面端在安装启动、模型配置、数据隐私、工作流和 MCP 连接上的常见问题与排查方法。
安装与启动
Q: 应用启动后白屏/无法加载？
Go Sidecar 引擎可能未正常启动。检查步骤：
- 查看 日志 页面是否有错误信息
- 确认端口
16060未被占用 - 尝试重启应用，Sidecar 会自动在启动时拉起（最多等待 30 秒）
Q: macOS 提示 "无法打开，因为无法验证开发者"？
右键点击应用 → "打开"，在弹出的对话框中再次点击 "打开"。或者执行：
xattr -cr /Applications/HexClaw.appQ: 如何开机自启动？
进入 设置 → 通用 → 开机自启动，开启即可。macOS 使用 LaunchAgent 实现。
模型与对话
Q: API 请求返回 401 / 403 错误？
API Key 无效或过期。进入 设置 → 模型服务商，检查 Key 是否正确，确认账户余额充足。
Q: 如何使用本地模型（不联网）？
安装 Ollama 后，在河蟹 AI 中添加 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: 数据会发送到第三方服务器吗？
不会。河蟹 AI 仅与你配置的 AI API 端点通信。如果使用 Ollama 本地模型，所有数据完全离线。
工作流与 Agent
Q: 工作流执行失败了怎么办？
查看失败节点的错误信息。常见原因：Agent 未配置模型、MCP 工具连接断开、Token 超限。
Q: 多 Agent 会议最多支持几个 Agent？
没有硬性限制，但建议 2~5 个 Agent 参与，过多会导致对话变长，Token 消耗增大。
MCP 与工具
Q: MCP 服务器连接失败？
- 确认服务器进程已启动
- 检查协议类型是否匹配（stdio / sse / streamable_http）
- 查看 日志 页面获取详细错误信息
深度研究
深度研究模式一直停在"搜索"阶段怎么办？
确认 Agent 可以访问网络搜索工具（Skill 中的 web_search 需要已启用）。如果后端没有配置搜索 Skill，研究模式会退化为普通 Agent 回复。
研究报告质量不高？
尝试：
- 使用更强的模型（如 Claude Sonnet 4 或 GPT-4o）
- 提供更明确的研究主题和范围
- 在输入中指定输出格式要求（如"生成带引用的 Markdown 报告"）
IM 通道
配置了飞书/钉钉/企微，但收不到消息？
- 确认配置保存后已重启 Engine
- 检查 App Secret / Token 是否正确（注意区分测试环境和正式环境的凭证）
- 确认机器人已添加到目标群组或已启用消息接收权限
- 查看日志页是否有连接错误信息
技能市场
ClawHub 技能安装后不生效？
当前 ClawHub 处于 Mock 模式（本地预览），安装操作不会真正下载技能文件。正式版上线后将直接对接 ClawHub 社区 API。本地安装的 .md Skill 文件可以正常使用。
性能与优化
Q: 应用占用内存较高？
河蟹 AI 使用 WebView 渲染界面。正常内存占用约 200~400MB。如果超过 1GB，尝试：
- 关闭不必要的会话标签
- 清理日志缓存（日志页面 → 清除）
- 重启应用
Q: 如何查看引擎运行状态？
仪表盘页面显示 Sidecar 引擎健康状态，包括连接状态、API 端口等信息。引擎每 5 秒自动检测一次。
与其他产品的区别
Q: HexClaw 和 ChatGPT Desktop / Claude Desktop 有什么不同？
ChatGPT Desktop 和 Claude Desktop 是特定服务商的官方客户端，只能连接自家模型。HexClaw 是模型无关的 —— 你可以同时接入 OpenAI、Claude、DeepSeek、Gemini、Ollama 等多个服务商，并在同一个界面中切换。此外，HexClaw 内置了 Agent 引擎、MCP 工具协议、工作流画布和 RAG 知识库，是一个完整的 AI Agent 运行平台，而不仅仅是对话客户端。
Q: HexClaw 和 Cursor 有什么不同？
Cursor 是一款 AI 代码编辑器，专注于编程场景。HexClaw 定位是通用 AI Agent 桌面客户端，覆盖对话、Agent 编排、工作流自动化、知识库等多种场景，不限于代码生成。
数据管理
Q: 如何备份/迁移数据？
HexClaw 的所有数据存储在本地数据目录中（可在 设置 → 通用 → 数据目录 查看）。备份时只需复制该目录。迁移到新电脑时，将数据目录复制到对应位置即可。
Q: 知识库支持多大的文档？
单个文档建议不超过 50MB。知识库总容量取决于本地磁盘空间。文档上传后会自动分块（chunking）和向量嵌入，检索效率不受文档总量影响。