OpenClaw 多用户模式：共享同一 Agent 时的会话归属、在线状态与 @提及机制-平芜编程栈

OpenClaw 多用户模式：共享同一 Agent 时的会话归属、在线状态与 @提及机制

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

多用户（Multi-user）模式让多名可信操作者共同操作同一个 OpenClaw agent：它通过会话所有者归属、参与者历史、实时在线状态和所有者过滤，帮助团队看清"谁发起了工作、现在谁在负责、谁参与过"。读完本篇，你将掌握三层归属模型（Creator / Owner / Participants）的设计原理、sessions.assignOwner的授权链路、按人筛选会话与 People 卡片、@提及收件箱（Mentions Inbox）、Agent 派生会话归属，以及按人登录模型账号（personal model accounts）的完整配置路径与凭据存储位置。

信任边界：多用户不等于隔离

所有能够操作该 agent 的人，都能让 agent 做它所能做的任何事。会话所有权、侧边栏可见性和在线指示器都是可用性功能，而非安全边界。如果人与人之间不能互相访问对方的会话、工具、凭据或文件，应使用独立的 agent 或独立的 gateway/host 信任边界，而不是依赖头像或过滤器来隔离。

两个容易误判的点：

已通过认证的 Control UI 管理员（operator.admin）可以在该 Gateway 上以对话方式管理任意自动化任务（包括来自其他渠道或其他人创建的任务），这一权限来自被允许的管理员回合，而不需要将渠道身份与 Gateway 档案匹配；但它不转移任务的创建者归属或计划执行策略（详见 cron-jobs 的对话式管理）。
共享 Gateway 始终是一个信任域：会话、工具、凭据、文件都在同一域内，身份化便捷状态不改变操作者作用域（operator scopes）控制的授权结果（详见 Gateway security）。

会话公开链接：可见性 ≠ 公开

对已认证人员可见，与允许公开读取转录，是两回事：

将会话在Shared、Read-only、Suggest、Draft之间切换，只控制已登录人员；这些设置都不会产生公开链接。
只有会话创建者或Gateway 管理员可以显式开启Public access。任何持有生成的 bearer URL 的人都无需登录即可读取现有与未来的对话文本，但工具调用、推理内容、文件、图片、widget、隐藏消息与内部元数据均被排除。
变更所有者不会转移公开授权；关闭 public access 会撤销该发布下的所有 URL，但已下载的副本无法收回。

用户操作流见公开分享会话，安全与部署契约见公共会话转录。

三层归属模型：Creator、Owner、Participants

每个会话最多携带三层归属信息：

Creator（不可变）：创建路径能证明"谁触发了创建"时，新会话会记录一次写一次的createdActor。人类创建者保留其来源：已验证的 Gateway 档案、渠道发送者，或未知的历史归属。只有档案创建者才能获得隐式的创建者访问权（包括通过已验证档案合并）。仅凭渠道、agent 或系统 ID 匹配不能识别这个人。共享与可见性权限始终锚定在创建者上，即使 owner 变更也不改变。
Owner（可指派）：当前对会话负责的人或 agent，类似 GitHub issue 的 assignee。默认为创建者，随时可以改派；改派会记录"谁在何时改派"。侧边栏头像、owner 过滤器和按人排序都跟随当前 owner。
Participants（历史）：其输入被会话接受的已认证人员、渠道发送者与请求方 agent。会话自身的 agent 和被动观看者不会被记录。新身份准入上限为每个会话 32 条记录，修复逻辑可以保留更大的既有历史。参与记录是后台尽力而为的，从不延迟回合。

展示名称与头像在返回会话行时从当前档案解析；参与者聚合不存储显示标签，因此重命名档案或 agent 时无需重写参与者历史即可更新归属 UI。

指派 Owner：UI 操作与 Gateway 方法

Control UI 中，对侧边栏行（或聊天头部）使用上下文菜单（kebab / 右键），可以看到：

Assign to me：由自己接手该会话。
Assign to…：选择任意已注册的人或已配置的 agent，包括离线的人和从未拥有过会话的人。选项在打开菜单时刷新，不依赖会话过滤器或归档状态。

Agent 也可以通过sessions工具重新指派归属：使用action: "assign_owner"，配合ownerType（"human"或"agent"）与ownerId；默认指向当前会话，也可以通过sessionKey指向其他可见会话。

两条路径最终都调用 Gateway 方法sessions.assignOwner（需要operator.write作用域）。从源码看，sessions-mutations.ts 中的实现印证了文档契约：

先解析调用者身份：优先取受信 agent 身份（runtime 或工具调用方 agent），否则取人类档案；两者皆无时直接返回FORBIDDEN: "sessions.assignOwner requires an identified caller"——即文档强调的"指派需要已识别的调用者"。
通过会话可见性过滤器（createSessionListEntryFilter）做授权，不可见的会话返回FORBIDDEN: "session is not visible to this connection"。
写前用assertCurrent复检会话是否已被改动（sessionId / storeKey / 可见性），变了就要求重试，防止竞态下的越权写入。

指派成功后，头像提示从 "Created by" 变为 "Owned by"。需要再次强调：改 owner 只改变责任与显示，不转移共享权限（仍属于创建者），也不授予或移除任何访问权。

此外，Creator 来源会跟随计划任务与继承的创建策略：强制沙箱是限制而非档案身份的证据；历史自动化即使丢失了创建者来源也保留其归属，但不会获得推测性的档案授权；指派 owner 不会"修复"创建者权限。升级前请参阅 Creator namespace migration。

按人登录模型账号（Per-person model accounts）

每个人可以以自己的 Gateway 档案登录一个模型账号；其新建的会话会优先使用该账号，而不是 Gateway 默认账号。可用的 provider 与登录方式来自 Gateway 的 provider 插件。选择账号不保证每一回合都计费到该账号。

这里有两个"登录"：Gateway 识别你是谁，然后 provider 授权你的模型账号。CLI 与 Web UI 使用同一套个人账号存储；共享服务器不会把个人登录变成共享凭据。系统/agent 凭据是独立范围，通过运行该 OpenClaw 实例的机器上的models auth管理。

四个账号概念

概念	含义
Saved account	属于你 Gateway 档案的凭据；同一 provider 可保存多个。
New-chat default	你新建聊天时偏好的已保存账号；修改它不会重新固定已有聊天。
Chat selection	某个聊天已经选定的账号；其他人和 fork 沿用该选择。
Sign-in attempt	临时的、可取消的操作；登录成功前不保存任何账号。

添加账号

打开Settings → Profile → Connected accounts，选择Add account，然后选 provider 与登录方式。添加账号需要带operator.write的已识别连接。

Anthropic接受个人使用的 API key（不接受 Claude 订阅 token）。
OpenAI提供 API key、ChatGPT/Codex 浏览器登录与设备码登录。
Grok (xAI)提供 API key 与设备登录。

选择器只显示该 Gateway 上启用于个人账号的 provider 方式；凭据或授权码要使用受保护输入框。浏览器回调可能在输入框打开时完成，需保持 Profile 连接直到报告结果。保存凭据与验证一次成功的模型请求是两件事。

添加前先检查Gateway、Person、Scope: Personal三行。账号归属跟随 Gateway 分配的档案，而不是未保存的显示名编辑。单用户连接可以使用持久的Owner档案；使用同一档案的所有设备会共享其账号。要在共享服务器上区分人，请使用 Gateway 的带身份端点；若未分配档案，该区域会说明缺少什么并链接到Connection settings，而不是显示凭据输入框。浏览器身份不会转移到 CLI，参见 personal-account CLI setup。

页面以友好标签列出已保存账号并标注 new-chat default；选择另一个已保存账号即可在不重新登录的情况下改默认值；Load more用于翻页更大的账号列表；Use Gateway defaults for new chats清除个人默认值（账号仍保留）。页面会将登录操作报告为 pending / connected / cancelled / expired / failed；Cancel会让 Gateway 终止该操作（包括已在进行中的 exchange）。断连、失去权限或重启 Gateway 都会阻止未完成的登录发起新的 provider 请求或保存凭据。

为聊天选择账号

在New session或现有聊天中打开模型菜单，展开Account类别即可为所选 provider 选择你的已保存账号。当Automatic没有可用模型时，账号选择器仍然可用。在 New session 中，选择账号会先预览可用模型；该选择只作用于你创建的会话，还可以用于草稿标题准备，不改变你的 new-chat 默认或已保存模型偏好；换账号会丢弃旧标题建议。在已有聊天中，换账号只改该聊天的选择。

账号控件对他人个人账号只显示人级标签，不显示其私密邮箱、provider 账号标签或账号 id——该标签描述选择本身而非计费回执，因为配置好的共享 failover 账号仍可能被使用。聊天状态与模型列表将所选个人凭据标识为personal account，但不暴露其私密标签、邮箱或账号 id。

CLI 与 Custodian 路径

CLI 通过openclaw models accounts走同一套 Gateway 操作：openclaw models accounts login交互式选择 provider 与方式，或直接用login <provider> --method <id>；list查看已保存账号。每条命令都会显示所选 Gateway、已验证的人与 Personal 作用域；目标是你这个人，而不是--agent或操作系统用户名。

向 OpenClaw（Custodian）提问需要管理员访问与可用推理路由；让它管理你的个人模型账号，或输入model accounts。在 Control UI 中它会打开Settings → Profile → Connected accounts，在终端中给出 CLI 命令；托管本身不做任何变更。登录必须在受保护控件或隐藏终端提示中完成，绝不要在对话中完成；被委托的 agent 请求无法打开或完成人类登录流程。

凭据存储位置

凭据与所选链接一起保存在共享状态数据库（Gateway 状态目录下的state/openclaw.sqlite）中私有的、身份作用域的记录里——没有第二个账号数据库或 JSON sidecar。待处理登录操作只存在于 Gateway 内存。凭据不会进入共享或 agent 本地 auth store、不会被复制进全局运行时快照、也不参与自动账号轮换。重新连接只替换该人拥有的凭据；对 ChatGPT，仅匹配 workspace 不够，provider 还必须识别出同一用户；管理员关联的共享账号永远不会被个人重连覆盖。

管理员仍可通过 CLI 创建共享档案（如openclaw models auth login --provider openai --profile-id openai:alice，见 OAuth）并用users.linkAuthProfile关联；users.unlinkAuthProfile保持"本人或管理员"，users.listAuthLinks只返回链接元数据而不含机密。个人凭据不能链接到他人档案。

Pin 与默认规则

当关联的人创建会话时，OpenClaw 会把其默认账号捕获为该会话的 auth 选择，其效力等同于/model ...@profilepin；这发生在首条消息派发之前（即使创建与首条消息是两次独立请求）。通过 turn admission 首次创建的会话在该 admission 时捕获默认值。该 pin 是会话粘性的：其他进入该会话的人使用其选定账号，fork 也会继承；显式/model ...@profile -spin 优先级更高。新个人选择必须属于执行该操作的已认证人类——知道别人的账号 id 不等于有权选择它。agent 与渠道来源的回合不会产生个人链接。对于使用 OpenClaw auth fallback planner 的运行时，同 provider 的有序共享档案在 pin 账号失败时仍是 failover 候选；Claude CLI 则严格要求其选定账号，不会用共享档案或原生登录替代。

Use Gateway defaults for new chats、CLIclear-default与 APIusers.unlinkAuthProfile只影响未来会话：改默认不会重新固定已有聊天（包括使用共享凭据的未固定聊天）；接手或 fork 已有聊天不会应用当前参与者的默认值；清除默认既不删除已保存凭据也不撤销 provider token——若必须让既有会话停用它，请到 provider 侧撤销。链接与既有会话凭据跟随已验证档案合并，但对幸存档案上的显式 unlink 不会被合并逆转。

这是单一信任域内的账号选择便利，而不是对管理员或 Gateway OS 用户代码的隔离。在兼容性降级时，旧版本不会把个人凭据发现为共享默认；个人账号选择将在支持版本恢复前不可用。

按 Owner 查找会话

侧边栏会话过滤器在归属可见时会多出Owners区：

All owners：显示全部（默认）。
某个具体的人或 agent：显示其当前拥有的会话。
Involving me：显示你拥有的会话，加上你至少 prompt 过一次、且 Gateway 会针对完整参与者历史求值的会话。它只匹配你已认证的档案身份；渠道原生发送者 id 仅用于显示、永不匹配，因此数字渠道 id 不可能与你的档案冲突。

Involving me要求已登录 Gateway 档案。当已加载会话有多个 owner 时，Group by Person会为每个当前 owner 建一个分节；Owners排序模式按名称对 owner 组排序。

读懂头像：归属与在线状态的区别

Control UI 刻意把归属与在线状态在视觉上区分开：

会话行上的实心 owner 头像在该会话生命周期内恒定显示当前 owner；owner 离线时头像略变暗。
当其他人/agent 曾 prompt 该会话时，行头像变为pair-stack：owner 在最前，另一名参与者从后面探出，或多名参与者以+N汇总。聊天头部显示 owner chip 加最多四个头像的参与者 facepile；owner 本人不计入参与者显示。
带环或半透明的在线头像表示当前连接中或在旁观的人，来自实时 presence 而非归属，观众离开即消失。已被 owner/参与者头像显示的人不会在同一表面重复为 live viewer；被+N汇总的参与者仍可单独以 live viewer 出现。
在Group by Person下，分节标题中的 owner 头像在该人连接时显示小绿点，闲置数分钟后淡出，离开时消失；你自己的分节永不显示。

多人同时观看同一会话时，转录区还显示实时"正在输入"指示：Control UI 中打字的人会把草稿以较淡的已发消息气泡样式流式显示（同一发送者身份、光标与Typing · not sent标签），其他人则显示三点气泡。草稿是临时 presence：永不持久化、永不进入会话转录或模型上下文，在打字者停顿或发送后短暂淡出。

当已加载会话列表中没有两个以上不同的 owner 身份、且没有任何会话记录过外部参与者时，OpenClaw 会隐藏全部归属与 owner 过滤 UI——单用户 Gateway 看起来完全不变。

People 卡片（People cards）

点击或点按侧边栏Online区的人，可打开其 Activity 页面；悬停或聚焦该行打开信息卡片，卡片中View activity打开同一页面。无档案的普通观看者没有 Activity 页，点击只打开卡片（含连接细节与可见的观看中会话）。在Group by Person下，他人分节标题的头像与名字打开同一卡片；chevron 仍是折叠分节。未连接的 owner 显示带Offline标记的卡片，只有其最近会话与 Activity 链接。

卡片显示该人持续连接时长、其上报的 app/设备上下文与时区，以及该在线期间最后观察到的活动：打开另一会话、打字、发送新消息都算活动，连接心跳与 agent 回复不算。Not observed yet表示尚未记录到符合条件的活动，而非该人不活跃。这些时序事实是临时的，在该人最后连接关闭或 Gateway 重启后重置。

人员 presence 对所有具有读访问（operator.read，也被operator.write/operator.admin隐含）的操作者共享；这些读取者无论某人是否在看会话，都能看到其在线与活动时序及上报时区。Node 与纯配对连接既收不到 presence 清单也收不到其活动事件。参见 Who can see presence。

Viewing now与Recent sessions只链接到你已加载会话列表中可用的会话；recent sessions 要求观看者与 owner/creator 两侧是同一记录在案的档案身份，仅原始 ID 匹配不够；它们不是此人贡献的完整历史；会话更新时间描述的是会话而非该人最后动作时间；连接描述与时区是客户端上报提示，不是经过验证的物理位置。

Gateway 还会按接收者用sessions.list可见性规则过滤其观看中的会话引用（横跨连接快照、presence RPC 响应与事件）；被隐藏或缺失的引用直接省略，不带计数或占位符。打开某人的卡片永远不会"借用"对方的会话访问权。

@提及（Mentioning people）

在普通 Control UI 聊天中输入@并从选择器选人；composer 会显示Will notify与所选接收者。每条消息最多 10 个提及；直接键入或粘贴@name而未选人，只发送普通文本，不会通知任何人。Remove mention清除接收者选择但保留消息文本。

选择器包含已知的、有资格读该会话的 Gateway 档案（含离线者）；在线指示只是连接提示，不是资格前提。要使用人类提及，请使用持久 Gateway 档案登录。提及永不增加会话成员身份、不改变可见性、不授予访问权；Gateway 在创建与显示时都会复核接收者当前的访问权。

提及适用于普通消息、排队或 steering 输入，以及新会话（包括远程放置的会话）的第一条消息；在 incognito、Goal、catalog、suggestion-only、command-send 或 terminal-launch 模式下不可用。若切换到不支持的模式时仍有已选提及，composer 会阻止发送并要求移除或回到普通聊天，不会静默丢弃接收者。

Mentions Inbox（提及收件箱）

打开Inbox → Mentions可以看到跨可访问 agent 发向你已登录档案的消息。打开某条提及会打开其会话且不消除该条目；Dismiss将其从你的 Inbox 移除——该状态跟随同一档案跨已连接浏览器同步，且不删除聊天消息本身。

提及与消除记录在 Gateway 重启和升级后仍然存活；条目保留其原始标识与过期时间：最多 7 天、每档案最多 100 条、全 Gateway10,000 条，容量限制可能提前淘汰旧条目。刷新或重连会重新加载保留的 Inbox，不会重发旧的浏览器提醒；不会扫描旧转录消息来重建缺失条目。

Inbox 及其重放记账复用共享数据库既有的 machine-state 记录，无 SQLite schema 变更；提及标注保留在既有的消息 JSON 中，通知偏好使用既有 preference 记录（见 Inbox storage and retention）。Inbox 无需浏览器通知权限；如需离开 Control UI 时的可选提醒，请在通知设置中启用Someone mentions me，发送与重试契约见 WebChat。

Agent 派生会话（Agent-spawned sessions）

agent 通过sessions_spawn（visible: true）创建的会话归属于请求方 agent：创建者与初始 owner 都是该 agent 本身，侧边栏显示 agent 配置的标识名与头像，而不是内部 session key。

被接受的 spawn 结果同时充当回执：包含子会话 key、run id、直达 Control UI 的sessionUrl，以及标明请求方 agent 的owner记录（Control UI 禁用时省略sessionUrl）。当 agent 在聊天渠道确认 spawn 时，会把会话 URL 放在第一行、Owner: <label>放在第二行，你可以直接打开会话、一眼看清责任人；接手工作时用Assign to me改派给自己。生命周期细节见 Sub-agents。

身份作用域的便捷状态（Identity-scoped convenience state）

当连接具有持久 Gateway 档案时，新会话偏好与会话选择器最近记录会跟随这个人跨浏览器同步。偏好仍按 agent 存储；最近记录只从该人创建的会话推导。没有持久身份的连接保留浏览器本地偏好，最近记录来自已加载的会话名单。

单用户 Gateway 会给未识别操作者分配一个共享 owner 档案（包括设备 token 重连）；配置了gateway.roles时，这只适用于 token/password 连接。使用该档案的设备共享其身份与偏好——请用逐人登录来区分不同人，见 Gateway profiles。

这类状态改善连续性，但不是授权或隔离边界：操作者作用域仍然控制动作，共享 Gateway 对会话、工具、凭据与文件始终是一个信任域。

