Skip to content

LeoYeAI/agent-master-skills / skills/bengii-gemini-fix

openclaw

Flagged

Comprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.

FileKindSize
README.mdmarkdown7.5 KB
README_CN.mdmarkdown7.3 KB
SKILL.mdskill md18.7 KB
_meta.jsonconfig286 B
references/acp_agents.mdmarkdown12.6 KB
references/agent_runtime.mdmarkdown5.6 KB
references/architecture.mdmarkdown3.8 KB
references/automation.mdmarkdown5.8 KB
references/bonjour.mdmarkdown3.3 KB
references/browser.mdmarkdown8.5 KB
references/channel_routing.mdmarkdown4.0 KB
references/channel_troubleshooting.mdmarkdown11.6 KB
references/channels.mdmarkdown6.2 KB
references/clawhub.mdmarkdown3.6 KB
references/config_reference.mdmarkdown11.2 KB
references/diffs_firecrawl.mdmarkdown3.3 KB
references/elevated.mdmarkdown2.8 KB
references/exec.mdmarkdown6.5 KB
references/exec_approvals.mdmarkdown3.1 KB
references/gateway_internals.mdmarkdown7.7 KB
references/gateway_ops.mdmarkdown9.6 KB
references/heartbeat.mdmarkdown4.9 KB
references/hooks.mdmarkdown14.6 KB
references/install.mdmarkdown4.1 KB
references/llm_task.mdmarkdown2.6 KB
references/lobster.mdmarkdown7.8 KB
references/media.mdmarkdown4.2 KB
references/memory.mdmarkdown11.9 KB
references/model_failover.mdmarkdown3.1 KB
references/multi_agent.mdmarkdown4.4 KB
references/nodes.mdmarkdown8.8 KB
references/openprose.mdmarkdown2.6 KB
references/pairing.mdmarkdown3.1 KB
references/pdf_tool.mdmarkdown3.5 KB
references/platforms.mdmarkdown2.7 KB
references/plugins.mdmarkdown6.9 KB
references/polls.mdmarkdown2.2 KB
references/presence_discovery.mdmarkdown2.2 KB
references/providers.mdmarkdown6.0 KB
references/queue.mdmarkdown2.1 KB
references/remote_access.mdmarkdown4.7 KB
references/sandboxing.mdmarkdown5.6 KB
references/secrets.mdmarkdown5.4 KB
references/security.mdmarkdown24.5 KB
references/sessions.mdmarkdown8.9 KB
references/skills.mdmarkdown4.4 KB
references/slash_commands.mdmarkdown5.1 KB
references/streaming.mdmarkdown1.8 KB
references/subagents.mdmarkdown12.3 KB
references/thinking.mdmarkdown2.8 KB
references/tools.mdmarkdown13.3 KB
references/tui.mdmarkdown4.0 KB
references/voice.mdmarkdown2.7 KB
references/web_tools.mdmarkdown2.7 KB
references/web_ui.mdmarkdown4.5 KB

references/lobster.md

View on GitHub
# Lobster — Typed Workflow Runtime

Lobster is a typed workflow runtime for OpenClaw that lets agents run composable pipelines with built-in approval gates. One tool call replaces many, with resumable state and deterministic execution.

## Why Lobster

- **One call instead of many**: OpenClaw runs one Lobster tool call and gets a structured result.
- **Approvals built in**: Side effects (send email, post comment) halt the workflow until explicitly approved.
- **Resumable**: Halted workflows return a `resumeToken`; approve and resume without re-running everything.

## Why a DSL Instead of Plain Programs

- **Approve/resume built in**: Normal programs can't pause and resume with a durable token without custom runtime.
- **Determinism + auditability**: Pipelines are data — easy to log, diff, replay, and review.
- **Constrained surface for AI**: Tiny grammar + JSON piping reduces "creative" code paths.
- **Safety policy baked in**: Timeouts, output caps, sandbox checks, and allowlists enforced by runtime.
- **Still programmable**: Each step can call any CLI or script. Generate `.lobster` files from code if needed.

## How It Works

