设备模型库

Device Models（设备模型）定义了 OpenClaw 管理的物理或虚拟设备的能力和约束。每个设备模型描述了设备支持的交互方式、硬件特性与通信协议。

设备模型概念

设备模型是一种能力声明，告诉 Agent 和网关当前设备可以做什么、不能做什么。

# 设备模型示例
device:
  model: 'smart-speaker'
  capabilities:
    audio: true
    display: false
    keyboard: false
    touch: false
    camera: false

为什么需要设备模型

不同设备有不同的交互能力。Agent 需要根据设备能力调整响应方式——对智能音箱用语音回复，对手机用图文回复。

内置设备模型

能力矩阵

设备模型	音频	显示	键盘	触控	摄像	文件
desktop	✅	✅	✅	❌	✅	✅
mobile	✅	✅	✅	✅	✅	✅
tablet	✅	✅	❌	✅	✅	✅
smart-speaker	✅	❌	❌	❌	❌	❌
smart-display	✅	✅	❌	✅	✅	❌
iot-sensor	❌	❌	❌	❌	❌	❌
web-client	✅	✅	✅	✅	❌	✅
cli	❌	✅	✅	❌	❌	✅

设备模型详情

desktop

model: desktop
displayName: 桌面电脑
capabilities:
  audio: { input: true, output: true }
  display: { width: 1920, height: 1080, color: true }
  keyboard: true
  touch: false
  camera: { resolution: '1080p' }
  fileSystem: { read: true, write: true }
messageFormats: ['text', 'markdown', 'image', 'file', 'code']
maxMessageLength: 10000

mobile

model: mobile
displayName: 移动设备
capabilities:
  audio: { input: true, output: true }
  display: { width: 390, height: 844, color: true }
  keyboard: true
  touch: true
  camera: { resolution: '4K' }
  fileSystem: { read: true, write: true }
messageFormats: ['text', 'image', 'voice', 'location']
maxMessageLength: 5000

smart-speaker

model: smart-speaker
displayName: 智能音箱
capabilities:
  audio: { input: true, output: true }
  display: false
  keyboard: false
  touch: false
  camera: false
  fileSystem: false
messageFormats: ['voice']
maxMessageLength: 500

添加自定义设备模型

在 devices/ 目录下创建设备模型定义文件：

# devices/kiosk.yaml
model: kiosk
displayName: 自助终端机
description: 商场自助服务终端

capabilities:
  audio:
    input: true
    output: true
  display:
    width: 1080
    height: 1920   # 竖屏
    color: true
  keyboard: false
  touch: true
  camera:
    resolution: '720p'
  printer: true       # 自定义能力
  fileSystem: false

messageFormats: ['text', 'image', 'qrcode']
maxMessageLength: 2000

constraints:
  sessionTimeout: 300    # 5 分钟无操作超时
  language: ['zh-CN']

注册自定义设备模型：

# openclaw.config.yaml
devices:
  models:
    - ./devices/kiosk.yaml
    - ./devices/car-display.yaml

设备特定配置

在 Agent 中根据设备类型调整行为：

agents:
  - name: assistant
    deviceConfig:
      smart-speaker:
        model: gpt-4o-mini     # 音箱用轻量模型
        maxTokens: 200          # 限制回复长度
        responseFormat: 'voice'
      desktop:
        model: gpt-4o
        maxTokens: 2000
        responseFormat: 'markdown'
      mobile:
        model: gpt-4o-mini
        maxTokens: 500
        responseFormat: 'text'

自适应响应

Agent 会根据设备能力自动调整回复格式。在智能音箱上只返回简短语音，在桌面端可以返回丰富的 Markdown 内容。

设备配对

设备通过配对流程与 OpenClaw 网关建立信任关系：

# 在网关端生成配对码
openclaw device pair --model kiosk

# 设备端使用配对码连接
# 输出: Pairing code: ABC-123-XYZ
# 有效期: 5 分钟

🇨🇳 中国用户须知

• 国内智能音箱（天猫精灵、小爱同学等）可通过自定义设备模型接入
• 自助终端机场景在国内商场、医院、银行应用广泛，建议自定义 kiosk 设备模型
• 设备配对时注意内网环境的防火墙配置