메인 콘텐츠로 건너뛰기

​
Lobster

Lobster는 OpenClaw가 다단계 tool 시퀀스를 명시적인 승인 체크포인트와 함께 하나의 결정론적 작업으로 실행할 수 있게 해주는 워크플로 셸입니다. Lobster는 분리된 백그라운드 작업보다 한 단계 위의 작성 계층입니다. 개별 작업 위의 흐름 오케스트레이션은 Task Flow (openclaw tasks flow)를 참고하세요. 작업 활동 원장은 openclaw tasks를 참고하세요.

​
Hook

어시스턴트는 자신을 관리하는 도구를 직접 만들 수 있습니다. 워크플로를 요청하면, 30분 후 하나의 호출로 실행되는 CLI와 파이프라인을 얻게 됩니다. Lobster는 빠져 있던 조각입니다. 결정론적 파이프라인, 명시적 승인, 재개 가능한 상태를 제공합니다.

​
이유

오늘날 복잡한 워크플로에는 많은 왕복 tool 호출이 필요합니다. 각 호출은 토큰 비용이 들고, LLM은 모든 단계를 오케스트레이션해야 합니다. Lobster는 그 오케스트레이션을 타입이 지정된 런타임으로 옮깁니다:
  • 여러 번의 호출 대신 한 번의 호출: OpenClaw는 Lobster tool 호출 한 번을 실행하고 구조화된 결과를 받습니다.
  • 승인 내장: 부작용(이메일 전송, 댓글 게시)은 명시적으로 승인될 때까지 워크플로를 중단합니다.
  • 재개 가능: 중단된 워크플로는 토큰을 반환하며, 모든 것을 다시 실행하지 않고 승인 후 재개할 수 있습니다.

​
왜 일반 프로그램 대신 DSL인가?

Lobster는 의도적으로 작게 설계되었습니다. 목표는 “새 언어”가 아니라, 승인과 재개 토큰을 일급으로 지원하는 예측 가능하고 AI 친화적인 파이프라인 명세입니다.
  • 승인/재개가 내장됨: 일반 프로그램도 사람에게 물어볼 수는 있지만, 자체적으로 그 런타임을 만들지 않는 한 내구성 있는 토큰으로 _중단했다가 재개_할 수는 없습니다.
  • 결정론 + 감사 가능성: 파이프라인은 데이터이므로 로그 기록, diff, 재실행, 검토가 쉽습니다.
  • AI를 위한 제한된 표면: 작은 문법 + JSON 파이프는 “창의적인” 코드 경로를 줄이고 검증을 현실적으로 만듭니다.
  • 안전 정책 내장: 타임아웃, 출력 제한, 샌드박스 검사, 허용 목록은 각 스크립트가 아니라 런타임이 강제합니다.
  • 여전히 프로그래밍 가능: 각 단계는 어떤 CLI나 스크립트도 호출할 수 있습니다. JS/TS를 원한다면 코드에서 .lobster 파일을 생성하면 됩니다.

​
동작 방식

OpenClaw는 로컬 lobster CLI를 tool mode로 실행하고 stdout에서 JSON envelope를 파싱합니다. 파이프라인이 승인을 위해 일시 중지되면, tool은 나중에 계속할 수 있도록 resumeToken을 반환합니다.

​
패턴: 작은 CLI + JSON 파이프 + 승인

JSON을 말하는 작은 명령들을 만들고, 이를 하나의 Lobster 호출로 연결하세요. (아래 명령 이름은 예시이므로, 직접 만든 것으로 바꾸세요.) 
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
}
AI가 워크플로를 트리거하고, Lobster가 단계를 실행합니다. 승인 게이트는 부작용을 명시적이고 감사 가능하게 유지합니다. 예시: 입력 항목을 tool 호출로 매핑하기: 
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 플러그인 tool을 활성화하고 Lobster에서 호출하세요. 이렇게 하면 워크플로를 결정론적으로 유지하면서도 모델을 사용해 분류/요약/초안 작성을 할 수 있습니다. tool 활성화: 
{
  "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.",
  "thinking": "low",
  "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 tool 호출에서는 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를 기준으로 단계를 게이트할 수 있습니다.

​
Lobster 설치

OpenClaw Gateway를 실행하는 동일한 호스트에 Lobster CLI를 설치하고(Lobster repo 참고), lobster가 PATH에 있도록 하세요.

​
tool 활성화

Lobster는 선택적 플러그인 tool입니다(기본적으로 활성화되지 않음). 권장 방식(추가형, 안전함): 
{
  "tools": {
    "alsoAllow": ["lobster"]
  }
}
또는 에이전트별로: 
{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "alsoAllow": ["lobster"]
        }
      }
    ]
  }
}
제한적인 허용 목록 모드로 실행하려는 의도가 아니라면 tools.allow: ["lobster"]는 사용하지 마세요. 참고: 허용 목록은 선택적 플러그인에 대해 옵트인 방식입니다. 허용 목록에 lobster 같은 플러그인 tool만 들어 있으면, OpenClaw는 코어 tool을 계속 활성화합니다. 코어 tool을 제한하려면 허용 목록에 원하는 코어 tool 또는 그룹도 포함하세요.

