openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-25 01:34:47 +00:00
parent c9bd15c7f9
commit 2df8214e9a
1 changed files with 104 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

206
docs/zh-CN/concepts/context-engine.md
View File

@ -6,29 +6,29 @@ read_when:
summary: 上下文引擎：可插拔的上下文组装、压缩和子智能体生命周期
title: 上下文引擎
x-i18n:
generated_at: "2026-04-24T04:20:42Z"
generated_at: "2026-04-25T01:34:00Z"
model: gpt-5.4
provider: openai
source_hash: 8f4e5f01f945f7fe3056587f2aa60bec607dd0dd64b29e9ab2afe8e77b5d2f1e
source_hash: 1dc4a6f0a9fb669893a6a877924562d05168fde79b3c41df335d697e651d534d
source_path: concepts/context-engine.md
workflow: 15
---
**上下文引擎**控制 OpenClaw 如何为每次运行构建模型上下文：
**上下文引擎** 控制 OpenClaw 如何为每次运行构建模型上下文：
包含哪些消息、如何总结较早的历史记录，以及如何跨子智能体边界管理
上下文。
OpenClaw 内置了 `legacy` 引擎，并默认使用它——大多数
用户都不需要更改。只有当你想要不同的组装、压缩或跨会话召回行为时，
OpenClaw 内置了一个 `legacy` 引擎，并默认使用它——大多数
用户都不需要更改这一点。只有当你希望获得不同的组装、压缩或跨会话召回行为时，
才需要安装并选择插件引擎。
## 快速开始
检查当前激活的是哪个引擎：
检查当前启用了哪个引擎：
```bash
openclaw doctor
# 或直接检查配置：
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'
```
@ -38,72 +38,72 @@ cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'
然后在插槽中选择该引擎：
```bash
# 从 npm 安装
# Install from npm
openclaw plugins install @martian-engineering/lossless-claw
# 或从本地路径安装（用于开发）
# Or install from a local path (for development)
openclaw plugins install -l ./my-context-engine
```
然后在你的配置中启用该插件，并将其选为当前激活的引擎：
然后在你的配置中启用该插件，并将其选为活动引擎：
```json5
// openclaw.json
{
plugins: {
slots: {
contextEngine: "lossless-claw", // 必须与插件注册的引擎 id 匹配
contextEngine: "lossless-claw", // must match the plugin's registered engine id
},
entries: {
"lossless-claw": {
enabled: true,
// 插件特定配置写在这里（参见该插件的文档）
// Plugin-specific config goes here (see the plugin's docs)
},
},
},
}
```
安装并配置后，重启 Gateway 网关。
安装并配置完成后，重启 Gateway 网关。
若要切换回内置引擎，将 `contextEngine` 设为 `"legacy"`（或者
要切换回内置引擎，将 `contextEngine` 设为 `"legacy"`（或者
直接删除该键——`"legacy"` 是默认值）。
## 工作原理
每次 OpenClaw 运行模型提示词时，上下文引擎都会参与
四个生命周期阶段：
每次 OpenClaw 运行模型提示时，上下文引擎都会参与
四个生命周期节点：
1. **摄取**——当新消息被添加到会话时调用。引擎
可以将该消息存储或索引到它自己的数据存储中。
2. **组装**——在每次模型运行前调用。引擎返回一组按顺序排列的
1. **摄取** — 当新消息被添加到会话时调用。该引擎
可以将消息存储或索引到它自己的数据存储中。
2. **组装** — 在每次模型运行前调用。该引擎返回一组有序的
消息（以及可选的 `systemPromptAddition`），这些内容会适配
token 预算。
3. **压缩**——当上下文窗口已满，或当用户运行
`/compact` 时调用。引擎会总结较早的历史记录以释放空间。
4. **轮次结束后**——在一次运行完成后调用。引擎可以持久化状态、
3. **压缩** — 当上下文窗口已满，或当用户运行
`/compact` 时调用。该引擎会总结较早的历史记录以释放空间。
4. **轮次结束后** — 在一次运行完成后调用。该引擎可以持久化状态、
触发后台压缩，或更新索引。
对于内置的非 ACP Codex harness，OpenClaw 通过将已组装的上下文投射到
Codex 开发者指令和当前轮次提示词中，应用相同的生命周期。Codex 仍然保留
其原生线程历史记录和原生压缩器。
对于内置的非 ACP Codex Harness，OpenClaw 会通过将组装后的上下文
映射到 Codex 开发者指令和当前轮次提示中，应用相同的生命周期。
Codex 仍然管理它自己的原生线程历史记录和原生压缩器。
### 子智能体生命周期（可选）
OpenClaw 会调用两个可选的子智能体生命周期钩子：
- **prepareSubagentSpawn**——在子运行开始前准备共享上下文状态。
该钩子接收父/子会话键、`contextMode`
- **prepareSubagentSpawn** — 在子运行
开始前准备共享上下文状态。该钩子接收父/子会话键、`contextMode`
（`isolated` 或 `fork`）、可用的转录 id/文件，以及可选的 TTL。
如果它返回一个回滚句柄，那么当准备成功后生成失败时，
如果它返回一个回滚句柄，那么当启动在准备成功后失败时，
OpenClaw 会调用它。
- **onSubagentEnded**——在子智能体会话完成或被清理时执行清理。
- **onSubagentEnded** — 当子智能体会话完成或被清理时执行清理。
### 系统提示词追加内容
### 系统提示补充
`assemble` 方法可以返回一个 `systemPromptAddition` 字符串。OpenClaw
会将其预置到本次运行的系统提示词前面。这让引擎能够注入
动态召回指引、检索指令或上下文感知提示，
会将其前置到该次运行的系统提示中。这让引擎能够注入
动态召回指导、检索指令或上下文感知提示，
而无需依赖静态工作区文件。
## legacy 引擎
@ -111,15 +111,15 @@ OpenClaw 会调用两个可选的子智能体生命周期钩子：
内置的 `legacy` 引擎保留了 OpenClaw 的原始行为：
- **摄取**：无操作（会话管理器会直接处理消息持久化）。
- **组装**：直通（运行时中的现有 sanitize → validate → limit 流水线
负责处理上下文组装）。
- **压缩**：委托给内置的总结式压缩，它会对较早的消息生成
单一摘要，并保留最近的消息不变。
- **组装**：透传（运行时中现有的 sanitize → validate → limit 流水线
会处理上下文组装）。
- **压缩**：委托给内置的总结式压缩，它会创建
一个较早消息的单一摘要，并保持最近消息不变。
- **轮次结束后**：无操作。
legacy 引擎不会注册工具，也不会提供 `systemPromptAddition`。
当未设置 `plugins.slots.contextEngine`（或者它被设为 `"legacy"`）时，
当未设置 `plugins.slots.contextEngine`（或它被设为 `"legacy"`）时，
会自动使用该引擎。
## 插件引擎
@ -138,12 +138,12 @@ export default function register(api) {
},
async ingest({ sessionId, message, isHeartbeat }) {
// 将消息存储到你的数据存储中
// Store the message in your data store
return { ingested: true };
},
async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {
// 返回适配预算的消息
// Return messages that fit the budget
return {
messages: buildContext(messages, tokenBudget),
estimatedTokens: countTokens(messages),
@ -155,7 +155,7 @@ export default function register(api) {
},
async compact({ sessionId, force }) {
// 总结较早的上下文
// Summarize older context
return { ok: true, compacted: true };
},
}));
@ -183,58 +183,60 @@ export default function register(api) {
必需成员：
| 成员 | 类型 | 用途 |
| ------------------ | -------- | ---- |
| `info` | 属性 | 引擎 id、名称、版本，以及它是否负责压缩 |
| `ingest(params)` | 方法 | 存储单条消息 |
| `assemble(params)` | 方法 | 为一次模型运行构建上下文（返回 `AssembleResult`） |
| `compact(params)` | 方法 | 总结/缩减上下文 |
| 成员 | 类型 | 用途 |
| ------------------ | -------- | -------------------------------------------------------- |
| `info` | 属性 | 引擎 id、名称、版本，以及它是否拥有压缩控制权 |
| `ingest(params)` | 方法 | 存储单条消息 |
| `assemble(params)` | 方法 | 为一次模型运行构建上下文（返回 `AssembleResult`） |
| `compact(params)` | 方法 | 总结/缩减上下文 |
`assemble` 返回一个 `AssembleResult`，包含：
`assemble` 返回一个 `AssembleResult`，其中包含：
- `messages`——发送给模型的有序消息。
- `estimatedTokens`（必需，`number`）——引擎对
已组装上下文总 token 数的估算。OpenClaw 会将其用于压缩阈值
- `messages` — 要发送给模型的有序消息。
- `estimatedTokens`（必需，`number`）— 引擎对
已组装上下文中总 token 数的估算。OpenClaw 会将其用于压缩阈值
决策和诊断报告。
- `systemPromptAddition`（可选，`string`）——预置到系统提示词前面的内容。
- `systemPromptAddition`（可选，`string`）— 前置到系统提示中的内容。
可选成员：
| 成员 | 类型 | 用途 |
| ------------------------------ | ------ | ---- |
| `bootstrap(params)` | 方法 | 为会话初始化引擎状态。当引擎首次看到某个会话时调用一次（例如导入历史记录）。 |
| `ingestBatch(params)` | 方法 | 批量摄取一个已完成的轮次。在一次运行结束后调用，且该轮次的所有消息会一次性传入。 |
| `afterTurn(params)` | 方法 | 运行后的生命周期工作（持久化状态、触发后台压缩）。 |
| `prepareSubagentSpawn(params)` | 方法 | 在子会话开始前为其设置共享状态。 |
| `onSubagentEnded(params)` | 方法 | 在子智能体结束后执行清理。 |
| `dispose()` | 方法 | 释放资源。在 Gateway 网关关闭或插件重载时调用——不是按会话调用。 |
| 成员 | 类型 | 用途 |
| ------------------------------ | ------ | -------------------------------------------------------------------------------------------------------------- |
| `bootstrap(params)` | 方法 | 为会话初始化引擎状态。当引擎首次看到一个会话时调用一次（例如导入历史记录）。 |
| `ingestBatch(params)` | 方法 | 以批量方式摄取一个已完成轮次。在一次运行完成后调用，并一次性传入该轮次的所有消息。 |
| `afterTurn(params)` | 方法 | 运行后的生命周期工作（持久化状态、触发后台压缩）。 |
| `prepareSubagentSpawn(params)` | 方法 | 在子会话开始前为其设置共享状态。 |
| `onSubagentEnded(params)` | 方法 | 在子智能体结束后进行清理。 |
| `dispose()` | 方法 | 释放资源。在 Gateway 网关关闭或插件重载期间调用——不是按会话调用。 |
### ownsCompaction
`ownsCompaction` 控制 Pi 的内置单次尝试内自动压缩是否在本次运行中
保持启用：
`ownsCompaction` 控制 Pi 内置的尝试内自动压缩是否
在该次运行中保持启用：
- `true`——该引擎负责压缩行为。OpenClaw 会为该次运行禁用 Pi 的内置
自动压缩，而引擎的 `compact()` 实现则负责处理 `/compact`、
溢出恢复压缩，以及它希望在 `afterTurn()` 中执行的任何主动
压缩。
- `false` 或未设置——Pi 的内置自动压缩仍可能在提示词
执行期间运行，但当前激活引擎的 `compact()` 方法仍会用于
- `true` — 该引擎拥有压缩行为的控制权。OpenClaw 会禁用 Pi 内置的
自动压缩功能用于该次运行，而引擎的 `compact()` 实现
负责处理 `/compact`、溢出恢复压缩，以及它希望在 `afterTurn()`
中执行的任何主动压缩。OpenClaw 仍然可能运行
提示前的溢出保护机制；当它预测完整转录会溢出时，
恢复路径会在再次提交提示之前调用当前活动引擎的 `compact()`。
- `false` 或未设置 — Pi 内置的自动压缩在提示
执行期间仍可能运行，但活动引擎的 `compact()` 方法仍会用于
`/compact` 和溢出恢复。
`ownsCompaction: false` **并不**意味着 OpenClaw 会自动回退到
legacy 引擎的压缩路径。
这意味着存在两种有效的插件模式：
这意味着有两种有效的插件模式：
- **接管模式**——实现你自己的压缩算法，并设置
- **拥有模式** — 实现你自己的压缩算法，并设置
`ownsCompaction: true`。
- **委托模式**——设置 `ownsCompaction: false`，并让 `compact()` 调用
`openclaw/plugin-sdk/core` 中的 `delegateCompactionToRuntime(...)`，
以使用 OpenClaw 的内置压缩行为。
- **委托模式** — 设置 `ownsCompaction: false`，并让 `compact()` 调用
`openclaw/plugin-sdk/core` 中的 `delegateCompactionToRuntime(...)`，以使用
OpenClaw 内置的压缩行为。
对于一个处于激活状态的非接管引擎来说，无操作的 `compact()` 是不安全的，因为它
会禁用该引擎插槽的常规 `/compact` 和溢出恢复压缩路径。
对于一个活动的非拥有型引擎来说，无操作的 `compact()` 是不安全的，因为它
会禁用该引擎插槽正常的 `/compact` 和溢出恢复压缩路径。
## 配置参考
@ -242,57 +244,57 @@ legacy 引擎的压缩路径。
{
plugins: {
slots: {
// 选择当前激活的上下文引擎。默认值："legacy"。
// 设为某个插件 id 即可使用插件引擎。
// Select the active context engine. Default: "legacy".
// Set to a plugin id to use a plugin engine.
contextEngine: "legacy",
},
},
}
```
该插槽在运行时是互斥的——对于一次给定的运行或压缩操作，只会解析
一个已注册的上下文引擎。其他已启用的
`kind: "context-engine"` 插件仍然可以加载并运行其注册
代码；`plugins.slots.contextEngine` 只决定当 OpenClaw 需要上下文引擎时，
它会解析哪个已注册的引擎 id。
该插槽在运行时是排他的——对于给定的一次运行或压缩操作，
只会解析一个已注册的上下文引擎。其他已启用的
`kind: "context-engine"` 插件仍然可以加载并运行它们的注册
代码；`plugins.slots.contextEngine` 只决定当 OpenClaw 需要
上下文引擎时，会解析哪个已注册的引擎 id。
## 与压缩和记忆的关系
- **压缩**是上下文引擎的一项职责。legacy 引擎
- **压缩** 是上下文引擎的一项职责。legacy 引擎
委托给 OpenClaw 的内置总结机制。插件引擎可以实现
任意压缩策略（DAG 摘要、向量检索等）。
- **记忆插件**（`plugins.slots.memory`）与上下文引擎是分开的。
任何压缩策略（DAG 摘要、向量检索等）。
- **记忆插件**（`plugins.slots.memory`）与上下文引擎是分离的。
记忆插件提供搜索/检索；上下文引擎控制
模型看到什么。它们可以协同工作——上下文引擎可能会在
组装期间使用记忆插件的数据。想要使用当前激活记忆
模型能看到什么。它们可以协同工作——上下文引擎可能会在
组装期间使用记忆插件的数据。希望使用当前活动记忆
提示路径的插件引擎，应优先使用
`openclaw/plugin-sdk/core` 中的 `buildMemorySystemPromptAddition(...)`，
它会把当前激活的记忆提示部分转换成可直接预置的
它会将当前活动的记忆提示区段转换为可直接前置的
`systemPromptAddition`。如果引擎需要更底层的
控制，它仍然可以通过
`openclaw/plugin-sdk/memory-host-core` 中的
`buildActiveMemoryPromptSection(...)`
拉取原始行内容。
- **会话裁剪**（在内存中修剪旧的工具结果）仍会运行，
无论当前激活的是哪个上下文引擎。
提取原始行。
- **会话修剪**（在内存中裁剪旧工具结果）仍会运行，
无论当前启用了哪个上下文引擎。
## 提示
- 使用 `openclaw doctor` 验证你的引擎是否正确加载。
- 如果切换引擎，现有会话会继续保留其当前历史记录。
新引擎将接管后续运行。
- 引擎错误会被记录并显示在诊断中。如果插件引擎
注册失败，或无法解析所选引擎 id，OpenClaw
不会自动回退；运行会失败，直到你修复插件或
将 `plugins.slots.contextEngine` 切回 `"legacy"`。
- 在开发时，使用 `openclaw plugins install -l ./my-engine` 可以链接
本地插件目录而不进行复制。
- 如果切换引擎，现有会话会继续保留它们当前的历史记录。
新引擎将接管之后的运行。
- 引擎错误会被记录并显示在诊断信息中。如果插件引擎
注册失败，或者所选引擎 id 无法解析，OpenClaw
不会自动回退；在你修复插件或将
`plugins.slots.contextEngine` 切回 `"legacy"` 之前，运行都会失败。
- 在开发过程中，使用 `openclaw plugins install -l ./my-engine` 可以链接
本地插件目录，而无需复制。
另见：[压缩](/zh-CN/concepts/compaction)、[上下文](/zh-CN/concepts/context)、
另请参阅：[压缩](/zh-CN/concepts/compaction)、[上下文](/zh-CN/concepts/context)、
[插件](/zh-CN/tools/plugin)、[插件清单](/zh-CN/plugins/manifest)。
## 相关内容
- [上下文](/zh-CN/concepts/context)——如何为智能体轮次构建上下文
- [插件架构](/zh-CN/plugins/architecture)——注册上下文引擎插件
- [压缩](/zh-CN/concepts/compaction)——总结长对话
- [上下文](/zh-CN/concepts/context) — 如何为智能体轮次构建上下文
- [Plugin architecture](/zh-CN/plugins/architecture) — 注册上下文引擎插件
- [压缩](/zh-CN/concepts/compaction) — 总结长对话