OpenClaw Lobster 工作流工具确定性多步管线与可恢复审批门实战指南【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawLobster 是 OpenClaw 的可选插件工具用于将多步工具调用封装为一次确定性执行的工作流管线并在副作用操作发送、发布、删除前设置人工审批检查点。本文基于 Lobster 技能文档 展开结合 插件源码、运行器实现 与 测试用例讲清它的适用边界、run/resume 完整调用协议、参数默认值与底层执行机制读完后你可以独立编写带审批门的工作流并理解每个错误信息的来源。一、Lobster 解决什么问题一次调用替代多次往返没有 Lobster 时一个多步骤任务如邮件分诊意味着模型要编排多次往返的工具调用先列邮件、再总结、再按用户指示逐条回复且每轮之间没有状态记忆。Lobster 把这种编排移入一个类型化的工作流运行时一次调用而非多次一次lobster工具调用即可返回整条管线的结构化结果内置审批副作用步骤会暂停工作流直到显式批准可恢复暂停的工作流返回 resume token批准后继续执行而无需重跑前面的步骤。Lobster 刻意设计为一个小而受限的 DSL而非通用脚本语言管线是数据便于记录、diff、回放、审查approve/resume 是持久化的内建原语超时、输出上限、沙箱检查与白名单由运行时统一强制。何时该用 Lobster决策表原文档给出了一个清晰的意图判断表直接继承如下用户意图是否使用 Lobster“Triage my email”分诊我的邮件是 — 多步骤可能发送回复“Send a message”发送一条消息否 — 单一动作直接用消息工具“Check my email every morning and ask before replying”每天早上检查邮件并在回复前询问是 — 带审批的定时工作流“Whats the weather?”天气如何否 — 简单查询“Monitor this PR and notify me of changes”监控这个 PR 并通知变更是 — 有状态的、周期性的反过来不要在以下场景使用 Lobster简单单动作请求直接调用工具即可、流程中途需要 LLM 解释的查询、以及一次性的不会重复执行的任务。二、插件安装与启用可选工具与白名单机制Lobster 以插件形式存在包名为openclaw/lobster插件 id 为lobster。从 插件清单 可以看到其关键元数据{ id: lobster, activation: { onStartup: true }, contracts: { tools: [lobster] }, toolMetadata: { lobster: { optional: true } } }其中optional: true是关键设计因为该工具可能通过工作流触发副作用它默认不开放需要显式加入 agent 的工具白名单。按 插件 README 的安装方式为openclaw plugins install openclaw/lobster安装或更新插件后需重启 Gateway。启用时把插件 id 加入 agent 的tools.allow以插件 id 为单位启用该插件全部工具{ agents: { list: [ { id: main, tools: { allow: [lobster] } } ] } }README 特别建议如果工作流会通过openclaw.invoke回调用 OpenClaw 工具应对承载它的 agent 设置紧白名单如仅放行lobster、web_fetch、web_search、gog、gh并deny掉gateway避免工作流调用任意工具。注意tools.allow若省略或为空行为等价于“除 deny 外全部放行”因此真正的白名单必须是非空的。从 插件入口 可以看到两条硬约束register(api: OpenClawPluginApi) { api.registerTool( ((ctx) { if (ctx.sandboxed) { return null; // 沙箱上下文中直接不注册该工具 } ... }) as OpenClawPluginToolFactory, { optional: true }, ); }即沙箱化的工具上下文中 Lobster 被完全禁用——这是安全模型的一部分只有非沙箱、受信的执行环境才能运行管线。三、基本用法run运行一条管线工具参数在 lobster-tool.ts 中以 TypeBox 模式声明。最基础的运行调用继承自 SKILL.md 的示例{ action: run, pipeline: gog.gmail.search --query newer_than:1d --max 20 | email.triage }成功时返回结构化结果{ protocolVersion: 1, ok: true, status: ok, output: [{ summary: { ... }, items: [ ... ] }], requiresApproval: null }完整参数表源码默认值run的完整字段与默认值如下默认值取自 lobster-tool.ts 的参数解析代码字段默认值说明action必填run或resume二选一其他值直接报错Unknown action: …pipelinerun时必填内联管线字符串a | b | c语法或以.lobster/.yaml/.yml/.json结尾的工作流文件路径见 runner 中的workflowExts集合cwdGateway 工作目录相对路径必须解析到 Gateway 工作目录内部绝对路径被拒绝见下文沙箱检查timeoutMs20000超时中止执行maxStdoutBytes512000捕获的 stdout/stderr 或内嵌 JSON 结果超过该字节数即中止argsJson—传给工作流文件的 JSON 字符串参数内联管线时忽略非法 JSON 报run --args-json must be valid JSONtoken/approvalId/approveresume时使用见下一节flowControllerId等flow*字段—托管 TaskFlow 模式见第七节几个容易踩坑的实现细节cwd 防逃逸resolveLobsterCwd 会先拒绝绝对路径cwd must be a relative path再用isPathInside检查解析后的路径是否仍在 Gateway 工作目录内否则抛出cwd must stay within the gateway working directory。测试用例 覆盖了“默认 cwd”与“相对路径保持在仓库根内”两个场景。超时下限withTimeout 把实际超时钳制为Math.max(200, timeoutMs)超时后通过AbortController中止嵌入运行时的执行并抛出lobster runtime timed out。工作流文件识别detectWorkflowFile 只在候选字符串不含|即不是内联管线、扩展名属于workflowExts且对应文件真实存在时才按文件执行含空格的路径也会走stat探测文件不存在时回退为内联管线解释。四、审批门needs_approval状态与 resume 协议这是 SKILL.md 的核心内容。当管线中包含approve门或工作流步骤声明了approval: required时执行在门处暂停返回如下信封{ status: needs_approval, output: [], requiresApproval: { prompt: Send 3 draft replies?, items: [ ... ], resumeToken: ... } }正确流程是把prompt呈现给用户拿到用户决定后发起resume{ action: resume, token: resumeToken, approve: true }源码层面resume 的参数校验在 lobster-runner.ts 中非常严格三条规则都有对应测试用例必须提供token或approvalId之一token or approvalId requiredtoken是完整恢复令牌approvalId是同一对象中的短 id二选一即可approve必须是布尔值approve requiredapprove: false表示拒绝并终止工作流对应终态cancelledresume 不接受pipeline它只通过令牌指向暂停时的持久化状态。信封的状态空间从 LobsterEnvelope 类型 可以看到工具对外只有三种成功状态status含义ok管线成功执行完毕output携带各步结果needs_approval在审批门暂停requiresApproval携带prompt、items、resumeToken及可选approvalIdcancelled被显式拒绝或取消失败路径则返回ok: false加{ type, message }错误对象工具层会把它转成异常抛出lobster-tool.ts。另外 normalizeEnvelope 对两种情况直接 fail-closed嵌入运行时请求交互式输入needs_input时抛出“暂不支持”错误信封序列化后超过maxStdoutBytes时抛出lobster runtime result exceeded maxStdoutBytes。五、示例工作流邮件分诊与审批门SKILL.md 给出两条可直接复制的管线示例5.1 基础分诊gog.gmail.search --query newer_than:1d --max 20 | email.triage拉取近一天的邮件并分类到needs_reply、needs_action、fyi三个桶。5.2 带审批门的分诊gog.gmail.search --query newer_than:1d | email.triage | approve --prompt Process these?与上面相同的分诊但在返回结果前先暂停等待审批——即上文第四节描述的needs_approval→resume流程。5.3 组合模式小 CLI JSON 管道 审批OpenClaw 官方文档 tools/lobster.md 推荐的工程模式是写一堆只吐 JSON 的小命令再用 Lobster 把它们串成一条管线最后用approve --preview-from-stdin附带预览{ action: run, pipeline: exec --json --shell inbox list --json | exec --stdin json --shell inbox categorize --json | exec --stdin json --shell inbox apply --json | approve --preview-from-stdin --limit 5 --prompt Apply changes?, timeoutMs: 30000 }对应的小命令组inbox list --json inbox categorize --json inbox apply --json审批通过后用 token resume{ action: resume, token: resumeToken, approve: true }5.4 工作流文件.lobsterpipeline也可以指向一个 YAML 工作流文件支持name、args、steps、env、condition、approval字段官方文档示例name: inbox-triage args: tag: default: family steps: - id: collect command: inbox list --json - id: categorize command: inbox categorize --json stdin: $collect.stdout - id: approve command: inbox apply --approve stdin: $categorize.stdout approval: required - id: execute command: inbox apply --execute stdin: $categorize.stdout condition: $approve.approved配套约定stdin: $step.stdout/$step.json传递前序步骤输出condition或when可以基于$step.approved门控步骤。运行时还会向每个步骤的 shell 注入LOBSTER_ARG_NAME工作流参数参数名大写、非字母数字折叠为_和LOBSTER_ARGS_JSON两类环境变量便于命令引用解析后的参数而不必把原始值内嵌进命令字符串。文件路径形式调用示例{ action: run, pipeline: workspace/inbox-triage.lobster, argsJson: {\tag\:\family\} }六、关键行为与底层执行机制SKILL.md 总结了四条关键行为确定性相同输入→相同输出管线执行中无 LLM 方差、审批门approve命令暂停执行并返回 token、可恢复用resume token 继续、结构化输出始终返回带protocolVersion的 JSON 信封。结合源码可以进一步说明其实现机制进程内嵌入运行无子进程Lobster 不是通过 spawn 外部lobster命令实现的。loadEmbeddedToolRuntimeFromPackage 动态加载已发布的clawdbot/lobster/core包拼接 specifier 是为了避开打包器的静态解析并在 createEmbeddedLobsterRunner 中每 runner 只加载一次运行时测试用例loads the embedded runtime once per runner验证了这一点。工具调用直接拿到 JSON 信封不经过 stdout 文本解析。输出上限双保险createLimitedSink 为 stdout/stderr 各建一个有界 Writable 流累计字节超过maxStdoutBytes下限钳制到 1024立即以lobster stdout exceeded maxStdoutBytes或 stderr 版本终止信封序列化结果还会再校验一次总大小。状态持久化resume 状态以小 JSON 文件保存在 Lobster 状态目录默认~/.lobster/state可用LOBSTER_STATE_DIR覆盖token 本身只编码指向该状态的指针而非完整管线状态——这也是“暂停后可随时 resume”能跨轮次成立的原因。失败即终止嵌入运行时返回错误信封时测试 中有throws when the embedded runtime returns an error envelope与aborts long-running embedded work超时中止长任务两个用例对应验证。常见错误排查表综合 runner 源码 中的抛错点与 官方排障表错误信息原因 / 处理lobster runtime timed out管线超过timeoutMs默认 20 秒。调大该值或拆分管线lobster stdout exceeded maxStdoutBytes或 stderr捕获输出超过上限。调大maxStdoutBytes或减少输出lobster runtime result exceeded maxStdoutBytesJSON 结果本身超上限。调大上限或减少输出run --args-json must be valid JSONargsJson解析失败。修正 JSON 字符串pipeline requiredrun未提供 pipelinetoken or approvalId required/approve requiredresume 参数不完整cwd must stay within the gateway working directorycwd 逃逸出 Gateway 工作目录Lobster input requests are not supported …运行时请求交互式输入needs_input当前嵌入工具不支持属 fail-closed七、进阶托管 TaskFlow 模式源码补充除裸信封外工具还支持把一次 Lobster 执行挂到 OpenClaw 的托管 TaskFlow持久化记录上。参数解析规则在 parseManagedFlowParams 中定义得很严格run走托管模式时传flowControllerIdflowGoal可选flowCurrentStep、flowWaitingStep、flowStateJson此时禁止同时传flowId/flowExpectedRevisionresume走托管模式时传flowIdflowExpectedRevision乐观锁版本号token/approvalIdapprove此时禁止传flowControllerId、flowGoal或flowStateJson两种模式都要求存在已绑定的 TaskFlow 运行时index.ts 中通过api.runtime.tasks.managedFlows.fromToolContext(ctx)按会话绑定否则抛出Managed TaskFlow run mode requires a bound taskFlow runtime。lobster-taskflow.ts 中的executeManagedLobsterFlow展示了信封与流程记录之间的映射needs_approval→setWaiting记录审批等待状态含 prompt/items/resumeTokenok→finishcancelled→cancel任何异常 →fail。返回结构从“裸信封”变为{ ok, envelope, flow, mutation }。该模式面向需要跨 Gateway 重启保留流程状态的插件/控制器代码普通 ad-hoc agent 使用裸 run/resume 即可。八、安全边界小结综合 README 安全章节 与源码Lobster 的安全模型可以归纳为本地进程内执行工作流在 Gateway 进程内跑插件本身不发起网络调用不管密钥Lobster 不托管 OAuth/令牌它调用的是各自管理凭证的 OpenClaw 工具沙箱感知ctx.sandboxed时工具直接不注册运行时加固超时≥200ms 下限钳制、stdout/stderr 字节上限≥1024 下限钳制、严格 JSON 信封解析、cwd 目录边界检查四道防线全部由嵌入 runner 统一强制而不是依赖每条管线自觉。参考文件extensions/lobster/SKILL.md — 本文骨架来源使用时机决策表、run/resume 协议、关键行为extensions/lobster/README.md — 安装、白名单启用、openclaw.invoke回调用与安全说明extensions/lobster/openclaw.plugin.json — 插件 id、optional 工具元数据extensions/lobster/index.ts — 工具注册、沙箱禁用、TaskFlow 绑定extensions/lobster/src/lobster-tool.ts — 参数 schema、默认值、托管流程参数校验extensions/lobster/src/lobster-runner.ts — 嵌入运行时、cwd 守卫、超时与输出上限extensions/lobster/src/lobster-taskflow.ts — 信封与托管流程记录的映射extensions/lobster/src/lobster-runner.test.ts — 各行为约束的测试验证docs/tools/lobster.md — 工作流文件语法、环境变量注入、排障表【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考