配置详解

本章详细讲解 Freqtrade 的配置体系，涵盖 config.json 的完整结构、各配置项的功能说明、环境变量覆盖机制以及常见场景的配置模板，帮助读者深入理解并灵活配置交易机器人。

配置文件结构

基本配置结构

{
    "max_open_trades": 3,
    "stake_currency": "USDT",
    "stake_amount": 100,
    "tradable_balance_ratio": 0.99,
    "dry_run_wallet": 10000,
    "fiat_display_currency": "USD",
    "timeframe": "5m",
    "dry_run": true,
    "cancel_open_orders_on_exit": false,
    "trading_mode": "spot",
    "margin_mode": "",
    "unfilledtimeout": {
        "entry": 10,
        "exit": 10,
        "exit_timeout_count": 0,
        "unit": "minutes"
    },
    "entry_pricing": {
        "price_side": "same",
        "price_last_balance": 0.0,
        "use_order_book": true,
        "order_book_top": 1,
        "check_depth_of_market": {
            "enabled": false,
            "bids_to_ask_delta": 1
        }
    },
    "exit_pricing": {
        "price_side": "same",
        "price_last_balance": 0.0,
        "use_order_book": true,
        "order_book_top": 1
    },
    "exchange": {
        "name": "binance",
        "key": "",
        "secret": "",
        "ccxt_config": {},
        "ccxt_async_config": {}
    },
    "pairlists": [
        {"method": "StaticPairList"},
        {"method": "VolumePairList", "number_assets": 20}
    ],
    "telegram": {
        "enabled": false,
        "token": "",
        "chat_id": ""
    },
    "api_server": {
        "enabled": false,
        "listen_ip_address": "127.0.0.1",
        "listen_port": 8080,
        "verbosity": "error",
        "enable_openapi": false,
        "jwt_secret_key": "",
        "cors_origins": [],
        "username": "",
        "password": ""
    },
    "bot_name": "freqtrade",
    "initial_state": "running",
    "force_entry_enable": false,
    "internals": {
        "process_throttle_secs": 5
    }
}

核心交易配置

配置项	类型	默认值	说明
`max_open_trades`	int	3	最大同时持仓数，-1 表示无限
`stake_currency`	string	USDT	投入币种
`stake_amount`	float	100	每笔投入金额
`tradable_balance_ratio`	float	0.99	可用于交易的总余额比例
`dry_run_wallet`	float	1000	模拟运行时的初始钱包余额
`timeframe`	string	5m	默认 K 线周期
`fiat_display_currency`	string	USD	法币显示币种

交易模式配置

Freqtrade 支持三种交易模式：

{
    "trading_mode": "spot",
    "margin_mode": ""
}

模式	trading_mode	margin_mode	说明
现货	`spot`	``	默认模式，直接买卖
期货	`futures`	`isolated`	逐仓保证金
期货	`futures`	`cross`	全仓保证金

交易所配置

{
    "exchange": {
        "name": "binance",
        "key": "your_api_key",
        "secret": "your_api_secret",
        "password": "",
        "sandbox": false,
        "ccxt_config": {
            "enableRateLimit": true,
            "rateLimit": 50
        },
        "ccxt_async_config": {},
        "pair_whitelist": [
            "BTC/USDT",
            "ETH/USDT"
        ],
        "pair_blacklist": [
            "BNB/USDT.*"
        ],
        "timeout": 20,
        "l2_limit": 100
    }
}

交易所配置项

配置项	类型	说明
`name`	string	交易所名称（如 binance, okx, bybit）
`key`	string	API Key
`secret`	string	API Secret
`password`	string	部分交易所需要（如 okx）
`sandbox`	bool	是否使用沙箱环境
`ccxt_config`	object	CCXT 底层库配置
`pair_whitelist`	array	交易白名单
`pair_blacklist`	array	交易黑名单（支持正则）

订单与执行配置

{
    "entry_pricing": {
        "price_side": "same",
        "price_last_balance": 0.0,
        "use_order_book": true,
        "order_book_top": 1,
        "check_depth_of_market": {
            "enabled": false,
            "bids_to_ask_delta": 1
        }
    },
    "exit_pricing": {
        "price_side": "same",
        "price_last_balance": 0.0,
        "use_order_book": true,
        "order_book_top": 1
    },
    "unfilledtimeout": {
        "entry": 10,
        "exit": 10,
        "exit_timeout_count": 0,
        "unit": "minutes"
    },
    "custom_price_max_distance_ratio": 0.02
}

订单价格配置

配置项	说明	建议值
`price_side`	使用买一价还是卖一价	`same` / `ask` / `bid` / `other`
`use_order_book`	是否使用订单簿深度	`true` / `false`
`order_book_top`	使用第几档深度	1-5
`unfilledtimeout.entry`	未成交买入订单超时取消	10-30 分钟
`unfilledtimeout.exit`	未成交卖出订单超时取消	10-30 分钟

API 服务器配置

{
    "api_server": {
        "enabled": true,
        "listen_ip_address": "0.0.0.0",
        "listen_port": 8080,
        "verbosity": "error",
        "enable_openapi": true,
        "jwt_secret_key": "your-strong-secret-key",
        "cors_origins": ["*"],
        "username": "admin",
        "password": "your-strong-password"
    }
}

安全警告：在生产环境中，务必设置强密码和 JWT 密钥，不要将 API 服务暴露在公网。

高级配置

止损与 ROI 配置

{
    "stoploss": -0.10,
    "trailing_stop": true,
    "trailing_stop_positive": -0.02,
    "trailing_stop_positive_offset": 0.03,
    "trailing_only_offset_is_reached": true,
    "use_exit_signal": true,
    "exit_profit_only": false,
    "exit_profit_offset": 0.0,
    "ignore_roi_if_entry_signal": false,
    "minimal_roi": {
        "0": 0.10,
        "30": 0.05,
        "60": 0.02,
        "120": 0
    }
}

