故障排查:从症状到安全下一步
先保存证据,不先扩大权限
跳转到“先保存证据,不先扩大权限”故障可能发生在浏览器、Hive Server、Agent 电脑、模型服务或 MCP。先找出哪一层失败,再采取最小动作;不要把所有问题都处理成“切完全访问、重启、再跑一遍”。
先记录:
- 大致发生时间、系统与 Hive/运行时版本。
- 是本机房主、房主设备还是访客;访问的是哪台 Server,Agent 实际运行在哪台电脑。
- 对应任务或调用的状态、排队时间、最后事件和脱敏错误文本。
- 已经发生的文件、提交或外部操作,以及问题前后做过的配置变化。
不要提交 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)只重试和提示;我们自己的问题按同一种错误合并计数,展开能看到现场和派修记录。


演示环境界面截图:人名、房间和仓库都是示例数据,会跟随文档的明暗主题切换。故障单和规则提议也是演示数据;从「需要你处理」点进来时会直接展开对应那一条。
安全动作:可以手动派修,或标为已解决、忽略。修失败 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 参考,架构定位见开发参考。