1. 项目概述：一个为普通人打造的加密资产守护神
在加密货币的世界里，技术壁垒和信息不对称就像一道无形的墙，将许多普通人挡在了安全投资的门外。我们见过太多这样的场景：一位想为子女攒点教育金的母亲，因为误点了钓鱼链接而损失毕生积蓄；一位刚入行的年轻人，被天花乱坠的“百倍币”宣传冲昏头脑，最终遭遇“拉地毯”骗局。问题不在于他们不够谨慎，而在于面对精心设计的骗局和复杂的链上数据，普通人缺乏有效的“武器”和“哨兵”。这正是我们构建Binance Guardian AI的初衷——与其再做一个帮人“赚钱”的交易机器人，不如做一个帮人“守财”的智能卫士。
这个项目是一个基于OpenClaw AI 框架和Binance API构建的加密货币安全助手。它的核心使命不是提供交易信号，而是充当用户，尤其是非技术背景用户（如长辈、新手投资者）的 24/7 安全伴侣。通过一个简单的 Telegram 机器人界面，它能实时检测钓鱼网站、分析智能合约风险、用大白话解释行业黑话，并提供一套完整的 30 天安全课程。我们坚信，真正的金融普惠，始于对风险的有效识别和防范。这个工具就像一个全天候在线的、懂区块链的“家庭安全顾问”，旨在将专业的安全审计能力，以零门槛的方式交付给每一个普通用户。
2. 核心架构与设计哲学：为何选择“四层分离”？
一个健壮的系统始于清晰的架构。在设计 Guardian AI 时，我们摒弃了将所有功能塞进一个“大泥球”的常见做法，而是采用了清晰的四层分离架构。这不仅仅是为了代码整洁，更是为了安全性、可维护性和未来扩展性。
2.1 用户交互层：极简主义的入口
所有复杂的功能，最终都需要一个简单的出口。我们选择了Telegram Bot作为主要交互界面，原因有三：
- 零安装成本：用户无需下载新App，在熟悉的聊天环境中即可使用。
- 跨平台与移动优先：完美适配手机操作，方便长辈随时随地咨询。
- 天然的会话上下文：聊天记录本身就是安全审计的日志，方便回溯。
在这一层，我们设计了两种模式界面：
- 守护模式：面向新手和长辈，界面只有 5 个核心按钮（快速检查、风险评分、每日一课、诈骗案例、语音简报），最大限度减少认知负担。
- 专业模式：面向有一定经验的交易者，提供账户概览、市场数据、价格警报等进阶功能。两种模式通过密码切换，防止家人误操作进入复杂界面。
实操心得：在设计按钮回调时，务必处理好异步操作和超时。Telegram Bot 对回调查询有 10 秒的响应限制，如果 AI 分析或 API 调用耗时过长，需要先发送一个“正在处理”的临时消息，再用
editMessageText更新结果，避免用户收到超时错误。
2.2 AI 智能体层：系统的大脑与决策核心
这是项目的灵魂所在，基于OpenClaw框架构建。OpenClaw 提供了强大的智能体（Agent）编排能力，让我们能灵活地串联不同的工具和 LLM（大语言模型）。我们的设计采用了“路由-执行-复核”的工作流：
- 意图识别与路由：用户输入一句话，AI 首先判断其意图（是检查链接、分析合约，还是询问概念）。我们微调了一个轻量级分类器来完成这一步，这比直接将所有上下文扔给大模型要快且准。
- 工具调用与执行：根据意图，OpenClaw Agent 会自主选择并调用相应的工具。例如，识别到合约地址，则调用“合约分析工具”；识别到 URL，则调用“钓鱼检测工具”。
- 双模型协作与复核：我们接入了Claude和Gemini双模型。常规分析和解释由 Claude 负责，因其在遵循指令和生成安全、细致的回复方面表现优异。当遇到高风险的模糊案例时，系统会将问题同时抛给 Gemini 进行交叉验证，综合两者结论后给出最终判断，这相当于增加了一道人工复核环节。
- 结果格式化与输出：AI 将工具返回的原始数据（如合约验证状态、交易次数）转化为用户能听懂的风险描述和安全建议，并附上明确的评分（0-100）和风险等级（低、中、高、严重）。
// 伪代码示例：OpenClaw Agent 处理合约检查的核心逻辑 async function analyzeContract(contractAddress, chain) { // 1. 路由：根据链参数选择对应的区块链浏览器API const explorerAPI = getExplorerAPI(chain); // 2. 工具调用：并行获取合约信息 const [verificationStatus, txCount, holderData] = await Promise.all([ explorerAPI.checkContractVerification(contractAddress), explorerAPI.getTransactionCount(contractAddress), explorerAPI.getTopHolders(contractAddress) ]); // 3. AI分析与评分：将原始数据交给LLM进行评估 const analysisPrompt = ` 基于以下数据评估合约风险： - 验证状态: ${verificationStatus} - 交易笔数: ${txCount} - 前10名持有者占比: ${holderData.concentration}% 请给出0-100的安全评分和详细理由。 `; const aiAssessment = await claudeAPI.complete(analysisPrompt); // 4. 格式化输出 return formatResponseForUser(aiAssessment, contractAddress); }2.3 数据集成层：连接现实世界的触手
AI 的决策需要可靠的数据源。这一层集成了多个外部服务，是系统的“眼睛和耳朵”。
- Binance API（只读）：获取用户账户的资产快照、充值提现记录，用于“账户健康度”检查。至关重要的一点：我们强制要求用户创建并仅使用“只读”权限的 API Key。这意味着 Guardian AI 只能看，不能动，从根本上杜绝了误操作或潜在恶意代码导致资产转移的风险。在代码中，我们甚至硬性检查了 API Key 的权限标签。
- 多链区块链浏览器：支持 9 条主流链（ETH, BSC, Polygon 等）的合约查询。我们封装了一个统一的适配器，根据用户提供的链 ID 或名称，自动切换到对应的浏览器 API（如 Etherscan, BscScan）。核心检查项包括：合约是否开源验证、创建者、交易总数、持币集中度。
- 公开诈骗数据库：维护一个本地的、定期更新的钓鱼域名和已知诈骗合约地址黑名单。同时，会调用一些社区维护的 API（如
scam-alert.io的公共列表）进行交叉比对。 - 市场数据源：集成 NOFX 的 AI500 榜单，用于识别短期内被过度炒作、风险可能较高的代币。
注意事项：频繁调用第三方 API 存在速率限制和 IP 封锁风险。我们的策略是：1) 为所有请求添加合理的延迟；2) 实现请求结果的缓存机制（例如，将已验证安全的合约地址缓存 24 小时）；3) 准备多个备用数据源（如 RPC 节点）作为降级方案。
2.4 基础设施层：确保稳定运行的基石
为了让这个“守护神”7x24小时在线，我们选择了轻量化的部署方案：
- 服务器：一台基础配置的 VPS（如 1核1G），月成本约 11 美元。
- 进程管理：使用PM2守护 Node.js 进程，实现崩溃自动重启、日志轮转。
- 配置管理：所有敏感信息（API Keys, Bot Token）通过
config.json文件管理，该文件被严格排除在 Git 版本控制之外。我们提供了config.example.json模板供用户参考。 - 日志与监控：输出结构化日志到文件，便于问题排查。同时，Bot 自身集成了一个简单的
/status命令，可汇报内存使用、运行时长等基本信息。
3. 核心功能深度解析与实操要点
3.1 钓鱼链接检测：不只是域名比对
当用户发送一个可疑链接时，Guardian AI 的检测流程远比简单的字符串匹配复杂：
- 即时特征分析：
- 域名混淆检查：识别
bínance.com(含特殊字符)、binance-support.com(子域名误导) 等常见把戏。 - URL 结构分析：检查是否包含
connect、walletlink、approve等高风险路径或参数。 - SSL 证书检查：快速验证证书颁发者是否可信（虽然钓鱼站也可能有廉价证书）。
- 域名混淆检查：识别
- 后台深度验证：
- IP 与 WHOIS 查询：对比真实官网的 IP 段和注册信息。
- 截图与内容比对（实验性功能）：使用无头浏览器获取页面截图，通过 AI 图像识别粗略比对页面布局与官方页面是否一致。
- 动态风险库更新：我们建立了一个简单的反馈循环。当多个用户查询同一可疑域名时，系统会将其标记为“待复核”，并尝试进行更深入的静态分析或提交给社区列表。
给用户的回复示例：
⚠️ **【高仿钓鱼警报】** 您查询的链接 `https://www.binance.airdrop-claim.com` 高度可疑！ 🔍 **我们的分析发现**： 1. **域名欺诈**：使用了 `binance.` 作为子域，试图伪装成 Binance 相关页面。 2. **非官方域名**：主域为 `airdrop-claim.com`，与 Binance 官方域名 (`binance.com`) 无关。 3. **典型骗局特征**：链接包含 `airdrop`、`claim` 等诱导性词汇，是空投钓鱼的常见手法。 🛡️ **行动建议**： • **立即关闭**该网页。 • **切勿**输入您的账号密码、短信验证码或助记词。 • 真正的空投活动只会在 Binance **官方公告**中发布。 ✅ **安全访问方式**： 请始终手动输入：https://www.binance.com这个回复不仅给出判断，更解释了“为什么”，并提供了明确的安全操作指引。
3.2 智能合约安全评分：量化风险的四个维度
对于合约地址，我们不是简单回复“安全”或“危险”，而是生成一个 0-100 的安全评分，它由四个维度的子分数加权计算得出：
| 维度 | 权重 | 检查项 | 高分特征 | 低分/风险特征 |
|---|---|---|---|---|
| 1. 可信度 | 30% | 合约验证状态、创建者信息、审计报告 | 已通过 Etherscan/BscScan 验证，创建者为知名项目方多签地址，有 CertiK/SlowMist 审计报告。 | 未验证合约，创建者地址匿名且为新地址，无审计信息。 |
| 2. 活跃度 | 25% | 总交易数、近期交易频率、持币地址数 | 交易数 > 10,000，近期交易活跃，持币地址数 > 1,000。 | 交易数极少（如 < 100），近一周无交易，持币地址寥寥无几。 |
| 3. 健康度 | 25% | 前10名持币占比、流动性池锁定情况 | 持币分散（前10占比 < 20%），流动性池通过知名平台（如 Uniswap, PancakeSwap）锁定。 | 持币高度集中（前10占比 > 60%），流动性池未锁定或锁定期极短。 |
| 4. 声誉度 | 20% | 社区舆情、是否在黑名单、关联地址风险 | 社交媒体有真实讨论，未出现在主流黑名单中，关联地址无不良记录。 | 社区充斥刷量评论，被多个安全平台标记，关联地址曾涉及诈骗。 |
计算过程示例： 假设一个 BSC 上的合约，检查结果如下：
- 可信度：已验证，但无知名审计（得分 70/100）→ 贡献 70 * 0.3 = 21
- 活跃度：交易数 500，持币地址 80（得分 40/100）→ 贡献 40 * 0.25 = 10
- 健康度：前10持仓占比 85%（得分 15/100）→ 贡献 15 * 0.25 = 3.75
- 声誉度：未在黑名单，但社区讨论极少（得分 50/100）→ 贡献 50 * 0.2 = 10
- 最终安全分= 21 + 10 + 3.75 + 10 =44.75，四舍五入为45，属于“高风险”。
实操心得：权重并非一成不变。对于 DeFi 合约，“健康度”（防“拉地毯”）的权重应该更高；对于 NFT 项目，“声誉度”和社区活跃度可能更关键。我们在专业模式中允许高级用户微调这些权重。
3.3 30天安全课程：将知识拆解为每日习惯
安全意识的培养无法一蹴而就。我们设计了为期30天的渐进式课程，每天通过 Bot 推送一个 5 分钟内可读完的微课程。内容设计遵循“概念-风险-实操”三步法：
- 第1周：认识基础（什么是钱包、公钥私钥、Gas费）
- 第2周：识别风险（钓鱼、假币、庞氏骗局）
- 第3周：安全操作（如何安全交易、使用硬件钱包）
- 第4周：进阶认知（理解智能合约、DeFi 风险、市场情绪）
每天课程末尾都有一个简单的互动问答或小任务（如“请找出这条消息中的可疑点”），强化学习效果。所有进度保存在本地 JSON 文件中，确保隐私。
3.4 只读账户监控：家庭的“财务健康仪表盘”
对于授权了只读 API Key 的用户，Guardian AI 可以定期（如每天一次）扫描账户，生成一份“健康报告”：
- 资产异动警报：大额充值或提现时通知（可自定义阈值）。
- 资产分布建议：过于集中在某个高风险小币种时给出提示。
- 授权检查（通过区块链数据）：提醒用户检查是否对不明合约有过高的代币授权额度，这是许多盗币事件的根源。 这个功能让家人之间可以多一份安心，尤其适合子女远程关注长辈的投资账户健康状况。
4. 从零到一的部署与配置实战
4.1 环境准备与依赖安装
首先，你需要一台可以长期运行的服务器。这里以 Ubuntu 22.04 为例。
# 1. 更新系统并安装 Node.js 18（推荐使用 nvm 管理版本） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash source ~/.bashrc nvm install 18 nvm use 18 # 2. 克隆项目代码 git clone https://github.com/pjl914335852-ux/Binance-guardian-ai.git cd Binance-guardian-ai # 3. 安装项目依赖 npm install # 4. 安装 PM2 用于进程管理 npm install -g pm24.2 关键配置详解：安全是第一位
项目根目录下的config.example.json是配置模板。请复制它并创建你的config.json文件：
cp config.example.json config.json nano config.json # 或用你喜欢的编辑器下面逐项解释关键配置，请务必仔细阅读：
{ "telegram": { "botToken": "YOUR_BOT_TOKEN_HERE", // 从 @BotFather 申请 "chatId": "YOUR_PERSONAL_CHAT_ID" // 用于接收系统警报，非必须但建议 }, "cryptoex": { "apiKey": "YOUR_BINANCE_READONLY_API_KEY", "apiSecret": "YOUR_BINANCE_API_SECRET", "exchangeId": "binance" }, "ai": { "anthropicApiKey": "YOUR_CLAUDE_API_KEY", // 来自 Anthropic 控制台 "googleAiApiKey": "YOUR_GEMINI_API_KEY" // 来自 Google AI Studio }, "security": { "enableIpWhitelist": false, // 如开启，需在Binance API设置IP白名单 "riskScoreThreshold": 40, // 低于此分触发强烈警告 "cacheDuration": 3600 // 缓存时间（秒），减轻API压力 }, "mode": "guardian" // 启动模式：'guardian' 或 'professional' }配置要点与避坑指南：
Telegram Bot Token：
- 在 Telegram 中搜索
@BotFather，发送/newbot并按提示操作。 - 获取到的 token 格式类似
710012345:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw。 - 安全提示：Bot Token 一旦泄露，他人可控制你的机器人。切勿上传至公开仓库。
- 在 Telegram 中搜索
Binance API Key（重中之重）：
- 登录 Binance 官网，进入【用户中心】->【API 管理】。
- 点击【创建 API】，系统会要求你进行二次验证。
- 在权限设置中，务必且仅勾选【读取】权限。绝对不要勾选【交易】、【提现】等任何资金操作权限。
- 创建后，建议进一步设置IP 白名单（在配置中启用
enableIpWhitelist后，填入你服务器的公网 IP），这样即使 API Key 和 Secret 泄露，攻击者也无法从其他 IP 地址访问。 - API Secret 仅在创建时显示一次，请妥善保存。
AI API Keys：
- Claude API Key 需在 Anthropic 官网申请。Gemini API Key 可在 Google AI Studio 免费获取。
- 初期测试或轻度使用，可以只配置其中一个。双模型协作逻辑在代码中已做降级处理，单一模型也可运行。
4.3 运行与守护
配置完成后，即可启动：
# 使用 PM2 启动并守护进程，命名为 guardian-ai pm2 start crypto-scout.js --name guardian-ai # 查看运行日志 pm2 logs guardian-ai # 设置开机自启 pm2 startup pm2 save启动后，在 Telegram 中搜索你的机器人并发送/start，你应该能收到欢迎信息。
4.4 首次使用与功能验证
- 测试链接检测：发送一个已知的钓鱼测试链接（如
http://binance.airdrop-claim-fake.com），查看机器人是否能准确识别并告警。 - 测试合约分析：发送一个主流代币的合约地址（如 BSC 上的 CAKE 合约：
0x0e09fabb73bd3ade0a17ecc321fd13a19e81ce82），查看返回的安全评分和详细信息是否合理。 - 测试安全课程：点击或发送
/lesson，开始第一天的学习。 - （专业模式）测试账户连接：在专业模式下，发送
/account，机器人应能返回你的 Binance 账户资产概况（仅显示，无操作按钮）。
5. 常见问题排查与维护技巧
即使设计再完善，在实际运行中也会遇到各种问题。以下是我们从部署和用户反馈中总结的“排错手册”。
5.1 机器人无响应或命令失效
| 现象 | 可能原因 | 排查步骤 |
|---|---|---|
发送/start无反应 | 1. Bot Token 配置错误 2. 服务器网络无法访问 Telegram API 3. PM2 进程已停止 | 1.pm2 status检查进程是否运行。2. pm2 logs guardian-ai查看日志，常见错误是Invalid token。3. 在服务器上 curl https://api.telegram.org测试网络连通性。 |
| 部分按钮点击无效 | 1. 回调查询超时 2. 消息格式更新冲突 | 1. 检查代码中处理callback_query的部分，确保所有异步操作都有await，且设置了answerCallbackQuery响应。2. 如果修改了按钮的 callback_data结构，需要确保处理逻辑同步更新，旧的客户端消息可能缓存了旧数据。 |
5.2 API 调用频繁失败或限流
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
Binance API 返回429(太多请求) | 请求频率超限 | 1. 在代码中为所有 Binance API 调用添加延迟，例如使用setTimeout或sleep函数，确保每秒请求数低于限制。2. 充分利用缓存，对不常变的数据（如合约验证信息）缓存更长时间。 |
区块链浏览器 API 返回403 | IP 被临时封锁（免费 API 常见） | 1. 实现请求重试机制（如指数退避）。 2. 考虑使用付费的 RPC 服务（如 Infura, Alchemy）作为备用数据源，它们通常有更高的速率限制和稳定性。 |
| AI 模型 API 超时或返回空 | 网络波动或模型服务不稳定 | 1. 增加请求超时时间（如从 10s 增加到 30s）。 2. 实现降级策略：当主模型（Claude）失败时，自动尝试备用模型（Gemini），或返回一个友好的“服务暂时不可用，请稍后再试”提示。 |
5.3 安全评分不准或分析逻辑有误
- 问题：某个明显是骗局的合约，评分却偏高。
- 排查：
- 检查该合约在区块链浏览器上的数据是否“伪装”得很好（例如，交易数被刷得很高，持币地址通过空投分散）。
- 审查
scoring.js中四个维度的权重和计分规则。对于新型骗局，可能需要加入新的检查维度，例如“合约创建后短时间内添加流动性并移除”的“拉地毯”模式检测。 - 查看 AI 模型收到的提示词（Prompt）是否足够清晰，能引导它关注持币集中度、创建者历史等关键风险点。可能需要优化提示词工程。
- 根本解决：安全攻防是动态的。需要建立一个机制，定期从社区、安全机构收集最新的诈骗模式特征，并更新到检测规则和风险数据库中。
5.4 服务器资源占用过高
- 现象：运行一段时间后，内存占用持续增长（超过 100MB），或 CPU 使用率飙升。
- 排查与优化：
- 内存泄漏：使用
node --inspect配合 Chrome DevTools 或clinic.js等工具进行内存堆快照分析。常见泄漏点：未清理的全局缓存、未关闭的数据库连接、事件监听器未移除。 - 缓存膨胀：检查本地缓存文件（如
./cache/目录）是否无限增长。实现缓存淘汰策略（LRU）或定期清理。 - 同步阻塞操作：避免在 Bot 的消息回调中进行复杂的同步计算或大量同步文件读写。应将耗时任务（如深度合约分析）放入队列异步处理。
- 日志文件：PM2 和应用的日志文件可能变大。配置
pm2的日志轮转：pm2 install pm2-logrotate并配置。
- 内存泄漏：使用
5.5 维护与升级建议
- 定期更新依赖：每月运行
npm audit检查安全漏洞，并谨慎升级package.json中的依赖，特别是 Telegram Bot API 和 Binance API 客户端库。 - 备份配置文件：
config.json是核心，务必定期备份。可以考虑使用环境变量（如dotenv）管理部分敏感配置，进一步提升安全性。 - 监控与告警：除了 PM2 自带的监控，可以简单配置一个
cron定时任务，每隔一小时检查一次 Bot 进程是否存活，如果挂了就重启并发送通知到你的 TelegramchatId。 - 关注 API 变更：Binance 和区块链浏览器的 API 可能会更新。关注其官方文档，及时调整代码中的接口调用。
这个项目的核心价值不在于用了多炫酷的技术，而在于它切实地解决了一个痛点——用 AI 和自动化工具，为最需要保护的普通投资者筑起一道易懂、易用的第一道防线。在开发过程中，我们最大的体会是：安全产品，自己必须是第一个用户。我们用自己的测试钱包尝试了各种可疑链接和合约，不断调整风险模型和提示词，才让这个“守护神”的判断越来越接近一个谨慎的老手。希望这份详细的拆解，能帮助你不仅部署它，更能理解其背后的设计逻辑，甚至在此基础上，为你的家人和朋友定制更贴心的安全功能。
