diff --git a/docs/zh-CN/cli/agents.md b/docs/zh-CN/cli/agents.md index 7e89f98b5..eebf4dd6c 100644 --- a/docs/zh-CN/cli/agents.md +++ b/docs/zh-CN/cli/agents.md @@ -1,13 +1,13 @@ --- read_when: - - 你想要多个相互隔离的智能体（工作区 + 路由 + 凭证） + - 你想要多个彼此隔离的智能体（工作区 + 路由 + 认证） summary: '`openclaw agents` 的 CLI 参考（list/add/delete/bindings/bind/unbind/set identity）' title: 智能体 x-i18n: - generated_at: "2026-04-29T10:59:37Z" + generated_at: "2026-05-02T12:44:58Z" model: gpt-5.5 provider: openai - source_hash: 46742a890a57cb1035a053f14fe574044e4a3d7dcc04812cd11c633bd808819b + source_hash: 3522394dd416a9c8b4bf25767a14073484df0ff3d7c546cf6c730f111c5c51dc source_path: cli/agents.md workflow: 16 --- @@ -16,11 +16,11 @@ x-i18n: 管理隔离的智能体（工作区 + 凭证 + 路由）。 -相关： +相关内容： - [多智能体路由](/zh-CN/concepts/multi-agent) - [Agent 工作区](/zh-CN/concepts/agent-workspace) -- [Skills 配置](/zh-CN/tools/skills-config)：Skill 可见性配置。 +- [Skills 配置](/zh-CN/tools/skills-config)：技能可见性配置。 ## 示例 @@ -41,7 +41,7 @@ openclaw agents delete work 使用路由绑定将入站渠道流量固定到特定智能体。 -如果你还想为每个智能体配置不同的可见 Skills，请在 `openclaw.json` 中配置 `agents.defaults.skills` 和 `agents.list[].skills`。请参阅 [Skills 配置](/zh-CN/tools/skills-config)和[配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。 +如果你还想为每个智能体配置不同的可见 Skills，请在 `openclaw.json` 中配置 `agents.defaults.skills` 和 `agents.list[].skills`。请参阅 [Skills 配置](/zh-CN/tools/skills-config) 和 [配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。 列出绑定： @@ -57,15 +57,15 @@ openclaw agents bindings --json openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a ``` -如果省略 `accountId`（`--bind `），OpenClaw 会在可用时从渠道默认值和插件设置钩子解析它。 +如果省略 `accountId`（`--bind `），OpenClaw 会在可用时从渠道默认值和插件设置钩子中解析它。 -如果为 `bind` 或 `unbind` 省略 `--agent`，OpenClaw 会以当前默认智能体为目标。 +如果对 `bind` 或 `unbind` 省略 `--agent`，OpenClaw 会以当前默认智能体为目标。 -### 绑定作用域行为 +### 绑定范围行为 -- 没有 `accountId` 的绑定仅匹配渠道默认账号。 -- `accountId: "*"` 是渠道范围内的后备项（所有账号），其优先级低于显式账号绑定。 -- 如果同一个智能体已经有一个不带 `accountId` 的匹配渠道绑定，而你稍后使用显式或已解析的 `accountId` 绑定，OpenClaw 会就地升级该现有绑定，而不是添加重复项。 +- 没有 `accountId` 的绑定只匹配渠道默认账号。 +- `accountId: "*"` 是渠道范围的后备项（所有账号），其优先级低于显式账号绑定。 +- 如果同一个智能体已经有一个匹配的、没有 `accountId` 的渠道绑定，而你稍后使用显式或解析出的 `accountId` 进行绑定，OpenClaw 会就地升级现有绑定，而不是添加重复项。 示例： @@ -86,9 +86,9 @@ openclaw agents unbind --agent work --bind telegram:ops openclaw agents unbind --agent work --all ``` -`unbind` 接受 `--all` 或一个或多个 `--bind` 值，但不能同时使用二者。 +`unbind` 接受 `--all` 或一个或多个 `--bind` 值，不能同时使用两者。 -## 命令界面 +## 命令表面 ### `agents` @@ -99,7 +99,7 @@ openclaw agents unbind --agent work --all 选项： - `--json` -- `--bindings`：包含完整路由规则，而不只是按智能体的计数/摘要 +- `--bindings`：包含完整路由规则，而不仅是每个智能体的计数/摘要 ### `agents add [name]` @@ -112,14 +112,14 @@ openclaw agents unbind --agent work --all - `--non-interactive` - `--json` -说明： +注意： - 传入任何显式添加标志都会将命令切换到非交互路径。 - 非交互模式需要同时提供智能体名称和 `--workspace`。 -- `main` 是保留项，不能用作新的智能体 ID。 -- 在交互模式中，凭证种子仅复制可移植的静态配置文件 +- `main` 是保留字，不能用作新的智能体 ID。 +- 在交互模式下，凭证植入只会复制可移植的静态配置文件 （默认是 `api_key` 和静态 `token`）。OAuth 刷新令牌配置文件仍然 - 只能通过从真实 `main` 智能体存储读取继承来使用。 + 只能通过从真实 `main` 智能体存储进行读取继承来使用。 如果配置的默认智能体不是 `main`，请为新智能体单独登录 OAuth 配置文件。 @@ -154,11 +154,12 @@ openclaw agents unbind --agent work --all - `--force` - `--json` -说明： +注意： -- `main` 不能删除。 -- 不带 `--force` 时，需要交互式确认。 -- 工作区、智能体状态和会话记录目录会被移到废纸篓，而不是硬删除。 +- `main` 不能被删除。 +- 如果没有 `--force`，需要交互式确认。 +- 工作区、智能体状态和会话转录目录会被移动到废纸篓，而不是硬删除。 +- 当 Gateway 网关可访问时，删除会通过 Gateway 网关发送，因此配置和会话存储清理会与运行时流量共享同一个写入器。如果无法访问 Gateway 网关，CLI 会回退到离线本地路径。 - 如果另一个智能体的工作区是同一路径、位于此工作区内，或包含此工作区， 该工作区会被保留，并且 `--json` 会报告 `workspaceRetained`、 `workspaceRetainedReason` 和 `workspaceSharedWith`。 @@ -174,7 +175,7 @@ openclaw agents unbind --agent work --all ## 设置身份 -`set-identity` 将字段写入 `agents.list[].identity`： +`set-identity` 会将字段写入 `agents.list[].identity`： - `name` - `theme` @@ -193,11 +194,11 @@ openclaw agents unbind --agent work --all - `--avatar ` - `--json` -说明： +注意： -- 可以使用 `--agent` 或 `--workspace` 选择目标智能体。 +- `--agent` 或 `--workspace` 可用于选择目标智能体。 - 如果你依赖 `--workspace`，且多个智能体共享该工作区，命令会失败并要求你传入 `--agent`。 -- 当没有提供显式身份字段时，命令会从 `IDENTITY.md` 读取身份数据。 +- 如果没有提供显式身份字段，命令会从 `IDENTITY.md` 读取身份数据。 从 `IDENTITY.md` 加载： @@ -231,7 +232,7 @@ openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --ava } ``` -## 相关 +## 相关内容 - [CLI 参考](/zh-CN/cli) - [多智能体路由](/zh-CN/concepts/multi-agent) diff --git a/docs/zh-CN/cli/sessions.md b/docs/zh-CN/cli/sessions.md index 19348aa36..8eb322a3a 100644 --- a/docs/zh-CN/cli/sessions.md +++ b/docs/zh-CN/cli/sessions.md @@ -1,13 +1,13 @@ --- read_when: - 你想列出已存储的会话并查看最近活动 -summary: CLI 参考：`openclaw sessions`（列出已存储的会话 + 用法） +summary: '`openclaw sessions` 的 CLI 参考（列出已存储的会话 + 用法）' title: 会话 x-i18n: - generated_at: "2026-05-02T12:15:16Z" + generated_at: "2026-05-02T12:44:54Z" model: gpt-5.5 provider: openai - source_hash: 8791a36fedc18a1c2d4144c3fd4faeaf8f5320676ceee76026959cbe2dc1873c + source_hash: 5c9ec3ca55f7c5b6217b481e9da62f5416df73e69405a0dc15e77d2afeac723f source_path: cli/sessions.md workflow: 16 --- @@ -16,7 +16,7 @@ x-i18n: 列出已存储的对话会话。 -会话列表不是渠道/提供商存活检查。它们显示来自会话存储的持久化对话行。安静的 Discord、Slack、Telegram 或其他渠道可以成功重新连接，但在处理消息之前不会创建新的会话行。当你需要实时渠道连接性时，请使用 `openclaw channels status --probe`、`openclaw status --deep` 或 `openclaw health --verbose`。 +会话列表不是渠道/提供商的活性检查。它们显示来自会话存储的持久化对话行。安静的 Discord、Slack、Telegram 或其他渠道可以成功重新连接，而不会创建新的会话行，直到处理消息为止。当你需要实时渠道连接性时，请使用 `openclaw channels status --probe`、`openclaw status --deep` 或 `openclaw health --verbose`。 ```bash openclaw sessions @@ -42,9 +42,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12 openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json ``` -这是所有者批准执行请求后，`/export-trajectory` 斜杠命令使用的命令路径。输出目录始终解析到所选工作区下的 `.openclaw/trajectory-exports/` 内。 +这是所有者批准执行请求后 `/export-trajectory` 斜杠命令使用的命令路径。输出目录始终解析到所选工作区下的 `.openclaw/trajectory-exports/` 内。 -`openclaw sessions --all-agents` 读取已配置的智能体存储。Gateway 网关和 ACP 会话发现范围更广：它们还包括在默认 `agents/` 根目录或模板化 `session.store` 根目录下找到的仅磁盘存储。这些发现的存储必须解析为智能体根目录内的常规 `sessions.json` 文件；符号链接和根目录外路径会被跳过。 +`openclaw sessions --all-agents` 会读取已配置的智能体存储。Gateway 网关和 ACP 会话发现范围更广：它们还会包含在默认 `agents/` 根目录或模板化 `session.store` 根目录下找到的仅磁盘存储。这些发现的存储必须解析为智能体根目录内的常规 `sessions.json` 文件；符号链接和根目录外路径会被跳过。 JSON 示例： @@ -82,19 +82,19 @@ openclaw sessions cleanup --json `openclaw sessions cleanup` 使用配置中的 `session.maintenance` 设置： -- 范围说明：`openclaw sessions cleanup` 会维护会话存储、转录和轨迹附属文件。它不会清理 cron 运行日志（`cron/runs/.jsonl`），这些日志由 [Cron 配置](/zh-CN/automation/cron-jobs#configuration)中的 `cron.runLog.maxBytes` 和 `cron.runLog.keepLines` 管理，并在 [Cron 维护](/zh-CN/automation/cron-jobs#maintenance)中说明。 +- 范围说明：`openclaw sessions cleanup` 维护会话存储、转录记录和轨迹附属文件。它不会清理 cron 运行日志（`cron/runs/.jsonl`），这些日志由 [Cron 配置](/zh-CN/automation/cron-jobs#configuration)中的 `cron.runLog.maxBytes` 和 `cron.runLog.keepLines` 管理，并在 [Cron 维护](/zh-CN/automation/cron-jobs#maintenance)中说明。 -- `--dry-run`：预览将会在不写入的情况下剪除/限制多少条目。 - - 在文本模式下，dry-run 会打印每个会话的操作表（`Action`、`Key`、`Age`、`Model`、`Flags`），以便你查看哪些会保留、哪些会移除。 +- `--dry-run`：预览会裁剪/限制多少条目，而不写入。 + - 在文本模式下，dry-run 会打印按会话列出的操作表（`Action`、`Key`、`Age`、`Model`、`Flags`），因此你可以看到哪些会保留、哪些会移除。 - `--enforce`：即使 `session.maintenance.mode` 为 `warn`，也应用维护。 -- `--fix-missing`：移除转录文件缺失的条目，即使它们通常还不会因年龄/数量被剔除。 -- `--active-key `：保护特定活跃键不受磁盘预算驱逐。持久外部对话指针（例如群组会话和线程范围的聊天会话）也会通过年龄/数量/磁盘预算维护保留。 +- `--fix-missing`：移除转录记录文件缺失的条目，即使它们通常还不会因年龄/数量而淘汰。 +- `--active-key `：保护特定活跃键免受磁盘预算驱逐。持久的外部对话指针（例如群组会话和线程范围的聊天会话）也会在年龄/数量/磁盘预算维护中保留。 - `--agent `：为一个已配置的智能体存储运行清理。 - `--all-agents`：为所有已配置的智能体存储运行清理。 -- `--store `：针对特定 `sessions.json` 文件运行。 +- `--store `：针对特定的 `sessions.json` 文件运行。 - `--json`：打印 JSON 摘要。使用 `--all-agents` 时，输出会包含每个存储的一份摘要。 -当 Gateway 网关可达时，对已配置的智能体存储执行清理会通过 Gateway 网关发送，以便它与运行时流量共享同一个会话存储写入器。使用 `--store ` 对存储文件进行显式离线修复。 +当 Gateway 网关可访问时，已配置智能体存储的非 dry-run 清理会通过 Gateway 网关发送，因此它与运行时流量共享同一个会话存储写入器。使用 `--store ` 对存储文件执行显式离线修复。 `openclaw sessions cleanup --all-agents --dry-run --json`： diff --git a/docs/zh-CN/reference/session-management-compaction.md b/docs/zh-CN/reference/session-management-compaction.md index 3b0468fa4..73c3efc14 100644 --- a/docs/zh-CN/reference/session-management-compaction.md +++ b/docs/zh-CN/reference/session-management-compaction.md @@ -1,104 +1,104 @@ --- read_when: - - 你需要调试会话 ID、对话记录 JSONL 或 sessions.json 字段 - - 你正在更改自动压缩行为，或添加“预压缩”清理维护 + - 你需要调试会话 ID、会话记录 JSONL 或 sessions.json 字段 + - 你正在更改自动压缩行为，或添加“预压缩”整理工作 - 你想实现记忆刷新或静默系统轮次 -summary: 深入解析：会话存储 + 转录记录、生命周期和（自动）压缩内部机制 -title: 会话管理深度解析 +summary: 深入解析：会话存储 + 对话记录、生命周期和（自动）压缩内部机制 +title: 会话管理深入解析 x-i18n: - generated_at: "2026-05-02T12:15:26Z" + generated_at: "2026-05-02T12:45:05Z" model: gpt-5.5 provider: openai - source_hash: 6e2097d685381964608096cc0505aeedbd3a8f9bc682168bd519ebe4ffe9218d + source_hash: 8038d42c1112172ebdfefdd7d42d5c729a975095e2d695f5d5122b21a2fa93c1 source_path: reference/session-management-compaction.md workflow: 16 --- -OpenClaw 在以下方面端到端管理会话： +OpenClaw 跨以下领域端到端管理会话： - **会话路由**（入站消息如何映射到 `sessionKey`） - **会话存储**（`sessions.json`）及其跟踪内容 -- **对话记录持久化**（`*.jsonl`）及其结构 -- **对话记录清理**（运行前的提供商特定修正） -- **上下文限制**（上下文窗口与跟踪的 token） +- **会话记录持久化**（`*.jsonl`）及其结构 +- **会话记录清理**（运行前的提供商特定修正） +- **上下文限制**（上下文窗口与已跟踪 token） - **压缩**（手动压缩和自动压缩）以及在何处挂接压缩前工作 - **静默内务处理**（不应产生用户可见输出的记忆写入） -如果你想先阅读更高层次的概览，请从这里开始： +如果你想先了解更高层概览，请从这里开始： - [会话管理](/zh-CN/concepts/session) - [压缩](/zh-CN/concepts/compaction) - [记忆概览](/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 控制 UI、TUI）应向 Gateway 网关查询会话列表和 token 计数。 +- UI（macOS 应用、Web 控制 UI、TUI）应查询 Gateway 网关以获取会话列表和 token 计数。 - 在远程模式下，会话文件位于远程主机上；“检查你的本地 Mac 文件”不会反映 Gateway 网关正在使用的内容。 --- ## 两个持久化层 -OpenClaw 分两层持久化会话： +OpenClaw 在两个层中持久化会话： 1. **会话存储（`sessions.json`）** - - 键值映射：`sessionKey -> SessionEntry` - - 体积小、可变、可安全编辑（或删除条目） + - 键/值映射：`sessionKey -> SessionEntry` + - 小型、可变、可安全编辑（或删除条目） - 跟踪会话元数据（当前会话 ID、最后活动时间、开关、token 计数器等） -2. **对话记录（`.jsonl`）** - - 带树结构的追加式对话记录（条目有 `id` + `parentId`） +2. **会话记录（`.jsonl`）** + - 带树结构的仅追加会话记录（条目包含 `id` + `parentId`） - 存储实际对话 + 工具调用 + 压缩摘要 - - 用于为后续轮次重建模型上下文 - - 一旦活跃对话记录超过检查点大小上限，就会跳过大型压缩前调试检查点，避免生成第二份巨大的 `.checkpoint.*.jsonl` 副本。 + - 用于为未来轮次重建模型上下文 + - 一旦活动会话记录超过检查点大小上限，就会跳过大型压缩前调试检查点，避免再生成一个巨大的 `.checkpoint.*.jsonl` 副本。 -除非界面明确需要任意历史访问，否则 Gateway 网关历史读取器应避免物化整个对话记录。第一页历史、嵌入式聊天历史、重启恢复以及 token/用量检查都使用有界尾部读取。完整对话记录扫描通过异步对话记录索引执行，该索引按文件路径加 `mtimeMs`/`size` 缓存，并在并发读取器之间共享。 +Gateway 网关历史读取器应避免实体化整个会话记录，除非该界面明确需要任意历史访问。第一页历史、嵌入式聊天历史、重启恢复以及 token/用量检查使用有界尾部读取。完整会话记录扫描会经过异步会话记录索引，该索引按文件路径加 `mtimeMs`/`size` 缓存，并在并发读取器之间共享。 --- ## 磁盘位置 -每个智能体在 Gateway 网关主机上： +按智能体划分，位于 Gateway 网关主机上： - 存储：`~/.openclaw/agents//sessions/sessions.json` -- 对话记录：`~/.openclaw/agents//sessions/.jsonl` +- 会话记录：`~/.openclaw/agents//sessions/.jsonl` - Telegram 话题会话：`.../-topic-.jsonl` -OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。 +OpenClaw 通过 `src/config/sessions.ts` 解析这些位置。 --- ## 存储维护和磁盘控制 -会话持久化对 `sessions.json`、对话记录产物和轨迹 sidecar 有自动维护控制（`session.maintenance`）： +会话持久化为 `sessions.json`、会话记录工件和轨迹 sidecar 提供自动维护控制（`session.maintenance`）： - `mode`：`warn`（默认）或 `enforce` - `pruneAfter`：过期条目年龄截止值（默认 `30d`） - `maxEntries`：`sessions.json` 中的条目上限（默认 `500`） -- `resetArchiveRetention`：`*.reset.` 对话记录归档的保留时间（默认：与 `pruneAfter` 相同；`false` 禁用清理） +- `resetArchiveRetention`：`*.reset.` 会话记录归档的保留期（默认：与 `pruneAfter` 相同；`false` 禁用清理） - `maxDiskBytes`：可选的会话目录预算 -- `highWaterBytes`：清理后的可选目标值（默认为 `maxDiskBytes` 的 `80%`） +- `highWaterBytes`：清理后的可选目标（默认是 `maxDiskBytes` 的 `80%`） -正常的 Gateway 网关写入会经过每个存储专用的会话写入器，它会序列化进程内变更，而不获取运行时文件锁。热路径补丁辅助函数在持有该写入器槽位期间借用经过验证的可变缓存，因此大型 `sessions.json` 文件不会为每次元数据更新都被克隆或重新读取。运行时代码应优先使用 `updateSessionStore(...)` 或 `updateSessionStoreEntry(...)`；直接保存整个存储是兼容性和离线维护工具。当 Gateway 网关可达时，`openclaw sessions cleanup --enforce` 会将维护委派给 Gateway 网关，使清理加入同一个写入器队列；`--store ` 是用于直接文件维护的显式离线修复路径。对于生产级上限，`maxEntries` 清理仍会批处理，因此存储可能会短暂超过配置的上限，直到下一次高水位清理将其重写回上限以下。会话存储读取不会在 Gateway 网关启动期间修剪或限制条目；请使用写入或 `openclaw sessions cleanup --enforce` 进行清理。`openclaw sessions cleanup --enforce` 仍会立即应用配置的上限。 +普通 Gateway 网关写入会通过每个存储的会话写入器流转，该写入器会在进程内串行化变更，而不获取运行时文件锁。热路径补丁助手会在持有该写入器槽位时借用已验证的可变缓存，因此大型 `sessions.json` 文件不会为每次元数据更新而被克隆或重新读取。运行时代码应优先使用 `updateSessionStore(...)` 或 `updateSessionStoreEntry(...)`；直接保存整个存储属于兼容性和离线维护工具。当 Gateway 网关可达时，非试运行的 `openclaw sessions cleanup` 和 `openclaw agents delete` 会将存储变更委托给 Gateway 网关，因此清理会加入同一写入器队列；`--store ` 是用于直接文件维护的显式离线修复路径。对于生产规模的上限，`maxEntries` 清理仍会分批执行，因此存储可能会短暂超过配置的上限，然后在下一次高水位清理时被重写回上限以下。会话存储读取不会在 Gateway 网关启动期间修剪或限制条目；请使用写入或 `openclaw sessions cleanup --enforce` 进行清理。`openclaw sessions cleanup --enforce` 仍会立即应用配置的上限。 -维护会保留持久的外部对话指针，例如群组会话和线程范围的聊天会话，但 cron、钩子、heartbeat、ACP 和子智能体的合成运行时条目在超过配置的年龄、数量或磁盘预算时仍可能被删除。 +维护会保留耐久的外部对话指针，例如群组会话和线程范围聊天会话，但 cron、钩子、Heartbeat、ACP 和子智能体的合成运行时条目在超过配置的年龄、数量或磁盘预算时仍可能被移除。 -OpenClaw 不再在 Gateway 网关写入期间创建自动 `sessions.json.bak.*` 轮转备份。旧版 `session.maintenance.rotateBytes` 键会被忽略，`openclaw doctor --fix` 会从旧配置中移除它。 +OpenClaw 在 Gateway 网关写入期间不再创建自动 `sessions.json.bak.*` 轮转备份。旧版 `session.maintenance.rotateBytes` 键会被忽略，`openclaw doctor --fix` 会将其从旧配置中移除。 -磁盘预算清理的强制执行顺序（`mode: "enforce"`）： +磁盘预算清理的执行顺序（`mode: "enforce"`）： -1. 先移除最旧的已归档、孤立对话记录或孤立轨迹产物。 -2. 如果仍高于目标值，则驱逐最旧的会话条目及其对话记录/轨迹文件。 -3. 持续执行，直到用量小于或等于 `highWaterBytes`。 +1. 先移除最旧的归档工件、孤立会话记录工件或孤立轨迹工件。 +2. 如果仍高于目标，则逐出最旧的会话条目及其会话记录/轨迹文件。 +3. 持续执行，直到用量等于或低于 `highWaterBytes`。 -在 `mode: "warn"` 中，OpenClaw 会报告潜在驱逐项，但不会变更存储/文件。 +在 `mode: "warn"` 中，OpenClaw 会报告可能的逐出，但不会变更存储/文件。 按需运行维护： @@ -111,22 +111,22 @@ openclaw sessions cleanup --enforce ## Cron 会话和运行日志 -隔离的 cron 运行也会创建会话条目/对话记录，并且它们有专用的保留控制： +隔离的 cron 运行也会创建会话条目/会话记录，并且它们有专用的保留控制： -- `cron.sessionRetention`（默认 `24h`）会从会话存储中修剪旧的隔离 cron 运行会话（`false` 禁用）。 -- `cron.runLog.maxBytes` + `cron.runLog.keepLines` 会修剪 `~/.openclaw/cron/runs/.jsonl` 文件（默认值：`2_000_000` 字节和 `2000` 行）。 +- `cron.sessionRetention`（默认 `24h`）会从会话存储中修剪旧的隔离 cron 运行会话（`false` 会禁用）。 +- `cron.runLog.maxBytes` + `cron.runLog.keepLines` 会修剪 `~/.openclaw/cron/runs/.jsonl` 文件（默认：`2_000_000` 字节和 `2000` 行）。 -当 cron 强制创建新的隔离运行会话时，它会在写入新行前清理先前的 `cron:` 会话条目。它会携带安全偏好，例如思考/快速/详细设置、标签，以及用户明确选择的模型/凭证覆盖。它会丢弃环境对话上下文，例如渠道/群组路由、发送或队列策略、提权、来源和 ACP 运行时绑定，因此新的隔离运行无法从较早的运行继承过期的投递或运行时权限。 +当 cron 强制创建新的隔离运行会话时，它会先清理之前的 `cron:` 会话条目，然后再写入新行。它会携带安全偏好，例如思考/快速/详细设置、标签，以及用户显式选择的模型/身份验证覆盖。它会丢弃环境对话上下文，例如渠道/群组路由、发送或队列策略、提权、来源和 ACP 运行时绑定，因此新的隔离运行无法从较旧运行继承过期的投递或运行时权限。 --- ## 会话键（`sessionKey`） -`sessionKey` 标识你位于_哪个对话桶_中（路由 + 隔离）。 +`sessionKey` 标识你所在的_对话桶_（路由 + 隔离）。 常见模式： -- 主/直接聊天（每个智能体）：`agent::`（默认 `main`） +- 主/直接聊天（按智能体）：`agent::`（默认 `main`） - 群组：`agent:::group:` - 房间/渠道（Discord/Slack）：`agent:::channel:` 或 `...:room:` - Cron：`cron:` @@ -138,105 +138,106 @@ openclaw sessions cleanup --enforce ## 会话 ID（`sessionId`） -每个 `sessionKey` 指向一个当前 `sessionId`（继续该对话的对话记录文件）。 +每个 `sessionKey` 指向一个当前 `sessionId`（继续对话的会话记录文件）。 经验规则： -- **重置**（`/new`、`/reset`）会为该 `sessionKey` 创建新的 `sessionId`。 -- **每日重置**（默认在 Gateway 网关主机本地时间上午 4:00）会在越过重置边界后的下一条消息创建新的 `sessionId`。 -- **空闲过期**（`session.reset.idleMinutes` 或旧版 `session.idleMinutes`）会在空闲窗口后有消息到达时创建新的 `sessionId`。当每日重置和空闲重置都配置时，先过期者生效。 -- **系统事件**（heartbeat、cron 唤醒、exec 通知、Gateway 网关簿记）可能会变更会话行，但不会延长每日/空闲重置的新鲜度。重置滚动会在构建新提示前丢弃上一会话的队列系统事件通知。 -- **父级 fork 策略**在创建线程或子智能体 fork 时使用 Pi 的活跃分支。如果该分支过大，OpenClaw 会使用隔离上下文启动子级，而不是失败或继承不可用的历史。大小策略是自动的；旧版 `session.parentForkMaxTokens` 配置会被 `openclaw doctor --fix` 移除。 +- **重置**（`/new`、`/reset`）会为该 `sessionKey` 创建一个新的 `sessionId`。 +- **每日重置**（默认是 Gateway 网关主机本地时间凌晨 4:00）会在重置边界后的下一条消息上创建新的 `sessionId`。 +- **空闲过期**（`session.reset.idleMinutes` 或旧版 `session.idleMinutes`）会在空闲窗口之后收到消息时创建新的 `sessionId`。当每日重置和空闲过期都已配置时，先到期者生效。 +- **系统事件**（Heartbeat、cron 唤醒、exec 通知、Gateway 网关账务记录）可能会变更会话行，但不会延长每日/空闲重置的新鲜度。重置滚动会在构建新提示前丢弃上一会话中排队的系统事件通知。 +- **父级分叉策略**在创建线程或子智能体分叉时使用 PI 的活动分支。如果该分支过大，OpenClaw 会以隔离上下文启动子级，而不是失败或继承无法使用的历史。大小策略是自动的；旧版 `session.parentForkMaxTokens` 配置会由 `openclaw doctor --fix` 移除。 实现细节：该决策发生在 `src/auto-reply/reply/session.ts` 中的 `initSessionState()`。 --- -## 会话存储 schema（`sessions.json`） +## 会话存储架构（`sessions.json`） 存储的值类型是 `src/config/sessions.ts` 中的 `SessionEntry`。 -关键字段（并非完整列表）： +关键字段（不完整）： -- `sessionId`：当前对话记录 ID（除非设置了 `sessionFile`，否则文件名从它派生） +- `sessionId`：当前会话记录 ID（除非设置了 `sessionFile`，否则文件名由此派生） - `sessionStartedAt`：当前 `sessionId` 的开始时间戳；每日重置新鲜度使用它。旧版行可能会从 JSONL 会话头派生它。 -- `lastInteractionAt`：最后一次真实用户/渠道交互时间戳；空闲重置新鲜度使用它，因此 heartbeat、cron 和 exec 事件不会让会话保持存活。没有此字段的旧版行会回退到恢复出的会话开始时间来判断空闲新鲜度。 -- `updatedAt`：最后一次存储行变更时间戳，用于列表、修剪和簿记。它不是每日/空闲重置新鲜度的权威来源。 -- `sessionFile`：可选的显式对话记录路径覆盖 +- `lastInteractionAt`：最后一次真实用户/渠道交互时间戳；空闲重置新鲜度使用它，因此 Heartbeat、cron 和 exec 事件不会让会话保持活跃。没有此字段的旧版行会回退到已恢复的会话开始时间，用于空闲新鲜度。 +- `updatedAt`：最后一次存储行变更时间戳，用于列表、修剪和账务记录。它不是每日/空闲重置新鲜度的权威依据。 +- `sessionFile`：可选的显式会话记录路径覆盖 - `chatType`：`direct | group | room`（帮助 UI 和发送策略） - `provider`、`subject`、`room`、`space`、`displayName`：用于群组/渠道标签的元数据 - 开关： - `thinkingLevel`、`verboseLevel`、`reasoningLevel`、`elevatedLevel` - - `sendPolicy`（每个会话的覆盖） + - `sendPolicy`（每会话覆盖） - 模型选择： - `providerOverride`、`modelOverride`、`authProfileOverride` - Token 计数器（尽力而为 / 依赖提供商）： - `inputTokens`、`outputTokens`、`totalTokens`、`contextTokens` -- `compactionCount`：该会话键完成自动压缩的次数 -- `memoryFlushAt`：上一次压缩前记忆刷新时间戳 -- `memoryFlushCompactionCount`：上次刷新运行时的压缩计数 +- `compactionCount`：此会话键完成自动压缩的次数 +- `memoryFlushAt`：上一次压缩前记忆刷新的时间戳 +- `memoryFlushCompactionCount`：上一次刷新运行时的压缩计数 -该存储可以安全编辑，但 Gateway 网关是权威来源：会话运行时，它可能会重写或重新水合条目。 +该存储可安全编辑，但 Gateway 网关是权威：随着会话运行，它可能会重写或重新补水条目。 --- -## 对话记录结构（`*.jsonl`） +## 会话记录结构（`*.jsonl`） -对话记录由 `@mariozechner/pi-coding-agent` 的 `SessionManager` 管理。 +会话记录由 `@mariozechner/pi-coding-agent` 的 `SessionManager` 管理。 -该文件是 JSONL： +文件是 JSONL： - 第一行：会话头（`type: "session"`，包含 `id`、`cwd`、`timestamp`，可选 `parentSession`） -- 随后：带 `id` + `parentId` 的会话条目（树） +- 之后：包含 `id` + `parentId` 的会话条目（树） 值得注意的条目类型： -- `message`：用户/assistant/toolResult 消息 -- `custom_message`：插件注入的、_会_进入模型上下文的消息（可以从 UI 隐藏） -- `custom`：_不会_进入模型上下文的插件状态 -- `compaction`：持久化的压缩摘要，带有 `firstKeptEntryId` 和 `tokensBefore` +- `message`：用户/助手/`toolResult` 消息 +- `custom_message`：扩展注入的消息，_会_进入模型上下文（可从 UI 隐藏） +- `custom`：_不会_进入模型上下文的扩展状态 +- `compaction`：持久化的压缩摘要，包含 `firstKeptEntryId` 和 `tokensBefore` - `branch_summary`：导航树分支时持久化的摘要 -OpenClaw 有意**不会**“修正”对话记录；Gateway 网关使用 `SessionManager` 读写它们。 +OpenClaw 有意**不会**“修正”会话记录；Gateway 网关使用 `SessionManager` 读写它们。 --- -## 上下文窗口与跟踪的 token +## 上下文窗口与已跟踪 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 将较长的对话记录拆分为压缩分块时，它会让 assistant 工具调用与其对应的 `toolResult` 条目保持配对。 +当 OpenClaw 将长会话记录拆分为压缩块时，它会保持助手工具调用与其匹配的 `toolResult` 条目成对。 -- 如果 token 份额切分点落在工具调用和其结果之间，OpenClaw - 会把边界移动到助手工具调用消息处，而不是拆开这一对消息。 -- 如果尾部工具结果块本会让分块超过目标大小，OpenClaw - 会保留该待处理工具块，并保持未总结的尾部完整。 -- 已中止/错误的工具调用块不会保持待处理切分处于开启状态。 +- 如果 token 份额切分边界落在一次工具调用及其结果之间，OpenClaw + 会把边界移到助手工具调用消息处，而不是拆开这一对消息。 +- 如果尾随的工具结果块原本会让分块超过目标大小，OpenClaw + 会保留该未决工具块，并保持未摘要化尾部 + 完整。 +- 已中止/错误的工具调用块不会维持未决切分。 --- @@ -258,14 +259,27 @@ exceeded`，以及类似的提供商形态变体) → 压缩 → 重试。 - `contextWindow` 是模型的上下文窗口 - `reserveTokens` 是为提示词 + 下一次模型输出预留的余量 -这些是 Pi 运行时语义（OpenClaw 消费这些事件，但由 Pi 决定何时压缩）。 +这些是 Pi 运行时语义（OpenClaw 会消费事件，但由 Pi 决定何时压缩）。 -当设置了 `agents.defaults.compaction.maxActiveTranscriptBytes` 且活跃转录文件达到该大小时，OpenClaw 也可以在打开下一次运行前触发一次预检本地压缩。这是用于降低本地重新打开成本的文件大小保护，不是原始归档：OpenClaw 仍会运行正常的语义压缩，并且它要求启用 `truncateAfterCompaction`，这样压缩后的摘要才能成为新的后继转录。 +当设置了 `agents.defaults.compaction.maxActiveTranscriptBytes` 且活动转录文件达到该大小时，OpenClaw 也可以在打开下一次 +运行前触发一次预检本地压缩。这是用于降低本地 +重新打开成本的文件大小防护，而不是原始归档：OpenClaw 仍会运行正常的语义压缩， +并且需要 `truncateAfterCompaction`，这样压缩后的摘要才能成为 +新的后继转录。 对于嵌入式 Pi 运行，`agents.defaults.compaction.midTurnPrecheck.enabled: true` -会添加一个可选择启用的工具循环保护。在追加工具结果之后、下一次模型调用之前，OpenClaw 会使用与回合开始时相同的预检预算逻辑估算提示词压力。如果上下文已不再适配，该保护不会在 Pi 的 `transformContext` 钩子内压缩。它会抛出结构化的回合中预检信号，停止当前提示词提交，并让外层运行循环使用现有恢复路径：在足够时截断过大的工具结果，或触发已配置的压缩模式并重试。该选项默认禁用，并且适用于 `default` 和 `safeguard` -两种压缩模式，包括由提供商支持的 safeguard 压缩。 -这与 `maxActiveTranscriptBytes` 相互独立：字节大小保护在打开回合之前运行，而回合中预检会在嵌入式 Pi 工具循环中、追加新工具结果之后稍后运行。 +会添加一个可选启用的工具循环防护。在追加工具结果之后、下一次 +模型调用之前，OpenClaw 会使用与回合开始时相同的预检 +预算逻辑来估算提示词压力。如果上下文已无法容纳，该防护 +不会在 Pi 的 `transformContext` 钩子内压缩。它会发出结构化的 +回合中预检信号，停止当前提示词提交，并让 +外层运行循环使用现有恢复路径：当截断超大工具结果已足够时就截断， +否则触发已配置的压缩模式并重试。该 +选项默认禁用，并且同时适用于 `default` 和 `safeguard` +压缩模式，包括由提供商支持的 safeguard 压缩。 +这独立于 `maxActiveTranscriptBytes`：字节大小防护会在 +回合打开前运行，而回合中预检则稍后在嵌入式 Pi 工具 +循环中、追加新工具结果后运行。 --- @@ -283,17 +297,30 @@ 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.midTurnPrecheck.enabled: true`，可在新工具结果之后、下一次模型调用之前运行可选工具循环预检。这只是触发器；摘要生成仍使用已配置的压缩路径。它独立于 `maxActiveTranscriptBytes`，后者是回合开始时的活跃转录字节大小保护。 -- 将 `agents.defaults.compaction.maxActiveTranscriptBytes` 设置为字节值或类似 `"20mb"` 的字符串，可在活跃转录变大时于回合前运行本地压缩。仅当同时启用 `truncateAfterCompaction` 时，此保护才会生效。保持未设置或设为 `0` 可禁用。 -- 启用 `agents.defaults.compaction.truncateAfterCompaction` 后，OpenClaw 会在压缩后将活跃转录轮转为压缩后的后继 JSONL。旧的完整转录会保留为归档，并从压缩检查点链接，而不是就地重写。 + 并保留 Pi 的最近尾部切分点。没有显式保留预算时， + 手动压缩仍是硬检查点，重建后的上下文会从 + 新摘要开始。 +- 设置 `agents.defaults.compaction.midTurnPrecheck.enabled: true` 可在新 + 工具结果之后、下一次模型 + 调用之前运行可选的工具循环预检。这只是触发器；摘要生成仍使用已配置的 + 压缩路径。它独立于 `maxActiveTranscriptBytes`，后者是一个 + 回合开始时的活动转录字节大小防护。 +- 将 `agents.defaults.compaction.maxActiveTranscriptBytes` 设置为字节值或 + `"20mb"` 这样的字符串，可在活动 + 转录变大时于回合前运行本地压缩。只有在同时启用 + `truncateAfterCompaction` 时，该防护才会生效。留空或设置为 `0` 可 + 禁用。 +- 启用 `agents.defaults.compaction.truncateAfterCompaction` 后， + OpenClaw 会在压缩后将活动转录轮换为一个压缩后的后继 JSONL。 + 旧的完整转录会保持归档，并从 + 压缩检查点链接，而不是就地重写。 原因：在压缩变得不可避免之前，为多轮“内务处理”（例如记忆写入）留下足够余量。 @@ -304,16 +331,17 @@ OpenClaw 还会对嵌入式运行强制执行安全下限： ## 可插拔压缩提供商 -插件可以通过插件 API 上的 `registerCompactionProvider()` 注册压缩提供商。当 `agents.defaults.compaction.provider` 设置为已注册的提供商 id 时，safeguard 插件会把摘要生成委托给该提供商，而不是使用内置的 `summarizeInStages` 流水线。 +插件可以通过插件 API 上的 `registerCompactionProvider()` 注册压缩提供商。当 `agents.defaults.compaction.provider` 设置为已注册的提供商 id 时，safeguard 插件会将摘要委托给该提供商，而不是使用内置的 `summarizeInStages` 流水线。 -- `provider`：已注册压缩提供商插件的 id。不设置则使用默认 LLM 摘要生成。 -- 设置 `provider` 会强制 `mode: "safeguard"`。 -- 提供商接收与内置路径相同的压缩指令和标识符保留策略。 -- safeguard 在提供商输出之后仍会保留近期回合和切分回合的后缀上下文。 -- 内置 safeguard 摘要生成会用新消息重新提炼先前摘要，而不是逐字保留完整的先前摘要。 +- `provider`：已注册压缩提供商插件的 id。留空则使用默认 LLM 摘要。 +- 设置 `provider` 会强制使用 `mode: "safeguard"`。 +- 提供商会收到与内置路径相同的压缩指令和标识符保留策略。 +- safeguard 仍会在提供商输出之后保留最近回合和切分回合的后缀上下文。 +- 内置 safeguard 摘要会用新消息重新提炼先前摘要， + 而不是逐字保留完整的旧摘要。 - safeguard 模式默认启用摘要质量审计；设置 - `qualityGuard.enabled: false` 可跳过格式错误输出时重试的行为。 -- 如果提供商失败或返回空结果，OpenClaw 会自动回退到内置 LLM 摘要生成。 + `qualityGuard.enabled: false` 可跳过格式异常输出时重试的行为。 +- 如果提供商失败或返回空结果，OpenClaw 会自动回退到内置 LLM 摘要。 - 中止/超时信号会被重新抛出（不会被吞掉），以尊重调用方取消。 来源：`src/plugins/compaction-provider.ts`、`src/agents/pi-hooks/compaction-safeguard.ts`。 @@ -324,10 +352,10 @@ OpenClaw 还会对嵌入式运行强制执行安全下限： 你可以通过以下方式观察压缩和会话状态： -- `/status`（在任何聊天会话中） +- `/status`（在任意聊天会话中） - `openclaw status`（CLI） - `openclaw sessions` / `sessions --json` -- 详细模式：`🧹 Auto-compaction complete` + 压缩计数 +- 详细模式：`🧹 Auto-compaction complete` + 压缩次数 --- @@ -337,60 +365,71 @@ OpenClaw 支持用于后台任务的“静默”回合，此时用户不应看 约定： -- 助手以精确静默 token `NO_REPLY` / - `no_reply` 开始输出，表示“不要向用户投递回复”。 +- 助手以精确的静默 token `NO_REPLY` / + `no_reply` 开始输出，以表示“不要向用户发送回复”。 - OpenClaw 会在投递层剥离/抑制它。 - 精确静默 token 抑制不区分大小写，因此当整个载荷只是静默 token 时，`NO_REPLY` 和 - `no_reply` 都算数。 -- 这仅用于真正的后台/不投递回合；它不是普通可操作用户请求的快捷方式。 + `no_reply` 都会生效。 +- 这只用于真正的后台/不投递回合；它不是处理 + 普通可操作用户请求的快捷方式。 -自 `2026.1.10` 起，当部分分块以 `NO_REPLY` 开头时，OpenClaw 还会抑制**草稿/正在输入流式传输**，因此静默操作不会在回合中泄漏部分输出。 +自 `2026.1.10` 起，当 +局部分块以 `NO_REPLY` 开头时，OpenClaw 还会抑制**草稿/输入状态流式传输**，因此静默操作不会在回合中途泄漏局部 +输出。 --- -## 压缩前“记忆刷写”（已实现） +## 预压缩“记忆刷新”（已实现） -目标：在自动压缩发生之前，运行一个静默的智能体回合，把持久状态写入磁盘（例如 Agent 工作区中的 `memory/YYYY-MM-DD.md`），这样压缩就无法抹除关键上下文。 +目标：在自动压缩发生前，运行一个静默的智能体回合，将持久 +状态写入磁盘（例如智能体工作区中的 `memory/YYYY-MM-DD.md`），这样压缩就不能 +抹掉关键上下文。 -OpenClaw 使用**预阈值刷写**方式： +OpenClaw 使用**预阈值刷新**方案： 1. 监控会话上下文用量。 -2. 当它越过“软阈值”（低于 Pi 的压缩阈值）时，对智能体运行一条静默的“立即写入记忆”指令。 -3. 使用精确静默 token `NO_REPLY` / `no_reply`，让用户看不到任何内容。 +2. 当它跨过“软阈值”（低于 Pi 的压缩阈值）时，向智能体运行一条静默的 + “立即写入记忆”指令。 +3. 使用精确静默 token `NO_REPLY` / `no_reply`，让用户 + 看不到任何内容。 配置（`agents.defaults.compaction.memoryFlush`）： - `enabled`（默认：`true`） -- `model`（用于刷写回合的可选精确提供商/模型覆盖，例如 `ollama/qwen3:8b`） +- `model`（可选的精确提供商/模型覆盖项，用于刷新回合，例如 `ollama/qwen3:8b`） - `softThresholdTokens`（默认：`4000`） -- `prompt`（刷写回合的用户消息） -- `systemPrompt`（为刷写回合追加的额外系统提示词） +- `prompt`（用于刷新回合的用户消息） +- `systemPrompt`（为刷新回合追加的额外系统提示词） 说明： -- 默认提示词/系统提示词包含 `NO_REPLY` 提示，以抑制投递。 -- 设置 `model` 后，刷写回合会使用该模型，而不继承活跃会话的回退链，因此仅本地的内务处理不会静默回退到付费对话模型。 -- 每个压缩周期只运行一次刷写（在 `sessions.json` 中跟踪）。 -- 刷写仅针对嵌入式 Pi 会话运行（CLI 后端会跳过）。 -- 当会话工作区为只读（`workspaceAccess: "ro"` 或 `"none"`）时，会跳过刷写。 -- 请参阅[记忆](/zh-CN/concepts/memory)，了解工作区文件布局和写入模式。 +- 默认提示词/系统提示词包含 `NO_REPLY` 提示以抑制 + 投递。 +- 设置 `model` 后，刷新回合会使用该模型，而不会继承 + 活动会话的回退链，因此仅本地内务处理不会静默 + 回退到付费对话模型。 +- 每个压缩周期刷新一次（在 `sessions.json` 中跟踪）。 +- 只有嵌入式 Pi 会话会运行刷新（CLI 后端会跳过）。 +- 当会话工作区为只读（`workspaceAccess: "ro"` 或 `"none"`）时会跳过刷新。 +- 请参阅 [记忆](/zh-CN/concepts/memory)，了解工作区文件布局和写入模式。 -Pi 还在插件 API 中暴露了 `session_before_compact` 钩子，但 OpenClaw 的刷写逻辑目前位于 Gateway 网关侧。 +Pi 还在插件 API 中暴露了 `session_before_compact` 钩子，但 OpenClaw 的 +刷新逻辑目前位于 Gateway 网关侧。 --- -## 故障排除清单 +## 故障排除检查清单 - 会话键错误？从 [/concepts/session](/zh-CN/concepts/session) 开始，并确认 `/status` 中的 `sessionKey`。 -- 存储与转录不匹配？通过 `openclaw status` 确认 Gateway 网关主机和存储路径。 +- 存储与转录不匹配？从 `openclaw status` 确认 Gateway 网关主机和存储路径。 - 压缩刷屏？检查： - - 模型上下文窗口（太小） + - 模型上下文窗口（过小） - 压缩设置（`reserveTokens` 对于模型窗口过高可能导致更早压缩） - - 工具结果膨胀：启用/调整会话修剪 + - 工具结果膨胀：启用/调优会话剪枝 - 静默回合泄漏？确认回复以 `NO_REPLY` 开头（不区分大小写的精确 token），并且你使用的构建包含流式传输抑制修复。 ## 相关内容 - [会话管理](/zh-CN/concepts/session) -- [会话修剪](/zh-CN/concepts/session-pruning) +- [会话剪枝](/zh-CN/concepts/session-pruning) - [上下文引擎](/zh-CN/concepts/context-engine)