SkillHub

tbot-controller

v1.0.0

Operate TradingBoat/TBOT (TBOT runtime stack) via a controlled automation interface (DB-first queries; lifecycle control on explicit request).

Sourced from ClawHub, Authored by PlusGenie

Installation

Please help me install the skill `tbot-controller` from SkillHub official store. npx skills add PlusGenie/tbot-controller

What this skill does

  • Query TBOT sqlite DB for alerts/orders/errors/portfolio (DB-first)
  • Start/stop TradingBoat/TBOT (docker compose or systemd)
  • Fetch health/status (containers, ports, basic checks) only when explicitly requested
  • Read recent logs only when explicitly requested

Safety rules

  • Default to read-only operations (status/logs) unless user explicitly requests a control action.
  • For any state-changing action (start/stop/restart/send), require explicit confirmation via the flag --run-it or environment variable RUN_IT=1. The controller will refuse execution otherwise.
  • Never print secrets (webhook keys, tokens). Redact them.

Refusal criteria (must-stop conditions)

The agent MUST stop and ask for user action if any of the following is true: - Runtime location is unknown and discovery cannot uniquely resolve it. - The TBOT database path cannot be found or opened read-only. - A request would start/stop/restart services or send signals without --run-it / RUN_IT=1. - A request implies destructive DB changes (DROP/TRUNCATE/ALTER) or “run arbitrary SQL”.

Prerequisites (first-time users)

This skill controls a separate TBOT runtime stack. The reference/runtime implementation is:

  • openclaw-on-tradingboat (TBOT runtime stack): https://github.com/PlusGenie/openclaw-on-tradingboat

This tbot-controller skill does not download or install the runtime for you. If the runtime is missing, the skill will run read-only DB helpers where possible, but status/logs/control actions will fail until the runtime exists.

1) Clone the runtime repo:

git clone https://github.com/PlusGenie/openclaw-on-tradingboat.git
cd openclaw-on-tradingboat

2) Ensure you can start it manually (outside this skill). For Docker Compose based installs, this typically means:

docker compose up -d

3) Tell this skill where the runtime lives (recommended):

  • Set TBOT_COMPOSE_DIR to the folder that contains docker-compose.yml or compose.yaml.

Examples:

export TBOT_COMPOSE_DIR="$HOME/develop/github/openclaw-on-tradingboat"

Or add it to ~/.openclaw/.env / your skill env block in openclaw.json.

Configure runtime secrets (outside this skill)

  • TBOT typically uses a .env file for broker credentials and webhook keys.
  • Do not commit secrets to git.
  • If you are unsure whether the runtime is set to paper or live, this skill must refuse to execute any trade/action until you confirm which it is.

Install / script permissions

This skill is invoked via a bash entrypoint script. Ensure it is executable:

chmod +x scripts/tbot.sh

Python deps (OpenClaw-native)

This skill uses uv to run Python scripts in an isolated environment and auto-install dependencies from: - {baseDir}/scripts/requirements.txt

Install uv (macOS):

brew install uv

ClawHub packaging note: if you publish this skill, ensure scripts/ (including requirements.txt) is included at the root of the repo.

IMPORTANT: DB-first, discovery only for status/control

DB queries do NOT require discovery. Discovery is required only before status/logs/control actions.

OpenClaw must NOT hardcode old paths like ~/ib-gateway-docker.

Always prefer discovery output (usually pointing to openclaw-on-tradingboat).

Commands

Entry point (required)

OpenClaw MUST invoke this skill via:

bash scripts/tbot.sh <mode> <args...>

Valid modes: - ctl — operations control (docker/systemd) - json — JSON signal generation (schema-validated) and send to TBOT webhook (non-interactive) - status — read-only inspection (probe & discovery)

OpenClaw must never call python tbot*.py directly.

Probe & Discovery (read-only, only for status/control)

When the user says “open TBOT”, “start TBOT”, “TBOT status”, etc., OpenClaw should:

1) Try discovery first (read-only):

bash scripts/tbot.sh status discover

This step is mandatory because the compose folder may change over time (for example migrating from ib-gateway-docker to openclaw-on-tradingboat).

2) If discovery returns a resolved runtime, run ctl commands by injecting env vars:

  • Docker example:
MODE=docker COMPOSE_DIR="<compose_dir>" bash scripts/tbot.sh ctl status

Example expected compose folder:

~/develop/github/openclaw-on-tradingboat>
  • systemd example:
