Lobster

Lobster là một workflow shell cho phép OpenClaw chạy chuỗi tool nhiều bước như một thao tác duy nhất, xác định với các điểm kiểm tra phê duyệt rõ ràng.

Hook

Assistant của các bạn có thể tự xây dựng các tool để quản lý chính nó. Yêu cầu một workflow, và 30 phút sau các bạn có một CLI cùng các pipeline chạy như một lệnh gọi duy nhất. Lobster là mảnh ghép còn thiếu: pipeline xác định, phê duyệt rõ ràng, và trạng thái có thể tiếp tục.

Tại sao cần Lobster

Hiện tại, các workflow phức tạp yêu cầu nhiều lệnh gọi tool qua lại. Mỗi lệnh gọi tốn token, và LLM phải điều phối từng bước. Lobster chuyển việc điều phối đó vào một runtime có kiểu dữ liệu:

Một lệnh gọi thay vì nhiều: OpenClaw chạy một lệnh gọi Lobster tool và nhận kết quả có cấu trúc.
Phê duyệt tích hợp sẵn: Các tác động phụ (gửi email, đăng comment) sẽ dừng workflow cho đến khi được phê duyệt rõ ràng.
Có thể tiếp tục: Workflow bị dừng trả về một token; phê duyệt và tiếp tục mà không cần chạy lại mọi thứ.

Tại sao dùng DSL thay vì chương trình thông thường?

Lobster được thiết kế nhỏ gọn có chủ đích. Mục tiêu không phải là “một ngôn ngữ mới”, mà là một đặc tả pipeline có thể dự đoán, thân thiện với AI với phê duyệt và resume token hạng nhất.

Approve/resume tích hợp sẵn: Một chương trình thông thường có thể nhắc người dùng, nhưng nó không thể tạm dừng và tiếp tục với một token bền vững nếu các bạn không tự tạo runtime đó.
Tính xác định + khả năng kiểm toán: Pipeline là dữ liệu, nên chúng dễ log, diff, replay và review.
Bề mặt hạn chế cho AI: Một ngữ pháp nhỏ + JSON piping giảm các đường dẫn code “sáng tạo” và làm cho validation thực tế.
Chính sách an toàn tích hợp: Timeout, giới hạn output, kiểm tra sandbox, và allowlist được thực thi bởi runtime, không phải từng script.
Vẫn có thể lập trình: Mỗi bước có thể gọi bất kỳ CLI hoặc script nào. Nếu các bạn muốn JS/TS, hãy tạo file .lobster từ code.

Cách hoạt động

OpenClaw khởi chạy CLI lobster cục bộ ở tool mode và phân tích một JSON envelope từ stdout. Nếu pipeline tạm dừng để phê duyệt, tool trả về một resumeToken để các bạn có thể tiếp tục sau.

Pattern: CLI nhỏ + JSON pipes + phê duyệt

Xây dựng các lệnh nhỏ nói JSON, sau đó xâu chuỗi chúng thành một lệnh gọi Lobster duy nhất. (Tên lệnh ví dụ bên dưới — thay bằng của các bạn.)

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
}

Nếu pipeline yêu cầu phê duyệt, tiếp tục với token:

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

AI kích hoạt workflow; Lobster thực thi các bước. Các cổng phê duyệt giữ cho các tác động phụ rõ ràng và có thể kiểm toán.

Ví dụ: ánh xạ các item đầu vào thành các lệnh gọi tool:

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

Các bước LLM chỉ JSON (llm-task)

Đối với các workflow cần một bước LLM có cấu trúc, hãy bật tool plugin tùy chọn llm-task và gọi nó từ Lobster. Điều này giữ cho workflow xác định trong khi vẫn cho phép các bạn phân loại/tóm tắt/soạn thảo với một model.

Bật tool:

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

Sử dụng nó trong một pipeline:

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
  }
}'

Xem LLM Task để biết chi tiết và các tùy chọn cấu hình.

File workflow (.lobster)

Lobster có thể chạy các file workflow YAML/JSON với các trường name, args, steps, env, condition, và approval. Trong các lệnh gọi OpenClaw tool, đặt pipeline thành đường dẫn file.

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

Lưu ý:

stdin: $step.stdout và stdin: $step.json truyền output của bước trước đó.
condition (hoặc when) có thể kiểm soát các bước dựa trên $step.approved.

Cài đặt Lobster

Cài đặt Lobster CLI trên cùng host chạy OpenClaw Gateway (xem Lobster repo), và đảm bảo lobster có trong PATH. Nếu các bạn muốn sử dụng vị trí binary tùy chỉnh, truyền một lobsterPath tuyệt đối trong lệnh gọi tool.

Bật tool

Lobster là một tool plugin tùy chọn (không được bật mặc định).

