OpenClaw Lobster:带可恢复审批门的多步骤工作流运行时完整指南

原创2026-10-14 14:48:401,817 阅读
文章标签:人工智能大模型AI 应用后端LLM 网关即时通讯AI Agent插件系统本地部署MCP Clients

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),超时与输出上限由运行时强制执行。

此外还有两个源码层面的加固点值得了解:

  1. Windows 启动策略:在 Windows 上,npm 安装产生的 lobster.cmd shim 会被 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);
  2. 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. 进一步阅读

适用前提小结:lobster CLI 必须已安装在 Gateway 所在主机并位于 PATH;工具为 optional,需通过 alsoAllow(或显式 allowlist)启用;沙箱上下文中工具不可用;cwd 必须是相对路径且不能逃逸出 Gateway 工作目录;默认超时 20000ms、stdout 上限 512000 字节,超时或超限的子进程会被直接 SIGKILL。

登录后查看全文
openclaw-zero-token