Beam 插件

内置的 beam 插件通过经过认证的 HTTP 接收经过脱敏处理的编码会话快照，并将其展示在 Control UI 现有的外部会话目录中。源计算机会向外发送文本；OpenClaw 从不回连该计算机，也不会获得任何文件系统、终端、工具或节点能力。

Beam 随 OpenClaw 一起发布，但默认处于禁用状态。启用后，它会注册：

POST /api/v1/beam/sessions
Control UI 侧边栏中的 Beam 会话目录

启用¶

openclaw plugins enable beam

启用操作会自动应用到正在运行的 Gateway。如果 Gateway 处于离线状态，请先启动它再使用 Beam。请参阅应用更改并检查。

等效配置：

{
  plugins: {
    entries: {
      beam: { enabled: true },
    },
  },
}

当不需要摄取路由时，请禁用该插件：

openclaw plugins disable beam

认证¶

接收端使用正常的 Gateway HTTP 认证。它不是一个匿名上传端点。

当 gateway.auth.mode: "trusted-proxy" 时，通过配置的身份感知代理发送请求。Beam 会在可用时记录已验证上传者的 OpenClaw 个人资料 ID；它不会保留代理身份标头或凭据。
使用令牌或密码认证时，发送 Authorization: Bearer <gateway-token-or-password>。
除非另一个私有入口能完全认证每个请求，否则不要在 gateway.auth.mode: "none" 的情况下启用 Beam。

受 Cloudflare Access 保护的部署可以认证本地 CLI，而无需暴露 GitHub 令牌：

cloudflared access login https://gateway.example.com
cloudflared access curl https://gateway.example.com/api/v1/beam/sessions \
  -H 'Content-Type: application/json' \
  --data-binary @sanitized-beam.json

openclaw/agent-skills 中的 beam 技能负责处理本地对话记录的发现、脱敏、Cloudflare Access 登录，以及为 Claude Code 和 Codex 进行上传。

请求¶

POST /api/v1/beam/sessions
Content-Type: application/json

{
  "version": 1,
  "beamId": "0123456789abcdef0123456789abcdef",
  "source": "claude",
  "sourceModel": { "provider": "anthropic", "model": "claude-opus-4-1" },
  "title": "Fix the upload flow",
  "updatedAt": "2026-07-20T12:00:00.000Z",
  "completed": false,
  "items": [
    { "type": "userMessage", "text": "Fix the upload flow." },
    { "type": "agentMessage", "text": "Implemented and tested." },
    { "type": "other", "text": "3 read, 2 write, 1 execute; raw tool outputs dropped: 4" }
  ]
}

按对话顺序发送 items，最早的在前。Beam 在存储中保留该顺序，并在回复之前显示问题。其会话目录 API 返回最新的页面在前，与其他编码会话目录保持一致。

该 schema 是封闭的。Beam 会拒绝未知字段、无效的条目类型、空文本、超过 200 个条目、条目文本超过 6,000 个字符、非 JSON 请求以及超过 56 KiB 的请求体。

成功上传会返回稳定的 Beam id 和相对 Control UI URL：

{
  "ok": true,
  "beamId": "0123456789abcdef0123456789abcdef",
  "url": "/beam/fix-the-upload-flow-0123456789ab"
}

返回的 URL 使用会话标题的 slug，后跟 12 个字符的小写十六进制 id 前缀，与常规会话链接一致。id 仍然具有权威性：仅包含裸 id 的链接和带有旧标题的链接仍然可以解析，浏览器会用当前标题替换名称，且不会添加历史记录。无法生成 slug 的标题则使用裸 id。配置的 Control UI 基础路径会作为路由前缀，例如 /openclaw/beam/fix-the-upload-flow-0123456789ab。使用完整 32 字符 Beam id 的更长前缀也有效。命名链接随 2026.8.2 接收端一起发布；在更新接收端之前请先更新 Beam 技能，以便其响应验证器能够接受这些链接。

当同一 beamId 的 updatedAt 更新时，上传它会更新现有的目录行。时间戳相同的上传可以刷新相同的状态或将活跃行标记为已完成，但不能将已完成的行回退为活跃。较旧的上传以及时间戳相同但会导致完成状态回退的上传仍会返回正常的 200 成功响应，但 OpenClaw 会忽略它们。只有被接受的更新才会刷新保留期并更新上传者归属。

sourceModel 是可选的。自动镜像会包含源目录报告的最新模型。没有该字段的旧客户端和快照仍然有效。

在 Team Gateway 上继续¶

在 Control UI 中选择一个 Beam 并在其撰写器中编写消息。首次发送时，OpenClaw 会为选定的 Team agent 创建一个普通会话，将保留的规范 Beam 行中有界的脱敏历史复制到该会话中，并在其中发送您的消息。被忽略的过期上传无法更改该延续源。原始的 Beam 保持不变，后续的源上传也不会更改已复制的会话。

当 Team agent 可以使用完全相同的模型时，OpenClaw 会使用 sourceModel。否则，它会使用 agent 配置的模型。每个复制的对话记录条目都被标记为不可信的外部内容。复制的会话还包含一条通知，说明旧内容是参考资料而非操作员指令，指明模型选择，并说明该会话无法访问源机器或其工具。

延续是副本，而不是远程恢复或双向同步。每个操作员都可以从同一个 Beam 创建独立的延续。

存储与可见性¶

Beam 将脱敏后的负载存储在 OpenClaw 基于 SQLite 的共享插件状态中：

最多 500 个会话
七天的保留期，每次被接受的更新都会刷新
当目录达到上限时，驱逐最早的条目
服务器接收时间控制目录排序；客户端无法通过伪造的时间戳让自己排到前面

侧边栏复用内存中的元数据清单，而不是在每次轮询时加载每个对话记录。上传和删除会立即使该清单失效；下一次列表会共享一次规范的重新加载。插件服务会预加载该清单，并每 30 秒刷新一次，以获取其他进程所做的更改。过期的条目在所有列表中都不可见。对话记录读取和延续始终读取规范存储。更新时不需要进行存储数据迁移。

The catalog is intentionally shared across the Gateway operator domain. Every client with operator.read can view every beamed session. Uploading or continuing requires operator.write or operator.admin; agent access policy must also allow the chosen agent. Any write-authorized operator that knows a Beam id can update that row. Uploader attribution does not grant ownership or change access. OpenClaw operator scopes are not tenant isolation; use a separate Gateway when sessions must be isolated between teams or machines.

A continuation belongs to the authenticated operator who creates it. From then on it follows ordinary session sharing, sandbox, tool, and model policy for that Team agent. Access to the original Beam does not grant access to another operator's continuation.

User turns are attributed to the verified publisher of the current snapshot, using their current profile name and avatar, including merged profiles. Beam's upload format does not identify individual authors within a multi-user transcript. The uploader reference shares the snapshot's seven-day retention and is replaced on each upload. Shared-token uploads, failed profile resolution, and older snapshots without a recorded uploader display User; they never inherit the viewer's identity or a previous uploader's identity. Reupload an older snapshot through personal authentication to attribute it.

删除¶

任何具有 operator.write 的操作员都可以从其侧边栏行菜单中删除 Beam。确认后，侧边栏会在删除完成前隐藏该行。如果删除失败，该行会恢复显示并出现错误。成功删除是永久的。重新上传相同的 beamId 会重新创建该行，无论是通过手动技能还是仍活动的镜像的下一次上传。镜像会跳过未变化的快照，因此重新创建不一定发生在下一次轮询。删除 Beam 不会影响已从它创建的延续。

安全边界¶

Beam 发布不是远程控制。

继续会创建一个由 Gateway 拥有的独立会话。Beam 本身没有文件系统、终端、工具或节点能力。
它只接受纯文本的规范化转录项，不接受 HTML、脚本、归档、附件或服务器获取的 URL。
官方技能在上传前会移除原始工具结果、推理、提示词、本地路径、凭据、Cookie 和身份验证材料。
接收方将每个转录视为不可信文本。Beam 编辑器中的第一条消息是操作员将其复制到新会话的显式操作。
请求在读取正文之前会进行速率限制和并发限制。

镜像¶

Beam 也可以作为发送方：一个可选启用的镜像，持续将本机活动的本地编码会话（Claude Code、Codex 和其他已注册的会话目录）发布到远程 Beam 接收方，例如共享团队 Gateway。团队成员随后可以在远程 Control UI 中查看近乎实时的会话转录，而无需访问源机器。

{
  plugins: {
    entries: {
      beam: {
        enabled: true,
        config: {
          mirror: {
            endpoint: "https://team.example.com/api/v1/beam/sessions",
            token: { source: "env", provider: "default", id: "BEAM_TEAM_TOKEN" },
            catalogs: ["claude", "codex"],
          },
        },
      },
    },
  },
}

endpoint（必需）：最终远程接收方 URL。更改它会向该接收方重新开始投递，包括未变化的活动会话；针对先前接收方的待处理终态重试会被丢弃，让其行正常过期。重定向响应（301、302、303、307 和 308）不会被跟随；请直接配置目标 URL。发生重定向后，当前镜像服务实例会抑制重复轮询。Gateway 重启会再次探测已配置的 endpoint，以便在同一 URL 上修正的接收方可以恢复。非回环主机强制使用 HTTPS；明文 http:// 仅接受用于 localhost/127.0.0.1/::1 开发。
token：用于远程接收方的 Gateway 凭据，以 Authorization: Bearer 发送。接受普通字符串或密钥引用；已配置但未解析的令牌会暂停镜像，而不是发送未认证请求。由身份感知代理前置的部署需要一个接受此 Bearer 凭据的入口。
catalogs（必需）：要镜像的会话目录 ID，作为按目录的显式同意——省略或空列表不会镜像任何内容。本地 beam 接收方目录始终被排除，因此两个镜像 Gateway 不会重新镜像彼此的行。
pollSeconds（默认 30，最小 10）：镜像扫描本地目录的频率。
activeWindowMinutes（默认 180）：活动比该窗口更新的会话被视为活动并继续镜像；当会话空闲超过窗口后，正在运行的镜像服务会重试其最终 completed 更新，直到接收方接受或七天保留窗口结束。重试状态是进程本地的：Gateway 重启会清除待处理的终态重试，因此远程行保持活动，直到其正常七天保留期过期。

镜像上传用户和代理消息文本，用紧凑计数替换结构化推理、工具调用、工具结果和原始负载。标题和消息在裁剪前会经过 OpenClaw 内置的凭据掩码和已配置的 logging.redactPatterns，即使日志脱敏已禁用。手动 beam 技能还会额外移除设置包装器、本地路径、联系人标识符和不透明值；自动镜像不会应用这些额外规则。仅对你打算共享可见消息文本的目录启用它。

镜像在应用接收方限制（200 项、56 KiB）之前，将最新优先的目录页转换为按时间顺序的上传，并首先丢弃最旧的条目。只要仍有较旧的页面、源报告截断，或文本或条目被裁剪，它就将上传标记为 truncated。Claude 目录页会统计单独的文本、推理和工具块，并限制其文本大小。配对节点上的会话不会被镜像；镜像仅共享来自此 Gateway 机器的会话，最新 32 个优先。已列出的会话离开活动窗口时，即使其目录还有更多页面，也会收到最终完成更新；缺失的会话只有在完整且成功的主机列表之后才会被最终化。

在配对节点上浏览 Claude 会话时，请同时更新这些节点和 Gateway。没有 block-resume 元数据的旧版节点构建，在混合行跨页时会报告需要更新的错误。

故障排查¶

404 Not Found Beam 插件已禁用、运行时应用失败，或请求到达了另一个 Gateway。请检查启用结果并检查插件。

401 Unauthorized 请求未满足 Gateway HTTP 身份验证。请检查 bearer 凭据或 trusted-proxy/Access 会话。

405 Method Not Allowed 接收方仅接受 POST。

413 Payload Too Large 序列化后的请求超过了 56 KiB。官方 skill 会丢弃较早的已清理消息，直到快照可容纳。

429 Too Many Requests 已认证客户端超过了请求或并发上限。请在当前分钟窗口结束后重试。

beam mirror upload blocked ... receiver returned redirect 配置的镜像端点返回了重定向。Beam 不会跟随重定向，并会抑制当前服务实例的重复尝试；请将 mirror.endpoint 设置为最终接收方 URL。重启 Gateway 会再次探测配置的端点。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw

Beam 插件

启用¶

认证¶

请求¶

在 Team Gateway 上继续¶

存储与可见性¶

删除¶

安全边界¶

镜像¶

故障排查¶

相关¶