Freqtrade 命令行全景指南：34 个子命令的完整手册与 argparse 分发机制解析

docs/commands/main.md 是 Freqtrade 顶层命令行（freqtrade --help）的完整帮助输出，它列出了整个项目暴露给用户的全部 34 个子命令及两个全局选项（-h/--help、-V/--version）。本文以该文档的“命令清单 + 全局选项”为骨架，逐类解读每个子命令的用途，并结合 入口文件、参数解析器 与 CLI 选项定义 的源码，讲清这些命令是如何注册、解析并分发到具体 start_* 处理函数的，最终帮助读者既能“查手册式”地使用每条命令，又能理解其底层分发与配置注入机制。

1. 这份文档是什么：freqtrade --help 的权威快照

docs/commands/main.md 的内容是一段被 ```output 围栏包裹的纯文本输出，即直接运行：

freqtrade --help

得到的完整结果，头部如下（继承自原文档）：

usage: freqtrade [-h] [-V]
                 {trade,create-userdir,new-config,show-config,new-strategy,download-data,convert-data,convert-trade-data,trades-to-ohlcv,list-data,backtesting,backtesting-show,backtesting-analysis,edge,hyperopt,hyperopt-list,hyperopt-show,list-exchanges,list-markets,list-pairs,list-strategies,list-hyperoptloss,list-freqaimodels,list-timeframes,show-trades,test-pairlist,convert-db,install-ui,plot-dataframe,plot-profit,webserver,strategy-updater,lookahead-analysis,recursive-analysis} ...

Free, open source crypto trading bot

该文件并非手写，而是由 build_helpers/create_command_partials.py 从参数解析器中自动抓取生成（详见第 6 节），并作为 MkDocs 局部片段（partial）通过 --8<-- "commands/main.md" 被 docs/bot-usage.md 内嵌进“启动机器人”章节。因此它的价值有二：一是作为命令总索引，二是作为与源码保持同步的活文档——解析器一旦变化，重新运行生成脚本即可刷新全部命令手册。

2. 34 个子命令完整清单（按功能域归类）

原文档的 positional arguments 列表共 34 项，help 描述与源码中 subparsers.add_parser(...) 传入的 help= 参数逐字一致。按其功能域归类后如下表，便于检索定位：

2.1 交易主循环

命令	官方 help 描述	说明
trade	Trade module.	启动实盘/模拟交易。是否实盘取决于配置中的 dry_run 值（见 main.py 中无子命令时的提示语），也可用 --dry-run 强制模拟交易

2.2 脚手架与部署

命令	官方 help 描述
create-userdir	Create user-data directory.
new-config	Create new config
show-config	Show resolved config
new-strategy	Create new strategy
install-ui	Install FreqUI
strategy-updater	updates outdated strategy files to the current version

2.3 数据管理

命令	官方 help 描述
download-data	Download backtesting data.
convert-data	Convert candle (OHLCV) data from one format to another.
convert-trade-data	Convert trade data from one format to another.
trades-to-ohlcv	Convert trade data to OHLCV data.
list-data	List downloaded data.

2.4 回测与优化

命令	官方 help 描述
backtesting	Backtesting module.
backtesting-show	Show past Backtest results
backtesting-analysis	Backtest Analysis module.
edge	（无描述，见下文说明）
hyperopt	Hyperopt module.
hyperopt-list	List Hyperopt results
hyperopt-show	Show details of Hyperopt results
lookahead-analysis	Check for potential look ahead bias.
recursive-analysis	Check for potential recursive formula issue.

其中 edge 在帮助输出中没有描述文本。对照 arguments.py 可以看到它的 help 字符串被注释为 # help="Edge module. No longer part of Freqtrade"——从源码结构看，这是一个保留的遗留入口，实际描述已被有意隐藏。

2.5 信息列举（探索类）

命令	官方 help 描述
list-exchanges	Print available exchanges.
list-markets	Print markets on exchange.
list-pairs	Print pairs on exchange.
list-strategies	Print available strategies.
list-hyperoptloss	Print available hyperopt loss functions.
list-freqaimodels	Print available freqAI models.
list-timeframes	Print available timeframes for the exchange.

值得注意的是 list-markets 与 list-pairs 在 arguments.py 中复用同一个处理函数 start_list_markets，仅以 partial(start_list_markets, pairs_only=True/False) 区分行为。

2.6 运维、数据库与可视化

命令	官方 help 描述
show-trades	Show trades.
test-pairlist	Test your pairlist configuration.
convert-db	Migrate database to different system
webserver	Webserver module.
plot-dataframe	Plot candles with indicators.
plot-profit	Generate plot showing profits.

3. 全局选项：-h/--help 与 -V/--version

原文档末尾的两个 options：

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

• -h/--help：由 argparse 的 ArgumentParser(prog="freqtrade", ...) 自动提供（见 arguments.py 构建主解析器的位置）。
• -V/--version：在 main.py 中被优先拦截——只要 args.get("version") or args.get("version_main") 为真，就直接调用 print_version_info() 并以 0 退出，不进入任何子命令。源码里同时定义了两个版本选项（version 与 version_main，见 cli_options.py 的注释），目的是让 -V 在“带子命令”与“不带子命令”两种形态下都可用，即 freqtrade -V 与 freqtrade trade -V 都有效。当前仓库 版本标识 为 2026.9-dev，开发版还会拼接 git 短哈希。

4. 入口与命令分发：main() 的完整流程

理解帮助输出的最好方式是看它的消费者。main() 的执行链如下：

1. Python 版本门禁：入口处硬性要求 sys.version_info >= (3, 11)，否则直接 sys.exit（main.py）。
2. 环境准备：setup_logging_pre() 预置日志、asyncio_setup() 初始化事件循环配置。
3. 参数解析：arguments = Arguments(sysargv)，随后 arguments.get_parsed_arg() 返回解析后的 dict。
4. 三路分发：
   • 带 -V → 打印版本并退出（返回码 0）；
   • args 中含 func（即命中了某个子命令）→ 打印 freqtrade {__version__}，设置 GC 阈值与多进程启动方式，然后调用 args"func"，这就是 34 个子命令对应的 start_* 函数；
   • 都没有 → 抛出 OperationalException，提示用户使用 freqtrade trade 或 freqtrade --help。
5. 统一退出码语义（main.py）：KeyboardInterrupt → 130（对应 SIGINT 惯例）；FreqtradeException（含 ConfigurationError）→ 2，且配置错误会附带文档链接提示；未预期异常 → 1。这对编写 systemd unit 或 CI 脚本时判断失败类型很有用。

5. Arguments 类：子命令如何被注册

所有解析逻辑集中在 Arguments 类中，_build_subcommands() 按固定套路为每条命令注册：

trade_cmd = subparsers.add_parser(
    "trade", help="Trade module.", parents=[_common_parser, _strategy_parser]
)
trade_cmd.set_defaults(func=start_trading)
self._build_args(optionlist=ARGS_TRADE, parser=trade_cmd)

关键点：

• 父解析器复用：_common_parser（Common arguments 组）承载 ARGS_COMMON = ["verbosity", "print_colorized", "logfile", "version", "config", "datadir", "user_data_dir"]（arguments.py），被几乎所有子命令以 parents= 引入；_strategy_parser 承载 ARGS_STRATEGY（strategy、strategy_path、recursive_strategy_search、freqaimodel、freqaimodel_path），只注入给 trade、backtesting、hyperopt、plot-* 等需要策略的命令。
• set_defaults(func=start_xxx)：每个子命令把一个处理函数塞进 argparse 的 Namespace.func，main() 据此完成“命令名 → 函数”的分发。这些 start_* 函数统一从 freqtrade/commands/init.py 导出，分别定义在 trade_commands.py、data_commands.py、optimize_commands.py、deploy_commands.py 等模块中。
• 每条命令的参数集合由顶部的 ARGS_* 列表声明式定义，例如 ARGS_BACKTEST 在 ARGS_COMMON_OPTIMIZE（timeframe、timerange、max_open_trades、stake_amount、fee、pairs 等）基础上扩展出 position_stacking、enable_protections、strategy_list、export、backtest_cache 等回测专属项（arguments.py）；ARGS_HYPEROPT 再追加 epochs、spaces、hyperopt_loss、hyperopt_jobs、early_stop 等（arguments.py）。

5.1 配置文件自动发现与“免配置”命令

_parse_args() 中含有一段决定“哪些命令可以不传 -c”的关键逻辑（arguments.py）：当 --config 未显式给出时：

1. 优先探测 <userdir>/config.json（userdir 取 --userdir，默认 user_data）；
2. 否则探测当前工作目录的 config.json；
3. 仅当文件存在，或该命令不属于 NO_CONF_REQURIED 列表时，才把默认配置注入 parsed_arg.config。

NO_CONF_REQURIED（arguments.py）收录了 download-data、list-data、plot-dataframe、show-trades、install-ui 等 20 条“纯工具型”命令——它们没有本地配置文件也能运行；而 create-userdir、list-exchanges、new-strategy 属于 NO_CONF_ALLOWED，即配置文件可选但非必需。这解释了为什么 freqtrade list-exchanges、freqtrade download-data ... 可以直接裸跑，而 freqtrade trade 找不到配置时会报 ConfigurationError。

6. 参数定义中枢：cli_options.py 与 fthelp 机制

arguments.py 里的 ARGS_* 列表只是“选项 key”，真正的短名/长名、类型、帮助文本全部集中在 AVAILABLE_CLI_OPTIONS 字典中，由 Arg 类（cli_options.py）描述。几个值得注意的工程设计：

• 帮助文本可按命令定制（fthelp）：Arg 支持 fthelp 字典，_build_args() 会按 parser.prog（即 freqtrade <command>）查找定制文案。典型例子是 exportfilename（--backtest-filename/--export-filename）：在 freqtrade backtesting 下其帮助被替换为“DEPRECATED: … use --backtest-directory”（cli_options.py）——同一选项在不同子命令下呈现不同帮助，而主帮助输出不受影响。
• 类型校验前置：如 epochs 使用 check_int_positive（cli_options.py）把“必须为正整数”的校验提前到 argparse 层，非法值直接给出 ArgumentTypeError 而不是深进到业务层才报错。
• 默认值与常量联动：--cache 的默认值来自 constants.BACKTEST_CACHE_DEFAULT，--epochs 来自 constants.HYPEROPT_EPOCH，保证 CLI 默认与配置默认一致。

高频公共参数速查（帮助文本均摘自 cli_options.py）：

选项	作用
-v / --verbose	详细日志，-vv 更多、-vvv 全部
--logfile	日志落盘，特殊值 syslog、journald
-c / --config	指定配置文件，可多次出现（后者覆盖前者），也支持 - 从 stdin 读取
-d / --datadir	历史数据根目录
--userdir / --user-data-dir	user-data 目录路径
--no-color	关闭超参优化输出的彩色化
-s / --strategy	指定策略类名
-i / --timeframe	K 线周期（1m、5m、1h 等）
--timerange	限定时间范围，格式如 20240101-20240201T1200

7. 典型使用方式

以下示例均只依赖本仓库定义的命令与选项，可直接在已安装环境中执行：

# 查看版本
freqtrade --version

# 创建 user-data 目录（含示例配置/策略）
freqtrade create-userdir

# 启动模拟/实盘交易（取决于配置 dry_run，可强制模拟）
freqtrade trade -c user_data/config.json --dry-run

# 指定策略回测，限定时间范围
freqtrade backtesting -c user_data/config.json --strategy SampleStrategy -i 5m --timerange 20240101-20240201

# 超参优化（指定优化空间与轮数）
freqtrade hyperopt -c user_data/config.json --strategy SampleStrategy --spaces buy --epochs 500

# 探索交易所与交易对（免配置命令）
freqtrade list-exchanges
freqtrade list-pairs --exchange binance --print-list

# 下载回测数据
freqtrade download-data --exchange binance --pairs BTC/USDT ETH/USDT --timeframes 5m 1h

# 查看已解析的完整配置
freqtrade show-config -c user_data/config.json

多条 -c 的合并语义与密钥分离技巧可进一步参阅 docs/bot-usage.md 的“multiple configuration files”一节。

8. 这份文档是如何生成的

build_helpers/create_command_partials.py 是 docs/commands/ 下所有 *.md 手册的生成器：

• 它固定 COLUMNS=80 与 NO_COLOR=1 环境变量，保证帮助文本的折行与配色在任意终端上稳定一致（create_command_partials.py）；
• 构造 Arguments(None) 并调用 _build_subcommands() 得到完整解析器，随后把主解析器的帮助输出写入 docs/commands/main.md，再把 trade、backtesting 等 34 个子解析器各自的帮助逐一写入 docs/commands/<command>.md（create_command_partials.py）；
• 脚本要求 Python 3.13+ 运行，因为 argparse 的输出格式在 3.13 起发生了变化（create_command_partials.py）。注意这与运行 Freqtrade 本身的 Python 3.11+ 要求（main.py）是两回事。

这也意味着：阅读 docs/commands/*.md 等价于运行 freqtrade <command> --help，而两者永远与源码中的解析器定义保持一致——这是本文所有命令描述可被追溯验证的根本原因。

9. 相关文件索引

路径	角色
docs/commands/main.md	本文主体：顶层帮助输出快照
docs/bot-usage.md	内嵌该手册的“启动机器人”文档页
freqtrade/main.py	进程入口、子命令分发与退出码
freqtrade/commands/arguments.py	Arguments 类、ARGS_* 分组、配置自动发现
freqtrade/commands/cli_options.py	全部 CLI 选项的声明式定义
freqtrade/commands/init.py	各 start_* 处理函数导出
build_helpers/create_command_partials.py	命令手册自动生成脚本

掌握以上结构后，使用 Freqtrade 的心法很简单：用 freqtrade --help 或本手册定位子命令，用 freqtrade <command> --help 查看该命令的参数细节，而一切细节都能在 arguments.py 的 ARGS_* 列表与 cli_options.py 的选项字典中找到一一对应的源码依据。