接入 OpenMax
用 createChatHost 把聊天接到 OpenMax 后端,渲染出来,并处理好令牌。
接入 OpenMax
@openmaxai/chat-openmax/react 的 createChatHost 返回一个对接 OpenMax 后端的宿主(ChatHost)。先完成安装和样式配置(引入 @openmaxai/chat-sdk/styles.css)。
创建宿主
src/chat-host.ts
import { createChatHost } from "@openmaxai/chat-openmax/react";
export const host = createChatHost({
baseUrl: "https://openmax.com", // REST 基址,不带 /api/v1
wsUrl: "wss://openmax.com/ws", // 或者 realtime: "off"
auth: {
mode: "token",
getToken: async () => fetchShortLivedToken(), // 你自己的取令牌逻辑
},
workspaceId: currentWorkspaceId, // 与 baseUrl 同源时作为 X-Workspace-ID 发送
orgId: currentOrgId, // 作为 X-Org-ID 发送
locale: "en-US", // 内置文案默认是中文
});
createChatHost是同步的:只校验配置,不发请求,不调getToken。在模块顶层或 memo 里建一次。baseUrl必填,SDK 不读环境变量。wsUrl与realtime: "off"必须二选一,都不传或都传会抛错。"off"时别人的新消息要刷新才看得到。
OpenMax 的地址
| 用途 | 地址 |
|---|---|
baseUrl(REST) |
https://openmax.com(不带 /api/v1)。SDK 在它后面拼 /api/v1/…(聊天接口)和 /auth/…(换令牌、换实时票据) |
wsUrl(实时) |
wss://openmax.com/ws |
本页示例都用这两个地址;同源代理和你的服务端转发,转发目标也是它们。
用个人 API Key 时 orgId 必须传
Key 不带组织,后端靠
X-Org-ID定组织,不带时/api/v1/conversations返回401;本身带组织的会话令牌可不传。workspaceId(X-Workspace-ID)后端不读,传不传都行,跨域时 SDK 也不发。这两个选项属于实验性配置,名称将来可能调整。
服务端渲染与 Next.js
baseUrl、wsUrl 除了绝对地址,还可以写成以 / 开头的路径(如 /openmax-api、/openmax-ws),由同源反向代理转给 OpenMax。路径不在建宿主时解析,而在第一次用到时(第一个 REST 请求、第一次建实时连接)按 new URL(path, location.origin) 解析,不看 <base href>;wsUrl 在 https: 页面得到 wss:、在 http: 页面得到 ws:。设备标识也在第一次建连时才取。所以宿主可以在模块顶层创建,服务端渲染时不碰 window。
location.origin本身不能用时(在服务端;about:blank这类location.origin为"null"的页面;或file:、chrome-extension:这类不是 http(s) 的页面),第一个请求以点名baseUrl的ChatSdkConfigError拒绝;路径写法的wsUrl不建连、不重连,适配器经sink.error报一次code为ws_url_unresolved的错误(cause是点名wsUrl的ChatSdkConfigError),聊天界面不受影响,只是没有实时。开发构建里另在控制台console.error一次(同一个宿主只一次),点名wsUrl、说明原因与改法;生产构建不输出。两种情况都不会调getToken。沙箱 iframe 不在此列:它的location.origin是地址的 http(s) 源(window.origin才是"null"),路径照常解析、照常发请求,能不能连通由服务端的 CORS 决定。//host/api这种协议相对写法不特判,按 URL 标准解析成页面协议下那台主机(另一个源,跨源部署的要求照样适用);不以/开头的写法(api)在建宿主时就抛。
Next.js 的推荐写法:带 "use client" 的模块在服务端渲染时也会在服务端执行。在这样一个模块的顶层建宿主,REST 用路径,再用 rewrites 转给 OpenMax:
src/chat-host.ts
"use client";
import { createChatHost } from "@openmaxai/chat-openmax/react";
export const host = createChatHost({
baseUrl: "/openmax-api",
wsUrl: "wss://openmax.com/ws", // 或者同源路径,见下
auth: {
mode: "token",
getToken: async () => fetchShortLivedToken(),
},
});
next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
async rewrites() {
return [
{ source: "/openmax-api/:path*", destination: "https://openmax.com/:path*" },
];
},
};
export default nextConfig;
/openmax-api/:path* 同时覆盖 /openmax-api/api/v1/… 和换票用的 /openmax-api/auth/ws-ticket。转发时保留 Authorization、X-Org-ID;/openmax-api 这类路径与页面同源,传了 workspaceId 就会发 X-Workspace-ID。
聊天组件也可以在服务端渲染。服务端不发请求、不调 getToken;服务端 HTML 与客户端第一帧画的是同一个占位:会话列表是加载中的骨架,消息区什么都不画(传了 emptyState 就画它),群信息面板什么都不画。<ChatProvider> 在浏览器里挂上之后才开始请求,数据到了替换占位。
在那之前 host.identity 还不认识任何人:currentUserId() 回 "",listMembers() 回空列表。服务端渲染时不要依赖它;自己的组件要用当前用户,在 useEffect 里(或挂载之后)读 host.identity。在浏览器里、组件之外直接调 host.identity,照旧按需取数。
Next.js 的 rewrites 不转发 WebSocket
rewrites只转 HTTP 请求,不转 WebSocket 升级。wsUrl要么给绝对地址(wss://…,页面的源要登记,见实时连接的部署形态第 2 种),要么写成路径(如/openmax-ws),并在 Next.js 前面放一个能转发升级的反向代理(Upgrade、Connection;nginx 写法见同一节第 1 种)。
渲染聊天界面
src/app.tsx
import { createChatI18n } from "@openmaxai/chat-sdk";
import {
ChatProvider,
ChatRoot,
ChatSplitLayout,
ConversationHeader,
CwsConversationList,
CwsMessageThread,
useChatSdkConversationList,
} from "@openmaxai/chat-sdk/react";
import { useState } from "react";
import { I18nextProvider } from "react-i18next";
import { host } from "./chat-host";
const i18n = createChatI18n({ locale: "zh-CN" });
export function App() {
return (
<I18nextProvider i18n={i18n}>
<ChatProvider host={host}>
<ChatRoot style={{ display: "flex", height: "100vh" }}>
<Chat />
</ChatRoot>
</ChatProvider>
</I18nextProvider>
);
}
function Chat() {
const { conversations } = useChatSdkConversationList();
const [selectedId, setSelectedId] = useState<string | null>(null);
const selected = conversations.find((c) => c.id === selectedId) ?? null;
return (
<ChatSplitLayout
open={selected !== null}
list={
<CwsConversationList
selectedId={selectedId}
onSelect={(c) => setSelectedId(c.id)}
onDeselect={() => setSelectedId(null)}
/>
}
>
{selected && (
<>
<ConversationHeader
conversation={selected}
onBack={() => setSelectedId(null)}
/>
<CwsMessageThread key={selected.id} conversation={selected} />
</>
)}
</ChatSplitLayout>
);
}
ChatProvider安装宿主和输入框插件,并在个人信息和成员数据到达后重渲染。ChatRoot是聊天区的上下文根:给里面的 SDK 组件提供配色和弹出层落点,SDK 组件都放在它里面。它本身不是样式作用域,样式只作用在各 SDK 组件自带的组件根之内,见安装 · 引入样式。CwsConversationList是会话列表,数据来自宿主的conversations.list,新消息到达时重取。ChatSplitLayout把会话列表和打开的会话左右并排;窄屏(视口窄于 768 px)一次只显示一栏:open为 true 时显示会话,否则显示列表。它的宽度由父元素给,所以ChatRoot加了display: flex。见ChatSplitLayout。ConversationHeader是会话顶部栏:标题、成员数和静音开关(OpenMax 适配器已接setMuted,发POST /api/v1/conversations/{id}/mute或/unmute)。窄屏上它显示返回箭头,点了调onBack,在那里清掉选中就回到列表。见会话头部。CwsMessageThread是消息区和输入框。它已为这条会话包好ConversationScope,附件上传绑定到这条会话(OpenMax 的上传接口按会话走)。- 输入框插件:这个宿主有
workItems(GET /api/v1/work-references),ChatProvider装上#插件:打#或点工具条的#按钮列出项目,打字搜项目和 Issue,项目可以展开取它的 Issue,见能力。 I18nextProvider(从你自己装的react-i18next取,实例用createChatI18n建):部分组件通过 react-i18next 取文案,见国际化。
这个示例不需要 @tanstack/react-query。
useChatSdkConversationList() 还返回 isLoading、error、hasNextPage、fetchNextPage 和 refetch。配了 wsUrl 时,新消息、已读变化或重连后列表会在一秒内刷新。
令牌与过期
SDK 只用令牌,不签发也不刷新:
- 第一个需要令牌的请求调用
getToken(),结果缓存复用。 - 遇到
401再调一次getToken({ refresh: true })(这时要真去续期),用新令牌重发该请求一次。 - 续不出令牌、或重发仍是
401,则以ChatSdkRequestError失败。怎么续期由你负责;续期接口断网时抛kind为network的ChatSdkError,请求就以network失败、不算会话过期。getToken30 秒内没结果按timeout失败,同样不算会话过期,下一发请求会重新调它。
WebSocket 用同一个令牌换一次性票据;换票遇 401 同样先续期再换一次,续期后仍被拒或 getToken() 以凭据失效失败时不再重连(network 照常退避重连)。换票遇 403(不许换票)不续期、不再重连,经错误事件报一次,不算会话过期;连接被服务端以凭据失效关闭时也不再重连,按凭据失效处理。见错误与会话过期。
短期令牌请连同到期时间一起返回:getToken 可以回 { token, expiresAt }(OpenMaxToken;expiresAt 是 epoch 毫秒或 ISO 8601 串)。这时:
- 请求要发出时离到期不到 60 秒(令牌寿命不到两分钟时按寿命的一半算),SDK 先问一次
getToken({ refresh: true })再发,不会有请求因为令牌到期先吃401。同时发现的几发只问一次;页面在后台挂了很久回来,第一个请求之前就会先续。 - 实时连接在到期前交接,不断开:用新票开第二条连接,连上后再关掉旧的。交接时到达的消息只出现一次。
- 只有
code为AUTH_TOKEN_EXPIRED的401才续。其它401(令牌或它背后的 Key 被吊销)直接以unauthorized失败:调onUnauthorized,实时不再重连,也不再去换令牌。
只回字符串时,上面的行为不变。
用个人 API Key 接入
个人 API Key 由用户自己在 OpenMax 的「设置 → 开发者 → 个人 API Key」里创建,以 cwpat_ 开头。Key 只放在你的服务端:由你的服务端拿 Key 换一张短期令牌,交给浏览器里的 SDK。
每个用户用自己的 Key。 一把 Key 只代表创建它的那个人,不支持一把 Key 给多个用户的浏览器共用。用户在 OpenMax 建好自己的 Key 交给你,你的服务端按登录用户分别保存,替谁换令牌就用谁的 Key。
不要把个人 API Key 放进浏览器
Key 代表创建它的那个人,有效期最长一年(默认 90 天)。写进浏览器端代码后,任何能打开这个页面的人都能在开发者工具里读到它,在它过期或被轮换之前,以这个人的身份、在勾选的权限内收发消息。怀疑泄露就立刻吊销。唯一的例外见只给 Key 主人自己用的内部页面。
不管 Key 在哪一端发出:
- Key 作为
Authorization: Bearer cwpat_…发送,后端只认这个请求头。 - 必须传
orgId。Key 只说明你是谁,组织由X-Org-ID决定;后端每次请求都现查你在这个组织里的成员身份,被移出组织或降了角色,下一次请求就按新身份算。用 Key 时在任何组织里都不会超过你本人的权限。 - 跨域嵌入时 SDK 不发
X-Workspace-ID(后端不读它,OpenMax 的 CORS 也不放行它)。页面与baseUrl同源、且传了workspaceId时才发;拿不到页面的源(不在浏览器里)时按跨域算。
推荐做法:服务端换短期令牌
接口是 POST /auth/pat/exchange(在 baseUrl 下),请求头带 Authorization: Bearer cwpat_… 和 X-Org-ID。X-Org-ID 必带,不带回 403 AUTH_ORG_MEMBERSHIP_REQUIRED。响应包在统一的 data 信封里,令牌在 data.access_token,另有到期时间、实际给到的权限(scopes)等字段;把令牌连同到期时间一起交给浏览器,SDK 就能在到期前续上。请求体可以不带:令牌有效 900 秒,权限取 Key 的权限与「聊天」预设的交集。要改就带 JSON:expires_in(60–900 秒,不会超过 Key 本身的到期时间);scopes(要的权限,同样和 Key 的取交集,Key 没有的直接去掉)。「聊天」预设不含改群资料与成员、切模型这几项(见要勾哪些权限),要用就在 scopes 里列出来。
- SDK 要令牌时调你的
getToken,它去问你自己的服务端。 - 你的服务端先认清是哪个登录用户,再拿这个用户自己的 Key、带上组织(
X-Org-ID)向 OpenMax 换一张短期令牌,把令牌交回浏览器。令牌绑定这个组织,浏览器里的orgId要和它一致,不一致时请求以401被拒。Key 不出服务端。 - SDK 用这张令牌发请求、申请实时连接。快到期时 SDK 照令牌与过期用
getToken({ refresh: true })再要一次,你的服务端再换一张,请求和实时连接都接着用,用户感觉不到。
你的服务端(Node / Express):
server.ts
import express from "express";
const app = express();
// requireLogin 是你自己的登录校验,过了之后 req.user 是当前用户
app.post("/chat-token", requireLogin, async (req, res) => {
// 当前用户自己的 Key(cwpat_…),只存在服务端;一把 Key 只代表一个人,不能给别的用户用
const apiKey = await loadUserApiKey(req.user.id);
if (!apiKey) return res.status(401).end(); // 这个用户还没交 Key,或已经删掉
const r = await fetch("https://openmax.com/auth/pat/exchange", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"X-Org-ID": req.user.orgId, // 必带,不带回 403;换出的令牌绑定这个组织,浏览器里的 orgId 要和它一致
},
});
if (r.ok) {
const { data } = await r.json(); // 响应包在 data 信封里
// expires_in 是令牌还能活的秒数,换成 epoch 毫秒就是 SDK 要的 expiresAt
return res.json({ token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 });
}
// 只有 Key 本身不能用(被吊销、轮换掉、过期)才回 401,浏览器据此按凭据失效处理
if (r.status === 401) return res.status(401).end();
// 400、403、404 重试也换不来:Key 没勾 org:token:exchange、用户不在这个组织、拿来换的不是 Key、请求的权限 Key 一项都没有、换令牌在服务端没开
if ([400, 403, 404].includes(r.status)) return res.status(r.status).end();
if (r.status === 429) {
return res.status(429).set("Retry-After", r.headers.get("Retry-After") ?? "1").end();
}
res.status(503).end(); // 上游出错、连不上:暂时换不到,不是 Key 的问题
});
浏览器里:
src/chat-host.ts
import { ChatSdkError } from "@openmaxai/chat-sdk";
import { createChatHost } from "@openmaxai/chat-openmax/react";
// SDK 缓存返回的令牌,快到 expiresAt 时再来问,所以每次都去服务端换一张新的
async function getToken() {
// fetch 自己失败(如断网)抛的 TypeError,SDK 按 network 处理,不用接
const r = await fetch("/chat-token", { method: "POST", credentials: "include" });
if (r.status === 401) throw new Error("chat token: 401"); // 只有这里按凭据失效处理:停实时、调 onUnauthorized
// 重试换不来:按 forbidden 报,实时停止重连,也不算会话过期
if ([400, 403, 404].includes(r.status)) throw new ChatSdkError("forbidden", "", { status: r.status });
if (!r.ok) throw new ChatSdkError("network", "", { status: r.status }); // 限流、上游出错:不算会话过期,实时照常重连
const { token, expiresAt } = await r.json();
return { token, expiresAt }; // 带上到期时间,SDK 才会在到期前续
}
export const host = createChatHost({
baseUrl: "https://openmax.com",
wsUrl: "wss://openmax.com/ws",
auth: { mode: "token", getToken },
orgId: currentOrgId, // 必传
});
SDK 把
getToken()的结果缓存复用,快到expiresAt时、以及收到code为AUTH_TOKEN_EXPIRED的401时(页面时钟不准)带{ refresh: true }再来问。带{ refresh: true }时一定要去服务端换新的,不能交回旧的那张。其它401说明 Key 或令牌被吊销了:SDK 不再来问,按凭据失效处理。换不出令牌时分三种:
- 你的服务端回
401(这个用户的 Key 没有了,或过期、被吊销、被轮换掉)才抛普通Error,按凭据失效处理。 - 换令牌的接口回
400、403或404是重试也换不来的失败,你的服务端原样回这个状态,不要改成503;浏览器抛kind为forbidden的ChatSdkError,实时停止重连,也不算会话过期。403的code是AUTH_PAT_INSUFFICIENT_SCOPE(Key 没勾org:token:exchange,meta.required_scope写着它;拿短期令牌再换也是这个,换出的令牌不带这一项)、AUTH_ORG_MEMBERSHIP_REQUIRED(用户不在这个组织,或请求没带X-Org-ID)或AUTH_PAT_EXCHANGE_CREDENTIAL_INVALID(拿来换的不是个人 API Key,例如网页登录的会话);400的code是AUTH_PAT_EXCHANGE_SCOPE_INVALID(要的权限 Key 一项都没有,没带scopes时按「聊天」预设算,缺的写在meta.missing_scopes;scopes里有不存在的权限时也是它,写在meta.invalid_scopes)或AUTH_PAT_EXCHANGE_EXPIRES_IN_INVALID(有效期不在 60–900 秒内);404的code是AUTH_PAT_EXCHANGE_DISABLED(换令牌在服务端没开,开放之前都是它)。400、403要改 Key 或改你的服务端,请用户换一把勾齐权限的 Key,或检查组织;404等 OpenMax 开放换令牌:开放之后普通接口下一次请求会重新换,实时已停止重连,要新建宿主(或刷新页面)才会恢复。 - 限流(
429,code为AUTH_PAT_EXCHANGE_RATE_LIMITED,带Retry-After;每把 Key 每 60 秒最多换 30 次)、上游出错、连不上都抛kind为network的ChatSdkError,不算会话过期,否则一次上游抖动就会让所有开着的页面提示「登录已过期」。
见错误与会话过期。
- 你的服务端回
不换短期令牌:由你的服务端转发
不换短期令牌时,可以让 SDK 的 baseUrl 指向你自己的服务端,由它把请求转发给 OpenMax,转发时加上当前用户自己的 Key(Authorization: Bearer cwpat_…)。浏览器里始终没有 Key。
getToken交你自己站点的令牌,你的服务端认出是哪个用户,换成这个用户的 Key 再转发。不要用一把 Key 转发多个用户的请求,也不要转发未登录的请求。- 这种做法没有实时:实时连接只认短期令牌,Key 本身会被拒。用
realtime: "off",别人的新消息要刷新才看得到。 - 只转发 SDK 用到的接口路径(列白名单),别的一律拒掉;转发前去掉浏览器带来的
Authorization,换成 Key。 - 不要把
Authorization请求头写进日志;Key 也不要放进NEXT_PUBLIC_、VITE_这类会打进前端包的环境变量。 - 附件的上传、下载地址由 OpenMax 直接给出,不经你的服务端,照部署要求放行。
只给 Key 主人自己用的内部页面
只有在页面只给 Key 的主人自己用时(例如自己的调试页),才可以把 Key 放进浏览器,getToken 直接返回 Key。三条都要满足:页面只有你本人打开;Key 只勾聊天要的权限(见要勾哪些权限);有效期设短。实时连接不认 Key 本身,这时用 realtime: "off"。
src/chat-host.ts
import { createChatHost } from "@openmaxai/chat-openmax/react";
export const host = createChatHost({
baseUrl: "https://openmax.com",
realtime: "off", // 实时连接不认 Key 本身
auth: { mode: "token", getToken: async () => apiKey }, // cwpat_…,只限本人用的页面
orgId: currentOrgId, // 必传
});
要勾哪些权限
创建 Key 时选「聊天」预设,一键勾齐下表里聊天要的权限,只有改群资料与成员(messages:conversation:write、messages:conversation.member:write)和切模型(agents:model:write)不在里面,要用就另外勾。
Key 只能调它勾选了权限的接口。最省事的是勾 messages:read、messages:write 两个大项,再按用到的功能补下面几项:
| 功能 | 权限 |
|---|---|
| 会话列表、成员、消息、已读与未读、增量同步 | messages:read(含 messages:conversation:read、messages:conversation.member:read、messages:message:read、messages:read_state:read、messages:sync:read) |
| 发消息和附件、编辑撤回、表态、卡片作答、标已读、免打扰和置顶、发起私聊和建群、改群和成员 | messages:write(含 messages:message:send、messages:message:write、messages:reaction:write、messages:card:interact、messages:read_state:write、messages:conversation.preference:write、messages:conversation:create、messages:conversation:write、messages:conversation.member:write) |
| 当前用户 | org:me:read |
组织成员的名字、头像、@ 候选 |
org:member:read |
# 工作项 |
work:project:read |
| 消息里的产物链接 | kb:artifact:read |
| Agent 私聊的模型名、切模型 | agents:model:read、agents:model:write |
换短期令牌和实时连接还要下面几项,「聊天」预设里都有:
org:token:exchange:用 Key 换短期令牌。换出的令牌不带这一项,不能拿令牌再换。messages:realtime:connect:用换出的短期令牌申请实时连接。它在messages:read大项里,勾了大项就有。messages:typing:read、org:presence:read、agents:activity:read:实时收正在输入、在线状态、Agent 执行过程。勾大项不会带上这三项,不用预设时要单独勾。
401 和 403
401:令牌或 Key 过期、被吊销、被轮换掉,或者无效。getToken回的是{ token, expiresAt }时,只有AUTH_TOKEN_EXPIRED会让 SDK 再要一次,其它401直接以unauthorized失败。否则 SDK 照令牌与过期的流程用getToken({ refresh: true })再要一次:换短期令牌时去你的服务端换一张新的;转发或直接用 Key 时 Key 不能续期,原样返回即可。重发仍是401就以kind为unauthorized的ChatSdkRequestError失败;Key 本身失效时,请 Key 的主人换一把。403:Key 有效,但没勾这个操作要的权限。错误的code是AUTH_PAT_INSUFFICIENT_SCOPE,kind是forbidden;缺哪一项写在响应体的meta.required_scope里。403不会触发续期,也不算会话过期。
吊销或轮换 Key 在下一次请求就生效:后端每次请求都查 Key 是否还有效,用它换出的短期令牌从下一次请求起也不能用;已经建立的实时连接约 1 秒内断开;用户被移出组织时,他在这个组织的实时连接也一样约 1 秒内断开。SDK 收到这种断开按凭据失效处理:不再重连,以 kind 为 unauthorized 的错误报一次,宿主照凭据失效处理(调 onUnauthorized,没给时提示一次「登录已过期」,见错误与会话过期)。
实时连接
- 实时连接要用换出的短期令牌申请(换令牌的 Key 要勾
messages:realtime:connect),新消息实时出现;Key 本身申请实时连接会被拒(403,code为AUTH_REALTIME_REQUIRES_EXCHANGED_TOKEN),转发和内部页面两种做法都只能用realtime: "off"。 - 短期令牌到期时,服务端关掉用它建的实时连接,SDK 照常重连:换票先挨一次
401,换到新令牌后重新连上,用户感觉不到。 - 申请实时连接被拒(
403)时 SDK 停止重连,经错误事件(适配器的sink.error)只报一次,kind为forbidden。它不算会话过期:不续期、不调onUnauthorized、不提示「登录已过期」。实时不会自己恢复:给 Key 补上权限后,要新建宿主(或刷新页面)才会重新连上。 - 实时连接按短期令牌的权限过滤事件,缺哪项就收不到那类事件:消息、成员变化、已读要
messages:read里对应的那几项,正在输入、在线状态、Agent 执行过程要上面单独列的三项,自己发「正在输入」要messages:message:send。 - 不需要实时的场景用
realtime: "off",别人的新消息要刷新才看得到。
销毁
host.dispose();
关闭 WebSocket 并永久停止重连,销毁后不能恢复。在退出登录或离开页面时调用。 它不适合放在可能重复执行的 effect cleanup 里:开发模式下 StrictMode 挂载时会先跑一次 cleanup。
配置项
| 选项 | 类型 | 必填 | 说明 |
|---|---|---|---|
baseUrl |
string |
是 | REST 基址,不带 /api/v1;OpenMax 是 https://openmax.com。http(s) 绝对地址,或以 / 开头的路径(见服务端渲染与 Next.js)。 |
wsUrl |
string |
与 realtime 二选一 |
实时地址,OpenMax 是 wss://openmax.com/ws:ws(s) 绝对地址,或以 / 开头的路径。不从 baseUrl 推导。 |
realtime |
"off" |
与 wsUrl 二选一 |
只走 REST,不建 WebSocket。 |
auth |
{ mode: "token"; getToken } |
是 | 只支持 token;logto、cookie 抛 ChatSdkConfigError。 |
agentActivity |
boolean |
否 | Agent 执行过程,只读进度(实验性 · 过渡),规划中的 Agent 运行能力落地时替换它。默认 true(realtime: "off" 时也是):实时通道认 agent_activity 帧、回复上的 agent_run 解码成 agent_run_summary;false 时两样都不做,什么都不画。只在适配器一侧,SDK 里没有这个开关。 |
workspaceId / orgId |
string |
否(用个人 API Key 时 orgId 必传;workspaceId 后端不读,可不传) |
作为 X-Workspace-ID / X-Org-ID 发送;X-Workspace-ID 只在页面与 baseUrl 同源时发。 |
locale |
string |
否 | BCP-47。主标签为 en 用英文,其余中文。默认 "zh-CN"。传了 ports.i18n 时忽略。 |
storage |
"memory" | "localStorage" |
否 | 草稿和设备标识的存放处。默认 "memory":不写页面存储,每次加载都算新设备。 |
instanceKey |
string |
否 | 同页两个聊天时区分保存的草稿,仅在 storage: "localStorage" 时跨加载生效。默认 "default"。 |
ports |
ChatSdkPortOverrides |
否 | 整体替换本地能力:render、attention、i18n、navigation、mediaViewer、composerPreferences、localRecords、drafts、attachments、instanceScope。 |
配置不合法同步抛 ChatSdkConfigError(从 @openmaxai/chat-sdk/react 导出),请求失败以 ChatSdkRequestError 拒绝(从 @openmaxai/chat-openmax 导出)。
表情回应、撤回、编辑和修订历史已经接上,别人的表态、编辑、撤回实时出现,被审核删除的消息整条去掉;离线、切走期间别人改过的消息,在重连、切回会话时按改动日志补回来(见实时与同步 · 补洞)。「@我」跳转也已接上:有人 @ 你时消息区右下角出现带计数的按钮,点一下跳到下一条,长按可以全部标已读。已读回执也已接上:自己的消息在单聊里显示对勾、在群里显示「已读 n/m」;回执关闭的会话(读游标接口回 412)不显示回执。卡片能作答,别人的作答实时出现;业务卡的按钮要改用 { adapter } 写法、交 cards.isOperationAllowed 才画。输入框里的 # 工作项也已接上:选中的项目或 Issue 以 [#label](proj://…) / issue://… 引用发出去。Agent 私聊的头部也已接上模型:Owner 看到模型按钮(宿主给了 memberMarks.nameTag 时名字后还有「我的」字签),可以切模型、切模型名是否对别人可见;别人看到只读的模型名。这个宿主提供哪些可选能力(包括名片、群管理)、ports 能替换哪些,见已知限制 · 默认宿主。
部署要求
聊天所在页面的源与 baseUrl 不同(嵌在别的域名下)时,后端要为这个页面的源放行 CORS。同源部署不需要 CORS,但实时连接仍会检查页面的源,见实时连接的部署形态。
直连要先登记页面的源。 页面从自己的源直接调 OpenMax(浏览器 → OpenMax,下面第 2 种)时,OpenMax 只放行登记过的源:没登记的页面既调不通接口,也建不了实时连接。发邮件到 contact@openmax.com 申请登记,写明要登记的页面源(协议、主机和端口);不会对所有源放开。经同源代理接入、并在代理里改写或去掉 Origin(第 1 种)时,REST 和实时连接不用登记,只要上面的 OpenMax 地址;附件见下面两条。
- REST 接口(直连时):每个请求都带
Authorization请求头,浏览器会先发预检(OPTIONS)。预检要放行这个源,并在Access-Control-Allow-Headers里允许Authorization、X-Org-ID(跨域时 SDK 不发X-Workspace-ID)。预检被挡时连当前用户都取不到。 - 附件上传地址(两种形态都要):上传的
PUT由浏览器直接发到服务端返回的upload_url,不经你的代理,存放上传的那一端也要放行这个源的PUT。 - 附件下载地址(两种形态都要):收到的附件地址(
download_url)原样用来显示图片和预览,存放附件的那一端也要放行这个源。
被 CORS 挡下的请求以 status 为 0 的 ChatSdkRequestError 失败,见错误与会话过期。
实时连接的部署形态
实时连接的入口检查 WebSocket 握手的 Origin:Origin 的主机与请求所到的主机相同、Origin 登记过、或者根本不带 Origin(非浏览器客户端)时放行,其余一律回 403,代码为 WS_ORIGIN_NOT_ALLOWED。按你的部署选一种:
同源代理。 页面、
baseUrl、wsUrl都在你自己的源上,由你的服务端转发到 OpenMax。REST 不需要 CORS。代理一般会把Host改成 OpenMax 的主机,而浏览器带的Origin仍是你页面的源,握手就过不了检查。在代理里把Origin改写成 OpenMax 的源或者去掉,是正式支持的做法;也可以像第 2 种那样登记页面的源。代理还要把 WebSocket 升级透传过去(Upgrade、Connection)。nginx 的写法:nginx.conflocation /openmax-ws { proxy_pass https://openmax.com/ws; proxy_ssl_server_name on; proxy_http_version 1.1; proxy_set_header Host openmax.com; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Origin ""; }Origin改写或去掉之后不用登记页面的源;OpenMax 把这条连接当作来自服务端:哪些页面能用你的代理,由你自己把关。直连。 页面从别的源直接调 OpenMax 的
baseUrl和wsUrl。登记页面的源(见部署要求),一次登记同时管 CORS 和实时连接。不接受单独一个*(对所有源放开);*.example.com这样的子域名模式可以登记。建议登记确切的源。
| 现象 | 原因 |
|---|---|
浏览器里 WebSocket 以 1006 关闭 |
握手的 Origin 没通过检查(服务端回的是 403 WS_ORIGIN_NOT_ALLOWED,浏览器读不到,只报 1006):页面的源没有登记(第 2 种),或者代理把浏览器的 Origin 原样透传了(第 1 种) |
独立的 OpenMax 包
OpenMax 相关代码在独立的 @openmaxai/chat-openmax 包里,本页示例都从 @openmaxai/chat-openmax/react 引 createChatHost。从旧写法迁移时,配置不变,导入路径和配置类型名变了:
| 旧写法 | 现在 |
|---|---|
@openmaxai/chat-sdk/react 的 createChatHost 直接收 OpenMax 配置(它现在只收 { adapter },传 OpenMax 配置当场抛 ChatSdkConfigError) |
@openmaxai/chat-openmax/react 的 createChatHost |
ChatSdkConfig、ChatSdkAuth |
OpenMaxChatConfig、OpenMaxAuth |
| — | 一行配置不收 onUnauthorized(已知缺口);要它改用 { adapter: createOpenMaxAdapter(config), onUnauthorized } |
