realvco Docs

騰訊元寶（Yuanbao）連接教學

騰訊元寶是騰訊推出的協作平台，主要服務中華區市場（中國大陸、香港、澳門）。如果你的客戶或團隊主要在這個區域，元寶是接觸他們的自然選擇 — Telegram / Discord / WhatsApp 在這些地區受網路限制，元寶反而是首選。

Hermes v0.12 開始原生支援元寶（native adapter，比 Teams 的 plugin 機制更直接），設定只需要一組 API 金鑰。

元寶整合是 Hermes-Agent 獨有（Ada / Vi 預裝 Hermes-Agent，都可接元寶），目前不支援把 Rose（OpenClaw）接到元寶。

流程總覽

① 在元寶開發者後台建立應用            ← 5 分鐘
② 取得 API Key + Bot ID              ← 即時
③ 在 admin panel 貼上憑證             ← 30 秒
④ 在元寶搜尋 Bot 並加為好友           ← 即時
⑤ 開始對話                          ← 完成！

準備工作

你需要：

  • 騰訊元寶帳號（可用微信 / 騰訊 ID 登入）
  • 元寶開發者後台存取權（一般帳號就能進，不像 Teams 要管理員）
  • realvco admin panel 登入權限
  • 你的主機已有 Vi（hm-3 容器，Hermes v0.12 以上）

步驟 1：在元寶開發者後台建立 Bot

進元寶開發者後台（搜尋「元寶開放平台」或從元寶 App 設定進）。

  1. 登入後選 建立應用
  2. 應用類型選 Bot（聊天機器人）
  3. 填基本資訊：
    • 應用名稱：Bot 在元寶顯示的名字（例如「Vi 助理」）
    • 應用簡介：一句話描述（會顯示在 Bot 個人檔案）
    • 頭像：可選，建議上傳辨識度高的圖
  4. 提交後幾秒鐘審核通過，會給你兩個值：
值用途
API Key等同密碼，不要外洩
Bot ID公開識別碼，會出現在 Bot 個人檔案

API Key 等同密碼。任何人拿到就能操控 Bot。

  • 不要截圖發到公開群組
  • 不要寫進公開 Git repo
  • 洩漏可在元寶開發者後台 重新產生 作廢舊 key

步驟 2：在 admin panel 設定

hm-3 設定子分頁 — 騰訊元寶設定欄位所在的完整面板 hm-3 設定子分頁 — 騰訊元寶設定欄位所在的完整面板
元寶 API Key 與 Bot ID 貼在這個 hm-3 設定面板的 Messaging 區塊
  1. 登入 admin panel
  2. 切到 hm-3 (Vi) 容器
  3. 進 Settings → Messaging → 騰訊元寶（Yuanbao）
  4. 貼上：
    • API Key
    • Bot ID
  5. 按 Save

admin panel 會即時驗證，成功會顯示：

  • ✅ Bot Display Name
  • ✅ Bot ID 認證通過
  • ✅ Connection Status: Connected

失敗常見原因：API Key 抄錯、Bot ID 和 API Key 不對應（換 Bot 時忘了同步換 Key）。

步驟 3：在元寶找 Bot 開始對話

打開元寶 App 或網頁版，搜尋你剛建立的 Bot 名稱（例如「Vi 助理」），點 加好友。

加好友後在對話視窗傳任意訊息，Vi 就會回覆。

📷 元寶 App 內對話視窗為元寶原生 UI，搜尋你建立的 Bot 名稱加好友後即可看到

進階設定

加 Bot 到元寶群組

把 Bot 加到元寶群組：

  1. 群組設定 → 添加成員 → 搜尋 Bot 名稱
  2. 加進去後預設只回覆 @Bot名稱 提及訊息

要改成「每則訊息都回覆」，告訴 Rose：

「請把 Vi 的元寶群組 XXX 設成不用 @mention 也回覆」

限制誰能用（白名單）

預設任何加 Bot 為好友的人都能對它傳訊息。要限制：

「請限制 Vi 的元寶 Bot 只有以下這些 user ID 能用：[列表]」

取得自己的元寶 User ID：在元寶 App 個人檔案 → 我的 ID。

媒體支援

Vi 在元寶上支援：

  • ✅ 文字訊息
  • ✅ 圖片（自動分析）
  • ✅ 語音（自動轉文字）
  • ✅ 文件（PDF / Word / Excel）
  • ✅ 表情符號回應
  • ⚠️ 視訊／視像（依元寶當前 API 能力，可能不支援）

多媒體流量配額

元寶對 API 流量有上限（依應用等級不同）。一般小型 Bot 不會踩到，大量客服場景建議在元寶開發者後台升級配額或申請企業版。

常見問題

Bot 沒有回應

  1. 確認憑證：admin panel 的元寶設定頁應顯示「Connected」
  2. 檢查 Vi 容器狀態：admin panel → hm-3 → 主頁 → 容器應為 Running
  3. 看活動紀錄：admin panel → hm-3 → Activity → 看訊息是否被接收
  4. 元寶網路狀況：偶爾元寶 API 自身會有暫時性故障，可在元寶開發者後台公告頁查看
  5. 重啟容器：admin panel → hm-3 → Restart Container

訊息延遲很高

  • 正常 1-3 秒回應
  • 超過 10 秒：
    • 可能 Vi 模型繁忙（看 admin panel → Usage 是否高峰）
    • 可能元寶 API 限流（短時間大量訊息會觸發）
    • 換輕量模型試試（GPT-4o-mini、Claude Haiku）

可以同時建多個 Bot 嗎？

可以。每個 Bot 獨立，憑證分開。實用組合：

  • Bot 1 → Vi（對外客服公開）
  • Bot 2 → Vi（內部員工私用）

API Key 外洩怎麼辦

立刻到元寶開發者後台 → 你的應用 → 重新產生 API Key。新 Key 產生後舊的立即失效。記得回 admin panel 更新設定。

元寶帳號被封怎麼辦

這是元寶平台層問題，不是 realvco 的範圍。聯繫元寶官方客服。可同時把 Vi 切換到其他平台（Telegram / Discord）保持服務不中斷。

下一步