第 2 章 · 02 配置文件全解

第 2 章 · 02 配置文件全解

本节摘要:freqtrade 几乎所有运行时行为都由一份 JSON 配置驱动——它就是机器人的「大脑」。本节把配置文件的顶层结构、各段职责、以及最关键的若干参数一次讲透:交易所连接(exchange)、计价与下注(stake_currency/stake_amount/max_open_trades)、模拟开关(dry_run)、订单定价(entry_pricing/exit_pricing)、内部行为(internals)。读完本节,你能徒手写一份最小可用的配置,并知道每个关键参数改了会影响什么。

内容来源:原项目文档 docs/configuration.md、config_examples/config_full.json.example,汉化并套用体系化模板。

⚠️ 风险提示:dry_run 是模拟/实盘的总开关——务必在彻底理解每个参数前保持 true。错误的 stake_amount 或 max_open_trades 组合可能让你的全部本金在几分钟内被分仓耗尽。

学习目标

阅读完本节,你应当能够:

1. 列举配置 JSON 的顶层结构与各段职责。
2. 配置 exchange 段:交易所、密钥、交易对范围。
3. 说清 stake_currency、stake_amount、max_open_trades、tradable_balance_ratio 各自管什么。
4. 区分 dry_run 模拟与实盘,知道如何切换。
5. 配置 entry_pricing / exit_pricing 的订单定价策略。
6. 用 new-config 交互生成一份最小可用配置。

一、顶层结构一张图

freqtrade 的 JSON 顶层是若干「段」,每段管一类事:

下面一份「最小可用」配置(只列必填字段):

{
    "max_open_trades": 3,
    "stake_currency": "USDT",
    "stake_amount": 100,
    "tradable_balance_ratio": 0.99,
    "dry_run": true,
    "timeframe": "5m",
    "trading_mode": "spot",
    "strategy": "SampleStrategy",
    "exchange": {
        "name": "binance",
        "key": "",
        "secret": "",
        "pair_whitelist": ["BTC/USDT", "ETH/USDT"]
    },
    "pairlists": [{"method": "StaticPairList"}],
    "bot_name": "my_bot",
    "initial_state": "running"
}
​

二、资金与下注:四个核心参数

这是配置里最该谨慎对待的一段,直接决定「拿多少钱、怎么分」。

💡 算一笔账:若 stake_amount=100、max_open_trades=3,则机器人最多同时占用 300 USDT。配合 available_capital(整账户模拟金额)或真实账户余额,机器人会自动判断仓位够不够。

stake_amount 还支持三种渐进加仓写法(配合 DCA,第 4 章详讲):

"stake_amount": {
    "amount": 100,
    "amount_increase": 50
}
​

新人保持 stake_amount 为单个数字、max_open_trades 不超过 3,先把策略跑顺再扩仓。

三、dry_run:模拟与实盘的总开关

"dry_run": true,
"dry_run_wallet": 1000
​

• dry_run: true —— 模拟模式。机器人会模拟下单、模拟撮合、模拟记账,完全不动真钱。所有盈亏都用 dry_run_wallet(默认 1000)作为虚拟本金计算。
• dry_run: false —— 实盘模式。需要正确填写 exchange.key / exchange.secret,机器人会用真实账户下单。

⚠️ 切换到实盘前:至少跑 1~2 周 Dry-Run,确认 Telegram、订单定价、止损都按预期工作。实盘时务必先用最小金额(如 stake_amount=20),跑通流程再放大。

注意 dry_run 模拟撮合的成交价是「同周期 K 线 Fusion」或「最佳买卖盘」,与真实滑点会有差异——回测好/模拟好不等于实盘好(第 6 章详讲)。

四、exchange 段:连接交易所

"exchange": {
    "name": "binance",
    "key": "your_api_key",
    "secret": "your_api_secret",
    "ccxt_config": {"enableRateLimit": true},
    "ccxt_async_config": {"enableRateLimit": true},
    "pair_whitelist": ["BTC/USDT", "ETH/USDT"],
    "pair_blacklist": ["BNB/.*"]
}
​

