会话头部
会话上方的标题栏,包含标题、状态、正在输入、群信息按钮、Agent 模型切换和规划中的 Agent 运行入口。
会话头部

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): header-group.tsx
"use client";
import { ChatHeader } from "@openmaxai/chat/header";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
import { useState } from "react";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost, useIsCompact } from "./kit";
export default function GroupHeaderDemo() {
const host = useDemoHost();
const { conversations, lang } = useDemoData();
const isCompact = useIsCompact();
const [infoOpen, setInfoOpen] = useState(false);
const group = conversations[0];
return (
<ChatHostProvider host={host}>
<div className="flex h-full flex-col bg-background text-foreground">
<ChatHeader
conversation={group}
headerTitle={group.name ?? ""}
headerSubtitle={lang === "zh" ? "4 位成员" : "4 members"}
isAgentCollab={false}
isObserving={false}
collabAgents={[]}
typingText={null}
mode={isCompact ? "compact" : "full"}
infoPanelOpen={infoOpen}
// Without this callback the header draws no info-panel button.
onToggleInfoPanel={() => setInfoOpen((open) => !open)}
/>
<div className="flex min-h-0 flex-1">
{/* In a row, the thread must fill the remaining width itself, or it shrinks to its content and no longer lines up with the header. */}
<div className="flex min-w-0 flex-1 flex-col">
<MessageThread conversation={group} />
</div>
{infoOpen && (
<aside className="w-56 shrink-0 border-l p-4 text-muted-foreground text-sm">
{lang === "zh"
? "infoPanelOpen 为 true 时,在这里放你的群信息面板。"
: "infoPanelOpen is true: put your group info panel here."}
</aside>
)}
</div>
</div>
</ChatHostProvider>
);
}
演示使用内存宿主(useDemoHost)。实际项目里宿主来自 createChatHost,ChatHeader 只需放在它的 Provider 里。
何时使用
- 放在
MessageThread上方。MessageThread不自带头部。 - 标题、副标题、徽标等由应用算好传入,头部不判断会话类型。
trailing插槽可放自己的控件,比如浮窗的最小化 / 关闭。
代码示例
第一节用 SDK 的 ConversationHeader;其后各节用的是 @openmaxai/chat/header 的 ChatHeader,它不带样式根:SDK 样式表只作用在 SDK 组件自带的 .omx-chat 组件根之内,ChatRoot 本身不是样式作用域,所以照抄出来没有样式。要用它,把它放进 ChatRoot,再在外面包一层带 omx-chat 类的元素(深色时另加 omx-dark,并给 ChatRoot 传 colorScheme="dark"),或者自己出样式;用 createChatHost 的宿主时用 ConversationHeader。只包一层不够:对话框、菜单、浮层不在 ChatRoot 里时落到 document.body,在你包的那层之外,拿不到样式;在 ChatRoot 里时它们落在 ChatRoot 带 omx-chat 类的落点上。
SDK 的会话顶部栏

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): header-sdk.tsx
"use client";
import {
ChatProvider,
ConversationHeader,
CwsMessageThread,
createChatHost,
} from "@openmaxai/chat-sdk/react";
import { createMemoryAdapter } from "@openmaxai/chat-sdk/testing";
import { useEffect, useMemo } from "react";
// Docs helpers: page language and the toast line at the bottom of the demo.
import { useDemoData, useDemoNotify } from "./kit";
export default function SdkHeaderDemo() {
const { lang, members } = useDemoData();
const notify = useDemoNotify();
// In your app the host comes from createChatHost() with your adapter. The memory adapter
// implements `conversations.setMuted`, so the header shows the mute toggle.
const host = useMemo(
() =>
createChatHost({
adapter: createMemoryAdapter({
me: members[0],
people: members.slice(1),
conversations: [
{
id: "design",
name: lang === "zh" ? "设计评审" : "Design review",
messages: [
{
senderId: members[1]?.memberId ?? "me",
text: lang === "zh" ? "稿子发群里了" : "Mockups are in",
},
],
},
],
}),
locale: lang === "zh" ? "zh-CN" : "en",
ports: { attention: { notify, setUnreadSignal: () => {} } },
}),
[lang, members, notify],
);
useEffect(() => () => host.dispose(), [host]);
const conversation = {
id: "design",
type: "GROUP" as const,
name: lang === "zh" ? "设计评审" : "Design review",
created_at: "2026-10-01T00:00:00Z",
last_message_at: "2026-10-01T00:00:00Z",
unread_count: 0,
member_count: members.length,
is_observer: false,
};
return (
<ChatProvider host={host}>
<div className="flex h-full flex-col bg-background text-foreground">
{/* Title, member count and mute come from the conversation; on a narrow
screen `onBack` adds a back arrow. */}
<ConversationHeader
conversation={conversation}
onBack={() => notify("info", "onBack()")}
/>
<CwsMessageThread conversation={conversation} />
</div>
</ChatProvider>
);
}
用 createChatHost 时放 ConversationHeader:标题、头像、徽标、成员数从会话数据算,和会话列表那一行同名;读的是列表里同一 id 的最新那一行,静音、成员数、改名后跟着变;这条会话不在已取到的列表里时(已隐藏、从链接打开),静音开关读这次设成功的结果(换到别的会话就不再用它);静音成功后再从链接打开这条会话,读到的是静音后的状态。
conversation-pane.tsx
import { ConversationHeader, CwsMessageThread } from "@openmaxai/chat-sdk/react";
<ConversationHeader
conversation={selected}
onBack={() => setSelected(null)}
trailing={<MyButton />}
/>;
<CwsMessageThread conversation={selected} />;
- 静音:宿主有
conversations.setMuted(OpenMax 适配器已接)时出现开关,旁观的会话没有;失败时经attention.notify提示。 - 返回:窄屏(视口窄于 768 px)且传了
onBack才有返回键。一次一栏的布局用ChatSplitLayout;浏览器后退要你的应用自己接历史。 - 群信息:传
onToggleInfoPanel才有按钮,只在群聊里。Chat SDK 的ConversationHeader另要宿主有groupManagement、会话不是旁观,否则传了也不画。trailing画在最右侧。 - 正在输入与对端在线状态:副标题那一行画正在输入;与 Agent 单聊时画对端的在线状态(来自成员资料与
presence信号,状态不知道时不画、不猜「离线」,对方计费停机时照旧画「暂停 · 欠费」)。还没有的见已知限制。属性见 API 参考。
群聊
conversation-header.tsx
import { ChatHeader } from "@openmaxai/chat/header";
<ChatHeader
conversation={conversation}
headerTitle={titleFor(conversation)}
headerSubtitle={`${memberCount} 位成员`}
isAgentCollab={conversation.type === "BRIDGE"}
isObserving={conversation.is_observed === true}
collabAgents={[]}
typingText={null}
infoPanelOpen={infoOpen}
onToggleInfoPanel={() => setInfoOpen((v) => !v)}
/>;
信息按钮用来打开 ChatInfoPanel,只在 GROUP 会话且传了 onToggleInfoPanel 时出现。
带模型切换的 Agent 单聊

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): header-agent-dm.tsx
"use client";
import { ChatHeader } from "@openmaxai/chat/header";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { AGENT, useDemoData, useDemoHost, useIsCompact } from "./kit";
export default function AgentDmHeaderDemo() {
// The demo host provides `agentConfig` (model selector) and `profileCard` (clickable avatar).
const host = useDemoHost();
const { conversations } = useDemoData();
const isCompact = useIsCompact();
const dm = conversations.find((c) => c.id === "helper");
if (!dm) return null;
return (
<ChatHostProvider host={host}>
<div className="flex h-full flex-col bg-background text-foreground">
<ChatHeader
conversation={dm}
headerTitle={dm.name ?? ""}
headerSubtitle={null}
isAgentCollab={false}
isObserving={false}
collabAgents={[]}
dmPeerStatus="online"
typingText={null}
mode={isCompact ? "compact" : "full"}
infoPanelOpen={false}
// Your own agent: the header shows the model selector for it.
isAgentOwnerDm
agentModelMemberId={AGENT}
/>
<MessageThread conversation={dm} />
</div>
</ChatHostProvider>
);
}
你和自己名下 Agent 的单聊里,头部可以切换模型、设置模型名是否对他人可见。
<ChatHeader
/* …必填 props */
isAgentOwnerDm
agentModelMemberId={agentMemberId}
/>
不传 agentModelMemberId 就不画。数据来自宿主的 agentConfig 能力:
agent-config.ts
import type { ChatAgentConfigPort } from "@openmaxai/chat/host";
export const agentConfig: ChatAgentConfigPort = {
async loadModelState(agentMemberId) {
const res = await api.getAgentModel(agentMemberId);
if (!res.ok) return undefined; // 头部会显示禁用的占位控件
return {
effectiveModel: res.body.active,
desiredModel: res.body.requested,
applyState: res.body.pending ? "applying" : "ready",
visible: res.body.public,
configurable: res.body.canEdit,
availableModels: res.body.choices.map((c) => ({ key: c.id, displayName: c.label })),
};
},
setModel: (agentMemberId, model) => api.setAgentModel(agentMemberId, model),
setModelVisibility: (agentMemberId, visible) => api.setAgentModelVisibility(agentMemberId, visible),
};
- 读不到模型时
loadModelState返回undefined,不要抛错。 setModel返回只代表已受理。头部会重新读取状态,applyState变回ready前一直显示「应用中」。- 别人的 Agent 改传
dmPeerModelLabel,显示只读模型名。
用 @openmaxai/chat-sdk 时,适配器的 agentConfig 是同一个类型,SDK 自有名为 ChatSdkAdapterAgentConfig,适配器不必从 @openmaxai/chat/host 引。
单栏布局和浮窗
<ChatHeader
/* …必填 props */
mode="compact"
onBack={() => setSelectedId(null)}
trailing={<WindowControls />}
/>
传了 onBack 才显示返回箭头,显示不显示由你决定,比如只在一次只显示一栏的布局里传。头部的排版跟随所在容器的宽度,不需要告诉它是不是移动端,见响应式。
头部在盖住应用弹层的浮层里时,传 overlayContainer,让它的浮层渲染在这一层里。
Agent 运行入口
规划中
宿主提供 agentRuns 能力后,头部为每个有未结束运行的 Agent 显示一个入口,如「助手 · 2 个进行中 · 1 个排队中」。点开是这个 Agent 在本会话里的运行列表(AgentRunList)。
今天:执行摘要(过渡)
过渡
上面的运行入口落地之前,用 Chat SDK 时头部已有一句执行摘要,属只读进度(实验性 · 过渡)。宿主的 agentActivity 里这条会话有进行中(排队中、思考中、调用工具中)且没失联的 run 时,ConversationHeader 把它显示在副标题的位置,有人在输入也先显示它;run 全部结束(终态、失联、淘汰、作用域结束)后回落到下面的「正在输入」。ChatHeader 自己不算,文字同样经 typingText 传进来。
| 进行中的 run | 显示(chat 命名空间的 key) |
|---|---|
| 一个,排队中 | 「助手 等待处理」(agentRun.header.queued);当前用户参与的单聊里不带名字:「等待处理」(agentRun.state.queued) |
| 一个,处理中 | 「助手 处理中」(agentRun.header.working);当前用户参与的单聊里不带名字:「处理中」(agentRun.state.working) |
| 同一个 Agent 的两条及以上 | 「助手 处理中(2 条)」(agentRun.header.workingCount),都在排队时「助手 等待处理(2 条)」(agentRun.header.queuedCount);当前用户参与的单聊里不带名字:「处理中(2 条)」(agentRun.state.workingCount)/「等待处理(2 条)」(agentRun.state.queuedCount) |
| 两个及以上的 Agent | 「2 个 Agent 处理中」(agentRun.header.many),数的是不同的 Agent,不是 run |
名字取这条会话的成员,查不到时是「未知成员」。头部只给固定状态,不写 Agent 正在做的具体动作,动作在消息区的执行过程块里。规划中的 Agent 运行能力落地时由上面的运行入口替换它。
正在输入
会话里有当前用户以外的人在输入时,头部副标题的位置显示「正在输入」,压过对端状态与副标题。ChatHeader 自己不算:文字由 typingText 传进来;用 Chat SDK 时 ConversationHeader 替你算好(数据来自适配器 realtime 交的 typing 信号)。
| 谁在输入 | 显示(chat 命名空间的 key) |
|---|---|
| 当前用户参与的单聊里的对方 | 「正在输入…」(typing.peer) |
| 其余:一个人 | 「张三 正在输入…」(typing.one,名字查不到时是「未知成员」) |
| 其余:两个人及以上 | 「3 人正在输入…」(typing.many) |
- 只算别人。 自己在别的标签页或设备上输入不显示;当前用户还不知道(
GET /me没回)时谁都不显示。 - 会自己过期。 最后一声「开始」之后 6 秒没有新的就去掉;收到「停止」立即去掉。对方发了消息不会提前收起。
- Agent 照样显示。
- 旁观者看不看得到以后端为准:OpenMax 目前只把
typing发给会话成员。 - 自己打字别人看不到:Chat SDK 还不发
typing,见已知限制。
数据来自 typing 信号,见实时与同步 · 实时信号。会话列表的行上不显示「正在输入」。
API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
conversation |
ChatConversation |
必填 | 当前会话 |
headerTitle |
string |
必填 | 标题 |
headerSubtitle |
string | null |
必填 | 副标题;Agent 单聊里改为显示 Agent 状态 |
isAgentCollab |
boolean |
必填 | Agent 协作会话,显示协作的 Agent |
isObserving |
boolean |
必填 | 当前用户在旁观(只读) |
collabAgents |
CollabAgent[] |
必填 | 协作会话里显示的 Agent |
typingText |
string | null |
必填 | 「正在输入」的文字,见正在输入;null 不显示 |
infoPanelOpen |
boolean |
必填 | 信息按钮的按下状态 |
dmPeerStatus |
OnlineStatus |
— | 单聊对方的在线状态 |
peerStatusAvailable |
boolean |
true |
有没有对方的在线状态。false 时 Agent 单聊的状态行只在对方计费停机时显示,不显示「离线」 |
mode |
"full" | "compact" |
"full" |
密度,只影响间距。移动端和浮窗用 compact |
showIdentity |
boolean |
true |
画不画会话的头像与名字。停靠列给 false(标签上已有),其余元素照常 |
inlineMeta |
boolean |
false |
副行(正在输入 / 对端状态 / 副标题)与徽标 / 模型排进同一行、不换行,副行在前;名字(画身份时)独占上面一行。停靠列与抽屉给 true;放不下时徽标与模型名截断,不换行 |
onBack |
() => void |
— | 返回箭头回调;传了就显示返回箭头 |
onToggleInfoPanel |
() => void |
— | 群信息按钮;不传则无按钮,传了 onToggleInfoSidebar 时也没有 |
onToggleInfoSidebar |
() => void |
— | 会话信息侧栏按钮,所有会话类型都有,代替群信息按钮;不传则无按钮。@experimental |
infoSidebarOpen |
boolean |
false |
侧栏开没开:按钮的按下态与 aria-expanded |
infoSidebarId |
string |
— | 侧栏元素的 id;开着时作为按钮的 aria-controls |
isMuted |
boolean |
false |
已静音:开关画划线铃铛 |
onToggleMute |
() => void |
— | 静音开关回调;不传则无开关 |
muteDisplay |
"toggle" | "marker" |
"toggle" |
静音怎么画:"toggle" 常驻铃铛;"marker" 不画铃铛,只在已静音时名字旁出现「已静音」,点它调 onToggleMute(取消静音)。只对群聊生效,其他会话照旧是铃铛。会话信息侧栏打开时用。@experimental |
memberCounts |
{ people: number; agents: number } | null |
null |
群里的人数与 Agent 数。群聊且同时给了 onOpenMembers 时,标题下方的人数画成「N 人 · N 个 Agent」两个按钮;否则副标题照给的画。@experimental |
onOpenMembers |
(tab: "people" | "agents") => void |
— | 点了上面两个数中的一个:在成员列表的对应页打开。@experimental |
onOpenPeerInfo |
() => void |
— | 给了 ⇒ 单聊里对端的头像和名字是调它的按钮(打开会话信息侧栏并停在「信息」tab),不再弹对端名片。旁观的单聊也接(与名片不同,侧栏是它的只读视图);与系统成员的私聊、Agent 协作会话和群聊不接。@experimental |
onPopOut |
() => void |
— | 「弹出成浮窗」按钮,排在静音 / 群信息之后;不传则没有。这里能不能开浮窗由你判断 |
isAgentOwnerDm |
boolean |
false |
当前用户是单聊里 Agent 的主人:显示主人徽标,启用模型切换 |
agentModelMemberId |
string |
— | 要配置模型的 Agent 成员 id,仅 isAgentOwnerDm 时读取 |
dmPeerModelLabel |
string | null |
— | 与他人 Agent 单聊时的只读模型名 |
badge |
ChatHeaderBadge | null |
null |
标题旁的徽标 { label, bg, color } |
trailing |
ReactNode |
— | 最右侧插槽 |
rootProps |
ComponentPropsWithoutRef<"div"> |
— | 根元素额外属性;className 会合并 |
overlayContainer |
HTMLElement | null |
— | 浮层和对话框的挂载点 |
CollabAgent 是 { name: string; online_status?: OnlineStatus | null },OnlineStatus 是 "online" | "starting" | "stopping" | "offline" | "error" | "unknown"(和数据模型里成员的 online_status 相同)。两个类型都从 @openmaxai/chat/header 导出 规划中。
依赖的能力
| 能力 | 缺了会怎样 |
|---|---|
agentConfig |
主人单聊里模型切换处显示禁用的占位控件 |
profileCard |
单聊头像和名字不可点,见名片 |
agentRuns 规划中 |
没有 Agent 运行入口 |
适配器的 realtime(typing / presence 信号,ConversationHeader) |
没有就不显示「正在输入」,Agent 单聊的在线状态只来自成员资料、不随上下线实时变 |
适配器的 profiles(ConversationHeader) |
Agent 单聊的在线状态要等第一声 presence 信号才出现;两样都没有时状态行只在对方计费停机时出现 |
无障碍
- 返回按钮、主人徽标按钮和模型切换按钮都有标签。模型切换生效前带
aria-busy,失败用role="alert"提示。 - 群信息按钮只有图标,用
aria-label给出无障碍名称。规划中 - 「正在输入」与对端状态不进实时播报区域:变化不播报,读屏用户读到头部时能读到这行文字。
常见问题
信息按钮没出来。
需要 GROUP 会话,并传 onToggleInfoPanel。
模型切换没出来或是灰的。
isAgentOwnerDm 和 agentModelMemberId 都要传。灰色说明宿主没有 agentConfig、loadModelState 返回了 undefined,或状态里 configurable: false、availableModels 为空。
