5.15 会话工具

核心概念核心概念

OpenClaw 提供了一组会话工具,允许代理跨会话进行通信、查询历史记录和创建新的会话。

核心工具

sessions_list

列出当前代理可访问的所有会话。

// 工具调用示例
{
  "name": "sessions_list",
  "input": {}
}

// 返回结果
{
  "sessions": [
    {
      "id": "main-123",
      "kind": "main",
      "displayName": "主对话",
      "lastActive": "2026-02-01T10:30:00Z"
    },
    {
      "id": "group-456",
      "kind": "group",
      "displayName": "团队协作",
      "channel": "slack-general"
    }
  ]
}

sessions_history

获取指定会话的历史消息记录。

// 工具调用示例
{
  "name": "sessions_history",
  "input": {
    "sessionId": "group-456",
    "limit": 50,          // 可选: 限制返回的消息数量
    "before": "msg-789"   // 可选: 获取某条消息之前的历史
  }
}

// 返回结果
{
  "messages": [
    {
      "id": "msg-100",
      "role": "user",
      "content": "帮我分析这个日志文件",
      "timestamp": "2026-02-01T09:00:00Z"
    },
    {
      "id": "msg-101",
      "role": "assistant",
      "content": "我来帮你分析...",
      "timestamp": "2026-02-01T09:00:15Z"
    }
  ]
}

sessions_send

向另一个会话发送消息,实现跨会话通信。

// 工具调用示例
{
  "name": "sessions_send",
  "input": {
    "targetSession": "group-456",
    "message": "已完成数据分析,结果已上传",
    "metadata": {               // 可选: 附加元数据
      "priority": "high",
      "source": "analysis-bot"
    }
  }
}

// 返回结果
{
  "success": true,
  "messageId": "msg-202",
  "deliveredAt": "2026-02-01T10:35:00Z"
}

sessions_spawn

创建新的子会话。

// 工具调用示例
{
  "name": "sessions_spawn",
  "input": {
    "kind": "group",                    // 会话类型
    "name": "代码审查讨论",
    "config": {                         // 可选: 会话配置
      "channel": "slack-dev",
      "permissions": ["read", "write"]
    }
  }
}

// 返回结果
{
  "sessionId": "group-789",
  "kind": "group",
  "displayName": "代码审查讨论",
  "createdAt": "2026-02-01T10:40:00Z"
}

会话类型 (Session Kinds)

OpenClaw 支持以下会话类型:

main

主对话会话,通常是用户与主代理的一对一交互。

  • 默认会话类型
  • 具有完整的工具和权限访问
  • 适用于日常对话和任务执行

group

群组会话,支持多个参与者。

  • 可以有多个用户和代理参与
  • 支持 displayName 和 channel 配置
  • 适用于团队协作场景

cron

定时任务会话,用于执行计划任务。

  • 按照设定的时间表自动触发
  • 适用于定期报告、监控等场景
  • 可配置执行频率和条件

hook

事件钩子会话,响应特定事件。

  • 由外部事件触发 (如 Git 提交、文件变化)
  • 支持自定义触发条件
  • 适用于事件驱动的自动化

node

节点会话,用于分布式和多代理场景。

  • 支持代理间的协调和通信
  • 可以形成代理网络
  • 适用于复杂的多步骤任务

沙箱与权限

沙箱代理的会话工具行为:

  • 默认可见性: 沙箱代理默认只能看到自己创建的子会话
  • 权限隔离: 不能访问主会话或其他代理的会话
  • 显式授权: 需要通过配置显式授予跨会话权限
{
  "agents": {
    "sandbox-agent": {
      "sandbox": true,
      "sessionPermissions": {
        "allowList": ["group-456"],  // 明确允许访问的会话
        "canSpawn": true,            // 允许创建新会话
        "canSend": ["main", "group"] // 允许向哪些类型的会话发送消息
      }
    }
  }
}

使用场景

场景1: 多代理协作

// 主代理创建专门的分析会话
{
  "name": "sessions_spawn",
  "input": {
    "kind": "node",
    "name": "数据分析节点"
  }
}

// 向分析会话发送任务
{
  "name": "sessions_send",
  "input": {
    "targetSession": "node-123",
    "message": "分析最近7天的用户行为数据"
  }
}

// 稍后查询结果
{
  "name": "sessions_history",
  "input": {
    "sessionId": "node-123",
    "limit": 10
  }
}

场景2: 群组通知

// 向团队群组发送任务完成通知
{
  "name": "sessions_send",
  "input": {
    "targetSession": "group-team",
    "message": "✅ 部署流程已完成，所有测试通过",
    "metadata": {
      "type": "notification",
      "severity": "success"
    }
  }
}

场景3: 定时报告

// Cron 会话自动生成报告并发送到主会话
{
  "name": "sessions_send",
  "input": {
    "targetSession": "main",
    "message": "📊 每日报告:\n\n- 新用户: 127\n- 活跃度: 85%\n- 系统健康: 正常"
  }
}

常用命令

# 在聊天中列出会话
/sessions list

# 查看会话历史
/sessions history <session-id>

# 向会话发送消息
/sessions send <session-id> "你的消息"

# 创建新会话
/sessions spawn --kind group --name "新群组"

# 通过 CLI 查看所有会话
openclaw session list

# 通过 CLI 查看会话详情
openclaw session info <session-id>

最佳实践

使用建议
  • 命名规范: 为会话使用清晰、描述性的名称
  • 权限最小化: 只授予必要的会话访问权限
  • 消息结构化: 使用 metadata 传递结构化信息
  • 历史管理: 定期检查和清理不活跃的会话
  • 错误处理: 处理会话不存在或权限不足的情况
提示
会话工具是实现多代理系统和自动化工作流的关键。合理使用这些工具可以构建复杂的代理协作网络。

相关概念