基于TypeScript的Polymarket预测市场自动化交易机器人开发指南-编程阁

1. 项目概述：一个用于Polymarket预测市场的五分钟交易机器人骨架

如果你对加密货币、体育赛事或者政治事件的预测市场感兴趣，并且想尝试用代码来自动化交易决策，那么你很可能听说过Polymarket。这是一个基于区块链的预测市场平台，用户可以买卖关于未来事件的“是”或“否”的份额。今天要聊的这个项目，OpenClaw Polymarket Betting Bot，就是一个为这类市场量身定制的、开箱即用的自动化交易机器人骨架。它的核心目标非常聚焦：预测某个市场在未来5分钟内，“是”份额的价格是会上涨还是会下跌。

这个项目最吸引我的地方在于它的“骨架”设计理念。它不是一个封装死的、声称能稳定盈利的“黑箱”策略。相反，它提供了一个完整的、模块化的TypeScript框架，将市场数据获取、特征工程、预测模型、模拟交易和结果验证这些核心环节清晰地拆分开来。你可以把它看作一个功能齐全的“实验室”，里面准备好了各种仪器（数据接口、计算模块），而具体的“实验配方”（交易策略）需要你自己来调配和优化。这对于想要深入理解预测市场微观结构、并亲手构建和测试自己交易逻辑的开发者来说，价值巨大。它默认处于“模拟交易”模式，这意味着你可以用真实的市场数据来测试你的想法，而无需承担任何资金风险，这为策略的迭代和验证提供了安全的环境。

2. 核心架构与设计思路拆解

在动手写代码之前，理解这个机器人的整体设计思路至关重要。这能帮助你在后续修改和扩展时，清楚地知道每一部分代码的职责和它们之间的协作关系。

2.1 整体工作流：从数据到决策

这个机器人的核心工作流是一个清晰的循环，我们可以把它想象成一个不断感知、思考、决策的自动化系统。每一次循环，它都执行以下步骤：

数据获取：通过connectors/模块，调用Polymarket的公开API，获取指定市场的实时订单簿、最新成交价、交易量等原始数据。
特征提取：在engine/模块中，对原始数据进行加工，计算出一系列用于预测的“特征”。这是策略的核心，当前版本主要计算三类特征：
- 短期动量：计算过去30秒和2分钟内的价格变化率，捕捉最新的价格趋势。
- 波动率：计算过去2分钟内的价格波动幅度，衡量市场的不确定性或活跃度。
- 大额资金流代理：通过分析近期的大额交易（例如，单笔交易额超过某个阈值）以及成交量与价格变化的关联，来间接推测“聪明钱”的动向。需要注意的是，当前版本并非追踪具体钱包地址，而是基于公开的交易数据做统计推断。
预测评分：将计算好的特征输入到predictor（预测器）中。预测器采用一个轻量级的“集成”模型。简单来说，它会为动量、波动率、资金流这些特征分别赋予权重，计算出一个基础分数。此外，项目提供了一个可选的LLM scorer（大语言模型评分器），你可以接入像OpenAI的GPT系列模型，让AI基于市场标题、描述等文本信息，给出一个“叙事偏向”分数，与基础分数结合，形成最终的综合置信度分数。
模拟交易决策：paper trader（模拟交易器）登场。它接收预测器给出的分数和方向（看涨/看跌），并依据你在.env文件中设置的参数（如EDGE_THRESHOLD边缘阈值）做出决策。如果置信度高于阈值，则生成BUY YES（买入是份额）或SELL YES（卖出是份额，相当于看跌）的信号；否则，发出HOLD（持有）指令。同时，它会根据MAX_POSITION_USD来管理虚拟仓位。
日志与等待：将本次循环的决策、价格、预测概率等信息输出到控制台。然后等待设定的时间间隔（LOOP_SECONDS），开启下一次循环。

2.2 项目目录结构解析

清晰的目录结构是项目可维护性的基础。OpenClaw Bot的代码组织得非常模块化：

