- freqtrade 速读指南
- 熟悉命令行界面
本章将全面掌握 Freqtrade 的命令行操作，从基础命令结构到高级配置查看，再到版本管理技巧。通过实际操作示例，将学会如何高效地与 Freqtrade 机器人交互，执行交易、回测、数据下载等核心功能，为后续策略开发和优化打下坚实基础。
Freqtrade 作为一款命令行驱动的量化交易框架，所有功能都通过命令来触发。掌握这些命令的基本结构和常用参数，是使用 Freqtrade 的第一步。就像学习一门编程语言先了解语法规则一样，熟悉命令行界面的操作逻辑，能在后续使用中事半功倍。
Freqtrade 的命令遵循统一的结构，基本格式如下：
freqtrade [全局选项] <命令> [命令选项]
这个结构可以分为三个部分：全局选项、命令本身和命令选项。全局选项影响所有命令的行为，比如 -V 或 --version 用于查看版本信息；命令是具体要执行的操作，如 trade 启动交易、backtesting 进行回测；命令选项则是针对该命令的特定参数，比如 --strategy 指定使用哪个策略。
举个实际例子，启动交易机器人并指定配置文件和策略：
freqtrade trade -c config.json --strategy MyAwesomeStrategy
这里 trade 是核心命令，-c config.json 是命令选项（指定配置文件），--strategy MyAwesomeStrategy 也是命令选项（指定交易策略）。
Freqtrade 提供了丰富的命令集，涵盖从数据下载到策略回测再到实际交易的全流程。我们先对常用命令做个整体了解，后续会深入讲解关键命令的使用细节。
通过 freqtrade -h 可以查看所有可用命令，主要包括以下几类：
交易相关
trade: 启动交易机器人，是最核心的命令show-trades: 查看历史交易记录test-pairlist: 测试交易对列表配置数据相关
download-data: 下载历史 K 线数据convert-data: 转换数据格式list-data: 列出已下载的数据trades-to-ohlcv: 将交易数据转换为 K 线数据策略与回测
new-strategy: 创建新策略模板backtesting: 策略回测backtesting-show: 查看回测结果hyperopt: 策略参数优化配置与管理
create-userdir: 创建用户数据目录new-config: 生成新配置文件show-config: 查看当前配置install-ui: 安装 FreqUI 界面信息查询
list-exchanges: 列出支持的交易所list-pairs: 列出交易所可用交易对list-strategies: 列出可用策略list-timeframes: 列出支持的时间框架这个命令列表看起来很多，但日常使用频率高的也就那么几个。接下来我们重点介绍几个最常用的命令。
trade 命令是启动 Freqtrade 交易机器人的入口，也是我们使用最频繁的命令之一。其基本用法如下：
freqtrade trade [选项]
常用选项包括：
-c/--config: 指定配置文件路径--strategy: 指定要使用的策略类名--strategy-path: 添加额外的策略文件搜索路径--dry-run: 启动干跑模式，不实际下单--db-url: 指定数据库连接 URL--userdir: 指定用户数据目录例如，启动干跑模式并使用特定策略：
freqtrade trade --dry-run --strategy SampleStrategy -c config_dry.json
这个命令会加载 config_dry.json 配置文件，使用 SampleStrategy 策略，在干跑模式下启动机器人。干跑模式非常重要，它会模拟交易而不实际连接交易所下单，是测试策略的安全方式。
需要注意的是，启动交易前必须确保配置文件中的交易所 API 密钥正确（实盘模式），或者使用干跑模式（无需 API 密钥）。如果 API 密钥错误，机器人将无法连接交易所，会在日志中显示认证失败的错误信息。
在进行策略回测前，我们需要获取历史市场数据，这就需要用到 download-data 命令。其基本用法：
freqtrade download-data [选项]
核心选项：
-p/--pairs: 指定要下载的交易对，多个交易对用逗号分隔-t/--timeframes: 指定时间框架，多个时间框架用逗号分隔--days: 下载数据的天数--startdate/--enddate: 指定开始/结束日期（格式 YYYYMMDD）-c/--config: 指定配置文件（用于获取交易所信息）示例，下载 BTC/USDT 和 ETH/USDT 的 1 小时和 4 小时数据，共 30 天：
freqtrade download-data -p BTC/USDT,ETH/USDT -t 1h,4h --days 30 -c config.json
这个命令会从配置文件中指定的交易所下载数据，并保存到用户数据目录下的 data 文件夹中。默认情况下，数据以 JSON 格式存储，文件名包含交易对、时间框架和日期范围信息。
下载数据时要注意几个问题：首先，不同交易所支持的时间框架可能不同，大部分交易所支持 1 分钟、5 分钟、1 小时、1 天等标准时间框架；其次，数据量较大时下载可能需要较长时间，建议先测试小范围数据下载；最后，确保网络连接稳定，中断后可能需要重新下载。
策略编写完成后，需要通过历史数据回测来评估其表现，这就要用到 backtesting 命令。基本用法：
freqtrade backtesting [选项]
关键选项：
--strategy: 指定要回测的策略-i/--timerange: 指定回测时间范围--timeframe: 指定回测使用的时间框架--stats-file: 指定回测结果保存文件--processes: 指定用于回测的进程数（加速回测）示例，回测 SampleStrategy 策略在 2023 年 1 月的 1 小时数据：
freqtrade backtesting --strategy SampleStrategy -i 20230101-20230131 --timeframe 1h
回测完成后，会显示详细的统计结果，包括总交易次数、胜率、盈亏比、最大回撤等关键指标。这些指标是评估策略优劣的重要依据。
回测命令还有很多高级选项，比如 --eps 启用每步模拟（更精确但速度慢）、--enable-position-stacking 允许同一策略在同一时间持有多个头寸等。随着对 Freqtrade 的深入使用，我们会逐渐掌握这些高级功能。
Freqtrade 提供了完善的帮助系统，无论对哪个命令不熟悉，都可以通过帮助系统快速了解其用法。掌握如何高效使用帮助系统，能在使用 Freqtrade 时更加独立自主，减少对外部文档的依赖。
在命令行中输入 freqtrade -h 或 freqtrade --help，可以获取全局帮助信息，包括所有可用命令和全局选项：
freqtrade -h
输出内容结构清晰，首先是命令格式，然后是位置参数（即各个命令），最后是全局选项。这种结构设计符合类 Unix 命令的风格，熟悉 Linux 命令的用户会感到很亲切。
全局帮助最有用的部分是命令列表，它简要描述了每个命令的功能。当忘记某个命令的具体名称时，这里可以快速查阅。例如，想不起下载数据的命令时，看到 download-data 及其描述“Download backtesting data.”就知道这是你需要的。
对于具体命令的详细用法，可以在命令后添加 -h 或 --help 参数。例如，要了解 trade 命令的所有选项：
freqtrade trade -h
这会显示 trade 命令的详细帮助信息，包括所有可用选项、选项说明和使用示例。输出内容通常分为几个部分：选项说明、示例用法（如果有）、以及相关提示。
命令帮助中的选项说明非常详细，包括选项的全称和缩写形式、是否需要参数、参数类型以及选项的具体含义。例如：
-c CONFIG, --config CONFIG
Specify configuration file (default: config.json). Multiple --config options may be used.
这段说明告诉我们，-c 是 --config 的缩写形式，需要一个参数（配置文件路径），默认值是 config.json，并且可以多次使用该选项指定多个配置文件。
学会解读帮助信息是使用命令行工具的关键技能。Freqtrade 的帮助信息遵循统一的格式，掌握这种格式能快速提取所需信息。
以 backtesting 命令的帮助信息为例，我们来看看如何解读：
usage: freqtrade backtesting [-h] [-v] [--logfile FILE] [-V] [-c CONFIG] [--userdir USERDIR] [-s STRATEGY] [--strategy-path STRATEGY_PATH] [-i TIMERANGE] [--timeframe TIMEFRAME] [--timerange-from TIMERANGE_FROM] [--timerange-to TIMERANGE_TO] [--max-open-trades MAX_OPEN_TRADES] [--stake-amount STAKE_AMOUNT] [--fee FEE] [--initial-wallet INITIAL_WALLET] [--dry-run-wallet DRY_RUN_WALLET] [--disable-max-market-positions] [--strategy-list STRATEGY_LIST] [--export EXPORT] [--export-filename EXPORT_FILENAME] [--export-json EXPORT_JSON] [--stats-file STATS_FILE] [--processes PROCESSES] [--no-timeout] [--eps] [--enable-position-stacking] [--disable-position-stacking] [--cache] [--forcebuy] [--breakdown] [--trade-source {file,db,exchange}] [--trade-source-path TRADE_SOURCE_PATH]
这是 backtesting 命令的使用格式，列出了所有可用选项。虽然看起来很长，但每个选项都有其特定用途。我们可以根据需要查找相关选项，不必一次记住所有内容。
帮助信息中的方括号 [] 表示可选参数，尖括号 <> 表示必选参数（不过在 Freqtrade 中大部分参数都是可选的）。竖线 | 表示“或”的关系，例如 [-h | --help] 表示这两个选项功能相同。
在实际使用中，我建议养成随时查阅帮助的习惯。遇到不确定的选项时，不要凭记忆猜测，而是通过 -h 查看准确说明，这样可以避免因参数错误导致的问题。
除了主动查阅帮助，Freqtrade 的错误信息也是学习命令使用的重要资源。当命令执行出错时，终端会显示错误信息，这些信息通常会指出问题所在，并给出解决建议。
例如，如果忘记指定策略就运行回测：
freqtrade backtesting
会得到类似以下错误：
Error: --strategy must be specified when not using config strategy.
这个错误信息清晰地告诉我们需要使用 --strategy 选项指定策略。Freqtrade 的错误提示通常都比较友好，包含具体的错误原因和解决方法，认真阅读错误信息能快速定位问题。
另一个常见错误是配置文件不存在：
Could not find config file 'nonexistent.json'. Please create a config file or check the path.
错误信息直接指出了文件不存在，并建议检查路径或创建配置文件。这种情况下，我们应该检查文件名拼写是否正确，或者文件是否确实在指定路径下。
Freqtrade 的行为主要通过配置文件控制，理解如何查看和管理配置是使用 Freqtrade 的关键。配置文件包含交易所连接信息、交易参数、策略设置等重要内容，掌握配置查看技巧能帮助确认当前设置是否正确，排查配置相关问题。
show-config 命令用于显示当前生效的配置，它会合并所有指定的配置文件，并展示最终的配置结果。基本用法：
freqtrade show-config [选项]
常用选项包括 -c/--config 指定配置文件，--dump 以 JSON 格式输出完整配置。
例如，查看默认配置：
freqtrade show-config
这会显示合并后的配置，按类别组织，如 exchange、dry_run、stake_currency 等。输出内容会隐藏敏感信息（如 API 密钥），用 *** 代替，确保安全。
show-config 命令非常有用，尤其是在使用多个配置文件时，可以确认配置是否按预期合并。例如，我们可以创建一个基础配置文件和一个包含 API 密钥的私密配置文件，然后用 show-config 验证合并结果：
freqtrade show-config -c config.json -c secrets.json
这会显示合并后的配置，让我们确认私密配置是否正确覆盖了基础配置中的相关项。
Freqtrade 支持同时指定多个配置文件，配置参数会按顺序合并，后面的配置文件会覆盖前面的同名参数。这种机制非常灵活，允许我们将配置分离，比如将公共设置和私密信息分开存储。
基本用法是多次使用 -c/--config 选项：
freqtrade trade -c base_config.json -c private_config.json
在这个例子中，private_config.json 中的参数会覆盖 base_config.json 中的同名参数，其他参数则保持 base_config.json 中的设置。
多配置文件的典型应用场景是分离敏感信息。我们可以创建一个不包含 API 密钥的基础配置文件（可以安全地分享或提交到版本控制），和一个包含 API 密钥的私密配置文件（设置严格的文件权限，不分享）。
例如，base_config.json 可能包含：
{
"dry_run": true,
"stake_currency": "USDT",
"stake_amount": 100,
"timeframe": "1h",
"exchange": {
"name": "binance",
"api_key": "",
"secret": ""
}
}
而 private_config.json 包含：
{
"exchange": {
"api_key": "your_actual_api_key",
"secret": "your_actual_secret"
}
}
运行时同时指定这两个文件，Freqtrade 会合并它们，使用 private_config.json 中的 API 密钥。这种方式既方便分享基础配置，又保护了敏感信息。
Freqtrade 的配置来源有多个：默认配置、配置文件、命令行参数。它们的优先级从低到高依次是：默认配置 < 配置文件 < 命令行参数。理解这个优先级规则，能准确控制机器人的行为。
-c/--config 指定的配置文件，会覆盖默认配置中的同名参数。如果指定多个配置文件，后面的文件会覆盖前面的。例如，假设配置文件中设置 stake_amount: 100，而命令行中指定 --stake-amount 200，则最终生效的是 200。
这种优先级机制非常有用，允许我们在不修改配置文件的情况下临时调整参数。例如，进行回测时临时修改 max_open_trades 参数：
freqtrade backtesting --strategy MyStrategy --max-open-trades 5
这个命令会使用配置文件中的大部分参数，但将 max_open_trades 临时设置为 5，方便测试不同参数对策略的影响。
配置问题是使用 Freqtrade 时常见的困扰，尤其是当使用多个配置文件或复杂命令行参数时。以下是一些调试配置的实用技巧：
1. 使用 show-config 验证配置
在运行关键命令（如实际交易）前，先用 show-config 验证最终生效的配置，确保所有参数都符合预期。特别是检查交易所设置、API 密钥（虽然会被隐藏，但可以确认是否有值）、交易对列表等关键项。
2. 逐步构建配置
如果配置比较复杂，建议从简单配置开始，逐步添加和修改参数。每次修改后用 show-config 验证，确保修改按预期生效。这种增量式的配置方式可以减少错误排查的难度。
3. 检查配置文件格式
配置文件使用 JSON 格式，JSON 对语法要求严格，逗号、引号等符号的错误都会导致配置加载失败。如果 Freqtrade 启动时报配置错误，可以使用在线 JSON 验证工具（如 jsonlint.com）检查配置文件的语法。
4. 利用日志调试
Freqtrade 启动时会记录配置加载过程，包括加载了哪些配置文件，合并后的配置是什么。如果遇到配置相关问题，可以查看日志文件（默认在 user_data/logs 目录），里面可能有更详细的错误信息。
Freqtrade 作为一个活跃开发的开源项目，不断有新功能和 bug 修复发布。掌握版本管理技巧，能及时获取更新，同时确保系统稳定。版本管理涉及查看当前版本、更新到新版本、以及在不同版本间切换等操作。
要查看当前安装的 Freqtrade 版本，可以使用 --version 选项：
freqtrade --version
输出类似：
freqtrade 2023.9
版本号通常由年份和月份组成，表示发布时间。Freqtrade 的版本策略是大约每月发布一个稳定版，版本号递增。了解当前版本有助于判断是否需要更新，以及在寻求帮助时提供版本信息。
除了版本号，还可以通过 git 命令查看当前代码的提交信息，这在使用开发分支时特别有用：
cd freqtrade
git log -n 1
这会显示最近一次提交的哈希值、作者、日期和提交信息，帮助确认当前代码的确切版本。
保持 Freqtrade 更新可以获得新功能和安全修复。更新方法取决于最初的安装方式，这里我们介绍最常见的两种方式：通过 setup.sh 脚本更新和手动 git 更新。
使用 setup.sh 脚本更新（推荐）
如果使用官方推荐的 setup.sh 脚本安装，更新非常简单：
cd freqtrade
./setup.sh -u
-u 选项表示 update，脚本会自动拉取最新代码、更新依赖，并重新创建虚拟环境。整个过程无需手动干预，非常方便。
手动更新
如果熟悉 git，也可以手动更新代码：
cd freqtrade
# 拉取最新代码
git pull
# 更新依赖
pip install -U -e .[all]
这种方式给你更多控制权，但需要自己处理可能的冲突。如果更新过程中遇到问题，可以使用 git status 查看修改内容，或 git reset --hard 回退到更新前的状态。
更新前建议先查看更新日志（CHANGELOG.md），了解新版本的变化，特别是不兼容的改动。虽然 Freqtrade 团队努力保持向后兼容，但重大更新有时会引入不兼容的变化，需要调整策略或配置。
Freqtrade 有两个主要分支：stable（稳定版）和 develop（开发版）。stable 分支包含经过充分测试的稳定代码，适合生产环境使用；develop 分支包含最新功能，但可能不够稳定，适合想要体验新特性的用户。
切换分支使用 git 命令：
# 切换到stable分支
git checkout stable
# 切换到develop分支
git checkout develop
切换分支后，需要重新安装依赖：
./setup.sh -i
或者手动重新安装：
pip install -e .[all]
选择哪个分支取决于需求。如果主要关注稳定性，希望尽可能减少问题，应该使用 stable 分支；如果想尝试最新功能，并且能够容忍一些潜在的 bug，可以使用 develop 分支。
无论使用哪个分支，都建议定期更新，以获取最新的安全补丁和 bug 修复。对于生产环境，建议在更新后先进行充分测试，再切换到新的版本进行实盘交易。
有时更新后可能会遇到问题，需要回退到之前的版本。使用 git 可以很方便地实现版本回退。首先，查看提交历史：
git log --oneline
这会显示简洁的提交历史，每个提交有一个哈希值和简短描述。找到想要回退到的提交哈希，然后执行：
git checkout <commit_hash>
例如：
git checkout a1b2c3d
回退后，同样需要重新安装依赖，因为不同版本的代码可能依赖不同版本的库。
版本回退是解决更新后问题的有效手段，但这只是临时措施。更好的做法是在 GitHub 上报告问题，帮助开发团队修复 bug，这样就能在未来的版本中安全地更新。
熟练使用命令行不仅需要记住命令，还需要掌握一些效率技巧。这些技巧能减少重复输入，快速找到需要的信息，提高整体工作效率。
对于频繁使用的长命令，可以创建 bash 别名来简化输入。例如，将 freqtrade trade --dry-run --strategy MyStrategy 简化为 ftrade。
编辑 bash 配置文件（通常是<sub>/.bashrc 或</sub>/.zshrc）：
nano ~/.bashrc
添加别名：
alias ftrade='freqtrade trade --dry-run --strategy MyStrategy -c config.json'
保存后，运行 source ~/.bashrc 使别名生效。现在只需输入 ftrade 就能执行那个长命令了。
别名可以根据具体需求定制，比如为不同的策略创建不同的别名，或为回测命令创建别名。合理使用别名能显著减少命令行输入量。
bash 和 zsh 都提供命令历史功能，可以通过上下箭头键浏览之前输入的命令。这对于重复执行相似命令非常有用。
此外，还可以使用 history 命令查看所有历史记录，结合 grep 搜索特定命令：
history | grep freqtrade
这会显示所有包含"freqtrade"的历史命令。找到需要的命令后，可以使用 !n 执行第 n 条历史命令，或 !-n 执行倒数第 n 条命令。
另一个实用技巧是使用 Ctrl+R 进行反向搜索：按下 Ctrl+R 后输入关键词，bash 会搜索包含该关键词的历史命令，找到后按 Enter 执行，或按右箭头键编辑后执行。
Freqtrade 支持命令行参数自动补全，可以通过安装补全脚本启用。虽然设置稍复杂，但启用后能极大提高输入效率。
补全脚本位于 Freqtrade 项目的 scripts 目录下，根据使用的 shell（bash 或 zsh）选择相应的脚本。以 bash 为例：
# 复制补全脚本到bash补全目录
sudo cp scripts/bash-completion/freqtrade /etc/bash_completion.d/
# 重新加载bash补全
source /etc/bash_completion
现在，当输入 freqtrade 并按下 Tab 键时，会自动补全可用命令；输入命令和 - 后按 Tab，会补全可用选项。这能快速了解可用参数，减少拼写错误。
结合 bash 的管道和循环功能，可以对多个交易对或策略进行批量操作。例如，为多个交易对下载数据：
for pair in BTC/USDT ETH/USDT BNB/USDT SOL/USDT;
do
freqtrade download-data -p $pair -t 1h --days 30;
done
这个循环会依次为列出的每个交易对下载 1 小时数据。同样，也可以批量运行多个策略的回测：
for strategy in Strategy1 Strategy2 Strategy3;
do
freqtrade backtesting --strategy $strategy -i 20230101-20230131;
done
批量操作对于比较不同策略或参数设置非常有用，能节省大量重复工作时间。不过使用时要注意控制并发，避免给系统或交易所 API 带来过大负担。
命令行是与 Freqtrade 交互的主要方式，本章详细介绍了 Freqtrade 命令行界面的各个方面，从基础命令结构到高级效率技巧。我们学习了核心命令的用法，如何利用帮助系统解决问题，如何查看和管理配置，以及版本控制的基本操作。这些知识是使用 Freqtrade 进行量化交易的基础，掌握它们能更高效、更自信地使用这个强大的交易框架。
命令行工具虽然不如图形界面直观，但提供了更强大的功能和灵活性。随着使用经验的积累，会发现命令行操作不仅高效，而且能更深入地理解系统的工作原理。下一章我们将学习 Freqtrade 配置文件的详细解析，进一步掌握如何定制机器人的行为。