OpenMax
免费试用

常见问题

集成时最常遇到的问题和解决办法。

常见问题

组件没有样式

没引入 SDK 的样式表,或者组件不在 ChatRoot 里。样式表只作用在 SDK 组件在 ChatRoot 里各自带的 .omx-chat 组件根之内。检查全局 CSS 里是否引入了 @openmaxai/chat-sdk/styles.css、这个 CSS 文件本身是否被引入、聊天是否包在 <ChatRoot> 里,见安装。

组件显示的是文案 key

少了 I18nextProvider。部分组件(提及面板、群管理、浮窗和抽屉)通过 useTranslation 取文案,需要用 <I18nextProvider i18n={createChatI18n({ locale: "zh-CN" })}>(I18nextProvider 来自 react-i18next,createChatI18n 来自 @openmaxai/chat-sdk) 包住整棵树。见国际化。

报 Invalid hook call

页面加载了两份 React。用 Vite 时设置 resolve.dedupe: ["react", "react-dom"],见安装 · 配置打包器。

不接后端能用吗

能。用内存函数加 createLocalPorts 拼一个宿主,见快速开始。本站所有演示都是这样运行的。

能接自己的后端吗

能。自己实现必填的 identity、messaging、inboundDelivery,要会话列表再加 conversations,其余必填能力交给 createLocalPorts。见接入自己的后端。也可以写一个适配器交给 createChatHost({ adapter }),由它造出宿主;两种写法都在同一篇指南里。

移动端支持

支持,不需要传设备开关。组件按自己容器的宽度切换排版(容器窄于 768 px 用窄排版),按输入方式决定触屏交互,见组件 · 响应式。@openmaxai/chat/surfaces 另有底部抽屉 ChatMobileDrawer,用不用由应用决定。

深色模式

在祖先元素(一般是 <html>)上加 dark 类。聊天不自动跟随 prefers-color-scheme。见主题。

某个功能没有出现

可选功能只在宿主提供对应能力时出现:

功能 需要的能力
「@我」跳转 mentions
# 引用工作项 workItems
Agent 模型选择 agentConfig
建群、群信息面板 groupManagement
卡片上的按钮和选项 cards
点头像弹出名片 profileCard
点图片放大 mediaViewer
表情回应、撤回、编辑、已读回执 messaging 上对应的可选方法
附件按钮 attachments,且附件上限大于 0

createChatHost 提供哪些见已知限制 · 默认宿主;它的上传还要求外层有 <ConversationScope>。完整说明见能力。

自己的消息短暂显示成别人的

createChatHost 在首次渲染后才取回当前用户,期间用户 id 为空,<ChatProvider> 会在数据到达后重渲染。

能看到 Agent 正在做什么、能停下它吗

能。宿主提供 agentRuns 能力、后端推 agent_event 帧后,消息区显示运行进度、工具步骤、逐字输出和停止按钮,见接入自有后端。规划中

能从 npm 安装吗

能。这些包已作为 3.0.0 预发布版本(3.0.0-beta.*)发布到 npm。所有导出都标着 @experimental,预发布版本之间可能变动,所以要锁定确切版本号,所有 @openmaxai/chat* 包用同一个,见安装。变化记录在更新日志。