OpenClaw 设备型号数据库（friendly names）完整指南：从 Instances 界面到源码级实现

OpenClaw 的 macOS 伴随应用在 Instances（已连接实例）界面中，将 Apple 设备型号标识符（如 iPad16,6、Mac16,6）映射为人类可读的友好名称，让运维者一眼就能识别每台机器的具体型号（如 "iPad Pro 13-inch (M4)"、"MacBook Pro (14-inch, 2024)"）。本指南以仓库中的官方文档 docs/reference/device-models.md 为核心骨架，结合源码、资源配置与测试，完整讲解该映射库的存储位置、数据来源、加载原理、更新流程与验证方法，并给出源码级的底层实现证据。

一、功能概述：Instances 界面中的友好名称是如何来的

在 OpenClaw macOS 伴随应用中，菜单栏 Instances 设置面板（对应源码 InstancesSettings.swift）会列出当前已连接的 OpenClaw 节点（gateway 推送的 presence 信标），并展示每台实例的主机名、IP、版本、模式等信息。其中设备名展示的核心逻辑位于：

// apps/macos/Sources/OpenClaw/InstancesSettings.swift#L56-L58
let device = DeviceModelCatalog.presentation(
    deviceFamily: inst.deviceFamily,
    modelIdentifier: inst.modelIdentifier)

DeviceModelCatalog.presentation(deviceFamily:modelIdentifier:) 接收来自实例 presence 数据中的两个字段：

字段	含义	来源
deviceFamily	设备家族（如 Mac、iPhone、iPad）	各节点上报的 deviceFamily
modelIdentifier	Apple 型号标识符（如 Mac16,6、iPad16,6）	各节点通过 uname/hw.model 获取并上报

该调用返回一个 DevicePresentation 结构体（定义于 DeviceModelCatalog.swift），包含：

struct DevicePresentation {
    let title: String   // 友好名称，如 "MacBook Pro (14-inch, 2024)"
    let symbol: String? // SF Symbols 图标名，如 "laptopcomputer"
}

界面随后用 device.symbol 作为行首图标（leadingDeviceIcon），用 device.title 作为设备名称标签。界面代码还有一层"防泛化"处理：如果映射结果只是把 family 原样返回（例如没有命中映射时 title 等于 family），则不会显示泛化的 "Mac"/"iPhone" 字样，而优先显示平台信息（见 InstancesSettings.swift 的 isGeneric 判断）。

数据流向全景

从节点采集到界面展示，完整链路如下：

1. 节点侧采集：各 OpenClaw 客户端在启动时通过 InstanceIdentity 获取本机型号标识符——iOS 上调用 uname() 读取 machine 字段，macOS 上通过 sysctlbyname("hw.model", ...) 读取（见 InstanceIdentity.swift）。
2. presence 上报：macOS 伴随应用的 PresenceReporter.swift 周期性（约 180 秒一次）向 gateway 发送 presence 事件，携带 deviceFamily 与 modelIdentifier；连接握手时也会在 GatewayChannel.swift 的 connect 消息中携带这两个字段。
3. Gateway 聚合：gateway 端通过 broadcastPresenceSnapshot 广播 presence 快照（见 presence-events.ts）。
4. 伴随应用拉取：Instances 面板的 InstancesStore.swift 通过控制通道请求 system-presence 拿到 presence 列表，构造 InstanceInfo（含 deviceFamily、modelIdentifier）。
5. 映射展示：DeviceModelCatalog.presentation 将 modelIdentifier 查表得到友好名称，并计算 SF Symbols 图标，最终渲染在 Instances 行内。

二、映射数据的存储位置与文件格式

映射以 JSON 形式随 macOS 应用资源打包（vendor），存放于：

apps/macos/Sources/OpenClaw/Resources/DeviceModels/
├── ios-device-identifiers.json   # iOS/iPadOS 设备映射
├── mac-device-identifiers.json   # macOS 设备映射
├── NOTICE.md                     # 上游来源与 pinned commit 记录
└── LICENSE.apple-device-identifiers.txt  # 上游 MIT 许可证文本

JSON 采用"型号标识符 → 友好名称"的键值结构，值为字符串或字符串数组（同一型号可能对应多个市场名）。例如 iOS 映射 ios-device-identifiers.json 中包含：

{
  "iPhone1,1": "iPhone",
  "iPad16,6": "iPad Pro 13-inch (M4)",
  "iPod9,1": "iPod touch (7th generation)"
}

macOS 映射 mac-device-identifiers.json 中：

{
  "Mac16,5": "MacBook Pro (16-inch, 2024)",
  "Mac16,6": "MacBook Pro (14-inch, 2024)",
  "iMac21,1": "iMac (24-inch, M1, 2021)"
}

数组值示例（同一 identifier 对应多个命名变体）：

