Skip to main content

​
龙虾

龙虾是一种工作流外壳，使OpenClaw能够以单一、确定性的操作运行多步骤工具序列，并配备明确的审批检查点。

​
挂钩

你的助手可以帮你构建自我管理的工具。只需请求一个工作流，30分钟后你就能拥有一套命令行界面工具以及可作为单次调用运行的管道。龙虾正是这一缺失的关键环节：它提供了确定性管道、明确的审批流程和可恢复的状态。

​
为什么

如今，复杂的工作流需要多次来回调用工具。每次调用都会消耗令牌，且LLM必须协调每一步。龙虾将这种协调转移到一个类型化的运行时中：
  • 一次调用取代多次调用：OpenClaw只需调用一次龙虾工具，即可直接获取结构化结果。
  • 内置审批机制：在未获得明确批准之前，任何具有副作用的操作（如发送电子邮件、发表评论）都会暂停工作流的执行。
  • 可恢复：被暂停的工作流会返回一个令牌；在获得批准后，工作流可以从中断处恢复，而无需重新运行整个流程。

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

龙虾的设计刻意精简。它的目标并非“一种新语言”，而是一种可预测、对AI友好的管道规范，具备一流的审批和恢复令牌。
  • 内置审批/恢复功能：普通程序可以向人类发出提示，但在没有你自行设计的运行时的情况下，它无法借助持久令牌实现“暂停并恢复”操作。
  • 确定性 + 可审计性：管道本身就是数据，因此可以轻松记录、比较、重放和审查，确保全程可追溯。
  • 为AI划定清晰边界：通过采用精简的语法和基于JSON的管道，我们大幅减少了“创造性”代码路径的数量，从而使代码验证变得切实可行。
  • 内置安全策略：超时限制、输出上限、沙盒检查和白名单等安全机制由运行时统一强制执行，无需每个脚本单独处理。
  • 依然高度可编程：每一步都可以调用任意CLI工具或脚本。如果你需要使用JS或TS，可以通过代码生成.lobster文件来满足需求。

​
工作原理

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

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

构建以JSON为通信协议的小型命令，然后将它们串联成一次龙虾调用。（以下为示例命令名称——请替换为你自己的。） 
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插件工具，并从龙虾中调用它。这使工作流保持 确定性，同时仍允许你使用模型进行分类、总结或草拟。 启用该工具： 
{
  "plugins": {
    "entries": {
      "llm-task": { "enabled": true }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": { "allow": ["llm-task"] }
      }
    ]
  }
}
在管道中使用它： 
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任务。

​
工作流文件（.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控制步骤。

​
安装龙虾

在运行OpenClaw网关的同一主机上安装龙虾CLI（参见龙虾仓库），并确保lobster位于PATH上。 如果你想使用自定义二进制位置，在工具调用中传递一个绝对lobsterPath。

​
启用工具

龙虾是一个可选的插件工具（默认未启用）。 推荐（叠加式，安全）： 
{
  "tools": {
    "alsoAllow": ["lobster"]
  }
}
或按代理： 
{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "alsoAllow": ["lobster"]
        }
      }
    ]
  }
}
除非你打算在严格的白名单模式下运行，否则请避免使用tools.allow: ["lobster"]。 注意：白名单是可选插件的一项可选功能。如果你的白名单仅列出 插件工具（如lobster），OpenClaw将保持核心工具处于启用状态。若要限制核心 工具，你还需将希望保留的核心工具或工具组列入白名单。

​
示例：邮件分类

没有龙虾： 
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)
有了龙虾： 
{
  "action": "run",
  "pipeline": "email.triage --limit 20",
  "timeoutMs": 30000
}
返回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": "..."
  }
}
用户批准→恢复： 
{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}
一个工作流。确定性。安全。

​
工具参数

​
run

以工具模式运行管道。 
{
  "action": "run",
  "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
  "cwd": "/path/to/workspace",
  "timeoutMs": 30000,
  "maxStdoutBytes": 512000
}
使用参数运行工作流文件： 
{
  "action": "run",
  "pipeline": "/path/to/inbox-triage.lobster",
  "argsJson": "{\"tag\":\"family\"}"
}

​
resume

在审批后继续暂停的工作流。 
{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}

​
可选输入

  • lobsterPath：龙虾二进制文件的绝对路径（省略时使用PATH）。
  • cwd：管道的工作目录（默认为当前进程的工作目录）。
  • timeoutMs：如果子进程运行时间超过此持续时间，则将其终止（默认：20000）。
  • maxStdoutBytes：如果stdout大小超过此限制，则终止子进程（默认：512000）。
  • argsJson：传递给lobster run --args-json的JSON字符串（仅适用于工作流文件）。

​
输出信封

龙虾返回一个JSON信封，包含三种状态之一：
  • ok → 成功完成
  • needs_approval → 暂停；需requiresApproval.resumeToken才能恢复
  • cancelled → 明确拒绝或取消
该工具以两种形式呈现信封：content（美观的JSON）和details（原始对象）。

​
审批

如果存在requiresApproval，请检查提示并决定：
  • approve: true → 恢复并继续副作用
  • approve: false → 取消并结束工作流
使用approve --preview-from-stdin --limit N可在不使用自定义jq/heredoc胶水的情况下，将JSON预览附加到审批请求中。恢复令牌现在更加紧凑：龙虾将其工作流恢复状态存储在其状态目录下，并返回一个较小的令牌密钥。

​
开放散文

OpenProse与龙虾配合默契：使用/prose来编排多代理准备，然后运行龙虾管道以实现确定性审批。如果Prose程序需要龙虾，可通过tools.subagents.tools为子代理启用lobster工具。详情请参阅OpenProse。

​
安全性

  • 仅本地子进程 — 插件本身不执行任何网络调用。
  • 无机密 — 龙虾不负责管理OAuth；它会调用专门负责管理OAuth的OpenClaw工具。
  • 沙盒感知 — 当工具上下文位于沙盒中时，该功能将被禁用。
  • 加固 — 如果指定了lobsterPath，则必须使用绝对路径；并强制实施超时限制和输出上限。
故障排除
  • lobster subprocess timed out → 增加timeoutMs，或拆分长管道。
  • lobster output exceeded maxStdoutBytes → 提高maxStdoutBytes，或减少输出大小。
  • lobster returned invalid JSON → 确保管道在工具模式下运行，并且仅输出JSON。
  • lobster failed (code …) → 在终端中运行相同的管道，以检查stderr。

​
了解更多信息

​
案例研究：社区工作流

一个公开示例：一个“第二大脑”CLI结合龙虾管道，用于管理三个Markdown保险库——个人、伙伴和共享。CLI会输出用于统计分析、收件箱列表生成以及过时内容扫描的JSON数据；龙虾则将这些命令串联成一系列工作流，例如weekly-review、inbox-triage、memory-consolidation和shared-task-sync，每个工作流都配备了审批闸门。在AI可用时，由AI负责判断（分类）；当AI不可用时，则退而求其次，转而使用确定性规则来处理任务。