OpenMax
免费试用

接入 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 只用令牌,不签发也不刷新:

  1. 第一个需要令牌的请求调用 getToken(),结果缓存复用。
  2. 遇到 401 再调一次 getToken({ refresh: true })(这时要真去续期),用新令牌重发该请求一次。
  3. 续不出令牌、或重发仍是 401,则以 ChatSdkRequestError 失败。怎么续期由你负责;续期接口断网时抛 kind 为 network 的 ChatSdkError,请求就以 network 失败、不算会话过期。getToken 30 秒内没结果按 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 里列出来。

  1. SDK 要令牌时调你的 getToken,它去问你自己的服务端。
  2. 你的服务端先认清是哪个登录用户,再拿这个用户自己的 Key、带上组织(X-Org-ID)向 OpenMax 换一张短期令牌,把令牌交回浏览器。令牌绑定这个组织,浏览器里的 orgId 要和它一致,不一致时请求以 401 被拒。Key 不出服务端。
  3. 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。按你的部署选一种:

  1. 同源代理。 页面、baseUrl、wsUrl 都在你自己的源上,由你的服务端转发到 OpenMax。REST 不需要 CORS。代理一般会把 Host 改成 OpenMax 的主机,而浏览器带的 Origin 仍是你页面的源,握手就过不了检查。在代理里把 Origin 改写成 OpenMax 的源或者去掉,是正式支持的做法;也可以像第 2 种那样登记页面的源。代理还要把 WebSocket 升级透传过去(Upgrade、Connection)。nginx 的写法:

    nginx.conf

    location /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 把这条连接当作来自服务端:哪些页面能用你的代理,由你自己把关。

  2. 直连。 页面从别的源直接调 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 }

参见 @openmaxai/chat-openmax。