5.23 输入指示器

输入指示器 (Typing Indicators) 在代理运行期间显示活动状态,让用户了解代理正在处理任务。

核心概念

输入指示器提供视觉反馈,显示代理何时在"思考"或"输入"。

控制参数

• typingMode: 控制何时开始显示输入指示器
• typingIntervalSeconds: 控制刷新频率 (默认 6 秒)

输入模式

never

永不显示输入指示器。

{
  "agents": {
    "default": {
      "typingMode": "never"
    }
  }
}

适用场景:

• 批处理任务
• 后台运行的代理
• 不需要实时反馈的自动化流程

instant

立即显示输入指示器,在运行开始时就显示。

{
  "agents": {
    "default": {
      "typingMode": "instant"
    }
  }
}

适用场景:

• 交互式聊天
• 需要即时反馈的场景
• 用户期望快速响应的对话

thinking

在模型开始推理时显示输入指示器。

{
  "agents": {
    "default": {
      "typingMode": "thinking",
      "reasoningLevel": "stream"  // 需要启用推理流
    }
  }
}

message

在开始生成消息时显示输入指示器。

{
  "agents": {
    "default": {
      "typingMode": "message"
    }
  }
}

特殊行为:

• 忽略静默回复: 如果回复被标记为 silent,不会显示输入指示器
• 适用于需要在实际输出内容时才显示反馈的场景

刷新频率

控制输入指示器的更新频率:

{
  "agents": {
    "default": {
      "typingMode": "instant",
      "typingIntervalSeconds": 6  // 每 6 秒刷新一次 (默认值)
    }
  }
}

调整建议:

• 3-5 秒: 更频繁的反馈,适合快速交互
• 6-10 秒: 平衡性能和反馈,推荐默认值
• 10+ 秒: 减少服务器负载,适合长时间运行的任务

智能默认值

OpenClaw 根据会话类型和配置自动选择合适的默认值:

聊天类型

• 主对话: 默认 instant
• 群组对话: 默认 instant
• 心跳会话: 默认 never (心跳永不显示输入状态)
• Cron 任务: 默认 never

代理类型

• 交互式代理: 默认 instant
• 后台代理: 默认 never
• 沙箱代理: 继承父代理设置

配置示例

全局配置

{
  "agents": {
    "defaults": {
      "typingMode": "instant",
      "typingIntervalSeconds": 6
    }
  }
}

会话级配置

{
  "sessions": {
    "main": {
      "typingMode": "instant"
    },
    "background": {
      "typingMode": "never"
    }
  }
}

代理级配置

{
  "agents": {
    "chat-agent": {
      "typingMode": "instant",
      "typingIntervalSeconds": 5
    },
    "analysis-agent": {
      "typingMode": "thinking",
      "reasoningLevel": "stream"
    },
    "cron-agent": {
      "typingMode": "never"
    }
  }
}

动态覆盖

// 通过 API 动态设置
await openclaw.sendMessage("你好", {
  typingMode: "message",
  typingIntervalSeconds: 3
});

特殊情况

心跳会话

心跳会话永远不显示输入指示器,无论配置如何设置。

{
  "heartbeat": {
    "enabled": true,
    "interval": "55m"
    // 心跳会话自动使用 typingMode: "never"
  }
}

静默回复

当 typingMode: "message" 时,标记为 silent 的回复不会显示输入指示器。

// 代理返回静默回复
{
  "role": "assistant",
  "content": "...",
  "metadata": {
    "silent": true  // message 模式下不显示输入指示器
  }
}

推理模式要求

thinking 模式需要启用推理流:

{
  "agents": {
    "default": {
      "typingMode": "thinking",
      "reasoningLevel": "stream"  // 必需
    }
  }
}

如果 reasoningLevel 不是 "stream",输入指示器将不会显示。

用户体验考虑

选择合适的模式

刷新频率优化

• 低频率 (10+ 秒): 减少服务器负载,但用户可能感觉不够响应
• 中频率 (5-8 秒): 平衡性能和体验,推荐
• 高频率 (3-4 秒): 更好的反馈,但增加服务器压力

实现细节

输入指示器的工作原理:

1. 触发检查: 根据 typingMode 决定何时开始
2. 状态发送: 向前端发送"正在输入"状态
3. 定期刷新: 按照 typingIntervalSeconds 的间隔刷新状态
4. 停止条件: 运行完成或出错时停止

常用命令

# 查看当前配置
openclaw config get agents.defaults.typingMode

# 设置全局默认值
openclaw config set agents.defaults.typingMode instant

# 设置刷新频率
openclaw config set agents.defaults.typingIntervalSeconds 5

# 查看会话配置
openclaw session info <session-id>

最佳实践

相关概念

• 会话详解: 会话的整体管理机制
• Agent循环: 代理的执行流程
• 推理模式: 推理流与 thinking 模式的关系
• 命令队列: 命令排队时的输入指示器行为