openclaw-plugin-yuanbao 2.13.1 → 2.13.3

package/README.md

@@ -1,58 +1,407 @@
-# openclaw-plugin-yuanbao
-
-[![npm version](https://img.shields.io/npm/v/openclaw-plugin-yuanbao.svg)](https://www.npmjs.com/package/openclaw-plugin-yuanbao)
-
-腾讯元宝智能机器人频道插件，让你的 OpenClaw 机器人能够接入元宝 Bot 通道，支持私聊和群聊。
-
-## ✨ 功能特性
-
-| 能力 | 描述 |
-|------|------|
-| 💬 群聊互动 | 在元宝派群组中，成员 @元宝Bot 即可触发 AI 回复 |
-| 🧠 长期记忆 | 记住与创建者的历史对话，越聊越懂你 |
-| ⏰ 随时在线 | 云端部署，7×24 小时在线服务派友 |
-| 🔍 联网搜索 | 自动接入 Web Search，回答实时信息 |
-
-## 🚀 快速开始
-
-### 1. 安装插件
-
-```bash
-openclaw plugins install openclaw-plugin-yuanbao
-```
-
-### 2. 配置通道
-
-```bash
-openclaw channels add
-```
-
-根据提示输入：
-- **AppID**: 元宝 APP 的 APP ID
-- **AppSecret**: 元宝 APP 的密钥
-
-### 3. 开始使用
-
-配置完成后，用户可以：
-- **私聊** - 直接向机器人发送消息
-- **群聊** - @机器人 或回复机器人消息触发对话
-
-## 🛠️ Bot 常用命令
-
-```
-/yuanbaobot-upgrade   # 升级元宝插件（需机器人主人权限）
-/issue-log            # 提交问题日志
-```
-
-## ❓ 常见问题
-
-### 连接失败
-- 检查 `AppID` 和 `AppSecret` 是否正确
-
-## 📚 相关文档
-- [元宝官网](https://yuanbao.tencent.com)
-
-## 🔧 系统要求
-
-- OpenClaw >= 2026.3.22
-- Node.js >= 18
+---
+summary: "Yuanbao bot overview, features, and configuration"
+read_when:
+  - You want to connect a Yuanbao bot
+  - You are configuring the Yuanbao channel
+title: Yuanbao
+---
+
+# Yuanbao
+
+Tencent Yuanbao is Tencent's AI assistant platform. The OpenClaw channel plugin
+connects Yuanbao bots to OpenClaw over WebSocket so they can interact with users
+through direct messages and group chats.
+
+**Status:** production-ready for bot DMs + group chats. WebSocket is the only supported connection mode.
+
+---
+
+## Quick start
+
+> **Requires OpenClaw 2026.4.10 or above.** Run `openclaw --version` to check. Upgrade with `openclaw update`.
+
+### 1. Add the Yuanbao channel with your credentials
+
+```bash
+openclaw channels add --channel yuanbao --token "appKey:appSecret"
+```
+
+The `--token` value uses colon-separated `appKey:appSecret` format. You can obtain these from the Yuanbao app by creating a robot in your application settings.
+
+### 2. Restart the gateway to apply the changes
+
+```bash
+openclaw gateway restart
+```
+
+### Interactive setup (alternative)
+
+You can also use the interactive wizard:
+
+```bash
+openclaw channels login --channel yuanbao
+```
+
+Follow the prompts to enter your App ID and App Secret.
+
+---
+
+## Access control
+
+### Direct messages
+
+Configure `dmPolicy` to control who can DM the bot:
+
+- `"pairing"` — unknown users receive a pairing code; approve via CLI
+- `"allowlist"` — only users listed in `allowFrom` can chat
+- `"open"` — allow all users (default)
+- `"disabled"` — disable all DMs
+
+**Approve a pairing request:**
+
+```bash
+openclaw pairing list yuanbao
+openclaw pairing approve yuanbao <CODE>
+```
+
+### Group chats
+
+**Mention requirement** (`channels.yuanbao.requireMention`):
+
+- `true` — require @mention (default)
+- `false` — respond without @mention
+
+Replying to the bot's message in a group chat is treated as an implicit mention.
+
+---
+
+## Configuration examples
+
+### Basic setup with open DM policy
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      appKey: "your_app_key",
+      appSecret: "your_app_secret",
+      dm: {
+        policy: "open",
+      },
+    },
+  },
+}
+```
+
+### Restrict DMs to specific users
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      appKey: "your_app_key",
+      appSecret: "your_app_secret",
+      dm: {
+        policy: "allowlist",
+        allowFrom: ["user_id_1", "user_id_2"],
+      },
+    },
+  },
+}
+```
+
+### Disable @mention requirement in groups
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      requireMention: false,
+    },
+  },
+}
+```
+
+### Optimize outbound message delivery
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      // Send each chunk immediately without buffering
+      outboundQueueStrategy: "immediate",
+    },
+  },
+}
+```
+
+### Tune merge-text strategy
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      outboundQueueStrategy: "merge-text",
+      minChars: 2800, // buffer until this many chars
+      maxChars: 3000, // force split above this limit
+      idleMs: 5000, // auto-flush after idle timeout (ms)
+    },
+  },
+}
+```
+
+---
+
+## Common commands
+
+| Command    | Description                 |
+| ---------- | --------------------------- |
+| `/help`    | Show available commands     |
+| `/status`  | Show bot status             |
+| `/new`     | Start a new session         |
+| `/stop`    | Stop the current run        |
+| `/restart` | Restart OpenClaw            |
+| `/compact` | Compact the session context |
+
+> Yuanbao supports native slash-command menus. Commands are synced to the platform automatically when the gateway starts.
+
+---
+
+## Troubleshooting
+
+### Bot does not respond in group chats
+
+1. Ensure the bot is added to the group
+2. Ensure you @mention the bot (required by default)
+3. Check logs: `openclaw logs --follow`
+
+### Bot does not receive messages
+
+1. Ensure the bot is created and approved in the Yuanbao app
+2. Ensure `appKey` and `appSecret` are correctly configured
+3. Ensure the gateway is running: `openclaw gateway status`
+4. Check logs: `openclaw logs --follow`
+
+### Bot sends empty or fallback replies
+
+1. Check if the AI model is returning valid content
+2. The default fallback reply is: "暂时无法解答，你可以换个问题问问我哦"
+3. Customize it via `channels.yuanbao.fallbackReply`
+
+### App Secret leaked
+
+1. Reset the App Secret in YuanBao APP
+2. Update the value in your config
+3. Restart the gateway: `openclaw gateway restart`
+
+---
+
+## Advanced configuration
+
+### Multiple accounts
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      defaultAccount: "main",
+      accounts: {
+        main: {
+          appKey: "key_xxx",
+          appSecret: "secret_xxx",
+          name: "Primary bot",
+        },
+        backup: {
+          appKey: "key_yyy",
+          appSecret: "secret_yyy",
+          name: "Backup bot",
+          enabled: false,
+        },
+      },
+    },
+  },
+}
+```
+
+`defaultAccount` controls which account is used when outbound APIs do not specify an `accountId`.
+
+### Message limits
+
+- `maxChars` — single message max character count (default: `3000` chars)
+- `mediaMaxMb` — media upload/download limit (default: `20` MB)
+- `overflowPolicy` — behavior when message exceeds limit: `"split"` (default) or `"stop"`
+
+### Streaming
+
+Yuanbao supports block-level streaming output. When enabled, the bot sends text in chunks as it generates.
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      disableBlockStreaming: false, // block streaming enabled (default)
+    },
+  },
+}
+```
+
+Set `disableBlockStreaming: true` to send the complete reply in one message.
+
+### Group chat history context
+
+Control how many historical messages are included in the AI context for group chats:
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      historyLimit: 100, // default: 100, set 0 to disable
+    },
+  },
+}
+```
+
+### Reply-to mode
+
+Control how the bot quotes messages when replying in group chats:
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      replyToMode: "first", // "off" | "first" | "all" (default: "first")
+    },
+  },
+}
+```
+
+| Value     | Behavior                                                 |
+| --------- | -------------------------------------------------------- |
+| `"off"`   | No quote reply                                           |
+| `"first"` | Quote only the first reply per inbound message (default) |
+| `"all"`   | Quote every reply                                        |
+
+### Markdown hint injection
+
+By default, the bot injects instructions in the system prompt to prevent the AI model from wrapping the entire reply in markdown code blocks.
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      markdownHintEnabled: true, // default: true
+    },
+  },
+}
+```
+
+### Debug mode
+
+Enable unsanitized log output for specific bot IDs:
+
+```json5
+{
+  channels: {
+    yuanbao: {
+      debugBotIds: ["bot_user_id_1", "bot_user_id_2"],
+    },
+  },
+}
+```
+
+### Multi-agent routing
+
+Use `bindings` to route Yuanbao DMs or groups to different agents.
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "main" },
+      { id: "agent-a", workspace: "/home/user/agent-a" },
+      { id: "agent-b", workspace: "/home/user/agent-b" },
+    ],
+  },
+  bindings: [
+    {
+      agentId: "agent-a",
+      match: {
+        channel: "yuanbao",
+        peer: { kind: "direct", id: "user_xxx" },
+      },
+    },
+    {
+      agentId: "agent-b",
+      match: {
+        channel: "yuanbao",
+        peer: { kind: "group", id: "group_zzz" },
+      },
+    },
+  ],
+}
+```
+
+Routing fields:
+
+- `match.channel`: `"yuanbao"`
+- `match.peer.kind`: `"direct"` (DM) or `"group"` (group chat)
+- `match.peer.id`: user ID or group code
+
+---
+
+## Configuration reference
+
+Full configuration: [Gateway configuration](/gateway/configuration)
+
+| Setting                                    | Description                                       | Default                                |
+| ------------------------------------------ | ------------------------------------------------- | -------------------------------------- |
+| `channels.yuanbao.enabled`                 | Enable/disable the channel                        | `true`                                 |
+| `channels.yuanbao.defaultAccount`          | Default account for outbound routing              | `default`                              |
+| `channels.yuanbao.accounts.<id>.appKey`    | App Key (used for signing and ticket generation)  | —                                      |
+| `channels.yuanbao.accounts.<id>.appSecret` | App Secret (used for signing)                     | —                                      |
+| `channels.yuanbao.accounts.<id>.token`     | Pre-signed token (skips automatic ticket signing) | —                                      |
+| `channels.yuanbao.accounts.<id>.name`      | Account display name                              | —                                      |
+| `channels.yuanbao.accounts.<id>.enabled`   | Enable/disable a specific account                 | `true`                                 |
+| `channels.yuanbao.dm.policy`               | DM policy                                         | `open`                                 |
+| `channels.yuanbao.dm.allowFrom`            | DM allowlist (user ID list)                       | —                                      |
+| `channels.yuanbao.requireMention`          | Require @mention in groups                        | `true`                                 |
+| `channels.yuanbao.overflowPolicy`          | Long message handling (`split` or `stop`)         | `split`                                |
+| `channels.yuanbao.replyToMode`             | Group reply-to strategy (`off`, `first`, `all`)   | `first`                                |
+| `channels.yuanbao.outboundQueueStrategy`   | Outbound strategy (`merge-text` or `immediate`)   | `merge-text`                           |
+| `channels.yuanbao.minChars`                | Merge-text: min chars to trigger send             | `2800`                                 |
+| `channels.yuanbao.maxChars`                | Merge-text: max chars per message                 | `3000`                                 |
+| `channels.yuanbao.idleMs`                  | Merge-text: idle timeout before auto-flush (ms)   | `5000`                                 |
+| `channels.yuanbao.mediaMaxMb`              | Media size limit (MB)                             | `20`                                   |
+| `channels.yuanbao.historyLimit`            | Group chat history context entries                | `100`                                  |
+| `channels.yuanbao.disableBlockStreaming`   | Disable block-level streaming output              | `false`                                |
+| `channels.yuanbao.fallbackReply`           | Fallback reply when AI returns no content         | `暂时无法解答，你可以换个问题问问我哦` |
+| `channels.yuanbao.markdownHintEnabled`     | Inject markdown anti-wrapping instructions        | `true`                                 |
+| `channels.yuanbao.debugBotIds`             | Debug whitelist bot IDs (unsanitized logs)        | `[]`                                   |
+
+---
+
+## Supported message types
+
+### Receive
+
+- ✅ Text
+- ✅ Images
+- ✅ Files
+- ✅ Audio / Voice
+- ✅ Video
+- ✅ Stickers / Custom emoji
+- ✅ Custom elements (link cards, etc.)
+
+### Send
+
+- ✅ Text (with markdown support)
+- ✅ Images
+- ✅ Files
+- ✅ Audio
+- ✅ Video
+- ✅ Stickers
+
+### Threads and replies
+
+- ✅ Quote replies (configurable via `replyToMode`)
+- ❌ Thread replies (not supported by platform)

package/dist/api.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Aggregated export file
+ * 供 index.ts 通过 loadBundledEntryExportSync 懒加载引用
+ */
 export { yuanbaoPlugin } from "./src/channel.js";
 export { yuanbaoSetupPlugin } from "./src/channel.setup.js";
 export { initLogger } from "./src/logger.js";

package/dist/api.js

@@ -1,3 +1,7 @@
+/**
+ * Aggregated export file
+ * 供 index.ts 通过 loadBundledEntryExportSync 懒加载引用
+ */
 export { yuanbaoPlugin } from "./src/channel.js";
 export { yuanbaoSetupPlugin } from "./src/channel.setup.js";
 export { initLogger } from "./src/logger.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 import { defineBundledChannelEntry, loadBundledEntryExportSync, } from "openclaw/plugin-sdk/channel-entry-contract";
 import { YUANBAO_PLUGIN_ID } from "./src/channel-shared.js";
+/** 懒加载注册工具 */
 function registerTools(api) {
     const register = loadBundledEntryExportSync(import.meta.url, {
         specifier: "./api.js",
@@ -7,6 +8,7 @@ function registerTools(api) {
     });
     register(api);
 }
+/** Lazy-load and register all slash commands */
 function registerCommands(api) {
     const yuanbaoUpgradeCommand = loadBundledEntryExportSync(import.meta.url, { specifier: "./api.js", exportName: "yuanbaoUpgradeCommand" });
     const yuanbaobotUpgradeCommand = loadBundledEntryExportSync(import.meta.url, { specifier: "./api.js", exportName: "yuanbaobotUpgradeCommand" });
@@ -15,6 +17,7 @@ function registerCommands(api) {
     api.registerCommand(yuanbaobotUpgradeCommand);
     api.registerCommand(logUploadCommandDefinition);
 }
+/** 懒加载初始化内置表情缓存 */
 function initBuiltinStickers() {
     const init = loadBundledEntryExportSync(import.meta.url, {
         specifier: "./api.js",
@@ -22,6 +25,7 @@ function initBuiltinStickers() {
     });
     init();
 }
+/** 懒加载初始化环境变量 */
 function initEnv(api) {
     const init = loadBundledEntryExportSync(import.meta.url, {
         specifier: "./api.js",
@@ -29,6 +33,7 @@ function initEnv(api) {
     });
     init(api);
 }
+/** 懒加载初始化日志 */
 function initLogger(api) {
     const init = loadBundledEntryExportSync(import.meta.url, {
         specifier: "./api.js",

package/dist/src/access/api.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Yuanbao API client.
+ *
+ * Backward-compatible re-export entry point.
+ * Implementation split into:
+ *   - http/request.ts  — Types, token cache, signing, auth headers, HTTP utilities
+ *   - http/main.ts     — Business APIs (uploadInfo / downloadUrl)
+ */
 export type { SignTokenData, AuthHeaders, CosUploadConfig, Log } from "./http/request.js";
 export { clearSignTokenCache, clearAllSignTokenCache, getTokenStatus, verifySignature, getSignToken, forceRefreshSignToken, getAuthHeaders, yuanbaoPost, yuanbaoGet, } from "./http/request.js";
 export { apiGetUploadInfo, apiGetDownloadUrl } from "./http/main.js";

package/dist/src/access/api.js

@@ -1,2 +1,10 @@
+/**
+ * Yuanbao API client.
+ *
+ * Backward-compatible re-export entry point.
+ * Implementation split into:
+ *   - http/request.ts  — Types, token cache, signing, auth headers, HTTP utilities
+ *   - http/main.ts     — Business APIs (uploadInfo / downloadUrl)
+ */
 export { clearSignTokenCache, clearAllSignTokenCache, getTokenStatus, verifySignature, getSignToken, forceRefreshSignToken, getAuthHeaders, yuanbaoPost, yuanbaoGet, } from "./http/request.js";
 export { apiGetUploadInfo, apiGetDownloadUrl } from "./http/main.js";

package/dist/src/access/http/bot-id-cache.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Lightweight botId cache shared between the HTTP sign-token client and
+ * account resolution.
+ *
+ * Kept in its own module (rather than inlined in `request.ts`) so that
+ * `accounts.ts` — which is on the `openclaw setup` / `openclaw configure`
+ * code path — can look up a previously-resolved botId without statically
+ * pulling in the full HTTP/crypto/env runtime stack.
+ */
+/** Read the last-known botId for an account, if any. */
 export declare function getCachedBotId(accountId: string): string | undefined;
+/** Record a botId obtained during sign-token exchange. */
 export declare function setCachedBotId(accountId: string, botId: string | undefined): void;
+/** Clear the cached botId (e.g. when tearing down an account). */
 export declare function clearCachedBotId(accountId: string): void;

package/dist/src/access/http/bot-id-cache.js

@@ -1,14 +1,26 @@
+/**
+ * Lightweight botId cache shared between the HTTP sign-token client and
+ * account resolution.
+ *
+ * Kept in its own module (rather than inlined in `request.ts`) so that
+ * `accounts.ts` — which is on the `openclaw setup` / `openclaw configure`
+ * code path — can look up a previously-resolved botId without statically
+ * pulling in the full HTTP/crypto/env runtime stack.
+ */
 const botIdCache = new Map();
+/** Read the last-known botId for an account, if any. */
 export function getCachedBotId(accountId) {
     const value = botIdCache.get(accountId);
     return value && value.length > 0 ? value : undefined;
 }
+/** Record a botId obtained during sign-token exchange. */
 export function setCachedBotId(accountId, botId) {
     if (!accountId || !botId) {
         return;
     }
     botIdCache.set(accountId, botId);
 }
+/** Clear the cached botId (e.g. when tearing down an account). */
 export function clearCachedBotId(accountId) {
     botIdCache.delete(accountId);
 }

package/dist/src/access/http/main.d.ts

@@ -1,4 +1,16 @@
+/**
+ * Yuanbao business API.
+ *
+ * Upload pre-sign config retrieval, resource download URL retrieval, etc.
+ * Auth and HTTP utilities are in request.ts.
+ */
 import type { ResolvedYuanbaoAccount } from "../../types.js";
 import type { Log, CosUploadConfig } from "./request.js";
+/**
+ * Get COS upload pre-sign config.
+ */
 export declare function apiGetUploadInfo(account: ResolvedYuanbaoAccount, fileName: string, fileId: string, log?: Log): Promise<CosUploadConfig>;
+/**
+ * Get COS download URL for a given resourceId.
+ */
 export declare function apiGetDownloadUrl(account: ResolvedYuanbaoAccount, resourceId: string, log?: Log): Promise<string>;

package/dist/src/access/http/main.js

@@ -1,6 +1,15 @@
+/**
+ * Yuanbao business API.
+ *
+ * Upload pre-sign config retrieval, resource download URL retrieval, etc.
+ * Auth and HTTP utilities are in request.ts.
+ */
 import { yuanbaoPost, yuanbaoGet } from "./request.js";
 const UPLOAD_INFO_PATH = "/api/resource/genUploadInfo";
 const DOWNLOAD_INFO_PATH = "/api/resource/v1/download";
+/**
+ * Get COS upload pre-sign config.
+ */
 export async function apiGetUploadInfo(account, fileName, fileId, log) {
     const data = await yuanbaoPost(account, UPLOAD_INFO_PATH, { fileName, fileId, docFrom: "localDoc", docOpenId: "" }, log);
     if (!data.bucketName || !data.location) {
@@ -8,6 +17,9 @@ export async function apiGetUploadInfo(account, fileName, fileId, log) {
     }
     return data;
 }
+/**
+ * Get COS download URL for a given resourceId.
+ */
 export async function apiGetDownloadUrl(account, resourceId, log) {
     const data = await yuanbaoGet(account, DOWNLOAD_INFO_PATH, { resourceId }, log);
     const downloadUrl = data.url ?? data.realUrl;

package/dist/src/access/http/request.d.ts

@@ -1,3 +1,4 @@
+/** Yuanbao HTTP request base layer — token cache, signature, auth headers, and HTTP utilities. */
 import type { ResolvedYuanbaoAccount } from "../../types.js";
 export { getCachedBotId } from "./bot-id-cache.js";
 export type SignTokenData = {