lobster-shell

OpenClaw plugin (@simplaix/lobster-shell) for Simplaix Gateway — tool policy evaluation, audit logging, and mobile approval pairing.

Every tool call made by an OpenClaw agent is intercepted:

1. Before execution — calls /api/v1/tool-gate/evaluate to check policy. The Gateway may allow, deny, or require_confirmation (human-in-the-loop). Denied or rejected calls are blocked before the tool runs.
2. After execution — calls /api/v1/tool-gate/audit to record the result, error status, and duration.

The plugin registers a /pair command that generates a deep link for the Simplaix mobile approval app. If the Gateway is unreachable, the plugin fails open (tool calls proceed with a warning).

How it works

Policy evaluation

Agent calls tool
       │
       ▼
  POST /api/v1/tool-gate/evaluate
       │
       ├─ allow       → tool executes
       ├─ confirmed   → tool executes (human approved)
       ├─ denied      → BLOCKED (policy violation)
       ├─ rejected    → BLOCKED (human rejected)
       ├─ timeout     → BLOCKED (approval timed out)
       └─ unreachable → tool executes (fail-open)

Audit logging

Tool execution completes
       │
       ▼
  POST /api/v1/tool-gate/audit  (fire-and-forget)
       │
       └─ Updates pending record with result, durationMs, status

Pairing (/pair command)

User sends /pair
  → Plugin calls POST /api/v1/auth/pairing-code
  → Gateway returns { token, deepLink }
  → User taps link → mobile app opens → device registered for push notifications

Agent identity

The plugin sends the art_xxx token as Authorization: Bearer art_xxx. The Gateway resolves the agent identity from this token — no agentId is sent in request bodies.

Setup

No Docker or PostgreSQL required — the gateway uses SQLite by default.

1. Install the gateway

npm install -g @simplaix/simplaix-gateway

2. Create a workspace and initialise

mkdir my-gateway && cd my-gateway
gateway init

gateway init generates a .env with auto-generated secrets.

3. Start the gateway + dashboard

# With public tunnel + dashboard UI (recommended)
gateway start --tunnel --dashboard

# Or local-only
gateway start --dashboard

This starts:

• Gateway on http://localhost:7521
• Dashboard UI on http://localhost:3000
• Python agent on http://localhost:8000
• Cloudflare tunnel (if --tunnel) → prints public HTTPS URL

4. Create an admin user

gateway admin create --email [email protected] --password yourpassword

5. Get an admin JWT

ADMIN_JWT=$(curl -s -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"yourpassword"}' \
  | jq -r '.token')

6. Register an agent and capture runtime_token

curl -s -X POST http://localhost:7521/api/v1/admin/agents \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-openclaw-agent",
    "upstreamUrl": "http://localhost:8000",
    "description": "OpenClaw agent with policy enforcement"
  }' | jq .

Save the runtime_token (art_xxx) — it is shown once.

7. Seed policies and capture PROVIDER_ID

ADMIN_JWT="$ADMIN_JWT" AGENT_ID="<agent.id>" bash \
  $(npm root -g)/@simplaix/simplaix-gateway/../lobster-shell/seed-openclaw-policies.sh

Or if you have the repo cloned:

ADMIN_JWT="$ADMIN_JWT" AGENT_ID="<agent.id>" bash seed-openclaw-policies.sh

8. Configure ~/.openclaw/openclaw.json

{
  "plugins": {
    "entries": {
      "lobster-shell": {
        "enabled": true,
        "config": {
          "gatewayUrl": "http://localhost:7521",
          "providerId": "<PROVIDER_ID>",
          "timeoutMs": 310000,
          "skipTools": []
        }
      }
    }
  },
  "env": {
    "vars": {
      "SIMPLAIX_AGENT_RUNTIME_TOKEN": "<art_xxx>"
    }
  }
}

9. Install the plugin

openclaw plugins install @simplaix/lobster-shell

10. Guide users to /pair

Share the dashboard URL (http://localhost:3000 or the public tunnel URL printed by --tunnel). Users send /pair in WhatsApp/Telegram, tap the returned link, and the mobile approval app connects.

Verify

• /api/health returns healthy
• Plugin initialization log: [simplaix-gateway] Policy & Audit plugin initialized
• Tool calls hit evaluate and audit endpoints
• High-risk tools trigger mobile confirmation
• Users can pair successfully

Configuration reference

Plugin config (openclaw.json → plugins.entries.lobster-shell.config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | gatewayUrl | string | required | Gateway base URL (e.g. http://localhost:7521) | | providerId | string | "lobster-shell" | Provider ID for policy evaluation | | timeoutMs | number | 310000 | HTTP timeout (ms) for evaluate endpoint | | skipTools | string[] | [] | Tool names to skip (no policy check, no audit) |

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | SIMPLAIX_AGENT_RUNTIME_TOKEN | Yes | Agent runtime token (art_xxx) from step 6 | | SIMPLAIX_GATEWAY_URL | No | Alternative to gatewayUrl in config |

OpenClaw hook notes

• OpenClaw may call register() twice; the plugin guards against duplicate registration.
• after_tool_call fires twice per execution — the plugin only sends the audit on the second (complete) invocation that includes durationMs.
• after_tool_call context lacks sessionKey, so toolName is used as the correlation key.

Files

lobster-shell/
  package.json                  # @simplaix/lobster-shell
  openclaw.plugin.json          # Plugin manifest (config schema, UI hints)
  index.ts                      # Entry point (hooks + commands)
  seed-openclaw-policies.sh     # Seeds default tool policies
  skills/                       # Agent setup skills
  README.md

License

See the Simplaix Gateway repository license.