配置文件完整指南

本文档详细说明了 OpenQuant 量化交易系统的配置文件格式和所有可用选项。

概述

OpenQuant 使用 TOML 格式的配置文件。配置文件通常命名为 config.toml，在启动时作为参数传递

./open_quant config.toml

顶层配置

strategy_path

类型: String (可选)
说明: 策略文件路径
- Python 策略：指向 .py 文件
- Rust 策略：指向动态库文件（.dll / .so / .dylib）

示例:

strategy_path = "examples/depth_imbalance_v2/strategy.py"
# 或
strategy_path = "target/release/libmy_strategy.so"

strategy_config_path

类型: String (可选)
说明: 策略专用配置文件路径，传递给策略的初始化函数，用于初始化策略的参数，支持toml、json、yaml和csv格式，不传则不使用配置文件

示例:

strategy_config_path = "examples/depth_imbalance_v2/strategy.toml"

instruments_refresh_sec

类型: u64
默认值: 300 (5分钟)
说明: 产品信息刷新间隔（秒）
示例:
```
instruments_refresh_sec = 300
```

trader_version

类型: String (仅 Python 策略)
可选值: "V1" 或 "V2"
默认值: "V2"
说明: Python Trader API 版本（Rust 策略不使用此字段）
示例:
```
trader_version = "V2"
```

launcher_mode

类型: String
可选值: "Bin" 或 "AlgoRunner"
默认值: "Bin"
说明: 启动模式
示例:
```
launcher_mode = "Bin"
```

Web 配置 [web]

用于配置 NB8 Web 服务连接。

[web]
is_production = false
secret_id = "your_secret_id"
secret_key = "your_secret_key"

字段说明

字段	类型	必填	说明
`is_production`	bool	是	是否为生产环境
`secret_id`	String	是	Web 服务密钥 ID
`secret_key`	String	是	Web 服务密钥

日志配置 [log]

配置日志输出行为和限流。

[log]
file = "logs/strategy"
level = "info"

[log.rate_limit]
max_tokens = 50
interval = 1

字段说明

字段	类型	默认值	说明
`file`	String (可选)	None	日志文件路径。如果不指定，输出到标准输出
`level`	String	"info"	日志级别: "trace", "debug", "info", "warn", "error"

日志限流 [log.rate_limit]

字段	类型	默认值	说明
`max_tokens`	f64	50.0	令牌桶最大容量，同时决定初始令牌数
`interval`	f64	0.0	令牌生成速率（秒）。0 表示不限流（实盘建议设置为 1）

注意: 设置 interval = 0 会禁用日志限流，适合开发调试；生产环境建议设置为 1。

Visitor 访问器配置 [visitor]

基于访问者模式的 API 拦截器配置，用于在请求/响应过程中自动处理数据标准化。访问器按优先级顺序执行，对订单、余额、行情等数据进行预处理和后处理。

v0.11.0 变更说明: 原本在 place_order 等下单接口 params 参数中的 market_order_mode、market_order_slippage、process_amount、process_price 字段已移至此配置。

执行顺序

Visitor	Priority	说明
BaseConverter	-2000	最先：乘数转换
OrderNormalizer	-1000	其次：tick 标准化
BalanceNormalizer	0	响应处理

数据流

策略下单 → [BaseConverter] → [OrderNormalizer] → 交易所
                 ↓                   ↓
           乘数转换           价格/数量标准化

交易所响应 → [BalanceNormalizer] → [BaseConverter] → 策略接收
                  ↓                       ↓
             过滤零值余额             乘数换算

完整配置示例

[visitor.base_converter]
enabled = true

[visitor.order_normalizer]
enabled = true
price_rounding = "BuyCeilSellFloor"
amount_rounding = "Round"
market_order_mode = "Safe"
market_order_slippage = 0.002

[visitor.balance_normalizer]
enabled = true

订单标准化配置 [visitor.order_normalizer]

在订单发送至交易所前，自动处理价格和数量的精度标准化。

字段	类型	默认值	说明
`enabled`	bool	true	是否启用订单标准化
`price_rounding`	String	"BuyCeilSellFloor"	价格舍入策略
`amount_rounding`	String	"Round"	数量舍入策略
`market_order_mode`	String	"Safe"	市价单处理模式
`market_order_slippage`	f64	0.002	市价单滑点（0.2%）

舍入策略 (RoundingStrategy)

值	说明
`"BuyCeilSellFloor"`	根据买卖方向决定：买入向上取整，卖出向下取整
`"BuyFloorSellCeil"`	根据买卖方向决定：买入向下取整，卖出向上取整
`"Ceil"`	始终向上取整
`"Floor"`	始终向下取整
`"Round"`	四舍五入
`"None"`	不进行任何处理