{
  "Mac14,8": [
    "Mac Pro (2023)",
    "Mac Pro (Rack, 2023)"
  ]
}

从仓库实际打包的 JSON 统计，iOS 映射约 174 个键（涵盖 iPhone、iPad、iPod 三大前缀及模拟器架构），macOS 映射约 138 个键（涵盖 MacBook、MacBookAir、MacBookPro、iMac、iMacPro、Macmini、MacPro、Mac Studio 等前缀），覆盖从 2009 年 iMac 到 2024 年 M4 设备、2025 年 iPad Pro (M5) 的广泛机型。

在 SwiftPM 构建中，资源通过 Package.swift 声明随 OpenClaw 可执行目标一起打包：

resources: [
    .copy("Resources/OpenClaw.icns"),
    .copy("Resources/DeviceModels"),
],

三、数据来源与确定性构建（pinning）

为保证构建的可复现性，映射数据从 MIT 许可的开源仓库 kyle-seongwoo-jun/apple-device-identifiers 引入，并固定到具体上游 commit，而非跟随上游最新代码。

每次更新时，需在两个 JSON 对应的上游 commit 上分别 pin，并在 NOTICE.md 中记录。当前仓库固定的版本为：

• iOS 映射：commit 8e7388b29da046183f5d976eb74dbb2f2acda955
• macOS 映射：commit 98ca75324f7a88c1649eb5edfc266ef47b7b8193

对应许可证文本存放于 LICENSE.apple-device-identifiers.txt（MIT License，Copyright (c) 2021 Kyle Seongwoo Jun）。

这种做法的好处：任何开发者检出同一 commit 的仓库都能得到完全一致的设备名称映射，避免上游新增机型导致构建产物漂移，也满足 NOTICE/许可证的合规审计要求。

四、更新数据库：逐步操作指南

官方文档给出了完整的五步更新流程，以下结合仓库实际说明每一步的要点。

第 1 步：选定上游 commit

分别选定 iOS 与 macOS 两个映射文件希望 pin 到的上游 commit（可以是同一次更新时上游的两个不同提交）。

第 2 步：更新 NOTICE.md 中的 commit 哈希

编辑 apps/macos/Sources/OpenClaw/Resources/DeviceModels/NOTICE.md，将 iOS 与 macOS 两行的 commit 哈希替换为第 1 步选定的值。

第 3 步：按固定 commit 重新下载 JSON

使用 curl 以 raw.githubusercontent.com 上的具体 commit 为锚点下载两个文件（<commit sha> 占位符需替换为第 1 步选定的真实哈希）：

IOS_COMMIT="<commit sha for ios-device-identifiers.json>"
MAC_COMMIT="<commit sha for mac-device-identifiers.json>"

curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${IOS_COMMIT}/ios-device-identifiers.json" \
  -o apps/macos/Sources/OpenClaw/Resources/DeviceModels/ios-device-identifiers.json

curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${MAC_COMMIT}/mac-device-identifiers.json" \
  -o apps/macos/Sources/OpenClaw/Resources/DeviceModels/mac-device-identifiers.json

两个 -o 输出路径均指向仓库内 apps/macos/Sources/OpenClaw/Resources/DeviceModels/ 目录下的目标文件。

第 4 步：核对上游许可证

检查 LICENSE.apple-device-identifiers.txt 是否仍与上游当前许可证一致；若上游变更了许可证，需同步替换该文件。

第 5 步：验证 macOS 应用可干净构建

以 SwiftPM 方式在 apps/macos 包目录构建，确保无警告：

swift build --package-path apps/macos

五、源码级实现原理：DeviceModelCatalog 的加载与解析

映射查询的底层实现集中在 DeviceModelCatalog.swift，理解它可以让你在更新数据库时更清楚边界行为。

5.1 加载与合并

loadModelIdentifierToName() 将 iOS 与 macOS 两份映射合并到同一个 [String: String] 字典中：

combined.merge(
    self.loadMapping(resourceName: "ios-device-identifiers"),
    uniquingKeysWith: { current, _ in current })
combined.merge(
    self.loadMapping(resourceName: "mac-device-identifiers"),
    uniquingKeysWith: { current, _ in current })

uniquingKeysWith: { current, _ in current } 表示当两个文件出现相同键时保留先合并的（iOS 侧）值。由于 iOS 与 macOS 的型号前缀天然不同（iPhone*/iPad* vs Mac*/iMac*），实际冲突极少。

5.2 资源定位

locateResourceBundle() 依次尝试 Bundle.main（打包后的应用）与 Bundle.module（SwiftPM/测试环境），并在 bundleIfContainsDeviceModels 中通过检查 DeviceModels 子目录下是否存在两个 JSON 资源来确认 bundle 有效。注释明确指出：打包应用中直接访问 Bundle.module 可能因 bundle 位置不符合 SwiftPM 预期而崩溃，因此优先主 bundle。

