常见问题
汇总河蟹 AI 桌面端在安装启动、模型配置、数据隐私、工作流和 MCP 连接上的常见问题与排查方法。
安装与启动
Q: 应用启动后白屏/无法加载？
先区分界面未加载和服务未连接，再按当前服务检查：
- 查看 日志 中的启动或连接错误
- 本机模式检查 Sidecar 是否启动，以及端口
16060是否被占用 - 云端模式检查服务地址、访问令牌和服务器状态；重启桌面应用不会重启云端服务
Q: macOS 提示 "无法打开，因为无法验证开发者"？
右键点击应用 → "打开"，在弹出的对话框中再次点击 "打开"。或者执行：
xattr -cr /Applications/HexClaw.appQ: 如何开机自启动？
进入 设置 → 系统设置 → 通用 → 开机自启，开启即可。macOS 使用 LaunchAgent 实现。
模型与对话
Q: API 请求返回 401 / 403 错误？
进入 设置 → 模型服务，核对当前服务使用的 Provider、地址、凭据和模型访问权限，再查看服务商返回的具体错误。不能只凭状态码认定是余额不足。
Q: 如何使用本地模型（不联网）？
让当前 HexClaw 服务能够访问 Ollama 与已下载的模型，再添加 Ollama 服务商。macOS 安装包包含 Ollama；Windows / Linux 使用本地模型需另行安装：
- Base URL:
http://localhost:11434/v1 - API Key: 留空
- 模型: 填写 Ollama 中实际已下载的模型名
这里的 localhost 指执行 HexClaw 服务的机器。连接云端时，它不是桌面电脑；本地模型也不代表联网搜索、外部工具等任务会自动离线。
Q: 流式输出卡住不动了？
先查看任务进度、工具活动和当前服务的日志，区分模型仍在处理、网络中断与明确失败。可以停止当前请求；支持恢复的任务沿原请求继续。若显示“结果未知”，先查询原任务和已有产物，不要直接重发可能产生计费或外部副作用的操作。
数据与隐私
Q: 我的数据存在哪里？
业务数据保存在当前选择的 HexClaw 服务：
- 本机服务：会话、学习记录、知识资料和生成文件保存在当前设备。
- 云端服务：上述业务数据与服务配置保存在部署服务器。
- 模型凭据：本机 Provider 配置和 API Key 保存在
~/.hexclaw/hexclaw.yaml；云端使用服务器的配置，不使用操作系统钥匙串保存本机 Provider Key。 - 桌面偏好：外观等桌面设置与服务中的业务数据分别管理。在设置中确认当前服务，并查看对应数据位置。
切换本机与云端不会自动迁移或合并会话、学习记录、模型配置和连接。
Q: 数据会发送到第三方服务器吗？
使用在线模型时，处理所需的题目、图片、文件内容和上下文会发送给配置的服务商。联网搜索、MCP、消息渠道等外部工具也会按任务发送所需内容。Ollama 可在本机完成模型推理，但任务是否完全离线还取决于所用工具和服务。
工作流与 Agent
Q: 工作流执行失败了怎么办？
查看失败节点的错误信息。常见原因：Agent 未配置模型、MCP 工具连接断开、Token 超限。
Q: 多 Agent 会议最多支持几个 Agent？
可参与范围以当前运行服务和已配置的智能体为准。按任务需要选择具有明确职责的角色；更多参与者会增加上下文与模型调用，不代表结果一定更好。
MCP 与工具
Q: MCP 服务器连接失败？
- 确认服务器进程已启动
- 检查协议类型是否匹配（stdio / sse / streamable_http）
- 查看 日志 页面获取详细错误信息
深度思考
开启深度思考就会自动联网搜索吗？
思考设置控制所选模型支持的推理能力；联网搜索需要可用的搜索工具和实际调用。查看本次工具活动和来源，区分模型推理与已经取得的检索结果。工具执行没有终态时，先查看原任务状态。
深度思考结果质量不高？
尝试：
- 选择适合任务且支持所需推理能力的模型
- 提供更明确的研究主题和范围
- 在输入中指定输出格式要求（如"生成带引用的 Markdown 报告"）
连接中心 · IM 通道
配置了飞书/钉钉/企微，但收不到消息？
- 在连接页面确认当前服务的通道配置和连接状态；按该通道提示处理需要重新连接的情况
- 检查 App Secret / Token 是否正确（注意区分测试环境和正式环境的凭证）
- 核对接收权限与目标会话绑定；K12 作业辅导使用已绑定的家长与机器人一对一私聊
- 查看日志页是否有连接错误信息
技能市场
ClawHub 技能安装后不生效？
技能市场通过当前 HexClaw 服务查询和安装技能。先在能力 → Skills检查是否已经安装并启用，再核对当前智能体的技能配置、依赖和运行记录。安装或网络失败应查看具体错误；浏览到市场条目不等于已经安装成功。也可通过本地文件或 URL 安装。
性能与优化
Q: 应用占用内存较高？
先区分桌面 WebView、HexClaw 服务与本地模型进程的占用。长会话、媒体预览、文档处理和模型大小都会影响内存需求，可以：
- 关闭暂时不需要的媒体预览
- 查看正在执行的任务与本地模型进程，确认占用来自哪一部分
- 任务结束后仍异常时，保留相关日志，再重启对应应用或服务
Q: 如何查看引擎运行状态？
在设置的服务卡片查看当前本机或云端服务及连接状态，在日志页查看执行详情。“关于”页可查看桌面、后端与组件版本；服务已连接不等于某次任务或消息已经完成。
与其他产品的区别
Q: HexClaw 和 ChatGPT Desktop / Claude Desktop 有什么不同？
HexClaw 的定位是可连接本机或自建云端的开源 Agent 工作台：在同一界面使用多个模型服务商、知识资料、MCP、Skill 和自动化。选择时先比较自己的任务、部署方式、模型和工具需求；其他产品的功能与使用条件以各自当前官方说明为准。
Q: HexClaw 和 Cursor 有什么不同？
HexClaw 面向通用任务交办，包含资料整理、媒体生成、知识检索、自动化和作业辅导。是否适合你的开发任务，要结合已连接的工具、执行环境和实际产物判断；不以能生成代码替代完整开发环境的评估。
数据管理
Q: 如何备份/迁移数据？
先确认数据属于本机还是云端服务。完整服务备份需要覆盖该部署实际使用的数据库、资料与产物目录、配置，按对应部署的方式备份和恢复；复制桌面偏好不能替代业务数据备份。会话可按需导出，家庭学习档案提供 .hexbak 归档与恢复。切换服务本身不迁移数据，模型凭据等配置应单独妥善保存。
Q: 知识库支持多大的文档？
可上传范围以当前服务的文件要求与实际提示为准。容量和处理时间受服务所在机器的磁盘、文档内容、解析与索引配置影响。上传后查看处理进度，检索就绪后再使用；文档数量和索引规模也会影响资源占用与检索表现。