src/ ├── app/ # 机器人主程序入口 │ └── index.ts # 核心循环逻辑，使用 `npm run dev` 启动 ├── server/ # 本地Web服务器（用于结果对比UI） │ └── index.ts # 提供UI页面和预测数据API，使用 `npm run ui` 启动 └── lib/ # 共享的核心功能库（被app和server共同引用） ├── config.ts # 环境变量配置管理 ├── types/ # TypeScript类型定义，确保代码安全 ├── connectors/ # 数据连接层，封装与Polymarket API的交互 ├── engine/ # 策略引擎：特征计算、预测器、模拟交易器 └── models/ # 可选的大语言模型（LLM）集成层

这种分离带来了几个好处：首先，职责清晰。connectors只负责拿数据，engine只负责处理数据和逻辑，app负责调度。其次，便于复用。比如lib/下的核心逻辑既可以被实时交易机器人（app）使用，也可以被后端服务器（server）调用来提供API。最后，易于测试和扩展。你想替换数据源？改connectors。想尝试新的预测模型？改engine/predictor。这种设计让你能像搭积木一样调整机器人的能力。

注意：初次接触时，建议先聚焦于app/index.ts和lib/engine/下的几个核心文件。app/index.ts是机器人运行的主循环，像项目的心脏；而engine/里的文件则是大脑，决定了机器人如何思考。理解它们的交互，就掌握了项目的命脉。

3. 环境配置与快速启动指南

理论说得再多，不如实际跑起来看看。这一部分，我会带你完成从零开始的环境搭建，并让机器人先“动”起来。

3.1 前期准备与依赖安装

首先，确保你的开发环境已经就绪。你需要安装Node.js（建议版本18或以上）和npm（通常随Node.js一起安装）。你可以通过在终端运行node -v和npm -v来检查是否安装成功。

接下来，获取项目代码。打开终端，使用git命令克隆仓库：

git clone https://github.com/TopTrenDev/openclaw-polymarket-betting-bot.git cd openclaw-polymarket-betting-bot

进入项目目录后，安装所有必要的依赖包。项目使用TypeScript编写，依赖项都定义在package.json里，执行以下命令：

npm install

这个过程可能会花费一两分钟，npm会下载所有需要的库，包括TypeScript编译器、用于HTTP请求的axios或fetch、环境变量管理工具dotenv等。

3.2 关键配置文件详解

安装完依赖后，最重要的一步是配置环境变量。项目根目录下有一个.env.example文件，它是配置模板。我们需要复制它并创建自己的.env文件：

cp .env.example .env

现在，用你喜欢的文本编辑器（如VSCode、Sublime Text）打开新创建的.env文件。这里面的每一个变量都控制着机器人的不同行为，我们来逐一拆解：

# Polymarket API 配置（核心） POLYMARKET_REST_BASE=https://gamma-api.polymarket.com # 你可以指定一个具体的市场，例如关于“BTC价格”的某个市场。如果留空，机器人会随机选择一个活跃市场。 POLYMARKET_MARKET_SLUG= POLYMARKET_MARKET_ID= # 机器人运行循环配置 LOOP_SECONDS=30

POLYMARKET_REST_BASE：这是Polymarket官方API的基础地址，通常不需要修改。
POLYMARKET_MARKET_SLUG或POLYMARKET_MARKET_ID：这是指定交易市场的关键。Slug是市场URL中易读的部分（如will-bitcoin-btc-price-above-65000），ID是内部的唯一标识符。我个人的经验是，初期测试时可以先留空，让机器人自己找一个活跃的“BTC涨跌”类市场，这能快速验证整个流程是否通畅。等流程跑通后，再去找一个你感兴趣的具体市场填入。
LOOP_SECONDS：循环间隔，单位是秒。设置为30意味着机器人每30秒获取一次数据、做一次预测。这里有个需要注意的点：预测目标是“5分钟后价格是否上涨”。如果你的循环间隔太短（比如5秒），会导致预测频率过高，信号可能互相干扰；间隔太长（比如300秒），又会错过很多机会。30-60秒是一个比较常见的起步设置，你可以在后续根据策略表现调整。

# 模拟交易（风控）配置 MAX_POSITION_USD=10 EDGE_THRESHOLD=0.02

