Lobster 深度解析：OpenClaw 的原生工作流引擎

项目地址：https://github.com/openclaw/lobster
集成 PR：https://github.com/openclaw/openclaw/pull/1152
整理日期：2026-03-04

一句话定义

Lobster 是 OpenClaw 原生的工作流 shell：一个类型化的、本地优先的”宏引擎”，将技能/工具转换为可组合管道和安全自动化——让 OpenClaw 能够一步调用这些工作流。

为什么需要 Lobster？

当前 AI Agent 的痛点

当 OpenClaw（或其他 AI Agent）处理复杂任务时，通常需要：

  1. 一步一步地调用工具
  2. 每步都重新规划
  3. 消耗大量 token
  4. 执行过程脆弱（容易出错）
  5. 难以恢复（出错后从头再来）

Lobster 的解决方案

“让 OpenClaw 使用 lobster 作为工作流引擎，避免每一步都重新规划——节省 token 的同时提高确定性和可恢复性。”

通过 Lobster，AI 可以：

  • 将多步骤工作流封装为单次工具调用
  • 获得类型安全的管道（JSON-first）
  • 在关键操作前设置审批门控
  • 支持断点恢复（approval token 可恢复）

核心设计理念

1. 类型化管道（Typed Pipelines）

传统 shell：文本管道（text pipes），容易出错

cat data.json | jq '.items[]' | grep "active" | wc -l

Lobster：对象/数组管道（objects/arrays），类型安全

lobster "exec --json --shell 'echo [1,2,3]' | where '0>=0' | json"

2. 本地优先（Local-first）

  • 所有执行都在本地完成
  • 不依赖远程服务
  • 无新的认证面：Lobster 不管理 OAuth/tokens

3. 可组合宏（Composable Macros）

  • 工作流可以像乐高一样组合
  • OpenClaw（或任何 Agent）可以一步调用
  • 节省 token：将多步编排移出 LLM

实际使用示例

示例 1：监控 GitHub PR 状态

监控一个没有变化的 PR：

node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"openclaw/openclaw\",\"pr\":1152}'"

输出（结构化 JSON）：

[
  {
    "kind": "github.pr.monitor",
    "repo": "openclaw/openclaw",
    "prNumber": 1152,
    "key": "github.pr:openclaw/openclaw#1152",
    "changed": false,
    "summary": {
      "changedFields": [],
      "changes": {}
    },
    "prSnapshot": {
      "author": {
        "login": "vignesh07",
        "name": "Vignesh"
      },
      "state": "OPEN",
      "title": "feat: Add optional lobster plugin tool",
      "mergeable": "MERGEABLE",
      "url": "https://github.com/openclaw/openclaw/pull/1152"
    }
  }
]

监控一个有状态变化的 PR（已合并）：

node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"openclaw/openclaw\",\"pr\":1200}'"

输出（检测到变化）：

{
  "changed": true,
  "summary": {
    "changedFields": ["number", "title", "url", "state", ...],
    "changes": {
      "state": { "from": null, "to": "MERGED" },
      "title": { "from": null, "to": "feat(tui): add syntax highlighting" }
    }
  }
}

工作流文件（Workflow Files）

Lobster 可以运行 YAML/JSON 格式的工作流文件，支持 steps、env、condition 和审批门控。

命令格式

lobster run path/to/workflow.lobster
lobster run --file path/to/workflow.lobster --args-json '{"tag":"family"}'

完整示例：收件箱分类工作流

name: inbox-triage
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

工作流程解析：

  1. collect：获取收件箱列表
  2. categorize：对邮件进行分类（依赖上一步输出）
  3. approve：申请审批（必需的人类确认）
  4. execute：执行操作（仅在审批通过后）

核心命令

命令 功能
exec 运行 OS 命令
exec --stdin raw\|json\|jsonl 将管道输入送入子进程 stdin
where, pick, head 数据塑形（过滤、选择、截取）
json, table 渲染器（输出格式化）
approve 审批门控（TTY 提示或 --emit 用于 OpenClaw 集成）

OpenClaw 集成方式

为什么是插件（Plugin）而非核心（Core）？

考量 说明
保持核心精简 避免在证明有用之前添加新的运行时/语言
可选启用 使用新添加的可选插件工具边界
可逆性 如果 Lobster 获得信任并稳定，可以考虑深度集成
最小足迹 初始影响最小，可逆

启用方式（Opt-in）

该工具以 { optional: true } 注册，永远不会自动启用。

用户必须在 agents.list[].tools.allow 中启用：

  • "lobster" —— 启用该插件的所有工具
  • "group:plugins" —— 启用所有插件工具

安全边界

安全措施 说明
本地执行 仅本地子进程执行，无新网络面
无密钥管理 Lobster 不管理 OAuth/tokens/secrets
绝对路径 lobsterPath 必须提供绝对路径（减少 PATH 劫持风险）
资源限制 timeoutMs 和 maxStdoutBytes 上限
严格解析 严格的 JSON 信封解析（拒绝无效输出）
沙箱安全 当 ctx.sandboxed 为 true 时，工具工厂返回 null（沙箱环境中不可用）

与 OpenClaw 的协作模式

传统模式（无 Lobster）

OpenClaw → 工具A → 等待 → 工具B → 等待 → 工具C → 等待 → 完成
          ↑_____ 多轮对话，大量 token ____↑

Lobster 模式

OpenClaw → Lobster 工作流（一次性调用）→ 返回结果
          ↑_____ 单次调用，显著节省 token ____↑

实际场景：邮件分类工作流

  • 传统：triage → draft → ask → send（4 轮工具调用）
  • Lobster：单次调用 lobster run inbox-triage.lobster，内部处理所有步骤，仅在需要审批时暂停

技术栈与快速开始

技术栈

  • 语言：TypeScript（Node.js）
  • 包管理器：pnpm
  • 构建：tsc 编译到 dist/

快速开始

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 代码检查
pnpm lint

# 查看帮助
node ./bin/lobster.js --help

# 诊断检查
node ./bin/lobster.js doctor

# 运行示例管道
node ./bin/lobster.js "exec --json --shell 'echo [1,2,3]' | where '0>=0' | json"

未来路线图

  • OpenClaw 深度集成：作为可选 OpenClaw 插件工具发布
  • 更多内置工作流：GitHub、GitLab、邮件、日历等常用工作流
  • 可视化编辑器：图形化工作流编辑
  • 工作流市场：社区共享工作流

总结

Lobster 代表了 AI Agent 工作流编排的新范式：

维度 传统方式 Lobster 方式
调用方式 多轮工具调用 单次工作流调用
数据类型 文本 结构化 JSON
执行环境 远程/混合 本地优先
人类介入 每步确认 仅在审批点暂停
可恢复性 困难 内置支持
Token 消耗 高 显著降低

一句话：Lobster 是 AI Agent 时代的 “bash pipes”——但类型化、安全、可恢复。

项目地址：https://github.com/openclaw/lobster
MIT 协议开源