跳转到内容

故障排查:从症状到安全下一步

先保存证据,不先扩大权限

跳转到“先保存证据,不先扩大权限”

故障可能发生在浏览器、Hive Server、Agent 电脑、模型服务或 MCP。先找出哪一层失败,再采取最小动作;不要把所有问题都处理成“切完全访问、重启、再跑一遍”。

先记录:

  1. 大致发生时间、系统与 Hive/运行时版本。
  2. 是本机房主、房主设备还是访客;访问的是哪台 Server,Agent 实际运行在哪台电脑。
  3. 对应任务或调用的状态、排队时间、最后事件和脱敏错误文本。
  4. 已经发生的文件、提交或外部操作,以及问题前后做过的配置变化。

不要提交 Token、环境变量全量、登录二维码、带凭证命令、私有聊天或原始数据库。日志和截图先脱敏;版本信息可用 node --version、hive --help 及运行时自身的版本/帮助命令查看,不要为了读取信息先发起模型任务。

身份与安全边界见安全参考。本文是静态源码依据的排查建议,不表示这些故障已在你的设备上被复现。

页面打不开、地址跳错或连接反复断开

跳转到“页面打不开、地址跳错或连接反复断开”

症状:浏览器无法访问、邀请指向错误地址、远程电脑连 localhost,或页面打开后频繁断线。

排查:

  • 核对 Server 是否仍运行,实际端口与启动时输出的地址是否一致。CLI 默认端口为 8787,但可以被配置覆盖。
  • localhost 指当前设备,其他电脑应访问 Server 的实际局域网或公网地址;多网卡、VPN 和 Wi-Fi 变化可能影响可用地址。
  • 检查防火墙是否允许预期的私有网络访问、访客 Wi-Fi 是否隔离客户端;不要直接关闭整台电脑的防火墙。
  • 公网检查证书、HTTPS/WSS、WebSocket 升级、代理超时和公开地址配置。能加载静态 HTML 不等于 WebSocket 已连接。
  • 确认打开的是 Hive 服务还是独立文档站。文档正文可静态部署,不需要 Hive Server;两者的 404 与发布路径不能混为一谈。

安全动作:先修地址、路由和网络规则。--public-url 只设置公开地址,不自动配置 TLS 或授权;部署见Hive 部署和文档站部署。重启前先核对正在执行的任务,避免把恢复问题变成重复操作。

401/403、邀请失效或设备退出

跳转到“401/403、邀请失效或设备退出”

症状:页面要求重新加入,接口返回未授权、房间无权限,设备管理按钮不可用。

排查:

  • 401 可能是缺少或失效凭据;房间接口的 403 可能是凭据有效但不属于该房间,或当前身份没有管理权限。具体原因以脱敏错误码和页面说明为准。
  • 邀请是否到期、被撤销,访客是否被移除;访客的 Agent 会跟随其授权状态变化。
  • 房主设备会话是否退出、过期或长期闲置。登录身份有效不等于本机管理授权仍有效。
  • 配对或飞书登录票可能过期或已被兑换;已经使用过的登录链接不能无限兑换新设备。
  • 代理是否丢失 Authorization 或返回自己的登录页;不要把自己的房主总令牌换给访客来“修复”错误房间访问。

安全动作:从对应的邀请或房主设备流程重新取得授权;需要管理权时按页面申请。过期或被撤销身份不应通过本机凭据回退、伪造请求头或删除服务端记录绕过。详见房间与身份及权限与审批。

没有本机启动入口、启动失败或名称冲突

跳转到“没有本机启动入口、启动失败或名称冲突”

症状:接入弹窗不能在本机启动、CLI 未找到、Agent 反复退出,或报告同名 Agent 已在线。

排查:

  • 本机启动发生在 Server 电脑;远程/反代访问不自动属于本机请求,房主设备还需要管理授权。检查是否关闭了本机 Agent 功能。
  • CLI 必须安装并配置在 Agent 所在电脑。检查所选运行时命令是否存在、登录或模型配置是否可用,不仅检查 Server 电脑。
  • 选择运行时和权限后须手动点「下一步」;未选中运行时不能进入下一步。
  • 批量启动数量是 1–5,同类设置逐个创建;部分失败前已启动的 Agent 不会回滚。先看已上线名称,不重复启动整批。
  • 同名 Agent 不能同时在线;同一人类用户名可以多标签页在线,两者不要混淆。
  • 工作区/完全访问的命令接入需要显式 cwd,并且目录必须存在、可访问。反复意外退出 5 次/10 分钟会停止自动重启。

安全动作:看本机 Agent 日志,修好 CLI、登录、目录或名称,再启动失败的项。命令接入在目标电脑运行;不要为了启动方便改成完全访问、借用其他人的凭证,或结束不属于当前任务的进程。步骤见接入 Agent。

Agent 在线却不回复、一直排队或委派没回执

跳转到“Agent 在线却不回复、一直排队或委派没回执”

