OpenClaw macOS 菜单栏图标与 Dock 图标全解状态机、动画渲染管线与图标生成流程【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本篇以 macOS 客户端apps/macos的图标系统为主线讲清两个紧密相关但相互独立的部分菜单栏里那只会眨眼、摆腿、竖耳朵的小龙虾menu bar critter的状态与动画实现以及 Dock 图标的多风格选择与离线生成流程。读完你能掌握各状态Idle / Paused / Sleeping / Celebrate / Voice wake / Working的触发条件与视觉参数earScale、antennaDroop、legWiggle等理解 18pt 模板图标的 Retina 渲染管线并能用scripts/generate-mac-app-icons.sh重新生成并校验全部 12 个 Dock 图标资源。整体范围与核心文件菜单图标与 Dock 图标共享同一个吉祥物Molty 小龙虾但由两套机制驱动互不干扰部分载体核心文件菜单栏小图标critter18×18pt 模板图标Swift 动态绘制CritterIconRenderer.swift、CritterStatusLabel.swift、CritterStatusLabelBehavior.swiftDock 图标预编译.icns资源运行期切换DockIconManager.swift、AppIconStyle.swift、generate-mac-app-icons.sh渲染入口是CritterIconRenderer.makeIcon(...)状态与动画接线在CritterStatusLabel及其Behavior扩展中完成。相关文档可继续参阅 Menu bar 与 Voice wake。Dock 图标六种风格与 macOS 26 的原生样式在 Mac 应用的 Dashboard 中通过Settings → This Mac → Dock icon选择 Dock 图标。当前仓库共支持 6 种设计源码定义见 AppIconStyle.swift 的AppIconStyle枚举rawValue 分别为paper、heritage、clawmark、origami、pincer、openCOriginal默认rawValuepaper纸砖底上的原始 Molty 剪影Heritage早期 README 中那只举起钳子的龙虾Clawmark粗粝雕塑感的小龙虾钳Origami折纸切面风格的 MoltyPincer单钳剪影带圆润流畅的手腕曲线Open C环形钳形两个对向钳尖。每种设计都同时提供 light 和 dark 两套素材。源码层面的切换逻辑在 DockIconManager.swift 的updateIconImage()中从AppDefaults读取当前 profile 保存的风格appIconStyleKey结合NSApp.effectiveAppearance解析出 light/dark 外观资源名按\(rawValue)-\(appearance.rawValue)拼出如heritage-dark再调用NSApp.applicationIconImage image立即生效macOS 26 及以上Original 使用原生图标样式跟随系统设置 → 外观 → 图标与小组件样式选 Dark → Auto 即可随外观自动切换否则默认图标样式即使应用窗口为深色也可能保持浅色。此时usesSystemIcon返回 trueupdateIconImage()会把applicationIconImage置回nil把外观完全交给 Icon Composer 编译进包的原生 dark/clear/tinted 版本旧版 macOSOriginal 在应用运行期间跟随 light/dark 外观其他五种风格同理见AppIconAppearance(NSAppearance)以.aqua/.darkAqua做 bestMatch 判定。选择结果按 OpenClaw profile 单独保存并立即生效。需要注意的是自定义风格只改变运行中的应用的 Dock 图标应用退出后 Finder/Dock 里的磁贴仍使用打包时的 Original 图标菜单栏 critter 及其动画则完全独立于这套机制。图标资源的来源与再生成Original 的矢量源是apps/macos/Icon.iconIcon Composer 文档其余五种矢量源位于apps/macos/AppIconDesigns/下的Heritage.icon、Clawmark.icon、Origami.icon、Pincer.icon、OpenC.icon。编辑源文件后用脚本重新生成 12 个 icns6 风格 × light/dark并校验# 重新生成 bash scripts/generate-mac-app-icons.sh # 校验产物是否与仓库内已提交资源一致CI 用途 bash scripts/generate-mac-app-icons.sh --check从 generate-mac-app-icons.sh 的实现看流程分三步外观定制内嵌的 Python 段把每个.icon源拷贝为{name}-light/{name}-dark两份dark 版本改写icon.json的fill——paper使用 sRGB 线性渐变0.192→0.078 灰阶heritage/clawmark/origami/pincer/openC各用一种深色纯色填充其中pincer与openC还会把Assets/molty.svg的前景fill反转为#f8f5ec即单色对monochrome pair连图形一起反转编译对 12 份文档逐一执行xcrun actool --compile ... --app-icon Icon --minimum-deployment-target 15.0 --platform macosx由 Apple 资产编译器负责 macOS 的遮罩mask与留白padding落盘/比对--write模式把Icon.icns写入apps/macos/Sources/OpenClaw/Resources/AppIcons/并把paper-light.icns复制为OpenClaw.icns主图标供 Icon Composer 原生样式使用--check模式则cmp逐一对比发现Stale ... icon即退出非零。也就是说生成器负责自定义深色背景 单色前景actool负责平台标准的遮罩与留白打包阶段再把主 Icon Composer 文档编译进应用以获得 macOS 26 的原生样式。仓库内对应的测试如 AppLaunchPresentationPolicyTests.swift、DeviceSettingsBridgeTests.swift覆盖了 Dock 图标可见性与设置下发的分支。菜单栏小图标六个状态与触发表状态触发条件视觉效果Idle默认正常眨眼/摆动动画睁眼时带高光glintPausedisPausedtrue触角垂下下班姿态且眼睛睁开无动作Sleeping网关断开/未配置触角垂下双眼闭成⌣ ⌣眼睑无动作Celebrate消息发出sendCelebrationTick双眼闪现约 0.9s 的开心∩ ∩弧线同时踢腿Voice wake大耳朵听到唤醒词触角竖直拉长earScale1.9静默后回落WorkingisWorkingtrue或存在活动的IconState腿部快速摆动legWiggle最高1.0并叠加小的水平位移叠加在 idle 摆动之上状态到渲染参数的映射集中在 CritterStatusLabelBehavior.swift 的iconImage计算属性中源码与上表一一对应// 暂停 下班睁眼 触角全垂antennaDroop: 1与 sleeping垂 闭眼刻意区分 if self.isPaused { return CritterIconRenderer.makeIcon(blink: 0, antennaDroop: 1, badge: nil) } // 睡眠 闭眼弧线 垂触角 if self.isSleeping { return CritterIconRenderer.makeIcon(blink: 1, antennaDroop: 1, eyesClosedLines: true, badge: nil) } // 其余情况working 时腿摆动下限抬到 0.6耳部 boost 时 earScale 抬到 1.9 return CritterIconRenderer.makeIcon( blink: self.blinkAmount, legWiggle: max(self.legWiggle, self.isWorkingNow ? 0.6 : 0), earWiggle: self.earWiggle, earScale: self.earBoostActive ? 1.9 : 1.0, happyEyes: self.celebrating, badge: badge)此外还有一类工具活动徽章当某个会话存在活动 job 或工具时可在同一 critter 图标上方叠加 SF Symbol 圆片徽章如 exec 用chevron.left.slash.chevron.right。徽章数据来自IconState/ActivityKindbadgeSymbolNamebadgeProminence完整状态模型见 Menu bar。在渲染端CritterIconRenderer.swift 的drawBadge先以.clear混合模式在图标右上角挖出一个直径约为画布 46% 的圆孔保证可读性再按 prominence 分级primary1.0 /overridden0.85 /secondary0.58调整填充与描边不透明度最后把 SF Symbol 以.black字重、模板模式镂空进去——源码注释说明这种填充圆片 透明镂空比小尺寸单色字形在模板渲染的菜单栏里更清晰。渲染管线18pt 模板图标如何在 Retina 上保持清晰makeIcon的完整签名为 CritterIconRenderer.swiftstatic func makeIcon( blink: CGFloat, legWiggle: CGFloat 0, earWiggle: CGFloat 0, earScale: CGFloat 1, antennaDroop: CGFloat 0, eyesClosedLines: Bool false, happyEyes: Bool false, badge: Badge? nil) - NSImage各参数的作用与取值范围画布与位深逻辑画布 18×18ptmakeBitmapRep()强制分配 36×36px2×位图后备存储Retina 下保持锐利绘制完成后image.isTemplate true让系统按菜单栏前景色label color自动着色天然适配深浅色菜单栏blink0–1眨眼程度。眼睛高度按eyeOpen max(0.22, 1 - blink)收缩——注释说明眨眼只是压扁成软线脸部不会在中途消失仅当眼睛张开度超过 70% 时才在眼内绘制高光小点glintR 0.26 × 眼宽避免半闭眼中出现噪点antennaDroop0–1把触角端点与二次贝塞尔控制点在抬起位upTip/upControl与下垂位downTip/downControl之间线性插值用于 Paused 与 SleepingearScale默认 1.0唤醒 boost 为 1.9reach 1 (min(earScale, 1.9) - 1) * 0.6同时放触角的高度与陡度尖端 x 向内侧收源码注释指出 idle 触角尖端刻意留在画布夹取线之下正是为了给 voice-wake 的更长更陡留出真实空间——否则 18pt 下竖起效果不可见legWiggle0–1两只腿以±legLiftlegLift legH × 0.35 × legWiggle反相起落形成小碎步Working 状态每 tick 额外走scurry()随机取 0.7–1.0 的摆动并叠加±0.6pt的水平位移eyesClosedLines / happyEyes都用弧线代替椭圆眼——happyEyes取弧的上半∩ ∩庆祝用eyesClosedLines取下半⌣ ⌣睡眠用线宽取max(2 × stepY, 0.34 × 眼高)保证像素对齐后仍可见。几何参数全部按画布比例给出Geometry结构体CritterIconRenderer.swift身体宽 0.72w、高 0.66h 的近圆剪影、两侧 0.10w 的圆手臂凸起、0.14w×0.18h 的圆角腿——注释反复强调这些比例必须撑得住 18pt剪影在该尺寸下保持连通即可读。动画调度随机计时器、工作节拍与庆祝CritterStatusLabel定义于 CritterStatusLabel.swift接收isPaused、isSleeping、isWorking、earBoostActive、blinkTick、sendCelebrationTick、gatewayStatus、iconState等输入行为扩展中主循环.task(id: tickTaskID)用 Swift 并发任务而非 CombineTimerPublisher驱动周期更新——源码注释说明在 macOS 26.2 上观察到 Combine 回调内 executor 检查引发的崩溃故弃用。tickTaskID由动画是否有效 / 耳部 boost / 是否 working三个位组合而成任一变化即重启取消旧任务重建循环节拍策略nextAnimationTickDelay规定 working 时固定 0.35s 的稳态节拍idle 时只睡到下一个最近事件blink / wiggle / leg / ear 四个 deadline 的最小值最小唤醒间隔 0.05s随机事件窗口scheduleRandomTimers眨眼 3.5–8.5s、身体摆动 6.5–14s、踢腿 5.0–11.0s、摆耳 7.0–14.0s各事件互相独立避免整齐划一的机械感庆祝sendCelebrationTick变化时触发celebrate()——置celebrating渲染出∩ ∩眼并踢腿900ms 后复位。用celebrationGeneration代数锁保证最新一次庆祝独占清除权旧到期任务自动放弃眼睛不会卡在开心状态。工作完成也会触发庆祝但workCompletionBeat要求持续工作至少 10sminimumDuration: 10防止菜单栏一闪而过的短工制造庆祝噪音网关从.failed恢复到 running 时同样会 celebrate wiggleEarsreconnectBeat只认 failed→running 的 comeback冷启动不庆祝。Voice wake大耳朵的触发链与静默窗口文档描述的听到唤醒词后耳朵竖起、静默后回落由以下调用链实现均以当前源码为准触发AppStateStore.shared.startVoiceEars()AppState.swift 中置earBoostActive true调用方包括语音唤醒捕获管线 VoiceWakeRuntime.swift、覆盖层窗口 VoiceWakeOverlayControllerWindow.swift 以及调试工具VoiceWakeTesterVoiceWakeTester.swift停止stopVoiceEars()在捕获结束时被调用VoiceWakeRuntime.swift 的finalizeCapture、VoiceWakeTester、VoiceWakeOverlayControllerSession均有对应调用静默窗口VoiceWakeRuntime中silenceWindow 2.0s正常仅听到触发词且无后续语音时使用更长的triggerOnlySilenceWindow文档给出 5.0s。循环中按heardBeyondTrigger ? silenceWindow : triggerOnlySilenceWindow取阈值超过即finalizeCapture收尾互斥门控boost 期间earBoostActive会同时暂停 idle 的 blink/wiggle/leg/ear 计时器——effectiveAnimationsEnabled不检查它但tick、.task循环、blink/celebrate 的onChange处理器都显式guard !earBoostActive避免耳朵竖起的同时身体还在乱动boost 结束后onChange(of: earBoostActive)重新scheduleRandomTimers。行为约束与设计守则文档末尾给出了两条实现者守则源码与之完全吻合不对外暴露 CLI/broker 开关耳朵 boost 与 working 状态均由应用内部信号驱动working 来自isWorking/IconState.isWorking耳朵来自startVoiceEars没有外部切换入口防止误触导致的乱抖任何新的 TTL 都保持短远小于 10s保证图标在 job 卡死时也能快速回到基线。与之配套的是渲染端的兜底resetMotion()在状态切换pause、sleep、boost 开启、动画关闭时一次性归零blinkAmount、celebrating、iconRotation、iconTranslation、legWiggle、earWiggle确保任何状态迁移后图标立即回到该状态的静止姿态。渲染单测见 CritterIconRendererTests.swift 与 CritterStatusBeatsTests.swift可分别验证图标绘制分支与 reconnect/work-completion 庆祝节拍逻辑。小结OpenClaw 的 macOS 图标体系可以概括为三层Dock 层由 6 套矢量源 actool编译产物构成运行期按 profile 与外观即时切换macOS 26 上 Original 交还系统原生样式菜单栏层由CritterIconRenderer以 18pt/2× 模板图标的矢量管线把 6 种状态映射为精确的几何参数调度层则用 Swift 并发的随机计时器循环在 0.35s 工作节拍与自然间隔的 idle 事件之间取得既灵动又不吵的平衡。理解了earScale、antennaDroop、legWiggle、blink四个连续参数加eyesClosedLines/happyEyes两个开关就掌握了这套图标系统的全部自由度。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考