Multica issue 一直停留在 queued 状态怎么排查

当你把一个 issue 指派给 agent（或在评论里 @ 了 agent）之后，发现它在 Multica 的执行日志里始终停在 queued 状态、迟迟不进入 dispatched 或 running，就可以按这篇文章的路径排查。queued 的含义是：run 已经创建，正在等待某个 runtime（执行机上的守护进程 + AI 编码工具）来认领它。只要认领不上，issue 就不会开始执行。适用前提是：Multica CLI 已安装并登录，目标机器上有 daemon 在跑（或本来应该跑）。

排查的核心思路是把问题定位到正确的层：Multica 服务、daemon、runtime、AI 编码工具。文档给出的第一组命令是：

multica version
multica auth status
multica daemon status --output json
multica daemon logs --lines 100

自托管实例还可以直接从执行机上请求服务健康检查：/health 只说明 API 进程在响应，/readyz 还会检查数据库和迁移。

从 issue 的执行日志确认 run 状态

打开目标 issue 右侧边栏的 Execution log（执行日志）区域，找到那条一直停在 queued 的 run。每一行会显示触发来源、执行 agent、状态和时间。如果看不到该区域，点 issue 标题栏的面板按钮展开边栏；窄屏下它默认是收起的。

也可以用 CLI 直接查看某个 issue 的 run 列表（<issue-id> 用类似 MUL-123 的 issue key 或完整 UUID）：

multica issue runs <issue-id>

确认它确实是 queued，而不是 waiting_local_directory（等待另一个 run 释放同一本地目录的锁）——后者的处理方式完全不同，本文只处理 queued。

按顺序检查四个卡点

文档对 queued 给出的排查顺序是固定的，按序检查：

1. agent 绑定的 runtime 是否在线？
2. 该 runtime 是否检测到了 agent 所配置的那个 AI 编码工具？
3. agent 是否还有并发余量？
4. daemon 是否还有全局执行容量？

下面逐项给出检查命令。

1. runtime 是否在线

在执行机上运行：

multica daemon status --output json

同时在 Multica 网页的 Runtimes 页面确认目标计算机和对应的 AI 编码工具显示为 online。

如果 daemon 本身没有起来，先启动它：

multica daemon start

daemon 每 15 秒发送一次心跳；daemon 意外退出后，runtime 最多大约 3 分钟后会显示为 offline。offline 期间已入队的 run 会一直等待它恢复——这正是 queued 长期不动的常见原因之一。

如果 daemon 起不来，常见原因包括：CLI 未登录或本机 token 过期、daemon 连错了 Multica 服务、执行机访问不到 API（DNS/TLS/防火墙）、当前账号已不是目标 workspace 的成员，或本机没有安装任何受支持的 AI 编码工具（daemon 至少要检测到 1 个内置支持的工具才会启动）。重新登录并重启 daemon：

multica login
multica daemon restart

2. 工具是否被 daemon 检测到

runtime 列表里缺少预期的工具时，先确认该工具能在同一系统账号、同一 PATH 下直接运行且已完成登录，再重启 daemon：

multica daemon restart

验证工具可发现性（<command> 换成实际命令，如 claude、codex、cursor-agent）：

command -v <command>
<command> --version

如果终端里能找到、但 Desktop 或后台 daemon 找不到，通常是两者使用的 PATH 不同：重启应用，或通过对应的 MULTICA_<PROVIDER>_PATH 环境变量设置绝对路径（完整配置见 环境变量文档）。

注意最低版本要求：低于最低版本时 daemon 不会注册对应 runtime。文档列出的部分最低版本为：Claude Code 2.0.0、Codex 0.100.0、Copilot 1.0.0、Grok 0.2.89、Qwen Code 0.20.0、MiniMax Code 0.1.2。工具清单与各自的可执行命令名见 安装 AI 编码工具。

daemon 日志里如有版本、路径或认证错误，用下面命令跟踪：

multica daemon logs --follow

3. 与 4. 并发余量是否耗尽

默认限制是：单个 agent 最多 6 个 run 并发，单个 daemon 最多 20 个 run 并发，实际生效值取两者中较小的。达到上限后，新 run 会一直留在队列里，直到有正在执行的 run 结束。

• agent 级并发：在 agent 设置中调整，或用 multica agent get <agent-id> 查看该 agent 的当前配置确认。
• daemon 级上限：环境变量 MULTICA_DAEMON_MAX_CONCURRENT_TASKS（默认 20），或启动参数 --max-concurrent-tasks，也可以持久化为 max_concurrent_tasks（multica config set max_concurrent_tasks <n>）。

如果确认是并发打满，处理办法是等活跃 run 结束，或调高上限。调高前要明白文档的提示：并行的 run 会同时竞争机器资源、工具账号配额和同一工作目录。

理解排队规则：queued 什么时候才会失败

这决定你要等多久、什么时候该动手：

• runtime 只要还在心跳（哪怕只是忙），它排队的 backlog 就不会因等待过久而失败，会一直等它慢慢消化。
• queued 的 run 只有在同时满足两个条件时才失败（失败原因记为 queued_expired）：runtime 停止心跳超过重连宽限期（reconnect grace），且该 run 本身入队时间也超过了这个宽限期。
• 宽限期由服务端的 MULTICA_RUNTIME_RECONNECT_GRACE 控制，默认 3h，低于 150s 的值会被截断。
• 把任务指派给一台已经下线的机器时，run 仍会获得一个完整的宽限期等你把它救回来，而不是立即失败。
• queued 状态的 run 不属于自动重试范围。

所以"排了很久的队"本身不报错、不自动消失，需要人工按上面四个卡点定位原因。

验证与恢复

逐项修复后，用以下方式确认问题真的解决了：

1. Runtimes 页面：目标计算机与对应工具显示 online，且该 runtime 在 agent 可选范围内。
2. 执行日志 / multica issue runs <issue-id>：那条 run 离开 queued，进入 dispatched（已被认领、正在启动工具，此状态超过 5 分钟会被判失败），再进入 running。
3. 如果之前已经以 queued_expired 失败，确认 runtime 在线后，从执行日志里对该 run 点重试；CLI 侧也可以重新入队：

multica issue rerun <issue-id>

rerun 针对 issue 当前的 agent 指派人，并使用全新的会话和工作目录；而执行日志里对某一条历史 run 的重试，用的是当时处理那条 run 的 agent，即使 issue 后来改派了也不会切换。

参考

• Troubleshooting：分层排查的完整入口，含 daemon 连接失败、日志位置等章节。
• Runs：run 的全部状态、超时后果与失败原因对照表。
• Daemon and runtimes：runtime 如何注册与报告在线状态、offline runtime 的排查顺序。
• CLI：daemon、runtime、issue runs、rerun 等命令的完整参数。