Lobster

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

フック

アシスタントは、自分自身を管理するツールを構築できます。ワークフローを依頼すると、30 分後には 1 回の呼び出しで実行されるパイプラインと CLI が完成します。Lobster はその欠けているピースです：決定論的パイプライン、明示的な承認、再開可能な状態。

理由

今日、複雑なワークフローは多くの往復ツール呼び出しを必要とします。各呼び出しはトークンを消費し、LLM はすべてのステップを調整する必要があります。Lobster はそのオーケストレーションを型付きランタイムに移行します：

  • 多くの呼び出しではなく 1 回の呼び出し: OpenClaw は 1 回の Lobster ツール呼び出しを実行し、構造化された結果を取得します。
  • 組み込まれた承認: 副作用（メール送信、コメント投稿）は明示的に承認されるまでワークフローを停止します。
  • 再開可能: 停止されたワークフローはトークンを返します。承認して、すべてを再実行せずに再開します。

なぜ通常のプログラムではなく 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.",
  "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 ツール呼び出しでは、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 にあることを確認してください。 カスタムバイナリの場所を使用する場合は、ツール呼び出しで 絶対 lobsterPath を渡します。

ツールの有効化

Lobster は オプション のプラグインツールです（デフォルトでは有効になっていません）。

推奨（追加、安全）：

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

またはエージェントごと：

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

制限的な許可リストモードで実行する意図がない限り、tools.allow: ["lobster"] の使用は避けてください。

注意：許可リストはオプションのプラグインに対してオプトインです。許可リストがプラグインツール（lobster など）のみを指定している場合、OpenClaw はコアツールを有効に保ちます。コアツールを制限するには、必要なコアツールまたはグループも許可リストに含めてください。

例：メールのトリアージ

Lobster なし：

ユーザー：「メールをチェックして返信を下書きして」
→ openclaw が gmail.list を呼び出す
→ LLM が要約
→ ユーザー：「#2 と #5 に返信を下書きして」
→ LLM がドラフト
→ ユーザー：「#2 を送信」
→ openclaw が gmail.send を呼び出す
（毎日繰り返し、トリアージされたものの記憶なし）

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
}

1 つのワークフロー。決定論的。安全。

ツールパラメータ

run

ツールモードでパイプラインを実行します。

{
  "action": "run",
  "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
  "cwd": "/path/to/workspace",
  "timeoutMs": 30000,
  "maxStdoutBytes": 512000
}

引数を指定してワークフローファイルを実行します：

{
  "action": "run",
  "pipeline": "/path/to/inbox-triage.lobster",
  "argsJson": "{\"tag\":\"family\"}"
}

resume

承認後に停止されたワークフローを続行します。

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

オプション入力

  • lobsterPath: Lobster バイナリへの絶対パス（PATH を使用する場合は省略）。
  • 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 → キャンセルしてワークフローを確定

カスタム jq/heredoc グルーなしで JSON プレビューを承認リクエストに添付するには、approve --preview-from-stdin --limit N を使用します。再開トークンはコンパクトになりました：Lobster はワークフロー再開状態をその状態ディレクトリに保存し、小さなトークンキーを返します。

OpenProse

OpenProse は Lobster とうまく組み合わせられます：/prose を使用してマルチエージェントの準備を調整し、次に Lobster パイプラインを実行して決定論的な承認を行います。Prose プログラムが Lobster を必要とする場合は、tools.subagents.tools 経由でサブエージェントに lobster ツールを許可します。OpenProse を参照してください。

安全性

  • ローカルサブプロセスのみ — プラグイン自体からのネットワーク呼び出しはありません。
  • シークレットなし — Lobster は OAuth を管理しません。それを行う OpenClaw ツールを呼び出します。
  • サンドボックス対応 — ツールコンテキストがサンドボックス化されている場合は無効になります。
  • 強化済み — 指定された場合、lobsterPath は絶対パスである必要があります。タイムアウトと出力上限が強制されます。

トラブルシューティング

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

詳細

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

公開例の 1 つ：3 つの Markdown ボールト（個人用、パートナー用、共有）を管理する「セカンドブレイン」CLI + Lobster パイプライン。CLI は統計、受信トレイリスト、古いスキャンのために JSON を発行します。Lobster はこれらのコマンドを weekly-review、inbox-triage、memory-consolidation、shared-task-sync などのワークフローにチェーンし、それぞれに承認ゲートがあります。AI は利用可能な場合は判断（分類）を処理し、そうでない場合は決定論的ルールにフォールバックします。

← ドキュメントに戻る