OctoBot 2.1.1 常用 CLI 命令与工具详解

目标：把 OctoBot 2.1.1 自带命令行入口 OctoBot 的全局选项与三个子命令（tentacles、node、sync）逐一讲清：语法、参数含义、真实运行回显与典型组合场景。本文所有帮助输出与执行回显均在 Ubuntu 22.04 服务器上的官方 2.1.1 发行包中实测采集（2026-10-24），逐行照抄，未实测的选项以帮助原文为准并标注。

一、环境信息

操作系统：Ubuntu 22.04.4 LTS（x86_64）
OctoBot：2.1.1（最新稳定版，官方发行包自带 OctoBot 命令行入口）
实测形态：官方发行包内执行 CLI 命令；二进制安装形态（官方 GitHub Release 提供的 Linux x64 可执行包）下命令为解压目录内的 ./OctoBot，选项与回显一致；Docker 部署形态的进入与调用方式见《OctoBot Docker Compose 部署指南》
版本验证（实测）：

OctoBot -v

实测回显：

2.1.1

二、前置条件

服务器上已安装 OctoBot 2.1.1（部署与持久化目录说明见部署篇）；
CLI 命令与正在运行的 Web 服务共用同一套 user/、tentacles/ 配置：涉及安装/更新插件的命令建议在服务停止时执行，避免两个进程同时写同一目录；
联网需求：tentacles 安装/更新需访问官方分发源 tentacles.octobot.online；
OctoBot 是完整机器人入口：不带参数直接执行等价于 OctoBot start，会启动交易服务与 Web 界面。

三、命令结构总览

OctoBot --help 实测原文（节选主结构，完整选项见第四章表）：

usage: OctoBot [-h] [-v] [-s] [-u] [-rts] [-b] [-bf BACKTESTING_FILES]
               [-wdr] [-ebt] [-r RISK] [-nw] [-nl] [-nt] [--encrypter]
               [--identifier] [-o]
               [strategy_optimizer ...] ...

General trader bot options

positional arguments:
  {tentacles,node,sync}
    tentacles           OctoBot tentacles manager
    node                OctoBot Node
    sync                OctoBot sync server

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit

命令地图：

入口	作用	本文实测情况
`OctoBot start`（默认）	启动完整交易服务 + Web 界面（部署篇的日常形态）	已在部署篇实测（服务启动日志）
`OctoBot -v`	输出版本号	✅ 实测 `2.1.1`
`OctoBot tentacles …`	插件（tentacle）管理器	✅ 实测安装全流程
`OctoBot node …`	分布式 Node 形态（2.1 新增）	✅ 实测 master 模式启动
`OctoBot sync …`	同步服务器	✅ 帮助已确认，未做长跑实测

四、全局选项详解

OctoBot --help 的完整全局选项（帮助原文逐条整理）：

选项	帮助原文摘要	用途说明
`-v, --version`	show program's version number and exit	输出版本号，升级后核对版本
`-s, --simulate`	Force the trading mode to simulate	临时强制模拟器形态启动（不改配置文件）
`-u, --update`	Update OctoBot	程序自更新（二进制形态使用；升级细节见部署篇第八章路径）
`-rts, --reset-trading-history`	Reset the trading history	清空交易历史（模拟盘重置常用）
`-b, --backtesting`	Start OctoBot in backtesting mode	回测模式启动
`-bf, --backtesting-files BACKTESTING_FILES`	Set the data files to use in backtesting	指定回测数据文件（配合 `-b`）
`-wdr, --whole-data-range`	Force to use the whole data range	回测使用数据全集
`-ebt, --enable-backtesting-timeout`	Disable the backtesting timeout	解除回测时长限制
`-r, --risk RISK`	Set the risk, between 0 and 1	临时覆盖风险系数（Profile 的 `trading.risk` 默认 0.5）
`-nw, --no_web`	Disable the web interface	无界面启动（纯后台执行策略时用）
`-nl, --no_logs`	Disable logs storage	不落日志文件
`-nt, --no-telegram`	Disable telegram	本次启动禁用 Telegram 通道
`--encrypter`	Set or reset the password for all encryption	生成/重置配置加密密钥（交易所 Key 加密体系）
`--identifier`	Display this OctoBot identifier	输出本实例标识
`-o, --strategy_optimizer [strategy_optimizer ...]`	Launch the strategy optimizer on the given strategy name	策略优化器：对指定策略类做时间框架/评估器/风险参数扫描

💡 技术拓展：-s（强制模拟）与配置层的 trader.enabled=false + trader-simulator.enabled=true（见配置详解篇）是同一开关体系的两种操作粒度——| 粒度 | 途径 | 持久性 | 适用 |；| 一次会话 | 命令行 -s | 仅本次启动 | 临时验证策略 |；| 常驻 | 配置文件 | 永久 | 日常形态定义 |。生产推荐"配置文件定形态 + 命令行做临时覆盖"，避免用临时参数跑长周期任务后忘记恢复。

