Beam 插件
捆绑的 beam 插件通过经过身份验证的 HTTP 接收脱敏后的编码会话快照,并将其呈现在 Control UI 现有的外部会话目录中。源计算机只向外发送文本;OpenClaw 永远不会回连到该计算机,也不会获得任何文件系统、终端、工具或节点能力。
Beam 随 OpenClaw 一同提供,但默认处于禁用状态。启用后,它会注册:
POST /api/v1/beam/sessions- Control UI 侧边栏中的 Beam 会话目录
启用¶
启用操作会自动应用于正在运行的 Gateway。如果 Gateway 处于离线状态,请启动它以使用 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 的上传。
请求¶
{
"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 返回最新优先的页面,与其他编码会话目录保持一致。
该模式是封闭的。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 代理创建一个常规会话,将权威 Beam 行中保留的有限脱敏历史复制到该会话中,并将你的消息发送到那里。被忽略的过期上传无法更改该继续会话的来源。原始 Beam 保持不变,后续的源上传也不会更改已复制的会话。
当 Team 代理可以使用完全相同的模型时,OpenClaw 会使用 sourceModel。否则,它会使用代理配置的模型。每个复制的转录条目都会被标记为不受信任的外部内容。复制的会话还包含一条通知,说明旧内容是参考材料而非操作员指令,指明所选的模型,并解释该会话无法访问源机器或其工具。
继续会话是一种复制,而非远程恢复或双向同步。每位操作员都可以从同一个 Beam 创建独立的继续会话。
存储与可见性¶
Beam 将脱敏后的负载存储在 OpenClaw 基于 SQLite 的共享插件状态中:
- 最多 500 个会话
- 七天保留期,每次被接受的更新都会刷新
- 当目录达到上限时,逐出最旧的条目
- 服务器接收时间控制目录排序;客户端无法通过伪造的时间戳让自己排到前面
侧边栏复用内存中的元数据清单,而不是在每次轮询时加载每个转录。上传和删除会立即使该清单失效;下一次列表操作会共用一次权威重载。插件服务会预加载该清单,并每 30 秒刷新一次,以获取其他进程所做的更改。过期的条目在所有列表中都会被隐藏。转录读取和继续会话始终读取权威存储。更新时无需进行存储数据迁移。
该目录有意在 Gateway 操作员域内共享。任何具有 operator.read 权限的客户端都可以查看每个 Beam 会话。上传或继续需要 operator.write 或 operator.admin;代理访问策略还必须允许所选代理。任何具有写入权限且知道 Beam id 的操作员都可以更新该行。上传者归属不会授予所有权或更改访问权限。OpenClaw 操作员范围不是租户隔离;当会话需要在团队或机器之间隔离时,请使用单独的 Gateway。
继续会话属于创建它的已认证操作员。此后,它遵循该 Team 代理的常规会话共享、沙箱、工具和模型策略。对原始 Beam 的访问权限不会授予访问其他操作员继续会话的权限。
用户轮次归属于当前快照的已验证发布者,并使用其当前个人资料名称和头像,包括合并后的个人资料。Beam 的上传格式不会在多用户转录中标识单个作者。上传者引用与快照的七天保留期共享,并在每次上传时被替换。共享令牌上传、个人资料解析失败以及没有记录上传者的旧快照会显示 User;它们永远不会继承查看者的身份或之前上传者的身份。通过个人身份验证重新上传旧快照以进行归属。
删除¶
任何具有 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