OpenClaw Lobster:带可恢复审批门的多步骤工作流运行时完整指南
OpenClaw Lobster:带可恢复审批门的多步骤工作流运行时完整指南
本文基于 OpenClaw 仓库中的 Lobster 工具文档与插件源码展开,讲解如何把"多次来回的 LLM 工具调用"收敛为一次确定性的 Lobster 流水线调用:包括工具参数的完整用法、.lobster 工作流文件语法、JSON 输出信封与 resumeToken 审批恢复机制,以及从 extensions/lobster/src/lobster-tool.ts 源码看到的超时、输出上限、cwd 沙箱和 Windows 启动策略等底层实现细节。读完你可以独立搭建一个"跑一次调用、审批一次副作用、随时可恢复"的自动化工作流。
1. Lobster 是什么:把编排从 LLM 挪进类型化运行时
Lobster 是一个独立的 workflow shell(工作流外壳):OpenClaw 以本地子进程方式启动 lobster CLI,以 tool mode(工具模式) 运行,并解析其 stdout 上的 JSON 信封。它让 OpenClaw 可以把一串多步骤工具调用当作一次确定性的操作来执行,同时在关键位置插入显式审批检查点(approval gate)。
文档中给出的动机很直接:传统上复杂工作流需要多次来回的工具调用,每次调用都消耗 token,且 LLM 必须亲自编排每一步。Lobster 把这部分编排移入类型化运行时,带来三个收益:
- 一次调用代替多次调用:OpenClaw 执行一次 Lobster 工具调用,拿到结构化结果;
- 审批内建:有副作用的步骤(发邮件、发评论)会暂停工作流,直到被显式批准;
- 可恢复(Resumable):暂停的工作流返回一个
resumeToken,批准后从断点继续,无需重跑前面的步骤。
1.1 为什么用 DSL 而不是普通程序
Lobster 被刻意设计得很小。目标不是"造一门新语言",而是一个可预测、对 AI 友好的流水线规约,且带有一等公民的审批与恢复令牌。仓库文档列出的理由包括:
- 审批/恢复内建:普通程序可以提示人类,但没法在不自己发明运行时的情况下,用一个持久化令牌实现"暂停并按 token 恢复";
- 确定性与可审计:流水线是数据(data),因此容易被记录、diff、重放和评审;
- 对 AI 受限的表达面:极小的语法 + JSON 管道,减少了"发挥创造性"的代码路径,让校验变得现实可行;
- 安全策略内建在运行时:超时、输出上限、沙箱检查和允许列表由运行时统一执行,而不是每个脚本各自实现;
- 仍然可编程:每一步可以调用任意 CLI 或脚本;如果偏好 JS/TS,可以生成
.lobster文件再交给 Lobster 执行。
1.2 运行模式:tool mode 与 JSON 信封
OpenClaw 侧的实际行为在 extensions/lobster/src/lobster-tool.ts 中可以看到:run 动作构造的命令行是
lobster run --mode tool <pipeline> [--args-json <json>]
子进程环境里还会注入 LOBSTER_MODE=tool(见 extensions/lobster/src/lobster-tool.ts),这确保 lobster 以工具模式输出纯 JSON 信封而不是面向人的文本。插件返回的信封类型定义在同一文件开头(L7-L22):
type LobsterEnvelope =
| {
ok: true;
status: "ok" | "needs_approval" | "cancelled";
output: unknown[];
requiresApproval: null | {
type: "approval_request";
prompt: string;
items: unknown[];
resumeToken?: string;
};
}
| { ok: false; error: { type?: string; message: string } };
这与文档中"三种状态"的说明一一对应(见第 5 节)。
2. 安装与启用:optional 插件工具
2.1 安装 Lobster CLI
把独立的 Lobster CLI 安装到运行 OpenClaw Gateway 的同一台主机上,并确保 lobster 在 PATH 上。注意:Lobster CLI 本身是独立项目,本仓库中的 extensions/lobster 只是把它接入 OpenClaw 的插件层——extensions/lobster/README.md 明确说明该插件"不改动核心代码"(without core changes)地集成 Lobster。插件的 npm 包名为 @openclaw/lobster(见 extensions/lobster/package.json)。
2.2 启用插件工具
Lobster 是一个 optional 插件工具,默认不启用。在 extensions/lobster/index.ts 中,工具工厂以 { optional: true } 注册,并且当工具上下文为 sandboxed(沙箱)时直接返回 null——即沙箱内不注册该工具,对应文档"Sandbox-aware"一条:
api.registerTool(
((ctx) => {
if (ctx.sandboxed) {
return null;
}
return createLobsterTool(api) as AnyAgentTool;
}) as OpenClawPluginToolFactory,
{ optional: true },
);
推荐的启用方式(增量、安全)是全局 alsoAllow:
{
"tools": {
"alsoAllow": ["lobster"]
}
}
或者按 agent 配置:
{
"agents": {
"list": [
{
"id": "main",
"tools": {
"alsoAllow": ["lobster"]
}
}
]
}
}
文档特别提醒:避免使用 tools.allow: ["lobster"],除非你确实想运行在严格的 allowlist 模式下。原因是:allowlist 对 optional 插件是"选择性加入"的——如果你的 allowlist 只列出了插件工具(如 lobster),OpenClaw 会保持核心工具继续可用;若想限制核心工具,必须把希望保留的核心工具或工具组也写进 allowlist。
3. 工具参数全解
lobster 工具的完整参数 schema 在 extensions/lobster/src/lobster-tool.ts 中用 TypeBox 定义:action("run" | "resume" 二选一,源码注释说明刻意用 string enum 而非 union,因为部分模型提供方会拒绝 union/anyOf)、pipeline、argsJson、token、approve、cwd、timeoutMs、maxStdoutBytes(后五项可选)。
3.1 run:执行流水线
{
"action": "run",
"pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
"cwd": "workspace",
"timeoutMs": 30000,
"maxStdoutBytes": 512000
}
运行工作流文件并传参时,pipeline 直接填文件路径,argsJson 传 JSON 字符串:
{
"action": "run",
"pipeline": "/path/to/inbox-triage.lobster",
"argsJson": "{\"tag\":\"family\"}"
}
从源码看,run 最终拼出的 argv 是 <a href="https://link.gitcode.com/i/c0d40cd3abc13bb3ff91c434eba65916" target="_blank">"run", "--mode", "tool", pipeline],若 argsJson 非空则追加 ["--args-json", argsJson]([buildLobsterArgv),argsJson 只对工作流文件生效。
3.2 resume:审批后恢复
{
"action": "resume",
"token": "<resumeToken>",
"approve": true
}
源码中 resume 校验 token 必填、approve 必填(布尔),拼出的命令行是:
lobster resume --token <token> --approve yes|no
即 approve: true 对应 --approve yes,false 对应 --approve no(extensions/lobster/src/lobster-tool.ts)。
3.3 可选输入参数
| 参数 | 说明 | 默认值 |
|---|---|---|
cwd |
流水线的工作目录,必须是相对路径,且必须落在当前进程工作目录之内 | 当前进程 cwd |
timeoutMs |
超过该时长则杀掉子进程 | 20000 |
maxStdoutBytes |
stdout 超过该字节数则杀掉子进程 | 512000 |
argsJson |
传给 lobster run --args-json 的 JSON 字符串(仅工作流文件) |
无 |
实现层面的细节值得注意(均来自 extensions/lobster/src/lobster-tool.ts):
- cwd 双重校验:
resolveCwd先拒绝绝对路径("cwd must be a relative path"),再解析后检查相对路径是否以..开头或变成绝对路径,若是则报 "cwd must stay within the gateway working directory"(L29-L48)。对应测试见 lobster-tool.test.ts; - 默认值与下限:
timeoutMs未传时取 20000,但无论如何最终值被钳制在最小 200ms(Math.max(200, …));maxStdoutBytes未传时取 512000,最小钳制 1024 字节(L57-L59); - stdout 超限即杀:每收到一个 stdout chunk 就累计字节数,一旦超过上限立即
SIGKILL并抛出lobster output exceeded maxStdoutBytes;超时同样SIGKILL并抛出lobster subprocess timed out(L107-L126)。
4. 编写流水线:JSON 管道 + 审批门
4.1 小 CLI + JSON 管道 + 审批的组合模式
文档给出的核心模式是:先造出会说 JSON 的小命令,再把它们串成一次 Lobster 调用。示例命令名(可自行替换):
inbox list --json
inbox categorize --json
inbox apply --json
对应的工具调用:
{
"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
}
其中 approve --preview-from-stdin --limit N 可以在不写自定义 jq/heredoc 的情况下,给审批请求附带上 JSON 预览(前 N 条)。流水线触发审批后,用返回的 token 恢复:
{
"action": "resume",
"token": "<resumeToken>",
"approve": true
}
一个把输入项映射成 OpenClaw 工具调用的示例(每封新邮件各触发一次发送):
gog.gmail.search --query 'newer_than:1d' \
| openclaw.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}'
注意 openclaw.invoke 的边界:它是 Lobster 流水线回打给 OpenClaw 的桥。按 extensions/lobster/README.md 的说明,OpenClaw Gateway 需要暴露 POST /tools/invoke 端点,请求受 gateway 鉴权(如 token 鉴权时的 Authorization: Bearer …)与工具策略(全局 + 按 agent + provider + group 策略)双重把关;目标工具若不在允许范围内,OpenClaw 返回 404 Tool not available。文档建议对使用 openclaw.invoke 的 agent 设置紧凑的 allowlist,例如:
{
"agents": {
"list": [
{
"id": "main",
"tools": {
"allow": ["lobster", "web_fetch", "web_search", "gog", "gh"],
"deny": ["gateway"],
},
},
],
},
}
(tools.allow 省略或为空时等效于"除 deny 外全允许";要做真正的 allowlist,必须设置非空的 allow。)
4.2 .lobster 工作流文件
Lobster 支持用 YAML/JSON 文件描述工作流,包含 name、args、steps、env、condition、approval 字段;在 OpenClaw 工具调用里把 pipeline 设为文件路径即可。完整示例:
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或stdin: $step.json:把前一步的输出接给当前步骤;condition(别名when):可以按$step.approved之类的条件决定是否执行该步骤——上面的execute步骤只有在approve步骤返回批准时才运行;args.tag带default: "family",可通过工具调用的argsJson覆盖(如{"tag":"work"})。
5. JSON 输出信封与审批恢复流程
Lobster 返回的 JSON 信封有三种 status:
| status | 含义 |
|---|---|
ok |
正常完成 |
needs_approval |
已暂停;恢复时必须使用 requiresApproval.resumeToken |
cancelled |
被显式拒绝或取消 |
工具会把信封同时放进 content(pretty JSON 文本)和 details(原始对象)。这一点在 lobster-tool.test.ts 中有直接验证:res.details 应匹配 { ok: true, status: "ok" }。
5.1 完整示例:邮件分诊
没有 Lobster 时的日常:
User: "Check my email and draft replies"
→ openclaw calls gmail.list
→ LLM summarizes
→ User: "draft replies to #2 and #5"
→ LLM drafts
→ User: "send #2"
→ openclaw calls gmail.send
(重复每天,且不记得昨天分诊过什么)
有了 Lobster,一次调用:
{
"action": "run",
"pipeline": "email.triage --limit 20",
"timeoutMs": 30000
}
返回的信封(节选):
{
"ok": true,
"status": "needs_approval",
"output": [{ "summary": "5 need replies, 2 need action" }],
"requiresApproval": {
"type": "approval_request",
"prompt": "Send 2 draft replies?",
"items": [],
"resumeToken": "..."
}
}
用户批准后恢复:
{
"action": "resume",
"token": "<resumeToken>",
"approve": true
}
approve: true → 恢复并继续执行副作用;approve: false → 取消并终止工作流。插件侧的 SKILL.md 还给出了带 protocolVersion 的完整成功信封形态,并总结了四条关键行为:确定性(相同输入 → 相同输出,流水线执行无 LLM 方差)、审批门(approve 命令暂停执行并返回 token)、可恢复(用 resume + token 继续)、结构化输出(始终返回 JSON 信封)。
5.2 容错的信封解析
源码里的 parseEnvelope(extensions/lobster/src/lobster-tool.ts)对 stdout 做了三层处理:先 trim 后整体 JSON.parse;若失败,则用正则 ({<a href="https://link.gitcode.com/i/5760ae8d63ac4d172b827077966769c7" target="_blank">\s\S]*}|\[[\s\S]*])\s*$ 提取最后一段 JSON 形态的后缀再解析(应对某些环境在最终 JSON 前泄漏告警/日志的情况);仍然失败,或解析结果不是对象、或缺少 ok 布尔字段,则抛出 lobster returned invalid JSON 或 lobster returned invalid JSON envelope。测试用例 "tolerates noisy stdout before the JSON envelope" 验证了 noise before json\n{...} 这种带前缀输出也能正常解析([lobster-tool.test.ts)。
6. 在 Lobster 中插入结构化 LLM 步骤(llm-task)
如果工作流需要一步结构化 LLM 处理(分类/摘要/起草),可以启用可选的 llm-task 插件工具,并在 Lobster 流水线里调用它——工作流整体保持确定性,同时仍能用模型做判断。配置方式(同时启用插件并在 agent 中放行工具):
{
"plugins": {
"entries": {
"llm-task": { "enabled": true }
}
},
"agents": {
"list": [
{
"id": "main",
"tools": { "allow": ["llm-task"] }
}
]
}
}
在流水线中按 JSON Schema 约束模型输出:
openclaw.invoke --tool llm-task --action json --args-json '{
"prompt": "Given the input email, return intent and draft.",
"input": { "subject": "Hello", "body": "Can you help?" },
"schema": {
"type": "object",
"properties": {
"intent": { "type": "string" },
"draft": { "type": "string" }
},
"required": ["intent", "draft"],
"additionalProperties": false
}
}'
llm-task 插件还可通过 plugins.entries.llm-task.config 配置默认 provider/模型、allowedModels、maxTokens、timeoutMs 等,详见 docs/tools/llm-task.md。
7. 安全模型:源码级证据
文档的 "Safety" 一节列了四条,都能在插件源码里找到对应实现:
- 仅本地子进程:工具通过
node:child_process的spawn拉起lobster,插件本身不发起任何网络调用(extensions/lobster/src/lobster-tool.ts); - 不管密钥:Lobster 不管理 OAuth,真正涉及凭据的是它调用的 OpenClaw 工具;
- 沙箱感知:工具工厂在
ctx.sandboxed为真时返回null(extensions/lobster/index.ts),测试用例 "can be gated off in sandboxed contexts" 专门验证了这一点(lobster-tool.test.ts); - 加固执行:可执行文件名固定为
lobster(源码中const execPath = "lobster",不接受自定义路径,见 extensions/lobster/src/lobster-tool.ts),超时与输出上限由运行时强制执行。
此外还有两个源码层面的加固点值得了解:
- Windows 启动策略:在 Windows 上,npm 安装产生的
lobster.cmdshim 会被 resolveWindowsLobsterSpawn 解析成"直接用 Node 执行脚本",且禁止 shell 回退(allowShellFallback: false;若解析结果仍带 shell 则直接抛错 "lobster wrapper resolved to shell fallback unexpectedly")。相关行为(cmd shim 解包、%dp0%/%~dp0%token、npm layout 下从package.json的bin字段定位脚本、失败不重试)都有完整测试覆盖(lobster-tool.test.ts); - NODE_OPTIONS 卫生:spawn 前会检查继承到的
NODE_OPTIONS,若包含--inspect则删除,避免调试端口被带进子进程(extensions/lobster/src/lobster-tool.ts)。
8. 与 OpenProse 的协作
OpenProse 与 Lobster 是很好的组合:用 /prose 编排多 agent 的准备阶段,再用 Lobster 流水线执行需要确定性审批的部分。如果 Prose 程序里的子 agent 需要 Lobster,可以通过 tools.subagents.tools 放行 lobster 工具。更多见 docs/prose.md。
9. 故障排查速查
| 症状 | 处理 |
|---|---|
lobster subprocess timed out |
调大 timeoutMs,或把长流水线拆成多段 |
lobster output exceeded maxStdoutBytes |
调大 maxStdoutBytes,或减小输出体积 |
lobster returned invalid JSON |
确认流水线以 tool mode 运行,且 stdout 只输出 JSON |
lobster failed (code …) |
在终端里手动运行同一条流水线,查看 stderr |
前两条错误文案正是 failAndTerminate 抛出的信息(extensions/lobster/src/lobster-tool.ts);lobster failed (code …) 来自子进程非零退出时的 exit 处理(L132-L141);invalid JSON 来自第 5.2 节描述的解析失败路径。
10. 什么时候该用 Lobster
插件随附的 SKILL.md 给了一张判断表,可作实操参考:
| 用户意图 | 用 Lobster? |
|---|---|
| "Triage my email"(分诊邮件) | 是 —— 多步骤,可能发送回复 |
| "Send a message"(发一条消息) | 否 —— 单一动作,直接用消息工具 |
| "Check my email every morning and ask before replying" | 是 —— 带审批的定时工作流 |
| "What's the weather?"(问天气) | 否 —— 简单查询 |
| "Monitor this PR and notify me of changes" | 是 —— 有状态、可重复 |
对应的反模式:单动作请求(直接调工具)、流程中途需要 LLM 主观解读的查询(可考虑 llm-task 承担该步骤,但流水线骨架应保持确定性)、以及一次性不会重复的任务。
11. 社区案例:第二大脑
文档收录了一个公开案例:一套"second brain" CLI + Lobster 流水线,管理三个 Markdown vault(个人 / 伴侣 / 共享)。CLI 对统计、收件箱列表、过期扫描等输出 JSON;Lobster 把这些命令串成 weekly-review、inbox-triage、memory-consolidation、shared-task-sync 等工作流,每个都带审批门。AI 在可用时负责判断(分类),不可用时回退到确定性规则。
12. 进一步阅读
- docs/tools/llm-task.md:流水线中结构化 LLM 步骤的配置详解;
- docs/tools/plugin.md:OpenClaw 插件与工具策略总览;
- docs/plugins/agent-tools.md:插件工具编写指南;
- 插件源码:extensions/lobster/index.ts、extensions/lobster/src/lobster-tool.ts、extensions/lobster/src/windows-spawn.ts;
- 测试:extensions/lobster/src/lobster-tool.test.ts。
适用前提小结:lobster CLI 必须已安装在 Gateway 所在主机并位于 PATH;工具为 optional,需通过 alsoAllow(或显式 allowlist)启用;沙箱上下文中工具不可用;cwd 必须是相对路径且不能逃逸出 Gateway 工作目录;默认超时 20000ms、stdout 上限 512000 字节,超时或超限的子进程会被直接 SIGKILL。