在线状态

Presence（在线状态）系统管理连接到 OpenClaw Gateway 的设备与用户的实时状态，支持在线/离线检测和勿扰模式。

基本概念

每个连接到 Gateway 的设备维护一个 Presence（在线状态）记录：

interface PresenceRecord {
  deviceId: string           // 设备唯一标识
  userId: string             // 关联用户 ID
  status: 'online' | 'offline' | 'dnd'  // 状态
  lastSeen: string           // 最后活跃时间 (ISO 8601)
  channel: string            // 连接渠道
  metadata?: {
    platform: string         // 设备平台 (iOS/Android/Web)
    version: string          // 客户端版本
    ip?: string              // 连接 IP
  }
}

状态类型

状态	标识	说明
在线	online	设备已连接且活跃
离线	offline	设备已断开连接
勿扰	dnd	设备在线但不接收通知

在线/离线检测

连接检测

设备通过 WebSocket 建立持久连接。Gateway 通过以下机制检测状态：

设备连接                      Gateway
  │                             │
  │──── WebSocket 连接 ────────▶│  → status: online
  │                             │
  │◀───── 心跳 Ping ───────────│
  │──── 心跳 Pong ────────────▶│  → 更新 lastSeen
  │                             │
  │◀───── 心跳 Ping ───────────│
  │         (无响应)            │
  │                             │  → 等待超时
  │                             │  → status: offline

心跳配置

presence:
  heartbeat:
    interval: 30000           # 心跳间隔（毫秒）
    timeout: 90000            # 超时判定（毫秒）
    maxMissed: 3              # 允许错过的心跳次数

连接恢复

设备断开后重新连接时，Presence 自动恢复为 online。无需手动操作。

勿扰模式（Do Not Disturb）

DND（Do Not Disturb）模式让设备保持连接但不接收通知：

# 启用勿扰模式
openclaw presence dnd --enable

# 禁用勿扰模式
openclaw presence dnd --disable

# 定时勿扰
openclaw presence dnd --enable --until "08:00"

DND 模式下的行为：

功能	DND 开启时
消息接收	✅ 正常接收（排队处理）
通知推送	❌ 不推送
Typing Indicator	❌ 不显示
Agent 响应	✅ 正常响应
消息存储	✅ 正常存储

Presence 事件

Gateway 通过 WebSocket 推送 Presence 事件给所有连接的客户端：

{
  "type": "presence",
  "event": "status_change",
  "data": {
    "deviceId": "device-abc-123",
    "userId": "user_12345",
    "previousStatus": "online",
    "currentStatus": "offline",
    "lastSeen": "2025-01-15T10:30:00Z"
  }
}

事件类型

事件	触发条件
status_change	设备状态变更
device_connected	新设备连接
device_disconnected	设备断开
dnd_enabled	勿扰模式开启
dnd_disabled	勿扰模式关闭

Agent 感知 Presence

Agent 可以根据用户的在线状态调整行为：

# 当用户离线时的 Agent 行为
presence:
  offlineBehavior:
    queueMessages: true       # 排队消息，用户上线后发送
    silentMode: true          # 不发送实时通知
    
  onlineBehavior:
    immediateResponse: true   # 立即响应
    typingIndicator: true     # 显示输入状态

多设备管理

同一用户可以有多个设备连接：

用户 user_12345:
  ├── 📱 iPhone (online)
  ├── 💻 MacBook (online)
  └── 📟 iPad (offline)

聚合状态: online (任一设备在线即为在线)

presence:
  multiDevice:
    aggregation: any          # any: 任一在线 = 在线
                              # all: 全部在线 = 在线

查看 Presence 状态

# 查看所有设备状态
openclaw presence list

# 输出示例
# DEVICE ID          STATUS    LAST SEEN              CHANNEL
# device-abc-123     online    2025-01-15T10:30:00Z   web
# device-def-456     offline   2025-01-15T09:15:00Z   mobile
# device-ghi-789     dnd       2025-01-15T10:28:00Z   desktop

配置汇总

presence:
  enabled: true               # 启用 Presence 系统
  heartbeat:
    interval: 30000            # 心跳间隔
    timeout: 90000             # 超时判定
  multiDevice:
    aggregation: any           # 多设备聚合策略
  offlineBehavior:
    queueMessages: true
  dnd:
    scheduleEnabled: true      # 允许定时勿扰

下一步

• 了解 网关架构 中设备连接的角色
• 查看 消息格式 了解消息排队机制
• 探索 多 Agent 路由 了解设备与 Agent 的关系