1. 项目概述ClawOn一个跨平台的OpenClaw网关客户端如果你和我一样在多个设备上使用过不同的AI助手或者管理过不止一个自部署的AI网关那你一定体会过那种来回切换、配置繁琐的痛苦。桌面端一个客户端手机端又是另一个App浏览器里还得开个标签页聊天记录和配置还互不打通。这种割裂的体验让我一直想找一个能“一统江湖”的解决方案。直到我遇到了OpenClaw这个项目它提供了一个统一的AI网关接口但官方并没有一个全平台、体验一致的客户端。于是ClawOn这个想法就诞生了。ClawOn是一个用Flutter构建的、完全开源的跨平台客户端它的核心目标只有一个让你用一个应用就能连接和管理你所有的OpenClaw网关无论你用的是安卓手机、iPhone、Mac、Windows电脑、Linux桌面还是直接在浏览器里。它不是一个独立的AI模型而是一个功能强大的“遥控器”让你能方便地与部署在OpenClaw网关背后的各种AI智能体进行交互。无论是聊天、管理技能还是创建自定义的智能体所有操作都能在一个统一的界面里完成。对于开发者、AI爱好者或者任何需要集中管理多个AI服务端点的用户来说这无疑能极大地提升效率和体验。2. 核心功能深度解析与设计思路2.1 多网关管理从分散到集中OpenClaw网关可能部署在不同的服务器、不同的网络环境下比如一台在公司的内网服务器用于工作流自动化另一台在家里的NAS上用于个人助理。ClawOn最基础也最核心的功能就是将这些分散的端点集中管理。在技术实现上这不仅仅是保存一个URL列表那么简单。每个连接Connection在ClawOn内部都是一个独立的状态单元包含了网关的WebSocket地址如wss://gateway.yourdomain.com:18789和对应的身份验证令牌Token。应用使用web_socket_channel包为每个活跃的连接维持一个独立的WebSocket链接用于实时通信。而ConnectionStore基于MobX则负责管理这个链接的生命周期连接、断开、重连以及状态连接中、已连接、错误的响应式更新。实操心得连接稳定性处理在实际网络环境中WebSocket连接并不总是稳定的。ClawOn需要处理网络波动、服务器重启等场景。我的做法是在ConnectionStore中实现指数退避的重连逻辑。当连接意外断开时不会立即疯狂重试而是等待一个短暂时间如1秒后尝试第一次重连如果失败则等待时间逐渐加倍2秒、4秒...直到达到一个上限如30秒。这既能避免在服务器短暂故障时对客户端和服务器造成压力也能在连接恢复后尽快重新建立会话。这个逻辑是写在业务逻辑层对UI层完全透明用户只会看到连接状态的平滑切换。2.2 实时聊天与会话管理打造流畅的对话体验与AI对话的核心是聊天界面。ClawOn的聊天功能支持流式响应这意味着AI返回的文本是逐字或逐词“流”到界面上的就像真人在打字一样而不是等待整个响应生成完毕再一次性显示。这极大地提升了交互的实时感和自然度。技术层面当用户发送一条消息后ChatStore会通过当前活跃的WebSocket连接将消息发送给网关。网关开始流式返回响应数据。Flutter端通过监听WebSocket的Stream将收到的每一个数据块通常是JSON格式包含文本片段实时更新到ChatStore中的一个响应消息对象上。由于ChatStore是MobX observable的绑定到该消息的UI Widget比如一个Text组件会自动重建渲染出最新的文本内容。这里用到了flutter_markdown包来渲染AI返回的、可能包含Markdown格式的响应使代码块、列表、加粗等格式能正确显示。会话Session管理则是基于本地数据库Drift/SQLite实现的。每个会话对应一个与特定智能体Agent的对话线程包含了所有的往来消息。用户可以创建新会话、为会话命名、浏览历史会话列表并且即使在没有网络连接的情况下也能查看以往的对话记录。这种离线能力是通过Drift将所有的消息和会话数据持久化在本地设备上实现的。2.3 技能与智能体系统赋予AI可扩展的能力OpenClaw网关的强大之处在于其“技能”Skills系统。你可以把技能理解为AI可以调用的工具或函数。比如一个“天气查询”技能AI在对话中可以根据你的问题调用这个技能去获取实时天气数据。ClawOn的“技能管理”界面允许你浏览网关提供的所有可用技能并针对每个连接、每个智能体独立地启用或禁用这些技能。这意味着你可以为“编程助手”智能体开启“代码执行”技能而为“客服机器人”智能体关闭它实现精细化的权限和能力控制。而“智能体”Agent则是技能、系统指令Prompt和基础参数的集合体它定义了AI的行为模式。ClawOn允许你创建自定义智能体。在“创建智能体”界面你可以设定它的名称、描述、系统指令例如“你是一个专业的翻译助手只回答与语言翻译相关的问题”并从已启用的技能列表中勾选它可用的技能。创建完成后这个自定义智能体就会出现在新建会话的智能体选择列表中。其背后的数据流是创建智能体的配置信息通过WebSocket发送给OpenClaw网关进行保存而ClawOn本地数据库也会保存一份元数据如名称、ID用于快速显示和选择。2.4 国际化与多平台适配细节决定成败一个目标是服务全球用户的全平台应用国际化i18n和真正的跨平台适配是绕不开的挑战。ClawOn支持多达25种语言包括从左到右LTR和从右到左RTL的布局如阿拉伯语、波斯语。这不仅仅是文本翻译还涉及到UI布局的镜像翻转。我使用Flutter官方推荐的intl包和flutter_localizations来实现国际化。所有的UI字符串都被提取到ARBApplication Resource Bundle文件中进行管理。LanguageStore负责管理当前应用语言的状态并在用户切换语言时通知整个应用重建UI。对于RTL语言Flutter会自动处理文本方向和部分布局但对于一些自定义的图标位置或不对称的间距则需要手动在代码中根据Directionality进行检查和适配。真正的“一次编写处处运行”在Flutter中也不是魔法。虽然大部分UI代码是共享的但平台特定的差异仍需处理。例如导航栏样式在iOS上我们期望页面返回按钮在左上角并带有平滑的滑动返回手势在Android上则可能有物理返回键或手势边缘返回。go_router包提供了声明式的路由管理与平台导航习惯结合得较好。本地存储路径Drift数据库文件、shared_preferences的存储位置在不同操作系统上完全不同。幸运的是Drift和shared_preferences这些插件已经帮我们封装好了平台差异我们只需调用统一的API。Web特定问题这是最特殊的一环。Drift在Web上运行需要SQLite的WebAssemblyWASM版本。项目中将sqlite3.wasm和编译好的Web Worker脚本 (drift_worker.dart.js) 直接放在了web/目录下并提交到代码库这样在构建Web版本时可以直接使用避免了复杂的构建后处理流程。3. 技术架构与关键实现细节3.1 清晰架构Clean Architecture在Flutter中的实践为了确保代码的可维护性、可测试性和可扩展性ClawOn采用了Clean Architecture干净架构的思想来组织项目结构。虽然这不是一个教科书级别的严格分层但核心思想是将代码按职责清晰分离。lib/ ├── core/ # 核心层 - 共享工具、常量、扩展函数、全局异常处理 ├── data/ # 数据层 - 数据来源的具体实现 │ ├── datasources/ # 本地数据源Drift、远程数据源WebSocket API │ ├── models/ # 数据模型与API/DB对应的DTO │ ├── repositories/ # 仓库实现协调多个数据源 │ └── services/ # 具体的业务服务 ├── domain/ # 领域层 - 业务核心 │ ├── entities/ # 业务实体纯Dart类无外部依赖 │ ├── repositories/ # 仓库接口抽象定义供上层依赖 │ └── usecases/ # 用例具体的业务逻辑单元 └── presentation/ # 表现层 - Flutter UI相关 ├── stores/ # MobX Store状态管理 ├── screens/ # 全屏页面 ├── widgets/ # 可复用UI组件 └── routing/ # 路由配置领域层domain是核心它包含纯粹的商业逻辑实体如Connection,Agent,Message和抽象接口如IConnectionRepository。这一层完全不依赖Flutter框架或任何第三方数据包。数据层data负责实现领域层定义的接口。例如ConnectionRepositoryImpl会具体实现如何通过WebSocket建立连接、如何通过Drift将连接配置保存到本地数据库。表现层presentation包含所有的UI组件和状态管理。这里使用MobX Store来持有可观察的状态Observables并定义修改状态的Action。UI Widget通过Observer包裹自动响应状态变化。依赖方向是内向的表现层依赖领域层数据层也依赖领域层。领域层是独立的。这通常通过依赖注入使用get_it包来实现在应用启动时将IConnectionRepository接口的具体实现ConnectionRepositoryImpl注册到容器中然后在Store或页面中获取它。这种结构的好处是当我们需要更换数据源比如从WebSocket换成REST API或者修改UI框架时影响范围可以被控制在局部核心业务逻辑不需要改动。3.2 状态管理为什么选择MobXFlutter的状态管理方案众多如Provider、Riverpod、Bloc等。我选择MobX主要是看中了它的“响应式”特性和极低的样板代码。在MobX中你只需要用observable装饰器标记你的状态变量用action装饰器标记修改这些状态的方法然后用computed装饰器标记派生状态。在UI中用Observerwidget包裹需要响应状态变化的部分即可。当observable变量发生变化时所有依赖它的computed值和Observerwidget都会自动、高效地更新。例如在ChatStore中part chat_store.g.dart; // 这是自动生成的代码 class ChatStore _ChatStore with _$ChatStore; abstract class _ChatStore with Store { observable ListMessage messages []; observable bool isSending false; action Futurevoid sendMessage(String text) async { isSending true; try { // ... 发送逻辑 final newMessage Message(...); messages [...messages, newMessage]; // 触发UI更新 } finally { isSending false; // 触发UI更新 } } computed bool get hasMessages messages.isNotEmpty; }代码非常直观几乎就是在写普通的Dart类然后通过注解声明其响应式行为。通过build_runner工具运行代码生成命令后会自动生成_$ChatStore这个Mixin里面包含了所有响应式更新的底层逻辑。这比一些基于事件流Stream的方案写起来更简洁心智负担更小。3.3 数据持久化Drift原Moor的使用与Web适配本地数据存储选择了Drift原名Moor它是一个功能强大且类型安全的SQLite ORM库。它允许我们使用Dart代码来定义数据表并通过编译时生成类型安全的查询代码极大地减少了手写SQL字符串的错误。定义一个消息表可能像这样DataClassName(MessageDb) class Messages extends Table { IntColumn get id integer().autoIncrement()(); TextColumn get sessionId text()(); TextColumn get content text()(); DateTimeColumn get timestamp dateTime()(); // ... 其他字段 }然后Drift会帮我们生成对应的MessageDb类以及相关的插入、查询方法。在移动端和桌面端Drift直接使用平台的本地SQLite库。但在Web端由于浏览器环境限制它需要依靠WebAssembly版本的SQLite (sqlite3.wasm) 和一个运行在Web Worker中的Dart脚本来操作数据库以避免阻塞UI线程。这就是为什么项目web/目录下会包含那两个预编译的资产文件。当sqlite3包升级时需要按照项目README中的步骤重新下载匹配版本的.wasm文件并重新编译Worker脚本这是一个关键的部署步骤。3.4 构建与部署全平台CI/CD流水线对于一个支持6个平台的应用手动为每个平台打包发布是不可想象的。ClawOn利用GitHub Actions实现了自动化的持续集成和部署CI/CD。在.github/workflows/目录下主要定义了两种工作流CI工作流 (ci.yml)在每次提交或拉取请求时触发。它会运行代码格式检查 (dart format --set-exit-if-changed)、静态分析 (flutter analyze)、以及所有单元测试和Widget测试 (flutter test)。这确保了代码库的质量。构建工作流 (build.yml)通常在对主分支main进行推送或者发布新版本标签如v1.0.2时触发。这个工作流复杂得多它会在一个矩阵策略中为每个目标平台android, ios, macos, windows, linux, web分别运行构建任务。以Android构建为例工作流会检查Flutter环境。获取项目依赖。运行flutter build apk --release或flutter build appbundle --release。将生成的APK或AAB文件作为构建产物上传方便下载。如果配置了还可以自动将APK发布到Google Play的内部测试轨道这需要额外的服务账号和密钥配置。对于iOS和macOS的构建需要在GitHub Runner的macOS环境中进行并且需要配置苹果开发者证书和描述文件这些敏感信息通过GitHub Secrets注入。Web构建则相对简单最终生成静态文件可以部署到任何静态网站托管服务。4. 开发指南与实战踩坑记录4.1 环境搭建与初次运行要开始贡献代码或自行构建你需要准备好Flutter开发环境。确保Flutter SDK版本在3.0.6或以上可通过flutter --version检查。克隆项目后第一步是获取依赖flutter pub get接下来由于项目使用了MobX和Drift它们都需要通过代码生成来创建.g.dart文件所以必须运行flutter packages pub run build_runner build --delete-conflicting-outputs--delete-conflicting-outputs参数很重要它会自动清理之前生成的可能有冲突的旧文件。常见问题代码生成失败如果这一步报错最常见的原因是现有生成的.g.dart文件与当前代码不同步或者有残留的冲突。除了使用--delete-conflicting-outputs还可以尝试更彻底的方法手动删除lib/目录下所有的.g.dart文件。运行flutter clean清理构建缓存。再次运行flutter pub get和build_runner build。 如果问题依旧检查pubspec.yaml中build_runner的版本是否与其他代码生成包如mobx_codegen,drift_dev兼容。锁定在某个已知可用的版本组合通常是稳妥的做法。环境就绪后连接一台设备或启动模拟器运行flutter run即可启动调试版本的应用。4.2 核心功能开发流程示例添加一个新设置项假设我们需要在应用中增加一个“深色模式/浅色模式”的切换开关。这是一个很好的例子因为它涉及UI、状态管理和本地持久化。定义领域实体与仓库接口可选如果主题设置是一个重要的业务概念可以在domain/entities/下创建AppTheme枚举如light,dark,system。在domain/repositories/下创建ISettingsRepository接口定义saveTheme和getTheme方法。实现数据层在data/repositories/下创建SettingsRepositoryImpl实现ISettingsRepository。我们可以使用shared_preferences包来持久化主题设置。在saveTheme方法中将枚举值转换为字符串存入SharedPreferences在getTheme中读取并转换回来。创建状态管理Store在presentation/stores/下创建SettingsStore。它需要依赖ISettingsRepository通过get_it注入并包含一个observable AppTheme currentTheme状态以及一个action Futurevoid switchTheme(AppTheme theme)方法。这个方法会调用仓库保存设置并更新currentTheme。在UI中使用在应用的根Widget或一个设置页面中使用Observer包裹需要根据主题变化的部分比如整个MaterialApp的theme属性。提供一个开关控件其onChanged回调调用settingsStore.switchTheme(newValue)。依赖注入在应用启动时通常在main.dart的main函数中使用get_it注册ISettingsRepository和SettingsStore的单例实例。这个过程清晰地遵循了从领域逻辑到数据持久化再到UI表现的路径保持了代码的清晰和可测试性。4.3 Web平台特有的构建与调试问题开发Web版本与移动端有些许不同。使用flutter run -d chrome可以启动一个本地开发服务器并在Chrome中调试。但需要注意热重载/热重启在Web上热重载Hot Reload有时可能不如在移动端稳定特别是涉及状态管理或路由时。遇到UI不更新时尝试完全热重启Hot Restart。CORS问题如果你的OpenClaw网关运行在另一个域名或端口下浏览器会因为同源策略CORS阻止WebSocket连接。你需要在OpenClaw网关服务器端配置正确的CORS头部允许你的ClawOn Web应用所在域名进行连接。这是一个后端配置问题而非Flutter代码问题。发布构建运行flutter build web后产物在build/web目录下。你可以将这些文件部署到任何静态托管服务如GitHub Pages, Vercel, Netlify等。记得配置托管服务的单页应用SPA回退路由因为Flutter Web使用哈希路由#/或路径路由需要将所有非静态文件请求重定向到index.html。4.4 性能优化与内存管理随着聊天记录增多本地数据库可能会变得庞大。虽然SQLite和Drift能处理大量数据但在UI中一次性加载成千上万条消息显然是不明智的。分页加载在会话列表和聊天消息列表中实现分页。例如首次只加载最近的50条消息当用户滚动到列表顶部时再加载更早的50条。Drift的查询语句天然支持limit和offset可以很方便地实现。图片/文件缓存如果AI返回的消息中包含图片链接考虑使用cached_network_image这类包来缓存图片避免重复下载。WebSocket连接管理当应用切换到后台或长时间不活跃时可以考虑主动断开非活跃的WebSocket连接以节省服务器资源和设备电量。当应用回到前台时再自动重连。这可以通过Flutter的WidgetsBindingObserver监听AppLifecycleState来实现。5. 常见问题排查与解决方案速查在实际开发和用户使用中会遇到一些典型问题。这里我整理了一份速查表涵盖了从连接到构建的常见坑点。问题现象可能原因排查步骤与解决方案无法连接到网关1. 网关地址或协议错误。2. 身份验证令牌无效或过期。3. 网络防火墙或CORSWeb端阻止。1.检查地址确认URL完整例如wss://your.server.com:18789。注意是wssWebSocket Secure而非https。本地测试可能是ws://127.0.0.1:18789。2.检查令牌在OpenClaw网关管理界面重新生成令牌并粘贴。确保令牌没有空格。3.网络诊断尝试在浏览器中访问网关的HTTP API端点如果开放或使用curl或 WebSocket测试工具连接。对于Web版检查浏览器控制台F12的CORS错误并在网关服务器配置中允许你的Web应用域名。应用启动后白屏/崩溃1. 代码生成文件缺失或冲突。2. 依赖包版本冲突或损坏。3. 平台特定配置错误如iOS签名。1.运行代码生成执行flutter packages pub run build_runner build --delete-conflicting-outputs。2.清理并重装依赖依次运行flutter clean,rm -rf pubspec.lock .packages .dart_tool, 然后flutter pub get。3.检查平台配置iOS需检查ios/Runner.xcworkspace中的签名和证书Android检查android/app/build.gradle中的minSdkVersion等是否与依赖包要求匹配。Web版无法加载或数据库错误1.sqlite3.wasm或drift_worker.dart.js文件缺失或版本不匹配。2. Web服务器未正确配置SPA回退。1.检查Web资产确认web/目录下存在这两个文件。如果刚升级了sqlite3包需按README步骤重新下载和编译。2.检查部署配置如果你自行部署确保服务器将所有非静态文件请求重定向到index.html例如在Vercel或Netlify中配置_redirects或vercel.json。聊天消息不更新或UI卡顿1. MobX的Observer未正确包裹。2. 在action外部修改了observable变量。3. 进行了大量同步计算阻塞UI线程。1.检查Widget树确保需要响应的Widget被Observer()包裹。2.遵守MobX规则所有对observable变量的修改都应在action方法内进行。可以使用runInAction(() { ... })包裹异步回调中的状态修改。3.性能分析使用Flutter DevTools的Performance视图检查是否有耗时操作在UI线程执行考虑使用compute将其移到隔离Isolate中。构建Release版本失败1. 图标或启动图资源格式/尺寸问题。2. 混淆或缩减配置错误Android。3. 缺少发布证书或描述文件iOS。1.检查资源根据Flutter文档确保android/app/src/main/res/和ios/Runner/Assets.xcassets/下的图标和启动图符合各平台要求。2.检查Android混淆在android/app/build.gradle中检查minifyEnabled和shrinkResources是否为true并确认proguard-rules.pro文件包含了所有必要依赖的保留规则。3.配置iOS发布使用Xcode打开ios/Runner.xcworkspace在“Signing Capabilities”中为Release模式选择正确的团队和发布Production配置文件。开发这样一款全平台应用就像是在同时指挥多个乐团演奏同一首交响乐。每个平台乐器都有自己的特性和限制而Flutter框架乐谱提供了统一的旋律。ClawOn项目的价值不仅在于它实现了一个好用的OpenClaw客户端更在于它提供了一个用Flutter构建复杂、生产级、全平台应用的完整实践样板。从清晰的分层架构、响应式状态管理到Web平台的WASM适配、自动化的多平台CI/CD每一个环节都充满了值得深入思考和借鉴的技术细节。如果你正打算用Flutter挑战一个类似的全平台项目希望这篇分享和这个开源项目能给你带来一些实实在在的帮助。