1. 为什么要在 opencode 里折腾循环任务如果你已经在用 opencode 做本地编码助手大概率遇到过这种场景改完一版代码想让 AI 每隔几分钟自动看一眼 CI 有没有挂、部署有没有起来、review 评论有没有新增。手动敲一遍 prompt 当然可以但人总会忘而且重复劳动本身就很烦。opencode-plugin-loop 这个插件解决的就是这件事——它给 opencode 加了一个/loop命令让同一个 prompt 按固定间隔或自适应间隔反复执行灵感直接来自 Claude Code 的同名能力。先说清楚它是什么、能做什么、适合谁。opencode-plugin-loop 是一个为 opencode 量身打造的调度插件核心是/loop命令/loop 5m prompt表示每 5 分钟重发一次这个 prompt/loop prompt不带时间则由 LLM 自己决定下一次什么时候触发裸/loop会去读.opencode/loop.md里的维护脚本。它适合需要在本地编码助手内跑自动化循环任务的开发者比如 CI 巡检、部署观察、PR review 轮询这类周期性动作。任务绑定创建它的 sessionID不会跨会话串扰持久化到.opencode/cache/loop/tasks.json重启也能存活。我试过把它接进日常的仓库维护流程最大的感受是「省心」——不用再盯着终端手动重发。下面从环境要求一路写到排障每一步都能直接复制。2. 装插件前先把 opencode 和 Node 环境对齐装任何插件之前先把地基打牢。opencode-plugin-loop 对环境有明确要求版本不对会出现插件加载了但/loop不生效的情况这类问题排查起来很费时间不如一开始就对齐。组件版本要求如下组件版本要求说明OpenCode 1.17.18用于交互式 TUI 伴侣低于这个版本对话框行为会异常Node.js 18插件构建与运行依赖调度服务端插件本身有原生 toast 兜底所以即使 TUI 版本稍旧也能跑但支持的 OpenCode 版本会自动安装 package 的两个入口点server 与 tui体验才完整。先确认版本opencode --version node --version如果 OpenCode 低于 1.17.18先升级再继续。Node 低于 18 的话用 nvm 或系统包管理器升上去。这两步做完再进入安装环节。安装方式有三种推荐第一种。通过 OpenCode 插件安装器安装opencode plugin opencode-plugin-loop --global --force这条命令会同时识别 npm 包里的 server 与 TUI 入口点并把无版本号的包名写入全局opencode.json与tui.json后续升级不用手动改版本号。注意一个细节如果/loop还没在你的 OpenCode 配置里定义需要把下面「手动配置」里的command.loop段手动加进opencode.json。OpenCode 会自动发现 npm 包的两个插件入口点但目前不会把包内的commands/loop.md拷到你的配置目录。升级到最新版本也是同一条命令--force会替换已安装版本并刷新全局配置里的两项执行完重启 OpenCode。手动配置方式适合想精确控制配置文件的同学。把包名分别加入两个配置文件的plugin数组。服务端配置~/.config/opencode/opencode.json{ plugin: [opencode-plugin-loop], command: { loop: { description: 定时重复执行 prompt。可选间隔: s/m/h/d。子命令: list | status | cancel id | pause id | resume id | stop-all加 --all 跨 session, template: $ARGUMENTS, agent: build } } }TUI 配置~/.config/opencode/tui.json{ $schema: https://opencode.ai/tui.json, plugin: [opencode-plugin-loop] }从源码安装适合要改插件本身的开发者git clone https://github.com/jkrandom-sudo/opencode-plugin-loop.git cd opencode-plugin-loop npm install npm run build opencode plugin file:///absolute/path/to/opencode-plugin-loop --global --force改完src/后重新npm run build再重启 OpenCode 加载新版本。这里有个坑插件只能从一处来源安装。OpenCode 会分别从opencode.json的 npm 插件目录和~/.config/opencode/plugins/下拷贝的插件加载包名相同也会重复加载导致任务行覆盖输入区之类的怪现象。装完先检查有没有残留拷贝ls ~/.config/opencode/plugins/opencode-plugin-loop如果存在移出自动加载目录再重启mv ~/.config/opencode/plugins/opencode-plugin-loop \ ~/.config/opencode/plugins/opencode-plugin-loop.backup验证 npm 安装正常后再删备份。3. 可复制的配置片段与循环任务写法配置这块分两层插件选项和命令用法。插件选项写在opencode.json里控制调度器的全局行为{ plugin: [opencode-plugin-loop], opencode-plugin-loop: { maxTasks: 50, taskTtlDays: 7, defaultAdaptiveMinMs: 60000, defaultAdaptiveMaxMs: 3600000, tickerIntervalMs: 15000 } }字段含义对照字段默认值说明maxTasks50最大并发任务数taskTtlDays7任务过期时间天加载时自动清理defaultAdaptiveMinMs60000自适应模式最小间隔毫秒defaultAdaptiveMaxMs3600000自适应模式最大间隔毫秒tickerIntervalMs15000内部调度器检查间隔毫秒命令用法上固定间隔模式支持 s/m/h/d 四种单位/loop 5m check if the deploy finished /loop 30s ping the health endpoint /loop 2h look for failing CI runs自适应间隔模式不带时间参数LLM 每次执行都会收到 prompt并通过loop_schedule工具自主选择下一次间隔160 分钟/loop check whether CI passed and address any review comments裸/loop会读维护脚本。在项目根目录新建.opencode/loop.md项目级或user/.opencode/loop.md用户级Check the release branch PR. If CI is red, pull the failing log, diagnose, and push a minimal fix. If new review comments have arrived, address each one. If everything is green, say so in one line.下次直接输入/loop就按这个脚本跑维护任务。子命令默认只作用于当前会话加--all跨会话/loop list # 当前会话任务 /loop list --all # 所有会话任务带 [s:xxxx] 标签 /loop status # list 的别名 /loop cancel taskId # 取消指定任务 /loop cancel taskId --all /loop pause taskId /loop resume taskId /loop stop-all /loop stop-all --all如果尝试取消属于其他会话的 taskId会收到拒绝提示并提示加--all。程序化调用走 LLM 工具默认绑定当前会话传all: true跨会话loop_schedule({ action: create, prompt: check the deploy, intervalMs: 300000 }) loop_schedule({ action: cancel, taskId: abc12345 }) loop_schedule({ action: reschedule, taskId: abc12345, nextDueAtMs: Date.now() 300000 }) loop_status({}) loop_status({ all: true })如果你同时用 Claude Code 或 Cline MCP 这类工具配置三件套要写全Base URL、Key、Model ID。以接入 TaoToken 为例Base URL 填https://taotoken.net/apiKey 在控制台生成Model ID 按你选的模型填。opencode 侧在opencode.json里对应配置 provider 即可插件本身不碰模型配置两者互不干扰。4. 验证插件生效与成功结果长什么样装完配置别急着上生产任务先做一次最小验证。重启 OpenCode 后在任意会话里敲/loop 30s echo hello from loop预期行为是命令提交后弹出一个独立的 OpenCode 原生对话框显示任务已创建带一个 taskId。这个对话框和 prompt 输入区完全隔离不会覆盖你正在输入的内容。对话框提供三个操作Copy ID: taskId复制结果里出现的每个任务 ID、Copy all复制完整结果文本、Close关闭。用鼠标或方向键选按 Enter 或 Space 确认。复制成功会显示确认并自动关闭剪贴板访问失败则保持打开并报错。长文本用 Page Up / Page Down 滚动按 q 或 Esc 关闭。窄终端下对话框自动缩放到可视区域结果区和操作列表独立滚动。接着验证任务真的在跑/loop list应该能看到刚才创建的任务带 taskId、间隔、下次触发时间。等 30 秒左右观察会话里是否出现新的执行结果。再查调度记录cat .opencode/cache/loop/history.log有调度记录说明 ticker 正常工作。任务持久化在.opencode/cache/loop/tasks.json可以打开看结构cat .opencode/cache/loop/tasks.json每个任务携带 sessionID 字段这是会话隔离的关键。生命周期行为是这样的用户在 session A 执行/loop任务创建sessionID ATicker 每 15 秒扫描只触发 sessionID activeSessionID 的任务通过 chat.message hook 追踪活跃会话切到 session B 后A 的任务挂起等待session A 触发 session.deletedA 的所有任务自动取消插件热重载时老 ticker 停止、新 ticker 启动in-flight 任务由 inflight Set 守护没有 sessionID 的旧 tasks.json 加载时丢弃并打日志。验证自适应模式/loop check whether CI passed and address any review comments这次不带时间参数执行后 LLM 会通过loop_schedule决定下一次触发时间范围在 160 分钟。用/loop status看下次触发时间是否被动态调整。如果一切正常你会看到任务按 LLM 判断的节奏重新触发而不是固定间隔。5. 常见报错排查401、local proxy failed、reading choices、OAuth排障这块我踩过的坑不少按真实报错对照着看。401 未授权多半是模型 provider 的 Key 没配好或过期。opencode-plugin-loop 本身不管理模型鉴权它只负责调度 prompt。检查opencode.json里 provider 的 apiKey 字段确认 Key 有效。如果你用 TaoToken 接入去控制台重新生成 KeyBase URL 用https://taotoken.net/api别带多余路径。401 出现时/loop任务会照常触发但每次执行都失败history.log 里会连续记录错误。local proxy failed这个报错通常和本地网络配置有关。先确认 opencode 能正常发起模型请求——手动发一条普通 prompt 试试。如果普通请求也失败问题在 provider 配置而非插件。检查opencode.json里的 baseURL 是否可达用 curl 测一下curl -I https://taotoken.net/api返回 200 或 401 都说明网络通401 是没带 Key 的正常响应。如果 curl 都不通先解决网络层。reading choices 报错这是解析模型响应时choices字段读不到常见于返回体格式和预期不符。检查 Model ID 是否填对有些模型名带版本后缀填错会返回错误结构。另外确认 provider 的响应格式是 OpenAI 兼容格式。opencode-plugin-loop 不解析模型响应内容它只把 prompt 交给 opencode 执行所以这个错在插件之外修 provider 配置。OAuth 相关报错如果你用 OAuth 方式登录某个 providertoken 过期会报鉴权失败。重新走一遍 OAuth 流程或在配置里改用 API Key。OAuth 和 API Key 别混用同一 provider 只保留一种鉴权方式。任务没触发按顺序查——OpenCode 版本是否 1.17.18/loop list看任务是否注册tickerIntervalMs是否被改得过大.opencode/cache/loop/history.log有没有调度记录。如果任务在 list 里但从不触发检查当前活跃 session 是否就是创建任务的 session跨 session 的任务默认挂起。任务行覆盖输入区0.2.4 之前的版本会把/loop结果直接写终端OpenCode 重绘 UI 时可能造成任务 ID 与 prompt 串行。升级到 0.2.6它用响应式交互对话框运行期诊断信息写入 OpenCode 结构化应用日志。同时确保插件只从一处来源安装重复加载是常见诱因。想清理所有历史任务rm -rf .opencode/cache/loop下次启动插件重建空目录。6. 把循环任务接进你的日常编码流跑通之后几个实践建议。CI 巡检用/loop 10m check the latest CI run for my branch让 AI 自动分析失败用例。部署观察用/loop 30s curl the staging health endpoint and report status。Review 自动化在.opencode/loop.md里写 PR review 流程对重要仓库轮询检查。自适应模式谨慎用间隔由 LLM 决定可能产生不可预测的频率建议在 prompt 里给出明确的最长间隔提示。短期任务完成后主动/loop cancel taskId清理避免堆积超过 maxTasks。如果你需要长期跑编码 Agent 或更复杂的自动化流程可以了解下 Coding Plan配合循环任务能把仓库维护的重复动作压到最低。模型对话页适合先验证模型连通性接入文档里有完整的 Base URL 和 Key 配置说明。API Keys 页面生成和管理你的密钥排障时对照着检查最直接。最后提醒一句插件配置和模型配置是两套东西/loop不生效先查插件安装和 session 隔离任务触发了但执行失败先查 provider 鉴权和网络。把这两层分开看大部分问题十分钟内能定位。