五、tentacles 子命令详解

5.1 语法与参数

OctoBot tentacles --help 实测原文：

usage: OctoBot tentacles [-h] [-i] [-u] [-ui] [-r]
                         [-sti SINGLE_TENTACLE_INSTALL SINGLE_TENTACLE_INSTALL]
                         [-p PACK] [-e EXPORT [EXPORT ...]] [-a]
                         [--export-with-package-name] [-d DIRECTORY]
                         [-l LOCATION] [-f] [-idm] [-ite]
                         [-ute UPLOAD_TENTACLES_EXPORT]
                         [-upe UPLOAD_PACKAGE_EXPORT] [-ut UPLOAD_TYPE]
                         [-c CREATOR [CREATOR ...]] [-m METADATA_FILE] [-cy]
                         [-q]
                         [tentacle_names ...]

positional arguments:
  tentacle_names

options:
  -h, --help            show this help message and exit
  -i, --install         Install or re-install the given tentacles modules with
                        their requirements if any. Does not edit tentacles
                        configuration files and creates it if missing.
  -u, --update          Update the given tentacle modules and install missing
                        requirements if any. Does not update already filled
                        requirements regardless of their version to avoid
                        conflicts. Prefer a full tentacles update if a
                        requirement version is creating conflicts. Does not
                        edit tentacles configuration files.
  -ui, --uninstall      Uninstall the given tentacle modules. Does not delete
                        the associated tentacle configuration.
  -r, --repair          Repair a tentacles installation. Fixes __init__.py
                        files, missing main folders and configuration files.
  -sti, --single-tentacle-install SINGLE_TENTACLE_INSTALL SINGLE_TENTACLE_INSTALL
                        Single tentacle to install identified by a local path
                        and its tentacle type. Example: -sti "/bot/macd_eval"
                        "Evaluator/TA".
  -p, --pack PACK       Create a tentacle package containing all tentacles in
                        the given folder. Specify source folder using the
                        --directory argument. Add --cythonize to cythonize and
                        compile the packed tentacles.Example: -p
                        myTentaclesPackage.zip -d ./tentacles
  -e, --export EXPORT [EXPORT ...]
                        Export tentacles into a folder containing tentacles in
                        the given folder. Removes installation generated
                        files. Exported tentacles can be filtered to only be
                        the ones from a given package by using the package
                        name as a second argument. Specify source folder using
                        the --directory argument. Example (all tentacles): -e
                        myTentaclesFolder -d ./tentacles other example
                        (tentacles from 'OctoBot-Default-Tentacles' package):
                        -e myTentaclesFolder OctoBot-Default-Tentacles -d
                        ./tentacles
  -a, --all             Apply command to all available Tentacles.
  --export-with-package-name
                        Export package using its artifact's name as package
                        name. When used with cythonize, the exported package
                        name wont contain the os and the architecture
  -d, --directory DIRECTORY
                        Path to the root of the OctoBot installation folder to
                        operate on. Default is '/octobot'.
  -l, --location LOCATION
                        Tentacles package local path or url to find the
                        tentacles package to process.
  -f, --force           Skip user confirmations.
  -idm, --include-dev-mode
                        Include tentacles in dev mode in export and pack
                        commands.
  -ite, --include-tentacles-export
                        Include tentacles during export and pack commands.
  -ute, --upload-tentacles-export UPLOAD_TENTACLES_EXPORT
                        Upload tentacles during export and pack commands.
                        Usage: <upload_path>
  -upe, --upload-package-export UPLOAD_PACKAGE_EXPORT
                        Upload package during export and pack commands. Usage:
                        <upload_path>
  -ut, --upload-type UPLOAD_TYPE
                        Uploader type, can be s3 or nexus
  -c, --creator CREATOR [CREATOR ...]
                        Start OctoBot Tentacles Creator. Examples: -c
                        Evaluator to create a new evaluator tentacles. Use: -c
                        help to get the Tentacles Creator help.
  -m, --metadata-file METADATA_FILE
                        The metadata file to use when exporting the package.
  -cy, --cythonize      Option for the --pack command: cythonize and compile
                        the packed tentacles.
  -q, --quite           Only display errors in logs.

5.2 常用操作一：安装官方全量插件包（实测）

本节要做的：在全新 OctoBot 上安装官方默认插件包（交易所、指标、策略、交易模式等全部模块）。注意 -a 参数是必需的——只写 -i 不带包名或 -a 会因缺参报错（实测实录见本节末尾）。

OctoBot tentacles -a -i

实测回显（关键行，节选）：

