OpenClaw 中文

深色模式

广告 · 本站推荐广告

Lobster ​

OpenClaw 的类型化工作流运行时 — 可组合管道与审批门控。

概述 ​

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

引子 ​

你的助手可以构建管理自身的工具。请求一个工作流，30 分钟后你就有了一个 CLI 加上作为单次调用运行的管道。Lobster 就是那块缺失的拼图：确定性管道、明确的审批和可恢复的状态。

为什么需要 Lobster ​

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

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

为什么使用 DSL 而非普通程序？ ​

Lobster 有意设计得很小。目标不是"一门新语言"，而是一个可预测的、AI 友好的管道规范，具有一流的审批和恢复令牌支持。

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

工作原理 ​

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

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

构建输出 JSON 的小型命令，然后将它们链接成单次 Lobster 调用。（以下为示例命令名 — 替换为你自己的。）

bash
inbox list --json
inbox categorize --json
inbox apply --json
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
}

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

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

AI 触发工作流；Lobster 执行步骤。审批门控保证副作用明确且可审计。

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

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

JSON-only LLM 步骤（llm-task） ​

对于需要结构化 LLM 步骤的工作流，启用可选的 llm-task 插件工具并从 Lobster 调用它。这保持了工作流的确定性，同时仍允许你使用模型进行分类/总结/起草。

启用工具：

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

在管道中使用：

txt
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。

工作流文件（.lobster） ​

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

yaml
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 ​

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

启用工具 ​

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

推荐方式（附加式，安全）：

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

或按代理配置：

json
{
  "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：

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

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

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

用户批准 → 恢复：

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

一个工作流。确定性。安全。

工具参数 ​

run ​

在工具模式下运行管道。

json
{
  "action": "run",
  "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
  "cwd": "workspace",
  "timeoutMs": 30000,
  "maxStdoutBytes": 512000
}

使用参数运行工作流文件：

json
{
  "action": "run",
  "pipeline": "/path/to/inbox-triage.lobster",
  "argsJson": "{\"tag\":\"family\"}"
}

resume ​

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

json
{
  "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 将工作流恢复状态存储在其状态目录下，并返回一个小型令牌 key。

OpenProse ​

OpenProse 与 Lobster 配合良好：使用 /prose 编排多代理准备工作，然后运行 Lobster 管道进行确定性审批。如果 Prose 程序需要 Lobster，通过 tools.subagents.tools 为子代理允许 lobster 工具。参见 OpenProse。

安全 ​

  • 仅本地子进程 — 插件本身不进行网络调用。
  • 无密钥 — Lobster 不管理 OAuth；它调用处理 OAuth 的 OpenClaw 工具。
  • 沙箱感知 — 当工具上下文处于沙箱中时禁用。
  • 强化 — PATH 上固定的可执行文件名（lobster）；强制执行超时和输出上限。

故障排查 ​

  • 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 在可用时处理判断（分类），在不可用时回退到确定性规则。

基于MIT协议开源 | 内容翻译自 官方文档，同步更新

Copyright © 2026 OpenClaw 中文社区