1. 项目概述与核心定位如果你在DEX去中心化交易所上做过交易尤其是玩过永续合约肯定有过这样的体验眼睛得同时盯着好几个屏幕——价格图表、深度图、资金费率、甚至还得刷一下社交媒体看看有没有什么突发消息。手忙脚乱不说一个犹豫可能就错过了机会或者更糟没来得及止损。我自己在HyperLiquid上做手动交易的头几个月这种感觉特别明显。后来我开始琢磨能不能让机器来帮我处理这些繁琐的监控和初步决策我只负责把控大方向和风险这就是我接触并深入研究HyperLiquid Claw这个项目的初衷。简单来说HyperLiquid Claw不是一个单一的、固化的“交易机器人”。你可以把它理解为一个高度模块化、可编程的“策略执行框架”。它的核心思想是“技能”Skill或者说“爪”Claw。每一个Claw都是一个独立的、专注于特定市场行为比如套利、动量跟踪、均值回归的自动化程序。你可以像搭积木一样根据市场环境组合、启用或停用不同的Claw。它不宣称自己是一个能预测市场的“AI圣杯”而是提供了一个强大的工具箱和一套运行规则让你能将自己的交易逻辑严谨地自动化并引入AI作为分析辅助而不是决策主宰。这个框架最适合两类人一是已经有成熟交易想法但苦于手动执行效率低下、容易受情绪影响的个人交易者二是希望构建和测试多种量化策略但又不想从零搭建底层基础设施的开发者和研究员。它帮你解决了连接交易所API、处理实时数据流、管理订单生命周期、风险检查等脏活累活让你能聚焦在策略逻辑本身。2. 架构深度解析为什么设计成“技能”模式很多传统的交易机器人是一个“黑箱”你输入参数它输出交易信号内部逻辑难以审计和调整。HyperLiquid Claw采用了一种截然不同的设计哲学其架构可以拆解为四个核心层级这种设计背后有很强的实用考量。2.1 数据感知与处理层这是所有策略的基石。Claw框架内置了与HyperLiquid节点的高效WebSocket连接能够实时订阅多个交易对的订单簿、成交记录、资金费率等数据。这里的一个关键设计是数据标准化与缓冲。不同来源、不同频率的原始数据会被清洗、统一格式并放入一个内部的数据总线Data Bus中。这样做的好处是上层的任何一个Claw技能都无需自己维护复杂的连接只需从总线上订阅它关心的数据流即可。例如一个三角套利Claw可能只订阅ETH、BTC、SOL三个永续合约的实时价格和深度而一个情绪分析Claw则可能去订阅特定的链上数据或经过预处理的社会情绪指数。注意在实际部署时数据源的稳定性和延迟是首要问题。框架虽然提供了重连和容错机制但你自己的网络环境尤其是家用宽带可能不稳定。我个人的经验是至少在初期使用一个稳定的云服务器如AWS/Azure/GCP的轻量级实例来运行Claw能极大减少因网络抖动导致的信号丢失或订单异常。2.2 “技能”Claw执行层这是整个框架最核心的部分。每个Claw都是一个独立的Python模块遵循统一的接口规范。这个规范通常要求实现几个关键方法initialize初始化、on_market_data处理市场数据、should_act生成信号、execute_action执行交易。这种设计实现了策略的热插拔。为什么热插拔如此重要市场是分状态的——有趋势市、震荡市、高波动市。没有一个策略能通吃所有行情。在趋势市表现良好的动量策略在震荡市里可能会反复止损。Claw框架允许你同时运行多个策略但为它们设置不同的激活条件。你可以写一个简单的“市场状态判别器”Claw当它判断市场进入震荡时自动禁用动量Claw启用均值回归Claw。这一切都可以在运行时动态完成无需重启整个程序保证了策略切换的平滑性和资金的安全性。2.3 风险与执行网关层这是保障资金安全的“防火墙”。所有Claw生成的交易信号比如“在价格X买入1个ETH永续”都不会直接发送到HyperLiquid链上。它们必须首先通过这个统一的网关。网关会进行一系列检查头寸检查当前账户的总风险暴露是否超过预设上限本次开仓是否会违反单品种或总仓位限制参数校验订单价格是否合理如远离标记价格超过一定百分比则拒绝滑点容忍度是否在设定范围内模拟预执行框架会在本地完全模拟这笔交易计算预估的成交价、手续费和潜在盈亏并与策略预期的盈亏比进行对比。如果模拟结果远差于预期交易会被挂起并触发警报。AI辅助复核可选如果配置了OpenAI或Claude API网关可以将交易信号和当前市场快照发送给大模型让其从一个“保守的第三方”视角进行评论。例如模型可能会提示“当前市场波动率异常升高建议缩小仓位”或“该交易逻辑与过去24小时同类策略的成功模式不符”。请注意AI在这里的角色是“顾问”而非“决策者”最终是否放行仍由你设定的规则或你自己决定。只有通过了所有这些检查交易指令才会被组装成合法的HyperLiquid交易签名并广播。这个设计彻底杜绝了单个Claw逻辑出错时“乱开仓”的风险。2.4 协调与监控层当运行多个Claw时它们之间可能需要协作或避免冲突。协调层管理着Claw之间的通信例如一个Claw发现了机会但需要另一个Claw提供流动性支持和资源分配例如共享的保证金池。同时监控层负责收集所有Claw的性能指标胜率、夏普比率、最大回撤、系统资源使用情况并通过Telegram、Discord等渠道发送警报。一个实用的功能是仪表盘它能实时展示每个Claw的状态、当前持有的仓位、以及模拟的账户权益曲线让你对整体情况一目了然。3. 从零到一的实战部署与配置详解看懂了架构我们动手把它跑起来。这里我会以在Linux云服务器上部署为例给出最详细、避坑最多的步骤。3.1 环境准备与依赖安装首先确保你的环境符合要求。Python 3.10或以上版本是必须的因为框架用到了很多新的语法特性。# 1. 更新系统并安装基础工具 sudo apt-get update sudo apt-get upgrade -y sudo apt-get install -y python3-pip python3-venv git # 2. 创建并进入一个独立的项目目录使用虚拟环境是绝对的最佳实践能避免依赖冲突。 mkdir ~/hyperliquid_trading cd ~/hyperliquid_trading python3 -m venv venv source venv/bin/activate # 3. 克隆仓库。注意原项目地址可能需要替换为实际的GitHub仓库地址。 # 这里假设项目已在GitHub上公开我们使用一个示例地址。 git clone https://github.com/devilthresh2/hyperliquid-claw-scribe.git cd hyperliquid-claw-scribe # 4. 安装依赖。原文档提到的 .[cognitive,strategies,analytics] 是一种extras安装方式。 # 你需要检查项目根目录下的 setup.py 或 pyproject.toml 文件确认这些extras是否存在。 # 更稳妥的方式是先安装核心依赖再按需安装可选组件。 pip install -e . # 先安装核心包 # 如果有 extras 定义可以这样安装请根据实际项目文件调整 # pip install -e .[cognitive,strategies,analytics]实操心得很多人在第一步就卡住问题出在系统自带的Python版本太老或者pip版本不兼容。一个万无一失的方法是使用pyenv来管理多个Python版本但在服务器上为了简单直接安装Python 3.10的包即可。另外强烈建议在虚拟环境中操作这样以后你如果想测试不同版本的Claw框架可以轻松创建多个互不干扰的环境。3.2 核心配置文件剖析安装好后不要急着运行。框架的强大和安全性很大程度上来自于其细致的配置。我们需要创建并理解核心配置文件claw_profile.yaml。这个文件通常放在~/.hyperliquid/目录下。# ~/.hyperliquid/claw_profile.yaml identity: name: my_trading_bot_01 # 给你的机器人起个名用于日志标识 risk_tolerance: 0.7 # 风险容忍度一个0-1的系数会影响仓位计算 operating_capital: 0.1 # 动用总资金的10%作为运作资本。这是最重要的风控之一 max_positions: 2 # 同时最多持有2个不同标的的仓位防止过度集中 cognitive_enhancement: openai_integration: false # 初期强烈建议关闭先让纯策略跑通。 claude_integration: false local_llm_fallback: false analysis_depth: basic # 初期用basic即可 strategic_preferences: preferred_timeframes: [5m, 15m] # 策略默认参考的时间框架 blacklisted_assets: [SHIB-PERP, DOGE-PERP] # 黑名单绝不交易这些高波动或迷因币 correlation_threshold: 0.8 # 如果两个想开的仓位相关性超过0.8则禁止同时开仓避免风险叠加 execution_parameters: slippage_tolerance: 0.005 # 能接受0.5%的滑点超过则订单取消 gas_optimization: moderate # 交易费用优化模式激进(aggressive)、适中(moderate)、保守(conservative) confirmation_blocks: 1 # 等待1个区块确认后才认为交易最终成功 monitoring: health_checks: true # 启用健康检查如心跳包 performance_telemetry: anonymized # 发送匿名性能数据可选 alert_channels: [telegram] # 警报只发到TelegramDiscord可能太吵 # Telegram配置需要额外的bot token和chat id在另一个文件设置。关键参数解读与避坑指南operating_capital: 这是你绝对不能忽视的参数。即使你对策略再有信心也永远不要超过你总交易资金的20%。我建议从5%开始。这个框架是来帮你管理风险和提升效率的不是来“赌身家”的。blacklisted_assets: 一定要设置永续合约市场有很多流动性差、波动性极高的“土狗”币一个闪崩就可能让你的仓位瞬间归零。只交易你熟悉且流动性好的主流币如BTC、ETH、SOL。slippage_tolerance: 在市场波动剧烈时这个值设得太低会导致大量订单失败设得太高则可能以非常差的价格成交。需要根据交易标的的平常流动性来调整。对于BTC/ETH0.0050.5%通常足够对于小币种可能需要放宽到0.01甚至更高。openai_integration:新手切记先关闭。AI分析会引入额外的API调用成本、延迟和不确定性。第一步是让你的基础策略在模拟环境Testnet下稳定运行。3.3 钱包与密钥的安全配置这是整个设置中最敏感的一环。Claw框架支持非托管模式即私钥由你自己保管。# 1. 生成一个新的以太坊钱包用于HyperLiquid的L1账户 # 你可以使用任何你信任的工具如eth-keyfile库或者手动在MetaMask里创建。 # 这里演示用Python脚本生成仅用于测试网主网请用更安全的方式 python -c from eth_account import Account; acct Account.create(); print(Address:, acct.address); print(Private Key (HEX):, acct.key.hex()) # 2. 将私钥加密存储到框架的密钥库 # Claw框架通常提供一个安全的加密存储命令 claw keys encrypt --key 你的私钥 --output ~/.hyperliquid/encrypted_key.json # 执行后它会提示你输入一个强密码来加密这个文件。记住这个密码 # 3. 配置框架使用这个加密的密钥文件 # 这通常在环境变量或另一个配置文件中设置 export HYPERLIQUID_PRIVATE_KEY_FILE~/.hyperliquid/encrypted_key.json # 启动时框架会要求你输入解密密码。安全黄金法则测试网先行永远先在HyperLiquid测试网上配置和运行你的Claw。测试网有免费的模拟资金可以让你任意测试而不会损失真金白银。隔离账户即使上主网也务必使用一个独立的、全新的钱包地址并且只转入你计划用于策略交易的资金。绝对不要使用存有大量资产的主钱包。硬件钱包集成对于较大资金框架支持Ledger/Trezor。这虽然增加了一些操作步骤但将私钥存储在离线设备上安全性是质的提升。强烈建议在熟悉框架后迁移到硬件钱包。密码管理加密密钥文件的密码不要和任何其他网站或服务的密码相同。考虑使用密码管理器生成并保存。3.4 运行你的第一个Claw测试网假设一切配置妥当现在我们来启动一个最简单的“示例”Claw比如一个只打印价格变动但不真正交易的Claw。# 1. 首先切换到测试网模式。这通常通过环境变量或命令行参数实现。 export HYPERLIQUID_NETWORKtestnet # 2. 初始化框架它会检查配置和网络连接。 claw init --profile ~/.hyperliquid/claw_profile.yaml # 3. 列出所有可用的Claw技能。 claw list-skills # 你应该能看到一些内置技能例如 price_logger, simple_mean_reversion。 # 4. 激活一个无害的、仅用于观察的Claw。 claw activate --skill price_logger --markets ETH-PERP BTC-PERP # 5. 打开监控仪表板查看实时状态。 claw monitor --dashboard如果一切正常你应该能在终端或者打开的浏览器仪表板中看到ETH和BTC永续合约的价格在实时滚动更新。恭喜你已经成功搭建了自动化交易系统的“感官系统”。4. 策略开发入门编写你的第一个自定义Claw框架内置的策略可能不符合你的需求。真正的力量来自于自定义。下面我们来创建一个最简单的策略一个“移动平均线交叉”Claw。4.1 Claw技能的结构在项目的skills/目录下新建一个文件my_ma_cross.py。每个Claw技能都是一个类必须继承自基础BaseClaw类并实现几个核心方法。# skills/my_ma_cross.py import pandas as pd import numpy as np from hyperliquid_claw_sdk import BaseClaw, OrderSide, OrderType class MyMovingAverageCrossClaw(BaseClaw): 一个简单的双移动平均线交叉策略Claw。 def __init__(self, config): super().__init__(config) # 从配置中读取参数 self.fast_period config.get(fast_period, 10) # 快线周期 self.slow_period config.get(slow_period, 30) # 慢线周期 self.symbol config.get(symbol, ETH-PERP) # 交易标的 self.position_size config.get(position_size, 0.01) # 开仓量 self.data_window [] # 用于存储价格数据的列表 self.in_position False # 是否持有仓位 def on_market_data(self, data): 当接收到新的市场数据时被调用。 # 假设data是一个包含最新成交价‘price’的字典 current_price data.get(price) if not current_price: return # 1. 更新数据窗口 self.data_window.append(current_price) # 只保留足够计算慢线的最新数据 max_len max(self.slow_period, 100) # 留一些余量 if len(self.data_window) max_len: self.data_window self.data_window[-max_len:] # 2. 检查是否有足够数据计算指标 if len(self.data_window) self.slow_period: self.logger.info(f数据收集中当前{len(self.data_window)}/{self.slow_period}条) return # 3. 计算移动平均线 prices pd.Series(self.data_window) fast_ma prices.rolling(windowself.fast_period).mean().iloc[-1] slow_ma prices.rolling(windowself.slow_period).mean().iloc[-1] # 4. 记录日志可选 self.logger.debug(f价格: {current_price:.2f}, 快线: {fast_ma:.2f}, 慢线: {slow_ma:.2f}) # 5. 生成交易信号 signal self._generate_signal(current_price, fast_ma, slow_ma) return signal def _generate_signal(self, price, fast_ma, slow_ma): 根据均线交叉生成交易信号。 # 金叉快线上穿慢线且当前未持多仓 - 开多 if fast_ma slow_ma and not self.in_position: self.logger.info(f 金叉信号快线{fast_ma:.2f} 慢线{slow_ma:.2f}建议开多仓。) # 返回一个信号字典框架的风险网关会处理它 return { action: open, side: OrderSide.BUY, symbol: self.symbol, order_type: OrderType.MARKET, # 市价单 quantity: self.position_size, reason: MA Golden Cross } # 死叉快线下穿慢线且当前持有多仓 - 平多 elif fast_ma slow_ma and self.in_position: self.logger.info(f⚠️ 死叉信号快线{fast_ma:.2f} 慢线{slow_ma:.2f}建议平多仓。) return { action: close, side: OrderSide.SELL, symbol: self.symbol, order_type: OrderType.MARKET, quantity: self.position_size, # 平掉全部仓位 reason: MA Death Cross } # 无信号 return None def on_order_filled(self, order_info): 当订单成交后被框架调用。 if order_info[side] OrderSide.BUY and order_info[action] open: self.in_position True self.logger.info(f多仓已开立成交价: {order_info[avg_price]}) elif order_info[side] OrderSide.SELL and order_info[action] close: self.in_position False self.logger.info(f多仓已平仓成交价: {order_info[avg_price]}) def get_state(self): 返回Claw的当前状态用于监控仪表盘。 return { fast_ma_period: self.fast_period, slow_ma_period: self.slow_period, in_position: self.in_position, data_points: len(self.data_window) }4.2 配置与启用自定义Claw编写好Claw后需要在配置中启用它。修改你的claw_profile.yaml在active_skills部分添加如果该部分不存在你可能需要查看框架文档确认配置方式或者通过命令行激活。更常见的方式是通过命令行激活并传入参数# 假设你的技能已经放在正确的目录并被框架扫描到 claw activate --skill my_ma_cross \ --params {symbol: ETH-PERP, fast_period: 12, slow_period: 26, position_size: 0.02} \ --network testnet开发与调试心得日志是你的眼睛在Claw中大量使用self.logger.info()和self.logger.debug()。通过日志级别控制输出信息量在调试时设为DEBUG在生产环境设为INFO或WARNING。先在历史数据上回测不要直接上线实盘框架应该提供回测工具。用过去几个月的数据跑一跑你的策略看看盈亏曲线、最大回撤、夏普比率。回测不能预测未来但能帮你发现策略逻辑上的明显漏洞比如在横盘市频繁交易导致手续费磨损殆尽。小仓位实盘测试回测通过后在测试网或用极小仓位比如0.001个ETH在主网运行至少一周观察其实际行为是否与预期一致特别是滑点、成交延迟等回测中难以模拟的因素。5. 高级主题风险管控与多Claw协作当你的策略库丰富起来后如何让它们安全、高效地协同工作就成了新挑战。5.1 全局风险引擎配置除了每个Claw自带的参数框架的全局风险引擎是最后的守门员。你需要深入理解并配置它。这通常在一个独立的risk_config.yaml文件中。# risk_config.yaml global_limits: max_total_exposure: 0.5 # 总保证金占用不得超过净资产的50% max_daily_loss: -0.05 # 单日亏损达到本金的5%停止所有策略 max_drawdown: -0.15 # 从最高净值回撤达到15%停止所有策略 position_limits: per_symbol_max: 0.2 # 单个标的仓位不超过总资金的20% correlated_group_max: 0.3 # 相关性高的标的组如ETH和山寨币总仓位不超过30% circuit_breakers: - trigger: price_change_1m 0.05 # 1分钟内价格变动超过5% action: pause_all # 暂停所有开仓 cooldown: 300 # 暂停5分钟 - trigger: network_latency 1000 # 网络延迟大于1秒 action: cancel_all_pending # 取消所有挂单5.2 多Claw协作模式框架支持几种协作模式独立模式每个Claw独立运行互不知晓。风险引擎负责防止它们冲突例如同时开相反方向仓位。这是最简单的方式。共享信息模式Claw之间可以通过一个共享的内存区域或消息总线传递简单信息。例如一个“市场波动率计算”Claw可以将其计算出的波动率值广播出去其他Claw根据当前波动率水平调整自己的仓位大小。主从模式一个“指挥官”ClawMaster负责分析宏观市场状态然后动态启用或禁用其他“士兵”ClawSlaves并给它们分配资金额度。这需要更复杂的编程但能实现更智能的资金分配。一个实用的多Claw启动脚本示例#!/bin/bash # start_trading_session.sh # 1. 启动市场数据收集和波动率计算Claw不交易 claw activate --skill market_data_collector --markets BTC-PERP,ETH-PERP,SOL-PERP,AVAX-PERP sleep 5 # 2. 根据当前是亚洲、欧洲还是美洲交易时段启动不同的主力策略 CURRENT_HOUR$(date %H) if [[ $CURRENT_HOUR -ge 1 $CURRENT_HOUR -lt 9 ]]; then # 亚洲时段波动较低启用均值回归策略 claw activate --skill mean_reversion_asia --params {symbols: [ETH-PERP, SOL-PERP]} elif [[ $CURRENT_HOUR -ge 9 $CURRENT_HOUR -lt 17 ]]; then # 欧洲时段启用趋势跟踪策略 claw activate --skill trend_follower --params {symbol: BTC-PERP, trend_filter: strong} else # 美洲时段波动大启用突破策略 claw activate --skill breakout_scalper --params {symbol: ETH-PERP, timeframe: 5m} fi # 3. 始终运行一个套利监控Claw低风险 claw activate --skill funding_rate_arbitrage --markets ALL # 4. 启动监控仪表板 claw monitor --dashboard --port 8050 echo 交易系统已启动。监控地址: http://你的服务器IP:80506. 常见问题与故障排查实录在实际运行中你一定会遇到各种问题。下面是我踩过坑后总结的速查表。问题现象可能原因排查步骤与解决方案Claw启动失败提示“ModuleNotFoundError”1. 自定义Claw文件放置目录不对。2. 依赖包未安装。1. 确认你的Claw文件在skills/目录下且该目录包含__init__.py文件。2. 检查你的Claw代码开头的import语句确保所有引用的包都已安装在虚拟环境中 (pip list | grep 包名)。连接HyperLiquid测试网/主网超时1. 网络防火墙或代理问题。2. HyperLiquid节点暂时不可用。3. 系统时间不同步。1. 运行curl -v https://api.hyperliquid-testnet.xyz/info(测试网) 或主网端点检查连通性。2. 查看项目文档或社区确认API端点地址是否有更新。3. 使用date命令检查服务器时间并用sudo ntpdate -u pool.ntp.org同步。订单频繁被拒绝或失败1. 余额不足。2. 价格波动快滑点容忍度设置过低。3. 仓位限制或风险规则触发。4. 订单参数错误如最小数量不对。1. 检查账户余额 (claw account info)。2. 适当提高slippage_tolerance或尝试使用限价单Post Only模式。3. 查看风险网关日志确认是哪条规则阻止了订单。4. 查阅HyperLiquid官方文档确认交易对的最小下单量、价格精度等。策略在回测中盈利实盘却亏损1. 回测过度拟合。2. 未考虑滑点和手续费。3. 实盘市场流动性差异。4. 网络延迟导致成交价差。1. 使用更长的历史数据、进行样本外测试。2. 确保回测脚本中包含了合理的手续费模型和滑点模型。3. 在实盘用极小仓位运行对比实际成交与回测信号的差异。4. 考虑将策略从依赖tick级数据改为1分钟或5分钟K线降低对延迟的敏感性。AI顾问返回无关或错误建议1. 提示词Prompt设计不佳。2. 提供给AI的市场上下文信息不足。3. AI模型本身局限性。1. 精心设计发送给AI的提示词明确其角色“你是一个保守的风险控制顾问”和任务“仅评估此交易的风险不提供新策略”。2. 在请求中附带更多数据当前仓位、近期波动率、市场整体情绪指数等。3. 降低对AI建议的权重仅将其作为众多风控因子中的一个而不是决定性因素。服务器内存或CPU占用过高1. 同时运行Claw数量过多。2. 某个Claw存在内存泄漏如无限列表增长。3. 数据存储未清理。1. 使用claw monitor --system查看各Claw资源消耗停用不必要或低效的Claw。2. 检查你的Claw代码确保在on_market_data等方法中缓存的数据有大小限制如我们之前代码中的self.data_window截断操作。3. 配置日志轮转定期清理旧的日志和缓存文件。最后我想分享一点最重要的心得自动化交易系统是你的仆人不是你的主人。它负责执行纪律、处理信息但战略方向、风险承受能力和最终的责任永远在你这个使用者身上。定期审查你的策略表现警惕市场结构的变化比如从牛市的趋势市转为熊市的震荡市并准备好随时手动干预或关闭系统。这个框架提供了强大的工具但真正的“阿尔法”来源依然是你对市场的深刻理解和不断进化的交易哲学。从测试网开始从小资金开始保持学习保持敬畏。