freqtrade trade 命令全解析：从启动参数到交易主循环的实战指南

2026-09-07 09:09:37作者：盛欣凯Ernestine

freqtrade trade 是 freqtrade 开源加密货币交易机器人的核心运行子命令，负责将配置文件、交易策略与交易所账户状态结合起来，驱动机器人在实盘（Live）或模拟盘（Dry Run）模式下持续运行。本文以仓库文档 docs/commands/trade.md 中记录的完整 --help 输出为骨架，结合 freqtrade 源码（commands、worker、configuration 等模块）逐项讲解每个参数的默认值、底层影响与典型用法，帮助你准确启动、调试和在生产环境（含 systemd）中部署一个稳定的交易进程。

trade 子命令在 freqtrade 中的定位与启动链路

freqtrade 采用 argparse 多子命令架构，trade 是其中驱动常驻交易进程的一个子命令。在 freqtrade/commands/arguments.py 中可以清楚地看到它的注册方式：

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)

这里有三个关键信息：

parents=[_common_parser, _strategy_parser]：trade 命令继承了两组公共参数——"Common arguments"（日志、配置文件、数据目录等）与"Strategy arguments"（策略与 FreqAI 模型选择）。
set_defaults(func=start_trading)：trade 子命令实际执行的入口函数是 start_trading。
ARGS_TRADE 定义了该子命令独有的交易参数，见 freqtrade/commands/arguments.py：

ARGS_TRADE = ["db_url", "sd_notify", "dry_run", "dry_run_wallet", "fee"]

start_trading 的实现位于 freqtrade/commands/trade_commands.py：它注册 SIGTERM 信号处理器（将终止信号转成 KeyboardInterrupt 以便统一走异常清理逻辑），然后实例化 Worker 并调用 worker.run()，在 finally 中确保退出前调用 worker.exit() 做资源清理。也就是说，freqtrade trade 启动后实际上运行的是 freqtrade/worker.py 中定义的 Worker 状态机与 freqtrade/freqtradebot.py 中的交易机器人逻辑。

完整的 usage 帮助输出

docs/commands/trade.md 记录的就是 freqtrade trade --help 的完整输出，这也是后续所有参数讲解的基准：

usage: freqtrade trade [-h] [-v] [--no-color] [--logfile FILE] [-V] [-c PATH]
                       [-d PATH] [--userdir PATH] [-s NAME]
                       [--strategy-path PATH] [--recursive-strategy-search]
                       [--freqaimodel NAME] [--freqaimodel-path PATH]
                       [--db-url PATH] [--sd-notify] [--dry-run]
                       [--dry-run-wallet DRY_RUN_WALLET] [--fee FLOAT]

options:
  -h, --help            show this help message and exit
  --db-url PATH         Override trades database URL, this is useful in custom
                        deployments (default: `sqlite:///tradesv3.sqlite` for
                        Live Run mode, `sqlite:///tradesv3.dryrun.sqlite` for
                        Dry Run).
  --sd-notify           Notify systemd service manager.
  --dry-run             Enforce dry-run for trading (removes Exchange secrets
                        and simulates trades).
  --dry-run-wallet, --starting-balance DRY_RUN_WALLET
                        Starting balance, used for backtesting / hyperopt and
                        dry-runs.
  --fee FLOAT           Specify fee ratio. Will be applied twice (on trade
                        entry and exit).

Common arguments:
  -v, --verbose         Verbose mode (-vv for more, -vvv to get all messages).
  --no-color            Disable colorization of hyperopt results. May be
                        useful if you are redirecting output to a file.
  --logfile, --log-file FILE
                        Log to the file specified. Special values are:
                        'syslog', 'journald'. See the documentation for more
                        details.
  -V, --version         show program's version number and exit
  -c, --config PATH     Specify configuration file (default:
                        `userdir/config.json` or `config.json` whichever
                        exists). Multiple --config options may be used. Can be
                        set to `-` to read config from stdin.
  -d, --datadir, --data-dir PATH
                        Path to the base directory of the exchange with
                        historical backtesting data. To see futures data, use
                        trading-mode additionally.
  --userdir, --user-data-dir PATH
                        Path to userdata directory.

