什么是 Lobster
Lobster 是 OpenClaw 的工作流 Shell，可以将多个工具调用合并为一次确定性执行，并在关键节点插入人工审批门控。
与常规的 AI 对话式工具调用不同，Lobster 的核心优势：
- 确定性：固定的执行管道，不依赖 LLM 逐步决策
- 可审批：关键操作前暂停等待人工确认
- 可恢复：审批后通过 resume token 继续执行
- 低成本：一次调用替代多次 LLM 往返，节省 Token
启用 Lobster
Lobster 是可选插件工具，需要在配置中显式启用：
{
"tools": {
"alsoAllow": ["lobster"]
}
}
也可以在特定 Agent 配置中单独启用。
内联管道模式
最简单的使用方式是通过 JSON 请求发送内联管道：
{
"action": "run",
"pipeline": "inbox list --json | inbox categorize --json",
"timeoutMs": 30000
}
管道使用 | 连接多个命令，前一步的输出自动作为后一步的输入。
添加审批门控
在管道中插入 approve 命令：
{
"action": "run",
"pipeline": "inbox list --json | inbox categorize --json | approve --prompt '确认发送分类结果？'",
"timeoutMs": 30000
}
执行到 approve 时会暂停，返回 needs_approval 状态和 resume token。
工作流文件模式
对于复杂流程，使用 .lobster 工作流文件（YAML 格式）：
# workflows/inbox-triage.lobster
name: inbox-triage
args:
maxEmails:
default: 20
description: "最大处理邮件数"
env:
INBOX_FOLDER: "INBOX"
steps:
- id: collect
command: inbox list --json --limit $maxEmails
- id: categorize
command: inbox categorize --json
stdin: $collect.stdout
- id: review
approval: required
prompt: "以下邮件将被自动处理，请确认"
- id: execute
command: inbox process --json
stdin: $categorize.stdout
condition: $review.approved
工作流文件特性
| 特性 | 说明 |
|---|---|
args |
带默认值的参数定义 |
env |
环境变量注入 |
stdin |
引用前序步骤输出：$step.stdout 或 $step.json |
condition / when |
条件执行 |
approval |
人工审批门控 |
运行工作流文件
{
"action": "run",
"pipeline": "workflows/inbox-triage.lobster",
"argsJson": {
"maxEmails": 50
},
"timeoutMs": 60000
}
恢复暂停的工作流
当工作流在审批处暂停时，使用 resume 操作继续：
{
"action": "resume",
"token": "<resume-token-from-pause>",
"approve": true
}
设置 "approve": false 则拒绝并取消工作流。
返回值结构
Lobster 返回 JSON 信封，包含三种状态：
// 成功完成
{ "status": "ok", "content": "...", "details": {...} }
// 等待审批
{ "status": "needs_approval", "requiresApproval": { "resumeToken": "..." } }
// 已取消
{ "status": "cancelled" }
结合 LLM Task
通过 llm-task 插件在工作流中使用 LLM 能力：
steps:
- id: classify
tool: llm-task
action: json
args:
prompt: "对以下邮件内容进行意图分类"
schema:
type: object
properties:
intent:
type: string
enum: ["urgent", "normal", "spam"]
summary:
type: string
stdin: $collect.stdout
这在保持确定性的同时，允许在特定步骤使用 AI 分类和摘要能力。
安全机制
Lobster 内置多层安全保护：
- 超时控制：默认 20 秒超时（
timeoutMs） - 输出限制：默认最大 512KB 输出（
maxStdoutBytes） - 沙箱限制：沙箱上下文中自动禁用
- 工作目录约束：
cwd限制在网关目录内 - 无外部进程：在网关进程内运行，不生成子进程
实际应用：邮件分拣工作流
将多次 AI 对话交互压缩为一次 Lobster 调用：
name: email-triage
steps:
- id: fetch
command: gmail search --json --query "is:unread" --limit 30
- id: classify
tool: llm-task
action: json
args:
prompt: "分类邮件：urgent/normal/spam"
schema: { type: array, items: { type: object } }
stdin: $fetch.stdout
- id: preview
approval: required
prompt: "以下邮件将被自动处理"
- id: archive_spam
command: gmail archive --json --label spam
stdin: $classify.json
when: $preview.approved
与其他工具协作
- OpenProse：用于多 Agent 编排，在 Lobster 确定性执行之前协调
- Task Flow：流程级编排，Lobster 适合单个流程内的步骤管理
- Cron：定时触发 Lobster 工作流，实现定时自动化
注意事项
- Lobster 是可选插件，需显式启用
- 不管理 OAuth 认证（委托给 OpenClaw 工具层）
- 工作流文件建议放在
workflows/目录下统一管理 - 复杂场景建议拆分为多个小工作流，通过 Task Flow 编排