市价单模式 (MarketOrderMode)

值	说明
`"Safe"`	安全模式：将市价单转换为限价单 + IOC，价格 = 当前价 × (1 ± slippage)，需要传递价格
`"Normal"`	普通模式：直接发送市价单，无需传递价格

余额标准化配置 [visitor.balance_normalizer]

处理交易所返回的余额数据，执行以下标准化操作：

稳定币零值保护: 将 USDT/USDC 等稳定币的 0 余额转为 0.0001，避免除 0 错误
默认值填充: 当余额列表为空时，自动填充 USDT/USDC 默认值

字段	类型	默认值	说明
`enabled`	bool	true	是否启用余额标准化

基础币转换配置 [visitor.base_converter]

处理合约乘数/打包币的双向换算，统一为基础币单位。

字段	类型	默认值	说明
`enabled`	bool	true	是否启用基础币转换

功能说明:

请求方向: 将策略的基础单位转换为交易所单位（× multiplier）
响应方向: 将交易所单位转换为基础单位（÷ multiplier）

适用场景:

合约乘数换算: 如 Binance 的 1000PEPE 合约，价格和数量自动换算为 PEPE 单位
统一数据格式: 策略代码无需关心不同交易所的打包币差异

处理范围:

方向	处理内容
请求处理（发送订单前）	Order / BatchOrder / StopOrder
响应处理（收到数据后）	Ticker / BboTicker / Depth / MarkPrice / Kline / Position / Order / StopOrder / WebSocket 回调数据

插件系统 [[plugin.plugins]]

OpenQuant 支持插件系统，可以扩展系统功能。

折扣币插件 (DiscountCoin)

自动管理交易所折扣币（如 BNB、OKB 等），用于抵扣手续费。

[[plugin.plugins]]
name = "DiscountCoin"
enabled = true
priority = 100
auto_restart = false
restart_delay = 5
max_restarts = 3

[plugin.plugins.config]
check_interval = 60

插件通用字段

字段	类型	默认值	说明
`name`	String	-	插件名称
`enabled`	bool	false	插件总开关
`priority`	u32	100	插件优先级
`auto_restart`	bool	false	是否自动重启
`restart_delay`	u64	5	重启延迟（秒）
`max_restarts`	u32	3	最大重启次数

折扣币插件配置

字段	类型	默认值	说明
`check_interval`	u64	60	检查间隔（秒）

交易所配置 [[exchanges]]

配置一个或多个交易所账户。每个交易所需要一个 [[exchanges]] 配置块。

基本配置示例

[[exchanges]]
exchange = "BinanceSwap"
key = "your_api_key"
secret = "your_api_secret"
passphrase = ""
rebate_rate = 0.0
is_colo = false
is_testnet = false
is_unified = false
use_ws_api = false

字段说明

必填字段

字段	类型	说明
`exchange`	String	交易所名称（见下方支持的交易所列表）
`key`	String	API Key
`secret`	String	API Secret
`rebate_rate`	f64	返佣比例（小数，如 0.0001 表示 0.01%）

可选字段

字段	类型	默认值	说明
`passphrase`	String	""	API Passphrase（OKX、Coinbase 等需要）
`is_colo`	bool	false	是否为托管机房环境
`is_testnet`	bool	false	是否为测试网
`is_unified`	bool	false	是否为统一账户（如 Bybit 统一账户）
`use_ws_api`	bool	自动	是否使用 WebSocket API 下单默认值：BinanceSpot/OkxSwap/OkxSpot/OkxMargin 为 true，其他为 false
`ws_api_count`	usize	16	WebSocket API 连接数

支持的交易所

v0.11.0 变更说明：自 v0.11.0 起，仅以下 7 个交易所为积极维护状态，其他交易所暂不维护。如需支持其他交易所，请联系交易系统团队。

✅ 积极维护的交易所（7 个）

以下交易所为积极维护状态，全面支持 WebSocket 运行时动态订阅/取消订阅：

交易所	现货	合约	杠杆	币本位合约	统一账户	WS 动态订阅
Binance	✅	✅	✅	✅		✅
OKX	✅	✅	✅	✅	✅	✅
Bitget	✅	✅	✅		✅	✅
Bybit	✅	✅			✅	✅
Coinex	✅	✅				✅
Gate	✅	✅	✅		✅	✅
Huobi	✅	✅				✅

交易所枚举列表：