Strategy arguments:
  -s, --strategy NAME   Specify strategy class name which will be used by the
                        bot.
  --strategy-path PATH  Specify additional strategy lookup path.
  --recursive-strategy-search
                        Recursively search for a strategy in the strategies
                        folder.
  --freqaimodel NAME    Specify a custom freqaimodels.
  --freqaimodel-path PATH
                        Specify additional lookup path for freqaimodels.

逐类拆解：三个层次的命令行参数

trade 的参数可以清晰地分为"交易核心参数""通用参数"与"策略参数"三类，每一类来自不同的 parser 与配置处理管线。

交易核心参数（ARGS_TRADE）

下表为上述帮助输出中 options 一节的参数速查：

参数	类型/取值	默认值	核心作用
`--db-url PATH`	数据库连接串	实盘 `sqlite:///tradesv3.sqlite`，Dry Run `sqlite:///tradesv3.dryrun.sqlite`	覆盖交易数据库地址，用于自定义部署
`--sd-notify`	开关	关闭	向 systemd 服务管理器发送通知
`--dry-run`	开关	依配置决定（默认 true）	强制模拟盘模式，剔除交易所密钥并模拟成交
`--dry-run-wallet` / `--starting-balance`	float	配置默认 `1000`（见 `DRY_RUN_WALLET`）	设置回测、超参优化与模拟盘使用的起始资金
`--fee FLOAT`	float（费率比例）	由配置/交易所决定	指定交易费率，开仓与平仓各计一次

这些参数对应的 argparse 定义可以在 freqtrade/commands/cli_options.py 与 fee（同文件 L260-L265）处找到，其类型、metavar 与默认值说明均与帮助输出一致。注意 --dry-run-wallet 是 type=float，而配置文件中它还可以是"按币种区分"的对象形式（详见下文）。

通用参数（Common arguments）

-v / --verbose：冗余日志级别，-vv 更详细、-vvv 输出全部消息；
--no-color：关闭输出着色，重定向日志到文件时尤其有用；
--logfile / --log-file FILE：将日志写入指定文件，特殊值支持 syslog 与 journald；
-V / --version：打印版本号；
-c / --config PATH：配置文件路径。默认在 userdir/config.json 或 config.json 中取存在者；可多次传入实现配置合并（例如"基础配置 + 交易所密钥配置"分文件管理）；传 - 表示从标准输入读取配置；
-d / --datadir / --data-dir PATH：交易所历史回测数据所在基础目录；若要读取期货（futures）数据需同时配合 trading-mode 参数；
--userdir / --user-data-dir PATH：用户数据目录，默认包含 strategies、data、logs 等子目录。

策略参数（Strategy arguments）

-s / --strategy NAME：指定策略类名。实际解析时先在配置查找，再通过 freqtrade/resolvers/strategy_resolver.py 在策略目录中定位并加载对应类；
--strategy-path PATH：追加一个额外策略搜索路径，便于在默认 user_data/strategies 之外存放策略文件；
--recursive-strategy-search：在 strategies 目录中递归搜索策略，适用于多级子目录组织大量策略的仓库；
--freqaimodel NAME 与 --freqaimodel-path PATH：选择自定义 FreqAI 模型类名及其额外查找路径，对应解析器在 freqtrade/resolvers/freqaimodel_resolver.py。

参数如何进入配置：CLI 与配置文件的合并规则

所有命令行参数最终都会经过 freqtrade/configuration/configuration.py 中的 Configuration 类处理。该类的 get_config()（入口见 class Configuration，L34）按顺序执行多步 _process_* 处理，其中两个方法与本主题关系最密切：

_process_common_options（L161）：把 --strategy、--strategy-path、--db-url 等参数写入配置字典。例如只有当命令行传入的 db_url 存在且不等于生产默认 URL 时才执行覆盖（L170-L176），从而避免误把显式设置的默认 URL 当成"用户意图"；
_process_runmode（L463-L475）：将 --dry-run 写入配置后推断运行模式：

self.runmode = RunMode.DRY_RUN if config.get("dry_run", True) else RunMode.LIVE

可见 dry_run 在配置缺失时默认取 True，即缺省更倾向安全的模拟盘，只有显式配置 "dry_run": false 才会进入实盘。除 CLI 参数外，freqtrade 还支持用 FREQTRADE__* 前缀的环境变量覆盖任意配置项，多份 -c 文件、CLI 参数、环境变量的优先级关系需要在部署前仔细核对。

Dry Run 与 Live：两种运行模式的默认行为差异

