OpenClaw Lobster: 복잡한 워크플로우를 단일 호출로 자동화

복잡한 작업을 자동화하려고 할 때, AI가 매번 도구를 호출하고 결과를 기다리는 과정이 번거로우셨죠? 토큰 비용은 계속 나가고, 중간에 실수가 생기면 처음부터 다시 시작해야 하는 상황은 개발자라면 누구나 겪어본 고충일 거예요.

Lobster는 이런 복잡한 워크플로우를 하나의 결정론적인 파이프라인으로 묶어주는 해결책이에요. 명시적인 승인 단계와 중단된 지점부터 다시 시작할 수 있는 기능을 통해 더 안전하고 효율적인 자동화를 구현할 수 있습니다.

Lobster

Lobster는 OpenClaw가 여러 단계의 도구 시퀀스를 명시적인 승인 체크포인트가 있는 단일 작업으로 실행할 수 있게 해주는 워크플로우 쉘이에요.

Lobster는 백그라운드 작업의 한 단계 위에 있는 저작 레이어입니다. 만약 예전의 ClawFlow라는 용어를 보게 된다면, 이는 동일한 작업 지향 런타임 영역에 대한 과거의 명칭으로 생각하면 돼요. 현재 사용자가 마주하는 CLI 인터페이스는 openclaw tasks입니다.

Hook

어시스턴트가 스스로를 관리하는 도구를 직접 만들 수 있습니다. 워크플로우를 요청하면 30분 만에 한 번의 호출로 실행되는 CLI와 파이프라인을 갖게 되죠. Lobster는 결정론적 파이프라인, 명시적 승인, 그리고 재개 가능한 상태라는 빠진 조각을 채워줍니다.

Why

오늘날 복잡한 워크플로우는 도구 호출을 여러 번 주고받아야 합니다. 각 호출마다 토큰이 소모되고, LLM이 모든 단계를 조율해야 하죠. Lobster는 그 조율 과정을 타입화된 런타임으로 옮겨줍니다.

여러 번 대신 한 번의 호출: OpenClaw는 하나의 Lobster 도구 호출을 실행하고 구조화된 결과를 얻습니다.
기본 내장된 승인 단계: 이메일 발송이나 댓글 게시 같은 부수 효과(Side effects)는 명시적으로 승인될 때까지 워크플로우를 중단시킵니다.
재개 가능: 중단된 워크플로우는 토큰을 반환합니다. 모든 것을 처음부터 다시 실행할 필요 없이 승인 후 바로 재개할 수 있어요.

Why a DSL instead of plain programs?

Lobster는 의도적으로 작게 설계되었습니다. 목표는 “새로운 언어”를 만드는 것이 아니라, 승인과 재개 토큰을 기본으로 지원하는 예측 가능하고 AI 친화적인 파이프라인 스펙을 제공하는 것이에요.

승인/재개 기능 내장: 일반적인 프로그램도 사용자에게 물어볼 수는 있지만, 런타임을 직접 발명하지 않고서는 지속 가능한 토큰으로 일시 중단 및 재개를 할 수 없습니다.
결정론 및 감사 가능성: 파이프라인은 데이터이므로 로그 기록, 비교(diff), 재생 및 검토가 쉽습니다.
AI를 위한 제한된 범위: 아주 작은 문법과 JSON 파이핑은 “창의적인” 코드 경로를 줄여주고 검증을 현실적으로 만들어줍니다.
보안 정책 내장: 타임아웃, 출력 제한, 샌드박스 체크, 허용 목록(allowlist) 등이 각 스크립트가 아닌 런타임에 의해 강제됩니다.
프로그래밍 가능: 각 단계는 모든 CLI나 스크립트를 호출할 수 있습니다. JS/TS를 원한다면 코드에서 .lobster 파일을 생성하면 됩니다.

How it works

OpenClaw는 로컬 lobster CLI를 **도구 모드(tool mode)**로 실행하고 stdout에서 JSON 엔벨로프를 파싱합니다. 만약 파이프라인이 승인을 위해 일시 중단되면, 도구는 나중에 계속할 수 있도록 resumeToken을 반환합니다.

Pattern: small CLI + JSON pipes + approvals

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가 단계를 실행합니다. 승인 게이트는 부수 효과를 명시적이고 감사 가능하게 유지해 줍니다.

예시: 입력 항목을 도구 호출로 매핑하기:

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

JSON-only LLM steps (llm-task)

구조화된 LLM 단계가 필요한 워크플로우의 경우, 선택 사항인 llm-task 플러그인 도구를 활성화하고 Lobster에서 호출하세요. 이렇게 하면 모델을 사용해 분류, 요약, 초안 작성을 하면서도 워크플로우를 결정론적으로 유지할 수 있습니다.

도구 활성화:

