Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

Lobster 是一个工作流外壳，它让 OpenClaw 能将多步工具序列作为一次单一、确定性的操作来运行，并带有显式的审批检查点。 Lobster 是位于分离式后台工作的上一层编写层。对于位于单个任务之上的流程编排，请参见 Task Flow（openclaw tasks flow）。有关任务活动账本，请参见 openclaw tasks。

​
Hook

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

​
为什么

如今，复杂工作流需要多次来回的工具调用。每次调用都会消耗 token，而 LLM 必须编排每一步。Lobster 将这种编排移入一个类型化运行时：
  • 一次调用，而不是多次：OpenClaw 执行一次 Lobster 工具调用并获得结构化结果。
  • 内置审批：副作用（发送邮件、发布评论）会暂停工作流，直到显式批准。
  • 可恢复：暂停的工作流会返回一个 token；批准后即可恢复，而无需重新运行全部内容。

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

Lobster 故意保持小巧。目标不是“又一种新语言”，而是一个可预测、对 AI 友好的管道规范，内置审批和恢复 token。
  • 审批/恢复内置：普通程序可以提示人类，但如果没有你自己发明那套运行时，它无法用持久 token 来 暂停并恢复。
  • 确定性 + 可审计性：管道是数据，因此易于记录、diff、回放和审查。
  • 为 AI 约束的表面：小型语法 + JSON 管道减少“创造性”代码路径，并使验证切实可行。
  • 内置安全策略：超时、输出上限、沙箱检查和允许列表由运行时强制执行，而不是每个脚本分别处理。
  • 仍然可编程：每一步都可以调用任意 CLI 或脚本。如果你想用 JS/TS，可以从代码生成 .lobster 文件。

​
它是如何工作的

OpenClaw 使用嵌入式运行器 在进程内 运行 Lobster 工作流。不会启动外部 CLI 子进程；工作流引擎在网关进程内部执行，并直接返回一个 JSON 信封。 如果管道因审批而暂停，工具会返回一个 resumeToken，以便你稍后继续。

​
模式：小型 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
}
如果管道请求审批，请使用 token 恢复： 
{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}
AI 触发工作流；Lobster 执行各步骤。审批闸门使副作用保持显式且可审计。 示例：将输入项映射为工具调用： 
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": {
    "list": [
      {
        "id": "main",
        "tools": { "alsoAllow": ["llm-task"] }
      }
    ]
  }
}
在管道中使用它： 
openclaw.invoke --tool llm-task --action json --args-json '{
  "prompt": "给定输入邮件，返回意图和草稿。",
  "thinking": "low",
  "input": { "subject": "你好", "body": "你能帮忙吗？" },
  "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-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 对步骤设置门控。

​
安装 Lobster

捆绑的 Lobster 工作流以内嵌方式运行；不需要单独的 lobster 二进制文件。嵌入式运行器随 Lobster 插件一同提供。 如果你在开发或外部管道中需要独立的 Lobster CLI，请从 Lobster repo 安装，并确保 lobster 位于 PATH 中。

​
启用该工具

Lobster 是一个可选的插件工具（默认未启用）。 推荐方式（增量式，安全）： 
{
  "tools": {
    "alsoAllow": ["lobster"]
  }
}
或者按 agent 配置： 
{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "alsoAllow": ["lobster"]
        }
      }
    ]
  }
}
除非你打算使用受限的允许列表模式，否则不要使用 tools.allow: ["lobster"]。
Allowlist 是可选插件的自愿启用项。alsoAllow 仅启用指定的可选插件工具，同时保留正常的核心工具集。若要限制核心工具，请使用 tools.allow 并指定你想要的核心工具或工具组。

​
示例：邮件分拣

不使用 Lobster： 
User: "查看我的邮件并起草回复"
→ openclaw calls gmail.list
→ LLM summaries
→ 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
}
返回一个 JSON 信封（已截断）： 
{
  "ok": true,
  "status": "needs_approval",
  "output": [{ "summary": "5 封需要回复，2 封需要处理" }],
  "requiresApproval": {
    "type": "approval_request",
    "prompt": "发送 2 封草稿回复？",
    "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：如果输出超过此大小则中止（默认：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 可以在无需自定义 jq/heredoc 连接的情况下，将 JSON 预览附加到审批请求中。恢复 token 现在更紧凑：Lobster 将工作流恢复状态存储在其状态目录下，并返回一个较小的 token 键。

​
OpenProse

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

​
安全性

  • 仅本地进程内 — 工作流在网关进程内部执行；插件本身不会发起网络调用。
  • 无密钥 — Lobster 不管理 OAuth；它调用的是负责这部分的 OpenClaw 工具。
  • 感知沙箱 — 当工具上下文处于沙箱中时会被禁用。
  • 强化 — 由嵌入式运行器强制执行超时和输出上限。

​
故障排查

  • lobster timed out → 增加 timeoutMs，或将长管道拆分。
  • lobster output exceeded maxStdoutBytes → 提高 maxStdoutBytes 或减少输出大小。
  • lobster returned invalid JSON → 确保管道以工具模式运行，并且只输出 JSON。
  • lobster failed → 检查网关日志中的嵌入式运行器错误详情。

​
了解更多

​
案例研究：社区工作流

一个公开示例：一个“第二大脑” CLI + Lobster 流水线，管理三个 Markdown 知识库（个人、伴侣、共享）。CLI 会为统计信息、收件箱列表和过期扫描输出 JSON；Lobster 将这些命令串联成诸如 weekly-review、inbox-triage、memory-consolidation 和 shared-task-sync 之类的工作流，每个工作流都带有审批关卡。AI 在可用时负责判断（分类），在不可用时则回退到确定性规则。

​
相关内容