Multica 任务失败原因码（如 provider_auth_or_access、queued_expired）怎么对照处理

Multica 里每次 agent 开始工作都会产生一条 run（运行记录），运行失败后，issue 右侧边栏 Execution log 的该行会带一个失败原因码，Usage 统计里也会按同样的码归类。当你看到 agent_error.provider_auth_or_access、queued_expired 这类码时，需要判断两件事：失败卡在平台/调度层还是卡在 AI 编程工具自身，以及该不该自动重试、要先修什么再手动重试。本文按 Runs 的 Failure reason reference 整理对照表和处理路径。

原因码分两组

• 无 agent_error. 前缀：由平台（服务器或 daemon）记录，表示失败归因于平台、调度或运行时这一层，而不是 agent 进程做错了什么。
• agent_error.*：由 AI 编程工具自身返回的错误文本分类而来，表示工具进程已经跑起来了，但被 provider、模型或工具自身挡住。

在 issue 侧边栏的 Execution log 中，点击某行的 View transcript 可以看到 agent 的消息、工具调用和错误输出，这是定位具体失败时应该先打开的地方。

平台侧原因码对照

原因码	含义	文档给出的处理
runtime_offline	运行期间 runtime 掉线	恢复 runtime 后重试；参考 Daemon and runtimes
queued_expired	runtime 心跳缺席超过重连宽限期，且该 run 排队也已满这么久	确认 runtime 在线后重试
runtime_recovery	daemon 重启后回收了一条被中断的 run	直接重试
environment_prepare_failed	daemon 无法为本次运行准备执行环境（工作目录或写入其中的本地 runtime 配置）	读原始错误确认哪一步失败，再检查该机器：磁盘空间、权限、目录仍被占用、AI 编程工具的本地配置
cancelled	手动停止，或随归档/删除被取消	无需处理
timeout	超过 daemon 配置的执行时间上限	收窄 issue 范围，或调整 daemon 的 agent_timeout
iteration_limit	达到单条 run 的迭代上限	收窄 issue 范围
agent_blocked	agent 报告它无法继续	补上它评论里要的东西
api_invalid_request	平台 API 拒绝了无效请求	重试；若反复出现则上报问题
codex_semantic_inactivity	Codex 长时间没有有效输出，被判定停滞	重试，或调整 Codex 不活动超时

关于 queued_expired，有一个容易误解的点：排队久本身不会让任务过期。只要 runtime 还在发心跳，它就只是忙，积压可以慢慢消化。一条排队中的 run 只有同时满足两个条件才会失败：runtime 的心跳已缺席超过重连宽限期，并且该 run 自己也已经排队了同样长的时间。第二条条件意味着你把工作派给一台已经睡机的机器时，仍有一整段宽限期把机器弄回来，而不是立刻失败。queued 状态的任务不参与自动重试。

agent 侧原因码对照（agent_error.*）

原因码	含义	文档给出的处理
provider_auth_or_access	模型服务认证失败或无访问权限（401/403）	在该 AI 编程工具中重新登录，或检查 API key
provider_quota_limit	额度或余额耗尽（402）	充值或换账号
provider_capacity_or_rate_limit	被限流或容量不足（429/529）	稍后重试
provider_server_error	模型服务商服务端错误（5xx）	稍后重试
provider_network	到模型服务商的网络故障	会自动重试；若持续存在，检查执行机器的网络
model_not_found_or_unavailable	模型不存在或当前不可用	在 agent 设置里换一个可用模型
context_overflow	上下文超出模型窗口	收窄 issue 范围或减少输入
missing_config	缺少 API key 等必需配置	补上 agent 的环境变量或工具配置
runtime_missing_executable	找不到 AI 编程工具的可执行文件	重装工具；参考 Install AI coding tools
runtime_version_unsupported	工具版本过旧	升级工具
process_failure	工具进程异常退出	查看运行记录定位原因，再重试
empty_or_unparseable_output	工具无输出或输出无法解析	重试；反复出现则检查工具安装
agent_timeout	工具长时间无响应后被终止	重试，或收窄 issue 范围
unknown	未分类失败	查看运行记录中的原始错误

哪些失败会自动重试

普通 run 默认最多执行两次；工具网络中断最多三次，最后一次在约 5 秒延迟后开始。自动重试只覆盖以下瞬态故障，且只适用于挂在 issue 或 chat 上的 run（Autopilot 的 run only 模式不自动重试，避免与下一次计划运行重叠）：

可自动重试的失败	尝试上限
Runtime 掉线	默认 2 次（首次运行 + 1 次重试）
daemon 重启后被回收	默认 2 次
平台判定的执行超时	默认 2 次
Codex 停滞无有效输出	默认 2 次
Skill 包下载失败	默认 2 次（此时 agent 进程尚未启动；已下载的包走本地缓存）
工具网络中断	最多 3 次

