바닷가재

Lobster는 명시적인 승인 체크포인트와 재개 토큰을 사용하여 다단계 도구 파이프라인을 하나의 결정론적 도구 호출로 실행합니다. 이는 분리된 백그라운드 작업보다 한 계층 위에 있습니다. 여러 분리된 작업에 걸친 흐름을 오케스트레이션하려면 Task Flow(openclaw tasks flow)를 참조하고, 작업 활동 원장은 백그라운드 작업을 참조하세요.

필요한 이유

Lobster가 없으면 다단계 작업에는 여러 차례의 왕복 도구 호출이 필요하며, 모델이 모든 단계를 오케스트레이션해야 합니다. Lobster는 이 오케스트레이션을 타입이 지정된 런타임으로 옮깁니다.

여러 번이 아닌 한 번의 호출: 단일 Lobster 도구 호출이 전체 파이프라인의 구조화된 결과를 반환합니다.
내장된 승인: 부작용(전송, 게시, 삭제)이 있는 경우 명시적으로 승인될 때까지 워크플로가 중단됩니다.
재개 가능: 중단된 워크플로는 토큰을 반환하므로, 이전 단계를 다시 실행하지 않고 승인 후 재개할 수 있습니다.

Lobster는 범용 스크립팅 언어가 아니라 작고 제약된 DSL입니다. 승인/재개는 지속성이 있는 내장 기본 요소이고, 파이프라인은 데이터이므로 로깅, 차이 비교, 재실행, 검토가 쉽습니다. 작은 문법은 “창의적인” 코드 경로를 제한하여 검증을 현실적으로 유지하며, 시간 제한, 출력 상한, 샌드박스 검사, 허용 목록은 각 스크립트가 아니라 런타임에서 적용합니다. 각 단계에서는 여전히 모든 CLI나 스크립트를 호출할 수 있습니다. 더 풍부한 작성 언어가 필요하면 다른 도구에서 .lobster 파일을 생성하세요. Lobster가 없으면 반복적인 이메일 분류는 다음과 같습니다.

사용자: "내 이메일을 확인하고 답장을 작성해 줘"
→ openclaw가 gmail.list 호출
→ LLM이 요약
→ 사용자: "#2와 #5에 대한 답장을 작성해 줘"
→ LLM이 초안 작성
→ 사용자: "#2를 보내 줘"
→ openclaw가 gmail.send 호출
(매일 반복되며, 분류한 내용은 기억하지 못함)

Lobster를 사용하면 같은 작업이 승인을 위해 중단되고 이후 재개되는 한 번의 호출로 처리됩니다.

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

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

작동 방식

OpenClaw는 번들로 제공되는 @clawdbot/lobster 패키지를 임베디드 실행기로 사용하여 Lobster 워크플로를 프로세스 내에서 실행합니다. 외부 lobster 하위 프로세스는 생성되지 않으며, 도구 호출이 JSON 봉투를 직접 반환합니다. 파이프라인이 승인을 위해 중단되면 나중에 계속할 수 있도록 봉투에 재개 토큰 또는 짧은 승인 ID가 포함됩니다.

활성화

Lobster는 기본적으로 활성화되지 않는 선택적 Plugin 도구입니다. 번들로 제공되므로 별도의 설치 단계 없이 도구만 허용하면 됩니다.

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

또는 에이전트별로 설정합니다.

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

alsoAllow는 다른 핵심 도구를 제한하지 않고 활성 도구 프로필에 lobster를 추가합니다. 제한적인 허용 목록 모드를 사용하려는 경우에만 tools.allow를 대신 사용하세요.

샌드박스 처리된 도구 컨텍스트에서는 이 도구가 완전히 비활성화됩니다. 개발 또는 외부 파이프라인을 위해 임베디드 Gateway 실행기 외부에서 독립 실행형 Lobster CLI가 필요하다면 Lobster 저장소에서 설치하고 lobster를 PATH에 추가하세요.

패턴: 소형 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
}

예시: 입력 항목을 도구 호출로 매핑합니다.

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 Plugin 도구를 활성화하고 Lobster에서 호출합니다.

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

중요 제한 사항: 임베디드 Lobster와 `openclaw.invoke`

번들 Lobster Plugin은 Gateway 내부에서 워크플로를 프로세스 내에서 실행합니다. 이 임베디드 모드에서 openclaw.invoke는 중첩된 OpenClaw CLI 도구 호출에 필요한 Gateway URL/인증 컨텍스트를 자동으로 상속하지 않습니다. 따라서 다음 패턴은 현재 임베디드 실행기에서 안정적으로 동작하지 않습니다.

openclaw.invoke --tool llm-task --action json --args-json '{ ... }'

다음 예시는 openclaw.invoke에 올바른 Gateway/인증 컨텍스트가 이미 구성된 환경에서 독립 실행형 Lobster CLI를 실행할 때만 사용하세요.

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

현재 임베디드 Lobster Plugin을 사용 중이라면 다음 중 하나를 권장합니다.

Lobster 외부에서 llm-task 도구를 직접 호출하거나
지원되는 임베디드 브리지가 추가될 때까지 Lobster 파이프라인 내부에서 openclaw.invoke를 사용하지 않는 단계를 사용합니다.

자세한 내용과 구성 옵션은 LLM 작업을 참조하세요.

워크플로 파일(.lobster)

Lobster는 name, args, steps, env, condition, approval 필드가 포함된 YAML/JSON 워크플로 파일을 실행할 수 있습니다. 도구 호출의 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에 따라 단계 실행 여부를 제어할 수 있습니다.

도구 매개변수

`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\"}"
}

필드	기본값	참고
`pipeline`	필수	인라인 파이프라인 문자열 또는 워크플로 파일을 가리키는 `.lobster`/`.yaml`/`.yml`/`.json`으로 끝나는 경로입니다.
`cwd`	Gateway cwd	상대 작업 디렉터리입니다. Gateway 작업 디렉터리 내부로 해석되어야 하며 절대 경로는 거부됩니다.
`timeoutMs`	`20000`	이 시간을 초과하면 실행을 중단합니다.
`maxStdoutBytes`	`512000`	캡처된 표준 출력 또는 표준 오류가 이 크기를 초과하면 실행을 중단합니다.
`argsJson`	-	워크플로 파일에 전달할 인수의 JSON 문자열입니다. 인라인 파이프라인에서는 무시됩니다.

`resume`

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

resume은 token(requiresApproval의 전체 재개 토큰) 또는 approvalId(같은 객체의 짧은 ID)를 받습니다. 중단된 실행이 반환한 값을 사용하세요. approve는 필수입니다.

관리형 Task Flow 모드

run에 flowControllerId와 flowGoal을 전달하거나 resume에 flowId와 flowExpectedRevision을 전달하면, 호출은 단순 봉투를 반환하는 대신 Plugin 런타임의 관리형 Task Flow API를 통해 처리됩니다. OpenClaw는 지속성 있는 흐름 레코드를 생성하거나 재개하고 Lobster 봉투를 적용하여 승인 시 waiting, 완료 시 succeeded/failed로 설정한 뒤 { ok, envelope, flow, mutation }을 반환합니다. 이 모드에는 바인딩된 Task Flow 런타임이 필요하며, 일반적인 임시 에이전트 사용이 아니라 Gateway 재시작 후에도 지속되는 흐름 상태가 필요한 Plugin/컨트롤러 코드를 위한 것입니다.

출력 봉투

Lobster는 다음 세 가지 상태 중 하나를 포함하는 JSON 봉투를 반환합니다.

ok - 성공적으로 완료됨
needs_approval - 일시 중지됨. requiresApproval에 resumeToken과 짧은 approvalId가 포함되며, 둘 중 하나로 실행을 재개할 수 있음
cancelled - 명시적으로 거부되거나 취소됨

도구는 content(보기 좋게 정리된 JSON)와 details(원시 객체) 모두에 봉투를 노출합니다.

승인

requiresApproval이 있으면 프롬프트를 확인하고 결정합니다.

approve: true - 재개하고 부작용을 계속 실행
approve: false - 워크플로를 취소하고 종료

사용자 정의 jq/heredoc 연결 코드 없이 승인 요청에 JSON 미리보기를 첨부하려면 approve --preview-from-stdin --limit N을 사용하세요. 재개 상태는 Lobster 상태 디렉터리(기본값은 ~/.lobster/state, LOBSTER_STATE_DIR로 재정의 가능) 아래에 작은 JSON 파일로 저장됩니다. 토큰 자체에는 전체 파이프라인 상태가 아니라 해당 상태를 가리키는 포인터만 인코딩됩니다.

OpenProse

OpenProse는 Lobster와 함께 사용하기 좋습니다. /prose로 다중 에이전트 준비 작업을 오케스트레이션한 다음, 결정론적 승인을 위해 Lobster 파이프라인을 실행하세요. Prose 프로그램에 Lobster가 필요하면 tools.subagents.tools를 통해 하위 에이전트에 lobster 도구를 허용하세요. OpenProse를 참조하세요.

안전성

로컬 프로세스 내에서만 실행 - 워크플로는 Gateway 프로세스 내부에서 실행되며 Plugin 자체에서는 네트워크 호출을 수행하지 않습니다.
비밀 정보 없음 - Lobster는 OAuth를 관리하지 않으며, 이를 처리하는 OpenClaw 도구를 호출합니다.
샌드박스 인식 - 도구 컨텍스트가 샌드박스 처리된 경우 비활성화됩니다.
강화됨 - 시간 제한과 출력 상한은 임베디드 실행기에서 적용됩니다.

문제 해결

오류	원인 / 해결 방법
`lobster runtime timed out`	파이프라인이 `timeoutMs`를 초과했습니다. 값을 늘리거나 파이프라인을 분할하세요.
`lobster stdout exceeded maxStdoutBytes`(또는 `stderr`)	캡처된 출력이 상한을 초과했습니다. `maxStdoutBytes`를 늘리거나 출력을 줄이세요.
`run --args-json must be valid JSON`	`argsJson`(워크플로 파일 실행)을 구문 분석하지 못했습니다. JSON 문자열을 수정하세요.
`lobster runtime failed`(또는 다른 `runtime_error` 메시지)	임베디드 런타임이 오류 봉투를 반환했습니다. 자세한 내용은 Gateway 로그를 확인하세요.

자세히 알아보기

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

공개된 예시 중 하나는 세 개의 Markdown 볼트(개인용, 파트너용, 공유용)를 관리하는 “세컨드 브레인” CLI + Lobster 파이프라인입니다. 이 CLI는 통계, 받은 편지함 목록, 오래된 항목 검사를 JSON으로 출력하며, Lobster는 이러한 명령을 각각 승인 게이트가 있는 weekly-review, inbox-triage, memory-consolidation, shared-task-sync 등의 워크플로로 연결합니다. AI를 사용할 수 있으면 판단(분류)을 처리하고, 사용할 수 없으면 결정론적 규칙으로 대체합니다.

스레드: https://x.com/plattenschieber/status/2014508656335770033
저장소: https://github.com/bloomedai/brain-cli

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

필요한 이유

작동 방식

활성화

패턴: 소형 CLI + JSON 파이프 + 승인

JSON 전용 LLM 단계(llm-task)

중요 제한 사항: 임베디드 Lobster와 `openclaw.invoke`

워크플로 파일(.lobster)

도구 매개변수

`run`

`resume`

관리형 Task Flow 모드

출력 봉투

승인

OpenProse

안전성

문제 해결

자세히 알아보기

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

관련 항목

​필요한 이유

​작동 방식

​활성화

​패턴: 소형 CLI + JSON 파이프 + 승인

​JSON 전용 LLM 단계(llm-task)

​중요 제한 사항: 임베디드 Lobster와 openclaw.invoke

​워크플로 파일(.lobster)

​도구 매개변수

​run

​resume

​관리형 Task Flow 모드

​출력 봉투

​승인

​OpenProse

​안전성

​문제 해결

​자세히 알아보기

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

​관련 항목

필요한 이유

작동 방식

활성화

패턴: 소형 CLI + JSON 파이프 + 승인

JSON 전용 LLM 단계(llm-task)

중요 제한 사항: 임베디드 Lobster와 `openclaw.invoke`

워크플로 파일(.lobster)

도구 매개변수

`run`

`resume`

관리형 Task Flow 모드

출력 봉투

승인

OpenProse

안전성

문제 해결

자세히 알아보기

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

관련 항목