OpenClaw从入门到应用——工具（Tools）：Lobster

通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》

Lobster 是一个工作流 Shell，它让 OpenClaw 将多步工具序列作为单一的、确定性的操作来运行，并带有明确的审批检查点。

引子

你的助手可以构建管理自身的工具。只要要求一个工作流，30 分钟后你就能得到一个 CLI 以及能以一次调用运行的管道。Lobster 正是那缺失的一环：确定性的管道、明确的审批以及可恢复的状态。

为什么需要 Lobster

如今，复杂的工作流往往需要多次来回的工具调用。每次调用都会消耗 token，而 LLM 必须编排每一步。Lobster 将这种编排转移到了类型化的运行时中：

• 一次调用替代多次调用：OpenClaw 执行一次 Lobster 工具调用，并获得结构化的结果。
• 内置审批：副作用（发送邮件、发表评论）会暂停工作流，直到得到明确批准。
• 可恢复：暂停的工作流会返回一个令牌；批准后可恢复运行，无需重新执行所有步骤。

为什么用 DSL 而不是普通程序？

Lobster 刻意保持精简。目标并不是“一种新语言”，而是一个可预测、对 AI 友好的管道规范，并原生支持审批和恢复令牌。

• 审批/恢复是内置的：普通程序可以提示人类，但无法在不自行实现相应运行时的前提下，通过持久令牌暂停并恢复。
• 确定性与可审计性：管道就是数据，因此易于记录、对比、重放和审查。
• 对 AI 的约束面：极小的语法加上 JSON 管道，减少了“创造性”代码路径，并使验证切实可行。
• 内置安全策略：超时、输出上限、沙箱检查和允许列表均由运行时强制执行，而非每个脚本自行处理。
• 仍然可编程：每个步骤都可以调用任何 CLI 或脚本。如果你想使用 JS/TS，可以从代码生成.lobster文件。

工作原理

OpenClaw 在工具模式下启动本地lobsterCLI，并从 stdout 解析 JSON 信封。
如果管道因需要审批而暂停，该工具会返回一个resumeToken，以便稍后继续。

模式：小型 CLI + JSON 管道 + 审批

构建一些能输出 JSON 的小命令，然后将它们串联到一个 Lobster 调用中。（以下示例命令名仅作示意，可替换为你自己的。）

inbox list--jsoninbox categorize--jsoninbox 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}

如果管道请求审批，则使用令牌恢复：

{"action":"resume","token":"<resumeToken>","approve":true}

AI 触发工作流；Lobster 执行这些步骤。审批关卡让副作用保持明确且可审计。

示例：将输入项映射为工具调用：

gog.gmail.search--query'newer_than:1d'\|openclaw.invoke--toolmessage--actionsend--each--item-key message --args-json'{"provider":"telegram","to":"..."}'

纯 JSON 的 LLM 步骤（llm-task）

对于需要结构化的 LLM 步骤的工作流，请启用可选的
llm-task插件工具，并在 Lobster 中调用它。这既保持了工作流的确定性，
又能让你使用模型进行分类/总结/起草。

启用该工具：

{"plugins":{"entries":{"llm-task":{"enabled":true}}},"agents":{"list":[{"id":"main","tools":{"allow":["llm-task"]}}]}}

在管道中使用：

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 } }'

有关详细信息和配置选项，请参阅 LLM Task。

工作流文件（.lobster）

Lobster 可以运行包含name、args、steps、env、condition和approval字段的 YAML/JSON 工作流文件。在 OpenClaw 工具调用中，将pipeline设置为文件路径。

name:inbox-triageargs:tag:default:"family"steps:-id:collectcommand:inbox list--json-id:categorizecommand:inbox categorize--jsonstdin:$collect.stdout-id:approvecommand:inbox apply--approvestdin:$categorize.stdoutapproval:required-id:executecommand:inbox apply--executestdin:$categorize.stdoutcondition:$approve.approved

注意事项：

