openclaw transcripts¶
用于持久化会议记录的检查和导出命令。
Google Meet、Microsoft Teams、
Slack huddles 和 Zoom
浏览器参会者会自动捕获笔记;
transcripts 代理工具还支持提供商捕获和手动导入。
规范会议记录状态位于共享 SQLite 数据库中,路径为
$OPENCLAW_STATE_DIR/state/openclaw.sqlite。show 和 path 会显式
在状态目录下生成面向用户的产物:
$OPENCLAW_STATE_DIR/transcripts/YYYY-MM-DD/<session>/
metadata.json
transcript.jsonl
summary.json
summary.md
这些文件是导出文件,而不是第二个运行时存储。OpenClaw 不会在捕获、摘要或列出过程中
回读它们。默认状态目录为
~/.openclaw;可通过 OPENCLAW_STATE_DIR 覆盖。日期目录来自
会话开始时间;会话目录是由会话 ID 派生的文件系统安全 slug。
在 Control UI 中读取会议记录¶
在 Control UI 中,打开侧边栏的铅笔菜单
(编辑固定项)并选择 会议,即可在 /meetings 浏览同一个 SQLite 归档。
你可以将 会议 固定到侧边栏;默认未固定。
会议笔记与 会话 中的代理聊天记录是分开的。
会议以最新优先的时间线显示,并按开始日期分组,每个会议都有已保存的摘要预览。打开会议库时,时间线 以全宽显示;选择某个会议会打开其阅读器。会议库和阅读器 在获取数据时显示加载指示器,并且即使长会议超出聊天消息渲染限制,已保存的笔记也会以 Markdown 渲染。
搜索标题、会话/来源 ID、已保存的摘要笔记和会议记录文本; 不搜索会议 URL。可按 精确的提供商、账户或代理 ID,或按会话开始日期筛选。日期筛选 使用 UTC:开始日期不早于 包含所选日期,开始日期早于 排除该日期。结果以确定性分页加载。更改筛选条件或选择 刷新 会重新开始分页。
选择某个会议可打开其已保存的 摘要。现有的
/meetings?selector=... 书签仍然有效。选择 会议记录 可查看
带时间戳的说话人文本。在此会议记录中搜索 会在 Gateway 上搜索已保存的
语句,包括浏览器中尚未加载的文本。
阅读器会自动加载每一页,并保持完整会议记录可见。
诸如 context: 和 ### 等独立转录产物会从
阅读器、下载和新生成的笔记中省略。新捕获会跳过这些行;
现有原始归档行保持不变。
URL 会保留所选会议和标签页。打开带有已保存语音的会议时,如果你有写权限,会自动生成缺失的笔记。阅读器
会显示生成进度,如果生成失败则提供重试。
下载 Markdown 包含会议记录和任何已保存的摘要。
下载 JSONL 导出阅读器的公共语句投影,排除
提供商私有元数据和本地文件系统路径。本地 CLI 导出保留
其现有原始格式。大于 4 MiB 的浏览器导出会明显失败,
且不会生成部分文件;对于更大的导出,请在 Gateway 主机上使用 openclaw transcripts path <session> --transcript
或 openclaw transcripts path <session> --dir。
读取归档需要 operator.read 或其写入/管理员隐含权限,以及
读取共享归档的权限。在受限的多用户配置文件中,
选择代理筛选不会授予归档访问权限。捕获配置
需要 operator.admin。
命令¶
openclaw transcripts list
openclaw transcripts show <session>
openclaw transcripts show YYYY-MM-DD/<session>
openclaw transcripts path <session>
openclaw transcripts path YYYY-MM-DD/<session>
openclaw transcripts path <session> --dir
openclaw transcripts path <session> --metadata
openclaw transcripts path <session> --transcript
openclaw transcripts list --json
openclaw transcripts show <session> --json
openclaw transcripts path <session> --json
| 命令 | 描述 |
|---|---|
list |
列出已保存的会话。 |
show <session> |
打印并生成 summary.md。 |
path <session> |
生成并打印 summary.md 路径。 |
path <session> --dir |
生成所有产物并打印其目录。 |
path <session> --metadata |
生成并打印 metadata.json。 |
path <session> --transcript |
生成并打印 transcript.jsonl。 |
--json |
打印机器可读输出(任意子命令)。 |
使用 list 打印的选择器来定位精确捕获。现有的
规范选择器优先于具有相同文本的原始会话 ID。
否则,show 和 path 接受 YYYY-MM-DD/<raw-session-id>,并保持
整个后缀为字面值,包括标点和斜杠。例如:
如果两种限定形式都找不到捕获,则完整输入会作为字面 原始会话 ID 或导出 slug 进行匹配,区分大小写。原始 ID 中的类日期前缀 不会阻止此查找。多个匹配需要带日期的 选择器;不会对原始 ID 进行清理以选择捕获。默认会话 ID 包含时间戳和随机后缀;仅当该 ID 在一天内唯一时,才给会话指定固定 ID。
如果文件系统安全的导出名称超过 255 字节,OpenClaw 会将其缩短
为前缀加上完整原始会话 ID 的确定性 SHA-256 哈希。只有派生的导出名称及其选择器会改变;原始会话 ID、
提供商停止句柄和已保存的笔记保持不变。已经符合的名称
保持不变。对于缩短后的名称,请使用 list 打印的选择器。
对于存储名称过大的现有会话,请运行 openclaw doctor --fix
以修复其派生选择器,而不更改已保存的笔记。
输出¶
list 为每个会话打印一行制表符分隔的内容:selector、开始时间、标题、
summary 路径。
2026-05-22/standup 2026-05-22T09:00:00.000Z Weekly standup /Users/user/.openclaw/transcripts/2026-05-22/standup/summary.md
selector 是传回给 show 或 path 的最安全值。
工具选择器¶
从任意会话读取笔记¶
让 agent 使用 transcripts 工具列出过去的会议并读取它们的笔记。读取操作不绑定到捕获该会议的 agent 会话。
Operator 调用方可以读取 Gateway 上的所有会议。Channel 调用方只能读取源 provider 允许的会议;Discord 语音读取仍限制在调用方的 guild 内。这些读取权限不会改变捕获或 summary 写入权限。
```json validate=false { "action": "list", "limit": 20 }
`list` 按最新会议优先返回,包含 selector、开始时间、标题或 provider 名称、utterance 数量以及参与者。`limit` 默认为 20,
接受 1 到 50 的整数。文本是有界的;结构化结果位于
`details.sessions` 中。
```json validate=false
{ "action": "show", "selector": "2026-05-22/notes-room-one" }
show 返回已存储的笔记 Markdown 和会话详情。其文本上限为
12,000 个字符;截断标记指向
openclaw transcripts show <selector> 以获取完整笔记。没有 summary 的捕获会报告笔记尚不可用,包括它是否处于活动状态。
读取笔记不会重新生成 summary 或导出产物。
选择捕获¶
transcripts 工具会同时返回未更改的原始 sessionId 以及来自 start、import、stop 和 summarize 的规范
selector。经过授权的 status 结果
包含活动捕获和等待最终化的条目的 selectors。其
面向模型的文本最多显示三个完整 selectors,优先显示等待最终化的捕获并报告任何省略数量。结构化 status 详情
保留完整的授权列表。有界的活动捕获摘要包含源
定位符和标题,以便 agent 识别目标会议。后续 show、stop、
或 summarize 调用优先使用 selector:
```json validate=false { "action": "summarize", "selector": "2026-05-22/notes-room-one" }
Show、stop 和 summarize 要求恰好提供 `selector` 或 `sessionId` 之一。其他
操作拒绝 `selector`;start 和 import 继续通过
`sessionId` 接受原始 ID。显式 `selector` 输入接受规范 selectors 和
上述历史日期/原始 ID 形式,但永远不会将整个输入回退为
原始 ID。
旧版 `sessionId` 输入会同时考虑限定和 raw/slug 含义。如果
它们标识不同的捕获,工具会报告歧义而不列出
候选详情。捕获结束后仍保持歧义。使用 start、import 或授权 list/status 返回的 selector,或在本地检查 `openclaw transcripts
list` 并在 `selector` 字段中传入所需值。raw-ID/selector 冲突的两侧
仍可通过各自的规范 selector 寻址。
在没有冲突的限定含义或不同的 raw-ID/slug 候选时,
旧版 `sessionId` 会为 stop 和
summarize 选择当前精确 raw-ID 捕获,即使历史捕获复用了该 ID。如果没有当前捕获,
重复的历史 ID 需要带日期的 selector。针对
旧捕获的显式 selector 不会停止其较新的同 ID 兄弟捕获。
`show` 选择并授权持久捕获,仅使用实时状态来报告
捕获是否处于活动状态。即使有一个捕获处于活动状态,重复的历史 ID 也需要带日期的 selector。
## Gateway 和 Control UI 读取 {#gateway-and-control-ui-reads}
在 [Control UI](../web/control-ui/settings.md#meetings-page) 中打开 **Meetings**,无需终端即可浏览
已捕获的会议和笔记。该页面和其他 Gateway
客户端使用这些 RPC 方法:
| 方法 | 参数 | 结果 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transcripts.list` | 可选 `limit`(1–200,默认 50)、`cursor`、`query`、精确的 `providerId`/`accountId`/`agentId`,以及 `startedAfter`/`startedBefore` 日期时间边界 | 按最新优先的 `sessions`,包括参与者、utterance 数量、活动状态、summary 可用性、有界概览和 `nextCursor`。 |
| `transcripts.get` | 必需 `selector`;可选 `includeUtterances`、`limit`(1–100)、`cursor` 和 utterance `query` | 一个 `session`、已存储的 `summary`、可选的 `utterances` 和 `nextCursor`。显式分页返回完整文本;旧版请求保留下面描述的近期窗口。 |
| `transcripts.summarize` | 必需 `selector` | 生成缺失的笔记,并返回与 `transcripts.get` 相同的 `session` 和 `summary` 结构。现有笔记会被保留;并发请求共享 summary 所有者。 |
| `transcripts.export` | 必需 `selector` 和 `format`(`markdown` 或 `jsonl`) | 一个 base64 编码的文件,包含 `filename`、`mimeType` 和 `sizeBytes`。 |
| 方法 | 参数 | 结果 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transcripts.status` | 无 | 捕获启用状态、提供商可用性和设置元数据、已配置源的健康状态、活动订阅以及最新保存的转录。 |
读取方法需要 `operator.read` 或其写入/管理员隐含权限;
`transcripts.summarize` 需要 `operator.write`。所有方法都会在一个受信任的 Gateway 域中暴露会议。受限的操作员配置文件需要读取共享归档的权限;选择代理筛选不会授予访问权限。当读取者需要隔离时,请使用单独的 Gateway 域。源定位器仅包含 `providerId`、`accountId`、`guildId`、`channelId`、`threadTs`、`fileId`、`kind`,以及存在时净化后的 `meetingUrl`,绝不包含任意捕获元数据。参见 [Gateway 协议](../gateway/protocol.md)。
列表搜索匹配标题、会话/源 ID、已保存的摘要 Markdown 和概述,以及存储的语句文本,不包括源会议 URL 和私有元数据。
日期边界使用会话开始时间:`startedAfter` 包含边界,
`startedBefore` 不包含边界。日期按时间点比较,使用 JavaScript
日期字符串语义,包括存储的 UTC 偏移。原始时间戳和
选择器保持不变。无法解析的存储日期排在最后,并排除在日期范围之外。
相同时间点按会话 ID 排序,然后按原始时间戳排序。
按时间顺序选择页面会扫描候选捕获,并在搜索时扫描其已保存的笔记和语句,然后仅投影所选页面的笔记和参与者。搜索时间随被搜索的存储文本增长。
游标属于其当前查询和筛选条件;
更改其中任何一项都需要重新获取第一页。`nextCursor` 为 null 时结束分页。
存储的摘要 Markdown 是规范笔记文本,与 CLI 的
`show` 输出一致。读取不会生成摘要或生成文件。除非 `includeUtterances` 为 true,否则省略语句。提供 `limit`、`cursor` 或
`query` 会选择分页读取:每页最多 100 条语句,默认 50 条,
且不截断存储文本。`query` 搜索完整存储的转录,
包括未加载的页面。分页读取、列表和状态结果限制为
1 MiB,并在传输到 JavaScript 之前强制执行存储负载边界。
超大行或无效游标会显式失败。
摘要参与者和模型/启发式来源在可用时显示;
旧摘要可以不包含它们。
为了兼容在归档分页之前发布的客户端,`transcripts.get`
不带 `limit`、`cursor` 或 `query` 时会按时间顺序保留最近 2,000 条语句,
每条净化后的文本被裁剪到 4,000 个 UTF-16 单元。
这些旧式请求返回 `nextCursor: null`,并保留 25 MiB 的公共结果
上限,与现有 Gateway 客户端传输限制一致。它们保留了
文本裁剪和公共投影之前的原始行读取行为。
发送显式的 `limit` 以采用有界页面读取并获取完整文本;
继续使用 `nextCursor`,直到它为 null。所有归档访问检查都适用于
两种请求形式。
导出限制为 4 MiB,失败时不会返回部分文件。Markdown
保留存储的笔记,并在单独的标题下追加完整转录。JSONL 包含公共
语句投影:序列、语句 ID、完整文本、说话者身份、源
时间戳,以及可用时的最终性。它排除私有提供商元数据
和文件系统路径;本地 CLI 导出保留其原始语句格式。
对于更大的导出,请在 Gateway 主机上使用
`openclaw transcripts path <session> --transcript`。
状态报告的是已注册订阅,而不是已确认录制。`armed`、
`not-active` 和 `unknown` 保持不同;仅凭净化后的 URL 无法证明
是哪个原始邀请启动了捕获。提供商、已配置源和
活动列表限制为 100 个条目,并带有省略计数。已保存语句
计数来自持久化行。最新转录是最近更新的包含语句的会话;源语音时间不是摄取
时间戳。
## JSON 输出 {#json-output}
`list --json` 返回包含 `sessionId`、`selector`、`date`、`title`、
`startedAt`、`stoppedAt`、`source`、`path`、`summaryPath`、`hasSummary` 的对象。
存储的会议源 URL 仅包含源和路径;查询字符串、
片段和内嵌凭据会在持久化之前移除。
`show --json` 返回存储的会话元数据、选择器、会话
目录、摘要路径和摘要 Markdown 文本。
`path --json` 返回所选路径以及该产物能否被
生成。对于存储的会话,元数据和转录导出始终存在;摘要路径在会话拥有摘要之前报告 `exists: false`。
## 每天多个会话 {#many-sessions-per-day}
会话按日期分组,然后按会话 ID 分组。同一天的十场会议会变成
十个同级文件夹:
```text
~/.openclaw/transcripts/2026-05-22/
transcript-2026-05-22T09-00-00-000Z-a1b2c3d4/
transcript-2026-05-22T10-30-00-000Z-b2c3d4e5/
standup/
自动化请使用默认生成的 ID。仅当固定 ID(如 standup)不会在同一天重复时,才使用它。
缺失的摘要¶
活动捕获会在有新语音到达时大约每五分钟保存一次更新后的笔记。每次更新都会对已保存的转录快照进行摘要;生成期间到达的语音仍会保留,供下次更新使用。静默捕获不会反复调用模型。停止捕获会在已接收语音处理完毕后保存最终摘要。控制 UI 的 摘要 选项卡显示最新保存的笔记及其生成时间。打开包含已保存语音的会议时,也会通过 transcripts.summarize 请求缺失的笔记;这会复用捕获摘要所有者,并保存笔记而不导出文件。只读客户端可以查看现有笔记,但不能请求生成。归档读取 RPC 本身仍保持只读。
会议笔记优先使用所属代理的实用模型,必要时再使用其主要模型。如果没有可用模型、请求超时,或模型返回无效输出,OpenClaw 会改为保存确定性的启发式笔记。模型生成用于增强笔记;它不会阻止保存笔记。笔记包括概述、参与者、决策、行动项、风险,最后是转录文本,因此有长度限制的读者会先看到笔记,而不是冗长的转录文本。
网关关闭、重启以及禁用捕获时的排空操作会保存最终启发式笔记,而不会启动新的模型推理。网关恢复可用后,可以使用该工具的 summarize 操作从已保存的转录文本重新生成模型笔记。参与者来自按首次出现顺序排列的说话人标签,而不是模型猜测。摘要 JSON 会将 source 记录为 model 或 heuristic,对于模型笔记,还会记录所使用的模型引用。
模型最多接收 48,000 个转录字符;当必须省略中间部分时,会保留开头和结尾。已存储的语句保持完整。使用 transcripts summarize(代理工具的 summarize 操作)可从已存储的转录文本重新生成笔记,包括在更改模型配置之后。
该工具的 status 操作列出活动捕获订阅,而不是历史笔记。当提供商结束或替换订阅时,OpenClaw 会记录 stoppedAt 并保存其摘要;转录文本仍可供 list、show 和该工具的 summarize 操作使用。临时传输断开不会结束订阅。停止历史笔记不会停止较新的捕获,也不会更改已记录的停止时间。
由提供商驱动的完成操作会保存摘要,而不导出文件。显式工具停止、导入、摘要以及已配置的自动启动关闭也会尝试生成 summary.md。
如果最终持久化失败,status 会在 pendingFinalization 下报告已结束的捕获,与活动捕获分开显示。使用该工具针对该会话的 stop 操作可重试持久化,而无需再次停止提供商。
如果提供商无法完成清理,且未报告捕获已结束,status 会保持该捕获为活动状态,并设置 cleanupPending: true。现有语句保持完整,最终笔记会等待清理完成。提供商恢复后,使用相同的选择器重试 stop。替换或禁用插件不会将清理转移到另一个提供商实例。
在捕获仍活动时,会话可能出现在 list 中但没有摘要;如果提供商在停止期间失败,或在任何语句到达之前已存储元数据,也会出现这种情况。
使用 path <session> --transcript 检查原始仅追加转录文本,或运行 transcripts 工具的 summarize 操作重新生成 Markdown 摘要。
摘要会在可选工件导出之前保存到 SQLite。如果导出失败,即使缺少 summary.md,已保存的摘要仍可用。已配置的自动启动捕获在关闭期间会为导出失败或提供商停止错误记录警告。修复导出目标问题后,运行 openclaw transcripts path <session> 或 openclaw transcripts show <session> 重试导出;警告中提到的预期路径并不能证明文件已导出。
没有完整账户所有者元数据的历史会话仍保留在本地恢复路径上。使用针对该代理的本地回合恢复由代理拥有的行;没有代理归属的行需要本地主代理回合。没有账户绑定的来源在其正常界面上保留主代理访问权限。缺失的提供商、部分所有者元数据以及无账户的历史来源也保留在此本地恢复路径上。
openclaw agent --agent <owning-agent-or-main> --local --message \
"Use transcripts summarize for session <session>."
升级旧版文件存储¶
早于 SQLite 存储的 OpenClaw 版本会将规范运行时状态直接写入 $OPENCLAW_STATE_DIR/transcripts/ 下。运行:
Doctor 会将完整的旧版目录树导入 SQLite,验证行数与顺序,记录迁移回执,并将已验证的源目录树移动到带时间戳的 transcripts.migrated-* 归档中。运行时命令不会回退到旧版文件。请保留该归档,直到你验证了已导入的会话以及所依赖的任何导出。
配置¶
打开 设置 → 通信 → 会议捕获,可编辑现有的 transcripts.enabled 和 transcripts.autoStart 设置。启用转录存储 控制是否允许持久捕获;每个自动启动来源都会选择加入一个提供商和来源。你可以添加或删除来源,并编辑其标题、账户、来源定位符以及可选的自定义会话 ID。占用模式会自动选择会话 ID,因此其自定义 ID 字段处于禁用状态,同时保留已保存的值。
这些控件使用共享的设置草稿、自动保存、验证和应用流程。如果出现 应用更改,请使用它来激活已保存的更改。如果重启中断了待处理草稿,重连后自动保存已暂停 会保留该草稿,而不会将其发送到新连接。请检查该草稿,并在设置页脚中选择 保存。完整的转录架构编辑器位于 会议捕获 → 高级设置 下。
会议捕获设置无需重启 Gateway 即可生效。已移除或已更改的来源会在替换前排空其已接收的语音并定稿笔记;未更改的来源继续录制。来源标题的编辑仅适用于后续捕获。当前和历史笔记保留其原始标题、来源、代理归属和选择器。
启动重试仅在完全相同的失败 provider 尝试仍保留重试权限时,才会保留相同的已接纳 ID、原始标题、开始时间、来源和已保存笔记。这适用于生成的 ID 和配置的 ID。重试在十二次尝试后、服务关闭、手动停止,或保留清理托管权的失败后停止。状态会报告有界的诊断信息,而不包含 provider 错误详情。在尝试新的捕获之前,使用该工具的 stop 操作恢复待处理的清理。
会议转录捕获默认启用。要全局退出:
enabled(默认true):启用自动会议笔记、transcripts 工具和已配置的自动启动来源。当会议笔记不应持久化到主机上时,将其设置为false。显式请求的会议transcribe模式会保留其现有的有界实时字幕尾部,但在该设置为false时不会写入持久化行。
使用 transcripts.autoStart 配置自动启动来源。每个条目只要存在即启用;省略某个条目即可禁用该来源。discord-voice 是内置的、支持自动启动的来源,需要 guildId 和 channelId。当恰好有一个已配置的 Discord 账户具有凭据并启用了语音时,OpenClaw 会自动选择它。当多个账户支持语音时,OpenClaw 会选择支持语音的 channels.discord.defaultAccount。否则,将 accountId 设置为 channels.discord.accounts 下对应的键;省略账户会被视为歧义而拒绝:
{
"transcripts": {
"enabled": true,
"autoStart": [
{
"providerId": "discord-voice",
"accountId": "work",
"guildId": "1234567890",
"channelId": "2345678901",
"whenOccupied": true
}
]
}
}
whenOccupied 默认为 false:捕获随 Gateway 启动并持续进行,直到停止。将其设置为 true 以等待人类,然后为每个占用时段捕获一次会议。如果启动时人类已经存在,它也会启动;机器人永远不计入。最后一名人类离开后,固定的 30 秒宽限期允许短暂重连而不拆分会议。如果人类在该宽限期内返回,则取消停止。否则,OpenClaw 停止捕获并生成笔记。
占用时段使用生成的 ID;条目的 sessionId 会被忽略。为了在 Gateway 重启后继续会议,如果同一 provider、账户、guild 和 channel 的最近会话在过去 10 分钟内停止,且其存储的 ID 来源为 generated,OpenClaw 会重新打开该会话。会话保留其原始 ID、标题和开始时间,新的话语会追加到其中。在该时间窗口内的稍后返回也会复用该会议;在窗口外,捕获会获得新的 ID。
新的接纳会记录转录 ID 是生成的还是提供的。如果最新候选项具有提供的 ID,或其来源缺失或无效,捕获将从头开始,而不搜索旧历史记录。现有笔记保持不变且可读。因此,未记录来源的旧版生成的会议在升级或重启后可能会拆分。Doctor 在恢复元数据时会保留已记录的来源;它不会推断或回填缺失的来源。如果房间被路由到不同的代理,该代理会启动新的捕获;原始代理保留其存储的会议和摘要权限。
provider 必须报告占用状态。discord-voice 支持该功能;不支持的 provider 会记录警告并跳过该条目,而不是持续捕获。每个 Discord 账户和 guild 最多配置一个 whenOccupied: true 条目,即使 channel ID 不同:Discord 机器人每个 guild 只能占用一个语音频道。后续冲突的条目会被跳过并记录警告。完整的仅监听设置,请参阅 Discord 会议笔记。
会议 provider 的 ID 为 google-meet、teams、slack-huddle 和 zoom。它们的别名分别为 googlemeet/meet、teams-meetings/microsoft-teams/msteams、slack-huddles 和 zoom-meetings。会议 provider 会附加到已激活的会议机器人会话;正常的会议加入不需要 autoStart 条目。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw