Lobster

Lobsterは、OpenClawがマルチステップのツールシーケンスを、明示的な承認チェックポイント付きの単一の決定的操作として実行できるワークフローシェルです。

導入

アシスタント自身が自分を管理するツールを構築できます。ワークフローを依頼すれば、30分後にはCLIとパイプラインが一つの呼び出しで動きます。Lobsterはそのミッシングピース——決定的なパイプライン、明示的な承認、再開可能なステートを提供します。

なぜLobsterが必要か

現状、複雑なワークフローには多くのツール呼び出しの往復が必要です。呼び出しごとにトークンがかかり、LLMがすべてのステップをオーケストレーションしなければなりません。Lobsterはそのオーケストレーションを型付きランタイムに移行します:

• 多数の呼び出しが一度に: OpenClawはLobsterの1回のツール呼び出しで構造化された結果を取得。
• 承認の組み込み: 副作用（メール送信、コメント投稿）が発生する箇所でワークフローを停止し、明示的な承認を待機。
• 再開可能: 停止したワークフローはトークンを返し、承認後に最初からやり直すことなく再開。

なぜプレーンなプログラムではなくDSLか?

Lobsterは意図的にコンパクトです。目的は「新しい言語」ではなく、ファーストクラスの承認と再開トークンを備えた、予測可能なAI対応パイプライン仕様です。

• 承認/再開が組み込み: 通常のプログラムでも人間に確認は取れますが、永続的なトークンによる_一時停止と再開_は、そのランタイムを自前で構築しなければ実現できません。
• 決定性＋監査可能性: パイプラインはデータなので、ログ記録、差分比較、リプレイ、レビューが容易。
• 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 Taskを参照してください。

ワークフローファイル（.lobster）

LobsterはYAML/JSONワークフローファイルを実行でき、name、args、steps、env、condition、approvalフィールドに対応しています。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 Gatewayを実行している同じホストに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は3つのステータスのいずれかを含むJSONエンベロープを返します:

• ok → 正常完了
• needs_approval → 一時停止中。再開にはrequiresApproval.resumeTokenが必要
• cancelled → 明示的に拒否またはキャンセルされた

ツールはエンベロープをcontent（整形されたJSON）とdetails（生のオブジェクト）の両方で公開します。

承認

requiresApprovalが存在する場合、プロンプトを確認して判断します:

• approve: true → 再開して副作用を続行
• approve: false → キャンセルしてワークフローを終了

approve --preview-from-stdin --limit Nを使って、カスタムのjq/ヒアドキュメントなしでJSONプレビューを承認リクエストに添付できます。再開トークンはコンパクト化されました。Lobsterはステートディレクトリにワークフロー再開ステートを保存し、小さなトークンキーを返します。

OpenProse

OpenProseはLobsterと相性が良い組み合わせです。/proseでマルチエージェントの準備をオーケストレーションし、決定的な承認にはLobsterパイプラインを実行します。ProseプログラムがLobsterを必要とする場合、tools.subagents.toolsでサブエージェントにlobsterツールを許可してください。OpenProseを参照。

セーフティ

• ローカルサブプロセスのみ — プラグイン自体からネットワーク呼び出しは行いません。
• シークレットなし — LobsterはOAuthを管理しません。OAuthを管理するOpenClawツールを呼び出します。
• サンドボックス対応 — ツールコンテキストがサンドボックス化されている場合は無効化。
• 堅牢化 — 固定の実行可能ファイル名（lobster）をPATHから使用。タイムアウトと出力上限を強制。

トラブルシューティング

• lobster subprocess timed out → timeoutMsを増やすか、長いパイプラインを分割。
• lobster output exceeded maxStdoutBytes → maxStdoutBytesを増やすか、出力サイズを削減。
• lobster returned invalid JSON → パイプラインがツールモードで実行され、JSONのみを出力していることを確認。
• lobster failed (code …) → ターミナルで同じパイプラインを実行してstderrを確認。

関連ドキュメント

• プラグイン
• プラグインツールの作成

ケーススタディ: コミュニティワークフロー

公開例の一つ: 3つの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