{
  "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를 참조하세요.

Workflow files (.lobster)

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 상태에 따라 단계 실행 여부를 결정할 수 있습니다.

Install Lobster

OpenClaw Gateway가 실행되는 동일한 호스트에 Lobster CLI를 설치하고(Lobster 저장소 참조), lobster가 PATH에 있는지 확인하세요.

Enable the tool

Lobster는 선택 사항인 플러그인 도구입니다(기본적으로 활성화되어 있지 않음).

권장 설정 (추가 방식, 안전함):

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

또는 에이전트별 설정:

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

제한적인 허용 목록 모드에서 실행하려는 의도가 아니라면 tools.allow: ["lobster"] 사용은 피하는 것이 좋습니다.

참고: 허용 목록은 선택적 플러그인에 대해 옵트인(opt-in) 방식입니다. 허용 목록에 lobster와 같은 플러그인 도구만 지정하면 OpenClaw는 핵심(core) 도구들을 활성화된 상태로 유지합니다. 핵심 도구를 제한하려면 허용 목록에 원하는 핵심 도구나 그룹을 함께 포함해야 합니다.

Example: Email triage

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
(repeat daily, no memory of what was triaged)

Lobster가 있을 때:

{
  "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
}

하나의 워크플로우로 해결됩니다. 결정론적이고 안전하죠.

Tool parameters

`run`

도구 모드에서 파이프라인을 실행합니다.

{
  "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 문자열 (워크플로우 파일 전용).

Output envelope

Lobster는 세 가지 상태 중 하나를 가진 JSON 엔벨로프를 반환합니다.

ok → 성공적으로 완료됨
needs_approval → 일시 중단됨; 재개를 위해 requiresApproval.resumeToken이 필요함
cancelled → 명시적으로 거부되거나 취소됨

도구는 이 엔벨로프를 content (보기 좋은 JSON)와 details (원시 객체) 모두에 노출합니다.

Approvals

requiresApproval이 존재하면 프롬프트를 확인하고 결정하세요.

approve: true → 재개하고 부수 효과를 계속 진행
approve: false → 취소하고 워크플로우 종료

approve --preview-from-stdin --limit N을 사용하면 별도의 jq나 heredoc 처리 없이도 승인 요청에 JSON 미리보기를 첨부할 수 있습니다. 재개 토큰은 이제 간결해졌습니다. Lobster는 워크플로우 재개 상태를 자체 상태 디렉토리에 저장하고 작은 토큰 키만 전달합니다.

OpenProse

OpenProse는 Lobster와 잘 어울립니다. /prose를 사용해 멀티 에이전트 준비 과정을 조율한 다음, 결정론적 승인을 위해 Lobster 파이프라인을 실행하세요. Prose 프로그램에 Lobster가 필요한 경우, tools.subagents.tools를 통해 서브 에이전트에게 lobster 도구를 허용해 주세요. OpenProse를 참조하세요.

Safety

로컬 서브프로세스 전용 — 플러그인 자체에서 네트워크 호출을 하지 않습니다.
비밀 정보 없음 — Lobster는 OAuth를 관리하지 않습니다. 대신 이를 관리하는 OpenClaw 도구를 호출합니다.
샌드박스 인식 — 도구 컨텍스트가 샌드박스화된 경우 비활성화됩니다.
강화된 보안 — PATH에 있는 고정된 실행 파일 이름(lobster)을 사용하며, 타임아웃과 출력 제한이 강제됩니다.

Troubleshooting

lobster subprocess timed out → timeoutMs를 늘리거나 긴 파이프라인을 분할하세요.
lobster output exceeded maxStdoutBytes → maxStdoutBytes를 높이거나 출력 크기를 줄이세요.
lobster returned invalid JSON → 파이프라인이 도구 모드에서 실행 중이며 JSON만 출력하는지 확인하세요.
lobster failed (code …) → 터미널에서 동일한 파이프라인을 실행하여 stderr를 확인하세요.

Learn more

Case study: community workflows

공개된 사례 중 하나로, 세 개의 Markdown 보관함(개인용, 파트너용, 공용)을 관리하는 “제2의 뇌” CLI와 Lobster 파이프라인이 있습니다. CLI는 통계, 인박스 목록, 오래된 항목 스캔을 위해 JSON을 내보내고, Lobster는 이러한 명령어들을 weekly-review, inbox-triage, memory-consolidation, shared-task-sync와 같은 워크플로우로 연결하며 각 단계에 승인 게이트를 둡니다. AI는 판단(분류)이 필요할 때 개입하고, 그렇지 않을 때는 결정론적 규칙을 따릅니다.

Cron vs Heartbeat — Lobster 워크플로우 스케줄링
Automation Overview — 모든 자동화 메커니즘
Tools Overview — 사용 가능한 모든 에이전트 도구

AI Setup Assistant

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.