Freqtrade freqtrade-client 完全指南：命令行与 Python 方式驱动 REST API

本文基于仓库文档 freqtrade-client 命令参考 与配套源码编写，介绍 freqtrade 官方轻量级 REST 客户端 freqtrade-client 的安装配置、命令行调用方式、全部可用命令及其参数，并深入到 ft_rest_client.py 的请求实现层。读完后你将能够：独立于机器人安装并配置客户端、用 freqtrade-client <command> 完成启停、强开/强平、白黑名单、交易统计等运维操作，并在自己的 Python 脚本中通过 FtRestClient 编程式地调用机器人 API。

1. freqtrade-client 是什么

freqtrade 机器人的 REST API 通过内置的 api_server 对外提供 JSON 接口，官方推荐使用随仓库发布的 freqtrade-client 包来消费该 API（同样也有等价的独立脚本 scripts/rest_client.py）。该模块的设计目标是轻量：它不导入 freqtrade 的任何代码（见 ft_rest_client.py 顶部注释："Should not import anything from freqtrade"），仅依赖两个库——requests 与 python-rapidjson（见 ft_client/requirements.txt），因此可以安装在与机器人完全不同的环境中，例如一台只用于监控的跳板机。

安装方式：

pip install freqtrade-client

安装后获得一个名为 freqtrade-client 的可执行程序，其入口点定义在 ft_client/pyproject.toml 中：freqtrade-client = "freqtrade_client.ft_client:main"。

2. 命令行基本用法

2.1 命令格式

freqtrade-client <command> [optional parameters]

客户端默认假设机器人 API 监听在 127.0.0.1:8080（localhost），若要访问其他地址/端口或使用凭证，则通过 -c / --config 指定一个配置文件来覆盖默认行为（见 ft_client.py 中 main_exec）。

2.2 客户端配置文件

客户端只读取配置中的 api_server 段，最小可用配置如下（摘自 docs/rest-api.md）：

{
    "api_server": {
        "enabled": true,
        "listen_ip_address": "0.0.0.0",
        "listen_port": 8080,
        "username": "Freqtrader",
        "password": "SuperSecret1!"
    }
}

使用方式：

freqtrade-client --config rest_config.json <command> [optional parameters]

从源码看（ft_client.py），客户端会从中提取 listen_ip_address（缺省 127.0.0.1）、listen_port（缺省 8080）、username、password 四个字段，拼出 http://<ip>:<port> 并传入 FtRestClient；配置文件支持注释与尾随逗号（加载时使用 rapidjson.PM_COMMENTS | PM_TRAILING_COMMAS 解析模式），因此可以直接复制机器人完整配置中的一段。

前提条件：机器人端必须在配置中启用 api_server（"api_server": {"enabled": true, ...}）并正确设置用户名/密码；ping 端点无需鉴权，可直接用浏览器访问 http://127.0.0.1:8080/api/v1/ping 验证 API 是否就绪（预期返回 {"status":"pong"}）。官方安全建议：不要将 API 直接暴露在公网，远程访问推荐 SSH 隧道或 VPN（详见 docs/rest-api.md）。

2.3 参数传递规则：位置参数与键值参数

freqtrade-client 的参数解析规则非常简单（见 ft_client.py）：

• 命令行中以 = 分隔的片段被视为关键字参数，例如 enter_tag=GutFeeling；
• 其余片段按顺序作为位置参数传入；
• 命令名必须是 FtRestClient 的一个公开方法，否则客户端会报错并打印全部可用命令；
• 执行结果以 JSON 单行输出到 stdout，便于被 jq 等工具二次处理。

典型例子：

# 强制开多单，并指定入场标签（关键字参数）
freqtrade-client --config rest_config.json forceenter BTC/USDT long enter_tag=GutFeeling

2.4 查看帮助

freqtrade-client help        # 或 show，或 --show

help 输出由客户端在运行时动态生成：ft_client.py 中的 print_commands() 通过 inspect 遍历 FtRestClient 的全部公开方法，剥离 docstring 中的 :return: 行后逐条打印。也就是说，文档 docs/commands/freqtrade-client.md 本身就是由构建脚本 build_helpers/create_command_partials.py 执行 freqtrade-client --show 生成的——文档与客户端源码的 docstring 严格同源，命令签名变更时文档会随之再生成。

3. 完整命令参考

以下命令全集继承自 docs/commands/freqtrade-client.md，并按用途归类。每个命令对应 FtRestClient 的一个方法，调用机器人的 /api/v1/... 端点，返回 JSON。

3.1 机器人控制与运行状态

命令	参数	说明	对应方法
start	-	若机器人处于 stopped 状态则启动	start()
stop	-	停止机器人；可用 start 恢复	stop()
stopbuy	-	停止开新仓（已有持仓继续按规则处理）；reload_config 可重置	stopbuy()
reload_config	-	重新加载配置文件	reload_config()
ping	-	简单连通性检查	ping()
version	-	返回机器人版本	version()
health	-	快速健康检查（正在运行的机器人）	health()
sysinfo	-	系统信息（CPU、RAM 占用）	sysinfo()
show_config	-	返回与交易操作相关的部分配置	show_config()
logs	limit	显示最近日志；limit 限制为最近 N 条，缺省取全部	logs(limit=None)
strategies	-	列出可用策略	strategies()
strategy	strategy	获取指定策略类名的详情	strategy(strategy)
pairlists_available	-	列出可用的 pairlist 提供者	pairlists_available()
plot_config	-	若策略定义了绘图配置则返回之	plot_config()

其中 ping 值得一提：它并不是简单转发 /ping 端点，而是先调用 show_config，再根据 state 字段判断返回 pong 还是 not_running（见 ft_rest_client.py），因此它真实反映"机器人是否处于 running 状态"，适合写进监控脚本。

3.2 交易操作与干预

命令	参数	说明
forcebuy	pair，可选 price	买入指定交易对（如 ETH/BTC）
forceenter	pair、side（long/short）；可选关键字参数 price、order_type（limit/market）、stake_amount（float）、leverage（float）、enter_tag（字符串，默认 force_enter）	强制开仓，支持做空与杠杆
forceexit	tradeid（可从 status 获取）；可选 ordertype（market/limit）、amount（不给则全平）	强制平仓
cancel_open_order	trade_id	取消该笔交易的挂单
delete_trade	trade_id	从数据库删除该笔交易；会尝试撤销挂单，交易所侧资产需手动处理
whitelist	-	显示当前白名单
blacklist	可选 add（交易对列表，如 BNB/BTC）	无参显示黑名单；带参则向黑名单追加
lock_add	pair、until（格式 "2024-03-30 16:00:00Z"）、side（long/short/*）、reason	锁定指定交易对（按方向与时间段）
locks	-	返回当前所有锁
delete_lock	lock_id	删除（失效）指定锁

forceenter 的实现（ft_rest_client.py）会按需拼装 POST body：side 必填，price/ordertype/stakeamount/leverage/entry_tag 仅在有值时才写入请求体，因此"可选关键字参数"的语义在源码中得到直接印证。lock_add 则将参数打包为 [{"pair": ..., "until": ..., "side": ..., "reason": ...}] 列表后 POST 到 locks 端点，这与测试用例中的参数 ("lock_add", ["XRP/USDT", "2024-01-01 20:00:00Z", "*", "rand"], {}) 一一对应（见 test_rest_client.py）。

3.3 绩效与统计

命令	参数	说明
profit	-	利润汇总
count	-	当前未平仓交易数量
status	-	未平仓交易状态列表
daily	可选时间尺度（位置参数，对应 timescale）	每日利润与交易笔数
weekly	同上	每周利润与交易笔数
monthly	同上	每月利润与交易笔数
performance	-	各币种表现
stats	-	统计报表（持仓时长、卖出原因等）
entries	可选 pair	按 entry tag 汇总的交易表现，可指定交易对或取全对平均
exits	可选 pair	按 exit reason 汇总的交易表现
mix_tags	可选 pair	按 entry_tag + exit_reason 组合维度的表现

entries / exits / mix_tags 三个命令是策略归因分析的利器：不传 pair 时返回全市场按标签/出场原因聚合的统计，传 pair 时返回该交易对的明细，可用于评估某个入场标签（例如你自定义的 enter_tag）或某类出场原因（止损、止盈、信号）的整体贡献。

3.4 交易记录与自定义数据

命令	参数	说明
trades	可选 limit（最多 500 条）、offset、order_by_id（默认 True，为 False 时按最新时间戳排序）	交易历史
trade	trade_id	查询指定交易
list_custom_data	trade_id，可选 key	列出某笔交易的自定义数据（set_custom_data 写入的内容）
list_open_trades_custom_data	可选 key，limit（默认 100）、offset	列出全部未平仓交易的自定义数据，支持分页

3.5 行情与数据

命令	参数	说明
available_pairs	可选 timeframe、stake_currency	返回指定时间框架/计价货币下已有回测数据的交易对
pair_candles	pair、timeframe；可选 limit（最近 N 根 K 线）、columns（要返回的列，空列表返回 OHLCV）	返回 <pair><timeframe> 的实时数据帧
pair_history	pair、timeframe、strategy；可选 freqaimodel、timerange（与 --timerange 端点相同格式）	返回经策略分析后的历史数据帧

pair_candles 有一个源码级的细节值得注意（ft_rest_client.py）：不带 columns 时走 GET（普通查询参数），一旦传了 columns 就改为 POST 并把参数放进请求体——因为列名列表作为 query string 可能过长或含特殊字符。编写自动化脚本时若需要额外指标列，应按 pair_candles=... columns=... 的关键字形式传参。

4. 编程式使用（Python API）

freqtrade-client 包同样可以在自己的脚本中直接导入使用（无需安装完整 freqtrade）：

from freqtrade_client import FtRestClient

client = FtRestClient(server_url, username, password)

# 检查机器人是否在运行
print(client.ping())

# 查看未平仓交易
print(client.status())

# 向黑名单追加交易对
client.blacklist("BTC/USDT", "ETH/USDT")
# 或批量追加
client.blacklist(*list_pairs)

4.1 请求层的实现细节

从源码看（ft_rest_client.py），FtRestClient 的核心工作方式：

• 构造：FtRestClient(serverurl, username=None, password=None, *, pool_connections=10, pool_maxsize=10, timeout=10) 创建带连接池的 requests.Session；提供用户名与密码时自动启用 HTTP Basic 认证（session.auth = (username, password)）。
• URL 拼装：所有调用经 _call() 统一处理，最终 URL 为 {serverurl}/api/v1/{apipath}，query 参数经 urlencode 编码；合法方法限定为 GET/POST/PUT/DELETE。
• 超时与容错：默认 10 秒超时；ConnectionError 被捕获并记录 "Connection error" 日志而非抛出——测试用例 test_FtRestClient_call_invalid 专门验证了该行为（同时验证非法 HTTP 方法会抛 ValueError）。
• 返回：所有命令返回解析后的 JSON（resp.json()），因此 client.status() 得到的是 Python 对象而非字符串，可直接参与后续计算。

4.2 参数与端点映射示例

以 trades 为例（ft_rest_client.py）：limit、offset 仅在有值时写入 query；order_by_id=False 时显式附带 order_by_id=False 参数——默认不传该参数（服务端默认按 id 排序）。测试参数矩阵（test_rest_client.py）覆盖了 trades(5)、trades(5, 5)、trades(5, 5, False) 等组合，是核对"位置参数顺序 = (limit, offset, order_by_id)"的最佳依据。

5. 典型运维脚本示例

结合前述能力，一个"每日巡检"脚本可以这样组织（仅示意调用方式）：

from freqtrade_client import FtRestClient

client = FtRestClient("http://127.0.0.1:8080", "Freqtrader", "SuperSecret1!")

ping = client.ping()                    # 机器人是否在 running
if ping["status"] != "pong":
    raise SystemExit("bot not running")

print(client.health())                  # 健康检查
print(client.count())                   # 未平仓数量
print(client.profit())                  # 利润汇总
print(client.status())                  # 持仓明细

命令行等价操作：

freqtrade-client ping
freqtrade-client health
freqtrade-client count
freqtrade-client profit
freqtrade-client forceenter BTC/USDT short price=0.5 order_type=limit enter_tag=manual_short
freqtrade-client forceexit 42 ordertype=market

6. 注意事项与适用前提

1. 前提：机器人配置必须启用 api_server，且客户端配置中的地址、端口、凭证与机器人端一致；ping 端点免鉴权，其余端点均需认证。
2. 危险操作：delete_trade 只会删除数据库记录并尝试撤销挂单，交易所侧资产需要人工处理；forcebuy/forceenter/forceexit 直接产生真实订单，实盘环境务必谨慎。
3. 安全：不要把 API 端口直接映射到公网（官方文档中专门有 docker 端口映射的安全警告，见 docs/rest-api.md）；密码建议使用密码管理器或 secrets.token_hex() 生成强随机值。
4. 独立部署：客户端包与机器人版本解耦（仓库提供了 build_helpers/freqtrade_client_version_align.py 用于发版时对齐版本号），可在无 freqtrade 的机器上 pip install freqtrade-client 后使用。
5. 验证来源：本文命令清单、参数语义与 docs/commands/freqtrade-client.md 一致，底层行为以 ft_client/freqtrade_client/ft_rest_client.py、ft_client/freqtrade_client/ft_client.py 为准，测试覆盖见 ft_client/test_client/test_rest_client.py。