Lobster

Lobster 将多步骤工具流水线作为一次确定性工具调用运行，并带有显式审批检查点和恢复令牌。审批检查点属于 Lobster 运行器，而不是独立的编排注册表。

为什么¶

如果没有 Lobster，多步骤任务意味着许多往返工具调用，并且由模型编排每个步骤。Lobster 将该编排移入一个类型化运行时：

一次调用代替多次调用：一次 Lobster 工具调用会为整个流水线返回结构化结果。
内置审批：副作用（发送、发布、删除）会暂停工作流，直到被显式批准。
可恢复：已暂停的工作流会返回一个令牌；批准后可恢复，而无需重新运行之前的步骤。

Lobster 是一个小型、受限的 DSL，而不是通用脚本语言：approve/resume 是持久、内置的原语；流水线是数据（易于记录、差异比较、重放、审查）；极小的语法限制了“创造性”代码路径，使验证保持现实；超时、输出上限、沙箱检查和允许列表由运行时强制执行，而不是由每个脚本执行。每个步骤仍可以调用任何 CLI 或脚本——如果你希望使用更丰富的编写语言，可以从其他工具生成 .lobster 文件。

如果没有 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
(repeat daily, no memory of what was triaged)

使用 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": "..."
  }
}

工作原理¶

单独安装的官方 @openclaw/lobster 插件使用其内置的 @clawdbot/lobster 运行时，在进程内运行 Lobster 工作流。不会生成外部 lobster 子进程；工具调用会直接返回一个 JSON 信封。如果流水线因审批而暂停，信封会携带一个恢复令牌（或一个简短的审批 ID），以便你稍后继续。

启用¶

Lobster 是一个可选插件工具，默认不安装也不启用。安装官方插件：

openclaw plugins install @openclaw/lobster

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

然后全局允许该工具：

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

或按代理：

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

Note

alsoAllow 会在当前工具配置之上添加 lobster，而不会限制其他核心工具。只有当你希望改用限制性允许列表模式时，才使用 tools.allow。

对于沙箱化工具上下文，该工具会被完全禁用。

如果你需要独立的 Lobster CLI 用于开发或外部流水线（在嵌入式 Gateway 运行器之外），请从 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": {
        "default": true,
        "tools": { "alsoAllow": ["llm-task"] }
      }
    }
  }
}

重要限制：嵌入式 Lobster 与 `openclaw.invoke`¶

已安装的 Lobster 插件在 Gateway 内部以进程内方式运行工作流。在该嵌入式模式下，openclaw.invoke 不会自动为嵌套的 OpenClaw CLI 工具调用继承 Gateway URL/认证上下文。

这意味着该模式目前在嵌入式运行器中并不可靠：

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

仅当你在已正确配置 openclaw.invoke 的 Gateway/认证上下文的环境中运行独立 Lobster CLI 时，才使用下面的示例。

对于 openclaw.invoke 和 clawd.invoke，环境中的 OPENCLAW_TOKEN 或 CLAWD_TOKEN 凭据仅对 localhost、127.0.0.1 或 [::1] 目标有效。要将凭据发送到其他 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`	网关 cwd	相对工作目录；必须解析到网关工作目录内部（绝对路径会被拒绝）。
`timeoutMs`	`20000`	如果超过，则中止运行。
`maxStdoutBytes`	`512000`	如果捕获的 stdout、stderr 或嵌入式 JSON 结果超过此大小，则中止。
`argsJson`	-	用于工作流文件的参数 JSON 字符串（内联管道会忽略）。

`resume`¶

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

resume 接受 token（来自 requiresApproval 的完整恢复令牌）或 approvalId（来自同一对象的短 id）——使用被暂停运行返回的任意一个。approve 为必填。

输出信封¶

Lobster 返回一个 JSON 信封，其中包含三种状态之一：

ok - 成功完成
needs_approval - 已暂停；requiresApproval 包含 resumeToken 和一个短 approvalId，其中任意一个都可以恢复运行
cancelled - 已明确拒绝或取消

该工具会在 content（格式化 JSON）和 details（原始对象）中呈现该信封。

审批¶

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

approve: true - 恢复并继续副作用
approve: false - 取消并结束工作流

使用 approve --preview-from-stdin --limit N 可以为审批请求附加 JSON 预览，而无需自定义 jq/heredoc 胶水代码。恢复状态以小型 JSON 文件的形式存储在 Lobster 状态目录（默认为 ~/.lobster/state，可通过 LOBSTER_STATE_DIR 覆盖）下；令牌本身仅编码指向该状态的指针，而不是完整的管道状态。

安全性¶

仅限本地进程内 - 工作流在网关进程内执行；插件本身不进行网络调用。
不管理机密 - 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