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 可提供穩定的主機名稱，且不必直接暴露閘道連接埠。

# ~/.cloudflared/config.yml
tunnel: openclaw-discord
credentials-file: /home/you/.cloudflared/TUNNEL-ID.json
ingress:
  - hostname: openclaw.example.com
    service: http://127.0.0.1:18789
  - service: http_status:404

cloudflared tunnel login
cloudflared tunnel create openclaw-discord
cloudflared tunnel route dns openclaw-discord openclaw.example.com
cloudflared tunnel run openclaw-discord

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

​

設定

1. 透過 HTTPS 公開閘道

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

2. 在 Discord 中啟用 Activities

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

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

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

3. 複製 OAuth2 用戶端密鑰

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

4. 設定 OpenClaw

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

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

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

   一般 Discord 存取設定仍然彼此獨立。例如，allowFrom 仍控制誰可以私訊代理程式；它不控制誰可以開啟已發佈到頻道中的小工具。

5. 重新啟動並測試

   重新啟動閘道。在 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 殼層與權杖交換路由可透過你的通道存取。如果沒有有效的 OAuth 工作階段和一次性文件能力，這些路由不會公開小工具 HTML。

​

疑難排解

​

Activity 顯示「Gateway offline」

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

​

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

• 確認 URL 對應使用 ROOT，且未新增第二個 /discord/activity 區段
• 確認殼層、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。