tbot-controller

tbot-controller 是专为 TradingBoat/TBOT 运行时栈设计的自动化控制接口，采用"DB-first"架构，优先通过 SQLite 数据库查询交易订单、持仓、警报和错误日志。用户可通过 Docker Compose 或 systemd 控制服务生命周期，并生成 TradingView 风格的 Webhook JSON 信号。所有操作通过 bash scripts/tbot.sh 入口脚本执行，分为 ctl（控制）、json（信号生成）和 status（状态查询）三种模式。

该技能的显著优点在于其严谨的安全设计：默认只读操作，任何状态变更（启动/停止/重启）必须通过 --run-it 标志或 RUN_IT=1 环境变量显式确认，有效防止误操作导致的交易中断。本地优先架构确保所有数据处理在本地完成，从本地 .env 读取配置，不向远程上传敏感信息，充分保护交易隐私。同时支持 Docker Compose 和 systemd 两种部署方式，自动发现运行时位置，适应不同用户的部署习惯。完善的输入验证机制对参数进行类型检查和范围限制（如 --limit 限制 1-5000），并使用参数化查询防止 SQL 注入。

潜在局限性包括：该技能本身不安装 TBOT 运行时，若未预先部署 openclaw-on-tradingboat 项目，控制功能将无法使用；发现机制在识别运行中的 Docker Compose 栈时可能存在遗漏，建议优先使用 DB-first 命令；作为个人开发者（PlusGenie）维护的项目，长期维护能力存在不确定性；且功能仅针对 TBOT 生态设计，不适用于其他交易平台。

该技能适合使用 TradingBoat/TBOT 进行自动化量化交易的个人投资者、需要通过 OpenClaw 控制本地交易环境的开发者，以及使用 Interactive Brokers（IBKR）进行程序化交易的技术用户。使用者需具备 Docker 或 systemd 基础知识。

使用过程中需警惕以下风险：首先，虽然控制操作需要确认，但错误的交易信号生成仍可能导致实盘交易损失，使用前务必确认运行时是模拟盘还是实盘；其次，重启或停止操作会中断正在运行的交易策略，可能导致错过交易信号或持仓风险暴露；再次，若 TBOT_COMPOSE_DIR 或数据库路径配置错误，可能操作错误的环境或读取过期数据；最后，技能依赖 uv 和特定 Python 环境，依赖项变更可能影响正常运行。

核心功能

tbot-controller 是一款面向 TradingBoat/TBOT 交易运行时栈的自动化控制工具，专为量化交易场景设计。其核心能力分为四大模块：

1. DB-first 数据查询：直接读取 TBOT SQLite 数据库，支持订单、预警、错误日志、持仓组合等查询，无需启动完整运行时即可获取交易状态。

2. 生命周期控制：通过 Docker Compose 或 systemd 管理 TBOT 服务的启动、停止、重启，适用于本地开发环境和生产部署。

3. 状态与日志检查：实时获取容器/服务健康状态、端口监听情况及最近日志（仅限显式请求时执行）。

4. JSON 信号生成与发送：将自然语言交易指令（如"close 50 NFLX"）转换为符合 TradingView webhook 规范的 JSON 载荷，并发送至本地 TBOT 服务。

显著优点

• 安全设计突出：所有状态变更操作（start/stop/restart/send）必须通过 --run-it 标志或 RUN_IT=1 环境变量显式确认，有效防止误操作导致交易中断或资金风险。

• DB优先架构：查询类操作无需发现运行时位置，直接访问数据库，响应更快且更可靠，避免因容器状态异常导致的信息获取失败。

• 零配置信号生成：json 模式支持智能推断，自动补全 webhook URL、密钥、订单引用等字段，用户仅需提供核心交易参数即可生成合规 payload。

• 多运行时支持：同时兼容 Docker Compose 和 systemd 部署模式，适应不同技术栈用户的运维习惯。

• 信息脱敏机制：自动 redact webhook 密钥、令牌等敏感信息，降低日志泄露风险。

潜在缺点与局限性

• 外部运行时依赖：本 Skill 不自动安装 TBOT 运行时栈，需用户手动部署 openclaw-on-tradingboat 项目，首次配置门槛较高。

• 本地网络限定：webhook 通信仅限于 127.0.0.1:5001，不支持远程 TBOT 实例管理，分布式部署场景受限。

• SQLite 绑定限制：数据库访问依赖主机路径绑定，若容器未正确配置 volume，部分功能将无法使用。

• 确认机制增加交互成本：虽然安全，但频繁的状态变更操作需要重复确认，可能降低高频运维场景的效率。

适合人群

• 已部署或计划部署 TradingBoat/TBOT 的专业量化交易者
• 需要程序化管理交易运行时和查询交易数据的开发者
• 偏好本地优先、数据自主可控的技术型用户
• 熟悉 Docker/Linux 系统管理的中高级用户

常规风险

• 配置错误风险：TBOT_COMPOSE_DIR 等环境变量配置错误可能导致控制指令作用于错误的运行时实例。

• paper/live 模式混淆：Skill 无法自动识别 TBOT 当前运行于模拟盘还是实盘，用户必须自行确认，否则可能引发意外真实交易。

• 数据库并发访问：直接 SQLite 查询与 TBOT 运行时写入可能存在锁竞争，极端情况下导致查询延迟。

• 本地服务可用性：依赖的 TBOT webhook 服务若未启动，信号发送将失败，需先确保运行时健康。