OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Mainstream messaging

Discord 活動

Discord Activities 可讓代理程式將互動式、獨立的 HTML 小工具發佈至目前的 Discord 頻道。訊息中包含 Open widget 按鈕；按一下後會在 Discord 內啟動小工具。

此功能預設為關閉。只有在 channels.discord.activities 存在且可解析出用戶端密鑰時，OpenClaw 才會註冊 Activity HTTP 路由、show_widget 代理程式工具及啟動按鈕處理常式。已淘汰的 discord_widget 別名仍會保留一個版本。

先決條件

  • 現有的 OpenClaw Discord 機器人
  • 可連至 OpenClaw 閘道的公用 HTTPS 主機名稱
  • 設定機器人 Discord 應用程式之 Activities 與 OAuth2 的權限

任何 HTTPS 反向 Proxy 或通道皆可使用。具名 Cloudflare Tunnel 可提供穩定的主機名稱，且不會直接公開閘道連接埠。

yaml
# ~/.cloudflared/config.ymltunnel: openclaw-discordcredentials-file: /home/you/.cloudflared/TUNNEL-ID.jsoningress:  - hostname: openclaw.example.com    service: http://127.0.0.1:18789  - service: http_status:404
bash
cloudflared tunnel logincloudflared tunnel create openclaw-discordcloudflared tunnel route dns openclaw-discord openclaw.example.comcloudflared tunnel run openclaw-discord

請維持啟用一般閘道驗證。只有 Activity 前綴是公開的，而此外掛會自行驗證 OAuth、Activity 執行個體成員資格、頻道繫結、工作階段及一次性文件權能。

設定

  • 透過 HTTPS 公開閘道

    啟動通道或反向 Proxy，並在新增 Activities 設定後，確認 https://openclaw.example.com/discord/activity/ 可連至閘道。請將範例主機名稱替換為你自己的主機名稱。

  • 在 Discord 中啟用 Activities

    在 Discord Developer Portal 中開啟現有的機器人應用程式。開啟 Activities、啟用 Activities，然後建立 URL 對應：

    • 前綴：ROOT（/）
    • 目標：openclaw.example.com/discord/activity

    目標為公用主機名稱加上 /discord/activity，結尾不含斜線。

  • 複製 OAuth2 用戶端密鑰

    在 Developer Portal 中開啟 OAuth2。Discord 要求至少設定一個重新導向 URI，因此若應用程式尚未設定，請新增本機預留位置，例如回送位址；Embedded App SDK 會處理 Activity 的返回流程。複製或重設應用程式用戶端密鑰。請將其視為認證資訊：不要貼到聊天、日誌或已提交的設定檔中。

  • 設定 OpenClaw

    在應提供小工具的 Discord 帳號中新增一個區塊：

    json5
    {  channels: {    discord: {      token: "${DISCORD_BOT_TOKEN}",      activities: {        clientSecret: "${DISCORD_CLIENT_SECRET}",        // 選用。預設為啟動時取得的機器人應用程式 ID。        applicationId: "YOUR_DISCORD_APPLICATION_ID",      },    },  },}

    設定 DISCORD_CLIENT_SECRET 時，可從區塊中省略 clientSecret。區塊本身必須保留，才能選擇啟用此功能。

    一般 Discord 存取設定仍是分開管理。例如，allowFrom 仍控制誰可以向代理程式傳送私訊；它不會控制誰可以開啟已發佈至頻道的小工具。

  • 重新啟動並測試

    重新啟動閘道。在 Discord 對話中，要求代理程式顯示互動式小工具。代理程式會呼叫 show_widget；按一下已發佈訊息中的 Open widget。

    • 安全模型

    • 傳回小工具中繼資料前，OAuth 會識別 Discord 使用者。
    • Discord 的 Get Activity Instance API 必須確認 OAuth 使用者存在於目前的 Activity 執行個體中。該執行個體的頻道必須與小工具發佈所在的頻道相符。
    • Discord 允許進入該頻道的所有人都能開啟其中的小工具。若要縮小對象範圍，請使用 Discord 頻道權限。OpenClaw 命令與私訊允許清單不會授予或移除對已發佈頻道內容的存取權。
    • OAuth 工作階段會在 15 分鐘後到期。小工具文件權能會在 60 秒後到期，且僅能使用一次。
    • 小工具會在七天後到期，每個 Discord 外掛執行個體最多保留 64 個。
    • 小工具 HTML 由你的代理程式撰寫，應視為受信任的內容。請勿嵌入你不希望因小工具程式錯誤而外洩的機密資訊。
    • 小工具可在自身的巢狀框架內瀏覽。sandbox="allow-scripts" iframe 會封鎖頂層導覽、彈出式視窗及同源存取，而其內容安全政策會封鎖網路連線與外部資源。這些控制措施屬於縱深防禦，並非用來防範撰寫該小工具之代理程式的安全邊界。
    • 停用 Activities 時，完全不會註冊 /discord/activity。

    啟用後，可透過你的通道存取公開的 Activity Shell 與 Token 交換路由。若沒有有效的 OAuth 工作階段及一次性文件權能，這些路由不會公開小工具 HTML。

    疑難排解

    Activity 顯示「Gateway offline」

    • 確認通道正在執行，且路由至閘道實際繫結的連接埠
    • 確認 Developer Portal 目標包含 /discord/activity
    • 變更 Discord 或 OpenClaw 設定後，重新啟動閘道
    • 查看閘道日誌中關於缺少 Activities 用戶端密鑰的單行警告

    Discord 開啟空白頁面或回報 blocked:csp

    • 確認 URL 對應使用 ROOT，且沒有新增第二個 /discord/activity 區段
    • 確認 Shell、shell.js 及 SDK 模組全都透過 Discord Proxy 傳回
    • 檢查閘道日誌中位於 /discord/activity/ 下的要求

    系統會刻意封鎖小工具的網路要求。請將小工具所需的所有 CSS、JavaScript、圖片及資料全部內嵌。

    「Widget unavailable」

    請從代理程式發佈小工具的頻道啟動按鈕。按一下時，OpenClaw 會在伺服器端追蹤啟動，因此即使 Discord 省略或破壞按鈕的自訂 ID，新的啟動記錄仍可解析出確切的小工具。當自訂 ID 與啟動記錄皆無法解析時，OpenClaw 會開啟該頻道中最近發佈且仍有效的小工具。較舊的小工具仍可透過保留其自訂 ID 的按鈕存取。

    「You cannot launch Activities in this channel」

    Discord 不會從論壇貼文討論串啟動 Activities。OpenClaw 可以在該處發佈小工具訊息與按鈕，但請改從一般文字頻道啟動 Activity。此限制來自 Discord，而非 OpenClaw。

    Was this useful?
    On this page

    On this page