---
summary: "与配对的团队网关以只读方式共享选定的 OpenClaw 会话"
read_when:
  - "与团队网关共享个人 OpenClaw 会话"
  - "配对仅公开会话列表和记录的节点"
  - "为来自另一个网关的会话配置归因"
title: "会话共享插件"
---

捆绑的 `session-share` 插件允许队友从 Control UI 中的另一个 OpenClaw 网关读取选定的会话。源操作员选择要发布的会话组。源计算机上的节点主机读取这些会话并作为配对设备连接到接收者网关。

默认情况下禁用会话共享。它发布只读 **OpenClaw 会话** 目录，而不是在源计算机上运行代理的第二种方式。有关没有配对节点的外部编码会话的清理快照，请参阅 [Beam](/plugins/beam)。

## <a id="before-you-begin"></a> 开始之前

两台机器都需要带有会话共享插件的 OpenClaw。以相同的 OS 用户身份运行源节点主机，并使用与源网关相同的 `OPENCLAW_STATE_DIR` 和配置。当源使用自定义配置位置时，也设置 `OPENCLAW_CONFIG_PATH`。节点读取配置的 `session.store`，包括自定义路径和每个代理模板。接收者需要一个可访问的、经过身份验证的网关端点和批准设备配对的权限。

对于仅限会话的连接，请使用下面的白名单命令。如果没有白名单，普通节点主机可以通告其他功能。

## <a id="choose-sessions-on-the-source"></a> 在源上选择会话

在源上启用插件并选择要发布的确切会话组名称：

```json5
{
  plugins: {
    entries: {
      "session-share": {
        enabled: true,
        config: {
          share: { groups: ["Team"] },
        },
      },
    },
  },
}
```

在源 Control UI 中，将要共享的会话移至 **Team** 组中。组名称与会话类别完全匹配。省略或空的 `share.groups` 不会发布任何内容。子代理、隐身会话、草稿和其他会话目录中采用的行永远不会发布，即使它们属于选定的组也是如此。这也不包括具有记录的生成谱系的命名或恢复会话；用户创建的分叉仍然符合资格。

使用默认的混合重新加载模式，源网关会自动应用插件配置。更改插件配置后启动或重新启动源节点主机。将会话移出共享组会立即撤销新的转录本读取；已经阅读文本的接收者可以保留该文本。

## <a id="enable-the-receiver-and-pair-the-source"></a> 启用接收器并配对源

在接收网关上：

```bash
openclaw plugins enable session-share
openclaw devices join-code
```

启用命令应用正在运行的网关的插件生命周期，而无需重新启动它。将连接 URL 保持私有。在源计算机上，将 URL 与两个只读命令一起使用：

```bash
openclaw connect <join-url> --service \
  --commands openclaw.sessions.list.v1,openclaw.sessions.read.v1
```

省略 `--service` 在前台运行。使用 `--service`，允许列表保存在源节点的持久计算机状态中，并在服务重新启动时保持有效。

批准接收器上的源设备：

```bash
openclaw devices list
openclaw devices approve <requestId>
openclaw nodes list
```

检查配对请求和连接的节点是否仅声明 `openclaw.sessions.list.v1` 和 `openclaw.sessions.read.v1`，并具有 `openclaw-sessions` 能力。目录仅识别通告这两个命令的节点。有关加入代码到期的信息，请参阅 [Connect](/cli/connect)，有关命令白名单的信息，请参阅 [Nodes](/nodes#restrict-the-node-command-surface)。

## <a id="read-shared-sessions"></a> 读取共享会话

打开接收器Control UI。共享行显示在 **OpenClaw 会话** 中源节点的标题下。选择一行将打开其记录，仅供查看。仅共享用户和助理的对话文本。省略思考、工具调用、工具结果。接收方无法继续、存档或打开该会话的终端。

出版物与接收者允许的查看者共享，而不仅仅是指定的所有者。观众需要`operator.read`；在角色限制网关上，其配置文件的角色还必须允许查看其他人的会话（`sessions.others: "view"`、`"suggest"` 或 `"write"`）。仅所有者和未配置的受限查看者无法查看已发布的行。请参见 [ 操作员范围](/gateway/operator-scopes)。

目录通过轮询刷新，而不是实时转录流。源节点必须保持连接才能进行列表和读取。长的文字记录是分页的；必要时会剪裁各个文本字段，并且不会进行秘密屏蔽。

目录列表、搜索和分页对每个请求的配对节点使用一个完整的快照。接收器最多保留 32 个节点快照，并且最多同时运行 4 次刷新。发现本身并不调用节点。满载时，新主机立即返回加载结果。稍后的目录请求可以在工作解决后承认它，并且可以替换空闲的、最近请求较少的快照。接收器每 30 秒在后台刷新一次，每个节点一次刷新一次，所有源页面的预算为 5 分钟（每次调用最多 30 秒）。快照仅限于 10,000 个会话和 16 MiB 的序列化页面。超过任一限制都会导致刷新显式失败，而不会发布部分目录；减少源节点上的共享组。刷新失败将从 30 秒缩短到最多 5 分钟。在刷新成功之前，超过 60 秒的快照不可用；抄本读取时始终重新检查源上的共享。

冷列表立即返回显式加载主机。渐进调用者通过目录的正常主机更新接收快照；其他调用者可以刷新目录。不可用或过期的快照不会返回任何行，包括在刷新运行时。热情的呼叫者会从快照中收到完整的页面，而无需等待源。配置更改、观察到的节点断开或重新连接以及服务停用都会使快照和挂起的发布无效。接收器在目录请求、后台发现期间以及发布刷新之前检查节点连接。没有远程共享更改订阅：源更改在下一次成功的后台刷新时到达接收者。更新接收器不需要配置或存储状态迁移。

源在后台工作程序中读取其会话元数据清单，并跨页面重用它并刷新，而数据库修订版不变。从源网关写入、数据库替换和配置更改都会使该清单无效。每个页面仍然准备当前的创建者身份，并在发布之前重新检查其选定的会话是否保持共享。

列表保留冷记录档案不变，并使用任何存储的标题元数据。要读取冷历史记录，请首先在源网关上打开会话，以便其正常历史记录所有者恢复存档。每个源页面还将原始转录本读数限制为 8 MiB；单个较大的条目会返回显式错误，而不是默默地跳过。检查源网关上的该条目。

## <a id="attribute-the-source-node"></a> 属性源节点

接收方身份设置是可选的，并由 `openclaw nodes list` 显示的节点 ID 指定密钥：

```json5
{
  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 被命名为远程身份，永远不会直接解释为接收器上的配置文件。源和接收器设置可以共存于一个插件配置中。

## <a id="security-boundary"></a> 安全边界

来源选择发布内容；接收者信任配对设备的身份声明附加到该出版物。归属是显示元数据并且从不授予访问权限。

通过两个命令白名单，该节点不会公开 shell 执行、文件系统浏览、终端上传、插件工具、MCP 服务器、技能、工作人员托管或计算机使用。这两个命令都是只读的，每次读取的记录都会重新检查会话是否仍然是共享的。接收方不需要访问源网关的 HTTP 端点或身份验证凭据。

共享会话会公开其用户和助理对话文本和目录元数据，其中可能包括工作空间路径或分支名称。包含的文本未经过秘密屏蔽。在发布之前检查凭据和其他敏感内容。谨慎选择组并将收到的成绩单视为不受信任的文本。

## <a id="troubleshooting"></a> 故障排查

要撤消仅会话设置，请在前台使用 `openclaw node run --all-commands` 或在服务中使用 `openclaw node install --force --all-commands`；这会忘记保存的允许列表并恢复完整的默认节点表面。

**源节点失败，没有允许的命令**

在源上启用 `session-share`，设置非空 `share.groups`，重新启动节点主机，然后检查确切的命令 ID。不公布未知或不可用的命令。

**节点连接但没有出现OpenClaw会话主机**

在接收器上启用插件并确认其已应用。在 `openclaw nodes list` 中，源必须声明两个会话命令并获得批准。

**主机出现，但会话丢失**

检查其来源组、确切的 `share.groups` 拼写，以及它是否是子代理、隐身、草稿或从其他目录采用的。即使会话之前可见，子代理密钥和记录的生成沿袭仍会被排除。验证源节点是否使用与源网关相同的用户和状态目录。在角色受限的接收器上，检查查看者的个人资料和查看其他会话的权限。

**A 记录读取在行可见后失败**

刷新目录。源可能已离线、会话可能已被删除或其组可能不再共享。主机离线错误，重新连接源节点；不要扩大其命令白名单。

**目录刷新有时需要 30 秒**

当启用接收器诊断和警告日志时，`gateway/session-catalog` 会记录至少需要一秒、最多每分钟一次的后台刷新。这些刷新不会延迟目录列表响应。发货前发生 `TIMEOUT` 和 `nodeCommandDispatched: false`； `true` 表示接收方发送了命令，因此请检查源节点及其连接。它并不能证明源处理程序已启动。缺席的现场导致调度未知。这些记录包括有界节点错误代码和持续时间，没有节点标识符、请求参数或错误消息。

**名称未链接到本地​​配置文件**

检查配置的节点ID和`linkGitHubIdentities`。两个配置文件都需要相同的经过验证的数字 GitHub 帐户 ID；匹配的名称或未经验证的登录不会将它们链接起来。

## <a id="related"></a> 相关内容

- [连接节点](/cli/connect)
- [节点命令白名单](/nodes#restrict-the-node-command-surface)
- [团队设置](/start/teams)
- [Beam](/plugins/beam)
- [用户模型](/concepts/user-model)