---
url: https://docs.oakxgen.ai/zh-Hant-TW/guide/agents/web-widget.md
description: >-
  不用寫程式，把一段嵌入碼貼進網站，訪客就能在網頁右下角直接跟 Skill agent
  對話。這篇說明怎麼啟用、怎麼設定允許的網站與外觀、流量上限與人機驗證，以及訪客看到「這個網站沒有被允許使用這個聊天視窗」時要檢查什麼。
---

看完這篇，你可以替 Skill agent 產生網站聊天視窗的嵌入碼，設定哪些網站能用、長什麼樣子，並控制流量不被灌爆。

## 開始前

* 只有 **Skill agent** 能用網站 Widget；Channel agent 的串接頁看不到這張卡片。
* 要有這個 agent 的**編輯 Agent** 權限，**串接**分頁才會出現**網站 Widget** 設定卡（見[角色與權限](https://docs.oakxgen.ai/zh-Hant-TW/guide/settings/roles-and-permissions)）。
* 要能修改網站的 HTML，或請網站管理員幫你把嵌入碼貼到每一頁。

## 網站 Widget 跟其他串接怎麼選

| | 網站 Widget | [對話 API](https://docs.oakxgen.ai/zh-Hant-TW/guide/agents/api-conversation.md) | [通用 Webhook](https://docs.oakxgen.ai/zh-Hant-TW/guide/agents/webhook-integration.md) |
|---|---|---|---|
| 要不要寫程式 | 不用，貼一段嵌入碼 | 要，自己做聊天介面 | 要，自己收發訊息 |
| 訪客看到什麼 | OakXgen 提供的聊天視窗 | 你自己做的畫面 | 你自己的系統 |
| 適合 | 官網、活動頁想快速放一個 AI 客服 | 要把 AI 整合進自家 App 或網站流程 | 已經有客服系統，只想讓 AI 幫忙回 |

## 啟用網站 Widget

1. 打開 Skill agent，切到**串接**分頁。
2. 在**網站 Widget**卡片按**啟用網站 Widget**。
3. 卡片展開後，最上面是**嵌入碼（貼到網站每一頁的 `</body>` 前面）**，按旁邊的複製圖示複製。
4. 在**允許的網站**輸入你的網址（例如 `https://www.example.com`），按**加入**。貼整個網頁網址也可以，系統只會留下 `https://網域` 的部分。
5. 依需要調整外觀、開場白與建議問題，按右下角**儲存**。
6. 把嵌入碼貼到網站每一頁的 `</body>` 前面，重新整理網頁，右下角（或左下角）就會出現聊天按鈕。

下面的動畫示範在「示範：青葉書屋問答」的**串接**分頁按**啟用網站 Widget**：卡片展開，出現嵌入碼、**允許的網站**、外觀設定，右邊是**即時預覽**。

[動畫（MP4）](https://docs.oakxgen.ai/zh-Hant-TW/guide/agents/images/web-widget-01-enable.mp4)

**允許的網站一個都沒加之前，聊天視窗在任何網站都不會出現。** 卡片上會用橘色字提醒：「還沒有加任何網站：加入之前，聊天視窗在任何網站都不會出現。」所以啟用後一定要回來加網址。

## 設定卡上的每個欄位

下圖是設定好之後的**網站 Widget**卡片：左邊由上到下是嵌入碼、**允許的網站**、**外觀**（主色、位置、視窗標題、主題、頭像網址）、**開場白**、**建議問題**、**人機驗證**與**流量上限**；右邊的**即時預覽**照著還沒存檔的設定，顯示視窗標題「示範：青葉書屋線上服務」、開場白與兩個建議問題。預覽下方寫著「這裡顯示的是還沒存檔的設定，無法真的對話。」

![網站 Widget 設定卡：嵌入碼、允許的網站、外觀、開場白、建議問題、人機驗證、流量上限，右邊是即時預覽](https://docs.oakxgen.ai/zh-Hant-TW/guide/agents/images/web-widget-02-settings.png)

| 欄位 | 說明 | 限制 |
|---|---|---|
| **允許的網站** | 只有這些網站能載入聊天視窗 | 最多 20 個；正式網站要 `https://`，只有 `localhost` 可以用 `http://`；`https://*.example.com` 代表所有子網域 |
| **主色** | 視窗標題列與按鈕的顏色 | 要是 `#RRGGBB` 格式，例如 `#7c3aed` |
| **位置** | 聊天按鈕在網頁的**左下**或**右下** | — |
| **視窗標題** | 聊天視窗頂端的文字 | 最多 40 字 |
| **主題** | **淺色**或**深色** | — |
| **頭像網址** | 視窗裡 AI 的頭像，可以貼 `https://` 網址或按**上傳圖片** | 上傳：正方形、2MB 以內、JPG／PNG／WebP／GIF，會自動裁成 256×256 |
| **開場白** | 訪客打開視窗時看到的第一句話 | 最多 300 字 |
| **建議問題** | 開場白下方可以直接點的問題 | 最多 4 個，每個最多 80 字 |

頭像上傳完會出現「頭像已上傳，按「儲存」後生效」，要再按**儲存**才會換上。

## 流量上限與人機驗證

網站是公開的，任何人都能打開聊天視窗。**流量上限**是用來「防止有人灌爆對話、耗光點數」：

| 欄位 | 預設 | 可以填 |
|---|---|---|
| **每位訪客每分鐘** | 10 | 1～60 |
| **每個 IP 每分鐘** | 30 | 1～300 |
| **整個 widget 每天** | 1000 | 1～100000 |

超過上限的訪客會看到「請稍後再試」。填超出範圍的數字，欄位下方會出現「請填 1～60 的整數」這類提示，**儲存**按不了。

打開\*\*人機驗證（Cloudflare Turnstile）\*\*後，訪客第一次開啟對話前會先經過人機驗證。多數訪客不會看到任何挑戰，只有可疑的流量才需要點一下；驗證沒過時會看到「人機驗證失敗，請重新試一次」。

網站 Widget 的對話跟其他串接一樣算在**對外流量**、扣點數（見 [AI 用量](https://docs.oakxgen.ai/zh-Hant-TW/guide/settings/usage)）。對話會出現在[對話紀錄](https://docs.oakxgen.ai/zh-Hant-TW/guide/logs/chat-logs-find-and-filter)，來源是**網站 Widget**。

## 停用網站 Widget

按卡片右下角的**停用網站 Widget**，確認視窗會寫「停用後嵌入碼會立刻失效，網站上的聊天視窗會消失。之後重新啟用會產生新的嵌入碼。」確認後，網站上的聊天視窗立刻消失。

重新啟用會拿到**新的**嵌入碼，舊的那段不會再生效，記得把網站上的嵌入碼一起換掉。

## 常見問題

### 網站上看不到聊天按鈕

依序檢查：

1. 嵌入碼有沒有貼在每一頁的 `</body>` 前面，網站有沒有重新發布。
2. **允許的網站**有沒有加這個網站，網址的協定與網域要完全對上（`https://www.example.com` 跟 `https://example.com` 是不同網站；要涵蓋子網域用 `https://*.example.com`）。
3. 加完網址有沒有按**儲存**。

### 訪客看到「這個網站沒有被允許使用這個聊天視窗」

訪客所在的網址不在**允許的網站**清單裡。把那個網址加進去並儲存。

### 訪客看到「這個聊天視窗目前沒有開放」

網站 Widget 已經停用，或嵌入碼是停用前的舊版本。重新啟用後，把新的嵌入碼換到網站上。

### 儲存時出現「只有 localhost 可以用 http，正式網站請用 https」

正式網站一定要用 `https://`。本機測試可以加 `http://localhost:3000` 這種網址。

### 訪客看到「對話已過期，請重新整理頁面」

聊天視窗開太久，對話憑證過期了。請訪客重新整理網頁再問一次。

## 下一步

* [對話 API：同步呼叫與逐字串流](https://docs.oakxgen.ai/zh-Hant-TW/guide/agents/api-conversation.md)
* [對話紀錄：怎麼找到某個 Agent 的某段對話](https://docs.oakxgen.ai/zh-Hant-TW/guide/logs/chat-logs-find-and-filter)
* [AI 用量：怎麼看儲值餘額、免費額度與用量上限](https://docs.oakxgen.ai/zh-Hant-TW/guide/settings/usage)