5.3 容错解析与多名称归一化

JSON 值可能是字符串或字符串数组，NameValue 枚举通过 init(from:) 分别解码两种形态。normalizedName 的处理规则：

• 字符串：去除首尾空白，若为空返回 nil（该型号不进入映射）；
• 字符串数组：对每个元素去除空白并过滤空值，若全部为空返回 nil，否则用 " / " 拼接成单一字符串（例如 Mac Pro (2023) / Mac Pro (Rack, 2023)）。

任何解码失败（catch 分支）都会安全地返回空字典，不影响应用其余功能，体现容错设计。

5.4 展示标题的优先级

presentation(deviceFamily:modelIdentifier:) 生成 title 的优先级为：

1. 查表命中：modelIdentifier 非空且能在合并字典中查到 → 直接用友好名称（如 "iPad Pro 13-inch (M4)"）；
2. family + model 组合："\(family) (\(model))"（如 "Mac (Mac16,6)"）；
3. 仅 family：直接显示 family（如 "iPhone"）；
4. 仅 model：显示原始型号标识符；
5. 全部为空 → 返回 nil（界面不显示设备标签）。

5.5 SF Symbols 图标的推断逻辑

symbol(deviceFamily:modelIdentifier:friendlyName:) 优先按型号标识符前缀推断图标，未命中时再按 deviceFamily 兜底（见 DeviceModelCatalog.swift）：

型号标识符前缀	返回 SF Symbol	说明
ipad	ipad	iPad
iphone	iphone	iPhone
ipod	iphone	iPod touch 复用 iPhone 图标
watch	applewatch	Apple Watch
appletv	appletv	Apple TV
audio / homepod	speaker	HomePod 等音频设备
macbook* / macbookpro / macbookair	laptopcomputer	笔记本
macstudio	macstudio	Mac Studio
macmini	macmini	Mac mini
imac / macpro	desktopcomputer	一体机/塔式
其他 mac* 前缀	解析 friendlyName 关键字	含 "macbook"→"laptopcomputer"、"imac"→"desktopcomputer"、"mac mini"→"macmini"、"mac studio"→"macstudio"、"mac pro"→"desktopcomputer"

当型号标识符为空时，按 deviceFamily 兜底：ipad→ipad、iphone→iphone、mac→laptopcomputer、android→android、linux→cpu、其余→cpu。

5.6 测试验证

仓库包含针对上述行为的单元测试 DeviceModelCatalogTests.swift，覆盖：

• 型号前缀优先（iPad16,6→ipad、iPhone17,3→iphone）；
• Mac 变体依赖友好名称推断（Mac Studio (2025)→macstudio、Mac mini (2024)→macmini、MacBook Pro (14-inch, 2024)→laptopcomputer）；
• 无型号时按 family 兜底（Android→android、Linux→cpu）；
• 打包映射的真实查询（iPhone1,1→iPhone）。

这些测试由 apps/macos/Package.swift 中的 OpenClawIPCTests 测试目标承载，可用 swift test --package-path apps/macos 运行（测试目标启用了 Swift Testing 实验特性）。

六、常见问题与排查思路

6.1 界面不显示设备名称

可能原因与对应排查点：

• presence 未上报：检查网关是否在线、Instances 面板是否收到 presence 信标（InstancesStore 会拉取 system-presence）；PresenceReporter 每 180 秒周期性上报，连接瞬间也会触发一次。
• 映射未命中：新机型（如新发布的 identifier）尚未包含在 pinned JSON 中，此时 presentation 退化为 family (model) 或仅 family；界面会因 isGeneric 逻辑隐藏泛化名称。
• 资源未打包：确认构建使用了 Package.swift 的资源声明，否则 loadMapping 返回空字典。

6.2 需要覆盖新机型时

按"第四节"的五步流程更新：更新 NOTICE.md 的 commit、重新下载两个 JSON、核对许可证、执行 swift build --package-path apps/macos 验证无警告。建议同时运行测试目标确认 DeviceModelCatalogTests 全部通过，并留意 uniquingKeysWith 合并规则对新键的影响。

七、小结

OpenClaw 的设备型号数据库是"上游开源数据 + 确定性 pinning + 本地容错加载"的典型实践：数据来自 MIT 许可的 kyle-seongwoo-jun/apple-device-identifiers，以 JSON 形式 vendored 进 apps/macos/Sources/OpenClaw/Resources/DeviceModels/，由 DeviceModelCatalog.swift 完成合并、解析、标题与图标推断，最终服务于 Instances 界面的设备友好展示。更新数据库时只需遵循 NOTICE 更新、pinned 下载、许可证核对与干净构建验证四步即可保持构建可复现、合规可审计。相关实现文档可在 docs/reference/device-models.md 查阅。