--dry-run 帮助文本指出它会"removes Exchange secrets and simulates trades"——即模拟盘模式下交易所密钥不会被使用、也不会发生真实下单，所有撮合由 freqtrade 本地模拟完成。

与之配套的两个默认行为差异尤其值得注意：

数据库默认不同。freqtrade/constants.py 定义了两条默认数据库 URL：

DEFAULT_DB_PROD_URL = "sqlite:///tradesv3.sqlite"
DEFAULT_DB_DRYRUN_URL = "sqlite:///tradesv3.dryrun.sqlite"

Configuration._process_trading_options（L145-L159）负责在二者之间切换：当 dry_run 开启且用户没有自定义 db_url（或仍为生产默认）时，自动把数据库替换为 tradesv3.dryrun.sqlite，确保模拟盘交易记录与实盘彻底隔离；当实盘模式下未指定 db_url 时则落到生产默认 sqlite:///tradesv3.sqlite。日志中会通过 parse_db_uri_for_logging 对连接串脱敏后再打印，避免泄露凭证。

费率（fee）的模拟方式不同。在 freqtrade/exchange/exchange.py 中可以看到，当处于 dry_run 且配置了 fee 时，模拟盘直接使用该费率计算手续费：

if self._config["dry_run"] and self._config.get("fee", None) is not None:
    return self._config["fee"]

而实盘模式下会优先采用交易所实际返回的订单手续费结构。这正是 --fee 帮助文本强调"Will be applied twice (on trade entry and exit)"的原因——开仓与平仓各计一次，最终收益表现会同时受两次费率影响。配置项 fee 的 schema 约束为 0 ~ 0.1（即最高 10%），官方描述也说明它可以用来"在回测中模拟滑点"，见 freqtrade/config_schema/config_schema.py。

起始资金与费率在回测、超参、Dry Run 中的一致语义

--dry-run-wallet / --starting-balance 并非只在模拟盘生效，而是与回测（backtesting）和超参优化（hyperopt）共用同一个钱包语义。配置项默认值定义于 freqtrade/constants.py：

DRY_RUN_WALLET = 1000

config schema（L95-L101）允许两种形态：

单个数字（如 "dry_run_wallet": 1000）；
按币种区分的对象，例如 {"BTC": 0.5, "USDT": 1000}，用于多币种钱包模拟（schema 中 patternProperties 限制键名为字母数字串、值为数字）。

命令行传入的 --dry-run-wallet 会经 _args_to_config 覆盖该配置项（日志形如 "Parameter --dry-run-wallet detected, overriding dry_run_wallet to: ..."，见 configuration.py L304-L305）。在测试体系中可以找到大量佐证：例如 tests/freqtradebot/test_freqtradebot.py 与 tests/freqtradebot/test_integration.py 均以 default_conf_usdt["dry_run_wallet"] = ... 设定资金来验证仓位与风控逻辑。由于同一资金语义贯穿"回测—优化—模拟盘"，你在回测中验证过的资金规模行为可以直接平移用于 Dry Run 试运行。

--sd-notify 与 systemd：守护进程化的标准姿势

--sd-notify 让 freqtrade 以 systemd sd_notify 协议向服务管理器上报状态，从而支持 Type=notify、看门狗（watchdog）等机制。对应实现位于 freqtrade/worker.py：当配置 internals.sd_notify 开启时，Worker 创建 sdnotify.SystemdNotifier，并在各生命周期节点发送通知：

初始化完成 → READY=1；
状态切换/节流前 → WATCHDOG=1 + STATUS=State: RUNNING/PAUSED/STOPPED；
重载配置 → RELOADING=1，完成后再次 READY=1；
退出 → STOPPING=1。

仓库根目录自带两个可直接参考的 systemd 单元文件：freqtrade.service 与 freqtrade.service.watchdog。其中 watchdog 版本适合搭配 systemd 的 WatchdogSec= 使用：如果机器人在心跳周期内未能上报，systemd 将判定进程无响应并自动重启。心跳间隔与节流周期均可通过配置的 internals 段调整（heartbeat_interval 默认 60 秒，节流见下文）。

Worker 状态机：trade 进程启动后到底在做什么

freqtrade trade 的参数解析只是入口，真正的常驻逻辑由 Worker 驱动。理解 freqtrade/worker.py 的状态机有助于判断"进程为什么看起来在空转"以及如何优雅重启：

run() 是一个无限循环，每轮调用 _worker(old_state) 并根据返回状态决定是否 _reconfigure()（即热重载配置后重建 FreqtradeBot 实例）；
Worker 内部维护 State 状态机（RUNNING / PAUSED / STOPPED / RELOAD_CONFIG，枚举定义见 freqtrade/enums/state.py）。状态从非运行态切换到 RUNNING/PAUSED 时会执行 freqtrade.startup()，进入 STOPPED 时会检查未平仓订单；
每个节流周期默认 5 秒（PROCESS_THROTTLE_SECS，见 constants.py L17），即 _worker 每轮执行一次 freqtrade.process() 后睡眠到节流点。若配置了 timeframe，节流会进一步对齐到"下一根 K 线生成后 +1 秒"（worker.py L168-L177），确保每次处理都能拿到最新 K 线；
处理过程中若抛 TemporaryError 会在 RETRY_TIMEOUT 后重试；若抛出 OperationalException，则通过 RPC 发送异常通知并将状态置为 STOPPED，提示"Issue /start if you think it is safe to restart"（worker.py L197-L212）；
每 heartbeat_interval（默认 60 秒）会输出一条包含 PID、版本号与状态的 "Bot heartbeat" 日志，可作为监控探针。

此外，start_trading 中把 SIGTERM 转成 KeyboardInterrupt（trade_commands.py L16-L24），意味着 systemctl stop、kill 或 Ctrl-C 都会走同一套优雅退出路径：通知 STOPPING=1、发送 "process died" 状态、调用 worker.exit() 与 freqtrade.cleanup() 清理资源（worker.py L233-L239）。远程控制方面，Telegram/WebUI 的 /stop、/reload_config、/start 等指令会驱动状态机在上述状态间迁移，从而实现不重启进程的配置热更新。

完整可用的启动示例

综合以上规则，一个典型的模拟盘启动命令如下：

freqtrade trade \
  --config config.json \
  --config config-private.json \
  --strategy MyStrategy \
  --dry-run \
  --dry-run-wallet 1000 \
  --db-url sqlite:///user_data/tradesv3.dryrun.sqlite \
  -vv \
  --logfile user_data/logs/freqtrade.log

要点解读：

两份 -c：一份公开基础配置、一份含交易所密钥的私有配置，便于版本管理时避免密钥入库；
--dry-run --dry-run-wallet 1000：先以 1000 起始资金模拟运行，观察策略信号与资金曲线是否符合预期；
--db-url：把模拟盘数据库显式放到 user_data 下便于查阅（若不指定，默认即落在 user data 目录的 tradesv3.dryrun.sqlite）；
-vv --logfile：详细日志落盘，便于排查启动或运行期问题。

确认模拟盘表现稳定后，将配置中 "dry_run": false 并配置真实 API 密钥即可切换实盘（freqtrade 会校验密钥有效性，缺少必要密钥时将拒绝启动）。若要以 systemd 托管，可参考仓库根目录的 freqtrade.service / freqtrade.service.watchdog 单元文件，并在 ExecStart 中加入 --sd-notify。

源码与测试佐证：如何在仓库内继续深挖

入口与参数注册：freqtrade/commands/arguments.py（trade 子命令注册）、freqtrade/commands/trade_commands.py（start_trading）；
CLI 选项定义：freqtrade/commands/cli_options.py 与 L260-L265；
配置处理与默认值：freqtrade/configuration/configuration.py、freqtrade/constants.py、freqtrade/config_schema/config_schema.py；
主循环状态机：freqtrade/worker.py；
单元测试：tests/commands/test_commands.py 中的 test_start_trading_fail 直接以 ["trade", "-c", "tests/testdata/testconfigs/main_test_config.json"] 构造参数并调用 start_trading(get_args(args))，验证了从 argparse 到交易入口的整条调用链及异常退出路径；tests/freqtradebot/test_freqtradebot.py 等用例则反复以 dry_run_wallet 设定资金来验证机器人的实际行为。

如果需要在命令行层面继续验证其他子命令（download-data、backtesting、hyperopt 等）的差异，可阅读 docs/commands/main.md 与 docs/bot-usage.md 中的总体说明；--logfile 的 syslog / journald 特殊值以及期货数据所需 trading-mode 的细节，可在 docs/configuration.md 中查阅对应章节。