[2026-10-24 01:39:33,408] | WARNING  | <class 'octobot_tentacles_manager.loaders.tentacles_loader.TentaclesImportLoader'> tentacles are already installed at /octobot/tentacles, install the tentacles from scratch using the -r flag.
[2026-10-24 01:39:33,409] | INFO     | >==> >==> >==> >==> >==> >==> >==> >==> >==> >==> >==> >==> >==> >==> >==> OctoBot Tentacles Manager
[2026-10-24 01:39:35,730] | INFO     | >==> >==> Downloading and installing tentacles from https://tentacles.octobot.online/officials/packages/full/base/2.1.1/any_platform.zip (default repository on tentacles.octobot.online)
[2026-10-24 01:39:36,024] | INFO     | >==> >==> Downloading and installing tentacles from https://tentacles.octobot.online/officials/packages/full/base/2.1.1/any_platform.zip (default repository on tentacles.octobot.online)
[2026-10-24 01:39:47,938] | INFO     | Tentacles successfully installed (178) and configured in 14.51s

关键行说明：官方包地址随版本走（base/2.1.1/）；新装完成输出 Tentacles successfully installed (178)，即 178 个默认 tentacle；若目录里已有插件且非全新状态，会提示用 -r 修复安装（见 5.3）。

⚠️ 注意：缺 -a 会直接报错。实测 OctoBot tentacles -i（不带 -a、不带包名）的报错回显：

OctoBot
 Disclaimers: Use this bot in accordance with the exchange Terms of Service. Do not risk money which you are afraid to lose. Use the bot at your own responsibility.
...
2026-10-24 01:38:06,505 ERROR  Configuration                 Error when loading tentacles install parameters: Select at least one tentacle to install. Use the -a option to select all tentacles.
2026-10-24 01:38:06,505 ERROR  Configuration                 Cancelled error: Select at least one tentacle to install. Use the -a option to select all tentacles.

官方报错信息已直接给出修复方式（加 -a），这是 2.1.1 上最常见的 CLI 卡点（排障实录已沉淀）。

5.3 常用操作二：修复/重置安装（-r）

-r, --repair：修复安装产物（重建 __init__.py、缺失目录与配置文件）。适用场景：手工删过 tentacles/ 内文件、升级版本后启动报缺模块、或 5.2 提示用 -r 重装时：

OctoBot tentacles -a -r

配合 -l 可从本地包或自定义 URL 修复安装：

OctoBot tentacles -r -l /path/to/tentacles_package.zip -f

-f 跳过交互确认（脚本化运维必备）。

5.4 常用操作三：更新 / 卸载（-u / -ui）

OctoBot tentacles -a -u          # 全量更新（帮助原文：避免需求版本冲突时优先做全量更新）
OctoBot tentacles -a -ui         # 卸载全部（会保留配置文件）
OctoBot tentacles -a -i -f       # 重装并跳过确认

帮助原文对 -u 的取舍说明值得注意：更新不会强行升级已装好的依赖版本，若出现版本冲突应改用全量更新（即重新 -i）。

5.5 常用操作四：插件开发与打包（-c / -p / -e）

-c Evaluator：启动官方 Tentacles Creator 脚手架，按向导生成评估器骨架（-c help 查看完整帮助；同理可生成 Trading Mode、Strategy 等类型）；
-p <包名>.zip -d ./tentacles：把本目录插件打包成分发包，-cy 附加 cythonize 编译；
-e <导出目录> [包名过滤] -d ./tentacles：把插件导出为源码目录（去掉安装产物）；
-sti "<本地路径>" "<类型>"：单插件安装，如 -sti "/bot/macd_eval" "Evaluator/TA"（帮助原文示例）。

5.6 实测补充：无操作参数时的默认行为

实测直接执行 OctoBot tentacles（无任何操作参数）时程序正常退出（无输出，退出码 0），不会产生副作用；操作必须通过 -i/-u/-ui/-r/-p/-e/-c 显式指定。

六、node 子命令详解（2.1 新增）

OctoBot node --help 实测原文：

usage: OctoBot node [-h] [--host HOST] [--port PORT] [--master]
                    [--consumer_only CONSUMER_ONLY]

options:
  -h, --help            show this help message and exit
  --host HOST           Host to bind the server to.
  --port PORT           Port to bind the server to (default: 8000).
  --master              Enable master node mode (schedules and executes tasks,
                        UI enabled by default).
  --consumer_only CONSUMER_ONLY
                        Start OctoBot Node in consumer only mode, in case the
                        master node is not enough (requires a postgres
                        database).

参数	默认	说明
`--host` / `--port`	未指定 / `8000`	Node 服务监听地址与端口（与 Web 界面的 5001 是两个端口）
`--master`	关	主节点模式：调度并执行任务，默认启用其 UI
`--consumer_only`	未指定	纯消费模式：仅消费任务不调度，需要外部 PostgreSQL 数据库