Khuyến nghị (bổ sung, an toàn):

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

Hoặc theo từng agent:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "alsoAllow": ["lobster"]
        }
      }
    ]
  }
}

Tránh sử dụng tools.allow: ["lobster"] trừ khi các bạn có ý định chạy ở chế độ allowlist hạn chế.

Lưu ý: allowlist là tùy chọn cho các plugin tùy chọn. Nếu allowlist của các bạn chỉ đặt tên các tool plugin (như lobster), OpenClaw giữ các tool cốt lõi được bật. Để hạn chế các tool cốt lõi, hãy bao gồm các tool cốt lõi hoặc nhóm mà các bạn muốn trong allowlist.

Ví dụ: Phân loại email

Không có Lobster:

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
(lặp lại hàng ngày, không nhớ những gì đã được phân loại)

Với Lobster:

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

Trả về một JSON envelope (đã cắt bớt):

{
  "ok": true,
  "status": "needs_approval",
  "output": [{ "summary": "5 need replies, 2 need action" }],
  "requiresApproval": {
    "type": "approval_request",
    "prompt": "Send 2 draft replies?",
    "items": [],
    "resumeToken": "..."
  }
}

User phê duyệt → tiếp tục:

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

Một workflow. Xác định. An toàn.

Tham số tool

`run`

Chạy một pipeline ở tool mode.

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

Chạy một file workflow với args:

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

`resume`

Tiếp tục một workflow bị dừng sau khi phê duyệt.

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

Đầu vào tùy chọn

lobsterPath: Đường dẫn tuyệt đối đến binary Lobster (bỏ qua để sử dụng PATH).
cwd: Thư mục làm việc cho pipeline (mặc định là thư mục làm việc của process hiện tại).
timeoutMs: Kill subprocess nếu nó vượt quá thời lượng này (mặc định: 20000).
maxStdoutBytes: Kill subprocess nếu stdout vượt quá kích thước này (mặc định: 512000).
argsJson: Chuỗi JSON được truyền cho lobster run --args-json (chỉ file workflow).

Output envelope

Lobster trả về một JSON envelope với một trong ba trạng thái:

ok → hoàn thành thành công
needs_approval → tạm dừng; requiresApproval.resumeToken được yêu cầu để tiếp tục
cancelled → bị từ chối hoặc hủy rõ ràng

Tool hiển thị envelope trong cả content (JSON đẹp) và details (object thô).

Phê duyệt

Nếu requiresApproval có mặt, kiểm tra prompt và quyết định:

approve: true → tiếp tục và thực hiện các tác động phụ
approve: false → hủy và hoàn tất workflow

Sử dụng approve --preview-from-stdin --limit N để đính kèm một bản xem trước JSON vào các yêu cầu phê duyệt mà không cần jq/heredoc glue tùy chỉnh. Resume token giờ đây nhỏ gọn: Lobster lưu trữ trạng thái tiếp tục workflow dưới thư mục state của nó và trả về một token key nhỏ.

OpenProse

OpenProse kết hợp tốt với Lobster: sử dụng /prose để điều phối chuẩn bị multi-agent, sau đó chạy một pipeline Lobster cho các phê duyệt xác định. Nếu một chương trình Prose cần Lobster, cho phép tool lobster cho các sub-agent qua tools.subagents.tools. Xem OpenProse.

An toàn

Chỉ subprocess cục bộ — không có lệnh gọi mạng từ chính plugin.
Không có secret — Lobster không quản lý OAuth; nó gọi các tool OpenClaw làm điều đó.
Nhận biết Sandbox — bị vô hiệu hóa khi ngữ cảnh tool được sandbox hóa.
Được tăng cường — lobsterPath phải là tuyệt đối nếu được chỉ định; timeout và giới hạn output được thực thi.

Troubleshooting

lobster subprocess timed out → tăng timeoutMs, hoặc chia một pipeline dài.
lobster output exceeded maxStdoutBytes → tăng maxStdoutBytes hoặc giảm kích thước output.
lobster returned invalid JSON → đảm bảo pipeline chạy ở tool mode và chỉ in JSON.
lobster failed (code …) → chạy cùng pipeline trong terminal để kiểm tra stderr.

Tìm hiểu thêm

Case study: workflow cộng đồng

Một ví dụ công khai: một CLI “second brain” + các pipeline Lobster quản lý ba Markdown vault (cá nhân, đối tác, chia sẻ). CLI phát ra JSON cho thống kê, danh sách inbox, và quét cũ; Lobster xâu chuỗi các lệnh đó thành các workflow như weekly-review, inbox-triage, memory-consolidation, và shared-task-sync, mỗi cái với các cổng phê duyệt. AI xử lý phán đoán (phân loại) khi có sẵn và quay lại các quy tắc xác định khi không.