自定义外观
调整聊天配色、开场文字与输入区，并选择对应接入方式的保存位置。
让聊天的配色、开场和输入区与网站一致。iframe 与 Hosted 使用控制台保存的同一份外观；Kit 组件使用你在网页中传入的选项。
准备接入
先准备能正常回复的服务智能体和嵌入策略。Kit 示例要求宿主网站已提供 POST /api/praxis-token，验证登录态并返回 { token }；这是你的同源路由，详见嵌入令牌与用户。示例使用 Develop 地址，页面来源须获准接入。
| 接入方式 | 外观在哪里配置 |
|---|---|
| iframe / Hosted | 控制台保存，两个页面共用；刷新嵌入页后生效 |
| Kit 组件 | 网页的 setOptions；控制台的 Kit 编辑器只供预览和生成代码，不保存 |
保存托管外观
iframe / Hosted 的持久外观目前只能在控制台配置。当前控制台入口为「服务智能体 → 你的智能体 → 接入与配置 → 接入方式与外观 → iframe」。
- 在「主题」选择配色、强调色、灰阶、圆角和密度。
- 在「开场」填写欢迎语与推荐问题，在「输入区」设置输入提示和页脚。
- 点击「保存」。预期： 提示「已保存，嵌入页刷新后生效」。刷新 iframe，或重新打开 Hosted，检查同一组文字和配色。
不要去「配置 → 开场与外观」编辑：该位置目前是提示页。公开外观接口只提供读取，没有公开的保存接口。
设置 Kit 外观
把下面的 HTML 放在宿主网站。它同时设置主题、开场和输入框，并提供一个按钮验证运行中更新。
<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8" />
<title>订单助手</title>
<button id="dark">切换深色</button>
<praxis-agent style="display:block;height:600px"></praxis-agent>
<script type="module">
import "https://kit-develop.praxisusercontent.com/v1/praxis-kit.js";
await customElements.whenDefined("praxis-agent");
const chat = document.querySelector("praxis-agent");
chat.setOptions({
api: {
url: "https://api-develop.deepraxis.com",
getToken: async () => {
const response = await fetch("/api/praxis-token", {
method: "POST", credentials: "same-origin",
});
if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
const { token } = await response.json();
if (typeof token !== "string" || !token) throw new Error("Missing token");
return token;
},
},
agent: { name: "订单助手" },
theme: {
colorScheme: "light", accent: "#2563eb", grayscale: "cool",
radius: "lg", density: "normal", fontFamily: "system-ui, sans-serif",
fontSize: 16,
},
header: { title: "订单服务", subtitle: "配送与退货咨询" },
startScreen: {
greeting: "今天想了解什么？",
prompts: [{ label: "配送规则", prompt: "请介绍配送规则。" }],
},
composer: { placeholder: "输入订单问题", attachments: { enabled: false } },
history: { enabled: true },
footer: "订单信息以商家确认为准。",
});
document.querySelector("#dark").addEventListener("click", () => {
chat.setOptions({ theme: { colorScheme: "dark" } });
});
</script>
</html>预期结果： 出现蓝色强调色、欢迎语和「配送规则」按钮；输入框不显示附件入口。点击「切换深色」后颜色切换，当前会话和消息保留。
再次调用 setOptions 会合并嵌套选项，数组整体替换。因此更新 theme.colorScheme 不需要重传令牌回调；更换推荐问题时，传入完整的 startScreen.prompts 数组。
调整主题与文字
| 选项 | 可选值或用途 |
|---|---|
theme.colorScheme | light、dark、system；省略为浅色，system 跟随系统配色 |
theme.accent / theme.surface | 强调色 / 背景色；使用明确、不透明的 CSS 颜色，例如 #2563eb；不接受 var(...) 或透明色 |
theme.grayscale | neutral、warm、cool |
theme.radius | none、sm、md、lg、full |
theme.density | compact、normal、spacious |
theme.fontFamily / theme.fontSize | 字体栈 / 正数像素字号；字体须由你的页面自行加载 |
startScreen.greeting / startScreen.prompts | 欢迎语 / 最多显示 4 个推荐问题；label 是按钮文字，点击后发送 prompt |
composer.placeholder | 输入框提示 |
composer.attachments.enabled | Kit 附件入口开关，默认开启；不在保存的 iframe / Hosted 外观中提供 |
locale | zh 或 en；Kit 未指定时先取宿主页语言，再取浏览器语言 |
保存的外观 JSON 最多 8192 UTF-8 字节；欢迎语 200 字符、推荐问题最多 4 项，每项 label 40 字符、prompt 200 字符，输入提示 80 字符。头像和顶栏图片须使用 HTTPS 地址。只改组件配置时，详细属性边界见组件参考。
验证与下一步
在一个新会话中检查开场文字，点击推荐问题，确认实际发送的是 prompt。在已有消息的会话点击深色按钮，确认消息保留；另开页面检查控制台保存的外观，避免把 Kit 的本地配置误认为已保存。
外观更新不改变智能体指令或工具授权。若保存失败，按字段提示缩短文字、减少推荐问题或修正图片地址后重试。