> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asktable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 嵌入

> 嵌入让你把智能体以 iframe 放进自己的网站，访客无需登录即可直接问数。本页介绍嵌入的作用、配置步骤、访客体验与安全模型。

## 什么是嵌入

嵌入把[智能体](/concepts/agent/overview)以 `<iframe>` 的形式放进你自己的网站。网站访客**无需登录 AskTable、不用选数据源或角色**，打开页面就能用自然语言问数。

这是智能体对外的第四种方式，和[频道](/concepts/agent/channel)、[定时任务](/concepts/agent/schedule)并列：频道接 IM，定时任务按计划推送，嵌入面向你网站上的匿名访客。

## 典型场景

* 在官网或帮助中心放一个「自助查数」入口，访客自己问、自己得到答案
* 在客户门户里嵌入一个只读某类数据的问数窗口
* 在内部 wiki 页里嵌入一个绑定固定角色的分析助手

## 配置要素

一个嵌入地址包含：

| 要素       | 说明                                                            |
| -------- | ------------------------------------------------------------- |
| **名称**   | 地址的显示名，仅用于你在后台区分多个地址                                          |
| **绑定角色** | 必填。地址绑定一个固定角色（含固定角色变量），**所有匿名访客都在这个角色的数据范围内提问**，看到相同的数据边界     |
| **可信域名** | 开关 + 域名白名单。**关（默认）= 不校验来源，任何网站都可嵌入**；**开 = 只有白名单里的域名可以嵌入**该地址 |
| **启用**   | 开关。**新建即启用、立即可用**；停用后正在进行的会话立即断开                              |

每个嵌入地址都归属一个智能体，由它来回答。

## 如何配置

<Steps>
  <Step title="新建嵌入地址">
    进入智能体详情页，切到【嵌入】标签，点【新建地址】。
  </Step>

  <Step title="填名称、选角色">
    起个名字，选一个角色作为访客的数据范围。若该角色需要角色变量（如 `user_id`），一并填好——这些变量对所有访客固定生效。
  </Step>

  <Step title="设置可信域名（可选）">
    默认不校验来源，任何网站都能嵌入。若只想让特定网站嵌入，打开【可信域名】开关，把允许的域名逐个加入白名单（如 `https://example.com`）。

    <Warning>打开开关但白名单为空时，任何网站都无法嵌入——记得至少加一个域名。</Warning>
  </Step>

  <Step title="保存并复制嵌入代码">
    保存后地址默认已启用。点【复制嵌入代码】，把 `<iframe>` 代码贴到你的网页里：

    ```html theme={null}
    <iframe src="https://<你的 AskTable 站点>/embed/emb_xxxx"
            style="width:100%;height:600px;border:0"></iframe>
    ```
  </Step>
</Steps>

## 访客体验

访客打开嵌入页后：

* 无需登录，也不用选数据源或角色，直接在输入框提问
* 只能在地址绑定的角色数据范围内得到回答
* 可在**快速 / 深度思考**之间切换（初始为快速，响应更即时）
* 24 小时内刷新页面会**接着同一个对话**；超过则自动开始新对话，也可随时点【新对话】重新开始

## 安全模型

嵌入面向匿名公网访客，安全靠这几层：

* **固定角色数据范围** — 访客只能问到绑定角色允许的数据；改角色只影响之后新建的对话
* **不可猜的地址 ID** — 地址 ID 是随机串（`emb_` 前缀），不暴露枚举
* **可信域名白名单** — 打开【可信域名】后，只有白名单域名的页面能嵌入
* **禁用即停** — 停用地址后，正在进行的会话立即断开

<Note>嵌入是公开入口。绑定角色时，请确认该角色的数据范围适合对外公开。</Note>

## 嵌入 vs 频道

两者都让**外部用户**用智能体，但形态不同：

* **频道**：接入飞书等 IM，用户在 IM 里对话
* **嵌入**：以 iframe 放进你的网站，面向**匿名网页访客**，绑定一个固定角色，所有人看到相同的数据范围

## 常见问题

**Q: 访客需要登录吗？**
A: 不需要。嵌入面向匿名访客，打开页面即可提问。

**Q: 不同访客看到的数据一样吗？**
A: 一样。一个地址绑定一个固定角色和固定角色变量，所有访客都在这个范围内。要按访客身份隔离数据，用频道 + 权限，而不是嵌入。

**Q: 怎么限制只有我的网站能嵌入？**
A: 打开【可信域名】开关，把你的域名加入白名单。默认不限制来源。

**Q: 停用地址后正在聊天的访客会怎样？**
A: 会话立即断开。重新启用后，访客刷新页面即可重新开始。