Binance: BinanceSwap / BinanceSwapUsd / BinanceSpot / BinanceMargin / BinanceFuture
OKX: OkxSwap / OkxSwapUsd / OkxSpot / OkxMargin / OkxFuture
Bitget: BitgetSwap / BitgetSpot / BitgetMargin
Bybit: BybitSwap / BybitSpot
Coinex: CoinexSwap / CoinexSpot
Gate: GateSwap / GateSpot / GateMargin
Huobi: HuobiSwap / HuobiSpot

⚠️ 暂不维护的交易所

以下交易所代码仍保留，但不再进行积极维护。如有需要，请联系交易系统团队：

Apex, Aster, Bingx, Bitfinex, Bitmart, Bitmex, Coinbase, Coinw, Crypto, Deepcoin, Deribit, Dydx, Hotcoin, HyperLiquid, Kraken, Kucoin, Lbank, Mexc, Phemex, Weex, Whitebit, XT, Zoomex 等

其他特殊类型

CoinMarketCap: 市值数据查询（非交易所）
SignalCenter: 信号中心连接器
PyEx: Python 自定义交易所
Backtest: 回测虚拟交易所

多 IP 配置

某些交易所支持通过多个 IP 分散请求，避免触发频率限制。

[[exchanges]]
exchange = "BinanceSwap"
# ... 其他配置 ...
multi_ip = true
ip_indices = [0, 1, 3]

字段	类型	默认值	说明
`multi_ip`	bool	false	是否启用多 IP
`ip_indices`	Vec<usize>	[]	使用的 IP 索引列表（IP 按字符串排序后的索引）

注意: 启用 multi_ip 后，日志会输出可用 IP 列表及其索引。

自定义域名

用于特殊网络环境或自定义代理。

[[exchanges]]
exchange = "BinanceSwap"
# ... 其他配置 ...
host = "custom-api.example.com"
ws_host = "custom-ws.example.com"
ws_api_host = "custom-wsapi.example.com"

字段	类型	默认值	说明
`host`	String (可选)	None	HTTP REST API 域名
`ws_host`	String (可选)	None	WebSocket 数据流域名
`ws_api_host`	String (可选)	None	WebSocket API 域名

代理配置

支持 HTTP、HTTPS、SOCKS5 代理。

[[exchanges]]
exchange = "BinanceSwap"
# ... 其他配置 ...
proxy = "socks5://username:password@127.0.0.1:1080"

代理格式:

HTTP: http://proxy.example.com:8080
HTTPS: https://proxy.example.com:8080
SOCKS5: socks5://127.0.0.1:1080
带认证: socks5://username:password@127.0.0.1:1080

非标参数 (params)

某些交易所需要特殊参数。

[[exchanges]]
exchange = "BitgetSwap"
# ... 其他配置 ...

[exchanges.params]
cookie = "your_cookie"
code = "invitation_code"
org_id = "organization_id"
version = "v1"  # Bitget WebSocket 版本

支持的特殊参数

参数	适用交易所	说明
`cookie`	BitgetSwap, CoinexSwap, HotcoinSwap, BitmartSwap, GateSwap	网页 Cookie
`code`	BitgetSwap, CoinexSwap, HotcoinSwap, BitmartSwap, GateSwap	邀请码（配合 cookie 使用）
`org_id`	BitgetSwap, BitgetSpot, BitgetMargin, CoinexSwap, GateSwap, GateSpot, GateMargin	机构 ID
`version`	Bitget 系列	WebSocket 订阅版本（设置为 "v1" 可订阅 v1 版本的 depth 和 bbo）
`discount`	各交易所	平台币折扣信息

折扣币配置 (discount_coin_config)

为每个交易所单独配置折扣币管理策略。

[[exchanges]]
exchange = "BinanceSwap"
# ... 其他配置 ...

[exchanges.discount_coin_config]
enabled = true
unit = "Quote"
maintenance = 16
buy_multiplier = 0.6
quote_currency = "USDT"
spot_index = 0
quote_back_threshold = 50.0

字段	类型	默认值	说明
`enabled`	bool	false	是否为此交易所启用折扣币管理
`unit`	String	"Quote"	计算基础："Quote"（计价币）或 "Token"（折扣币）
`maintenance`	f64	200.0	维持数量
`buy_multiplier`	f64	0.6	买入乘数阈值（当数量 < 该值 * maintenance 时买入）
`quote_currency`	String	"USDT"	计价货币："USDT", "USDC", "USD"
`spot_index`	usize (可选)	0	现货账户 API Key 索引（合约和现货 Key 不通用时）
`quote_back_threshold`	f64	50.0	回转金额阈值（合约账户剩余计价币低于此值时回转）

缓存配置 [cache]

