1. 项目概述一个为AI Agent量身定制的排行榜如果你和我一样深度使用过OpenClaw或者正在开发自己的AI Agent那你肯定遇到过一个问题我怎么知道我的Agent在真实用户场景下到底表现如何是昙花一现还是稳定可靠市面上有各种大模型的基准测试但对于我们这些具体到某个应用、某个工作流的Agent来说那些宏观的排行榜意义不大。我们需要的是一个能反映“实战”表现的榜单能看到Agent在日复一日的真实交互中谁被用得最多谁最受用户信赖。这就是ClawRank诞生的初衷。它不是一个简单的计数工具而是一个“Agent优先”的排行榜系统核心数据源直接来自OpenClaw的会话记录。简单来说它把OpenClaw里每个Agent的每一次被调用、每一次成功完成任务都转化成一个可度量、可比较的“事实”然后按天、按周、按月、按总时长进行排名。你可以把它想象成AI Agent领域的“App Store排行榜”但数据更实时、更贴近开发者和用户的真实需求。这个项目特别适合几类人一是OpenClaw的重度用户想看看社区里哪些Agent真正好用二是AI Agent的开发者需要一个客观的指标来验证自己产品的受欢迎程度和稳定性三是任何对AI应用生态感兴趣想从数据层面理解Agent发展趋势的人。接下来我会带你深入这个项目的架构、实现细节以及我在搭建过程中踩过的坑和总结的经验。2. 架构设计与核心思路拆解2.1 为什么选择“模块化、职责清晰”的架构当我开始设计ClawRank时首要目标是确保系统的可维护性和可扩展性。数据从原始的OpenClaw会话记录最终变成网页上的一个排行榜中间要经过解析、转换、验证、存储、聚合等多个步骤。如果把这些逻辑全部混在一起初期可能开发快但后期加新功能、排查问题会是一场噩梦。因此我采用了严格的模块化边界设计整个数据流水线被清晰地划分为四个层次每个目录只做一件事适配器层src/adapters/openclaw/。它的唯一职责就是读取和解析OpenClaw的原始会话文件。这里不关心数据之后怎么用只保证能正确地把JSON文件里的复杂结构转换成程序里一个结构化的对象。这种设计的好处是如果未来OpenClaw的数据格式变了或者我要接入另一个数据源比如另一个AI平台我只需要修改或新增一个适配器其他部分完全不用动。** ingestion层**src/ingestion/openclaw/。这一层负责“翻译”。它接收适配器层解析好的原始消息然后根据业务规则判断哪些交互算作一次有效的“Agent使用”并将其转化为ClawRank领域内的“每日Agent事实”。比如一次成功的代码生成、一次有效的问答都可能被记为一个事实。这里的逻辑是业务核心决定了排行榜的公平性和准确性。领域层src/domain/。这是业务逻辑的心脏。所有转化来的“事实”在这里进行验证比如时间戳是否合理、Agent标识是否有效、去重然后被持久化。同时排行榜的聚合计算比如按时间周期求和、排序以及查询单个Agent详情的逻辑也都封装在这里。领域层完全不关心数据是存在数据库里还是文件里它只定义操作数据的接口。数据层src/db/。这一层是纯技术实现负责与PostgreSQL数据库对话。它包含连接管理、定义好的SQL查询语句使用TypeScript类型保证安全以及数据库表结构定义。领域层通过调用这里的接口来存、取数据实现了业务逻辑和数据存储的解耦。这种架构带来的最大好处是“可测试性”。我可以单独测试适配器解析是否正确单独测试ingestion层的转换逻辑而不需要启动整个数据库和Web服务。在开发初期这为我节省了大量调试时间。2.2 核心数据模型为什么是“每日Agent事实”在数据模型设计上我放弃了记录每一次原始交互的细节而是选择了“每日Agent事实”作为核心度量模型。一个“事实”通常包含Agent的唯一标识、日期、以及某种度量值比如当日被成功调用的次数。这个设计背后有几个考量降低数据粒度提升查询性能排行榜需要的是聚合后的数据总和、日均等如果直接存储海量的原始交互记录每次排名都要做GROUP BY和SUM对数据库压力很大。预聚合到“日”级别查询时直接对每日事实求和速度极快。平衡数据精度与存储成本对于排行榜来说我们通常不需要知道某次调用具体发生在几点几分知道它发生在哪一天足以支持按日、周、月、年的趋势分析。这大大减少了需要存储和索引的数据量。易于理解和扩展“事实”这个模型很灵活。今天我可以只记录“调用次数”明天我完全可以增加一个新的“事实类型”比如“平均任务耗时”、“用户满意度评分”而无需推翻整个数据架构。只需要在ingestion层增加对新指标的提取逻辑并在领域层增加相应的聚合方式即可。注意选择“每日”作为聚合维度意味着你无法在排行榜上实现“实时分钟级”更新。这对于一个旨在反映长期稳定性和受欢迎程度的榜单来说是合理的取舍。如果你的场景需要实时热度榜可能需要设计另一套流式处理的数据模型。3. 多级数据持久化策略详解一个项目能否顺利跑起来尤其是在开发、测试、演示等多种环境下数据源的稳定性和灵活性至关重要。ClawRank设计了一个三级递进的数据持久化与回退策略这是我自认为非常实用的一点。3.1 生产环境云端PostgreSQL在正式部署的环境比如Vercel中ClawRank使用Neon提供的PostgreSQL数据库。Neon是一个基于云的Postgres服务它和Vercel的集成非常顺畅。你只需要在Vercel的项目设置里从Marketplace添加NeonDATABASE_URL这个环境变量就会被自动注入到你的应用环境中无需手动配置。这是最理想的状态数据持久、可扩展、支持复杂的查询。3.2 本地开发回退平面JSON文件但是不是每个开发者一开始都想或者能搭建一个Postgres数据库。为了降低入门门槛我实现了一个本地文件回退机制。当系统检测到DATABASE_URL环境变量不存在比如在本地开发时没配置它会自动回退到使用项目根目录下的data/clawrank-pilot.json这个平面JSON文件来存储和读取数据。这个文件模拟了数据库表的结构将“每日Agent事实”以JSON数组的形式保存。领域层的代码通过一个统一的“存储仓库”接口来操作数据这个接口背后会根据环境自动选择是用数据库客户端还是用文件读写模块。这意味着你的业务逻辑代码完全不用关心数据到底存在哪里。实操心得实现这个回退机制的关键是设计好存储层的抽象接口。我定义了一个IRepository接口声明了upsertFact、getFactsByAgentAndDateRange等方法。然后分别实现了PostgresRepository和JsonFileRepository。在应用启动时根据环境变量决定实例化哪一个。这样未来如果要加一个Redis缓存层也只需要再实现一个新的Repository类即可。3.3 静态演示数据烘焙的JSON第三层是“烘焙数据”位于data/leaderboard.json和data/agents/*.json。这层数据是静态的在项目构建时就已经生成好。它的主要用途有两个演示和Mock当你想快速展示项目效果或者给前端同事一个固定的API响应格式时可以直接让相关路由读取这些静态文件完全绕过后端逻辑。构建优化对于某些不常变的数据比如历史总榜在构建时生成静态JSON可以直接通过CDN分发减轻服务器动态查询的压力极大提升页面加载速度。回退链的优先级是首先尝试连接数据库DATABASE_URL存在且有效 - 失败或不存在则回退到本地Pilot JSON文件 - 如果连这个文件也没有比如全新的克隆仓库则最终回退到静态烘焙数据确保应用在任何情况下都能“跑起来”虽然可能不是最新数据。4. 核心API接口与OpenGraph图像生成实战4.1 API设计简洁与实用并重ClawRank的API设计遵循RESTful风格但更注重实用性和前端使用的便利性。所有主要端点都支持通过period查询参数来获取不同时间周期的数据。/api/leaderboard?period...这是核心中的核心。它返回一个排序好的Agent列表包含名次、Agent名称、标识、以及选定周期内的总分数如调用次数。period可选alltime总榜、today今日、week本周、month本月。后端处理时会根据period参数计算日期范围然后从存储层查询对应范围内的所有“事实”进行聚合求和、排序。/api/agents/[detailSlug]?period...获取单个Agent的详细数据。除了在当前周期的排名和分数还可以返回其历史趋势数据比如过去30天每日的调用量用于绘制趋势图。detailSlug是Agent的唯一URL友好标识符通常由名称转换而来如my-code-agent。/api/submit与/api/ingest/openclaw这两个是数据输入端点。/api/submit设计为通用提交接口未来可以接收来自其他来源的Agent使用数据。/api/ingest/openclaw则是专门用于接收和处理来自OpenClaw技能或定时任务推送的数据。为了保护这些端点可以通过设置CLAWRANK_INGEST_TOKEN环境变量来启用简单的Bearer Token认证。避坑指南在设计聚合API时要特别注意时间窗口的计算。例如“本周”是指从本周一到周日还是从上周日到本周六这需要和前端显示保持一致。我采用的是从周一开始的ISO周标准。同时对于“今日”榜要考虑服务器时区与用户所在时区可能不同的问题。一个简单的做法是所有时间戳在存储时都统一为UTC时间在查询时根据需求用SQL的时区函数进行转换或者由前端根据用户时区来处理显示。4.2 OpenGraph图像生成让分享更具吸引力在现代社交传播中一个带有丰富信息的链接预览图OpenGraph Image能极大提升点击率。ClawRank为排行榜和每个Agent详情页都动态生成了OG图片。技术选型我选择了vercel/og这个库它基于Satori使用React语法生成SVG和Resvg将SVG转换为PNG在Vercel Serverless环境下运行效率非常高速度快且成本低。设计理念OG图片被设计成“CLI终端优先”的风格。使用等宽字体JetBrains Mono配色采用暖色调的终端主题来自DESIGN.md中的定义让图片看起来像一块优雅的命令行输出这非常符合开发者社区的审美。实现细节排行榜OG/api/og/leaderboard。它接收period参数动态查询该周期的排行榜数据然后生成一个单列列表显示前三名Agent的名字和分数。图片标题会显示周期如“Weekly Leaderboard”。详情页OG/api/og/[detailSlug]。它展示单个Agent的核心数据如当前排名、总分、以及一个简单的趋势火花图。为了确保即使该Agent没有真实数据时也能显示比如用于Mock页面还有一个/api/og/mock/[detailSlug]端点使用烘焙的静态数据生成图片。路由与元标签在前端页面需要根据当前页面在head中正确设置og:image标签。例如首页的og:image指向/api/og/leaderboard?periodalltime而详情页则指向/api/og/${agentSlug}。重要提示OG图片生成是服务器端渲染涉及数据查询和图像渲染可能成为性能瓶颈。务必添加缓存我采用了Vercel Edge Cache通过设置Cache-Control: public, max-age3600, s-maxage3600头部将图片在Vercel的边缘网络上缓存1小时因为排行榜数据通常不会每分钟都剧烈变化。这能减少重复计算显著提升响应速度。5. 从零开始的本地开发与部署指南5.1 环境配置与初始化让我们一步步把ClawRank在本地跑起来。首先确保你已安装Node.js推荐LTS版本和pnpm。# 1. 克隆项目 git clone repository-url cd ClawRank # 2. 安装依赖 pnpm install # 3. 配置环境变量 cp .env.example .env.local接下来是配置.env.local文件这里有几个关键点# 你的本地开发服务器地址 NEXT_PUBLIC_SITE_URLhttp://localhost:3000 # 指向你的OpenClaw会话索引文件路径 # 注意~ 在Node.js环境中可能无法直接解析最好使用绝对路径 # 例如/Users/yourname/.openclaw/agents/main/sessions/sessions.json OPENCLAW_SESSIONS_INDEX/绝对路径/.openclaw/agents/main/sessions/sessions.json # 本地回退数据文件路径 CLAWRANK_PILOT_STORE_PATH./data/clawrank-pilot.json # 可选用于保护数据提交端点的令牌 CLAWRANK_INGEST_TOKENyour_secret_token_here # 本地数据库连接如果不用本地Postgres可留空系统会回退到JSON文件 DATABASE_URLpostgresql://username:passwordlocalhost:5432/clawrank关于OPENCLAW_SESSIONS_INDEX的路径问题项目说明支持~但在实际代码中你需要确保读取文件的逻辑能正确展开用户主目录。一个可靠的做法是在适配器代码中使用os.homedir()来替换~。我在实现时在src/adapters/openclaw/的解析器初始化函数里就加入了这段路径处理逻辑。5.2 数据注入与系统验证配置好环境后第一步是注入初始数据。# 运行试点数据注入脚本 # 这个命令会读取 OPENCLAW_SESSIONS_INDEX 指向的文件解析并转换数据存入 CLAWRANK_PILOT_STORE_PATH 指定的JSON文件。 pnpm pilot:ingest执行成功后检查./data/clawrank-pilot.json文件应该能看到结构化的“事实”数据。如果这一步报错大概率是会话文件路径不对或者格式不符合预期。OpenClaw的会话文件结构可能随着版本更新而变化需要确保适配器层的解析逻辑与之匹配。接下来启动开发服务器pnpm dev现在打开浏览器访问http://localhost:3000你应该能看到排行榜页面。通过页面上的选项卡或直接访问API可以查看不同周期的数据首页 (/)总榜API/api/leaderboard?periodalltime某个Agent的详情API/api/agents/[agentSlug]?periodalltimeagentSlug可以从总榜API的响应中获取5.3 数据库集成与生产部署准备如果你想使用更强大的PostgreSQL数据库而不是本地JSON文件需要以下步骤安装并运行PostgreSQL可以在本地通过Docker快速启动一个。docker run --name clawrank-db -e POSTGRES_PASSWORDyourpassword -p 5432:5432 -d postgres创建数据库docker exec -it clawrank-db psql -U postgres -c CREATE DATABASE clawrank;更新.env.local将DATABASE_URL设置为postgresql://postgres:yourpasswordlocalhost:5432/clawrank。运行数据库迁移和种子脚本项目通常需要创建表结构并导入初始数据。# 首先执行迁移创建表如果项目有迁移脚本例如使用Prisma或Drizzle pnpm db:migrate # 然后将pilot数据导入数据库 pnpm db:seeddb:seed脚本会读取clawrank-pilot.json文件并将其中的数据upsert到数据库对应的表中。完成这些后重启pnpm dev应用现在应该会优先连接并使用PostgreSQL数据库。生产部署以Vercel为例将代码推送到GitHub等Vercel支持的平台。在Vercel控制台导入项目。在项目设置的“Environment Variables”中只需设置NEXT_PUBLIC_SITE_URL为你的生产域名以及可选的CLAWRANK_INGEST_TOKEN。DATABASE_URL不需要手动设置进入“Marketplace”标签页搜索并添加“Neon”。Vercel会自动创建一个Neon数据库并将连接字符串作为DATABASE_URL环境变量注入。部署。在部署日志中确保构建命令如pnpm run build成功并且数据库迁移脚本如果作为构建的一部分正确运行。6. 开发规范、文档与项目治理一个健康的开源项目离不开清晰的规范。ClawRank在项目根目录提供了几个关键的文档AGENTS.md这定义了向ClawRank提交数据的Agent需要遵守的编码和发布规范。例如Agent必须有一个全局唯一的标识符slug发送的数据必须包含时间戳和明确的Agent ID并且鼓励实现自动上报的“技能”。这份文档确保了数据源的质量和一致性。CLAUDE.md这是一个非常实用的文件用于记录面向Agent比如Claude等AI助手的简明实现说明。当我对项目进行一些用户体验的优化比如调整API响应格式、修改错误提示时我会在这里记下要点。这样当我下次让AI助手帮我写相关代码时它就能快速理解上下文和最新约定。docs/branch-naming.md定义了分支命名规范例如feat/前缀用于新功能fix/用于修复bugdocs/用于文档更新。这有助于团队协作和生成清晰的变更日志。经验之谈维护一个CLAUDE.md文件对于重度使用AI编程的开发者来说效率提升巨大。它相当于一个针对当前项目的、持续更新的“上下文备忘录”避免了每次都要向AI重复解释项目结构和技术选型。7. 已知局限与未来演进方向ClawRank目前是一个功能完整但目标明确的最小可行产品。在项目初期我刻意划定了范围以集中精力解决核心问题单一数据源目前仅支持OpenClaw。未来可以设计一个通用的Ingestion Adapter接口让接入其他平台如LangChain、AutoGen的数据变得容易。基础防滥用提交端点虽然有Token保护但缺乏更精细的速率限制、数据验证和欺诈检测。这对于一个公开的排行榜来说是必要的下一步。完整的认证/认领流程目前Agent数据是自动收集或提交的。未来应该允许Agent的开发者“认领”自己的条目并管理其展示信息如描述、图标、官网链接甚至隐藏或删除不准确的数据。社交分享深化目前只有OG图片。可以集成分享到Twitter、Reddit等平台的卡片优化并添加“复制分享链接”等一键操作。接下来的直接步骤实现持续数据流编写一个OpenClaw技能或设置一个Cron Job定期例如每小时将新的会话事实通过/api/submit端点推送到已部署的ClawRank服务器上实现排行榜的自动、近实时更新。构建认领流程设计一个简单的Web界面让开发者通过GitHub OAuth等方式登录搜索并认领自己的Agent随后可以编辑其公开信息。这个项目的魅力在于它从一个非常具体的需求OpenClaw用户想知道哪个Agent好用出发构建了一个可扩展的度量系统。无论你是想直接使用它还是借鉴其架构思路来构建自己的数据排行榜希望这篇详细的拆解能给你带来实实在在的帮助。在实际搭建过程中最深的体会是清晰的模块边界和渐进式的数据回退策略是让项目快速迭代且保持开发者友好性的关键。如果你在复现过程中遇到任何问题或者有新的想法非常欢迎一起探讨。