diff --git a/docs/zh-CN/channels/yuanbao.md b/docs/zh-CN/channels/yuanbao.md new file mode 100644 index 000000000..92d9b10e9 --- /dev/null +++ b/docs/zh-CN/channels/yuanbao.md @@ -0,0 +1,423 @@ +--- +read_when: + - 你想要连接一个 YuanBao 机器人 + - 你正在配置 YuanBao 渠道 +summary: YuanBao 机器人概览、功能和配置 +title: YuanBao +x-i18n: + generated_at: "2026-04-27T15:08:04Z" + model: gpt-5.4 + provider: openai + source_hash: 6a9177cba0fb64b9d47762450ff9ec7b0ae497ed0027f98f35dbd6b1bc252110 + source_path: channels/yuanbao.md + workflow: 15 +--- + +# YuanBao + +YuanBao 是腾讯的 AI 助手平台,支持通过即时消息进行机器人集成。机器人可以通过私信和群聊与用户互动。 + +**Status:** 机器人私信 + 群聊已可用于生产环境。WebSocket 是唯一受支持的连接模式。 + +--- + +## 快速开始 + +> **需要 OpenClaw 2026.4.10 或更高版本。** 运行 `openclaw --version` 进行检查。使用 `openclaw update` 升级。 + + + + ```bash + openclaw channels add --channel yuanbao --token "appKey:appSecret" + ``` + `--token` 的值使用以冒号分隔的 `appKey:appSecret` 格式。你可以在 YuanBao APP 中通过在应用设置里创建机器人来获取这些信息。 + + + + ```bash + openclaw gateway restart + ``` + + + +### 交互式设置(替代方式) + +你也可以使用交互式向导: + +```bash +openclaw channels login --channel yuanbao +``` + +按照提示输入你的 App ID 和 App Secret。 + +--- + +## 访问控制 + +### 私信 + +配置 `dmPolicy` 以控制谁可以向机器人发送私信: + +- `"pairing"` — 未知用户会收到配对码;通过 CLI 批准 +- `"allowlist"` — 只有列在 `allowFrom` 中的用户可以聊天 +- `"open"` — 允许所有用户(默认) +- `"disabled"` — 禁用所有私信 + +**批准配对请求:** + +```bash +openclaw pairing list yuanbao +openclaw pairing approve yuanbao +``` + +### 群聊 + +**提及要求**(`channels.yuanbao.requireMention`): + +- `true` — 需要 @提及(默认) +- `false` — 无需 @提及也会回复 + +在群聊中回复机器人的消息会被视为隐式提及。 + +--- + +## 配置示例 + +### 使用开放私信策略的基础设置 + +```json5 +{ + channels: { + yuanbao: { + appKey: "your_app_key", + appSecret: "your_app_secret", + dm: { + policy: "open", + }, + }, + }, +} +``` + +### 将私信限制为特定用户 + +```json5 +{ + channels: { + yuanbao: { + appKey: "your_app_key", + appSecret: "your_app_secret", + dm: { + policy: "allowlist", + allowFrom: ["user_id_1", "user_id_2"], + }, + }, + }, +} +``` + +### 在群组中禁用 @提及要求 + +```json5 +{ + channels: { + yuanbao: { + requireMention: false, + }, + }, +} +``` + +### 优化出站消息传递 + +```json5 +{ + channels: { + yuanbao: { + // 立即发送每个分块,不进行缓冲 + outboundQueueStrategy: "immediate", + }, + }, +} +``` + +### 调整 merge-text 策略 + +```json5 +{ + channels: { + yuanbao: { + outboundQueueStrategy: "merge-text", + minChars: 2800, // 缓冲直到达到这么多字符 + maxChars: 3000, // 超过此限制时强制拆分 + idleMs: 5000, // 空闲超时后自动刷新(毫秒) + }, + }, +} +``` + +--- + +## 常用命令 + +| Command | 描述 | +| ---------- | ---------------- | +| `/help` | 显示可用命令 | +| `/status` | 显示机器人状态 | +| `/new` | 开始一个新会话 | +| `/stop` | 停止当前运行 | +| `/restart` | 重启 OpenClaw | +| `/compact` | 压缩会话上下文 | + +> YuanBao 支持原生斜杠命令菜单。Gateway 网关启动时会自动将命令同步到平台。 + +--- + +## 故障排除 + +### 机器人在群聊中没有响应 + +1. 确保机器人已加入群组 +2. 确保你 @提及了机器人(默认要求) +3. 检查日志:`openclaw logs --follow` + +### 机器人没有收到消息 + +1. 确保机器人已在 YuanBao APP 中创建并通过审核 +2. 确保 `appKey` 和 `appSecret` 已正确配置 +3. 确保 Gateway 网关正在运行:`openclaw gateway status` +4. 检查日志:`openclaw logs --follow` + +### 机器人发送空回复或回退回复 + +1. 检查 AI 模型是否返回了有效内容 +2. 默认的回退回复是:“暂时无法解答,你可以换个问题问问我哦” +3. 可通过 `channels.yuanbao.fallbackReply` 自定义 + +### App Secret 泄露 + +1. 在 YuanBao APP 中重置 App Secret +2. 更新你配置中的值 +3. 重启 Gateway 网关:`openclaw gateway restart` + +--- + +## 高级配置 + +### 多账户 + +```json5 +{ + channels: { + yuanbao: { + defaultAccount: "main", + accounts: { + main: { + appKey: "key_xxx", + appSecret: "secret_xxx", + name: "主机器人", + }, + backup: { + appKey: "key_yyy", + appSecret: "secret_yyy", + name: "备用机器人", + enabled: false, + }, + }, + }, + }, +} +``` + +`defaultAccount` 控制在出站 API 未指定 `accountId` 时使用哪个账户。 + +### 消息限制 + +- `maxChars` — 单条消息的最大字符数(默认:`3000` 个字符) +- `mediaMaxMb` — 媒体上传/下载限制(默认:`20` MB) +- `overflowPolicy` — 消息超出限制时的行为:`"split"`(默认)或 `"stop"` + +### 流式传输 + +YuanBao 支持块级分块流式传输输出。启用后,机器人会在生成文本时按块发送。 + +```json5 +{ + channels: { + yuanbao: { + disableBlockStreaming: false, // 启用分块流式传输(默认) + }, + }, +} +``` + +设置 `disableBlockStreaming: true` 可在一条消息中发送完整回复。 + +### 群聊历史上下文 + +控制在群聊的 AI 上下文中包含多少条历史消息: + +```json5 +{ + channels: { + yuanbao: { + historyLimit: 100, // 默认:100,设置为 0 可禁用 + }, + }, +} +``` + +### 回复模式 + +控制机器人在群聊中回复时如何引用消息: + +```json5 +{ + channels: { + yuanbao: { + replyToMode: "first", // "off" | "first" | "all"(默认:"first") + }, + }, +} +``` + +| Value | 行为 | +| --------- | ------------------------------------------------ | +| `"off"` | 不进行引用回复 | +| `"first"` | 每条入站消息仅对第一条回复进行引用(默认) | +| `"all"` | 引用每一条回复 | + +### Markdown 提示注入 + +默认情况下,机器人会在系统提示中注入说明,以防止 AI 模型将整个回复包裹在 markdown 代码块中。 + +```json5 +{ + channels: { + yuanbao: { + markdownHintEnabled: true, // 默认:true + }, + }, +} +``` + +### 调试模式 + +为特定机器人 ID 启用未清洗的日志输出: + +```json5 +{ + channels: { + yuanbao: { + debugBotIds: ["bot_user_id_1", "bot_user_id_2"], + }, + }, +} +``` + +### 多智能体路由 + +使用 `bindings` 将 YuanBao 私信或群组路由到不同智能体。 + +```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" }, + }, + }, + ], +} +``` + +路由字段: + +- `match.channel`:`"yuanbao"` +- `match.peer.kind`:`"direct"`(私信)或 `"group"`(群聊) +- `match.peer.id`:用户 ID 或群组代码 + +--- + +## 配置参考 + +完整配置:[Gateway 网关配置](/zh-CN/gateway/configuration) + +| Setting | 描述 | 默认值 | +| ------------------------------------------ | -------------------------------------------- | -------------------------------------- | +| `channels.yuanbao.enabled` | 启用/禁用该渠道 | `true` | +| `channels.yuanbao.defaultAccount` | 用于出站路由的默认账户 | `default` | +| `channels.yuanbao.accounts..appKey` | App Key(用于签名和票据生成) | — | +| `channels.yuanbao.accounts..appSecret` | App Secret(用于签名) | — | +| `channels.yuanbao.accounts..token` | 预签名 token(跳过自动票据签名) | — | +| `channels.yuanbao.accounts..name` | 账户显示名称 | — | +| `channels.yuanbao.accounts..enabled` | 启用/禁用特定账户 | `true` | +| `channels.yuanbao.dm.policy` | 私信策略 | `open` | +| `channels.yuanbao.dm.allowFrom` | 私信允许列表(用户 ID 列表) | — | +| `channels.yuanbao.requireMention` | 在群组中要求 @提及 | `true` | +| `channels.yuanbao.overflowPolicy` | 长消息处理方式(`split` 或 `stop`) | `split` | +| `channels.yuanbao.replyToMode` | 群组 reply-to 策略(`off`、`first`、`all`) | `first` | +| `channels.yuanbao.outboundQueueStrategy` | 出站策略(`merge-text` 或 `immediate`) | `merge-text` | +| `channels.yuanbao.minChars` | merge-text:触发发送的最小字符数 | `2800` | +| `channels.yuanbao.maxChars` | merge-text:每条消息的最大字符数 | `3000` | +| `channels.yuanbao.idleMs` | merge-text:自动刷新的空闲超时(毫秒) | `5000` | +| `channels.yuanbao.mediaMaxMb` | 媒体大小限制(MB) | `20` | +| `channels.yuanbao.historyLimit` | 群聊历史上下文条目数 | `100` | +| `channels.yuanbao.disableBlockStreaming` | 禁用块级分块流式传输输出 | `false` | +| `channels.yuanbao.fallbackReply` | 当 AI 未返回内容时的回退回复 | `暂时无法解答,你可以换个问题问问我哦` | +| `channels.yuanbao.markdownHintEnabled` | 注入防止 markdown 包裹的提示说明 | `true` | +| `channels.yuanbao.debugBotIds` | 调试白名单机器人 ID(未清洗日志) | `[]` | + +--- + +## 支持的消息类型 + +### 接收 + +- ✅ 文本 +- ✅ 图片 +- ✅ 文件 +- ✅ 音频 / 语音 +- ✅ 视频 +- ✅ 贴纸 / 自定义表情 +- ✅ 自定义元素(链接卡片等) + +### 发送 + +- ✅ 文本(支持 markdown) +- ✅ 图片 +- ✅ 文件 +- ✅ 音频 +- ✅ 视频 +- ✅ 贴纸 + +### 线程和回复 + +- ✅ 引用回复(可通过 `replyToMode` 配置) +- ❌ 线程回复(平台不支持) + +--- + +## 相关内容 + +- [渠道概览](/zh-CN/channels) — 所有受支持的渠道 +- [配对](/zh-CN/channels/pairing) — 私信身份验证和配对流程 +- [群组](/zh-CN/channels/groups) — 群聊行为和提及门控 +- [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由 +- [安全](/zh-CN/gateway/security) — 访问模型和加固 diff --git a/docs/zh-CN/plugins/community.md b/docs/zh-CN/plugins/community.md index 27872937e..7d521949b 100644 --- a/docs/zh-CN/plugins/community.md +++ b/docs/zh-CN/plugins/community.md @@ -5,37 +5,32 @@ read_when: summary: 社区维护的 OpenClaw 插件:浏览、安装并提交你自己的插件 title: 社区插件 x-i18n: - generated_at: "2026-04-26T00:16:04Z" + generated_at: "2026-04-27T15:08:03Z" model: gpt-5.4 provider: openai - source_hash: 3af2f0be5e5e75fe26a58576e6f44bce52a1ff8d597f86cafd8fb893f6c6b8f4 + source_hash: 3b9c92e8f2e592bbbdbaa8d3f354d176f1600354f6438f137dbe01c01c6f5603 source_path: plugins/community.md workflow: 15 --- -社区插件是用于扩展 OpenClaw 的第三方软件包,可添加新的 -渠道、工具、提供商或其他能力。它们由社区构建和维护,发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm,并且 -可通过一条命令安装。 +社区插件是第三方软件包,可通过新的渠道、工具、提供商或其他能力扩展 OpenClaw。它们由社区构建和维护,发布在 [ClawHub](/zh-CN/tools/clawhub) 或 npm 上,并且只需一条命令即可安装。 -ClawHub 是社区插件的权威发现入口。不要仅仅为了让你的插件能在这里被发现而提交只改文档的 PR;请改为将它发布到 -ClawHub。 +ClawHub 是社区插件的权威发现入口。不要仅仅为了让你的插件更容易被发现而提交只改文档的 PR;请改为将它发布到 ClawHub。 ```bash openclaw plugins install ``` -OpenClaw 会先检查 ClawHub,并自动回退到 npm。 +OpenClaw 会先检查 ClawHub,并在需要时自动回退到 npm。 ## 已列出的插件 ### Apify -使用 20,000 多个现成爬虫从任意网站抓取数据。只需提出请求,你的智能体 -就能从 Instagram、Facebook、TikTok、YouTube、Google Maps、Google -Search、电商网站等提取数据。 +使用 20,000 多个现成爬虫从任何网站抓取数据。让你的智能体仅通过提问,就能从 Instagram、Facebook、TikTok、YouTube、Google Maps、Google Search、电商网站等提取数据。 -- **npm:** `@apify/apify-openclaw-plugin` -- **repo:** [github.com/apify/apify-openclaw-plugin](https://github.com/apify/apify-openclaw-plugin) +- **npm:** `@apify/apify-openclaw-plugin` +- **仓库:** [github.com/apify/apify-openclaw-plugin](https://github.com/apify/apify-openclaw-plugin) ```bash openclaw plugins install @apify/apify-openclaw-plugin @@ -43,11 +38,10 @@ openclaw plugins install @apify/apify-openclaw-plugin ### Codex App Server Bridge -面向 Codex App Server 对话的独立 OpenClaw 桥接插件。将聊天绑定到 -Codex 线程,使用纯文本与其交流,并通过聊天原生命令控制恢复、规划、审查、模型选择、压缩等功能。 +面向 Codex App Server 对话的独立 OpenClaw 桥接插件。你可以将聊天绑定到一个 Codex 线程,通过纯文本与其交互,并使用聊天原生命令控制恢复、规划、审查、模型选择、压缩等功能。 -- **npm:** `openclaw-codex-app-server` -- **repo:** [github.com/pwrdrvr/openclaw-codex-app-server](https://github.com/pwrdrvr/openclaw-codex-app-server) +- **npm:** `openclaw-codex-app-server` +- **仓库:** [github.com/pwrdrvr/openclaw-codex-app-server](https://github.com/pwrdrvr/openclaw-codex-app-server) ```bash openclaw plugins install openclaw-codex-app-server @@ -55,11 +49,10 @@ openclaw plugins install openclaw-codex-app-server ### DingTalk -使用 Stream 模式的企业机器人集成。支持通过任意 DingTalk 客户端发送文本、图片和 -文件消息。 +使用 Stream 模式的企业机器人集成。支持通过任意 DingTalk 客户端发送文本、图片和文件消息。 -- **npm:** `@largezhou/ddingtalk` -- **repo:** [github.com/largezhou/openclaw-dingtalk](https://github.com/largezhou/openclaw-dingtalk) +- **npm:** `@largezhou/ddingtalk` +- **仓库:** [github.com/largezhou/openclaw-dingtalk](https://github.com/largezhou/openclaw-dingtalk) ```bash openclaw plugins install @largezhou/ddingtalk @@ -67,11 +60,10 @@ openclaw plugins install @largezhou/ddingtalk ### Lossless Claw (LCM) -面向 OpenClaw 的无损上下文管理插件。基于 DAG 的会话摘要 -和增量压缩——在减少 token 使用量的同时保留完整上下文保真度。 +适用于 OpenClaw 的无损上下文管理插件。基于 DAG 的对话摘要与增量压缩,在减少 token 使用量的同时保留完整上下文保真度。 -- **npm:** `@martian-engineering/lossless-claw` -- **repo:** [github.com/Martian-Engineering/lossless-claw](https://github.com/Martian-Engineering/lossless-claw) +- **npm:** `@martian-engineering/lossless-claw` +- **仓库:** [github.com/Martian-Engineering/lossless-claw](https://github.com/Martian-Engineering/lossless-claw) ```bash openclaw plugins install @martian-engineering/lossless-claw @@ -79,11 +71,10 @@ openclaw plugins install @martian-engineering/lossless-claw ### Opik -将智能体追踪导出到 Opik 的官方插件。可监控智能体行为、 -成本、token、错误等。 +将智能体追踪导出到 Opik 的官方插件。可监控智能体行为、成本、token、错误等。 -- **npm:** `@opik/opik-openclaw` -- **repo:** [github.com/comet-ml/opik-openclaw](https://github.com/comet-ml/opik-openclaw) +- **npm:** `@opik/opik-openclaw` +- **仓库:** [github.com/comet-ml/opik-openclaw](https://github.com/comet-ml/opik-openclaw) ```bash openclaw plugins install @opik/opik-openclaw @@ -91,12 +82,10 @@ openclaw plugins install @opik/opik-openclaw ### Prometheus Avatar -为你的 OpenClaw 智能体提供一个具有实时口型同步、情绪 -表情和文本转语音功能的 Live2D 虚拟形象。包含用于 AI 资产生成的创作者工具, -以及一键部署到 Prometheus Marketplace 的能力。目前处于 alpha 阶段。 +为你的 OpenClaw 智能体赋予一个带有实时唇形同步、情绪表情和文本转语音能力的 Live2D 虚拟形象。包含用于 AI 资产生成的创作者工具,以及一键部署到 Prometheus Marketplace 的功能。目前处于 alpha 阶段。 -- **npm:** `@prometheusavatar/openclaw-plugin` -- **repo:** [github.com/myths-labs/prometheus-avatar](https://github.com/myths-labs/prometheus-avatar) +- **npm:** `@prometheusavatar/openclaw-plugin` +- **仓库:** [github.com/myths-labs/prometheus-avatar](https://github.com/myths-labs/prometheus-avatar) ```bash openclaw plugins install @prometheusavatar/openclaw-plugin @@ -104,16 +93,12 @@ openclaw plugins install @prometheusavatar/openclaw-plugin ### QQbot -通过 QQ Bot API 将 OpenClaw 连接到 QQ。支持私聊、群组 -提及、渠道消息,以及包括语音、图片、视频 -和文件在内的富媒体。 +通过 QQ Bot API 将 OpenClaw 连接到 QQ。支持私聊、群组提及、频道消息,以及语音、图片、视频和文件等富媒体内容。 -当前的 OpenClaw 版本已内置 QQ Bot。正常安装请使用 -[QQ Bot](/zh-CN/channels/qqbot) 中的内置设置;仅当你明确希望使用腾讯维护的独立软件包时, -才安装这个外部插件。 +当前的 OpenClaw 版本已内置 QQ Bot。正常安装时,请使用 [QQ Bot](/zh-CN/channels/qqbot) 中的内置设置;只有在你明确想使用腾讯维护的独立软件包时,才安装这个外部插件。 -- **npm:** `@tencent-connect/openclaw-qqbot` -- **repo:** [github.com/tencent-connect/openclaw-qqbot](https://github.com/tencent-connect/openclaw-qqbot) +- **npm:** `@tencent-connect/openclaw-qqbot` +- **仓库:** [github.com/tencent-connect/openclaw-qqbot](https://github.com/tencent-connect/openclaw-qqbot) ```bash openclaw plugins install @tencent-connect/openclaw-qqbot @@ -121,43 +106,47 @@ openclaw plugins install @tencent-connect/openclaw-qqbot ### wecom -由腾讯 WeCom 团队开发的 OpenClaw WeCom 渠道插件。基于 -WeCom Bot WebSocket 持久连接, -支持私信和群聊、流式回复、主动消息发送、图片/文件处理、Markdown -格式化、内置访问控制,以及文档/会议/消息技能。 +由腾讯企业微信团队提供的 OpenClaw WeCom 渠道插件。基于 WeCom Bot WebSocket 长连接,支持私信和群聊、流式回复、主动消息发送、图片/文件处理、Markdown 格式化、内置访问控制,以及文档/会议/消息相关 Skills。 -- **npm:** `@wecom/wecom-openclaw-plugin` -- **repo:** [github.com/WecomTeam/wecom-openclaw-plugin](https://github.com/WecomTeam/wecom-openclaw-plugin) +- **npm:** `@wecom/wecom-openclaw-plugin` +- **仓库:** [github.com/WecomTeam/wecom-openclaw-plugin](https://github.com/WecomTeam/wecom-openclaw-plugin) ```bash openclaw plugins install @wecom/wecom-openclaw-plugin ``` +### Yuanbao + +由腾讯元宝团队提供的 OpenClaw Yuanbao 渠道插件。基于 WebSocket 长连接,支持私信和群聊、流式回复、主动消息发送、图片/文件/音频/视频处理、Markdown 格式化、内置访问控制以及斜杠命令菜单。 + +- **npm:** `openclaw-plugin-yuanbao` +- **仓库:** [github.com/yb-claw/openclaw-plugin-yuanbao](https://github.com/yb-claw/openclaw-plugin-yuanbao) + +```bash +openclaw plugins install openclaw-plugin-yuanbao +``` + ## 提交你的插件 -我们欢迎实用、有文档并且可安全运行的社区插件。 +我们欢迎实用、有文档且可安全运行的社区插件。 - - 你的插件必须可通过 `openclaw plugins install \` 安装。 - 发布到 [ClawHub](/zh-CN/tools/clawhub)(推荐)或 npm。 - 完整指南请参见[构建插件](/zh-CN/plugins/building-plugins)。 + + 你的插件必须可以通过 `openclaw plugins install \` 安装。 + 请发布到 [ClawHub](/zh-CN/tools/clawhub)(推荐)或 npm。 + 完整指南请参阅 [构建插件](/zh-CN/plugins/building-plugins)。 - - 源代码必须位于带有设置文档和 issue - 跟踪器的公开仓库中。 + + 源代码必须位于带有设置文档和 issue 跟踪器的公开仓库中。 - - 你不需要仅为了让你的插件可被发现而提交文档 PR。请改为将它发布到 - ClawHub。 + + 你不需要仅为了让插件可被发现而提交文档 PR。请改为将它发布到 ClawHub。 - 只有当 OpenClaw 的源文档确实需要内容 - 更改时,才提交文档 PR,例如更正安装指引,或添加属于主文档集的 - 跨仓库文档。 + 只有当 OpenClaw 的源文档确实需要内容变更时,才应提交文档 PR,例如更正安装指引,或添加属于主文档集的跨仓库文档。 @@ -167,11 +156,11 @@ openclaw plugins install @wecom/wecom-openclaw-plugin | 要求 | 原因 | | --------------------------- | --------------------------------------------- | | 发布到 ClawHub 或 npm | 用户需要 `openclaw plugins install` 能正常工作 | -| 公开的 GitHub 仓库 | 便于审查源码、跟踪 issue,并保证透明度 | +| 公开的 GitHub 仓库 | 便于审查源码、跟踪问题并提升透明度 | | 设置和使用文档 | 用户需要知道如何配置它 | -| 持续维护 | 有近期更新或能及时响应 issue 处理 | +| 持续维护 | 近期有更新,或能及时响应 issue 处理 | -低质量封装、归属不明确或无人维护的软件包可能会被拒绝。 +低质量封装、归属不清或无人维护的软件包可能会被拒绝。 ## 相关内容