跳转至

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 后,同样的任务只需要一次调用,并在批准处暂停、随后恢复:

{ "action": "run", "pipeline": "email.triage --limit 20", "timeoutMs": 30000 }
{
  "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 是一个可选的插件工具,默认不安装或启用。安装官方插件:

openclaw plugins install @openclaw/lobster

安装会自动应用于正在运行的 Gateway;否则将在下次启动时生效。参见 应用更改并检查。

然后全局允许该工具:

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

或按 agent 配置:

{
  "agents": {
    "entries": {
      "main": {
        "tools": {
          "alsoAllow": ["lobster"]
        }
      }
    }
  }
}

Note

alsoAllow 在当前启用的工具配置文件之上添加 lobster,不会限制其他核心工具。只有在需要限制性允许列表模式时,才应使用 tools.allow。

该工具在沙箱化工具上下文中被完全禁用。

如果你需要独立的 Lobster CLI 用于开发或外部流水线(在嵌入式 Gateway runner 之外),请从 Lobster 仓库 安装,并将 lobster 放入 PATH。

模式:小型 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
}

如果流水线请求批准,使用令牌恢复:

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

示例:将输入项映射到工具调用:

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 中目前不可靠:

openclaw.invoke --tool llm-task --action json --args-json '{ ... }'

只有在独立 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

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

对于审批,使用 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 和 resumeToken
  • cancelled - 被明确拒绝或取消

该工具会在 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 在可用时处理判断(分类),不可用时回退到确定性规则。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw