tbot-controller

通过受控自动化接口（数据库优先查询；根据显式请求进行生命周期控制）操作 TradingBoat/TBOT（TBOT 运行时堆栈）。

## 概述（中文）

通过受控自动化接口（数据库优先查询；根据显式请求进行生命周期控制）操作 TradingBoat/TBOT（TBOT 运行时堆栈）。

## 原文

## 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.

### Install the runtime (recommended)
1) Clone the runtime repo:

```bash
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:

```bash
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:

```bash
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:

```bash
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):
```bash
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
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
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:
```bash
MODE=docker COMPOSE_DIR="<compose_dir>" bash scripts/tbot.sh ctl status
```

Example expected compose folder:

```text
~/develop/github/openclaw-on-tradingboat> 
```

- systemd example:
```bash
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
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
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.

```bash
# 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**:

```json
{
  "timestamp": 1710000000000,
  "ticker": "ES1!",
  "currency": "USD",
  "timeframe": "5",
  "clientId": 1,
  "key": "WebhookReceived:123456