症状:成员在线,但消息停在排队,委派提示卡住,或短时等待没返回结果。

排查:

  • 精确名称是否正确;未提及任何人时,房间是否有主 Agent,以及当前身份是否获准触发它。
  • 看调用详情:是否确认收到、前面是否有任务、是否正在等人回答、被访客授权或协作预算拦截。
  • 不同 worktree 目录的任务可能保持排队,不能通过引导硬塞进另一个 cwd。
  • hive_wait 的 done: false 只表示等待窗口结束,不是子任务失败;stalled: true 可能是离线、排队或尚未确认收到。
  • 跨房间 hive_room_post 的结果留在目标房间,不等同 hive_invoke 自动回执到委派方。

安全动作:先读队列与原因;预算拦截由人按页面决定是否放行。不要反复派同一任务、轮询催促或换名称绕过限制。必要时在明确授权的隔离测试房间使用 Echo 验证消息链路;它不能证明模型、审批或文件权限正常。见协作指南。

MCP 连不上、提示身份错误或某个工具不可用

跳转到“MCP 连不上、提示身份错误或某个工具不可用”

症状:/mcp 报未授权、协议错误,或 Agent 没有预期的额外工具。

排查:

  • Hive MCP 不只需要 URL:需要有效 Bearer 凭据、正确的房间和 Agent 名称身份头,以及该 Agent 在线。访客人类凭据不能替代访客 Agent 凭据。
  • 检查是 Hive MCP 还是额外 MCP;Codex/Claude Code 的本机加载清单可选择额外服务,hive 始终加载,其他运行时的配置入口不完全相同。
  • 代理是否改写 /mcp 路径、丢失身份头、限制连接,或返回 HTML 登录页而不是协议响应。
  • CLI 与协议是否兼容。Codex 的 auto 使用 app-server,不自动降级;旧 MCP transport 只适用于明确选择且已确认支持的 CLI,不能作为盲目重试方案。
  • 工具不存在、权限被拒或外部服务账号失效,是不同问题;开局 token 估算也不是连接成功或账号已授权的证明。

安全动作:用脱敏错误核对配置和版本,不公开 Authorization、不伪造在线身份、不把所有工具改为允许。变更 MCP 加载后在后续回合核对,运行中的调用不会因此撤销。详见权限与 MCP和 CLI 参考。

提问失效、权限申请超时或回复“允许”没生效

跳转到“提问失效、权限申请超时或回复“允许”没生效”

症状:等人回答、提示申请已过期、回复后仍被拒绝。

排查:

  • 普通业务提问:hive_ask_human 进入等人回答,准备回合正常结束后仍可回答,不套用执行中卡住超时。
  • 工具审批:许可交回正在执行的回合;10 分钟未处理、任务结束或停止、Server 重启按拒绝处理。
  • 房主设备管理/高危批准:是独立的限时批准单,不因设备已登录就长期有效,重启后未处理申请作废。
  • 是否回复了原申请,是否具有审批身份;有效访客只能批自己带入的 Agent。
  • 「可以,但先别删」不是明确批准;带条件回复不能转换成安全、可执行的工具范围。

安全动作:确需调整范围时先拒绝,再交新要求;需要重发申请则按相应流程办理。普通提问刚发就失效时保存脱敏状态、错误码与版本,检查是否被停止、撤回或处理,不改成完全访问绕过。详情见提问与协作及工具审批。

失败、结果未知、停止中或恢复后重复担忧

跳转到“失败、结果未知、停止中或恢复后重复担忧”

症状:模型限流、停止没有确认、电脑重启后状态未知,或出现自动恢复说明。

排查:

  • 失败是明确错误;结果未知可能已经做过一部分,不等于什么都没执行。
  • 检查调用详情、实际文件、提交与外部结果。停止和撤回不回滚已发生操作,直接调用停止也不自动停止所有委派子任务。
  • 崩溃后的自动恢复只有中断记录无可能副作用、旧进程退出、原消息/调用仍允许恢复且额度未满时才按原消息重跑,最多 2 次;不保证从写入断点继续。
  • Claude Code/Codex 的上游限流、过载或断流是另一种机制:无可能副作用时可等 1 分钟、3 分钟接原会话继续;改动后或次数用完则需人处理。
  • 睡醒后的心跳和运行中任务有宽限,但不保证网络或模型恢复,也不补跑已错过的定时执行。

安全动作:结果未知先核对,再明确继续范围。删除、部署、付款、发送消息等不得“重试看看”;模型不存在或账号不可用时先修配置。对长时间未确认停止的任务也不要假定进程已退出。详见任务状态与恢复。

页面卡顿、Agent 起不来,或同一种报错反复出现

跳转到“页面卡顿、Agent 起不来,或同一种报错反复出现”

症状:页面操作很慢、Agent 启动卡住,或同一种失败在不同房间反复出现。

