From 7eb2eccf399818086344d3cb868109dce41ef348 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 26 Apr 2026 02:13:50 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/session.md | 51 ++-- .../session-management-compaction.md | 232 +++++++++--------- 2 files changed, 142 insertions(+), 141 deletions(-) diff --git a/docs/zh-CN/concepts/session.md b/docs/zh-CN/concepts/session.md index 71d161a01..0830390da 100644 --- a/docs/zh-CN/concepts/session.md +++ b/docs/zh-CN/concepts/session.md @@ -6,17 +6,17 @@ read_when: summary: OpenClaw 如何管理会话会话 title: 会话管理 x-i18n: - generated_at: "2026-04-26T01:45:58Z" + generated_at: "2026-04-26T02:12:52Z" model: gpt-5.4 provider: openai - source_hash: 9ed910c990de38d6bcab4ac0bd47e4ed61a637cc6af5236c6fafc732aacb92ff + source_hash: 8f36995997dc7eb612333c6bbfe6cd6c08dc22769ad0a7e47d15dbb4208e6113 source_path: concepts/session.md workflow: 15 --- -OpenClaw 将对话组织为**会话**。每条消息都会根据其来源被路由到某个会话中——例如私信、群聊、cron 作业等。 +OpenClaw 将对话组织为**会话**。每条消息都会根据其来源被路由到某个会话——例如私信、群聊、cron 作业等。 -## 消息如何被路由 +## 消息如何路由 | 来源 | 行为 | | --------------- | ------------------------- | @@ -24,14 +24,14 @@ OpenClaw 将对话组织为**会话**。每条消息都会根据其来源被路 | 群聊 | 按群组隔离 | | 房间/渠道 | 按房间隔离 | | Cron 作业 | 每次运行使用全新会话 | -| Webhook | 按每个 hook 隔离 | +| Webhooks | 按 hook 隔离 | ## 私信隔离 -默认情况下，所有私信共享一个会话，以保持连续性。这对单用户设置来说没有问题。 +默认情况下，所有私信共享一个会话，以保持连续性。这对于单用户设置来说没有问题。 -如果有多个人可以向你的智能体发送消息，请启用私信隔离。否则，所有用户都会共享相同的对话上下文——Alice 的私密消息会对 Bob 可见。 +如果有多个人可以给你的智能体发消息，请启用私信隔离。否则，所有用户都会共享相同的对话上下文——Alice 的私人消息会对 Bob 可见。 **修复方法：** @@ -49,25 +49,26 @@ OpenClaw 将对话组织为**会话**。每条消息都会根据其来源被路 - `main`（默认）——所有私信共享一个会话。 - `per-peer`——按发送者隔离（跨渠道）。 - `per-channel-peer`——按渠道 + 发送者隔离（推荐）。 -- `per-account-channel-peer`——按账户 + 渠道 + 发送者隔离。 +- `per-account-channel-peer`——按账号 + 渠道 + 发送者隔离。 -如果同一个人通过多个渠道联系你，请使用 `session.identityLinks` 关联他们的身份，这样他们就会共享同一个会话。 +如果同一个人通过多个渠道联系你，请使用 +`session.identityLinks` 关联他们的身份，这样他们就会共享一个会话。 使用 `openclaw security audit` 验证你的设置。 ## 会话生命周期 -会话会被重复使用，直到它们过期： +会话会被重复使用，直到过期： -- **每日重置**（默认）——在 Gateway 网关宿主机的本地时间凌晨 4:00 创建新会话。每日新鲜度基于当前 `sessionId` 何时开始，而不是基于后续元数据写入时间。 -- **空闲重置**（可选）——在一段不活动时间后创建新会话。设置 `session.reset.idleMinutes`。空闲新鲜度基于最后一次真实的用户/渠道交互，因此 heartbeat、cron 和 exec 系统事件不会让会话保持活跃。 +- **每日重置**（默认）——在 Gateway 网关主机本地时间凌晨 4:00 创建新会话。每日新鲜度基于当前 `sessionId` 的开始时间，而不是后续元数据写入时间。 +- **空闲重置**（可选）——在一段时间无活动后创建新会话。设置 `session.reset.idleMinutes`。空闲新鲜度基于最近一次真实的用户/渠道交互，因此 heartbeat、cron 和 exec 系统事件不会让会话保持活跃。 - **手动重置**——在聊天中输入 `/new` 或 `/reset`。`/new ` 还会切换模型。 -当同时配置每日重置和空闲重置时，谁先到期就以谁为准。heartbeat、cron、exec 以及其他系统事件轮次可能会写入会话元数据，但这些写入不会延长每日或空闲重置的新鲜度。 +当同时配置每日重置和空闲重置时，先到期的那个生效。heartbeat、cron、exec 以及其他系统事件轮次可能会写入会话元数据，但这些写入不会延长每日或空闲重置的新鲜度。当重置切换会话时，旧会话中排队的系统事件通知会被丢弃，这样过时的后台更新就不会被预加到新会话的第一条提示中。 -拥有活跃的提供商自有 CLI 会话的会话，不会因隐式的默认每日重置而被切断。当这些会话应按定时器过期时，请使用 `/reset` 或显式配置 `session.reset`。 +带有处于活动状态、由提供商拥有的 CLI 会话的会话，不会被隐式的默认每日重置切断。当这些会话需要按计时器过期时，请使用 `/reset` 或显式配置 `session.reset`。 ## 状态存储位置 @@ -76,17 +77,17 @@ OpenClaw 将对话组织为**会话**。每条消息都会根据其来源被路 - **存储：** `~/.openclaw/agents//sessions/sessions.json` - **转录：** `~/.openclaw/agents//sessions/.jsonl` -`sessions.json` 会保留彼此独立的生命周期时间戳： +`sessions.json` 保存独立的生命周期时间戳： - `sessionStartedAt`：当前 `sessionId` 开始的时间；每日重置使用它。 -- `lastInteractionAt`：最后一次会延长空闲存活时间的用户/渠道交互时间。 -- `updatedAt`：最后一次存储行变更时间；对列出和清理很有用，但不能作为每日/空闲重置新鲜度的权威依据。 +- `lastInteractionAt`：最近一次会延长空闲生命周期的用户/渠道交互时间。 +- `updatedAt`：最近一次存储行变更时间；适合用于列出和修剪，但不能作为每日/空闲重置新鲜度的权威依据。 -对于缺少 `sessionStartedAt` 的旧记录，如果可用，会从转录 JSONL 会话头中解析。如果旧记录也缺少 `lastInteractionAt`，则空闲新鲜度会回退到该会话开始时间，而不是后续的簿记写入时间。 +旧记录中如果没有 `sessionStartedAt`，会在可用时从转录 JSONL 会话头中解析。如果旧记录同时缺少 `lastInteractionAt`，空闲新鲜度会回退到该会话开始时间，而不是后续的簿记写入时间。 ## 会话维护 -OpenClaw 会随着时间自动限制会话存储的规模。默认情况下，它运行在 `warn` 模式下（报告将会清理哪些内容）。将 `session.maintenance.mode` 设置为 `"enforce"` 以启用自动清理： +OpenClaw 会随着时间推移自动限制会话存储规模。默认情况下，它以 `warn` 模式运行（报告将会清理哪些内容）。将 `session.maintenance.mode` 设置为 `"enforce"` 可启用自动清理： ```json5 { @@ -106,18 +107,18 @@ OpenClaw 会随着时间自动限制会话存储的规模。默认情况下， - `openclaw status`——会话存储路径和最近活动。 - `openclaw sessions --json`——所有会话（可使用 `--active ` 过滤）。 -- 聊天中的 `/status`——上下文使用情况、模型和切换项。 -- `/context list`——系统提示词中包含的内容。 +- 聊天中的 `/status`——上下文使用情况、模型和开关状态。 +- `/context list`——系统提示中包含的内容。 -## 延伸阅读 +## 进一步阅读 - [会话修剪](/zh-CN/concepts/session-pruning)——裁剪工具结果 - [压缩](/zh-CN/concepts/compaction)——总结长对话 - [会话工具](/zh-CN/concepts/session-tool)——用于跨会话工作的智能体工具 -- [会话管理深入解析](/zh-CN/reference/session-management-compaction)——存储架构、转录、发送策略、来源元数据和高级配置 +- [会话管理深入解析](/zh-CN/reference/session-management-compaction)——存储结构、转录、发送策略、来源元数据和高级配置 - [多智能体](/zh-CN/concepts/multi-agent) — 跨智能体的路由和会话隔离 -- [后台任务](/zh-CN/automation/tasks) — 分离工作如何创建带有会话引用的任务记录 -- [渠道路由](/zh-CN/channels/channel-routing) — 入站消息如何被路由到会话 +- [后台任务](/zh-CN/automation/tasks) — 分离式工作如何创建带有会话引用的任务记录 +- [渠道路由](/zh-CN/channels/channel-routing) — 入站消息如何路由到会话 ## 相关内容 diff --git a/docs/zh-CN/reference/session-management-compaction.md b/docs/zh-CN/reference/session-management-compaction.md index 56ade6e4c..49bfe6d1f 100644 --- a/docs/zh-CN/reference/session-management-compaction.md +++ b/docs/zh-CN/reference/session-management-compaction.md @@ -1,68 +1,68 @@ --- read_when: - - 你需要调试会话 id、transcript JSONL 或 `sessions.json` 字段 - - 你正在更改自动压缩行为或添加“压缩前”清理逻辑 - - 你想实现 memory flush 或静默系统轮次 + - 你需要调试会话 ID、转录记录 JSONL 或 `sessions.json` 字段 + - 你正在更改自动压缩行为，或添加“压缩前”清理流程 + - 你想要实现内存刷新或静默系统轮次 summary: 深入解析：会话存储 + 转录记录、生命周期，以及（自动）压缩内部机制 title: 会话管理深入解析 x-i18n: - generated_at: "2026-04-26T01:46:40Z" + generated_at: "2026-04-26T02:12:52Z" model: gpt-5.4 provider: openai - source_hash: 5593cb9a2da91892c96f4162c57cf71177e7301d30c6e9d0e1f1a3fe13448735 + source_hash: f41f1c403f978c22cc2a929629e1811414d1399fa7f9e28c481fcb594d30196f source_path: reference/session-management-compaction.md workflow: 15 --- -本页说明 OpenClaw 如何端到端管理会话： +本页解释 OpenClaw 如何端到端管理会话： - **会话路由**（入站消息如何映射到 `sessionKey`） - **会话存储**（`sessions.json`）及其跟踪内容 - **转录记录持久化**（`*.jsonl`）及其结构 -- **转录记录卫生**（运行前按提供商执行的特定修正） -- **上下文限制**（上下文窗口 vs 已跟踪 token） -- **压缩**（手动 + 自动压缩）以及在哪里挂接压缩前工作 -- **静默清理**（例如不应产生用户可见输出的 memory 写入） +- **转录记录清理**（运行前按提供商进行的特定修正） +- **上下文限制**（上下文窗口与已跟踪 token） +- **压缩**（手动 + 自动压缩）以及在何处挂接压缩前工作 +- **静默清理流程**（例如不应产生用户可见输出的内存写入） -如果你想先看更高层的概览，请从以下页面开始： +如果你想先看更高层的概览，请先从以下页面开始： - [会话管理](/zh-CN/concepts/session) - [压缩](/zh-CN/concepts/compaction) -- [Memory 概览](/zh-CN/concepts/memory) -- [Memory 搜索](/zh-CN/concepts/memory-search) +- [内存概览](/zh-CN/concepts/memory) +- [内存搜索](/zh-CN/concepts/memory-search) - [会话修剪](/zh-CN/concepts/session-pruning) -- [转录记录卫生](/zh-CN/reference/transcript-hygiene) +- [转录记录清理](/zh-CN/reference/transcript-hygiene) --- ## 事实来源：Gateway 网关 -OpenClaw 围绕一个拥有会话状态的单一 **Gateway 网关进程** 进行设计。 +OpenClaw 围绕一个拥有会话状态的单一 **Gateway 网关进程** 而设计。 -- UI（macOS 应用、web Control UI、TUI）应通过 Gateway 网关查询会话列表和 token 计数。 +- UI（macOS 应用、Web Control UI、TUI）应通过 Gateway 网关查询会话列表和 token 计数。 - 在远程模式下，会话文件位于远程主机上；“检查你本地 Mac 上的文件”并不能反映 Gateway 网关实际使用的内容。 --- ## 两层持久化 -OpenClaw 用两层来持久化会话： +OpenClaw 以两层方式持久化会话： 1. **会话存储（`sessions.json`）** - 键/值映射：`sessionKey -> SessionEntry` - - 小型、可变、可安全编辑（或删除条目） - - 跟踪会话元数据（当前会话 id、最后活动时间、开关、token 计数器等） + - 体积小、可变、安全可编辑（或删除条目） + - 跟踪会话元数据（当前会话 id、最后活动时间、切换项、token 计数器等） 2. **转录记录（`.jsonl`）** - - 追加式转录记录，带树状结构（条目具有 `id` + `parentId`） + - 追加写入的转录记录，具有树结构（条目带有 `id` + `parentId`） - 存储实际对话 + 工具调用 + 压缩摘要 - 用于为未来轮次重建模型上下文 --- -## 磁盘位置 +## 磁盘上的位置 -在 Gateway 网关主机上，按智能体区分： +每个智能体在 Gateway 网关主机上的位置： - 存储：`~/.openclaw/agents//sessions/sessions.json` - 转录记录：`~/.openclaw/agents//sessions/.jsonl` @@ -74,23 +74,23 @@ OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。 ## 存储维护和磁盘控制 -会话持久化为 `sessions.json` 和转录记录工件提供了自动维护控制（`session.maintenance`）： +会话持久化带有自动维护控制项（`session.maintenance`），用于管理 `sessions.json` 和转录记录产物： - `mode`：`warn`（默认）或 `enforce` -- `pruneAfter`：陈旧条目年龄截止值（默认 `30d`） -- `maxEntries`：`sessions.json` 中条目的数量上限（默认 `500`） +- `pruneAfter`：陈旧条目的保留期限截止值（默认 `30d`） +- `maxEntries`：`sessions.json` 中的条目上限（默认 `500`） - `rotateBytes`：当 `sessions.json` 过大时进行轮转（默认 `10mb`） -- `resetArchiveRetention`：`*.reset.` 转录记录归档的保留期（默认：与 `pruneAfter` 相同；`false` 禁用清理） -- `maxDiskBytes`：可选的 sessions 目录预算 +- `resetArchiveRetention`：`*.reset.` 转录记录归档的保留期（默认：与 `pruneAfter` 相同；`false` 表示禁用清理） +- `maxDiskBytes`：可选的 sessions 目录容量预算 - `highWaterBytes`：清理后的可选目标值（默认是 `maxDiskBytes` 的 `80%`） 磁盘预算清理的执行顺序（`mode: "enforce"`）： -1. 先删除最旧的归档或孤立转录记录工件。 +1. 先删除最旧的已归档或孤立的转录记录产物。 2. 如果仍高于目标值，则逐出最旧的会话条目及其转录记录文件。 3. 持续执行，直到使用量小于或等于 `highWaterBytes`。 -在 `mode: "warn"` 下，OpenClaw 会报告潜在逐出项，但不会修改存储/文件。 +在 `mode: "warn"` 下，OpenClaw 会报告潜在的逐出操作，但不会修改存储/文件。 按需运行维护： @@ -103,22 +103,22 @@ openclaw sessions cleanup --enforce ## Cron 会话和运行日志 -隔离的 cron 运行也会创建会话条目/转录记录，并且它们有专用的保留控制： +隔离的 cron 运行也会创建会话条目/转录记录，并且它们有专门的保留控制项： -- `cron.sessionRetention`（默认 `24h`）会从会话存储中修剪旧的隔离 cron 运行会话（`false` 禁用）。 +- `cron.sessionRetention`（默认 `24h`）会从会话存储中修剪旧的隔离 cron 运行会话（`false` 表示禁用）。 - `cron.runLog.maxBytes` + `cron.runLog.keepLines` 会修剪 `~/.openclaw/cron/runs/.jsonl` 文件（默认值：`2_000_000` 字节和 `2000` 行）。 -当 cron 强制创建新的隔离运行会话时，它会在写入新行之前清理先前的 `cron:` 会话条目。它会保留安全的偏好设置，例如 thinking/fast/verbose 设置、标签以及用户明确选择的模型/认证覆盖项。它会丢弃环境性对话上下文，例如渠道/群组路由、发送或队列策略、提权、来源和 ACP 运行时绑定，以便新的隔离运行不会从旧运行中继承过期的投递或运行时权限。 +当 cron 强制创建新的隔离运行会话时，它会在写入新行之前清理先前的 `cron:` 会话条目。它会保留安全的偏好设置，例如 thinking/fast/verbose 设置、标签，以及用户显式选择的 model/auth 覆盖项。它会丢弃环境性对话上下文，例如 channel/group 路由、发送或队列策略、提权、来源以及 ACP 运行时绑定，以便新的隔离运行不会从旧运行中继承过期的投递或运行时权限。 --- ## 会话键（`sessionKey`） -`sessionKey` 用于标识你处于哪个 _对话分桶_ 中（路由 + 隔离）。 +`sessionKey` 用于标识你位于 _哪个对话桶_ 中（路由 + 隔离）。 常见模式： -- 主/直接聊天（每个智能体）：`agent::`（默认 `main`） +- 主/私聊（每个智能体）：`agent::`（默认 `main`） - 群组：`agent:::group:` - 房间/渠道（Discord/Slack）：`agent:::channel:` 或 `...:room:` - Cron：`cron:` @@ -130,17 +130,17 @@ openclaw sessions cleanup --enforce ## 会话 id（`sessionId`） -每个 `sessionKey` 都指向当前的 `sessionId`（即继续该对话的转录记录文件）。 +每个 `sessionKey` 都指向一个当前的 `sessionId`（用于延续对话的转录记录文件）。 经验规则： - **重置**（`/new`、`/reset`）会为该 `sessionKey` 创建新的 `sessionId`。 -- **每日重置**（默认在 Gateway 网关主机本地时间凌晨 4:00）会在越过重置边界后的下一条消息到来时创建新的 `sessionId`。 -- **空闲过期**（`session.reset.idleMinutes` 或旧版 `session.idleMinutes`）会在空闲窗口后有消息到达时创建新的 `sessionId`。当同时配置了每日重置和空闲过期时，谁先过期就以谁为准。 -- **系统事件**（心跳、cron 唤醒、exec 通知、Gateway 网关簿记）可能会修改会话行，但不会延长每日/空闲重置的新鲜度。 -- **线程父分叉保护**（`session.parentForkMaxTokens`，默认 `100000`）会在父会话已经过大时跳过父转录记录分叉；新线程会从头开始。设为 `0` 可禁用。 +- **每日重置**（默认在 Gateway 网关主机本地时间凌晨 4:00）会在越过重置边界后的下一条消息时创建新的 `sessionId`。 +- **空闲过期**（`session.reset.idleMinutes` 或旧版 `session.idleMinutes`）会在消息于空闲窗口结束后到达时创建新的 `sessionId`。当同时配置了每日重置和空闲重置时，以先到期者为准。 +- **系统事件**（心跳、cron 唤醒、exec 通知、Gateway 网关记账流程）可能会修改会话行，但不会延长每日/空闲重置的新鲜度。在构建新的提示词之前，重置切换会丢弃上一会话排队中的系统事件通知。 +- **线程父级分叉保护**（`session.parentForkMaxTokens`，默认 `100000`）会在父会话已经过大时跳过父转录记录分叉；新线程将从全新状态开始。设置为 `0` 可禁用。 -实现细节：该决策发生在 `src/auto-reply/reply/session.ts` 的 `initSessionState()` 中。 +实现细节：这一决定发生在 `src/auto-reply/reply/session.ts` 中的 `initSessionState()`。 --- @@ -150,25 +150,25 @@ openclaw sessions cleanup --enforce 关键字段（非完整列表）： -- `sessionId`：当前转录记录 id（除非设置了 `sessionFile`，否则文件名由此派生） -- `sessionStartedAt`：当前 `sessionId` 的起始时间戳；每日重置的新鲜度使用该字段。旧版行可能会从 JSONL 会话头派生该值。 -- `lastInteractionAt`：最后一次真实用户/渠道交互时间戳；空闲重置的新鲜度使用该字段，这样心跳、cron 和 exec 事件就不会让会话持续存活。没有此字段的旧版行会回退到恢复出的会话起始时间来判断空闲新鲜度。 -- `updatedAt`：最后一次存储行修改时间戳，用于列表、修剪和簿记。它不是每日/空闲重置新鲜度的权威来源。 +- `sessionId`：当前转录记录 id（除非设置了 `sessionFile`，否则文件名由此推导） +- `sessionStartedAt`：当前 `sessionId` 的开始时间戳；每日重置的新鲜度基于它。旧版行可能会从 JSONL 会话头推导它。 +- `lastInteractionAt`：最后一次真实用户/渠道交互的时间戳；空闲重置的新鲜度基于它，因此心跳、cron 和 exec 事件不会让会话保持活跃。旧版行若没有该字段，则会回退到恢复出的会话开始时间作为空闲新鲜度依据。 +- `updatedAt`：最后一次存储行变更的时间戳，用于列表、修剪和记账流程。它并不是每日/空闲重置新鲜度的权威依据。 - `sessionFile`：可选的显式转录记录路径覆盖 - `chatType`：`direct | group | room`（帮助 UI 和发送策略） -- `provider`、`subject`、`room`、`space`、`displayName`：用于群组/渠道标记的元数据 -- 开关： +- `provider`、`subject`、`room`、`space`、`displayName`：用于群组/渠道标签的元数据 +- 切换项： - `thinkingLevel`、`verboseLevel`、`reasoningLevel`、`elevatedLevel` - - `sendPolicy`（每会话覆盖） + - `sendPolicy`（按会话覆盖） - 模型选择： - `providerOverride`、`modelOverride`、`authProfileOverride` -- token 计数器（尽力而为 / 依赖提供商）： +- Token 计数器（尽力而为 / 取决于提供商）： - `inputTokens`、`outputTokens`、`totalTokens`、`contextTokens` -- `compactionCount`：该会话键完成自动压缩的次数 -- `memoryFlushAt`：最后一次压缩前 memory flush 的时间戳 -- `memoryFlushCompactionCount`：最后一次 flush 运行时的压缩计数 +- `compactionCount`：此会话键已完成自动压缩的次数 +- `memoryFlushAt`：上一次压缩前内存刷新的时间戳 +- `memoryFlushCompactionCount`：上一次刷新执行时的压缩计数 -该存储可以安全编辑，但 Gateway 网关才是权威：会话运行过程中，它可能会重写或重新填充条目。 +该存储可以安全编辑，但 Gateway 网关才是权威：随着会话运行，它可能会重写或重新补全条目。 --- @@ -179,54 +179,54 @@ openclaw sessions cleanup --enforce 该文件是 JSONL： - 第一行：会话头（`type: "session"`，包含 `id`、`cwd`、`timestamp`、可选的 `parentSession`） -- 然后：带有 `id` + `parentId` 的会话条目（树状） +- 之后：带有 `id` + `parentId` 的会话条目（树结构） 值得注意的条目类型： -- `message`：用户/助手/`toolResult` 消息 -- `custom_message`：由扩展注入的消息，_会_ 进入模型上下文（可在 UI 中隐藏） -- `custom`：不会进入模型上下文的扩展状态 -- `compaction`：持久化的压缩摘要，包含 `firstKeptEntryId` 和 `tokensBefore` -- `branch_summary`：导航树分支时持久化的摘要 +- `message`：用户/assistant/toolResult 消息 +- `custom_message`：由扩展注入、且 _会_ 进入模型上下文的消息（可在 UI 中隐藏） +- `custom`：_不会_ 进入模型上下文的扩展状态 +- `compaction`：持久化的压缩摘要，带有 `firstKeptEntryId` 和 `tokensBefore` +- `branch_summary`：在导航树分支时持久化的摘要 -OpenClaw 有意 **不会** “修正” 转录记录；Gateway 网关使用 `SessionManager` 来读取/写入它们。 +OpenClaw 有意 **不会** “修正” 转录记录；Gateway 网关使用 `SessionManager` 来读写它们。 --- -## 上下文窗口 vs 已跟踪 token +## 上下文窗口与已跟踪 token -这里有两个不同的概念： +这里有两个不同但都重要的概念： -1. **模型上下文窗口**：每个模型的硬上限（模型可见的 token） +1. **模型上下文窗口**：每个模型的硬上限（模型可见的 token 数） 2. **会话存储计数器**：写入 `sessions.json` 的滚动统计（用于 `/status` 和仪表板） -如果你正在调优限制： +如果你在调整限制： - 上下文窗口来自模型目录（也可通过配置覆盖）。 -- 存储中的 `contextTokens` 是运行时估计/报告值；不要把它当作严格保证。 +- 存储中的 `contextTokens` 是运行时估算/报告值；不要把它当作严格保证。 -更多信息，参见 [/token-use](/zh-CN/reference/token-use)。 +更多内容请参见 [/token-use](/zh-CN/reference/token-use)。 --- ## 压缩：它是什么 -压缩会将较早的对话总结为转录记录中持久化的 `compaction` 条目，并保留最近消息不变。 +压缩会将较早的对话总结为转录记录中的持久化 `compaction` 条目，并保留最近的消息不变。 压缩后，未来轮次将看到： - 压缩摘要 - `firstKeptEntryId` 之后的消息 -压缩是 **持久的**（不同于会话修剪）。参见 [/concepts/session-pruning](/zh-CN/concepts/session-pruning)。 +压缩是 **持久化的**（不同于会话修剪）。参见 [/concepts/session-pruning](/zh-CN/concepts/session-pruning)。 -## 压缩分块边界与工具配对 +## 压缩分块边界和工具配对 -当 OpenClaw 将长转录记录拆分为压缩分块时，它会让助手工具调用与其匹配的 `toolResult` 条目保持配对。 +当 OpenClaw 将长转录记录拆分为多个压缩分块时，它会让 assistant 工具调用与其对应的 `toolResult` 条目保持配对。 -- 如果 token 占比分割点落在某次工具调用和其结果之间，OpenClaw 会将边界移到助手工具调用消息处，而不是把这对拆开。 -- 如果尾部的工具结果块本来会让分块超出目标大小，OpenClaw 会保留这个待处理的工具块，并保持未摘要的尾部内容完整。 -- 已中止/出错的工具调用块不会让待处理分割一直保持打开状态。 +- 如果 token 占比分割点落在工具调用和其结果之间，OpenClaw 会将边界移到 assistant 工具调用消息处，而不是拆开这对条目。 +- 如果末尾的工具结果块本来会让该分块超过目标大小，OpenClaw 会保留这个待处理的工具块，并保持未总结的尾部完整。 +- 已中止/报错的工具调用块不会让待处理的拆分保持打开状态。 --- @@ -238,15 +238,15 @@ OpenClaw 有意 **不会** “修正” 转录记录；Gateway 网关使用 `Ses （`request_too_large`、`context length exceeded`、`input exceeds the maximum number of tokens`、`input token count exceeds the maximum number of input tokens`、`input is too long for the model`、`ollama error: context length -exceeded`，以及类似的提供商形态变体）→ 压缩 → 重试。 -2. **阈值维护**：成功完成一轮后，当： +exceeded`，以及类似的提供商风格变体）→ 压缩 → 重试。 +2. **阈值维护**：在一次成功轮次之后，当： `contextTokens > contextWindow - reserveTokens` 其中： - `contextWindow` 是模型的上下文窗口 -- `reserveTokens` 是为提示词 + 下一次模型输出预留的空间 +- `reserveTokens` 是为提示词 + 下一次模型输出预留的余量 这些是 Pi 运行时语义（OpenClaw 会消费这些事件，但由 Pi 决定何时压缩）。 @@ -254,7 +254,7 @@ exceeded`，以及类似的提供商形态变体）→ 压缩 → 重试。 ## 压缩设置（`reserveTokens`、`keepRecentTokens`） -Pi 的压缩设置位于 Pi 设置中： +Pi 的压缩设置位于 Pi settings 中： ```json5 { @@ -266,15 +266,15 @@ Pi 的压缩设置位于 Pi 设置中： } ``` -OpenClaw 还会为嵌入式运行强制一个安全下限： +OpenClaw 还会为嵌入式运行强制执行一个安全下限： -- 如果 `compaction.reserveTokens < reserveTokensFloor`，OpenClaw 会将其提高。 +- 如果 `compaction.reserveTokens < reserveTokensFloor`，OpenClaw 会将其提升。 - 默认下限是 `20000` token。 -- 设置 `agents.defaults.compaction.reserveTokensFloor: 0` 可禁用该下限。 -- 如果它本来就更高，OpenClaw 不会更改。 -- 手动 `/compact` 会遵循显式的 `agents.defaults.compaction.keepRecentTokens`，并保留 Pi 的最近尾部分割点。如果没有显式的保留预算，手动压缩仍然是一个硬检查点，重建后的上下文将从新摘要开始。 +- 设置 `agents.defaults.compaction.reserveTokensFloor: 0` 可禁用此下限。 +- 如果它已经更高，OpenClaw 不会更改。 +- 手动 `/compact` 会遵循显式的 `agents.defaults.compaction.keepRecentTokens`，并保留 Pi 的最近尾部截断点。如果没有显式的保留预算，手动压缩仍然是一个硬检查点，重建后的上下文会从新的摘要开始。 -原因：在压缩变得不可避免之前，留出足够空间用于多轮“清理”工作（例如 memory 写入）。 +原因：在压缩变得不可避免之前，为多轮“清理流程”（例如内存写入）留出足够的余量。 实现：`src/agents/pi-settings.ts` 中的 `ensurePiCompactionReserveTokens()` （由 `src/agents/pi-embedded-runner.ts` 调用）。 @@ -283,88 +283,88 @@ OpenClaw 还会为嵌入式运行强制一个安全下限： ## 可插拔压缩提供商 -插件可以通过插件 API 上的 `registerCompactionProvider()` 注册一个压缩提供商。当 `agents.defaults.compaction.provider` 被设置为某个已注册提供商 id 时，保护扩展会将摘要生成委托给该提供商，而不是使用内置的 `summarizeInStages` 流水线。 +插件可以通过插件 API 上的 `registerCompactionProvider()` 注册一个压缩提供商。当设置 `agents.defaults.compaction.provider` 为某个已注册提供商 id 时，safeguard 扩展会将摘要生成委托给该提供商，而不是使用内置的 `summarizeInStages` 流程。 -- `provider`：已注册压缩提供商插件的 id。不设置则使用默认 LLM 摘要生成。 +- `provider`：已注册压缩提供商插件的 id。不设置则使用默认的 LLM 摘要生成。 - 设置 `provider` 会强制使用 `mode: "safeguard"`。 -- 提供商会接收与内置路径相同的压缩指令和标识符保留策略。 +- 提供商接收与内置路径相同的压缩指令和标识符保留策略。 - 在提供商输出之后，safeguard 仍会保留最近轮次和拆分轮次的后缀上下文。 -- 内置 safeguard 摘要生成会用新消息重新提炼先前摘要，而不是原样保留之前的完整摘要。 +- 内置 safeguard 摘要生成会使用新消息重新提炼先前的摘要，而不是原样完整保留之前的摘要。 - safeguard 模式默认启用摘要质量审计；设置 - `qualityGuard.enabled: false` 可跳过输出格式错误时的重试行为。 + `qualityGuard.enabled: false` 可跳过输出格式异常时的重试行为。 - 如果提供商失败或返回空结果，OpenClaw 会自动回退到内置 LLM 摘要生成。 -- 中止/超时信号会被重新抛出（不会被吞掉），以遵循调用方取消逻辑。 +- 中止/超时信号会被重新抛出（不会被吞掉），以尊重调用方取消操作。 来源：`src/plugins/compaction-provider.ts`、`src/agents/pi-hooks/compaction-safeguard.ts`。 --- -## 面向用户的表面 +## 用户可见的界面 你可以通过以下方式观察压缩和会话状态： -- `/status`（在任意聊天会话中） +- `/status`（在任何聊天会话中） - `openclaw status`（CLI） - `openclaw sessions` / `sessions --json` - 详细模式：`🧹 Auto-compaction complete` + 压缩计数 --- -## 静默清理（`NO_REPLY`） +## 静默清理流程（`NO_REPLY`） -OpenClaw 支持用于后台任务的“静默”轮次，在这种情况下，用户不应看到中间输出。 +OpenClaw 支持用于后台任务的“静默”轮次，在这种情况下用户不应看到中间输出。 -约定： +约定如下： -- 助手会以精确的静默标记 `NO_REPLY` / - `no_reply` 开始其输出，用于表示“不要向用户投递回复”。 -- OpenClaw 会在投递层中剥离/抑制它。 -- 精确静默标记抑制不区分大小写，因此当整个载荷仅为该静默标记时，`NO_REPLY` 和 +- assistant 以精确的静默 token `NO_REPLY` / + `no_reply` 开始输出，以表示“不要向用户发送回复”。 +- OpenClaw 会在投递层中剥离/抑制该内容。 +- 对精确静默 token 的抑制是大小写不敏感的，因此当整个负载仅为该静默 token 时，`NO_REPLY` 和 `no_reply` 都会生效。 -- 这仅适用于真正的后台/无投递轮次；它不是普通可执行用户请求的捷径。 +- 这仅适用于真正的后台/不投递轮次；它不是普通可执行用户请求的捷径。 -自 `2026.1.10` 起，当部分分块以 `NO_REPLY` 开头时，OpenClaw 还会抑制 **草稿/打字流式传输**，这样静默操作就不会在轮次中途泄露部分输出。 +从 `2026.1.10` 起，当部分分块以 `NO_REPLY` 开始时，OpenClaw 还会抑制 **草稿/输入中流式传输**，因此静默操作不会在轮次中途泄露部分输出。 --- -## 压缩前 “memory flush”（已实现） +## 压缩前“内存刷新”（已实现） -目标：在自动压缩发生之前，运行一个静默的智能体轮次，将持久状态写入磁盘（例如智能体工作区中的 `memory/YYYY-MM-DD.md`），这样压缩就无法抹去关键上下文。 +目标：在自动压缩发生之前，运行一个静默的智能体轮次，将持久状态写入磁盘（例如智能体工作区中的 `memory/YYYY-MM-DD.md`），这样压缩就不会抹去关键上下文。 -OpenClaw 使用 **预阈值 flush** 方法： +OpenClaw 使用 **预阈值刷新** 方案： 1. 监控会话上下文使用量。 -2. 当它越过“软阈值”（低于 Pi 的压缩阈值）时，向智能体运行一个静默的“立即写入 memory”指令。 -3. 使用精确的静默标记 `NO_REPLY` / `no_reply`，这样用户什么也看不到。 +2. 当其跨过“软阈值”（低于 Pi 的压缩阈值）时，向智能体运行一个静默的“立即写入内存”指令。 +3. 使用精确的静默 token `NO_REPLY` / `no_reply`，这样用户什么也看不到。 配置（`agents.defaults.compaction.memoryFlush`）： - `enabled`（默认：`true`） - `softThresholdTokens`（默认：`4000`） -- `prompt`（flush 轮次的用户消息） -- `systemPrompt`（附加到 flush 轮次的额外系统提示） +- `prompt`（刷新轮次的用户消息） +- `systemPrompt`（附加到刷新轮次的额外系统提示词） 说明： -- 默认 prompt/system prompt 包含 `NO_REPLY` 提示，以抑制投递。 -- 每个压缩周期只运行一次 flush（在 `sessions.json` 中跟踪）。 -- flush 仅对嵌入式 Pi 会话运行（CLI 后端会跳过它）。 -- 当会话工作区为只读时（`workspaceAccess: "ro"` 或 `"none"`），会跳过 flush。 +- 默认 prompt/system prompt 包含一个 `NO_REPLY` 提示，用于抑制投递。 +- 每个压缩周期只运行一次刷新（在 `sessions.json` 中跟踪）。 +- 刷新仅对嵌入式 Pi 会话运行（CLI 后端会跳过）。 +- 当会话工作区为只读时会跳过刷新（`workspaceAccess: "ro"` 或 `"none"`）。 - 有关工作区文件布局和写入模式，请参见 [Memory](/zh-CN/concepts/memory)。 -Pi 也会在扩展 API 中暴露 `session_before_compact` 钩子，但 OpenClaw 的 flush 逻辑目前位于 Gateway 网关侧。 +Pi 也会在扩展 API 中公开一个 `session_before_compact` 钩子，但 OpenClaw 当前的刷新逻辑位于 Gateway 网关侧。 --- ## 故障排除清单 -- 会话键错误？先查看 [/concepts/session](/zh-CN/concepts/session)，并在 `/status` 中确认 `sessionKey`。 -- 存储与转录记录不匹配？确认 Gateway 网关主机以及 `openclaw status` 显示的存储路径。 +- 会话键不对？从 [/concepts/session](/zh-CN/concepts/session) 开始，并在 `/status` 中确认 `sessionKey`。 +- 存储与转录记录不匹配？确认 Gateway 网关主机以及 `openclaw status` 中显示的存储路径。 - 压缩过于频繁？检查： - - 模型上下文窗口（过小） + - 模型上下文窗口（是否过小） - 压缩设置（对于模型窗口来说，`reserveTokens` 过高会导致更早压缩） - - 工具结果膨胀：启用/调优会话修剪 -- 静默轮次泄露？确认回复以 `NO_REPLY` 开头（精确标记，不区分大小写），并且你使用的是包含流式传输抑制修复的构建版本。 + - 工具结果膨胀：启用/调整会话修剪 +- 静默轮次泄露内容？确认回复以 `NO_REPLY` 开头（大小写不敏感的精确 token），并且你使用的构建版本包含流式抑制修复。 ## 相关内容