- freqtrade 速读指南
- 配置文件解析
本章将深入探讨 Freqtrade 配置文件的结构和各项参数的含义，帮助理解如何通过配置文件控制机器人的行为。我们将从配置文件的基本结构入手，逐步讲解交易所连接、交易参数设置和路径配置等关键内容，并通过实际示例展示如何根据自己的需求定制配置。
Freqtrade 的配置文件采用 JSON 格式，这是一种轻量级的数据交换格式，易于阅读和编写。一个完整的配置文件通常包含多个部分，每个部分负责配置机器人不同方面的功能。理解配置文件的整体结构，是正确设置和调试机器人的基础。
JSON 文件由键值对组成，使用大括号 {} 包裹，键和值之间用冒号 : 分隔，键值对之间用逗号 , 分隔。值可以是字符串、数字、布尔值、数组或嵌套的 JSON 对象。Freqtrade 的配置文件充分利用了 JSON 的这些特性，将不同类别的配置参数组织在不同的键下。
以下是一个简化的配置文件示例，展示了最基本的结构：
{
"max_open_trades": 3,
"stake_currency": "USDT",
"stake_amount": 100,
"dry_run": true,
"exchange": {
"name": "binance",
"api_key": "your_api_key",
"secret": "your_api_secret"
},
"minimal_roi": {
"0": 0.1
},
"stoploss": -0.05
}
在这个示例中，我们可以看到顶级配置项如 max_open_trades、stake_currency，以及嵌套的配置项如 exchange 对象。这种层次化的结构使得配置文件清晰易读，也方便按类别查找和修改参数。
Freqtrade 的配置文件还支持注释，这在标准 JSON 中是不允许的，但 Freqtrade 对解析器进行了扩展，允许使用 // 进行单行注释和 /* */ 进行多行注释。这极大地提高了配置文件的可读性，方便我们添加注释说明各个参数的用途。
Freqtrade 的配置系统支持多种配置来源，包括默认配置、配置文件、环境变量和命令行参数。这些配置来源按照一定的优先级进行合并，优先级从低到高依次为：
-c/--config 指定的配置文件，可以指定多个FREQTRADE__ 为前缀的环境变量这种优先级机制非常灵活，允许我们在不同场景下方便地覆盖配置。例如，我们可以在配置文件中设置基本参数，然后通过命令行参数临时修改某些参数，而无需修改配置文件本身。
举个例子，假设配置文件中设置 max_open_trades: 3，而我们在命令行中执行：
freqtrade trade --config config.json --max-open-trades 5
此时，最终生效的 max_open_trades 值将是 5，因为命令行参数的优先级高于配置文件。
Freqtrade 支持同时加载多个配置文件，这一特性在实际使用中非常有用。最常见的场景是将公共配置和私密信息分离，例如将 API 密钥等敏感信息存储在单独的配置文件中，而将其他公共配置存储在主配置文件中。
使用多个配置文件的方法有两种：一是在命令行中多次使用 -c/--config 选项，二是在主配置文件中通过 add_config_files 参数指定额外的配置文件。
命令行方式：
freqtrade trade -c config.json -c secrets.json
配置文件方式：
在主配置文件（如 config.json）中添加：
{
"add_config_files": [
"secrets.json"
],
// 其他配置参数...
}
当加载多个配置文件时，后面的配置文件会覆盖前面配置文件中的同名参数。这种机制允许我们构建模块化的配置，例如创建一个基础配置文件，然后为不同的策略或不同的交易环境创建专门的配置文件，在运行时根据需要组合使用。
Freqtrade 在启动时会对配置文件进行验证，确保所有必要的参数都已设置，并且参数值符合要求。如果配置文件中存在错误，机器人会拒绝启动并显示相应的错误信息，帮助我们定位问题。
常见的配置错误包括：
stake_currency、exchange.name 等）stoploss 设置为正数）当遇到配置错误时，Freqtrade 的错误信息通常会指出具体的问题所在，例如：
Invalid configuration. Please check the log for details.
Error: 'stake_currency' is required
为了避免配置错误，建议使用 freqtrade show-config 命令在启动机器人前验证配置。这个命令会显示合并后的最终配置，并隐藏敏感信息，帮助我们确认配置是否符合预期。
交易所配置是 Freqtrade 配置文件中最重要的部分之一，它决定了机器人如何连接和与加密货币交易所交互。正确配置交易所参数是确保机器人能够正常交易的前提。
要连接到交易所进行交易，Freqtrade 需要使用交易所提供的 API 密钥。这些密钥通常包括 api_key（API 密钥）和 secret（API 密钥密码），有些交易所还可能需要 password 或 uid 等额外信息。
在配置文件中，交易所相关的参数都放在 exchange 对象下：
"exchange": {
"name": "binance",
"api_key": "your_api_key_here",
"secret": "your_api_secret_here",
// 其他交易所参数...
}
重要安全提示：API 密钥相当于交易所账户密码，必须妥善保管，绝对不要分享给他人或提交到代码仓库中。建议将包含 API 密钥的配置文件设置为仅自己可见的权限（如 chmod 600 secrets.json），并使用多配置文件功能将敏感信息与公共配置分离。
获取 API 密钥的步骤因交易所而异，但通常包括：
Freqtrade 允许通过配置文件指定交易对的白名单和黑名单，控制机器人可以交易哪些币种。这一功能在策略开发和实盘交易中都非常有用，可以帮助我们过滤掉不感兴趣或高风险的交易对。
白名单设置：
"exchange": {
// 其他参数...
"pair_whitelist": [
"BTC/USDT",
"ETH/USDT",
"BNB/USDT",
"SOL/USDT"
]
}
pair_whitelist 是一个字符串数组，每个元素是一个交易对符号，格式为 BASE/QUOTE，其中 BASE 是基础货币，QUOTE 是计价货币（通常是我们设置的 stake_currency）。
黑名单设置：
"exchange": {
// 其他参数...
"pair_blacklist": [
"DOGE/USDT",
"SHIB/USDT"
]
}
pair_blacklist 用于指定机器人绝对不应该交易的交易对。如果一个交易对同时出现在白名单和黑名单中，黑名单的优先级更高，机器人将不会交易该对。
除了静态的黑白名单，Freqtrade 还支持通过插件系统实现动态交易对选择，例如基于交易量或价格变化自动调整交易对列表。这部分内容我们将在后续章节中详细介绍。
不同的交易所可能有其特定的 API 行为或限制，Freqtrade 通过 ccxt_config、ccxt_sync_config 和 ccxt_async_config 参数允许我们传递额外的配置给底层的 CCXT 库（Freqtrade 使用 CCXT 库与交易所交互）。
"exchange": {
// 其他参数...
"ccxt_config": {
"enableRateLimit": true,
"options": {
"defaultType": "spot"
}
},
"ccxt_sync_config": {},
"ccxt_async_config": {}
}
ccxt_config 中的参数会同时应用于同步和异步的 CCXT 实例，而 ccxt_sync_config 和 ccxt_async_config 则分别用于同步和异步实例的特定配置。
常见的 CCXT 配置参数包括：
enableRateLimit: 是否启用速率限制（建议设为 true，避免触发交易所 API 限制）options.defaultType: 默认交易类型（如 spot、future 等）options.apiKey/options.secret: 也可以在这里设置 API 密钥，但建议使用 Freqtrade 的 api_key 和 secret 参数不同交易所支持的 CCXT 配置参数可能不同，详细信息可以参考 CCXT 官方文档。
Freqtrade 支持通过 WebSocket 连接接收实时市场数据，这可以提高数据更新的速度和减少 API 调用次数。相关的配置参数包括：
"exchange": {
// 其他参数...
"enable_ws": true,
"markets_refresh_interval": 60
}
enable_ws: 是否启用 WebSocket 连接（默认为 true）markets_refresh_interval: 市场信息（如交易对列表、手续费等）的刷新间隔（分钟），默认为 60 分钟启用 WebSocket 通常可以提高机器人对市场变化的响应速度，特别是在使用较短时间框架的策略时。不过，在某些网络环境下，WebSocket 连接可能不稳定，这时可以将 enable_ws 设置为 false，改用定期 API 轮询的方式获取数据。
交易参数决定了机器人的交易行为，包括每次交易的金额、最大持仓数量、止盈止损设置等。合理配置这些参数对于策略的表现至关重要。
最大持仓数量（max_open_trades）
max_open_trades 参数控制机器人可以同时持有的最大交易数量：
"max_open_trades": 5
这个参数的设置需要根据策略特性、可用资金和交易对数量综合考虑。值越大，机器人可以同时交易的币种越多，但也可能导致资金过度分散，增加管理难度。如果设置为-1，则表示不限制持仓数量（受交易对列表限制）。
交易货币与金额（stake_currency 与 stake_amount）
stake_currency 指定用于交易的计价货币：
"stake_currency": "USDT"
stake_amount 则指定每次交易投入的资金量，可以是固定金额或"unlimited"（动态分配）：
// 固定金额
"stake_amount": 100
// 动态分配
"stake_amount": "unlimited"
当设置为"unlimited"时，机器人会根据当前可用资金和 max_open_trades 动态计算每次交易的金额。例如，如果可用资金为 1000 USDT，max_open_trades 为 5，则每次交易大约投入 200 USDT（不考虑手续费和已持仓资金）。
可用资金比例（tradable_balance_ratio）
tradable_balance_ratio 控制机器人可以使用的资金比例，默认为 0.99（99%）：
"tradable_balance_ratio": 0.95
这个参数的作用是预留一部分资金作为缓冲，避免因手续费或价格波动导致的资金不足问题。例如，设置为 0.95 表示机器人最多使用账户中 95% 的资金进行交易。
最低回报率（minimal_roi）
minimal_roi（Return On Investment）定义了机器人的止盈策略，它是一个字典，键为时间（分钟），值为该时间后所需的最低回报率（比例）：
"minimal_roi": {
"60": 0.01,
"30": 0.02,
"0": 0.05
}
这个配置的含义是：
minimal_roi 的设计非常灵活，可以根据不同策略的时间特性设置不同的止盈目标。如果某个时间点的回报率达到或超过设定值，机器人就会执行平仓操作。
止损设置（stoploss）
stoploss 参数定义了允许的最大亏损比例（负数表示亏损）：
"stoploss": -0.05
设置为-0.05 表示当交易亏损达到 5% 时，机器人将执行止损平仓。止损是风险管理的重要工具，可以有效限制单次交易的最大损失。
Freqtrade 还支持更高级的追踪止损功能，通过以下参数配置：
"trailing_stop": true,
"trailing_stop_positive": 0.02,
"trailing_stop_positive_offset": 0.05,
"trailing_only_offset_is_reached": true
trailing_stop: 是否启用追踪止损trailing_stop_positive: 正的追踪止损阈值（比例）trailing_stop_positive_offset: 启动追踪止损前需要达到的盈利比例trailing_only_offset_is_reached: 是否只在达到 trailing_stop_positive_offset 后才启用追踪止损这些参数的组合可以实现复杂的止损策略，例如"当盈利达到 5% 后，启动追踪止损，允许利润回吐 2%"。
订单类型（order_types）
order_types 参数允许为不同的交易动作指定订单类型（如市价单、限价单等）：
"order_types": {
"entry": "limit",
"exit": "limit",
"stoploss": "market",
"stoploss_on_exchange": false
}
常见的订单类型包括：
market: 市价单，按当前市场价格立即成交limit: 限价单，按指定价格或更优价格成交stop: 止损单，价格达到指定水平时转为市价单stoploss_on_exchange 参数控制是否将止损单直接下到交易所，这可以提高止损的执行速度，尤其是在市场剧烈波动时。
订单超时设置（unfilledtimeout）
unfilledtimeout 参数定义了未成交订单的超时时间：
"unfilledtimeout": {
"entry": 30,
"exit": 30,
"unit": "minutes",
"exit_timeout_count": 3
}
entry: 入场订单超时时间exit: 出场订单超时时间unit: 时间单位（"minutes"或"seconds"）exit_timeout_count: 出场订单允许超时的次数，超过后触发紧急平仓设置合理的订单超时时间可以避免订单长时间未成交导致的资金占用问题，尤其是在市场流动性较低的交易对上。
timeframe 参数指定策略使用的 K 线时间框架：
"timeframe": "1h"
常见的时间框架包括：
1m: 1 分钟5m: 5 分钟15m: 15 分钟1h: 1 小时1d: 1 天时间框架的选择取决于策略的类型，短线策略通常使用较小的时间框架（如 5m、15m），而长线策略则使用较大的时间框架（如 1h、1d）。
需要注意的是，timeframe 参数也可以在策略代码中设置，配置文件中的设置会覆盖策略中的设置。
Freqtrade 使用多个目录存储数据、日志、策略和配置文件。正确配置这些路径可以帮助我们更好地组织和管理机器人的相关文件。
user_data_dir 参数指定用户数据的根目录，默认为当前工作目录下的 user_data：
"user_data_dir": "./user_data"
用户数据目录下通常包含以下子目录：
strategies: 存储策略文件data: 存储历史市场数据logs: 存储日志文件hyperopts: 存储超参数优化结果backtesting: 存储回测结果自定义 user_data_dir 路径可以将用户数据与 Freqtrade 程序文件分离，方便备份和管理。例如，可以将其设置为外部硬盘上的路径，或云存储同步目录。
Freqtrade 使用数据库存储交易记录、策略性能等信息。db_url 参数指定数据库连接 URL：
// SQLite数据库（默认）
"db_url": "sqlite:///tradesv3.sqlite"
// PostgreSQL数据库
"db_url": "postgresql://user:password@localhost:5432/freqtrade"
默认情况下，Freqtrade 使用 SQLite 数据库，数据库文件存储在用户数据目录下。对于需要更高性能或多机器人共享数据的场景，可以配置为使用 PostgreSQL 或 MySQL 等数据库。
注意：如果启用了 dry_run 模式，默认的数据库文件名会变为 tradesv3.dryrun.sqlite，避免与实盘交易数据混淆。
logfile 参数指定日志文件的路径和名称：
"logfile": "user_data/logs/freqtrade.log"
Freqtrade 采用滚动日志策略，默认保留 10 个日志文件，每个文件最大 1MB。日志文件包含了机器人的运行信息、交易记录和错误信息，是调试和分析机器人行为的重要依据。
除了文件日志，Freqtrade 还会在控制台输出日志信息。可以通过 log_config 参数自定义日志的格式和级别，但对于大多数用户来说，默认配置已经足够使用。
Freqtrade 支持多种格式存储历史市场数据，通过 dataformat_ohlcv 和 dataformat_trades 参数配置：
"dataformat_ohlcv": "feather",
"dataformat_trades": "feather"
支持的数据格式包括：
json: JSON 格式，可读性好，但文件较大feather: Feather 格式，二进制格式，读写速度快，文件较小hdf5: HDF5 格式，适合存储大量数据默认使用 Feather 格式，这是一种高效的列式存储格式，兼顾了读写性能和文件大小。如果需要与其他工具共享数据，可以考虑使用 JSON 格式。
Freqtrade 在启动时会搜索指定路径下的策略文件。strategy_path 参数允许添加额外的策略搜索路径：
"strategy_path": "./my_strategies"
此外，recursive_strategy_search 参数控制是否递归搜索子目录中的策略文件：
"recursive_strategy_search": true
这些参数使得组织多个策略文件变得更加灵活，例如可以按策略类型或版本创建不同的子目录。
配置文件是 Freqtrade 的核心，它集中了控制机器人行为的所有参数。本章详细介绍了配置文件的结构、交易所设置、交易参数和路径配置等关键内容。掌握这些知识，将能够根据自己的交易需求定制 Freqtrade 的行为，为后续的策略开发和优化打下坚实基础。在下一章中，我们将学习如何获取和管理市场数据，这是策略回测和实盘交易的基础。