其余原因——认证、额度、配置、模型等——永不自动重试，必须先修复原因再手动重试。

按高频码走处理路径

provider_auth_or_access：重新登录或核对 API key

这类错误不会被自动重试，因为重试同样会 401/403。处理顺序：

1. 在执行机器上直接打开终端运行该 AI 编程工具本身，确认它已完成登录且能独立完成请求。如果工具自己在终端里都跑不通，先修它的登录或配置。
2. 在该工具中重新登录，或检查 API key；missing_config 走同类路径——补上 agent 的环境变量或工具配置。
3. 登录或安装状态变化后，重启 daemon 让它重新检测：

multica daemon restart

4. 从 Execution log 手动重试该 run。

queued_expired / runtime_offline：先让 runtime 回来

queued_expired 的修复对象是机器而不是任务。按 Daemon and runtimes 的离线排查顺序：

multica daemon status
multica daemon logs -f
command -v <tool-command>

1. multica daemon status 确认 daemon 在运行。
2. multica daemon logs -f 找登录、网络或工具检测错误。
3. 在相同环境用 command -v <tool-command> 确认 daemon 能找到该工具（<tool-command> 换成实际命令，如 claude、codex）。
4. 打开 Multica 的 Runtimes 页面，确认目标机器和对应 AI 编程工具显示为在线。
5. 安装、改路径或更新 profile 之后运行 multica daemon restart。

如果机器是健康的、只是任务一直排队（queued 而非已失败），按 Troubleshooting 的顺序检查四点：runtime 是否在线、是否检测到 agent 配置的工具、agent 是否还有并发余量（默认每个 agent 最多 6 条并发 run）、daemon 是否还有全局容量（默认单个 daemon 最多 20 条）。可用这些命令核对：

multica daemon status --output json
multica agent get <agent-id>
multica issue runs <issue-id>

限流与服务端错误：稍后重试

provider_capacity_or_rate_limit（429/529）和 provider_server_error（5xx）都是瞬态的，文档给出的处理就是稍后重试。provider_network 会自动重试，如果持续出现，检查执行机器的网络。

environment_prepare_failed：读原始错误，修执行机器

这个码表示 agent 进程根本没有启动：daemon 在本机构建/重开执行环境（工作目录、写入其中的本地 runtime 配置）时失败了。先读运行记录里的原始错误确认是哪一步失败，再检查该机器——磁盘空间、权限、目录仍被其他进程占用、或 AI 编程工具的本地配置。所有修复都发生在运行 daemon 的这台机器上。

收窄范围与配置类

• context_overflow、iteration_limit、timeout：收窄 issue 范围；timeout 还可以调整 daemon 的 agent_timeout（该配置项默认为不限时，见 Environment variables）。
• agent_blocked：这不是系统错误，agent 是主动进入 blocked 状态等人——把它评论里要的信息补上。
• model_not_found_or_unavailable：在 agent 设置里换一个该账号可访问的模型。
• runtime_version_unsupported：升级工具。文档列了最低版本线（如 Claude Code 需 2.0.0 以上、Codex 0.100.0 以上），低于最低版本时 daemon 不会注册对应的 runtime。
• unknown：查看运行记录中的原始错误再判断。

手动重试的两种入口

• Execution log 行上的重试按钮：调用的是当时处理该 run 的 agent。即使 issue 后来改派给了别人，重试也不会切到新 assignee。重试会尽量保留上一次 run 已写入本地目录的文件；如果原会话仍然安全且由同一个 runtime 认领重试，它会继续之前的会话。会污染会话的错误（如 context_overflow、api_invalid_request）会在原工作目录上开新会话；原目录已不存在时使用新工作目录。
• CLI 重跑当前 issue：

multica issue rerun <issue-id>

这种形式不指向某条过去的 run，使用 issue 当前的 agent assignee，并从头开新会话、新工作目录。

验证处理结果

重试后在 Execution log 跟踪该行状态变化即可判断：

• dispatched（已被认领、工具启动中）停留超过 5 分钟会被判失败；
• running 没有固定时长上限，存活性跟随 runtime 心跳——心跳每 15 秒一次，心跳丢失后最迟约 3 分钟 runtime 被标记离线，其运行随之失败；
• completed 表示这条 run 正常结束，但不等于 issue 目标已达成，结果仍需人工复核。

如果失败时该 issue 没有其他活跃 run、也没有等待中的新重试，一次失败会把 in_progress 的 issue 退回 todo——这是判断"失败已被系统处理完、等修复后重试"的一个可观察信号。