配置系统缓存行为。

[cache]
typ = "File"
path = "cache.json"

字段	类型	默认值	说明
`typ`	String	"File"	缓存类型（目前仅支持 "File"）
`path`	String	"cache.json"	缓存文件路径

数据源配置 [data_source]

配置市场数据源。

[data_source]
typ = "Default"

字段	类型	默认值	说明
`typ`	String	"Default"	数据源类型

执行引擎配置 [execution_engine]

配置订单执行引擎。

[execution_engine]
typ = "Stand"
task_count = 500

字段	类型	默认值	说明
`typ`	String	"Stand"	执行引擎类型
`task_count`	usize	500	并发任务数量

可观测性配置 [o11y]

配置 OpenTelemetry 遥测数据上报。

[o11y]
enabled = true
endpoint = "http://35.79.151.195:4317"
report_interval = 5

字段	类型	默认值	说明
`enabled`	bool	true	是否启用遥测
`endpoint`	String	"http://35.79.151.195:4317"	OTLP 端点地址
`report_interval`	u64	5	上报间隔（秒）

回测配置 [backtest]

配置回测模式（可选，仅用于回测）。

[backtest]
start_logic_time = "2024-01-01T00:00:00Z"
end_logic_time = "2024-01-31T23:59:59Z"
wait_seconds_before_start = 5.0

[backtest.report]
# 报告配置

[backtest.server]
# 服务器配置

[[backtest.exchanges]]
# 回测交易所配置

基本字段

字段	类型	默认值	说明
`start_logic_time`	String	-	回测开始时间（RFC3339 格式）
`end_logic_time`	String	-	回测结束时间（RFC3339 格式）
`wait_seconds_before_start`	f64	5.0	策略启动前等待时间（秒）

完整配置示例

# 策略配置
strategy_path = "examples/depth_imbalance_v2/strategy.py"
strategy_config_path = "examples/depth_imbalance_v2/strategy.toml"
instruments_refresh_sec = 300
trader_version = "V2"

# Web 服务配置
[web]
is_production = false
secret_id = "your_secret_id"
secret_key = "your_secret_key"

# 日志配置
[log]
file = "logs/strategy"
level = "info"

[log.rate_limit]
max_tokens = 50
interval = 1

# Visitor 访问器配置
[visitor.order_normalizer]
enabled = true
price_rounding = "BuyCeilSellFloor"
amount_rounding = "Round"
market_order_mode = "Safe"
market_order_slippage = 0.002

[visitor.balance_normalizer]
enabled = true

[visitor.base_converter]
enabled = true

# 插件配置
[[plugin.plugins]]
name = "DiscountCoin"
enabled = true
priority = 100
auto_restart = false
restart_delay = 5
max_restarts = 3

[plugin.plugins.config]
check_interval = 60

# 交易所配置示例 1: Binance Swap（带多IP和折扣币）
[[exchanges]]
exchange = "BinanceSwap"
key = "your_api_key"
secret = "your_api_secret"
passphrase = ""
rebate_rate = 0.0001
is_colo = false
is_testnet = false
is_unified = false
use_ws_api = false
multi_ip = true
ip_indices = [0, 1, 3]

[exchanges.discount_coin_config]
enabled = true
unit = "Quote"
maintenance = 16

# 交易所配置示例 2: OKX Swap（带 passphrase）
[[exchanges]]
exchange = "OkxSwap"
key = "your_api_key"
secret = "your_api_secret"
passphrase = "your_passphrase"
rebate_rate = 0.0
is_colo = false
is_testnet = false
is_unified = false
use_ws_api = true

# 交易所配置示例 3: Bybit Unified Account
[[exchanges]]
exchange = "BybitSwap"
key = "your_api_key"
secret = "your_api_secret"
passphrase = ""
rebate_rate = 0.0
is_colo = false
is_testnet = false
is_unified = true

# 交易所配置示例 4: Bitget（带特殊参数）
[[exchanges]]
exchange = "BitgetSwap"
key = "your_api_key"
secret = "your_api_secret"
passphrase = ""
rebate_rate = 0.0
is_colo = false
is_testnet = false
is_unified = false

[exchanges.params]
cookie = "your_cookie"
code = "invitation_code"
org_id = "organization_id"

# 缓存配置
[cache]
typ = "File"
path = "cache.json"

# 数据源配置
[data_source]
typ = "Default"

# 执行引擎配置
[execution_engine]
typ = "Stand"
task_count = 500

# 可观测性配置
[o11y]
enabled = true
endpoint = "http://35.79.151.195:4317"
report_interval = 5

与旧版本的差异

新增功能

