独立运行与网页嵌入

Agent 配置并发布后，Clouisle 提供两种分发方式：

1. 站内运行页：面向登录用户的完整对话界面。Agent 用对话（Chat）（/chat/{agent_id}），工作流用运行（Run）（/run/{workflow_id}?type=workflow）。
2. 网页嵌入：用团队 API 密钥把已发布的 Agent 或工作流嵌入外部网站，支持浮窗、全屏与移动端三种形态。

嵌入始终以 API 密钥作为访客身份，不需要对方登录 Clouisle。因此目标必须先发布，密钥也只能访问你为它勾选的对象。

站内运行页

运行页去掉了编排侧边栏和配置抽屉，专注完成任务：

• 无干扰画布：适合复杂交互、大文档分析和多轮迭代。
• 必填变量先填写：Agent 配置了必填变量时，会话开始前会弹出结构化输入栏。
• 完整能力：附件上传、图片查看器、文档预览、ask_user 表单与消息版本分支。

进入方式：应用（/app/apps）> 悬浮应用卡片 > 右上角 ... 菜单：

• Agent 选对话（Chat），在新标签页打开 /chat/{agent_id}。
• 工作流选运行（Run），打开 /run/{workflow_id}?type=workflow。

也可以直接访问 /run/{id}：默认按 Agent 处理，带 ?type=workflow 时按工作流处理。

网页嵌入：准备 API 密钥

嵌入页面只认 clou_ 开头的 API 密钥，不接受账号登录状态。

1. 前往 API 密钥（/app/api-keys），点击创建密钥。
2. 填写名称，例如「官网嵌入」。
3. 按需在允许访问的智能体与允许访问的工作流里勾选要公开的对象。留空表示不限制，嵌入场景务必勾选，否则密钥能访问团队内所有可嵌入对象。
4. 按需设置过期时间（留空表示永不过期）与速率限制（每分钟请求数，0 表示不限；嵌入请求目前不按该值限流）。
5. 保存后立即复制密钥——弹窗关闭后无法再次查看。忘了只能新建一个再替换。

网页嵌入：开启与配置

1. 在 Agent 编排页（/app/apps/{agent_id}）或工作流编排页打开目标对象。
2. 确认对象处于已发布状态——未发布时嵌入抽屉顶部会提示，且无法保存。
3. 点击顶部工具栏的嵌入按钮。
4. 打开启用嵌入。
5. 在API 密钥处粘贴上一步的密钥，它会自动填入下方代码片段。
6. 选择嵌入模式（浮窗 / 全屏 / 移动端），按需调整外观。
7. 点预览检查效果，确认后点保存，再点复制代码粘贴到你的网站。

配置项

外观配置保存在对象上，保存后立即对新的访问生效；已经打开的页面需要刷新。

网页嵌入：把代码放进网站

抽屉底部的三个页签（浮窗 / 全屏 / 移动端）决定生成哪种片段。三者都指向同一个嵌入页面（Agent 为 /embed/agent/{id}，工作流为 /embed/workflow/{id}）。

浮窗模式（推荐）

浮窗需要引入官方 embed.js，再调用 Clouisle.init：

<script src="https://<your-domain>/embed.js"></script>
<script>
  Clouisle.init({
    type: 'agent',
    id: '550e8400-e29b-41d4-a716-446655440000',
    token: 'clou_a1b2c3d4e5f6...',
    mode: 'bubble',
    theme: 'auto',
    primaryColor: '#2563eb',
    position: 'bottom-right',
    greeting: '你好！有什么可以帮你的？',
  });
</script>

Clouisle.init 的参数：

浮窗实例可以用 Clouisle.open()、Clouisle.close()、Clouisle.destroy() 控制；重复调用 init 会先销毁上一个实例。嵌入页内部发出的关闭动作也会收起浮窗。

全屏与移动端模式（纯 iframe）

这两种模式不需要 JS，抽屉直接生成 iframe：

<!-- 全屏：放进页面里的某个容器 -->
<iframe
  src="https://<your-domain>/embed/agent/550e8400-e29b-41d4-a716-446655440000?token=clou_a1b2c3d4e5f6...&mode=fullscreen"
  style="width: 100%; height: 100%; border: none;"
  allow="clipboard-write"
></iframe>

<!-- 移动端：铺满整个视口 -->
<iframe
  src="https://<your-domain>/embed/agent/550e8400-e29b-41d4-a716-446655440000?token=clou_a1b2c3d4e5f6...&mode=mobile"
  style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; border: none; z-index: 9999;"
  allow="clipboard-write"
></iframe>

全屏模式也可以交给 SDK 指定容器：Clouisle.init({ type: 'agent', id: '...', token: '...', mode: 'fullscreen', container: '#chat' })。

地址参数

嵌入地址支持以下参数，手改片段时用得到：

访问与安全

• 只接受 API 密钥：嵌入页不使用账号登录状态。缺少密钥时页面无法加载（一直显示加载中）；密钥无效、被禁用或过期时，请求会被拒绝并提示密钥无效或已过期。
• 密钥归属于创建者：嵌入会话以创建密钥的那个用户身份执行，因此它能读到的知识库、能调用的工具都以该用户为准。不要用权限过高的个人账号创建嵌入密钥。
• 密钥绑定收窄范围：勾选了「允许访问的智能体 / 工作流」就只能访问勾选对象；留空则不限制。建议始终勾选。
• 多重校验：目标必须命中密钥绑定、必须已发布、必须启用嵌入，再叠加域名校验。对应提示分别是「此 API 密钥无权访问请求的 Agent」「Agent 未找到」「此资源未启用嵌入功能」「此域名不允许嵌入此资源」。
• 速率限制：密钥上的速率限制目前不作用于嵌入请求；实际速度受团队模型配额与供应商限流约束。
• 权限隔离：嵌入会话无法访问团队模型管理、站点设置或其他管理员功能。

常见问题

嵌入页一直转圈或提示密钥无效

1. 片段里的 token 是否完整（以 clou_ 开头），有没有粘贴成账号登录令牌。
2. 密钥是否已被禁用或过期；过期后必须新建密钥并替换网页代码。
3. 目标是否已发布、是否已打开启用嵌入。
4. 网站域名是否在允许的域名里。

浮窗按钮不出现

1. embed.js 的地址必须指向你实际部署的 Clouisle 域名。
2. id 与 token 都要有值。
3. 页面上重复初始化会互相替换，只保留最后一个实例。

访客看不到历史记录

嵌入页的历史存在访客浏览器本地：清空浏览器数据、换设备或无痕窗口都会丢失；需要跨设备保留历史时，请改用站内运行页。

相关页面

• 嵌入集成 API — 嵌入对话、工作流执行、上传与历史接口
• API 密钥 — 创建、绑定对象、禁用与轮换密钥
• 创建与编排 Agent — 编排、发布与工具配置
• 对话与会话 — 引用、附件与产物在会话中的表现