​
예시: 이메일 분류

Lobster 없이: 
사용자: "내 이메일을 확인하고 답장 초안을 작성해줘"
→ openclaw가 gmail.list 호출
→ LLM이 요약
→ 사용자: "#2와 #5에 대한 답장 초안을 작성해줘"
→ LLM이 초안 작성
→ 사용자: "#2를 보내"
→ openclaw가 gmail.send 호출
(매일 반복, 무엇을 분류했는지 기억 없음)
Lobster 사용 시: 
{
  "action": "run",
  "pipeline": "email.triage --limit 20",
  "timeoutMs": 30000
}
JSON envelope 반환(일부 생략): 
{
  "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
}
하나의 워크플로. 결정론적. 안전함.

​
tool 매개변수

​
run

tool mode에서 파이프라인을 실행합니다. 
{
  "action": "run",
  "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
  "cwd": "workspace",
  "timeoutMs": 30000,
  "maxStdoutBytes": 512000
}
인수가 있는 워크플로 파일 실행: 
{
  "action": "run",
  "pipeline": "/path/to/inbox-triage.lobster",
  "argsJson": "{\"tag\":\"family\"}"
}

​
resume

승인 후 중단된 워크플로를 계속합니다. 
{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}

​
선택적 입력

  • cwd: 파이프라인의 상대 작업 디렉터리입니다(현재 프로세스 작업 디렉터리 안에 있어야 함).
  • timeoutMs: 이 시간을 초과하면 서브프로세스를 종료합니다(기본값: 20000).
  • maxStdoutBytes: stdout이 이 크기를 초과하면 서브프로세스를 종료합니다(기본값: 512000).
  • argsJson: lobster run --args-json에 전달되는 JSON 문자열입니다(워크플로 파일 전용).

​
출력 envelope

Lobster는 세 가지 상태 중 하나를 가진 JSON envelope를 반환합니다:
  • ok → 성공적으로 완료됨
  • needs_approval → 일시 중지됨; 재개하려면 requiresApproval.resumeToken이 필요함
  • cancelled → 명시적으로 거부되었거나 취소됨
tool은 content(예쁘게 포맷된 JSON)와 details(원시 객체) 모두에 envelope를 노출합니다.

​
승인

requiresApproval이 있으면 프롬프트를 확인하고 결정하세요:
  • approve: true → 재개하고 부작용 계속 진행
  • approve: false → 취소하고 워크플로 종료
커스텀 jq/heredoc 연결 없이 승인 요청에 JSON 미리보기를 첨부하려면 approve --preview-from-stdin --limit N을 사용하세요. 이제 재개 토큰은 간결합니다. Lobster는 워크플로 재개 상태를 자신의 state 디렉터리에 저장하고 작은 토큰 키를 반환합니다.

​
OpenProse

OpenProse는 Lobster와 잘 어울립니다. /prose를 사용해 다중 에이전트 준비를 오케스트레이션한 다음, 결정론적 승인을 위해 Lobster 파이프라인을 실행하세요. Prose 프로그램에 Lobster가 필요하면 tools.subagents.tools를 통해 sub-agent에 lobster tool을 허용하세요. OpenProse를 참고하세요.

​
안전

  • 로컬 서브프로세스 전용 — 플러그인 자체에서는 네트워크 호출을 하지 않습니다.
  • 시크릿 없음 — Lobster는 OAuth를 관리하지 않으며, 대신 이를 처리하는 OpenClaw tool을 호출합니다.
  • 샌드박스 인식 — tool 문맥이 샌드박스된 경우 비활성화됩니다.
  • 강화됨 — PATH 상의 고정 실행 파일 이름(lobster)을 사용하며, 타임아웃과 출력 제한이 강제됩니다.

​
문제 해결

  • lobster subprocess timed out → timeoutMs를 늘리거나 긴 파이프라인을 분할하세요.
  • lobster output exceeded maxStdoutBytes → maxStdoutBytes를 늘리거나 출력 크기를 줄이세요.
  • lobster returned invalid JSON → 파이프라인이 tool mode로 실행되고 JSON만 출력하는지 확인하세요.
  • lobster failed (code …) → 동일한 파이프라인을 터미널에서 실행해 stderr를 확인하세요.

​
더 알아보기

​
사례 연구: 커뮤니티 워크플로

하나의 공개 예시로, 개인/파트너/공유 세 개의 Markdown 볼트를 관리하는 “second brain” CLI + Lobster 파이프라인이 있습니다. 이 CLI는 통계, 받은편지함 목록, 오래된 항목 스캔에 대해 JSON을 출력하고, Lobster는 이 명령들을 weekly-review, inbox-triage, memory-consolidation, shared-task-sync 같은 워크플로로 연결하며 각각 승인 게이트를 둡니다. 가능할 때는 AI가 판단(분류)을 담당하고, 그렇지 않을 때는 결정론적 규칙으로 폴백합니다.

​
관련 문서