OpenCode 中途卡住与上游错误：四步排障工作流

一句话结论

遇到 Ox Alpha 长时间不动时，先区分服务端错误和本地扫描/MCP 阻塞，再用 .ignore、snapshot: false 和临时移除 MCP 的顺序缩小问题范围。

适用场景

• 适合的任务：OpenCode 打开大型仓库后无响应、请求一直重试或中途挂起。

• 不适合的任务：把本地排障配置当作模型能力提升，或直接在生产仓库删除工具配置。

• 适用的模型版本：Ox Alpha；适用于 OpenCode CLI 的对应版本。

• 适用的客户端、Agent 或 API：OpenCode；原帖讨论的是 OpenCode 的 Ox Alpha 会话。

• 推荐的推理档位和参数：未公开；先保持模型参数不变，只改一个环境变量或配置项。

可直接使用的内容

原帖公开的是排障步骤而不是 prompt。可直接照做的工作流如下：

1. 查看 ~/.local/share/opencode/log/opencode.log，确认是认证/网络错误，还是本地扫描卡住。
2. 检查项目根目录是否包含多 GB 的资源目录；在项目根目录创建 .ignore，把大型资产目录排除。
3. 在 opencode.json 中暂时设置 "snapshot": false，重新启动并比较是否恢复。
4. 若仍卡住，临时重命名 .mcp.json，再运行一次；若恢复，逐个恢复 MCP 服务定位阻塞项。
5. 每次只改一项，并记录启动耗时、首次请求耗时和错误文本；定位后再恢复不相关配置。

适用边界

• .ignore 与 snapshot 只针对该评论作者遇到的扫描/快照问题，不是 OpenCode 官方保证。

• “Endpoint is unavailable” 等错误也可能来自服务端过载；本地配置修复不了服务端限流。

• 任何重命名或忽略配置都应在可回滚分支、脱敏仓库上进行。