@kirigaya/openclaw-onebot 1.0.0

package/skills/onebot-ops/receive.md

@@ -0,0 +1,85 @@
+# 消息接收规则
+
+## 私聊与群聊
+
+- **私聊 (private)**：所有消息 AI 都会回复
+- **群聊 (group)**：默认仅当用户 @ 机器人时 AI 才回复
+
+## 回复投递（deliver）
+
+Agent 的回复通过 deliver 自动发送，支持：
+- **text**：纯文本消息
+- **mediaUrl**：图片（`file://`、`http://`、`base64://`）
+- 无需 Agent 工具，Agent 输出即会送达
+
+## 使用 message 工具发送时
+
+若 Agent 调用 `message` 工具（action: send）发送消息或图片：
+- **target 必须使用 `ctx.To` 或 `ctx.ConversationLabel`**，二者在 OneBot 中均表示回复目标
+- **群聊**：target 为 `group:群号`（如 `group:1046693162`），**切勿使用 SenderId**（那是用户 QQ 号，会发到私聊）
+- **私聊**：target 为 `user:用户号` 或用户号
+
+## 表情回应（仿飞书，Lagrange/QQ NT）
+
+用户发消息后，会**立即**在用户的消息上添加表情回应（如点赞），让用户知道已收到。AI 回复完成后再取消该表情。使用 `set_msg_emoji_like` API，需 Lagrange.Core 等支持。可通过 `thinkingEmojiId` 配置，详见 [config.md](config.md)。
+
+## @ 逻辑
+
+可通过 `requireMention: false` 改为群聊全部回复，详见 [config.md](config.md)。
+
+## 新成员入群欢迎
+
+在 `openclaw.json` 中配置：
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "groupIncrease": {
+        "enabled": true,
+        "message": "欢迎 {name} 加入 {groupName}！"
+      }
+    }
+  }
+}
+```
+
+### 占位符（message 模板）
+
+| 占位符 | 说明 |
+|--------|------|
+| `{name}` | 新成员昵称（群名片或 QQ 昵称） |
+| `{userId}` | 新成员 QQ 号 |
+| `{groupName}` | 群名 |
+| `{groupId}` | 群号 |
+| `{avatarUrl}` | 新成员头像链接 |
+
+### 自定义 handler 脚本
+
+需要生成图片、调用外部 API 时，可配置 `handler` 路径（.mjs 或 .ts/.mts）：
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "groupIncrease": {
+        "enabled": true,
+        "handler": "./welcome.mjs"
+      }
+    }
+  }
+}
+```
+
+脚本接收上下文 `ctx`，返回 `{ text?, imagePath?, imageUrl? }`：
+
+```js
+// welcome.mjs 或 welcome.ts
+export default async function (ctx) {
+  // ctx: { groupId, groupName, userId, userName, avatarUrl }
+  // 可用 ctx.avatarUrl 获取头像，生成图片后写入文件
+  const path = "./welcome-out.png";
+  // ... 你的图片生成逻辑 ...
+  return { text: `欢迎 ${ctx.userName}！`, imagePath: path };
+}
+```

package/skills/onebot-ops/send.md

@@ -0,0 +1,39 @@
+# 发送消息（openclaw message send）
+
+通过 OpenClaw 的 `openclaw message send` CLI 主动发送消息，由 Channel outbound 处理，无需 Agent 工具。
+
+## 前置条件
+
+- Gateway 已启动：`openclaw gateway`
+- OneBot 渠道已配置并连接
+
+## target 格式
+
+| 格式 | 说明 |
+|------|------|
+| `user:123456789` | 私聊该 QQ 号 |
+| `group:987654321` | 群聊该群号 |
+| `123456789` | 纯数字且 > 100000000 时按用户处理，否则按群处理 |
+| `onebot:group:xxx` / `qq:user:xxx` | 支持 onebot/qq/lagrange 前缀 |
+
+## 发送文本
+
+```bash
+openclaw message send --channel onebot --target user:1193466151 --message "你好"
+openclaw message send --channel onebot --target group:123456789 --message "群公告内容"
+```
+
+## 发送图片（mediaUrl）
+
+`--media` 支持 `file://` 路径、`http://` URL 或 `base64://`：
+
+```bash
+openclaw message send --channel onebot --target user:1193466151 --media "file:///tmp/screenshot.png"
+openclaw message send --channel onebot --target group:123456789 --media "https://example.com/pic.jpg" --message "附带说明"
+```
+
+## 说明
+
+- **回复场景**（用户发消息 → Agent 回复）：由 deliver 自动处理，Agent 输出 text/mediaUrl 即会送达
+- **主动发送**（CLI 或工作流）：使用上述 `openclaw message send` 命令
+- 无 Agent 工具挂载，减少 token 消耗，提升扩展性