1. 项目概述ClawFace Gateway一个为AI开发者打造的macOS系统监控利器如果你和我一样是个重度依赖本地AI工具比如Claude Code、OpenAI Codex CLI进行开发的macOS用户那你肯定也经历过这些时刻一边跑着模型训练或代码生成一边焦虑地想知道CPU是不是快烧了、内存还剩多少、以及今天这波操作又“烧”了多少钱。传统的活动监视器只能看系统状态而AI工具的账单又往往滞后且分散。ClawFace Gateway的出现完美地解决了这个痛点。它是一款原生macOS菜单栏应用核心功能就两个实时监控你的Mac系统健康状态并精准追踪你在各种AI模型上的花费。更妙的是它能和配套的iPhone应用配对让你随时随地远程查看这些数据堪称AI开发者的“仪表盘”和“记账本”。这个项目本质上是一个精巧的本地监控代理。它安静地驻留在你的菜单栏通过一系列收集器Collector抓取系统指标CPU、内存、磁盘、温度、网络同时像侦探一样扫描你本地AI工具目前支持Claude Code和OpenAI Codex CLI生成的日志文件解析出每一次调用的token消耗再乘以内置的、实时更新的各模型单价计算出实时成本。所有这些数据都被聚合起来一方面通过一个简洁的彩色下拉面板展示另一方面可以通过WebSocket连接到一个中继服务器最终推送到你的iPhone上。整个过程中你的所有敏感数据——从系统信息到AI使用记录——都只留在你的本地Mac上中继服务器只负责转发加密的消息流不做任何存储隐私性设计得很到位。2. 核心功能与架构深度解析2.1 功能模块拆解不止是“监控”更是“洞察”ClawFace Gateway的功能可以清晰地分为四大模块每个模块都针对开发者的实际痛点设计。系统指标监控模块这不仅仅是简单读取top或vm_stat命令的输出。为了提供更流畅、更准确的体验它很可能通过Node.js的os模块、systeminformation这样的第三方库或者直接调用macOS的底层API如IOKit来获取数据。CPU使用率会被区分为用户态、系统态、空闲和Nice值并以动态彩条和百分比显示内存监控会清晰区分已用、缓存、活动、非活动内存让你知道是应用真占用了内存还是系统在高效利用缓存磁盘I/O和网络上行/下行速度的实时图表能帮你立刻定位到是哪个进程在疯狂读写或上传下载。温度传感器的读数对于Apple Silicon机型尤其重要能让你在风扇狂转之前就有所警觉。AI成本追踪模块这是项目的精髓所在。它没有采用侵入式的钩子Hook或代理Proxy方式而是采用了更优雅、更安全的日志分析模式。以Claude Code为例它会持续监控~/.anthropic/code/logs/目录下的JSONLJSON Lines格式日志文件。每当有新的一行日志写入对应一次AI调用claudeLogScanner.ts就会立即解析提取出input_tokens、output_tokens、model等关键字段。然后aiUsageTracker.ts会查阅一个内置的、可更新的价格表例如Claude 3.5 Sonnet: $3输入/$15输出每百万token完成本次调用的成本计算并累加到对应提供商和模型的总计中。所有历史记录都会存入本地的SQLite数据库~/.openclaw/usage.db方便你查看日、周、月的消费趋势而不仅仅是实时快照。OpenClaw状态监控模块从关键词openclaw-monitor可以看出该项目与OpenClaw生态深度集成。它不仅能监控基础的AI调用成本还能展示OpenClaw Agent的运行状态、活跃的通信通道Channels、会话Sessions数量、上下文使用量以及详细的token计数。这对于使用OpenClaw框架构建复杂AI代理系统的开发者来说相当于一个集成的控制面板可以一眼看清整个AI代理集群的健康状况和资源消耗。设备配对与远程中继模块这是实现“远程监控”的魔法所在。本地菜单栏应用desktop/启动后pairManager.ts会生成一个唯一的配对码如CLAW-1234和一个对应的QR码。iPhone上的ClawFace应用通过输入代码或扫描二维码与中继服务器建立安全的WebSocket连接。同时Mac端的relayClient.ts也会以相同的配对码为凭证连接到同一个中继服务器。这个中继服务器就像一个加密的“消息交换机”只负责将Mac端推送过来的数据包原样转发给iPhone端反之亦然。它不解析、不存储任何数据内容确保了端到端的隐私安全。这种设计比直接的P2P连接更可靠能更好地处理NAT穿透和移动网络环境下的连接稳定性问题。2.2 技术架构现代桌面应用与监控服务的优雅结合从项目结构看这是一个典型的Monorepo单体仓库项目使用npm workspaces管理三个子包体现了清晰的关注点分离Separation of Concerns思想。shared/存放共享的TypeScript类型定义types.ts。这是保证desktopElectron渲染进程和gatewayNode.js监控引擎之间数据通信一致性的基石。例如系统指标SystemMetrics、AI使用记录AIUsageRecord、配对消息PairingMessage等接口都在这里定义。任何一端的修改都会立即在另一端反映出来避免了隐式的契约破坏。gateway/这是监控的“大脑”或“引擎”。它是一个纯Node.js服务不涉及任何UI。index.tsOpenClawMonitor作为总指挥它初始化并协调所有收集器systemCollector,aiUsageTracker管理定时轮询或文件监听事件并负责通过relayClient向外推送数据。各个*Scanner.ts文件采用观察者模式Observer Pattern或事件发射器EventEmitter。它们监听特定目录的文件变化使用fs.watch或更高效的chokidar库一旦有新的日志行追加就触发解析事件。解析器需要处理日志滚存log rotation、部分写入partial write等边缘情况确保数据不丢失。aiUsageTracker.ts除了成本计算它还负责SQLite数据库的CRUD操作。数据库模式Schema设计需要考虑效率比如为provider、model、timestamp字段建立索引以加速按时间范围或模型类型的聚合查询。desktop/这是用户直接交互的“面孔”一个基于Electron的macOS菜单栏应用。main/主进程负责创建系统托盘图标Tray、上下文菜单、以及那个精致的下拉面板窗口。它通过进程间通信IPC与gateway引擎对话获取最新数据并转发给渲染进程。同时它也处理生成配对码、显示二维码等系统级任务。renderer/渲染进程用HTML/CSS/JS构建下拉面板的UI。这里会用到大量的数据绑定和动态更新例如使用Vue.js或React的轻量级方案来响应式地更新CPU进度条、成本数字等。UI设计的关键是信息密度和可读性在狭小的下拉窗口内清晰地展示大量数据。它们如何协同工作Electron主进程启动时会以子进程child_process或通过本地Socket的方式启动gateway监控引擎。引擎不断收集数据并通过IPC或自定义事件通知主进程。主进程将数据转发给渲染进程进行展示。当用户点击配对按钮时主进程调用pairManager生成代码渲染进程将其渲染为二维码。整个数据流是单向且解耦的非常清晰。注意关于Electron与原生体验的权衡。使用Electron开发菜单栏应用优势是跨平台理论上和Web技术栈的开发效率。但劣势是内存占用会比纯原生应用如用Swift开发高一些。ClawFace Gateway选择Electron推测是为了快速迭代、复用前端技术栈以及与可能存在的Web管理端保持技术统一。对于这种常驻后台、UI相对简单的工具只要优化得当如禁用不必要的Chromium功能、惰性加载Electron的体积和性能开销是可以接受的。3. 从零开始编译、运行与深度定制指南3.1 环境准备与源码编译虽然直接下载DMG安装是最快的方式但如果你想学习其实现、进行二次开发或为开源社区贡献代码从源码构建是必经之路。第一步搭建开发环境确保你的Mac满足以下条件操作系统macOS 13 (Ventura) 或更高版本。某些底层系统API或Electron版本可能依赖较新的macOS特性。芯片架构Apple Silicon (arm64)。项目可能使用了针对ARM架构优化的原生模块native addons在Intel Mac上编译可能会遇到问题。Node.js与npm需要Node.js 18或更高版本。建议使用nvmNode Version Manager来管理Node版本避免全局污染。# 使用nvm安装并切换至LTS版本 nvm install --lts nvm use --lts # 验证版本 node --version # 应 v18.0.0 npm --version第二步克隆与依赖安装# 克隆仓库到本地 git clone https://github.com/OrrisTech/clawface.git cd clawface # 安装所有工作区的依赖root, shared, gateway, desktop # 这利用了npm workspaces的特性会递归安装各个子目录的node_modules npm install这个过程可能会花费几分钟因为它需要下载Electron及其相关依赖Chromium等体积较大。第三步构建与运行项目采用了先构建build后运行的模式gateway部分很可能是用TypeScript写的需要编译成JavaScript。# 1. 构建gateway监控引擎TypeScript编译 cd gateway npm run build # 这通常会在gateway目录下生成一个dist或lib文件夹里面是编译后的JS文件。 cd .. # 2. 以开发模式运行桌面应用 cd desktop npm run devnpm run dev命令通常会做两件事启动Electron应用并可能开启一个热重载Hot Reload服务器。当你修改了renderer中的前端代码时窗口会自动刷新修改了main进程代码则需要重启应用。第四步生产环境打包如果你想生成和官网下载一样的.dmg安装包cd desktop npm run dist这个命令会触发Electron Builder进行打包。它会将gateway的构建产物和desktop的源码一起打包。编译并打包渲染进程的代码可能会用Webpack或Vite进行优化和混淆。为应用签名如果配置了开发者证书以确保在macOS Gatekeeper下顺利运行。最终在desktop/release/目录下生成ClawFace Gateway-x.x.x.dmg文件。实操心得解决打包过程中的常见坑。网络问题Electron Builder在打包时会下载特定版本的Electron二进制文件如果网络不畅可能导致失败。可以设置镜像或科学上网环境。签名问题如果没有有效的Apple开发者证书打包时需要配置forceCodeSigning: false。但这样生成的App在非开发机上打开时会遇到“无法验证开发者”的警告需要在“系统设置-隐私与安全性”中手动允许。原生模块Native Addons如果项目依赖了需要编译的原生模块比如某些性能监控库你需要确保打包环境通常是CI服务器或你的本地机安装了Xcode Command Line Tools (xcode-select --install)。3.2 核心配置与个性化调整ClawFace Gateway的设计考虑到了可配置性虽然UI可能没有提供全部设置但我们可以通过探索其代码和数据结构来进行深度定制。1. 监控频率与数据精度调整默认的数据刷新频率可能设置在gateway/src/index.ts或各个collector的配置中。例如系统指标可能每2秒采集一次而AI日志扫描可能是每5秒或实时监听文件变化。如果你觉得太耗电或太频繁可以找到类似pollingInterval的配置项适当调大如改为5000毫秒。反之如果你需要更实时的数据可以调小但需注意CPU开销。2. 扩展支持新的AI工具这是很多开发者最感兴趣的部分。项目目前支持Claude Code和OpenAI Codex CLI其扩展框架设计应该是开放的。要添加对新工具比如llama.cpp的服务器日志或自定义的AI API封装器的支持你需要在shared/types.ts中定义新的工具类型在AITool枚举或类似结构中添加新值如LlamaCpp。创建新的日志扫描器在gateway/src/下新建llamaLogScanner.ts。这个类的核心是实现一个统一的接口例如LogScanner包含startWatching(): void和stopWatching(): void方法。你需要研究目标工具的日志格式位置、格式是JSONL、TEXT还是CSV编写对应的解析逻辑提取model,input_tokens,output_tokens等字段。注册扫描器在gateway/src/index.ts的OpenClawMonitor初始化部分将你新建的扫描器实例添加到监控列表中。更新价格表在aiUsageTracker.ts中找到价格配置可能是一个JSON对象或数据库表添加新工具所支持模型的价格单位美元/百万token。3. 自定义中继服务器高级默认的中继服务器是项目方提供的。出于安全或网络性能考虑你可能想自建中继。这需要查看relayClient.ts中WebSocket连接的服务端地址可能是wss://relay.clawface.app。自己实现一个简单的WebSocket中继服务器可以用Node.js的ws库。服务器逻辑很简单维护一个配对码到WebSocket连接的映射表。当Mac客户端以配对码CLAW-1234连接时将其Socket存入映射当iPhone客户端以相同配对码连接时将二者Socket配对之后互相转发消息即可。修改桌面应用中的连接配置指向你自己的服务器地址。这可能需要修改源码并重新打包。4. 实战问题排查与性能优化经验谈即使是一个设计良好的应用在实际部署和使用中也会遇到各种问题。下面是我在长期使用和测试类似工具中总结的常见“坑”及其解决方案。4.1 安装与运行常见问题问题现象可能原因排查步骤与解决方案下载的DMG打不开提示“已损坏”或“无法验证开发者”。macOS Gatekeeper安全策略阻止了未签名的应用。1. 右键点击DMG文件 - “打开”。如果仍有警告再次点击“打开”。2. 如果不行进入系统设置 隐私与安全性在底部“安全性”区域应该能看到关于ClawFace Gateway的阻止信息点击“仍要打开”。3.终极方案仅限信任的软件在终端执行sudo xattr -rd com.apple.quarantine /Applications/ClawFace\ Gateway.app移除隔离属性。应用启动后菜单栏图标不显示或立即消失。权限问题或与其他菜单栏管理工具冲突。1. 检查“系统设置 隐私与安全性 辅助功能”确保ClawFace Gateway有权限控制电脑需要勾选。这是Electron菜单栏应用的常见权限需求。2. 检查“系统设置 隐私与安全性 屏幕录制”如果应用有截图或UI分析功能可能需要。3. 尝试暂时退出Bartender、Hidden Bar等菜单栏整理工具看是否冲突。系统指标显示为0或“N/A”AI成本不更新。监控引擎gateway启动失败或没有读取系统/日志文件的权限。1. 查看应用日志。通常Electron应用会在~/Library/Logs/ClawFace Gateway/目录下生成日志文件查看其中的错误信息。2. 检查AI工具日志路径是否存在且可读。例如确认~/.anthropic/code/logs/目录下有最新的.jsonl文件。3. 如果是从源码运行在终端运行npm run dev观察控制台是否有报错如文件读取权限错误。无法与iPhone配对二维码扫描后无反应。网络防火墙阻止了WebSocket连接端口通常为443/wss或中继服务器暂时不可用。1. 确保Mac和iPhone在同一网络下或两者都能正常访问公网。2. 尝试关闭Mac的防火墙系统设置 网络 防火墙临时测试。3. 检查Mac端是否生成了有效的配对码CLAW-XXXX尝试在iPhone App中手动输入代码而非扫码。4. 查看项目GitHub Issues页面确认中继服务状态。4.2 性能影响与资源占用优化一个常驻菜单栏的监控工具其资源消耗必须足够轻量否则就本末倒置了。ClawFace Gateway在这方面做了不少优化但我们也可以主动进行一些调整。CPU与内存占用在活动监视器中你可能会看到两个主要进程一个是Electron主进程ClawFace Gateway另一个是Node.js监控进程可能叫clawface-gateway或类似。正常情况下两者合计内存占用应在50MB-150MB之间CPU占用在空闲时接近0%数据刷新时可能有短暂小峰值。如果发现占用过高降低监控频率如前所述修改源码中的轮询间隔。将系统监控从2秒改为5秒AI日志扫描从实时监听改为每10秒扫描一次能显著降低CPU唤醒频率。精简监控项如果你不关心磁盘I/O或网络速度可以尝试注释掉systemCollector.ts中对应的收集代码重新打包。检查日志文件体积如果Claude Code等工具产生了巨大的日志文件几百MB文件监听和尾部读取可能会变慢。可以考虑为日志配置滚动策略或让扫描器只读取最近一段时间如最近1小时的日志。电池续航影响频繁的磁盘I/O读取日志和网络活动连接中继是耗电的主要因素。当使用电池时一个实用的技巧是可以在应用内添加一个“省电模式”开关或者在系统设置中为ClawFace Gateway配置“低电量模式”下的节电策略虽然这需要更底层的开发。作为用户可以在不需要远程监控时在iPhone端断开连接这样Mac端就会停止向中继服务器发送数据。数据库优化SQLite数据库usage.db会随着时间增长。可以设置一个自动清理策略例如在aiUsageTracker.ts中增加逻辑定期删除30天前的旧记录或者将旧数据聚合后移至归档表保持主表轻量。与OpenClaw集成的稳定性openclaw-monitor模块需要与OpenClaw的API或进程通信。确保OpenClaw服务运行如果OpenClaw的Agent或服务器没有运行监控面板中对应的状态就会显示异常。需要先确保你的OpenClaw环境是正常启动的。版本兼容性ClawFace Gateway的OpenClaw监控功能可能依赖特定版本的OpenClaw API。如果升级了OpenClaw后监控失效需要检查两者版本是否兼容并关注ClawFace Gateway的更新。4.3 数据准确性与校准成本计算可能不准首先确认以下几点价格表时效性AI模型价格会变动尤其是OpenAI和Anthropic。检查项目aiUsageTracker.ts中的价格常量是否最新。最好的方式是让价格表支持从某个安全的URL动态获取更新。日志字段匹配确认日志扫描器解析的字段名与AI工具实际输出的日志字段名完全一致。不同版本的工具日志格式可能有微调。缓存Token计算像Claude Code这样的工具会使用缓存Cache其日志中可能有cache_read_tokens字段。成本计算逻辑是否正确地处理了缓存token通常成本极低或为零需要仔细核对计算公式。系统温度读数异常在Apple Silicon Mac上读取温度通常通过IOKit或smc工具。不同型号的MacM1, M1 Pro, M2, M3其传感器键值key可能不同。如果温度显示为0或明显不合理可能是传感器键值不匹配。需要查阅对应机型的SMC键值表并更新systemCollector.ts中的相关代码。最后我想分享一点个人体会。ClawFace Gateway这类工具的价值在于它将“不可见”的系统消耗和AI成本变成了“可见”的、可管理的数据。对于独立开发者和中小团队来说这不仅是省钱更是培养资源意识、优化工作流的重要手段。我习惯在长时间运行批量任务时把它放在副屏上随时一瞥就能掌握全局状态那种掌控感是无可替代的。它的开源性质也让我们有机会根据自己的需求去打磨它比如我就在它的基础上为自己常用的另一个内部AI工具添加了日志支持。如果你也厌倦了在终端、活动监视器和账单页面之间来回切换不妨试试它或许你也会爱上这种一切尽在掌握的感觉。