28.4 共享组件

生成模型：Claude Opus 4.6 (anthropic/claude-opus-4-6) Token 消耗：输入 ~190k tokens，输出 ~5k tokens（本节）

---

macOS 和 iOS 应用之间存在大量共享逻辑——Gateway WebSocket 协议、聊天 UI、Canvas 命令解析、设备认证等。这些共享代码统一放在 apps/shared/OpenClawKit/ 中。

28.4.1 OpenClawKit 架构

Swift 包结构

OpenClawKit 是一个 Swift 包，包含三个库 target：

// apps/shared/OpenClawKit/Package.swift
let package = Package(
    name: "OpenClawKit",
    platforms: [.iOS(.v18), .macOS(.v15)],
    products: [
        .library(name: "OpenClawProtocol", targets: ["OpenClawProtocol"]),
        .library(name: "OpenClawKit", targets: ["OpenClawKit"]),
        .library(name: "OpenClawChatUI", targets: ["OpenClawChatUI"]),
    ],
    dependencies: [
        .package(url: "ElevenLabsKit", exact: "0.1.0"),   // TTS 语音合成
        .package(url: "textual", exact: "0.3.1"),          // Markdown 渲染
    ],
)

三层架构

┌──────────────────────┐
│   OpenClawChatUI     │  ← SwiftUI 聊天组件（macOS + iOS 共用）
│   依赖: OpenClawKit   │
│   依赖: Textual       │  ← Markdown 渲染
├──────────────────────┤
│   OpenClawKit        │  ← 核心业务逻辑
│   依赖: OpenClawProtocol│
│   依赖: ElevenLabsKit │  ← TTS 提供商
├──────────────────────┤
│   OpenClawProtocol   │  ← 纯数据模型 + 协议定义
│   无外部依赖          │
└──────────────────────┘

层	职责	文件数
OpenClawProtocol	Gateway JSON 模型（GatewayModels）、Wizard 帮助函数、AnyCodable	3
OpenClawKit	WebSocket 客户端、设备认证、Canvas 命令、TTS、能力声明、Deep Links	39
OpenClawChatUI	SwiftUI 聊天视图、消息渲染、Markdown、会话管理	13

OpenClawProtocol — 纯数据层

最底层只包含 Gateway 通信的数据模型，没有任何外部依赖：

Sources/OpenClawProtocol/
├── AnyCodable.swift       # 动态 JSON 值类型
├── GatewayModels.swift    # Gateway 帧、Hello、事件等类型
└── WizardHelpers.swift    # 引导向导的辅助类型

这种分层确保了协议类型可以被任何 target 引用，而不会引入不必要的依赖。

OpenClawKit — 核心逻辑

中间层包含与 Gateway 交互的所有核心逻辑：

Sources/OpenClawKit/
├── GatewayChannel.swift          # WebSocket 客户端（protocol + actor）
├── GatewayNodeSession.swift      # 节点会话管理
├── GatewayTLSPinning.swift       # TLS 证书钉扎
├── GatewayPush.swift             # 推送通知集成
├── DeviceIdentity.swift          # Ed25519 设备密钥
├── DeviceAuthStore.swift         # 设备 token 存储
├── Capabilities.swift            # 能力声明枚举
├── CanvasCommands.swift          # Canvas 操控命令
├── CanvasA2UIAction.swift        # Agent-to-UI 动作
├── CanvasA2UICommands.swift      # A2UI 命令定义
├── CanvasCommandParams.swift     # Canvas 参数类型
├── CameraCommands.swift          # 摄像头命令
├── ScreenCommands.swift          # 屏幕录制命令
├── LocationCommands.swift        # 位置命令
├── SystemCommands.swift          # 系统命令
├── TalkDirective.swift           # Talk Mode 指令
├── TalkPromptBuilder.swift       # Talk 提示词构建
├── TalkSystemSpeechSynthesizer.swift  # 系统 TTS
├── TalkHistoryTimestamp.swift    # 对话历史时间戳
├── BonjourTypes.swift            # Bonjour 服务发现类型
├── BonjourEscapes.swift          # Bonjour 名称转义
├── DeepLinks.swift               # 深度链接处理
├── StoragePaths.swift            # 文件路径常量
├── JPEGTranscoder.swift          # JPEG 编解码
└── ...

WebSocket 客户端

GatewayChannel 是共享的 WebSocket 客户端，通过协议抽象（WebSocketTasking）与具体的网络实现解耦：

// apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift
public protocol WebSocketTasking: AnyObject {
    var state: URLSessionTask.State { get }
    func resume()
    func cancel(with closeCode: URLSessionWebSocketTask.CloseCode, reason: Data?)
    func send(_ message: URLSessionWebSocketTask.Message) async throws
    func receive() async throws -> URLSessionWebSocketTask.Message
}

extension URLSessionWebSocketTask: WebSocketTasking {}

URLSession 的默认实现设置了 16MB 的最大消息大小——大型快照和历史 payload 可能超过默认限制：

extension URLSession: WebSocketSessioning {
    public func makeWebSocketTask(url: URL) -> WebSocketTaskBox {
        let task = self.webSocketTask(with: url)
        task.maximumMessageSize = 16 * 1024 * 1024  // 16 MB
        return WebSocketTaskBox(task: task)
    }
}

连接选项通过 GatewayConnectOptions 结构体传递：

public struct GatewayConnectOptions: Sendable {
    public var role: String          // "node" 或 "operator"
    public var scopes: [String]      // 权限范围
    public var caps: [String]        // 设备能力
    public var commands: [String]    // 支持的命令
    public var permissions: [String: Bool]  // 已获取的权限
    public var clientId: String
    public var clientMode: String
}

能力系统

设备能力通过一个简洁的枚举定义：

public enum OpenClawCapability: String, Codable, Sendable {
    case canvas       // 画布操控
    case camera       // 摄像头
    case screen       // 屏幕录制
    case voiceWake    // 语音唤醒
    case location     // 位置信息
}

每个能力对应一组命令类型（如 CameraCommands、ScreenCommands），Gateway 根据节点声明的能力列表来决定暴露哪些工具给 AI 代理。

OpenClawChatUI — 共享聊天界面

最上层是 SwiftUI 聊天组件，被 macOS 和 iOS 共同使用：

Sources/OpenClawChatUI/
├── ChatView.swift                 # 主聊天视图
├── ChatViewModel.swift            # 聊天视图模型
├── ChatComposer.swift             # 消息输入组件
├── ChatMessageViews.swift         # 消息气泡渲染
├── ChatModels.swift               # 聊天数据模型
├── ChatTransport.swift            # 聊天传输协议
├── ChatPayloadDecoding.swift      # 消息 payload 解码
├── ChatSessions.swift             # 会话管理
├── ChatSheets.swift               # 聊天相关的 Sheet 视图
├── ChatTheme.swift                # 聊天主题配色
├── ChatMarkdownPreprocessor.swift # Markdown 预处理
├── ChatMarkdownRenderer.swift     # Markdown 渲染（使用 Textual）
└── AssistantTextParser.swift      # 助手文本解析

ChatView 是一个完整的 SwiftUI 视图，包含消息列表、输入框、会话切换等。它通过 ChatTransport 协议与具体的网络层解耦——macOS 和 iOS 各自提供不同的 transport 实现。

Android 的共享策略

Android 应用无法直接使用 Swift 包。它的共享策略是：

1. 资源文件复用：通过 Gradle 的 assets.srcDir 直接引用 OpenClawKit/Resources

2. 协议重新实现：在 ai.openclaw.android.protocol 包中用 Kotlin 重新定义了能力枚举、命令类型等

3. 通信协议一致：虽然语言不同，但 JSON 格式的 WebSocket 帧是跨平台统一的

---

本节小结

1. OpenClawKit 是 macOS 和 iOS 共享的 Swift 包，采用三层架构：Protocol（纯数据）→ Kit（核心逻辑）→ ChatUI（SwiftUI 组件）。

2. WebSocket 客户端通过协议抽象与 URLSession 解耦，支持 16MB 大消息和 TLS 证书钉扎。

3. 能力系统通过 5 个枚举值声明设备硬件能力，Gateway 据此决定可用工具。

4. ChatUI 层提供完整的 SwiftUI 聊天界面，通过 ChatTransport 协议支持不同的网络后端。

5. Android 通过资源共享和协议重实现来保持跨平台一致性，JSON 帧格式是三个平台的统一契约。