消息
Messages（消息）是用户与 Agent 之间通信的基本单位。OpenClaw 统一处理来自不同渠道的各类消息格式。
消息类型
OpenClaw 支持以下消息类型：
| 类型 | 标识 | 说明 |
|---|---|---|
| 文本 | text | 纯文本或 Markdown 格式 |
| 图片 | image | JPEG、PNG、WebP、GIF |
| 语音 | voice | OGG、MP3、WAV 音频 |
| 视频 | video | MP4、WebM 视频 |
| 文档 | document | PDF、DOCX、TXT 等文件 |
| 位置 | location | 经纬度坐标 |
内部消息格式
所有渠道的消息被标准化为统一的内部格式：
typescript
interface Message {
id: string // 消息唯一 ID
type: MessageType // 消息类型
content: string // 文本内容
sender: {
id: string // 发送者 ID
name: string // 发送者名称
channel: string // 来源渠道
}
media?: {
url: string // 媒体文件 URL
mimeType: string // MIME 类型
size: number // 文件大小（字节）
}
timestamp: number // Unix 时间戳（毫秒）
metadata?: Record<string, unknown>
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
消息生命周期
一条消息从接收到回复的完整流程：
接收 预处理 Agent 处理 回复
Received → Preprocessed → Agent Loop → Response
│ │ │ │
▼ ▼ ▼ ▼
渠道适配器 格式标准化 LLM 调用 渠道格式化
收到原始消息 转换内部格式 生成回复 转换平台格式1
2
3
4
5
6
2
3
4
5
6
1. 接收（Received）
Channel Adapter（渠道适配器）从平台 API 或 WebSocket 接收原始消息。
2. 预处理（Preprocessed）
- 将平台特有格式转换为 OpenClaw 内部格式
- 处理媒体文件下载与缓存
- 语音消息自动转录（Speech-to-Text）
- 应用消息过滤规则
语音转录
语音消息会自动转录为文本，原始音频保留在 media 字段中。转录使用配置的 STT（Speech-to-Text）模型。
3. Agent 处理
消息进入 Agent Loop 的 五阶段流水线，LLM 生成回复。
4. 回复（Response）
Agent 的回复经过渠道格式化后发送给用户。
渠道特定格式
不同渠道对消息格式有不同的支持和限制：
markdown
- 支持基本文本格式（粗体、斜体）
- 图片最大 16MB
- 语音消息自动转 OGG Opus
- 不支持流式输出
- 消息长度限制 65536 字符1
2
3
4
5
2
3
4
5
markdown
- 支持 Markdown / HTML 格式
- 图片最大 10MB
- 支持内联键盘（Inline Keyboard）
- 支持流式编辑消息
- 消息长度限制 4096 字符1
2
3
4
5
2
3
4
5
markdown
- 支持 Markdown 格式
- 支持嵌入（Embed）富文本
- 支持斜杠命令（Slash Commands）
- 消息长度限制 2000 字符
- 支持线程（Thread）回复1
2
3
4
5
2
3
4
5
消息长度
超出渠道长度限制的回复会被自动分割为多条消息发送。分割点优先选择段落边界。
富媒体处理
图片处理
用户发送图片
│
▼
下载并缓存 → 检查模型是否支持视觉
│ │
▼ ▼
[支持] 直接发送 [不支持] OCR/描述
给多模态模型 转换为文本注入1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
语音处理
用户发送语音
│
▼
下载音频 → STT 转录 → 文本注入上下文
│
▼
转录结果附加到消息1
2
3
4
5
6
7
2
3
4
5
6
7
文档处理
支持的文档格式：
- PDF — 提取文本与表格
- DOCX — 提取富文本内容
- TXT/CSV — 直接读取
- 代码文件 — 语法高亮注入
消息队列
消息按渠道和会话进入队列处理：
Channel Queue → Session Queue → Agent Loop
渠道队列 会话队列 Agent 处理1
2
2
- 每个 Session 维护独立的消息队列
- 队列保证消息按序处理
- 队列溢出时按 steering 模式 处理
队列模式
steer 模式逐条处理；collect 模式在时间窗口内批量收集；followup 模式将后续消息追加到当前上下文。
消息元数据
每条消息可携带渠道特定的元数据（Metadata）：
json
{
"metadata": {
"telegram": {
"chatType": "private",
"replyToMessageId": "12345"
},
"whatsapp": {
"isForwarded": true,
"quotedMessage": "原始消息内容"
}
}
}1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
下一步
- 了解 会话管理 中消息的组织方式
- 查看 Markdown 格式化 了解输出渲染
- 探索 流式输出 的实时传输机制