• name:交易所名(小写),如 binance、bybit、okx、kraken、gate、hyperliquid。完整列表用 freqtrade list-exchanges。
• key / secret:API 密钥。Dry-Run 模式可以为空(只要交易所不需要私钥就能拉公开行情)。
• ccxt_config / ccxt_async_config:透传给 ccxt 的参数,通常只配 enableRateLimit: true 防止限流。
• pair_whitelist / pair_blacklist:白/黑名单,下一节详讲。这里直接列在 exchange 下只是「静态白名单」的简写,正式用法走 pairlists 段。

合约交易还需加:

"trading_mode": "futures",
"margin_mode": "isolated",
​

且合约交易对命名是 ETH/USDT:USDT(base/quote:settle)。

五、订单定价:entry_pricing 与 exit_pricing

机器人下限价单时,价格怎么定?由这两个段控制:

"entry_pricing": {
    "price_side": "same",
    "use_order_book": true,
    "order_book_top": 1,
    "price_last_balance": 0.0,
    "check_depth_of_market": {"enabled": false, "bids_to_ask_change": 1}
},
"exit_pricing": {
    "price_side": "same",
    "use_order_book": true
}
​

关键点:

• price_side:same 表示买时挂买盘一侧(更划算、可能不成交)、卖时挂卖盘一侧;other 表示跨盘(更激进、易成交)。新人默认 same。
• use_order_book:用订单簿最优价作为限价;关闭则用最近成交价。
• order_book_top:取订单簿第几档(1 是最优档)。

💡 定价影响成交率:same 挂得保守,可能要等几轮才成交(尤其剧烈行情);other 挂得激进,几乎必成交但成本更高。实盘要观察 unfilledtimeout(未成交超时)与定价策略的协同。

六、internals 与 initial_state

internals 段控制循环本身:

"internals": {
    "process_throttle_secs": 5,
    "heartbeat_interval": 60,
    "sd_notify": false
}
​

• process_throttle_secs:循环最小间隔秒(上一节已讲)。
• heartbeat_interval:心跳日志间隔秒,0 关闭。
• sd_notify:是否向 systemd watchdog 发心跳(容器化部署用)。

initial_state:进程启动后的初始状态,running 或 stopped。若你想启动后不立即交易(先观察行情),设 stopped,再用 /start 唤醒。

七、生成与校验配置

不必徒手敲 JSON,用脚手架:

freqtrade new-config
​

它会交互式问交易所、交易模式、是否 Telegram 等,最后生成 user_data/config.json。

配置加载时会做严格 schema 校验:字段类型错、必填缺、取值越界都会直接报错退出。这是 freqtrade 防止「配置笔误导致实盘灾难」的关键护栏。

⚠️ 配置优先级:命令行参数 > 配置 JSON > 策略类属性。同一个参数(如 stake_amount、minimal_roi、stoploss)在 JSON 和策略里都写,JSON 胜出。改策略里的 stoploss 却发现不生效,先检查 JSON 是否覆盖了。

本节要点回顾

1. 顶层结构:trading、exchange、pairlists、entry_pricing、exit_pricing、telegram、api_server、internals 八大段。
2. 资金四参数:stake_currency(计价币)、stake_amount(每单金额)、max_open_trades(并发上限)、tradable_balance_ratio(可用比例)。
3. dry_run:模拟/实盘总开关,Dry-Run 用 dry_run_wallet 虚拟本金;实盘前务必充分模拟。
4. exchange:name 定交易所,key/secret 实盘必填,合约另配 trading_mode/margin_mode 与 base/quote:settle 命名。
5. 定价策略:entry_pricing/exit_pricing 的 price_side(same 保守 / other 激进)与 use_order_book 决定限价单挂价。
6. 优先级:命令行 > JSON > 策略类属性——同一参数多处写时 JSON 覆盖策略,排查「改了不生效」先看这里。

下一节,我们看 pairlists 段如何决定机器人能交易哪些币——白名单与黑名单的完整机制。