插件系统 ([[plugin.plugins]])
- 支持模块化功能扩展
- 内置折扣币自动管理插件
多 IP 支持 (multi_ip, ip_indices)
- 可通过多个 IP 分散请求
- 避免触发交易所频率限制
WebSocket API (use_ws_api, ws_api_count)
- 部分交易所支持通过 WebSocket 下单
- 降低延迟
折扣币精细化配置 (discount_coin_config)
- 每个交易所单独配置
- 支持多种计算模式和阈值
可观测性 ([o11y])
- OpenTelemetry 集成
- 自动上报遥测数据
回测模式 ([backtest])
- 完整的历史数据回测支持
- Tardis 数据下载集成
日志限流 ([log.rate_limit])
- 避免高频日志占用资源
- 令牌桶限流算法
Rust 策略支持
- 通过动态库加载 Rust 策略
- 零 FFI 开销，极致性能

已移除/弃用字段

旧文档中的部分字段可能已移除或重命名，请参考本文档的当前版本。

常见问题

如何选择 trader_version?

V1: 旧版 API，功能较少，已不推荐
V2: 新版 API，功能更完善，推荐使用
注意: 仅适用于 Python 策略，Rust 策略不使用此字段

是否需要配置所有交易所?

不需要。只配置你实际使用的交易所即可。

multi_ip 如何获取可用 IP 列表?

启用 multi_ip = true 后运行程序，日志会输出可用 IP 列表及其索引。

如何调试配置问题?

设置 log.level = "debug" 获取详细日志
设置 log.rate_limit.interval = 0 禁用日志限流
检查日志输出的错误信息

目录​

概述​

顶层配置​

strategy_path​

strategy_config_path​

instruments_refresh_sec​

trader_version​

launcher_mode​

Web 配置 [web]​

字段说明​

日志配置 [log]​

字段说明​

日志限流 [log.rate_limit]​

Visitor 访问器配置 [visitor]​

执行顺序​

数据流​

完整配置示例​

订单标准化配置 [visitor.order_normalizer]​

舍入策略 (RoundingStrategy)​

市价单模式 (MarketOrderMode)​

余额标准化配置 [visitor.balance_normalizer]​

基础币转换配置 [visitor.base_converter]​

插件系统 [[plugin.plugins]]​

折扣币插件 (DiscountCoin)​

插件通用字段​

折扣币插件配置​

交易所配置 [[exchanges]]​

基本配置示例​

字段说明​

必填字段​

可选字段​

支持的交易所​

✅ 积极维护的交易所（7 个）​

⚠️ 暂不维护的交易所​

其他特殊类型​

多 IP 配置​

自定义域名​

代理配置​

非标参数 (params)​

支持的特殊参数​

折扣币配置 (discount_coin_config)​

缓存配置 [cache]​

数据源配置 [data_source]​

执行引擎配置 [execution_engine]​

可观测性配置 [o11y]​

回测配置 [backtest]​

基本字段​

完整配置示例​

与旧版本的差异​

新增功能​

已移除/弃用字段​

常见问题​

如何选择 trader_version?​

是否需要配置所有交易所?​

multi_ip 如何获取可用 IP 列表?​

如何调试配置问题?​

目录

概述

顶层配置

strategy_path

strategy_config_path

instruments_refresh_sec

trader_version

launcher_mode

Web 配置 [web]

字段说明

日志配置 [log]

字段说明

日志限流 [log.rate_limit]

Visitor 访问器配置 [visitor]

执行顺序

数据流

完整配置示例

订单标准化配置 [visitor.order_normalizer]

舍入策略 (RoundingStrategy)

市价单模式 (MarketOrderMode)

余额标准化配置 [visitor.balance_normalizer]

基础币转换配置 [visitor.base_converter]

插件系统 [[plugin.plugins]]

折扣币插件 (DiscountCoin)

插件通用字段

折扣币插件配置

交易所配置 [[exchanges]]

基本配置示例

字段说明

必填字段

可选字段

支持的交易所

✅ 积极维护的交易所（7 个）

⚠️ 暂不维护的交易所

其他特殊类型

多 IP 配置

自定义域名

代理配置

非标参数 (params)

支持的特殊参数

折扣币配置 (discount_coin_config)

缓存配置 [cache]

数据源配置 [data_source]

执行引擎配置 [execution_engine]

可观测性配置 [o11y]

回测配置 [backtest]

基本字段

完整配置示例

与旧版本的差异

新增功能

已移除/弃用字段

常见问题

如何选择 trader_version?

是否需要配置所有交易所?

multi_ip 如何获取可用 IP 列表?

如何调试配置问题?