@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

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:

{
  "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:

{
  "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:

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

   openclaw senpi runtime create -p ~/my-recipe.yaml

4. List recipes:

   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.

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 for the full install sequence, config stanza, and troubleshooting.

Docs

• Architecture
• Skills YAML schema
• Integration guide
• Runtime API

Changelog

CHANGELOG.md

Development

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 and docs/runtime-docs/ for conventions and design.