时间与频率控制

{
    "timeframe": "5m",
    "timeframe_in_sec": 300,
    "process_only_new_candles": true,
    "internals": {
        "process_throttle_secs": 5
    },
    "unfilledtimeout": {
        "entry": 10,
        "exit": 10,
        "unit": "minutes"
    }
}

环境变量覆盖

Freqtrade 允许通过环境变量覆盖配置文件中的值，这对 Docker 部署和密钥管理非常有用：

环境变量映射规则

环境变量格式：<SECTION>__<KEY>（双下划线作为分隔符）

# 覆盖 exchange.name
export FREQTRADE__EXCHANGE__NAME="binance"

# 覆盖 exchange.key
export FREQTRADE__EXCHANGE__KEY="your_api_key"

# 覆盖 exchange.secret
export FREQTRADE__EXCHANGE__SECRET="your_api_secret"

# 覆盖 telegram.token
export FREQTRADE__TELEGRAM__TOKEN="your_bot_token"

# 覆盖 max_open_trades
export FREQTRADE__MAX_OPEN_TRADES="5"

# 覆盖 dry_run
export FREQTRADE__DRY_RUN="true"

# 覆盖 api_server.username
export FREQTRADE__API_SERVER__USERNAME="admin"

# 覆盖 api_server.password
export FREQTRADE__API_SERVER__PASSWORD="strong_password"

环境变量优先级

环境变量 > 配置文件 > 默认值

Docker 中使用环境变量

version: '3'
services:
  freqtrade:
    image: freqtradeorg/freqtrade:stable
    volumes:
      - "./user_data:/freqtrade/user_data"
    env_file:
      - .env
    environment:
      - FREQTRADE__EXCHANGE__NAME=binance
      - FREQTRADE__TELEGRAM__ENABLED=true

多配置文件合并

Freqtrade 支持同时加载多个配置文件，后面的配置会合并（覆盖）前面的：

# 基础配置 + 私有配置 + 策略配置
freqtrade trade \
    --config user_data/config.json \
    --config user_data/private_config.json \
    --config user_data/strategy_config.json

# 回测使用专用配置
freqtrade backtesting \
    --config user_data/config.json \
    --config user_data/backtest_config.json

配置合并规则

// 文件 1: config.json
{
    "max_open_trades": 3,
    "stake_amount": 100,
    "exchange": {"name": "binance", "key": ""}
}

// 文件 2: override.json
{
    "stake_amount": 200,
    "exchange": {"key": "real_key"}
}

// 合并结果
{
    "max_open_trades": 3,
    "stake_amount": 200,
    "exchange": {"name": "binance", "key": "real_key"}
}

常用配置模板

现货 Dry-Run 模板

{
    "max_open_trades": 3,
    "stake_currency": "USDT",
    "stake_amount": 50,
    "tradable_balance_ratio": 0.99,
    "dry_run_wallet": 10000,
    "dry_run": true,
    "timeframe": "5m",
    "fiat_display_currency": "USD",
    "trading_mode": "spot",
    "margin_mode": "",
    "exchange": {
        "name": "binance",
        "key": "",
        "secret": "",
        "ccxt_config": {}
    },
    "pairlists": [
        {"method": "StaticPairList"}
    ],
    "telegram": {
        "enabled": false,
        "token": "",
        "chat_id": ""
    }
}

实盘交易模板

{
    "max_open_trades": 2,
    "stake_currency": "USDT",
    "stake_amount": 50,
    "tradable_balance_ratio": 0.95,
    "dry_run": false,
    "timeframe": "1h",
    "fiat_display_currency": "USD",
    "trading_mode": "spot",
    "exchange": {
        "name": "binance",
        "key": "${EXCHANGE_KEY}",
        "secret": "${EXCHANGE_SECRET}",
        "ccxt_config": {
            "enableRateLimit": true
        }
    },
    "telegram": {
        "enabled": true,
        "token": "${TELEGRAM_TOKEN}",
        "chat_id": "${TELEGRAM_CHAT_ID}"
    },
    "api_server": {
        "enabled": true,
        "listen_ip_address": "127.0.0.1",
        "listen_port": 8080,
        "username": "admin",
        "password": "${API_PASSWORD}"
    }
}

Docker 部署模板

version: '3'
services:
  freqtrade:
    image: freqtradeorg/freqtrade:stable
    container_name: freqtrade
    restart: unless-stopped
    volumes:
      - "./user_data:/freqtrade/user_data"
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - FREQTRADE__EXCHANGE__NAME=binance
      - FREQTRADE__EXCHANGE__KEY=${EXCHANGE_KEY}
      - FREQTRADE__EXCHANGE__SECRET=${EXCHANGE_SECRET}
      - FREQTRADE__TELEGRAM__ENABLED=true
      - FREQTRADE__TELEGRAM__TOKEN=${TELEGRAM_TOKEN}
      - FREQTRADE__TELEGRAM__CHAT_ID=${TELEGRAM_CHAT_ID}
      - FREQTRADE__DRY_RUN=false
    command: trade --strategy MyStrategy

常见配置问题

问题	原因	解决方案
交易所连接失败	API Key 错误或无权限	检查 Key/Secret 和 IP 白名单
交易对无数据	未下载数据或交易对不在白名单	运行 `freqtrade download-data`
参数未生效	策略中参数覆盖了配置	检查策略中的参数优先级
启动报错	JSON 格式错误	使用 `freqtrade check-config` 验证
Keepp 连接丢失	网络不稳定	启用 `ccxt_config.enableRateLimit`
多配置合并异常	配置字段冲突	检查合并后的完整配置