Lobster

Lobster는 OpenClaw가 다단계 도구 시퀀스를 명시적 승인 체크포인트가 있는 단일 결정적 작업으로 실행할 수 있게 해주는 워크플로 셸입니다.

핵심 가치

어시스턴트가 자신을 관리하는 도구를 직접 만들 수 있습니다. 워크플로를 요청하면 30분 안에 CLI와 파이프라인이 단일 호출로 실행됩니다. Lobster는 바로 그 빠진 조각입니다: 결정적 파이프라인, 명시적 승인, 재개 가능한 상태.

왜 필요한가

현재 복잡한 워크플로에는 많은 도구 호출이 필요합니다. 각 호출은 토큰을 소비하고, LLM이 모든 단계를 조율해야 합니다. Lobster는 이 조율을 타입 지정 런타임으로 이동합니다:

• 하나의 호출로 여러 작업: OpenClaw가 하나의 Lobster 도구 호출을 실행하고 구조화된 결과를 받습니다.
• 내장 승인: 부작용(이메일 전송, 댓글 게시)은 명시적으로 승인될 때까지 워크플로를 일시 중지합니다.
• 재개 가능: 일시 중지된 워크플로는 토큰을 반환하며, 승인 후 모든 것을 다시 실행하지 않고 재개할 수 있습니다.

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

Lobster는 의도적으로 작습니다. “새로운 언어”가 아니라 퍼스트 클래스 승인과 재개 토큰을 갖춘 예측 가능하고 AI 친화적인 파이프라인 사양입니다.

• 승인/재개가 내장: 일반 프로그램도 사용자에게 확인을 요청할 수 있지만, 지속 가능한 토큰으로 _일시 중지하고 재개_하려면 별도의 런타임을 만들어야 합니다.
• 결정성 + 감사 가능성: 파이프라인이 데이터이므로 로깅, diff, 리플레이, 검토가 쉽습니다.
• AI를 위한 제한된 표면: 작은 문법 + JSON 파이핑으로 “창의적인” 코드 경로를 줄이고 검증을 현실적으로 만듭니다.
• 내장된 안전 정책: 타임아웃, 출력 제한, 샌드박스 검사, 허용 목록이 각 스크립트가 아닌 런타임에 의해 적용됩니다.
• 여전히 프로그래밍 가능: 각 단계에서 임의의 CLI나 스크립트를 호출할 수 있습니다. JS/TS를 원한다면 코드에서 .lobster 파일을 생성하세요.

작동 방식

OpenClaw는 로컬 lobster CLI를 도구 모드로 실행하고 stdout에서 JSON 엔벨로프를 파싱합니다. 파이프라인이 승인을 위해 일시 중지되면, 도구는 나중에 계속할 수 있도록 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가 단계를 실행합니다. 승인 게이트가 부작용을 명시적이고 감사 가능하게 유지합니다.

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

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 플러그인 도구를 활성화하고 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 태스크를 참고하세요.

워크플로 파일 (.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에 따라 단계를 게이팅할 수 있습니다.

Lobster 설치

OpenClaw 게이트웨이를 실행하는 동일한 호스트에 Lobster CLI를 설치하고(Lobster 레포지토리 참고), lobster가 PATH에 있는지 확인하세요.

도구 활성화

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

권장 방법 (추가 방식, 안전):

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

또는 에이전트별:

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

제한적 허용 목록 모드를 사용하려는 경우가 아니라면 tools.allow: ["lobster"]는 피하세요.

참고: 허용 목록은 선택적 플러그인에 대한 옵트인 방식입니다. 허용 목록에 lobster와 같은 플러그인 도구만 있는 경우, OpenClaw는 핵심 도구를 활성 상태로 유지합니다. 핵심 도구를 제한하려면 허용 목록에 원하는 핵심 도구나 그룹도 포함하세요.

예시: 이메일 분류

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
}

하나의 워크플로. 결정적. 안전합니다.

도구 매개변수

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

출력 엔벨로프

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

• ok → 성공적으로 완료
• needs_approval → 일시 중지됨; 재개를 위해 requiresApproval.resumeToken 필요
• cancelled → 명시적으로 거부 또는 취소됨

도구는 content(포맷된 JSON)와 details(원시 객체) 모두에 엔벨로프를 표시합니다.

승인

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를 참고하세요.

안전

• 로컬 서브프로세스만 — 플러그인 자체에서 네트워크 호출이 없습니다.
• 시크릿 없음 — Lobster는 OAuth를 관리하지 않으며, OAuth를 처리하는 OpenClaw 도구를 호출합니다.
• 샌드박스 인식 — 도구 컨텍스트가 샌드박스일 때 비활성화됩니다.
• 보안 강화 — PATH의 고정 실행 파일 이름(lobster); 타임아웃과 출력 제한이 적용됩니다.

문제 해결

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

더 알아보기

• 플러그인
• 플러그인 도구 작성

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

공개 사례: 세 개의 마크다운 볼트(개인, 파트너, 공유)를 관리하는 “제2의 뇌” CLI + Lobster 파이프라인. CLI가 통계, 받은 편지함 목록, 오래된 항목 스캔을 JSON으로 출력하고, Lobster가 이 명령들을 weekly-review, inbox-triage, memory-consolidation, shared-task-sync 같은 워크플로로 체이닝하며, 각각 승인 게이트가 있습니다. AI가 판단(분류)을 처리하고, AI를 사용할 수 없을 때는 결정적 규칙으로 폴백합니다.

• 스레드: https://x.com/plattenschieber/status/2014508656335770033
• 레포지토리: https://github.com/bloomedai/brain-cli