1. Agent calls `lobster` tool with `action: "run"` and a `pipeline` string (inline or `.lobster` file path).
2. Lobster CLI executes the pipeline.
3. If a step requires approval, the tool returns `status: "needs_approval"` with a `resumeToken`.
4. Agent presents the approval to the user and calls `action: "resume"` with the token.

## Install Lobster

1. Get the Lobster CLI from [Lobster repo](https://github.com/openclaw/lobster).
2. Ensure `lobster` is on `PATH`.

## Enable the Tool

Global:

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

Per-agent:

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

Note: `tools.allow: ["lobster"]` also works but replaces the default set.

## Workflow Files (.lobster)

`.lobster` files define named, reusable workflows with typed args and steps.

**Fields**:
- `name` — workflow name
- `args` — named arguments with optional defaults
- `steps` — ordered list of steps
- `env` — environment variables (optional)
- `condition` / `when` — gate steps on prior results
- `approval` — mark steps requiring human approval
- `pipeline` — inline pipeline string (alternative to steps)

**Example — inbox triage**:

```yaml
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
```

**Piping**:
- `stdin: $step.stdout` and `stdin: $step.json` pass a prior step's output.
- `condition` (or `when`) can gate steps on `$step.approved`.

## Pattern: Small CLI + JSON Pipes + Approvals

Compose small CLIs that produce JSON, pipe them together, and gate side effects with `approve`:

```json5
// Inline pipeline
{
  "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
}
```

Resume after approval:

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

Cross-tool piping example:

```
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)

Use `llm-task` plugin inside Lobster for structured LLM output:

1. Enable the plugin:

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

2. Invoke inside a pipeline:

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

See [LLM Task](llm_task.md) for full parameter reference.

## Tool Parameters

### run

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

Run a `.lobster` file with args:

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

### resume

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

### Optional Inputs

| Parameter | Default | Description |
|---|---|---|
| `cwd` | process cwd | Working directory (must stay within cwd) |
| `timeoutMs` | 20000 | Kill subprocess if exceeded |
| `maxStdoutBytes` | 512000 | Kill subprocess if stdout exceeds this |
| `argsJson` | — | JSON string passed to `lobster run --args-json` (workflow files only) |

## Output Envelope

| Status | Meaning |
|---|---|
| `ok` | Finished successfully |
| `needs_approval` | Paused; `requiresApproval.resumeToken` needed to resume |
| `cancelled` | Explicitly denied or cancelled |

Output fields: `content` (result data), `details` (metadata).

## Approvals

When a step returns `requiresApproval`:

- `approve: true` → resume and continue side effects
- `approve: false` → cancel and finalize the workflow

Use `approve --preview-from-stdin --limit N` to show a preview before approval.

## OpenProse Integration

The `/prose` slash command can compile to `lobster` pipelines. OpenProse programs that use `tools.subagents.tools` map to Lobster tool invocations.

See [OpenProse](openprose.md).

## Safety

- **Local subprocess only** — no network calls from the plugin itself.
- **No secrets** — Lobster doesn't manage OAuth; it calls OpenClaw tools that do.
- **Sandbox-aware** — disabled when the tool context is sandboxed.
- **Hardened** — fixed executable name (`lobster`) on `PATH`; timeouts and output caps enforced.

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| `lobster subprocess timed out` | Pipeline takes too long | Increase `timeoutMs` or split pipeline |
| `lobster output exceeded maxStdoutBytes` | Too much output | Raise `maxStdoutBytes` or reduce output |
| `lobster returned invalid JSON` | Pipeline prints non-JSON | Ensure tool mode; print only JSON |
| `lobster failed (code …)` | Step error | Run the pipeline in a terminal to inspect stderr |

## Example: Email Triage

Without Lobster (manual multi-step):
```
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)
```

With Lobster (single tool call):

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

Returns:

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

Resume:

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

## Case Study: Community Workflows

Popular community workflow patterns: `weekly-review`, `inbox-triage`, `memory-consolidation`, `shared-task-sync`.

- Thread: https://x.com/plattenschieber/status/2014508656335770033
- Repo: https://github.com/bloomedai/brain-cli

## Learn More

- [Plugins](plugins.md)
- [LLM Task](llm_task.md)
- [OpenProse](openprose.md)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall