Lobster
Lobster 将多步骤工具流水线作为一个确定性的工具调用来运行,内置显式的批准/输入检查点和恢复令牌(resume token)。检查点归属于 Lobster runner,而非单独的工作流注册表。
为什么需要它¶
没有 Lobster 时,一个多步骤任务意味着多次往返的工具调用,由模型编排每个步骤。Lobster 将该编排移入类型化运行时(typed runtime):
- 一次调用代替多次:单个 Lobster 工具调用即为整个流水线返回结构化结果。
- 内置批准机制:副作用(发送、发布、删除)会暂停工作流,直到获得明确批准。
- 可恢复:暂停的工作流返回一个令牌;批准后可恢复,无需重新运行之前的步骤。
Lobster 是一个小型、受限的 DSL,而非通用脚本语言:批准/恢复是持久化、内置的基元;流水线是数据(易于记录、比对、重放、审查);极小的语法限制了“创造性”代码路径,使验证保持现实可行;超时、输出上限、沙箱检查和允许列表由运行时强制执行,而非由每个脚本自行处理。每个步骤仍可调用任何 CLI 或脚本——如果你想要更丰富的编写语言,可以从其他工具生成 .lobster 文件。
没有 Lobster 时,周期性的邮件分类处理看起来像这样:
用户:“检查我的邮件并起草回复”
→ openclaw 调用 gmail.list
→ LLM 总结
→ 用户:“起草 #2 和 #5 的回复”
→ LLM 起草
→ 用户:“发送 #2”
→ openclaw 调用 gmail.send
(每天重复,不记得已处理过什么)
使用 Lobster 后,同样的任务只需要一次调用,并在批准处暂停、随后恢复:
{
"ok": true,
"status": "needs_approval",
"output": [{ "summary": "5 封需要回复,2 封需要处理" }],
"requiresApproval": {
"type": "approval_request",
"prompt": "发送 2 封草拟回复?",
"items": [],
"resumeToken": "..."
}
}
工作原理¶
单独安装的官方 @openclaw/lobster 插件使用其嵌入式 @clawdbot/lobster 运行时,在进程内运行 Lobster 工作流。不会创建外部 lobster 子进程;工具调用直接返回 JSON 信封。如果流水线因需要批准或输入而暂停,Lobster 会保存其续行状态并返回恢复令牌。批准请求也可以携带一个简短的批准 ID。调用在检查点处结束;不会等待用户答复的进程。
启用¶
Lobster 是一个可选的插件工具,默认不安装或启用。安装官方插件:
安装会自动应用于正在运行的 Gateway;否则将在下次启动时生效。参见 应用更改并检查。
然后全局允许该工具:
或按 agent 配置:
Note
alsoAllow 在当前启用的工具配置文件之上添加 lobster,不会限制其他核心工具。只有在需要限制性允许列表模式时,才应使用 tools.allow。
该工具在沙箱化工具上下文中被完全禁用。
如果你需要独立的 Lobster CLI 用于开发或外部流水线(在嵌入式 Gateway runner 之外),请从 Lobster 仓库 安装,并将 lobster 放入 PATH。
模式:小型 CLI + JSON 管道 + 批准¶
构建能输出 JSON 的小型命令,然后将它们串联成一次 Lobster 调用。(下面示例中的命令名可换成你自己的。)
{
"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
}
如果流水线请求批准,使用令牌恢复:
示例:将输入项映射到工具调用:
gog.gmail.search --query 'newer_than:1d' \
| openclaw.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}'
仅 JSON 的 LLM 步骤(llm-task)¶
要在工作流中执行结构化的 LLM 步骤,请启用可选的 llm-task 插件工具,并从 Lobster 调用它:
{
"plugins": {
"entries": {
"llm-task": { "enabled": true }
}
},
"agents": {
"entries": {
"main": {
"tools": { "alsoAllow": ["llm-task"] }
}
}
}
}
重要限制:嵌入式 Lobster 与 openclaw.invoke¶
已安装的 Lobster 插件在 Gateway 进程内运行工作流。在该嵌入式模式下,openclaw.invoke 不会自动为嵌套的 OpenClaw CLI 工具调用继承 Gateway URL/认证上下文。
这意味着以下模式在嵌入式 runner 中目前不可靠:
只有在独立 Lobster CLI 运行于 openclaw.invoke 已配置正确 Gateway/认证上下文的环境中时,才可参考下面的示例。
对于 openclaw.invoke 和 clawd.invoke,只有在目标地址为 localhost、127.0.0.1 或 [::1] 时,环境中的 OPENCLAW_TOKEN 或 CLAWD_TOKEN 凭据才会被接受。要向其他 HTTP(S) 端点发送凭据,请显式传入 --token。此规则同样适用于显式配置了远程连接的嵌入式工作流。该命令参数是远程 Gateway 的凭据,而不是 Lobster 工具的批准-恢复 token 参数。如果一次调用在调度后超时或失败,Lobster 不会自动重试,因为 Gateway 可能已经执行了该操作。
openclaw.invoke --tool llm-task --action json --args-json '{
"prompt": "Given the input email, return intent and draft.",
"thinking": "low",
"input": { "subject": "Hello", "body": "Can you help?" },
"schema": {
"type": "object",
"properties": {
"intent": { "type": "string" },
"draft": { "type": "string" }
},
"required": ["intent", "draft"],
"additionalProperties": false
}
}'
如果你目前使用的是嵌入式 Lobster 插件,建议采用以下任一方式:
- 直接在 Lobster 外部调用
llm-task工具,或 - 在添加受支持的嵌入式桥接之前,在 Lobster 管道中使用非
openclaw.invoke步骤。
有关详细信息和配置选项,请参阅 LLM Task。
工作流文件 (.lobster)¶
Lobster 可以运行包含 name、args、steps、env、condition 和 approval 字段的 YAML/JSON 工作流文件。在工具调用中将 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控制步骤是否执行。
注入的环境变量¶
每个步骤的 shell 都会继承父环境以及以下 Lobster 注入的变量,因此命令可以引用已解析的工作流参数,而无需将原始值嵌入命令字符串中:
LOBSTER_ARG_<NAME>- 每个工作流参数对应一个。名称会转为大写,并将连续的非字母数字字符折叠为_,因此参数user-id变为LOBSTER_ARG_USER_ID。LOBSTER_ARGS_JSON- 所有已解析的参数,以单个 JSON 字符串形式提供。
这就是完整的注入集合。没有每个步骤级的输出变量,例如 LOBSTER_STEP_<id>_STDOUT 或 LOBSTER_STEP_<id>_JSON_<field>;shell 会将这些名称视为未设置,因此参数展开的默认值可能会掩盖错误。请改用步骤引用来读取上一步的输出 - $step.stdout、$step.json 或 $step.json.<field> - 并放在 stdin:、env: 或 condition: 值中。(LOBSTER_STATE_DIR 是用于状态目录的独立运行时设置,不是随运行提供的参数。)
工具参数¶
run¶
{
"action": "run",
"pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
"cwd": "workspace",
"timeoutMs": 30000,
"maxStdoutBytes": 512000
}
使用参数运行工作流文件:
{
"action": "run",
"pipeline": "/path/to/inbox-triage.lobster",
"argsJson": "{\"tag\":\"family\"}"
}
| 字段 | 默认值 | 说明 |
|---|---|---|
pipeline |
必需 | 内联管道字符串,或指向以 .lobster/.yaml/.yml/.json 结尾的工作流文件路径。 |
cwd |
网关工作目录 | 相对工作目录;必须解析到网关工作目录内部(拒绝绝对路径)。 |
timeoutMs |
20000 |
超过该时间则中止运行。 |
maxStdoutBytes |
512000 |
如果捕获的 stdout、stderr 或嵌入的 JSON 结果超过此大小,则中止。 |
argsJson |
- | 工作流文件的参数 JSON 字符串(对内联管道忽略)。 |
resume¶
对于审批,使用 requiresApproval 中的 token 或 approvalId,以及布尔值 approve。对于输入,使用 requiresInput 中的 token 和 responseJson。要取消任一类型的检查点,请使用 cancel: true 而不是做出决定。请恰好提供 approve、responseJson 和 cancel: true 其中之一。
结构化输入¶
工作流中的 input 步骤或内联的 ask 阶段会返回 needs_input,其中包含问题、JSON Schema 和 resume token。可选的 defaults 和 subject 提供建议值和待审阅的材料。例如:
{
"status": "needs_input",
"requiresInput": {
"type": "input_request",
"prompt": "What feedback should be included?",
"responseSchema": { "type": "string" },
"resumeToken": "<resumeToken>"
}
}
智能体在聊天中呈现问题,然后将用户的答案以 JSON 形式发送:
{
"action": "resume",
"token": "<resumeToken>",
"responseJson": "\"Please shorten the introduction.\""
}
responseJson 可以编码返回 schema 允许的任何值,而不仅仅是对象。Lobster 会在继续之前验证答案。无效的 JSON 或不符合 schema 的答案会使检查点保持可修正状态。一次 resume 调用可以返回另一个问题或审批请求。
这是一种聊天/工具交互,不是 Inbox 卡片或表单。插件不会列出待处理的检查点;请保留返回的 token 以便稍后恢复。与 approval token 一样,持有 input token 即可让被允许使用该工具的调用者恢复运行;token 不绑定到 OpenClaw 用户或会话。
输出信封¶
Lobster 返回一个 JSON 信封,包含以下四种状态之一:
ok- 成功完成needs_approval- 已暂停;requiresApproval携带resumeToken和一个简短的approvalId,两者中任何一个都可以恢复运行needs_input- 已暂停;requiresInput携带问题、答案 schema 和resumeTokencancelled- 被明确拒绝或取消
该工具会在 content(美化后的 JSON)和 details(原始对象)中同时呈现该信封。
审批¶
如果存在 requiresApproval,请检查 Prompt 并决定:
approve: true- 恢复并继续副作用approve: false- 取消并结束工作流
使用 approve --preview-from-stdin --limit N 为审批请求附加 JSON 预览,而无需自定义 jq/heredoc 胶水代码。恢复状态以小型 JSON 文件形式存储在 Lobster 状态目录(默认为 ~/.lobster/state,可通过 LOBSTER_STATE_DIR 覆盖)下;Token 本身仅编码指向该状态的指针,而非完整的流水线状态。
安全性¶
- 仅限本地进程内 - 工作流在网关进程内执行;插件本身不进行网络调用。
- 不管理密钥 - Lobster 不管理 OAuth;它调用执行此操作的 OpenClaw 工具。
- 感知沙箱 - 当工具上下文处于沙箱中时禁用。
- 已加固 - 由嵌入式运行器强制实施超时和输出上限。
故障排除¶
| 错误 | 原因 / 修复 |
|---|---|
lobster runtime timed out |
流水线超过 timeoutMs。请增大该值或拆分流水线。 |
lobster stdout exceeded maxStdoutBytes(或 stderr) |
捕获的输出超过上限。请提高 maxStdoutBytes 或减少输出。 |
lobster runtime result exceeded maxStdoutBytes |
JSON 结果超过上限。请提高 maxStdoutBytes 或减少输出。 |
run --args-json must be valid JSON |
argsJson(工作流文件运行)解析失败。请修复 JSON 字符串。 |
lobster runtime failed(或其他 runtime_error 消息) |
嵌入式运行时返回了错误信封。请查看网关日志以获取详细信息。 |
了解更多¶
案例研究:社区工作流¶
一个公开示例:一个“第二大脑” CLI + Lobster 流水线,用于管理三个 Markdown 库(个人、伙伴、共享)。CLI 为统计信息、收件箱列表和过期扫描输出 JSON;Lobster 将这些命令串联成类似 weekly-review、inbox-triage、memory-consolidation 和 shared-task-sync 的工作流,每个工作流都带有审批关卡。AI 在可用时处理判断(分类),不可用时回退到确定性规则。
- 帖子:https://x.com/plattenschieber/status/2014508656335770033
- 仓库:https://github.com/bloomedai/brain-cli
相关¶
- 自动化 - 所有自动化机制
- 工具概览 - 所有可用的代理工具
- Lobster 插件参考 - 该插件的清单、配置和工具参考
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw