允许的源

小部件脚本故意是公开的——任何人都可以获取 /widget/widget.js。 这使得 允许来源 成为信任边界，阻止第三方在他们的网站上嵌入 您的代码片段并消耗您的配额。

契约

每个 POST /v1/widget/init 读取请求的 Origin 头（或回退到 Referer）并根据智能体的 allowed_origins 列表检查它。规则是：

1. 空列表 → 403。拒绝所有地方。新智能体在添加至少一个来源之前为空。
2. 通配符 "*" → 允许。内部工具和演示的选择性逃生舱口。永远不要设置为默认值。
3. 否则 → 精确的 scheme://host 匹配。无子域名推断。https://example.com 不允许 https://app.example.com。

严格子域名匹配

这是让人们措手不及的规则，所以值得单独说明：

如果您确实想要所有子域名，请单独列出它们：

https://example.com
https://www.example.com
https://app.example.com
https://docs.example.com

添加来源

从智能体的设置页面（/app/agents/{id}/settings）， 允许来源 卡片有一个文本区域——每行一个来源。 保存立即更新智能体；新的 init 请求在几秒内使用新列表。

来源必须包含方案：

有效	无效
https://example.com	example.com
http://localhost:3000	localhost
https://shop.example.com	*.example.com（不支持通配符，除了 "*"）

本地测试

在开发期间，将 http://localhost:3000（或您使用的任何端口） 添加到智能体的允许来源中。不要为此使用 "*" ——意外在生产中保留它会 使智能体开放。

拒绝时会发生什么

来自不允许来源的请求获得 JSON 403：

{
    "error": {
        "code": "origin_forbidden",
        "message": "Origin is not allowed for this agent."
    }
}

小部件的加载器优雅地处理这个问题——启动器静默消失而不是抛出控制台错误， 因此访客永远不会看到损坏的 UI。403 在平台端记录，以便您可以观察滥用模式。

关于同主机来源

检查使用方案 + 主机，因此 http 与 https 是不同的（应该如此）。不同的端口也是不同的来源（http://localhost:3000 ≠ http://localhost:3001）。

通配符：何时使用，何时不使用

"*" 存在于您确实事先不知道来源的情况：

• 内部演示智能体，嵌入在每个潜在客户的预览网站上。
• 沙盒/预览环境，来源每天变化。

对于生产智能体，永远不要。忘记 "*" 的成本是任何找到您的 data-agent-id 的人都可以耗尽您的配额。显式列表的成本是每个新来源一分钟。

限制路径——路径级伴侣

允许来源 在域级别绘制信任边界（只有 https://shop.example.com 可以加载小部件）。 限制路径 是其兄弟：已在允许来源内的 URL 路径列表， 小部件不应在其中挂载。使用它将机器人排除在您自己的 /admin、 /checkout 或 /account 流程之外，而无需触碰代码。

每个条目都是一个 glob——* 是唯一的通配符，贪婪地跨斜杠匹配。 与 window.location.pathname 进行不区分大小写的比较：

模式	匹配	不匹配
/admin	/admin、/Admin	/admin/users（为此使用 /admin/*）
/admin/*	/admin/users、/admin/billing/invoices	/admin 确切（裸前缀）；如果两者都需要，请同时列出
/checkout	/checkout	/checkout/confirm
/account/*	/account/profile、/account/security	/Help/account

运行时工作原理

智能体的 restricted_paths 列表与其他配置一起乘坐相同的 POST /v1/widget/init 响应。init 成功后，小部件根据列表检查 window.location.pathname ——如果任何模式匹配，栏永远不会挂载， 触发引擎永远不会启动，并且该页面上没有进一步的 HTTP。init 调用本身确实发生 （服务器是事实来源），因此如果开销很重要，也可以使用 allowed_origins 在脚本标签级别为主机设置网关。

编写

从智能体的设置页面，限制路径 卡片有一个文本区域—— 每行一个路径。与允许来源相同的 UX。空列表 = 无限制（小部件在允许来源内的 任何地方挂载）。最多 32 个条目，每个最多 200 个字符。

为什么这与身份验证是分开的旋钮

平台还通过 Inertia 根布局中的服务器端检查自动抑制经过身份验证的管理/客户 路由上的营销演示小部件——这是一个不依赖于智能体配置的硬性保证。 restricted_paths 是买方侧扩展：即使在完全未经身份验证的营销网站上， /checkout 也不应杂乱无章地放置销售聊天机器人。

自动索引如何使用来源

自动索引 使用相同的允许列表， 但当设置 "*" 时有一个转折：正在自动索引的页面 URL 必须匹配 访客的实际 Origin 头。这阻止恶意页面通过通配符自动索引任意第三方域名。