MODE=systemd SERVICE_NAME="<service_name>" SYSTEMD_USER="<0|1>" bash scripts/tbot.sh ctl status

3) Only if discovery cannot resolve a single runtime, ask one precise question: - Docker Compose: “What is the folder containing docker-compose.yml/compose.yaml? (Usually this is the tbot-runtime (example) folder.)” - systemd: “What is the service name (and is it --user)?”

Notes: - Discovery must remain read-only (no starting/stopping). - Use discovery output as the authoritative suggestion for MODE/COMPOSE_DIR/SERVICE_NAME.

Why this matters

If OpenClaw skips discovery, it may incorrectly report TBOT as DOWN because it is checking an obsolete compose folder.

Status (read-only, only if requested)

bash scripts/tbot.sh ctl status
bash scripts/tbot.sh ctl logs --tail 200

Note: With tbot-runtime (example), docker compose typically brings up three containers: ib-gateway-on-tradingboat (gnzsnz/ib-gateway), redis-on-tradingboat, and tbot-on-tradingboat.

Internally: - Docker: docker compose ps, docker compose logs --tail=200 - systemd: systemctl --user status <service>, journalctl --user -u <service> -n 200

Control (explicit confirmation required)

bash scripts/tbot.sh ctl start --run-it
bash scripts/tbot.sh ctl stop --run-it
bash scripts/tbot.sh ctl restart --run-it

Tip: Use MODE=docker + COMPOSE_DIR pointed at tbot-runtime (example) to control the stack via docker compose.

Internally: - Docker: docker compose up -d, docker compose down - systemd: systemctl --user start <service>, systemctl --user stop <service>

JSON signal generation (generate + send)

json mode is non-interactive by design. OpenClaw MUST NOT ask the user for webhook details or trading intent if they can be inferred.

Inference rules: - Webhook URL default: http://127.0.0.1:5001/webhook (override with TBOT_WEBHOOK_URL) - Webhook key is read from the TBOT runtime .env by default (override with WEBHOOK_KEY) - orderRef is auto-generated when omitted - Natural language like close 50 NFLX implies strategy.close, contract=stock, qty=50

json mode generates a schema-valid TradingView-style payload and sends it to TBOT via webhook.

Defaults / inference rules (do not ask the user): - Webhook URL: default http://127.0.0.1:5001/webhook (override with TBOT_WEBHOOK_URL). - Webhook key: read from runtime .env (override with WEBHOOK_KEY). - orderRef: if not provided, auto-generate Close_<TICKER>_<QTY>_<epoch_ms>. - Close intent: inferred automatically; do not prompt the user.

# Example (user: “close 50 NFLX now”)
TBOT_WEBHOOK_URL="http://127.0.0.1:5001/webhook" 
WEBHOOK_KEY="WebhookReceived:123456" 
bash scripts/tbot.sh json 
  --ticker NFLX 
  --direction strategy.close 
  --contract stock 
  --metric qty=50

Guarantees: - Output is validated against alert_webhook_schema.json - Unsupported directions or metrics fail fast - No network calls or broker actions are performed - This generator is independent of the gateway container image (e.g., gnzsnz/ib-gateway).

Copy-paste JSON output (expected schema shape)

When asked to “generate a TradingView webhook JSON”, OpenClaw should output JSON exactly like this shape:

{
  "timestamp": 1710000000000,
  "ticker": "ES1!",
  "currency": "USD",
  "timeframe": "5",
  "clientId": 1,
  "key": "WebhookReceived:123456",
  "contract": "future",
  "orderRef": "Long#1",
  "direction": "strategy.entrylong",
  "exchange": "CME",
  "lastTradeDateOrContractMonth": "202603",
  "multiplier": "50",
  "metrics": [
    {"name": "entry.limit", "value": 0},
    {"name": "entry.stop", "value": 0},
    {"name": "exit.limit", "value": 0},
    {"name": "exit.stop", "value": 0},
    {"name": "qty", "value": 1},
    {"name": "price", "value": 5032.25}
  ]
}

Tip (local-first / zero-config examples): it’s OK to use a placeholder key value in docs. For real TradingView → TBOT delivery, set it to your actual shared secret (TVWB key).

DB inspection (read-only, primary)

  • Preferred (via this skill, DB-first):
  • bash scripts/tbot.sh status db --table orders --format summary --limit 100
  • bash scripts/tbot.sh status db --table alerts --format summary --limit 100
  • bash scripts/tbot.sh status db --table errors --format summary --limit 100
  • bash scripts/tbot.sh status db --table tbot --format summary --limit 100
  • Use --format json to return raw JSON.
  • Portfolio/positions are derived from TBOTORDERS (same as /orders/data in UI).

Read-only helpers (DB-first)

  • Portfolio snapshot:
  • bash scripts/tbot.sh status portfolio --format summary
  • Errors tail (with grouping):
  • bash scripts/tbot.sh status errors --format summary --limit 200
  • bash scripts/tbot.sh status errors --group --limit 200
  • Health checks (HTTP):
  • bash scripts/tbot.sh status health --base-url http://127.0.0.1:5001

Example output (--format summary, orders):

Totals:
- Market value: 284,103.16
- Unrealized PnL: 134,585.15
- Realized PnL: 0.00

TBOT_TIME        | ORD_TIME                | TICKER | TV_Close | ACTION | TYPE | QTY | LIMIT | STOP | ORDERID | ORDERREF  | STATUS    | POS | MRKVAL     | AVGF     | UnrealPnL  | RealPnL
----------------+-------------------------+--------+----------+--------+------+-----+-------+------+---------+-----------+-----------+-----+------------+----------+------------+--------
2026-02-05 20:06 | 2026-02-05 20:06:12.345 | TSLA   | 399.4796 | BUY    | LMT  | 455 | 0     | 0    | 12345   | Ptf_TSLA  | Portfolio | 455 | 181,763.22 | 187.9038 | 96,266.98  | 0
  • DB path resolution (first match wins):
  • --db-path /path/to/tbot_sqlite3
  • TBOT_DB_PATH=/path/to/tbot_sqlite3
  • TBOT_DB_OFFICE=/path/to/tbot_sqlite3
  • DB location notes:
  • Inside the container, TBOT may create the DB at /home/tbot/tbot_sqlite3 if no volume is set.
  • Recommended: bind-mount ./runtime/database to /home/tbot/database and set TBOT_DB_OFFICE=/home/tbot/database/tbot_sqlite3.
  • With the bind-mount, the host path is:
    • tbot-runtime (example)/runtime/database/tbot_sqlite3
  • After updating tbot-runtime (example)/docker-compose.yml, restart TBOT:
  • MODE=docker COMPOSE_DIR="/path/to/your/tbot-runtime" bash scripts/tbot.sh ctl restart --run-it
  • Container note:
  • The tbot container may not include sqlite3 CLI; read the DB on the host (preferred) via bind-mount.
  • Fallback (manual):
  • sqlite3 <path> "SELECT ..."

Known gaps & intended fixes (tracked)

  • Discovery can miss running docker compose stacks; use DB-first commands for portfolio instead of discovery.
  • Add explicit subcommands (planned): errors --tail (limit), health (HTTP checks for /orders/data + /tbot/data).
  • Add a single-line summary mode (planned): totals + top 3 positions + biggest losing position.

Data signal: TradingView-style webhook JSON generator

Required fields

This skill generates JSON with fields used by TBOT/TradingBoat style alerts: - timestamp (ms since epoch) - ticker (e.g., AAPL, ES1!) - currency (e.g., USD) - timeframe (e.g., 1, 5, 1D) - clientId (integer; IBKR client ID) - key (TVWB shared key) - contract (e.g., stock, forex, crypto, future) - orderRef (string identifier) - direction (e.g., strategy.entrylong, strategy.entryshort, strategy.exitlong, strategy.exitshort, strategy.close, strategy.close_all) - exchange, lastTradeDateOrContractMonth, multiplier (mostly for futures) - metrics (array of {name, value})

Example payload

(Uses a placeholder key value for copy-paste. Replace with your real TVWB shared key in production.)

{
  "timestamp": 1710000000000,
  "ticker": "ES1!",
  "currency": "USD",
  "timeframe": "5",
  "clientId": 1,
  "key": "WebhookReceived:123456",
  "contract": "future",
  "orderRef": "Long#1",
  "direction": "strategy.entrylong",
  "exchange": "CME",
  "lastTradeDateOrContractMonth": "202603",
  "multiplier": "50",
  "metrics": [
    {"name": "entry.limit", "value": 0},
    {"name": "entry.stop", "value": 0},
    {"name": "exit.limit", "value": 0},
    {"name": "exit.stop", "value": 0},
    {"name": "qty", "value": 1},
    {"name": "price", "value": 5032.25}
  ]
}