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-05 23:42:21 +00:00
parent a7fcd1c79d
commit ac65c9db37
2 changed files with 188 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

215
docs/zh-CN/concepts/dreaming.md
View File

@ -2,53 +2,52 @@
read_when:
- 你希望记忆提升能够自动运行
- 你希望了解 Dreaming 的三个阶段
- 你希望在不污染 MEMORY.md 的情况下调整整合行为
summary: 通过 light、deep 和 REM 三个协同阶段进行后台记忆整合
- 你希望调整整合过程而不污染 `MEMORY.md`
summary: 具有三个协作阶段的后台记忆整合：浅睡、深睡和 REM
title: Dreaming（实验性）
x-i18n:
generated_at: "2026-04-05T22:59:53Z"
generated_at: "2026-04-05T23:42:21Z"
model: gpt-5.4
provider: openai
source_hash: e6a82edf0b8630b48f458dacc270b0afc4032d5756baf39e28bf142e53cd8080
source_hash: 9ba56b20013aa53f5f440fd79ea14dc67a61c4fb63ebe91b3fd183d09a842912
source_path: concepts/dreaming.md
workflow: 15
---
# Dreaming（实验性）
Dreaming 是 `memory-core` 中的后台记忆整合系统。它会重新查看对话中出现的内容，并决定哪些内容值得保留为持久上下文。
Dreaming 是 `memory-core` 中的后台记忆整合系统。它会重新审视对话期间出现的内容，并判断哪些值得保留为持久上下文。
Dreaming 使用三个协同工作的**阶段**，而不是彼此竞争的模式。每个阶段都有不同的职责、写入不同的目标，并按照自己的计划运行。
Dreaming 使用三个相互协作的**阶段**，而不是彼此竞争的模式。每个阶段都有不同的职责、写入不同的目标，并按各自的时间表运行。
## 三个阶段
### Light
### 浅睡
Light Dreaming 会整理最近的杂乱内容。它会扫描最近的记忆轨迹，按 Jaccard 相似度去重，对相关条目进行聚类，并在启用 inline 存储时，将候选记忆暂存到共享的 Dreaming 轨迹文件（`DREAMS.md`）中。
浅睡 Dreaming 用来整理最近的杂乱信息。它会扫描最近的记忆痕迹，按 Jaccard 相似度去重，对相关条目进行聚类，并在启用内联存储时将候选记忆暂存到共享的 Dreaming 轨迹文件（`DREAMS.md`）中。
Light **不会**向 `MEMORY.md` 写入任何内容。它只负责组织和暂存。可以理解为：“今天哪些内容以后可能会重要？”
浅睡**不会**向 `MEMORY.md` 写入任何内容。它只负责整理和暂存。可以理解为：“今天的哪些内容以后可能有用？”
### Deep
### 深睡
Deep Dreaming 会决定哪些内容会成为持久记忆。它运行真正的提升逻辑：基于六种信号的加权评分、阈值门槛、召回次数、唯一查询多样性、近期性衰减以及最大年龄过滤。
深睡 Dreaming 决定哪些内容会成为持久记忆。它执行真正的提升逻辑：基于六个信号进行加权评分，并应用阈值门槛、召回次数、唯一查询多样性、时效衰减和最大年龄过滤。
Deep 是**唯一**允许将持久事实写入 `MEMORY.md` 的阶段。
它还负责在记忆不足时进行恢复（当健康度低于配置阈值时）。可以理解为：“哪些内容足够真实，值得保留？”
深睡是**唯一**允许向 `MEMORY.md` 写入持久事实的阶段。它还负责在记忆稀薄时进行恢复（健康度低于配置阈值）。可以理解为：“哪些内容足够真实，值得保留？”
### REM
REM Dreaming 会寻找模式并进行反思。它检查最近的材料，通过概念标签聚类识别反复出现的主题，并在启用 inline 存储时，将更高层次的笔记和反思写入 `DREAMS.md`。
REM Dreaming 用于发现模式与反思。它会检查近期内容，通过概念标签聚类识别反复出现的主题，并在启用内联存储时将更高层次的笔记和反思写入 `DREAMS.md`。
REM 在 inline 模式下会写入 `DREAMS.md`，**不会**写入 `MEMORY.md`。
REM 在内联模式下写入 `DREAMS.md`，**不会**写入 `MEMORY.md`。
它的输出是解释性的，而不是规范性的。可以理解为：“我注意到了什么模式？”
## 明确边界
## 硬性边界
| 阶段 | 职责 | 写入位置 | 不会写入 |
| ----- | -------- | ------------------------- | -------- |
| Light | 整理 | `DREAMS.md`（inline 模式） | MEMORY.md |
| Deep | 保留 | MEMORY.md | -- |
| REM | 解释 | `DREAMS.md`（inline 模式） | MEMORY.md |
| 浅睡 | 整理 | `DREAMS.md`（内联模式） | MEMORY.md |
| 深睡 | 保留 | MEMORY.md | -- |
| REM | 解释 | `DREAMS.md`（内联模式） | MEMORY.md |
## 快速开始
@ -70,7 +69,7 @@ REM 在 inline 模式下会写入 `DREAMS.md`，**不会**写入 `MEMORY.md`。
}
```
仅启用 deep 提升：
仅启用深睡提升：
```json
{
@ -95,72 +94,71 @@ REM 在 inline 模式下会写入 `DREAMS.md`，**不会**写入 `MEMORY.md`。
## 配置
所有 Dreaming 设置都位于 `openclaw.json` 中的 `plugins.entries.memory-core.config.dreaming` 下。
完整键名列表请参见 [记忆配置参考](/zh-CN/reference/memory-config#dreaming-experimental)。
所有 Dreaming 设置都位于 `openclaw.json` 中的 `plugins.entries.memory-core.config.dreaming` 下。完整键名列表请参见[记忆配置参考](/zh-CN/reference/memory-config#dreaming-experimental)。
### 全局设置
| 键名 | 类型 | 默认值 | 说明 |
| 键名 | 类型 | 默认值 | 描述 |
| ---------------- | --------- | ---------- | ------------------------------------------------------------ |
| `enabled` | `boolean` | `true` | 所有阶段的总开关 |
| `timezone` | `string` | 未设置 | 用于计划评估和 Dreaming 日期分桶的时区 |
| `timezone` | `string` | 未设置 | 用于时间表评估和 Dreaming 日期分桶的时区 |
| `verboseLogging` | `boolean` | `false` | 输出每次运行的详细 Dreaming 日志 |
| `storage.mode` | `string` | `"inline"` | 使用 inline `DREAMS.md`、独立报告，或两者同时使用 |
| `storage.mode` | `string` | `"inline"` | 使用内联 `DREAMS.md`、单独报告，或同时使用两者 |
### Light 阶段配置
### 浅睡阶段配置
| 键名 | 类型 | 默认值 | 说明 |
| ------------------ | ---------- | ------------------------------- | -------------------------- |
| `enabled` | `boolean` | `true` | 启用 Light 阶段 |
| `cron` | `string` | `0 */6 * * *` | 计划（默认：每 6 小时） |
| `lookbackDays` | `number` | `2` | 扫描多少天内的轨迹 |
| `limit` | `number` | `100` | 每次运行最多暂存的候选数 |
| `dedupeSimilarity` | `number` | `0.9` | 去重的 Jaccard 阈值 |
| `sources` | `string[]` | `["daily","sessions","recall"]` | 要扫描的数据源 |
| 键名 | 类型 | 默认值 | 描述 |
| ------------------ | ---------- | ------------------------------- | ---------------------------- |
| `enabled` | `boolean` | `true` | 启用浅睡阶段 |
| `cron` | `string` | `0 */6 * * *` | 调度计划（默认：每 6 小时） |
| `lookbackDays` | `number` | `2` | 扫描多少天内的痕迹 |
| `limit` | `number` | `100` | 每次运行最多暂存的候选数 |
| `dedupeSimilarity` | `number` | `0.9` | 去重的 Jaccard 阈值 |
| `sources` | `string[]` | `["daily","sessions","recall"]` | 要扫描的数据源 |
### Deep 阶段配置
### 深睡阶段配置
| 键名 | 类型 | 默认值 | 说明 |
| --------------------- | ---------- | ----------------------------------------------- | ------------------------------------ |
| `enabled` | `boolean` | `true` | 启用 Deep 阶段 |
| `cron` | `string` | `0 3 * * *` | 计划（默认：每天凌晨 3 点） |
| `limit` | `number` | `10` | 每个周期最多提升的候选数 |
| `minScore` | `number` | `0.8` | 提升所需的最低加权分数 |
| `minRecallCount` | `number` | `3` | 最低召回次数阈值 |
| `minUniqueQueries` | `number` | `3` | 最低不同查询数量 |
| `recencyHalfLifeDays` | `number` | `14` | 近期性分数减半所需的天数 |
| `maxAgeDays` | `number` | `30` | 可提升的每日笔记最大年龄 |
| `sources` | `string[]` | `["daily","memory","sessions","logs","recall"]` | 数据源 |
| 键名 | 类型 | 默认值 | 描述 |
| --------------------- | ---------- | ----------------------------------------------- | -------------------------------- |
| `enabled` | `boolean` | `true` | 启用深睡阶段 |
| `cron` | `string` | `0 3 * * *` | 调度计划（默认：每天凌晨 3 点） |
| `limit` | `number` | `10` | 每个周期最多提升的候选数 |
| `minScore` | `number` | `0.8` | 提升所需的最低加权分数 |
| `minRecallCount` | `number` | `3` | 最低召回次数阈值 |
| `minUniqueQueries` | `number` | `3` | 最低不同查询数量 |
| `recencyHalfLifeDays` | `number` | `14` | 时效分数减半所需天数 |
| `maxAgeDays` | `number` | `30` | 可用于提升的每日笔记最大年龄 |
| `sources` | `string[]` | `["daily","memory","sessions","logs","recall"]` | 数据源 |
### Deep 恢复配置
### 深睡恢复配置
当长期记忆健康度低于某个阈值时，会触发恢复。
| 键名 | 类型 | 默认值 | 说明 |
| --------------------------------- | --------- | ------- | -------------------------------- |
| `recovery.enabled` | `boolean` | `true` | 启用自动恢复 |
| `recovery.triggerBelowHealth` | `number` | `0.35` | 触发恢复的健康度分数阈值 |
| `recovery.lookbackDays` | `number` | `30` | 向前查找恢复材料的范围 |
| `recovery.maxRecoveredCandidates` | `number` | `20` | 每次运行最多恢复的候选数 |
| `recovery.minRecoveryConfidence` | `number` | `0.9` | 恢复候选所需的最低置信度 |
| `recovery.autoWriteMinConfidence` | `number` | `0.97` | 自动写入阈值（跳过人工审查） |
| 键名 | 类型 | 默认值 | 描述 |
| --------------------------------- | --------- | ------- | ---------------------------------- |
| `recovery.enabled` | `boolean` | `true` | 启用自动恢复 |
| `recovery.triggerBelowHealth` | `number` | `0.35` | 触发恢复的健康度阈值 |
| `recovery.lookbackDays` | `number` | `30` | 向前回看多长时间以查找恢复材料 |
| `recovery.maxRecoveredCandidates` | `number` | `20` | 每次运行最多恢复的候选数 |
| `recovery.minRecoveryConfidence` | `number` | `0.9` | 恢复候选所需的最低置信度 |
| `recovery.autoWriteMinConfidence` | `number` | `0.97` | 自动写入阈值（跳过人工审核） |
### REM 阶段配置
| 键名 | 类型 | 默认值 | 说明 |
| -------------------- | ---------- | --------------------------- | ------------------------------------ |
| `enabled` | `boolean` | `true` | 启用 REM 阶段 |
| `cron` | `string` | `0 5 * * 0` | 计划（默认：每周日凌晨 5 点） |
| `lookbackDays` | `number` | `7` | 反思多少天内的材料 |
| `limit` | `number` | `10` | 最多写入的模式或主题数量 |
| `minPatternStrength` | `number` | `0.75` | 最低标签共现强度 |
| `sources` | `string[]` | `["memory","daily","deep"]` | 用于反思的数据源 |
| 键名 | 类型 | 默认值 | 描述 |
| -------------------- | ---------- | --------------------------- | -------------------------------- |
| `enabled` | `boolean` | `true` | 启用 REM 阶段 |
| `cron` | `string` | `0 5 * * 0` | 调度计划（默认：每周日凌晨 5 点） |
| `lookbackDays` | `number` | `7` | 回顾多少天内的材料 |
| `limit` | `number` | `10` | 最多写入的模式或主题数量 |
| `minPatternStrength` | `number` | `0.75` | 最低标签共现强度 |
| `sources` | `string[]` | `["memory","daily","deep"]` | 用于反思的数据源 |
### 执行覆盖
### 执行覆盖设置
每个阶段都支持一个 `execution` 块，用于覆盖全局默认值：
每个阶段都接受一个 `execution` 块，用于覆盖全局默认值：
| 键名 | 类型 | 默认值 | 说明 |
| 键名 | 类型 | 默认值 | 描述 |
| ----------------- | -------- | ------------ | ------------------------------ |
| `speed` | `string` | `"balanced"` | `fast`、`balanced` 或 `slow` |
| `thinking` | `string` | `"medium"` | `low`、`medium` 或 `high` |
@ -170,36 +168,36 @@ REM 在 inline 模式下会写入 `DREAMS.md`，**不会**写入 `MEMORY.md`。
| `temperature` | `number` | 未设置 | 采样温度（0-2） |
| `timeoutMs` | `number` | 未设置 | 阶段超时时间（毫秒） |
## 提升信号（Deep 阶段）
## 提升信号（深睡阶段）
Deep Dreaming 会组合六种加权信号。要完成提升，所有已配置的阈值门槛都必须同时通过。
深睡 Dreaming 会组合六个加权信号。要完成提升，所有已配置的阈值门槛都必须同时通过。
| 信号 | 权重 | 说明 |
| 信号 | 权重 | 描述 |
| ------------------ | ---- | -------------------------------------------------- |
| 频率 | 0.24 | 同一条目被召回的频率 |
| 相关性 | 0.30 | 被检索到时的平均召回分数 |
| 查询多样性 | 0.15 | 使其浮现出来的不同查询意图数量 |
| 近期性 | 0.15 | 时间衰减（`recencyHalfLifeDays`，默认 14） |
| 整合度 | 0.10 | 奖励跨多天重复出现的召回 |
| 概念丰富度 | 0.06 | 奖励派生概念标签更丰富的条目 |
| 时效性 | 0.15 | 时间衰减（`recencyHalfLifeDays`，默认 14） |
| 整合度 | 0.10 | 奖励跨多日重复发生的召回 |
| 概念丰富度 | 0.06 | 奖励具有更丰富派生概念标签的条目 |
## 聊天命令
```
/dreaming status # 显示阶段配置和执行频率
/dreaming status # 显示阶段配置和运行节奏
/dreaming on # 启用所有阶段
/dreaming off # 禁用所有阶段
/dreaming enable light|deep|rem # 启用特定阶段
/dreaming disable light|deep|rem # 禁用特定阶段
/dreaming enable light|deep|rem # 启用指定阶段
/dreaming disable light|deep|rem # 禁用指定阶段
/dreaming help # 显示使用指南
```
## CLI 命令
从命令行预览并应用 deep 提升：
在命令行中预览并应用深睡提升：
```bash
# 预览提升候选
# 预览提升候选项
openclaw memory promote
# 将提升结果应用到 MEMORY.md
@ -208,7 +206,7 @@ openclaw memory promote --apply
# 限制预览数量
openclaw memory promote --limit 5
# 包含已提升条目
# 包含已经提升的条目
openclaw memory promote --include-promoted
# 检查 Dreaming 状态
@ -217,56 +215,69 @@ openclaw memory status --deep
完整 flag 参考请参见 [memory CLI](/cli/memory)。
### 预览与解释工具
另外两个子命令可帮助你在不写入任何内容的情况下检查提升与 REM 行为：
```bash
# 解释某个候选为何会或不会被提升
openclaw memory promote-explain "meeting notes"
# 预览 REM 反思、候选事实和深睡提升
openclaw memory rem-harness --json
```
完整选项请参见 [memory CLI](/cli/memory)。
## 工作原理
### Light 阶段流程
### 浅睡阶段流水线
1. 从 `memory/.dreams/short-term-recall.json` 读取短期召回条目。
2. 过滤出在当前时间 `lookbackDays` 范围内的条目。
2. 过滤出距当前时间在 `lookbackDays` 范围内的条目。
3. 按 Jaccard 相似度去重（阈值可配置）。
4. 按平均召回分数排序，最多取 `limit` 条目。
5. 在启用 inline 存储时，将暂存候选写入 `DREAMS.md` 的 `## Light Sleep` 区块下。
4. 按平均召回分数排序，最多取 `limit` 个条目。
5. 在启用内联存储时，将暂存候选写入 `DREAMS.md` 中的 `## Light Sleep` 区块下。
### Deep 阶段流程
### 深睡阶段流水线
1. 使用加权信号读取并排序短期召回候选。
2. 应用阈值门槛：`minScore`、`minRecallCount`、`minUniqueQueries`。
3. 按 `maxAgeDays` 过滤，并应用近期性衰减。
4. 扩展到所有已配置的记忆工作区。
5. 写入前重新读取实时每日笔记（跳过过期或已删除的片段）。
6. 将符合条件的条目连同提升时间戳追加到 `MEMORY.md`。
7. 标记已提升条目，以便在后续周期中将其排除。
3. 按 `maxAgeDays` 过滤，并应用时效衰减。
4. 分发到已配置的各个记忆工作区。
5. 写入前重新读取实时每日笔记（跳过过时或已删除的片段）。
6. 将符合条件的条目及其提升时间戳追加到 `MEMORY.md`。
7. 标记已提升条目，以便将来周期中排除它们。
8. 如果健康度低于 `recovery.triggerBelowHealth`，则运行恢复流程。
### REM 阶段流程
### REM 阶段流水线
1. 读取 `lookbackDays` 范围内的近期记忆轨迹。
2. 按共现关系对概念标签进行聚类。
1. 读取 `lookbackDays` 范围内的近期记忆痕迹。
2. 按共现关系对概念标签聚类。
3. 按 `minPatternStrength` 过滤模式。
4. 在启用 inline 存储时，将主题和反思写入 `DREAMS.md` 的 `## REM Sleep` 区块下。
4. 在启用内联存储时，将主题和反思写入 `DREAMS.md` 中的 `## REM Sleep` 区块下。
## 调度
每个阶段都会自动管理自己的 cron 任务。启用 Dreaming 后，
`memory-core` 会在 Gateway 网关启动时协调受管的 cron 任务。你无需手动创建 cron 条目。
每个阶段都会自动管理自己的 cron 作业。启用 Dreaming 后，`memory-core` 会在 Gateway 网关启动时协调受管 cron 作业。你无需手动创建 cron 条目。
| 阶段 | 默认计划 | 说明 |
| 阶段 | 默认计划 | 描述 |
| ----- | ---------------- | ----------------- |
| Light | `0 */6 * * *` | 每 6 小时一次 |
| Deep | `0 3 * * *` | 每天凌晨 3 点 |
| 浅睡 | `0 */6 * * *` | 每 6 小时一次 |
| 深睡 | `0 3 * * *` | 每天凌晨 3 点 |
| REM | `0 5 * * 0` | 每周日凌晨 5 点 |
你可以使用阶段的 `cron` 键覆盖任意计划。所有计划都会遵循全局 `timezone` 设置。
你可以用各阶段的 `cron` 键覆盖任意计划。所有计划都会遵循全局 `timezone` 设置。
## Dreams UI
启用 Dreaming 后，Gateway 网关侧边栏会显示一个 **Dreams** 标签页，其中包含记忆统计信息（短期数量、长期数量、已提升数量）以及下一次计划周期时间。每日计数在设置了 `dreaming.timezone` 时会遵循该时区，否则回退到已配置的用户时区。
启用 Dreaming 后，Gateway 网关侧边栏会显示一个**Dreams**选项卡，其中包含记忆统计信息（短期数量、长期数量、已提升数量）以及下一次计划周期的时间。每日计数会在设置 `dreaming.timezone` 时遵循该时区，否则回退到已配置的用户时区。
手动运行 `openclaw memory promote` 时，默认会使用与 Deep 阶段相同的阈值，因此除非你传入 CLI 覆盖项，否则计划提升与按需提升会保持一致。
手动运行 `openclaw memory promote` 默认会使用与深睡阶段相同的阈值，因此除非你传入 CLI 覆盖项，否则计划内提升与按需提升会保持一致。
## 相关内容
- [记忆](/zh-CN/concepts/memory)
- [记忆搜索](/zh-CN/concepts/memory-search)
- [Memory](/zh-CN/concepts/memory)
- [Memory Search](/zh-CN/concepts/memory-search)
- [记忆配置参考](/zh-CN/reference/memory-config)
- [memory CLI](/cli/memory)

148
docs/zh-CN/tools/lobster.md
View File

@ -1,54 +1,54 @@
---
read_when:
- 你希望使用带显式批准的确定性多步骤工作流
- 你想要具有显式审批机制的确定性多步骤工作流
- 你需要在不重新运行前面步骤的情况下恢复工作流
summary: OpenClaw 的类型化工作流运行时，带可恢复的 approval gate。
summary: OpenClaw 的类型化工作流运行时，支持可恢复的审批关卡。
title: Lobster
x-i18n:
generated_at: "2026-04-05T10:12:07Z"
generated_at: "2026-04-05T23:42:20Z"
model: gpt-5.4
provider: openai
source_hash: 82718c15d571406ad6f1507de22a528fdab873edfc6aafae10742e500f6a5eda
source_hash: c1014945d104ef8fdca0d30be89e35136def1b274c6403b06de29e8502b8124b
source_path: tools/lobster.md
workflow: 15
---
# Lobster
Lobster 是一个工作流 shell，让 OpenClaw 能够将多步骤工具序列作为单个、确定性的操作来运行，并带有显式的批准检查点。
Lobster 是一个工作流 shell，让 OpenClaw 能将多步骤工具序列作为一次单一、确定性的操作来运行，并带有显式审批检查点。
Lobster 比脱离式后台工作高一个编写层级。关于单个任务之上的 flow 编排，请参见 [Task Flow](/zh-CN/automation/taskflow)（`openclaw tasks flow`）。关于任务活动账本，请参见 [`openclaw tasks`](/zh-CN/automation/tasks)。
Lobster 位于分离式后台工作的上一层编写层级。有关单个任务之上的流程编排，请参见 [Task Flow](/zh-CN/automation/taskflow)（`openclaw tasks flow`）。有关任务活动账本，请参见 [`openclaw tasks`](/zh-CN/automation/tasks)。
## 引子
## 核心亮点
你的助手可以构建用于管理它自己的工具。提出一个工作流请求，30 分钟后你就能得到一个 CLI 加上一套可通过一次调用运行的流水线。Lobster 正是缺失的那一块：确定性流水线、显式批准和可恢复状态。
你的助手可以构建管理其自身的工具。提出一个工作流需求，30 分钟后你就能得到一个 CLI 和一组能通过一次调用运行的流水线。Lobster 正是缺失的那一块：确定性流水线、显式审批和可恢复状态。
## 为什么
如今，复杂工作流需要许多来回的工具调用。每次调用都会消耗 token，而且 LLM 必须编排每一个步骤。Lobster 将这种编排移入一个类型化运行时中：
如今，复杂工作流需要大量来回的工具调用。每次调用都会消耗 token，而且 LLM 必须编排每一步。Lobster 将这种编排移入一个类型化运行时中：
- **一次调用替代多次调用**：OpenClaw 运行一次 Lobster 工具调用并得到结构化结果。
- **内置批准**：副作用操作（发送邮件、发布评论）会暂停工作流，直到明确批准。
- **可恢复**：被暂停的工作流会返回一个 token；批准后可继续，而无需重新运行所有内容。
- **一次调用代替多次调用**：OpenClaw 运行一次 Lobster 工具调用，并获得结构化结果。
- **内置审批**：带有副作用的操作（发送邮件、发布评论）会暂停工作流，直到被显式批准。
- **可恢复**：已暂停的工作流会返回一个 token；批准后可继续，而无需重新运行所有内容。
## 为什么使用 DSL，而不是普通程序？
Lobster 是刻意保持小巧的。目标不是“创造一门新语言”，而是提供一种可预测、对 AI 友好的流水线规范，并带有一等公民级别的批准和恢复 token。
Lobster 有意保持精简。目标不是“发明一种新语言”，而是提供一种可预测、对 AI 友好的流水线规范，并内建一等支持的审批和恢复 token。
- **内置 approve/resume**：普通程序可以提示人类，但如果不由你自己发明那套运行时，它就无法使用持久 token 来_暂停并恢复_。
- **确定性 + 可审计性**：流水线是数据，因此易于记录、Diffs、重放和审查。
- **为 AI 限制表面**：微小的语法 + JSON 管道减少了“创造性”代码路径，使验证更现实。
- **内建安全策略**：超时、输出上限、沙箱检查和 allowlists 都由运行时强制执行，而不是由每个脚本各自处理。
- **仍然可编程**：每个步骤都可以调用任意 CLI 或脚本。如果你想使用 JS/TS，可以从代码生成 `.lobster` 文件。
- **内置批准/恢复机制**：普通程序可以提示人工确认，但如果没有你自己发明那套运行时，它就无法借助持久 token 实现_暂停并恢复_。
- **确定性 + 可审计性**：流水线是数据，因此容易记录、Diffs、重放和审查。
- **面向 AI 的受限表面**：精简语法 + JSON 管道可减少“创造性”代码路径，并让校验变得切实可行。
- **内建安全策略**：超时、输出上限、沙箱检查和允许列表都由运行时强制执行，而不是由每个脚本分别处理。
- **依然可编程**：每一步都可以调用任意 CLI 或脚本。如果你想用 JS/TS，可以从代码生成 `.lobster` 文件。
## 工作原理
OpenClaw 会以**工具模式**启动本地 `lobster` CLI，并从 stdout 解析一个 JSON 信封。
如果流水线因等待批准而暂停，该工具会返回一个 `resumeToken`，以便你稍后继续。
OpenClaw 使用内嵌运行器**在进程内**运行 Lobster 工作流。不会生成外部 CLI 子进程；工作流引擎在 Gateway 网关进程内执行，并直接返回一个 JSON 包装对象。
如果流水线因等待审批而暂停，工具会返回一个 `resumeToken`，这样你就可以稍后继续。
## 模式：小型 CLI + JSON 管道 + 批准
## 模式：小型 CLI + JSON 管道 + 审批
构建一些使用 JSON 通信的小命令，然后把它们串联成一次 Lobster 调用。（下面的命令名仅为示例 —— 你可以替换成自己的。）
构建能输出 JSON 的小命令，然后将它们串联成一次 Lobster 调用。（下面的命令名仅作示例——可替换为你自己的命令。）
```bash
inbox list --json
@ -64,7 +64,7 @@ inbox apply --json
}
```
如果流水线请求批准，请使用该 token 恢复：
如果流水线请求审批，可使用 token 恢复：
```json
{
@ -74,7 +74,7 @@ inbox apply --json
}
```
AI 触发工作流；Lobster 执行各个步骤。approval gates 让副作用保持显式且可审计。
AI 触发工作流；Lobster 执行这些步骤。审批关卡让副作用保持显式且可审计。
示例：将输入项映射为工具调用：
@ -83,11 +83,11 @@ gog.gmail.search --query 'newer_than:1d' \
| openclaw.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}'
```
## 仅限 JSON 的 LLM 步骤（llm-task）
## 仅 JSON 的 LLM 步骤（`llm-task`）
对于需要**结构化 LLM 步骤**的工作流，请启用可选的
`llm-task` 插件工具，并从 Lobster 中调用它。这样既能保持工作流的
确定性，又能继续使用模型进行分类/摘要/起草。
对于需要**结构化 LLM 步骤**的工作流，启用可选的
`llm-task` 插件工具，并从 Lobster 中调用它。这样可以让工作流保持
确定性，同时仍然可以借助模型进行分类、总结或起草。
启用该工具：
@ -128,11 +128,11 @@ openclaw.invoke --tool llm-task --action json --args-json '{
}'
```
详细信息和配置选项请参见 [LLM Task](/zh-CN/tools/llm-task)。
有关详细信息和配置选项，请参见 [LLM Task](/zh-CN/tools/llm-task)。
## 工作流文件（.lobster）
## 工作流文件（`.lobster`）
Lobster 可以运行 YAML/JSON 工作流文件，支持 `name`、`args`、`steps`、`env`、`condition` 和 `approval` 字段。在 OpenClaw 工具调用中，将 `pipeline` 设置为文件路径即可。
Lobster 可以运行带有 `name`、`args`、`steps`、`env`、`condition` 和 `approval` 字段的 YAML/JSON 工作流文件。在 OpenClaw 工具调用中，将 `pipeline` 设置为文件路径。
```yaml
name: inbox-triage
@ -158,11 +158,13 @@ steps:
说明：
- `stdin: $step.stdout` 和 `stdin: $step.json` 会传递前一步的输出。
- `condition`（或 `when`）可根据 `$step.approved` 控制步骤是否运行。
- `condition`（或 `when`）可基于 `$step.approved` 控制步骤是否执行。
## 安装 Lobster
请在运行 OpenClaw Gateway 网关的**同一台主机**上安装 Lobster CLI（参见 [Lobster 仓库](https://github.com/openclaw/lobster)），并确保 `lobster` 已加入 `PATH`。
内置的 Lobster 工作流在进程内运行；不需要单独的 `lobster` 二进制文件。内嵌运行器随 Lobster 插件一起提供。
如果你在开发或外部流水线中需要独立的 Lobster CLI，请从 [Lobster repo](https://github.com/openclaw/lobster) 安装，并确保 `lobster` 已在 `PATH` 中。
## 启用该工具
@ -178,7 +180,7 @@ Lobster 是一个**可选**插件工具（默认未启用）。
}
```
或按智能体配置：
或者按智能体配置：
```json
{
@ -195,28 +197,28 @@ Lobster 是一个**可选**插件工具（默认未启用）。
}
```
除非你确实打算在严格 allowlist 模式下运行，否则请避免使用 `tools.allow: ["lobster"]`。
除非你打算在限制性允许列表模式下运行，否则请避免使用 `tools.allow: ["lobster"]`。
注意：对于可选插件，allowlists 是选择加入的。如果你的 allowlist 只命名了
插件工具（例如 `lobster`），OpenClaw 仍会保持核心工具启用。若要限制核心
工具，也请在 allowlist 中加入你希望保留的核心工具或工具组。
注意：允许列表对于可选插件是选择启用的。如果你的允许列表只列出
插件工具（如 `lobster`），OpenClaw 会保留核心工具启用状态。若要限制核心
工具，也请将你希望保留的核心工具或工具组一并加入允许列表。
## 示例：邮件分类处理
## 示例：电子邮件分类处理
不使用 Lobster：
没有 Lobster 时：
```
User: "Check my email and draft replies"
→ openclaw 调用 gmail.list
→ LLM 做摘要
→ LLM 进行总结
→ User: "draft replies to #2 and #5"
→ LLM 起草回复
→ User: "send #2"
→ openclaw 调用 gmail.send
（每天重复，且不记得哪些内容已被分类处理）
（每天重复，没有关于已分类内容的记忆）
```
使用 Lobster：
使用 Lobster 时：
```json
{
@ -226,7 +228,7 @@ User: "Check my email and draft replies"
}
```
返回一个 JSON 信封（已截断）：
返回一个 JSON 包装对象（已截断）：
```json
{
@ -258,7 +260,7 @@ User: "Check my email and draft replies"
### `run`
以工具模式运行一个流水线。
以工具模式运行流水线。
```json
{
@ -282,7 +284,7 @@ User: "Check my email and draft replies"
### `resume`
在批准后继续一个被暂停的工作流。
在审批后继续已暂停的工作流。
```json
{
@ -294,62 +296,62 @@ User: "Check my email and draft replies"
### 可选输入
- `cwd`：流水线的相对工作目录（必须保持在当前进程工作目录内）。
- `timeoutMs`：如果子进程超过该时长，则将其终止（默认：20000）。
- `maxStdoutBytes`：如果 stdout 超过该大小，则将子进程终止（默认：512000）。
- `cwd`：流水线的相对工作目录（必须保持在 Gateway 网关工作目录内）。
- `timeoutMs`：如果工作流超过该时长则中止（默认：20000）。
- `maxStdoutBytes`：如果输出超过该大小则中止（默认：512000）。
- `argsJson`：传递给 `lobster run --args-json` 的 JSON 字符串（仅适用于工作流文件）。
## 输出信封
## 输出包装对象
Lobster 会返回一个 JSON 信封，其状态有以下三种之一：
Lobster 返回一个 JSON 包装对象，其状态有以下三种之一：
- `ok` → 成功完成
- `needs_approval` → 已暂停；恢复时需要 `requiresApproval.resumeToken`
- `cancelled` → 已被显式拒绝或取消
- `cancelled` → 被显式拒绝或取消
该工具会同时在 `content`（美化后的 JSON）和 `details`（原始对象）中暴露该信封。
该工具会在 `content`（美化后的 JSON）和 `details`（原始对象）中同时提供该包装对象。
## 批准
## 审批
如果存在 `requiresApproval`，请检查提示并决定：
如果存在 `requiresApproval`，请检查提示并作出决定：
- `approve: true` → 恢复并继续执行副作用
- `approve: false` → 取消并结束该工作流
- `approve: true` → 恢复并继续执行带副作用的操作
- `approve: false` → 取消并结束工作流
使用 `approve --preview-from-stdin --limit N` 可以将 JSON 预览附加到批准请求中，而无需自定义 jq/heredoc 胶水代码。现在的恢复 token 更紧凑：Lobster 会将工作流恢复状态存储在其状态目录下，并返回一个小型 token 键。
使用 `approve --preview-from-stdin --limit N` 可将 JSON 预览附加到审批请求中，而无需自定义 `jq` / heredoc 胶水代码。恢复 token 现在更加紧凑：Lobster 会将工作流恢复状态存储在其状态目录下，并返回一个小型 token 键。
## OpenProse
OpenProse 与 Lobster 很搭：使用 `/prose` 来编排多智能体准备工作，然后运行一个 Lobster 流水线来获得确定性批准。如果某个 Prose 程序需要 Lobster，请通过 `tools.subagents.tools` 为子智能体允许 `lobster` 工具。参见 [OpenProse](/zh-CN/prose)。
OpenProse 与 Lobster 配合良好：使用 `/prose` 来编排多智能体准备工作，然后运行 Lobster 流水线以进行确定性审批。如果某个 Prose 程序需要 Lobster，可通过 `tools.subagents.tools` 为子智能体允许 `lobster` 工具。请参见 [OpenProse](/zh-CN/prose)。
## 安全
- **仅限本地子进程** —— 插件本身不发起网络调用。
- **无密钥管理** —— Lobster 不管理 OAuth；它调用的是管理这些内容的 OpenClaw 工具。
- **感知沙箱** —— 在沙箱化工具上下文中会被禁用。
- **已加固** —— 固定可执行文件名（`PATH` 中的 `lobster`）；并强制执行超时和输出上限。
- **仅限本地进程内**——工作流在 Gateway 网关进程内执行；插件本身不会发起网络调用。
- **无密钥管理**——Lobster 不管理 OAuth；它调用的是负责管理 OAuth 的 OpenClaw 工具。
- **感知沙箱**——当工具上下文处于沙箱隔离状态时将被禁用。
- **已加固**——超时和输出上限由内嵌运行器强制执行。
## 故障排除
- **`lobster subprocess timed out`** → 增加 `timeoutMs`，或拆分过长的流水线。
- **`lobster output exceeded maxStdoutBytes`** → 提高 `maxStdoutBytes` 或减少输出量。
- **`lobster returned invalid JSON`** → 确保流水线以工具模式运行，并且只打印 JSON。
- **`lobster failed (code …)`** → 在终端中运行相同的流水线以检查 stderr。
- **`lobster timed out`** → 增加 `timeoutMs`，或拆分较长的流水线。
- **`lobster output exceeded maxStdoutBytes`** → 提高 `maxStdoutBytes` 或减少输出大小。
- **`lobster returned invalid JSON`** → 确保流水线以工具模式运行，并且只输出 JSON。
- **`lobster failed`** → 检查 Gateway 网关日志中的内嵌运行器错误详情。
## 了解更多
- [插件](/zh-CN/tools/plugin)
- [插件工具编写](/zh-CN/plugins/building-plugins#registering-agent-tools)
- [Plugins](/zh-CN/tools/plugin)
- [Plugin tool authoring](/zh-CN/plugins/building-plugins#registering-agent-tools)
## 案例研究：社区工作流
一个公开示例是：“second brain” CLI + Lobster 流水线，用于管理三个 Markdown 仓库（个人、伴侣、共享）。该 CLI 会为统计、收件箱列表和陈旧扫描输出 JSON；Lobster 再把这些命令串联成诸如 `weekly-review`、`inbox-triage`、`memory-consolidation` 和 `shared-task-sync` 之类的工作流，并为每个工作流设置 approval gates。AI 在可用时负责判断（分类），不可用时则回退为确定性规则。
一个公开示例是：一个“第二大脑” CLI + Lobster 流水线，用于管理三个 Markdown 知识库（个人、伴侣、共享）。该 CLI 会为统计信息、收件箱列表和陈旧内容扫描输出 JSON；Lobster 再将这些命令串联为 `weekly-review`、`inbox-triage`、`memory-consolidation` 和 `shared-task-sync` 等工作流，并为每个工作流设置审批关卡。在可用时，AI 负责判断（分类）；在不可用时，则回退到确定性规则。
- 讨论串：[https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033)
- 仓库：[https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli)
## 相关内容
- [自动化与任务](/zh-CN/automation) —— 调度 Lobster 工作流
- [自动化概览](/zh-CN/automation) —— 所有自动化机制
- [工具概览](/zh-CN/tools) —— 所有可用的智能体工具
- [Automation & Tasks](/zh-CN/automation) — 调度 Lobster 工作流
- [Automation Overview](/zh-CN/automation) — 所有自动化机制
- [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具