Drafts（草稿会话）

以草稿开始会话，可在你发布之前让进行中的工作不出现在其他人的侧边栏。草稿永不向管理员隐藏——管理员会看到他人的草稿，并带有淡化的幽灵标记。这是协调功能，不是安全边界。

Catalog 列表与进度更新会对每个接收者复核当前会话可见性；缓存的 provider 结果不会保留对已变为 draft 或 incognito 会话的访问权。被接手的线程仍绑定到其原始会话实例与插件归属；删除并重建会话 key 不会把旧线程转移到新创建者。Catalog 读与变更也会在 provider 枚举后复核存储的会话。

Turn 归属（Turn attribution）

回合发送者归属是尽力而为的：steering 可能把输入合并进活动回合，因此转录无法总能把每人的贡献表示为独立回合。参与者历史只记录"某 actor 曾 prompt 该会话"，而不是哪些字是他写的。

参与者身份独立于显示名与授权：已认证的 Gateway 档案、OpenClaw agent 与远程发送者即使 ID 匹配也保持区分。渠道插件在能证明时提供远程身份域与标识符种类；否则 OpenClaw 保留未解析的观察值，不会从发送者 ID、本地账号标签或 UUID 形态去猜测档案。档案合并通过既有档案别名解析；被接受的输入会更新已保留的当前档案行（或没有当前行时保留的别名行），即使已到 32 条准入上限。历史行保留原始 ID；这一过程不重写转录或其他 agent 数据库。

档案参与记录被接受的外部创作输入（包括被接受的 steering 与会话目标的交互输入）；合成运行、内部消息、bot 或环境类工作不构成个人档案活动。参与者记录是聚合，不是精确的、可回放的生命周期输入计数。重置保留同一逻辑会话的参与者；删除会话则删除参与者记录（即使转录归档被保留）。

常规准入上限是每个逻辑会话 32 个身份；既有身份在该上限下仍可继续贡献；修复逻辑保留已保留的更大历史而非丢弃。头部四个头像只是预览：Gateway 在分页与预览截断之前求值人员过滤器。活动报告关联的是会话（包括已验证的创建或指派责任），而非声称"会话新近即此人最后输入"。受限历史与截断结果会被标识为不完整。

schema-18 迁移（首发于 v2026.8.1）保留历史成员资格与已记录的贡献聚合；由于更早的写入者可能合并档案与渠道时间戳，模糊的首次/最后输入时间会变成未知，后续被接受的输入能建立新的最后时间，但无法恢复"史上首次输入时间"；不会运行任何基于转录、显示名或 UUID 的回填。详见 Database schemas。

新的转录消息将合格的发送者身份与显示名分开：只有合格的档案发送者才获得档案肖像、人员 Activity 链接或被识别为已登录者，也只有他们的消息会清除该档案的输入指示器；仅渠道发送者 ID 匹配不够。Write hooks 可以编辑（redact）发送者身份，但不能替换为另一个受信身份；suggestion 归属标识的是 suggestion 的作者，而不是接受它的操作者。

较旧或不合格的消息保留其保存的文本与发送者标签，用首字母代替推测的档案肖像，也没有人员 Activity 链接；OpenClaw 不会重写这些消息，也不会从 UUID、档案查询或参与者历史重建作者——这可能让一条确实由档案作者发出的旧消息失去档案展示，因为它当时没有记录足够证据。转录归属、参与者聚合与基于创建者的访问决策是三个相互独立的契约；归属与参与从不授予会话访问权。

经 Cloudflare Access 或 Tailscale Serve 的 GitHub 登录会在Settings → Profile → Identity下自动验证该人的 GitHub 账号。公开的Co-authored-by署名是独立的Git co-author credit开关，已验证账号默认开启。署名使用该偏好加上文所述的持久档案参与者记录，而不是显示名或四人 facepile 投影。隐私、资格、边界、账号变更与关闭未来署名的细节见 User model。