OpenClaw 会话技能

你现在拥有在 Talk Robots 会话中识别当前用户身份，并通过 Robot 消息接口把文本或文件事件投递给指定聊聊机器人的能力。当用户要求“记住我是谁”、“给我发个消息”、“通知我”、“给我发送文件”，或者你在后台完成了一项长耗时任务需要回推结果时，请使用此技能。

OpenClaw 会自动管理会话身份标识，但发送 Robot 消息时仍必须使用当前会话的 cvs_id。

⚠️ 重要: 发送消息时必须使用用户上下文中明确指出的 cvs_id（严格区分大小写），不要从 session key 中提取（session key 会被小写化，导致投递失败）。

推荐发送方式：shell/robot_send.sh

本技能目录提供了辅助脚本 shell/robot_send.sh。当运行环境允许执行 shell 时，优先使用该脚本发送与你聊聊文本消息或文件消息，不要手写签名或手动拼接 /robot/send 请求。

该脚本会自动完成：

• 生成 msg_id、noncestr、timestamp
• 按 Talk Robots /robot/send 规则生成 HMAC-SHA256 sign
• 文本消息使用完整 imx.Msg JSON 结构
• 文件消息使用 multipart/form-data
• 支持 --refer-msg-id、--at、--mentioned、--dry-run

发送前必须确认以下值均有效：

• robot_endpoint / TALK_ROBOT_ENDPOINT
• robot_id / TALK_ROBOT_ID
• robot_key / TALK_ROBOT_KEY
• 当前会话 cvs_id

使用脚本发送文本消息

./shell/robot_send.sh text \
  --base-url "{{robot_endpoint}}" \
  --robot-id "{{robot_id}}" \
  --robot-key "{{robot_key}}" \
  --cvs-id "{{cvs_id}}" \
  --content "你好，你交代的任务已经处理完成。"

使用脚本发送文件消息

./shell/robot_send.sh file \
  --base-url "{{robot_endpoint}}" \
  --robot-id "{{robot_id}}" \
  --robot-key "{{robot_key}}" \
  --cvs-id "{{cvs_id}}" \
  --content "请查看附件" \
  --file "./report.pdf"

发送前预检

不确定参数或签名是否正确时，先使用 --dry-run 查看请求内容，不要实际发送：

./shell/robot_send.sh text \
  --base-url "{{robot_endpoint}}" \
  --robot-id "{{robot_id}}" \
  --robot-key "{{robot_key}}" \
  --cvs-id "{{cvs_id}}" \
  --content "测试消息" \
  --dry-run

Robot 消息接口说明

如果不能使用 shell/robot_send.sh，再按下面的协议直接调用 Robot 消息接口。

配置项：

• robot_endpoint - Talk Robots 服务端点地址（在 OpenClaw 技能配置中设置）
• robot_id - 机器人 ID（在 OpenClaw 技能配置中设置）
• robot_key - 机器人密钥（在 OpenClaw 技能配置中设置）

发送消息时，系统需要生成 msg_id、noncestr、timestamp，并将 msg_id、noncestr、robot_id、timestamp 按 key 字典序排序、value URL encode 后拼接成签名原文，再使用 robot_key 做 HMAC-SHA256 生成 sign。最终 URL 形如：{{robot_endpoint}}?robot_id=...&noncestr=...&timestamp=...&msg_id=...&sign=...。

发送文本事件

• Endpoint: {{robot_endpoint}}
• Method: POST
• Content-Type: application/json
• Payload (JSON):
  • cmd: 固定为 msg
  • head.msg_id: 消息 ID，需与 URL 中 msg_id 一致
  • head.cvs_id: 目标会话 ID，必填
  • head.refer_msg_id: 可选，引用消息 ID
  • body.content: 要投递的文本内容

请求体示例：

{
  "cmd": "msg",
  "head": {
    "msg_id": "msg-001",
    "cvs_id": "cvs-123",
    "refer_msg_id": "refer-msg-id"
  },
  "body": {
    "content": "你好，你交代的任务已经处理完成。"
  }
}

发送文件事件

• Endpoint: {{robot_endpoint}}
• Method: POST
• Content-Type: multipart/form-data
• Form Fields:
  • msg_id: 消息 ID，需与 URL 中 msg_id 一致
  • cvs_id: 目标会话 ID，必填
  • file: 文件二进制内容
  • content: 可选，文件说明文本
  • refer_msg_id: 可选，引用消息 ID

注意：文件上传必须使用 multipart/form-data，不能使用 JSON 直接嵌入文件内容。

操作规范 (Rules)

1. 身份约束：OpenClaw 会自动管理当前用户的身份标识；引用历史上下文时，只能基于当前会话，不能混用其他会话记忆。
2. 前置检查：在投递消息前，务必先确认技能配置中已提供有效的 robot_endpoint、robot_id、robot_key 和当前会话 cvs_id。如果没有，请直接告知调用方当前缺少配置。
3. 优先脚本：当 shell 可用时，优先使用 shell/robot_send.sh 发送文本或文件；只有脚本不可用时才手动构造 /robot/send 请求。
4. 文本发送：发送纯文本时，请严格使用完整 imx.Msg JSON 结构：cmd=msg、head.msg_id、head.cvs_id、body.content。
5. 文件发送：发送文件时，请严格使用 multipart/form-data，并通过 file 字段上传文件，不要用 JSON 嵌入文件内容。
6. 会话 ID：无论用脚本还是手动请求，都必须显式传入当前会话 cvs_id，且大小写必须保持原样。
7. 投递语义：/robot/send 是把事件投递给目标 robot，不是直接绕过机器人给聊聊会话发消息；最终是否回发由机器人脚本逻辑决定。
8. 内容风格：默认使用自然、简洁的中文与用户沟通，除非用户明确要求其他语言。
9. 错误处理：如果缺少必要上下文、robot 消息配置无效，或调用协议不明确，请明确指出缺失项，不要自行猜测。
10. 禁止事项：不要虚构用户资料、历史记忆、robot 消息参数或接口协议。

示例 (Example)

当你需要在任务完成后通知当前用户时，推荐直接调用辅助脚本。

文本消息示例

./shell/robot_send.sh text \
  --base-url "{{config.robot_endpoint}}" \
  --robot-id "{{config.robot_id}}" \
  --robot-key "{{config.robot_key}}" \
  --cvs-id "{{cvs_id}}" \
  --content "你好，你交代的任务已经处理完成，我现在把结果同步给你。"

文件消息示例

./shell/robot_send.sh file \
  --base-url "{{config.robot_endpoint}}" \
  --robot-id "{{config.robot_id}}" \
  --robot-key "{{config.robot_key}}" \
  --cvs-id "{{cvs_id}}" \
  --content "请查看附件" \
  --file "./report.pdf"

手动文本请求示例（脚本不可用时）

{
  "cmd": "msg",
  "head": {
    "msg_id": "msg-001",
    "cvs_id": "cvs-123"
  },
  "body": {
    "content": "你好，你交代的任务已经处理完成，我现在把结果同步给你。"
  }
}

手动文件请求示例（脚本不可用时）

curl -X POST "{{config.robot_endpoint}}?robot_id={{config.robot_id}}&noncestr={{nonce}}&timestamp={{timestamp}}&msg_id={{msg_id}}&sign={{sign}}" \
  -F "msg_id={{msg_id}}" \
  -F "cvs_id={{cvs_id}}" \
  -F "content=请查看附件" \
  -F "file=@./report.pdf"