npm package: @senpi/runtime
Description: Senpi runtime plugin for OpenClaw
Latest version: 1.0.95-dev.20260409192509

# @senpi-ai/runtime

[![npm version](https://img.shields.io/npm/v/@senpi-ai/runtime.svg)](https://www.npmjs.com/package/@senpi-ai/runtime)

Event-driven automated trading plugin for OpenClaw. Orchestrates scanners, LLM-based trade decisions, and a DSL trailing stop-loss exit engine.

## Prerequisites

- **OpenClaw** >= 2026.2.0
- **Node** >= 22
- **Senpi API key** (for live trading)

## Install

```bash
openclaw plugins install @senpi-ai/runtime
```

## Configure

Add the plugin to your OpenClaw config (e.g. `~/.openclaw/openclaw.json` or via `openclaw config set`). Use the plugin **id** `@senpi-ai/runtime` as the key:

```json
{
  "plugins": {
    "entries": {
      "@senpi-ai/runtime": {
        "enabled": true,
        "config": {
          "stateDir": "~/.openclaw/senpi-state",
          "apiKey": "YOUR_SENPI_API_KEY"
        }
      }
    }
  }
}
```

## Notifications

- **Strategy-level:** Set `notifications.telegram_chat_id` in your strategy YAML to receive alerts (e.g. open/close, decision errors, scanner watchdog). The plugin sends messages via the OpenClaw gateway `message` tool (`action: send`, `target: telegram:<chatId>`).
- **Lifecycle (plugin start/stop):** Set `SENPI_LIFECYCLE_TELEGRAM_CHAT_ID` in the **gateway** environment (e.g. in Docker: add to `docker-compose` and `.env`) to receive "Senpi started. Strategy running." when the plugin service starts and "Senpi shutting down." when it stops. Requires `OPENCLAW_GATEWAY_TOKEN` (and optionally `OPENCLAW_GATEWAY_URL`) in the same environment.

## Auto-update

Auto-update is **enabled by default** (opt-out). When a new minor or patch version is published to npm, the plugin will install it automatically and attempt to restart the OpenClaw gateway so the new code takes effect.

- **Major versions** are never auto-installed. A Telegram notification is sent instead, asking you to review the changelog and update manually.
- **Default mode:** `auto-apply` — the plugin polls every 6 hours, installs the update, and triggers a gateway restart.
- **Gateway restart** requires `gateway.reload.mode` set to `restart` or `hybrid` in your OpenClaw config. If the mode is `hot` or `off`, or the config helpers are unavailable, the plugin will send a notification asking you to restart the gateway manually.

To customise or disable auto-update, add an `autoUpdate` block to the plugin config:

```json
{
  "plugins": {
    "entries": {
      "runtime": {
        "enabled": true,
        "config": {
          "autoUpdate": {
            "mode": "notify-only",
            "pollIntervalMinutes": 720
          }
        }
      }
    }
  }
}
```

Set `"enabled": false` inside the `autoUpdate` block to disable it entirely.

**Known limitation:** If the gateway cannot be restarted automatically (wrong reload mode or missing config access), runtimes that were stopped for the update remain stopped until you restart the gateway manually.

## Quickstart

1. Copy a minimal recipe template and set your wallet:
   ```bash
   cp $(openclaw plugins path @senpi-ai/runtime)/examples/strategies/minimal.yaml ~/my-recipe.yaml
   # Edit my-recipe.yaml: replace ${WALLET_ADDRESS} or set WALLET_ADDRESS in env
   ```

2. Set environment variables (e.g. `.env`): `SENPI_API_KEY`, `WALLET_ADDRESS`.

3. Load the recipe (hot-loads; no gateway restart):
   ```bash
   openclaw senpi runtime create -p ~/my-recipe.yaml
   ```

4. List recipes:
   ```bash
   openclaw senpi runtime list
   ```

5. Watch gateway logs for scanner runs and signal processing.

## Strategy templates

| File | Style | Scanners | Use case |
|------|-------|----------|----------|
| minimal.yaml | Watch-only | emerging_movers | Verify setup; no positions |
| wolf.yaml | Aggressive | emerging_movers | Early entry on FIRST_JUMP |
| viper.yaml | Moderate | prescreener + momentum | Candle-based breakouts |
| fox.yaml | OI-driven | prescreener + oi_tracker | OI-driven entries |
| dsl-showcase.yaml | DSL reference | emerging_movers | Annotated exit config |

Templates live under `examples/strategies/` in the package. See [examples/strategies/README.md](examples/strategies/README.md).

## CLI reference

**Runtime recipes:**
- `openclaw senpi runtime create -p <path>` — create from YAML file (hot-load)
- `openclaw senpi runtime create -c "<yaml>"` — create from inline YAML
- `openclaw senpi runtime list` — list installed runtimes
- `openclaw senpi runtime delete <runtime_id>` — remove by id

**In-shell reference:**
- `openclaw senpi guide` — overview
- `openclaw senpi guide scanners` — scanner types and config fields
- `openclaw senpi guide actions` — action types and decision modes
- `openclaw senpi guide dsl` — DSL two-phase exit engine
- `openclaw senpi guide examples` — print minimal strategy YAML
- `openclaw senpi guide schema` — full YAML schema
- `openclaw senpi guide version` — plugin version and changelog URL

## Guide skill

Once published, the **@senpi-guide** skill on ClawHub provides the same reference in chat. Install with `clawhub install skills/senpi-guide/` (or from the ClawHub UI).

## Install on an existing OpenClaw setup

If you already have OpenClaw installed (local, VPS, or self-hosted), see [Installing on existing OpenClaw](docs/install/existing-openclaw.md) for the full install sequence, config stanza, and troubleshooting.

## Docs

- [Architecture](docs/runtime-docs/design/architecture.md)
- [Skills YAML schema](docs/runtime-docs/design/skills-yaml-schema.md)
- [Integration guide](docs/runtime-docs/integration-guide.md)
- [Runtime API](docs/runtime-docs/runtime-api.md)

## Changelog

[CHANGELOG.md](CHANGELOG.md)

## Development

```bash
npm run build            # install deps + compile TypeScript (excludes *.test.ts)
npm run typecheck:tests  # typecheck all src including tests (no emit)
npm test                 # unit + integration tests (no credentials required)
npm run dev              # build + run
```

Pre-commit runs `npm run build`, `npm run typecheck:tests`, and `npm test`. See [CLAUDE.md](CLAUDE.md) and [docs/runtime-docs/](docs/runtime-docs/) for conventions and design.