故障排除

先保留证据：当前构建身份、安全错误文本、受影响的会话/工作流、容量状态、近期日志和 Git 状态。在确认持久化操作是否已经成功前，避免清理、删除或盲目重试。

Web UI 无法启动

**检查：**在前台运行服务器，调用 curl -fsS http://127.0.0.1:9889/health，确认端口在回环地址监听，并在可用时检查 Settings → About。

**解决方法：**修复报告的依赖/配置错误或端口冲突。如果健康检查成功但静态文件不可用，请验证候选版本，并确保 Python 代码和打包 Web 资源来自同一构建。

另一台机器上的浏览器无法连接

当 ThreadCells 正确监听在回环地址时，这是预期行为。不要改为公开绑定。请使用远程访问中的 SSH 隧道或经过认证的代理。

提供商显示未安装 CLI

**检查：**比较 Settings → Providers 与 Spawn Agent，然后以 ThreadCells 运行时用户执行 command -v PROVIDER_COMMAND。

**解决方法：**为该账户安装提供商的规范 CLI，修正其服务 PATH，或选择其他就绪提供商。仅注册适配器并不等于完成安装。

提供商已安装但未认证

**检查：**以运行时用户执行提供商支持的认证状态命令。

**解决方法：**完成提供商原生登录流程。ThreadCells 不会复制其他用户的凭据，也不会在预检期间登录。

提供商提示就绪状态未验证

命令存在，但无法暴露安全的非交互式认证事实。验证其版本，并进行一次小型原生测试。它可能仍可启动；请检查生成的终端中是否有提供商登录提示。

代理未启动

**检查：**提供商就绪状态、所选配置文件的解析后的预览、项目路径/权限、常驻/Provider/Work 容量、tmux 可用性和终端启动输出。

**解决方法：**修复第一个失败的准入项或提供商前提条件。第一个会话仍在启动时，不要反复启动重复会话。

容量耗尽

打开 Orchestration Capacity 并确定确切的已满类别。安全退役已完成工作，或等待相应提供商/重型任务。仅当主机和配额经测量确有余量时，才提高相应限制。

重型执行槽位不可用

构建、浏览器测试、扫描或恢复作业占用了 Heavy 槽位。等待其完成，或通过规范状态检查过期租约。不要为了绕过队列而在准入之外运行昂贵命令。

工作流等待所有者

阅读门控原因。仅当它是实际的发布、信任、破坏性、成本或产品语义边界时，才提供请求的决策。普通提供商最终回复应保留符合条件的自主工作；若发生自动关闭，请将其报告为工作流缺陷。

结果未纳入

确认子项已记录持久化结果，并已投递给正确的父项。父项必须读取/使用不可变结果，然后确认已纳入。重启重放可能再次投递未确认结果；不要重复应用它。

新的所有者输入排在已关闭工作流之后

重启一次受支持运行时，并检查精确的工作流和 Inbox 身份。当前构建会协调其绑定工作流已不再开放的待处理普通 Inbox 传输，然后允许较新的开放所有者回合继续。不要重新绑定或手动编辑 Inbox 行；如果过期传输仍待处理，或任何载荷跨越工作流身份，请保留数据库并报告缺陷。

未配置操作员授权

确认 THREADCELLS_OPERATOR_VERIFIER_FILE 已传递给实际服务器进程，然后重启。如果配置无效，请检查 schema、绝对/规范路径、文件所有者/模式、可读性和每个父目录。服务账户不得拥有或能够替换验证器。

正确的操作员密钥失败

确认服务器加载了 CLI 生成器所用的同一验证器。最小长度严格为五个字符。检查是否有旧服务器进程或最近替换的验证器；不要记录输入的密钥。

解锁操作员变更后打开 Settings → Telegram。Not configured 表示需要有效 bot token 和 chat ID。Invalid 表示私有 token 文件未通过所有权、常规文件或模式检查。成功的连接检查会验证 bot 凭据；发送显式测试通知以验证 chat 和可选 topic ID。如果任一操作失败，请检查出站 HTTPS/DNS。安全错误有意省略 Telegram 响应正文和 token。请参阅Telegram 通知。

Statistics 缺少当前会话

刷新用量/状态，验证提供商支持遥测，并确认其持久化 rollout 证据仍可读取。会话无需在计数前删除。缺失的提供商字段应显示未报告，而非零。

Statistics 总数似乎重复

比较全局、会话和终端维度，并保留数据库。提供商累计快照应在轮询/重启/重放期间更新一个稳定检查点。诊断前不要手动删除行。

Docs/构建身份不匹配

Settings → About、Docs 页脚、候选清单和静态资源修订版本应保持一致。重新构建并验证一个不可变候选版本；不要把一个检出的 Web 输出与另一个检出的 Python 代码混合。

磁盘压力或 Housekeeping 无法回收

检查 Housekeeping dry-run 计划。受保护、活动、未知、备份、当前和回滚项目会被有意保留。处理报告的所有者/引用问题，或安全扩充磁盘；绝不要递归删除运行时根目录。

如需最大化已证实安全的回收量，请检查单独的 Full Cleanup 预览。执行会一直受阻，直到每个智能体都被权威证明为空闲，且没有提供商、Heavy、排队变更或运行时操作处于活跃状态。不要关闭 Ready 智能体或削弱该门控：其继续执行状态仍受保护。Full Cleanup 会移除所有已证实不活跃的本地发布版本，因此请确认失去本地回滚可以接受。受保护的含糊工具、备份、源代码权限、dirty 或 unpublished worktree 以及未知路径都应作为预期报告条目，而不是手动删除它们的理由。