# 自定义外观 (/docs/developers/agent/embed/appearance)
让聊天的配色、开场和输入区与网站一致。iframe 与 Hosted 使用控制台保存的同一份外观；Kit 组件使用你在网页中传入的选项。
## 准备接入 [#prepare]
先准备能正常回复的服务智能体和嵌入策略。Kit 示例要求宿主网站已提供 `POST /api/praxis-token`，验证登录态并返回 `{ token }`；这是你的同源路由，详见[嵌入令牌与用户](/docs/developers/agent/embed/tokens)。示例使用 Develop 地址，页面来源须获准接入。
| 接入方式 | 外观在哪里配置 |
| --------------- | ------------------------------------------ |
| iframe / Hosted | 控制台保存，两个页面共用；刷新嵌入页后生效 |
| Kit 组件 | 网页的 `setOptions`；控制台的 Kit 编辑器只供预览和生成代码，不保存 |
## 保存托管外观 [#saved-appearance]
iframe / Hosted 的持久外观**目前只能在控制台配置**。当前控制台入口为「服务智能体 → 你的智能体 → 接入与配置 → 接入方式与外观 → iframe」。
1. 在「主题」选择配色、强调色、灰阶、圆角和密度。
2. 在「开场」填写欢迎语与推荐问题，在「输入区」设置输入提示和页脚。
3. 点击「保存」。**预期：** 提示「已保存，嵌入页刷新后生效」。刷新 iframe，或重新打开 Hosted，检查同一组文字和配色。
不要去「配置 → 开场与外观」编辑：该位置目前是提示页。公开外观接口只提供读取，没有公开的保存接口。
## 设置 Kit 外观 [#kit-options]
把下面的 HTML 放在宿主网站。它同时设置主题、开场和输入框，并提供一个按钮验证运行中更新。
```html
订单助手
```
**预期结果：** 出现蓝色强调色、欢迎语和「配送规则」按钮；输入框不显示附件入口。点击「切换深色」后颜色切换，当前会话和消息保留。
再次调用 `setOptions` 会合并嵌套选项，数组整体替换。因此更新 `theme.colorScheme` 不需要重传令牌回调；更换推荐问题时，传入完整的 `startScreen.prompts` 数组。
## 调整主题与文字 [#options]
| 选项 | 可选值或用途 |
| ---------------------------------------------- | ----------------------------------------------------------- |
| `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 地址。只改组件配置时，详细属性边界见[组件参考](/docs/developers/agent/embed/component-reference)。
## 验证与下一步 [#verify]
在一个新会话中检查开场文字，点击推荐问题，确认实际发送的是 `prompt`。在已有消息的会话点击深色按钮，确认消息保留；另开页面检查控制台保存的外观，避免把 Kit 的本地配置误认为已保存。
外观更新不改变智能体指令或工具授权。若保存失败，按字段提示缩短文字、减少推荐问题或修正图片地址后重试。
[组件参考](/docs/developers/agent/embed/component-reference) · [保护嵌入接入](/docs/developers/agent/embed/security) · [智能体 API](/docs/api/native/agent)。