排查:

  • 在 Server 所在电脑上以房主身份打开页面,点左侧「故障」。只有这台电脑上的房主能看到这个入口。
  • 「慢操作」里列出超过阈值的任务目录锁、git 命令、重查询和请求,同名的一分钟内合成一行,能看出是哪个命令或哪把锁在拖。
  • 「故障单」把失败分成外部原因、我们自己的问题和说不清的。外部原因(模型服务、网络、凭证、Agent 自己的 CLI)只重试和提示;我们自己的问题按同一种错误合并计数,展开能看到现场和派修记录。

左侧「故障」打开的面板:顶部提示自动派修没打开、可以展开「派修设置」;「待批准的规则提议」有一条 claude 的提议,带批准、拒绝;「我们的问题」里依次是标红的「需要你处理」(已经修失败 2 次)、「修复中」和「待处理」三张单,右上角是出现次数;最下面折叠着已解决、外部原因和说不清是谁的。左侧「故障」打开的面板:顶部提示自动派修没打开、可以展开「派修设置」;「待批准的规则提议」有一条 claude 的提议,带批准、拒绝;「我们的问题」里依次是标红的「需要你处理」(已经修失败 2 次)、「修复中」和「待处理」三张单,右上角是出现次数;最下面折叠着已解决、外部原因和说不清是谁的。

演示环境界面截图:人名、房间和仓库都是示例数据,会跟随文档的明暗主题切换。故障单和规则提议也是演示数据;从「需要你处理」点进来时会直接展开对应那一条。

安全动作:可以手动派修,或标为已解决、忽略。修失败 2 次、改到权限或规则这类受保护代码的单会升级给你,同时出现在左侧「需要你处理」里。自动派修默认关闭,在「故障」面板顶部点「派修设置」展开后打开;合入仍要经过 review。

Worktree 目录选不中、清理被拒或白板不能归档

跳转到“Worktree 目录选不中、清理被拒或白板不能归档”

症状:无法安全选择任务目录、交接后仍在旧目录、worktree 不能删,或清空房间提示工作区占用。

排查:

  • 查看创建返回的路径、分支、基线与 runtimeHandoff。准备回合须正常结束,再由支持的 Bridge 在精确 cwd 创建新会话;不是旧会话直接 cd。
  • 普通发消息、提问、委派、改文件或未知工具可能阻断自动交接;先核对旧工作区,不能重放已经产生的副作用。
  • 同一任务线是否复用同 slug,当前调用绑定是否仍有效,目录/仓库身份是否变化或曾被手工删除。
  • 清理不仅要求已合入,还要求无改动、未跟踪文件、挡住清理的忽略文件及任务占用。node_modules 和构建产物不挡清理,.env 等其他忽略文件会阻止删除,ignoredFiles 列出是哪些。
  • 白板受保护事项还关联已登记 worktree,不能靠归档或清空房间释放。单纯进行中/阻塞的旧事项与受保护工作区不同。

安全动作:使用网页「任务目录」面板、批量提醒或获授权的 hive_worktree_remove。拒绝时保留现场,接受“稍后再试”;不要裸删目录、强删分支、移除登记或删凭证、本地配置来让检查通过。403/404 不证明目录已安全清理,Git 保留分支也不代表清理工具失败。见Worktree 指南。

附件打不开、图片不能看或复制命令无反应

跳转到“附件打不开、图片不能看或复制命令无反应”

症状:附件过期、预览 404、模型仅看到图片元数据,或浏览器不能复制。

排查:

  • 附件是否属于当前房间,原消息是否撤回、文件是否失效;上传是否完成,单文件和一条消息总量是否超限。通常单文件上限 20 MB,一条最多 10 个、合计 50 MB。
  • HTML 预览使用短时链接,过期需从仍有权限的原附件入口重新打开;不要把预览链接当永久公开下载地址。
  • 模型的图片能力、运行时和 MCP 返回格式不同;上传成功不等于模型能理解图像。只读 Agent 不获得附件本地路径,可使用 Hive MCP;可写 Bridge 的本地路径仍受权限和发布边界约束。
  • 复制功能优先使用浏览器 Clipboard API,也有兼容方式;策略限制时按命令区提示手动复制。复制内容含凭据,不要截图或贴进公共聊天排障。

安全动作:从有权限的入口重新读取或上传必要文件,先用非私人小样例核对能力;不扩大附件可见范围、不在不可信 HTML 预览输入秘密。见消息与附件和安全参考。

仍未解决时怎样交给维护者

跳转到“仍未解决时怎样交给维护者”

给出症状、复现步骤、版本、任务状态、脱敏错误码与已经核对的范围,并明确哪些只是推测。将涉及私人数据的原件留在受控环境,公开讨论只用合成样例。

如果需要更新、重启、重置会话或修改数据,先明确授权和影响范围。开新话题不会还原代码或外部状态;不要把删除全部状态目录、强制结束所有进程或更换完全访问当作常规修复。升级与命令参数见 CLI 参考,架构定位见开发参考。