npm package: @launchthatbot/connect-openclaw-plugin
Description: LaunchThatBot-native OpenClaw connect plugin for external and managed deployments.
Latest version: 0.2.2

# @launchthatbot/connect-openclaw-plugin

LaunchThatBot-native OpenClaw connect plugin for external and LaunchThatBot-managed deployments.

This package complements (not replaces) `launchthat-openclaw-connector`:

- `launchthat-openclaw-connector`: telemetry-only connector path.
- `@launchthatbot/connect-openclaw-plugin`: plugin path with parity-oriented tools/methods and staged feature flags.

## Features

- Connect pairing helpers:
  - `launchthatbot.connect.begin`
  - `launchthatbot.connect.complete`
  - `launchthatbot.connect.status`
  - `launchthatbot.connect.disconnect`
- Core gateway methods:
  - `tools.list`
  - `tools.invoke` (plugin tools only)
- Read-only tool set (phase 1):
  - `fs_read`
  - `fs_list`
  - `entity_list`
  - `entity_search`
  - `entity_sync`
- Gated mutation features (phase 2, off by default):
  - `fs_mkdir`
  - `fs_write`
  - `fs_rename`
  - `fs_delete`
  - `sql_query`

## Install

```bash
openclaw plugins install @launchthatbot/connect-openclaw-plugin
```

## Config

- `launchthatbotApiBaseUrl`: LaunchThatBot Convex HTTP base URL (default: `https://api.ltb.it.com`).
- `presence.wsUrl`: Presence relay websocket URL (default: `<launchthatbotApiBaseUrl>/ws`).
- `presence.beatIntervalMs`: Presence beat interval in milliseconds (default: `60000`).
- `workspaceId`: workspace id (external mode).
- `instanceName`: display name for connected instance.
- `deploymentMode`: `external` or `managed`.
- `managed.serverId`: required in managed mode.
- `fs.allowedRoots`: allowed filesystem roots.
- `features.enableMutations`: default `false`.
- `features.enableSqlQuery`: default `false`.
- `bootstrap.syncPackagedSkills`: default `true`; syncs bundled `skills/` into `~/.openclaw/workspace/skills`.

Pairing flow:

1. Run `launchthatbot.connect.begin`
2. Open returned `authUrl` and sign in to LaunchThatBot
3. Plugin automatically completes linking once authorization is approved
4. Optional fallback: run `launchthatbot.connect.complete` (no args) to force completion using stored pairing state
5. Disconnect and clear local plugin state: `launchthatbot.connect.disconnect`

## Presence transport (v2)

After pairing succeeds, the plugin opens an outbound websocket to `presence.wsUrl` and maintains liveness by sending periodic `beat` messages.

- handshake uses nonce challenge + `sha256(nonce + ingestToken)` proof
- beats are rate-limited by the relay
- relay forwards authenticated presence updates to LaunchThatBot Convex (`/api/openclaw/ws/presence`)
- instance status in LaunchThatBot admin is driven by these websocket presence updates

## Skill bootstrap sync

This plugin bundles a companion skill at `skills/connect-openclaw/SKILL.md`.

On plugin load, it automatically syncs bundled skills into:

- `~/.openclaw/workspace/skills/<skill-name>`

Behavior:

- idempotent copy (unchanged files are skipped)
- additive (does not delete extra local files)
- opt-out via config: `bootstrap.syncPackagedSkills=false`

## Polling behavior

The plugin polls connect status every 3 seconds after pairing starts.
To avoid endless status traffic, polling is bounded:

- stops when connect succeeds
- stops when challenge expires/consumed
- stops after 120 attempts (about 6 minutes), then clears pending challenge state

## Security model

- Restricted filesystem roots.
- Hard-blocked sensitive paths (`credentials`, `devices`, `identity`) and sensitive files.
- OpenClaw config redaction for common auth token fields.
- Mutation and SQL capabilities are disabled by default behind explicit feature flags.

## Development

```bash
pnpm --filter @launchthatbot/connect-openclaw-plugin typecheck
pnpm --filter @launchthatbot/connect-openclaw-plugin build
```