MAX_POSITION_USD：模拟交易中，单次交易允许的最大仓位价值（美元）。这纯粹是一个虚拟风控参数，用于计算模拟盈亏。设为10意味着每次买卖信号会假设用10美元来交易。
EDGE_THRESHOLD：这是整个策略的“触发门槛”，非常重要。预测器会输出一个置信度分数（例如，认为上涨的概率是55%）。如果|置信度 - 0.5| > EDGE_THRESHOLD，才会产生交易信号。例如，阈值设为0.02，那么置信度必须高于0.52才会“买入是”，低于0.48才会“卖出是”。介于0.48-0.52之间则保持观望（HOLD）。设置太低（如0.005）会导致机器人频繁交易，对噪音敏感；设置太高（如0.1）则可能永远不交易。建议从0.02开始，根据回测结果调整。

# 可选：大语言模型（LLM）集成配置 OPENAI_API_KEY=sk-你的实际API密钥 OPENAI_BASE_URL=https://api.openai.com/v1 # 如果你使用第三方代理，可能需要修改 OPENAI_MODEL=gpt-3.5-turbo

这部分是可选的。如果你希望机器人能读取市场标题和描述，并用AI分析市场情绪，就需要配置OpenAI的API密钥。如果你暂时不想用这个功能，最简单的方法是直接注释掉或删除这三行，机器人会完全依靠价格和交易量数据特征来做决策。

3.3 首次运行与验证

配置完成后，就可以启动机器人了。在项目根目录下运行：

npm run dev

如果一切顺利，你将在终端看到连续的日志输出。初始几行会显示配置加载成功、连接Polymarket API等信息。随后，你会看到周期性的日志，通常包含以下信息：

Market: [市场名称]：当前正在监控的市场。
Current YES Price: $0.XX：当前“是”份额的实时价格。
Features: {...}：计算出的动量、波动率等特征值。
Prediction: UP/DOWN, p5m: 0.XX, confidence: 0.XX：预测方向、5分钟后上涨的概率、综合置信度。
Action: HOLD/BUY YES/SELL YES：模拟交易器根据置信度和阈值做出的最终决策。

看到这样规律滚动的日志，就说明机器人已经成功运行起来了！它正在按照你的配置，定期抓数据、做计算、出决策。不过，现在它只是在“自言自语”，我们还需要一个工具来验证它的预测到底准不准。这就是下一个章节要介绍的“对比UI”。

4. 核心模块深度解析与实操要点

让机器人跑起来只是第一步。要真正理解并改进它，我们必须深入其核心模块。这一部分，我会拆解lib/engine/目录下的几个关键组件，并分享一些实操中的调整思路。

4.1 特征工程：如何从原始数据中提取信号

特征工程是量化策略的基石，它的目标是把杂乱的市场原始数据，转化为能够预示未来价格变化的有效信号。OpenClaw Bot当前实现了三类特征，我们来看看它们的计算逻辑和潜在优化点。

1. 短期动量：

// 伪代码逻辑示意 function calculateMomentum(priceHistory: PriceBar[], lookbackSeconds: number): number { const nowPrice = priceHistory[0].close; // 最新价格 const pastPrice = priceHistory.find(bar => bar.time <= now - lookbackSeconds*1000)?.close; if (!pastPrice) return 0; return (nowPrice - pastPrice) / pastPrice; // 收益率 }

计算：分别计算过去30秒和2分钟的价格收益率（(当前价-过去价)/过去价）。正值表示上涨动量，负值表示下跌动量。
实操要点：lookbackSeconds（回看时间窗口）是一个可以优化的超参数。在5分钟预测尺度下，30秒和2分钟是合理的短期窗口。你可以尝试增加一个更短的窗口（如10秒）来捕捉瞬时脉冲，或者增加一个中等窗口（如1分钟）来平滑噪音。我的经验是，多时间窗口动量可以构成一个简单的趋势强度指标，例如，如果所有窗口动量都为正且数值递增，可能意味着趋势在加速。

2. 波动率：

计算：通常使用过去2分钟内价格的标准差或平均真实波幅（ATR）。高波动率可能意味着市场分歧大、方向不明；低波动率可能意味着市场在积蓄能量。
实操要点：波动率特征的使用方式很关键。一种常见做法是将动量除以波动率，得到一个“风险调整后的动量”，这能在市场剧烈无序波动时，降低信号的权重。你可以尝试在predictor中引入这样的组合特征。

3. 大额资金流代理：

计算：当前版本通过分析近期（如过去1分钟）成交订单，筛选出单笔金额较大的交易（“鲸鱼”交易），并计算这些大额交易净方向（买入“是”多还是卖出“是”多）以及其成交量占总成交量的比例。
注意事项与优化：这是当前版本的一个简化实现。真正的“聪明钱”追踪需要链上数据（钱包地址分析），这复杂得多。在现有框架下，你可以优化的方向有：
- 动态阈值：将“大额”定义为超过过去N笔交易平均金额的X倍，而不是一个固定美元值。
- 价格影响：结合大额交易发生时的价格变化。如果一笔大买单瞬间将价格推高了，这可能比一笔在当前价成交的大买单更有看涨意义。
- 订单簿分析：除了成交记录，还可以从connectors获取实时订单簿，观察大额限价单在买盘和卖盘的堆积情况，这可能是更强的领先指标。

4.2 预测器：集成模型与LLM的融合

预测器（predictor）是接收所有特征并输出最终决策建议的“大脑”。它目前的工作流程如下：

基础分数计算：为动量（30s, 2m）、波动率、资金流等每个特征分配一个权重（这些权重可能硬编码在代码中，或可通过配置调整）。将特征值乘以权重后求和，得到一个原始分数。然后通过一个函数（如Sigmoid）将这个分数映射到0-1之间，表示为p5m，即“5分钟后价格上涨的概率”。
LLM叙事评分（可选）：如果配置了LLM，预测器会将市场的问题描述（如“到6月30日，BTC价格会高于70000美元吗？”）发送给AI模型，并要求模型基于当前新闻、社交媒体情绪或常识，给出一个看涨或看跌的倾向性评分（例如，从-1到1）。
分数融合：将基础模型算出的p5m与LLM的倾向性评分进行加权融合，得到最终的confidence（置信度）。例如，final_confidence = 0.7 * p5m + 0.3 * llm_score。

实操心得与扩展思路：

权重调优：特征权重是策略的核心参数。不要凭感觉设置。一个标准的方法是使用历史数据进行回测，通过网格搜索或简单的优化算法（如爬山法）来寻找一组能最大化历史预测准确率或模拟收益的权重。项目目前的paper trader主要用于实时模拟，你需要自己扩展一个回测框架。
LLM的使用技巧：直接让LLM预测价格涨跌效果通常不稳定。更好的Prompt设计是让它进行情感分析或事件推理。例如：“给定以下市场描述‘[描述]’，以及当前加密货币领域的整体情绪（可附上几条最新推文摘要），请判断在接下来的一小时内，市场参与者对此结果的乐观情绪是上升、下降还是中性？请仅输出‘上升’、‘下降’或‘中性’。” 然后将文本输出转化为数值分数。
模型升级：基础加权求和模型比较简单。你可以考虑引入更复杂的机器学习模型，例如逻辑回归、轻量级梯度提升树（LightGBM）甚至简单的神经网络。这些模型可以自动学习特征之间的非线性关系。你需要将engine/predictor模块重构为可训练、可加载模型的模式。

4.3 模拟交易器：风险控制与决策执行

模拟交易器（paper trader）是策略与“市场”之间的最终关口。它接收预测器的输出（方向、置信度），并依据既定规则做出是否交易、交易多少的决策。

其核心逻辑可以用以下伪代码表示：

function makeDecision(predictedDirection: ‘UP‘ | ‘DOWN‘, confidence: number, currentPosition: ‘NONE‘ | ‘LONG‘ | ‘SHORT‘) { const edge = Math.abs(confidence - 0.5); // 计算“优势”程度 if (edge < EDGE_THRESHOLD) { return ‘HOLD‘; // 优势不足，观望 } if (predictedDirection === ‘UP‘) { if (currentPosition !== ‘LONG‘) { // 计算仓位大小，例如：positionSize = MAX_POSITION_USD * (edge - THRESHOLD) * 2; // 动态仓位 return { action: ‘BUY YES‘, size: positionSize }; } else { return ‘HOLD‘; // 已经持有多头仓位 } } else { // predictedDirection === ‘DOWN‘ if (currentPosition !== ‘SHORT‘) { return { action: ‘SELL YES‘, size: positionSize }; } else { return ‘HOLD‘; } } }

关键参数与风控思考：

EDGE_THRESHOLD（边缘阈值）：如前所述，这是过滤低质量信号的第一道防线。一个高级技巧是动态阈值。例如，在市场波动率高的时候，可以适当提高阈值，因为噪音更大，需要更强的信号才值得交易。
MAX_POSITION_USD（最大仓位）：在模拟交易中，这主要用于计算盈亏。但在设想实盘时，它关联着仓位管理。更科学的仓位管理不是固定每笔10美元，而是基于凯利公式或固定比例风险（如每次交易冒险总资金的1%）来计算。
止盈止损：当前框架没有实现止盈止损逻辑。在实盘策略中，这是必须的。你需要在paper trader中维护每个仓位的开仓价，并持续检查当前价格是否触及了预设的止盈或止损线，从而触发平仓动作。

5. 结果验证与策略迭代：使用对比UI

策略的好坏不能只看机器人输出的日志，必须进行客观的验证。项目内置的对比UI（npm run ui）就是一个轻量级但极其有用的验证工具。

5.1 启动与使用对比UI

在项目根目录下，新开一个终端窗口，运行：

npm run ui

控制台会提示服务已启动，通常在http://localhost:8787。用浏览器打开这个地址，你会看到一个简洁的Web界面。

这个UI的核心功能是进行“事后验证”：

获取预测：点击“Fetch Latest Prediction”按钮，它会从正在运行的机器人（npm run dev）中获取最近一次预测的快照，包括市场名称、当前价格、预测方向、上涨概率p5m和置信度。
记录结果：等待5分钟（或者你认为合适的预测周期后），在“Actual YES Price After 5min”输入框里，填入5分钟后的实际“是”份额价格。你可以手动从Polymarket网站查询，或者更酷的是——写一个简单的脚本自动获取并填入。
对比分析：点击“Compare”按钮。UI会判断你之前的预测是否正确（预测上涨且实际价格上涨，或预测下跌且实际价格下跌），并更新“Accuracy”（准确率）统计。

5.2 如何利用UI进行策略诊断与迭代

这个UI不仅仅是记录对错，更是你优化策略的“显微镜”。

识别模式：连续记录几十次预测后，观察哪些情况下容易错。是市场突然出现重大新闻时？还是在价格横盘、波动率极低的时候？这些观察能直接指导你改进特征工程。例如，你发现横盘时错误率高，就可以考虑在特征中加入一个“横盘识别器”（如最近N根K线的振幅小于某个值），当这个特征触发时，让预测器降低置信度或直接输出HOLD。
参数调优：你可以手动修改.env中的EDGE_THRESHOLD，然后运行一段时间，用UI记录不同阈值下的准确率。比如，阈值0.01时交易频繁但准确率55%，阈值0.03时交易稀少但准确率65%。你需要权衡交易频率和胜率，找到最适合你风险偏好的平衡点。
特征有效性检验：通过修改engine/中的特征计算代码，你可以“关闭”某个特征（将其权重设为0），然后运行对比测试，看准确率是上升还是下降。这是验证你新增或修改的特征是否有用的最直接方法。

一个实用的操作流程建议：

保持npm run dev在后台运行，让机器人持续产生预测。
打开UI页面，每隔5分钟手动或自动获取一次预测并记录结果。
每天或每周汇总一次数据，计算准确率、盈亏（如果模拟了仓位）。
根据分析结果，提出假设（例如：“加入RSI指标可能改善在超买/超卖区域的预测”）。
修改代码，实现新特征或调整模型。
重复步骤1-5，进行下一轮测试。

这个过程就是量化策略开发的核心闭环：想法 -> 实现 -> 回测/模拟 -> 分析 -> 改进。

6. 常见问题排查与进阶扩展方向

在实际操作中，你肯定会遇到各种各样的问题。这里我整理了一些常见的情况和解决思路，以及对这个项目未来可以如何扩展的一些想法。

6.1 常见运行问题与解决方案

问题现象	可能原因	排查步骤与解决方案
运行`npm run dev`后立即报错，提示`Cannot find module`	依赖未安装或安装不全	1. 确认在项目根目录。 2. 删除`node_modules`文件夹和`package-lock.json`文件。 3. 重新运行`npm install`。
机器人启动成功，但日志显示`Failed to fetch market data`或`Market not found`	1. Polymarket API暂时不可用。 2. 配置的市场Slug或ID错误。 3. 网络连接问题。	1. 访问`POLYMARKET_REST_BASE`对应的网址，检查API状态。 2. 检查`.env`中的`POLYMARKET_MARKET_SLUG`或`POLYMARKET_MARKET_ID`。建议先留空，让机器人自动选择市场，以排除配置错误。 3. 检查网络代理设置（如果你需要使用）。
预测结果始终是`HOLD`，几乎没有交易信号	`EDGE_THRESHOLD`设置过高。	查看日志中的`confidence`值。如果它总是在0.5附近小幅波动（如0.49-0.51），而你的阈值是0.05，那肯定无法触发。尝试逐步调低`EDGE_THRESHOLD`到0.01或0.005，观察信号变化。
UI页面 (`npm run ui`) 无法打开或显示空白	端口冲突或服务器未正确启动。	1. 检查控制台是否有错误输出。 2. 确认端口8787未被其他程序占用。可以修改`src/server/index.ts`中的端口号。 3. 确保先运行了`npm run dev`，因为UI需要从主程序获取预测数据。
LLM功能启用后，机器人运行速度变慢或出错	1. API密钥无效或额度不足。 2. 网络请求超时。 3. Prompt设计导致返回格式异常。	1. 验证`OPENAI_API_KEY`是否正确且有余额。 2. 在代码中为LLM请求增加超时设置和错误处理（try-catch）。 3. 检查`src/lib/models/llmScorer.ts`中解析AI返回结果的逻辑，确保能处理各种意外响应。

6.2 从模拟到实盘的考量

OpenClaw Bot目前是一个完美的模拟和实验框架。但如果你经过充分测试后，考虑将其用于实盘，请务必极度谨慎，并至少做好以下准备：

更换实盘交易接口：你需要将lib/connectors/中只读的API客户端，替换为支持下单、查询账户的Polymarket交易API客户端。这通常需要处理API密钥、签名请求等更复杂的安全逻辑。
强化错误处理与监控：模拟环境可以容忍偶尔的错误。实盘则需要坚如磐石的稳定性。必须为每一个网络请求、数据处理步骤添加详尽的错误处理、重试机制和警报（如发送邮件、Telegram消息）。
实施严格的风险管理：在paper trader的基础上，必须集成完整的仓位管理、止损止盈、每日/总体亏损限额等风控模块。这是保护本金的生命线。
小资金起步，长期验证：即使模拟表现优异，实盘也请用你完全输得起的极小资金开始，并持续运行至少一个月，跨越不同的市场状况，来验证策略的鲁棒性。

6.3 项目扩展与个性化改造思路

这个项目的骨架设计为扩展留下了巨大空间。以下是一些可以尝试的方向：

接入更多数据源：除了Polymarket自身数据，你可以在connectors/下添加新的模块，获取币安/Coinbase的BTC现货价格、恐惧贪婪指数、特定关键词的社交媒体情绪指数等，作为额外的特征输入。
实现策略回测框架：这是当前项目缺失但至关重要的一环。你可以编写一个脚本，读取Polymarket的历史市场数据（可能需要自己收集或购买），然后按照时间顺序，模拟运行你的策略引擎，并计算夏普比率、最大回撤、胜率等关键指标。这是科学评估策略性能的唯一方法。
尝试更复杂的模型：将简单的加权求和预测器，替换为基于TensorFlow.js或ONNX Runtime的轻量级机器学习模型。你可以使用历史数据离线训练一个模型，然后将模型文件加载到机器人中在线推理。
开发图形化监控面板：将ui/目录下的简单对比页面，扩展成一个包含实时价格图表、信号标注、资金曲线、绩效统计的完整仪表盘。可以使用Chart.js或ECharts来实现。

我个人在改造类似项目时，第一个增加的往往是回测框架。因为“感觉会赚钱”和“数据证明能赚钱”之间有巨大的鸿沟。通过回测，你可以快速验证上百种参数组合和特征组合，避免在无效的想法上浪费大量时间。当你有一个在历史数据上表现稳定的策略后，再用模拟交易去验证其在实时市场中的适应性，最后才考虑极小规模的实盘。这个循序渐进的过程，是量化交易者控制风险、提升认知的最佳路径。