14.15 macOS上的Gateway

macOS伴侣应用macOS伴侣应用

Gateway 是 OpenClaw macOS 应用的核心通信枢纽,负责协调应用与智能体运行时之间的所有交互。

概述

macOS Gateway 提供了一个基于 WebSocket 的通信层,使智能体能够与 macOS 应用的各个组件进行交互,包括 Canvas、菜单栏、IPC 等功能模块。

核心功能

消息路由

  • 双向 WebSocket 通信
  • 消息分发与路由
  • 事件订阅机制
  • 实时状态同步

会话管理

  • 多会话支持
  • 会话优先级管理(Main 优先)
  • 会话状态跟踪
  • 自动重连机制

控制通道

Gateway 提供控制通道(agent 流)用于传输:

  • job 事件 - 任务执行状态
  • tool 事件 - 工具调用阶段
  • 健康检查数据
  • 节点状态信息

架构组件

WebSocket 服务器

// Gateway WebSocket 端点
ws://127.0.0.1:8080/gateway

// 连接示例
const ws = new WebSocket('ws://127.0.0.1:8080/gateway');
ws.onopen = () => {
  console.log('Connected to Gateway');
};

消息格式

{
  "type": "command",
  "target": "canvas",
  "action": "present",
  "payload": {
    "content": "..."
  },
  "sessionId": "main",
  "timestamp": 1234567890
}

集成模块

Canvas 控制

# 显示 Canvas
openclaw nodes canvas present

# 更新内容
openclaw nodes canvas update --content "..."

# 隐藏 Canvas
openclaw nodes canvas dismiss

菜单栏控制

# 更新菜单栏状态
openclaw menubar update --status "Working"

# 设置图标状态
openclaw menubar icon --state working

IPC 通信

# 发送 IPC 消息
openclaw ipc send --target "app" --message "..."

# 订阅 IPC 事件
openclaw ipc subscribe --channel "events"

配置

基本配置

{
  "gateway": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 8080,
    "protocol": "ws"
  }
}

安全配置

{
  "gateway": {
    "security": {
      "requireAuth": true,
      "allowedOrigins": ["localhost"],
      "maxConnections": 10
    }
  }
}

性能配置

{
  "gateway": {
    "performance": {
      "messageQueueSize": 100,
      "compressionEnabled": true,
      "keepAliveInterval": 15000,
      "timeout": 30000
    }
  }
}

使用场景

智能体操作

  • 执行系统命令
  • 控制 UI 组件
  • 访问文件系统
  • 管理应用状态

状态同步

  • 实时更新菜单栏状态
  • 同步 Canvas 内容
  • 推送健康检查结果
  • 广播系统事件

监控与调试

查看连接状态

# 查看 Gateway 状态
openclaw gateway status

# 查看活跃连接
openclaw gateway connections

# 查看消息统计
openclaw gateway stats

消息追踪

# 启用消息追踪
openclaw gateway trace --enable

# 查看消息日志
./scripts/clawlog.sh --category Gateway --last 5m

# 过滤特定类型消息
./scripts/clawlog.sh --category Gateway --filter "type=command"

性能监控

# 查看性能指标
openclaw gateway metrics

# 监控消息延迟
openclaw gateway latency

# 查看资源使用
openclaw gateway resources

错误处理

连接错误

  • 连接被拒绝: 检查 Gateway 是否启动,端口是否被占用
  • 握手失败: 验证协议版本,检查认证配置
  • 连接超时: 调整超时配置,检查网络状态

消息错误

  • 消息格式错误: 验证 JSON 格式,检查必需字段
  • 路由失败: 确认目标模块已注册
  • 处理超时: 检查消息处理器,优化性能

重连机制

{
  "gateway": {
    "reconnect": {
      "enabled": true,
      "maxRetries": 5,
      "retryDelay": 1000,
      "backoffMultiplier": 2
    }
  }
}

最佳实践

性能优化

  • 启用消息压缩
  • 批量发送消息
  • 使用消息队列
  • 实施连接池
  • 监控资源使用

可靠性保障

  • 配置自动重连
  • 实施消息确认机制
  • 设置合理的超时
  • 启用心跳检测
  • 记录详细日志

安全建议

  • 限制连接来源
  • 启用身份认证
  • 加密敏感数据
  • 监控异常连接
  • 定期审计日志
相关资源