• stdin: $step.stdout和stdin: $step.json会传递前一步的输出。
• condition（或when）可以根据$step.approved来控制步骤的执行。

安装 Lobster

在运行 OpenClaw 网关的同一台主机上安装 Lobster CLI（参见 Lobster 仓库），并确保lobster在PATH中。

启用工具

Lobster 是一个可选的插件工具（默认不启用）。

推荐配置（增量式，安全）：

{"tools":{"alsoAllow":["lobster"]}}

或者按代理配置：

{"agents":{"list":[{"id":"main","tools":{"alsoAllow":["lobster"]}}]}}

除非你打算以限制性允许列表模式运行，否则应避免使用tools.allow: ["lobster"]。

注意：对于可选插件，允许列表是选择性加入的。如果你的允许列表只列出了
插件工具（如lobster），OpenClaw 仍会保持核心工具可用。若要限制核心工具，
请在允许列表中同时包含你需要的核心工具或工具组。

示例：邮件分类

没有 Lobster 时：

用户：“检查我的邮件并起草回复” → openclaw 调用 gmail.list → LLM 进行总结 → 用户：“为 #2 和 #5 起草回复” → LLM 起草 → 用户：“发送 #2” → openclaw 调用 gmail.send （每天重复，没有关于已处理内容的记忆）

使用 Lobster 时：

{"action":"run","pipeline":"email.triage --limit 20","timeoutMs":30000}

返回一个 JSON 信封（已截断）：

{"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}

一个工作流。确定性强。安全可靠。

工具参数

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\"}"}

resume

在审批后继续已暂停的工作流。

{"action":"resume","token":"<resumeToken>","approve":true}

可选输入

• cwd：管道的相对工作目录（必须保持在当前进程的工作目录之内）。
• timeoutMs：如果子进程超过此持续时间，则终止它（默认：20000）。
• maxStdoutBytes：如果 stdout 超过此大小，则终止子进程（默认：512000）。
• argsJson：传递给lobster run --args-json的 JSON 字符串（仅用于工作流文件）。

输出信封

Lobster 会返回一个 JSON 信封，包含以下三种状态之一：

• ok→ 成功完成
• needs_approval→ 已暂停；需要requiresApproval.resumeToken才能恢复
• cancelled→ 被明确拒绝或取消

该工具在content（格式化的 JSON）和details（原始对象）中均会提供此信封。

审批

如果存在requiresApproval，请检查提示并决定：

• approve: true→ 恢复并继续执行副作用
• approve: false→ 取消并终结工作流

使用approve --preview-from-stdin --limit N可以将 JSON 预览附加到审批请求中，而无需使用自定义的 jq/heredoc 胶水代码。恢复令牌现在十分紧凑：Lobster 将工作流恢复状态存储在其状态目录下，并返回一个小型的令牌键。

OpenProse

OpenProse 与 Lobster 能很好地搭配使用：先用/prose编排多代理的准备工作，然后运行 Lobster 管道进行确定性的审批。如果某个 Prose 程序需要 Lobster，可通过tools.subagents.tools为子代理允许lobster工具。请参阅 OpenProse。

安全性

• 仅本地子进程— 插件本身不进行网络调用。
• 无密钥— Lobster 不管理 OAuth；它调用的是负责管理这些的 OpenClaw 工具。
• 沙箱感知— 当工具上下文被沙箱化时，该工具将被禁用。
• 加固— 固定可执行文件名为lobster，并在PATH中查找；强制执行超时和输出上限。

故障排除

• lobster subprocess timed out→ 增大timeoutMs，或者拆分较长的管道。
• lobster output exceeded maxStdoutBytes→ 提高maxStdoutBytes或减少输出大小。
• lobster returned invalid JSON→ 确保管道在工具模式下运行，并且仅输出 JSON。
• lobster failed (code …)→ 在终端中运行相同的管道，检查 stderr。

了解更多

• 插件
• 插件工具编写

案例研究：社区工作流

一个公开示例：一个“第二大脑” 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