实测启动 master 模式（节选关键回显）：

2026-10-24 01:45:07,560 INFO   OctoBot               Using node OctoBot distribution.
...
Disclaimers: Use this bot in accordance with the exchange Terms of Service. Do not risk money which you are afraid to lose. Use the bot at your own responsibility.
* Running on all addresses (0.0.0.0)
* Running on http://127.0.0.1:8000
* Running on http://10.89.60.3:8000

实测观察到的两个行为要点：① node 形态的 --port 8000 端口提供的是任务/接口服务，与常规 Web 界面（5001）并行不冲突；② 启动过程中其内部健康检查访问根路径会出现一次 404 页面日志（node 分发未注册完整 Web 首页路由所致），不影响 master 节点本身启动，判断存活以进程监听 8000 与任务调度日志为准。

--consumer_only 模式未实测（依赖外部 PostgreSQL，本文实验环境未部署），字段语义以帮助原文为准；官方用途定位是"master 节点不够用时的水平扩展"。

七、sync 子命令详解（2.1 新增）

OctoBot sync --help 实测原文：

usage: OctoBot sync [-h] [--host HOST] [--port PORT]

options:
  -h, --help   show this help message and exit
  --host HOST  Host to bind the sync server to (default: 0.0.0.0).
  --port PORT  Port to bind the sync server to (default: 3000).

sync 启动一个同步服务器（默认绑定 0.0.0.0:3000），用于多实例间的数据同步通道；单实例部署无需运行。本文未做长跑实测，语义以帮助原文与官方 node/sync 系列文档为准。

八、典型使用场景组合

场景	命令组合	要点
全新安装	`OctoBot tentacles -a -i` → `OctoBot start`	先装插件再启动；首次启动 Web 部署形态已自动完成此步
模拟盘临时验证	`OctoBot -s start`	不改配置强制模拟器，验证完即退出
无界面长跑	`OctoBot start -nw`	不起 Web 界面，纯策略执行（配合 `nohup`/进程管理器）
重置模拟盘	`OctoBot -rts`	清空交易历史后重启
回测	`OctoBot -b -bf <数据文件>`	数据文件由 Web 界面 Data Collector 采集到 `user/data/`
策略参数扫描	`OctoBot -o <策略类名>`	时间框架/评估器/风险多组合扫描
升级插件	停服务 → `OctoBot tentacles -a -u` → 启动	避免与运行中服务同时写目录
修复安装	`OctoBot tentacles -a -r -f`	启动报缺模块/文件缺失时使用
Key 加密	`OctoBot --encrypter`	生成/重置配置加密密钥，配合配置层的加密存储
自研插件	`OctoBot tentacles -c Evaluator`	官方脚手架生成骨架后开发，`-p` 打包分发

九、常见问题（FAQ）

Q1：OctoBot tentacles -i 报 "Select at least one tentacle to install"？ 必加 -a（或指定包名/位置）。2.1.1 的安装命令需要显式选择安装范围，实测报错原文与修复方式见 5.2，官方报错信息本身已给出提示（Use the -a option to select all tentacles.）。

Q2：安装插件时提示已安装怎么办？ 提示原文为 tentacles are already installed at ... install the tentacles from scratch using the -r flag.，按提示改用 -a -r 修复式重装即可。

Q3：CLI 操作和 Web 界面配置冲突吗？ 共用同一套文件。tentacles 安装器默认"不编辑配置文件"（帮助原文多次声明），因此只动模块本体；启停 tentacle 仍通过 Web 界面或 tentacles_config.json（见配置详解篇第七章）。

Q4：node / sync 需要在单实例部署里开启吗？ 不需要。单实例跑 OctoBot start 即可；node/sync 是 2.1 引入的多实例/分布式形态（--consumer_only 还依赖 PostgreSQL），生态尚在完善，生产单实例部署不引入。

Q5：怎么确认 CLI 与服务是同一版本？ OctoBot -v 输出 2.1.1；Web 界面侧可用部署篇的 curl http://127.0.0.1:5001/api/version（实测返回 "OctoBot 2.1.1"）双向核对，二进制升级后务必两边一致。

十、参考链接

官方文档（安装与命令行）：https://www.octobot.cloud/en/guides/octobot-installation
Tentacles 官方分发源：https://tentacles.octobot.online
GitHub 仓库（CLI 源码 octobot/cli.py）：https://github.com/Drakkar-Software/OctoBot
本专栏相关篇目：《OctoBot 2.1.1 介绍与选型指南》、《OctoBot Docker Compose 部署指南》、《OctoBot 2.1.1 配置参数详解》