会话共享插件
The bundled session-share plugin lets teammates read selected sessions from another OpenClaw Gateway in the Control UI. The source operator chooses session groups to publish. A node host on the source machine reads those sessions and connects to the receiver Gateway as a paired device.
Session Share is disabled by default. It publishes a read-only OpenClaw sessions catalog, not a second way to run agents on the source machine. For sanitized snapshots of external coding sessions without a paired node, see Beam.
开始之前¶
Both machines need OpenClaw with the Session Share plugin. Run the source node host as the same OS user and with the same OPENCLAW_STATE_DIR and configuration as the source Gateway. Set OPENCLAW_CONFIG_PATH too when the source uses a custom config location. The node reads the configured session.store, including custom paths and per-agent templates. The receiver needs a reachable, authenticated Gateway endpoint and permission to approve device pairing.
Use the command allowlist below for a sessions-only connection. Without an allowlist, a normal node host can advertise other capabilities.
在源上选择会话¶
Enable the plugin on the source and choose the exact session group names to publish:
{
plugins: {
entries: {
"session-share": {
enabled: true,
config: {
share: { groups: ["Team"] },
},
},
},
},
}
In the source Control UI, move the sessions you want to share into the Team group. Group names match the session category exactly. An omitted or empty share.groups publishes nothing. Subagents, incognito sessions, drafts, and adopted rows from other session catalogs are never published, even when they belong to a selected group. This also excludes named or resumed sessions with recorded spawn lineage; a user-created fork remains eligible.
With the default hybrid reload mode, the source Gateway applies plugin configuration automatically. Start or restart the source node host after changing plugin configuration. Moving a session out of a shared group revokes new transcript reads immediately; a receiver that already read text may retain that text.
启用接收方并配对源¶
On the receiver Gateway:
The enable command applies the running Gateway's plugin lifecycle without restarting it. Keep the join URL private. On the source machine, use that URL with exactly the two read-only commands:
openclaw connect <join-url> --service \
--commands openclaw.sessions.list.v1,openclaw.sessions.read.v1
Omit --service to run in the foreground. With --service, the allowlist is saved in the source node's durable machine state and remains in effect when the service restarts.
Approve the source device on the receiver:
Check that the pairing request and connected node declare only openclaw.sessions.list.v1 and openclaw.sessions.read.v1, with the openclaw-sessions capability. The catalog only recognizes nodes advertising both commands. See Connect for join-code expiry and Nodes for the command allowlist.
读取共享会话¶
Open the receiver Control UI. Shared rows appear under the source node's heading in OpenClaw sessions. Selecting a row opens its transcript view-only. Only user and assistant conversation text is shared. Thinking, tool calls, and tool results are omitted. The receiver cannot continue, archive, or open a terminal for that session.
Publication is shared with the receiver's permitted viewers, not just the named owner. Viewers need operator.read; on role-restricted Gateways, their profile's role must also permit viewing others' sessions (sessions.others: "view", "suggest", or "write"). Owner-only and unprofiled restricted viewers cannot see published rows. See Operator scopes.
The catalog refreshes by polling, not a live transcript stream. The source node must remain connected for listings and reads. Long transcripts are paginated; individual text fields are redacted and clipped when necessary.
Catalog listings, searches, and pagination use one complete snapshot per requested paired node. The receiver retains at most 32 node snapshots and runs at most four refreshes concurrently. Discovery alone does not invoke nodes. At capacity, a new host returns a loading result immediately. A later catalog request can admit it after work settles and an idle, less recently requested snapshot can be replaced. The receiver refreshes it in the background every 30 seconds, with one refresh at a time per node and a five-minute budget for all source pages (at most 30 seconds per invocation). A snapshot is limited to 10,000 sessions and 16 MiB of serialized pages. Exceeding either limit fails the refresh explicitly without publishing a partial catalog; reduce the shared groups on the source node. A failed refresh backs off from 30 seconds to at most five minutes. Snapshots older than 60 seconds are unavailable until a refresh succeeds; transcript reads always recheck sharing on the source.
A cold listing returns an explicit loading host immediately. Progressive callers receive the snapshot through the catalog's normal host update; other callers can refresh the catalog. Unavailable or expired snapshots return no rows, including while a refresh is running. Warm callers receive a complete page from the snapshot without waiting for the source. Configuration changes, observed node disconnections or reconnections, and service retirement invalidate snapshots and pending publications. The receiver checks node connections during catalog requests, background discovery, and before publishing a refresh. There is no remote share-change subscription: source changes reach the receiver on the next successful background refresh. Updating the receiver requires no configuration or stored-state migration.
源在后台工作线程中读取其会话元数据清单,并在数据库修订版本未变化时,跨页面和刷新复用该清单。来自源 Gateway 的写入、数据库替换以及配置变更会使该清单失效。每个页面在发布前仍会准备当前的创建者身份,并重新检查其选定的会话是否仍保持共享。
列表不会改动冷转录归档,并使用任何已存储的标题元数据。若要读取冷历史记录,请先在源 Gateway 上打开该会话,以便其常规历史记录所有者恢复归档。每个源页面还将原始转录读取限制为 8 MiB;单个更大的条目会返回显式错误,而不是被静默跳过。请在源 Gateway 上检查该条目。
为源节点设置归属¶
接收端身份设置是可选的,并以 openclaw nodes list 显示的节点 ID 作为键:
{
plugins: {
entries: {
"session-share": {
enabled: true,
config: {
nodes: {
"<nodeId>": {
owner: "github:octocat",
linkGitHubIdentities: true,
},
},
},
},
},
},
}
owner 接受 github:<login> 或 profile:<profileId>。GitHub 登录名会不区分大小写地解析为具有已验证 GitHub 身份的本地个人资料。当某条记录没有可移植的人类创建者时,绑定的所有者提供默认归属;它不会覆盖可移植的人类身份,也不会授予基于所有权的访问权限。
linkGitHubIdentities 默认为 false。启用后,具有已验证数字 GitHub 账户 ID 的远程创建者和消息发送者将显示为接收端具有相同已验证账户 ID 的本地个人资料。仅凭登录名文本不足以关联远程发送者。未匹配的身份仍保持为远程身份,并保留其显示标签。
如果没有节点特定设置,归属将保持为远程。源本地个人资料 ID 会被命名空间化为远程身份,而不会在接收端直接解释为个人资料。源设置和接收端设置可以在同一个插件配置中共存。
安全边界¶
源选择要发布的内容;接收端信任已配对设备所附加到该发布的身份声明。归属是显示元数据,从不授予访问权限。
在两条命令的允许列表中,节点不暴露 shell 执行、文件系统浏览、终端上传、插件工具、MCP 服务器、技能、工作线程托管或计算机使用。两条命令均为只读,并且每次转录读取都会重新检查会话是否仍为共享状态。接收端无需访问源 Gateway 的 HTTP 端点或身份验证凭据。
共享会话会暴露其用户和助手的对话文本以及目录元数据,其中可能包含工作区路径或分支名称。脱敏会屏蔽已知的凭据模式;它不会使任意对话内容变得可以安全发布。请谨慎选择群组,并将接收到的转录视为不可信文本。
故障排除¶
若要撤销仅会话设置,请在前台使用 openclaw node run --all-commands,或为服务使用 openclaw node install --force --all-commands;这会忘记已保存的允许列表,并恢复完整的默认节点功能面。
源节点因没有允许的命令而失败
在源上启用 session-share,设置非空的 share.groups,重启节点主机,并检查确切的命令 ID。未知或不可用的命令不会被通告。
节点已连接,但没有出现 OpenClaw 会话主机
在接收端启用插件并确认其已生效。在 openclaw nodes list 中,源必须声明两个会话命令,并且已获得这些命令的批准。
主机出现,但缺少某个会话
检查其在源上的群组、share.groups 的确切拼写,以及它是否为子代理、隐身、草稿或从另一个目录采用。即使该会话之前可见,子代理键和记录的生成谱系仍会被排除。请验证源节点使用与源 Gateway 相同的用户和状态目录。在角色受限的接收端,请检查查看者的个人资料以及查看他人会话的权限。
某行可见后,转录读取失败
刷新目录。源可能离线,会话可能已被删除,或其群组可能不再共享。对于离线主机错误,请重新连接源节点;不要扩大其命令允许列表。
目录刷新有时需要 30 秒
当启用接收端诊断和警告日志时,gateway/session-catalog 会记录至少持续一秒的后台刷新,每分钟最多一次。这些刷新不会延迟目录列表响应。带有 nodeCommandDispatched: false 的 TIMEOUT 发生在分发之前;true 表示接收端已分发命令,因此请检查源节点及其连接。这并不能证明源处理程序已启动。字段缺失会使分发状态未知。这些记录包含有界的节点错误代码和持续时间,但不包含节点标识符、请求参数或错误消息。
名称未关联到本地个人资料
检查已配置的节点 ID 和 linkGitHubIdentities。两个个人资料都需要具有相同的已验证数字 GitHub 账户 ID;名称匹配或未验证的登录名不会将它们关联起来。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw