chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
a8898e4969
commit
a7d9939741
@ -1,36 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- 更改群组消息规则或提及方式
|
||||
summary: WhatsApp 群组消息处理的行为与配置（mentionPatterns 在各个界面间共享）
|
||||
- 更改群组消息规则或提及设置
|
||||
summary: WhatsApp 群组消息处理的行为和配置（`mentionPatterns` 在各个界面中共享）
|
||||
title: 群组消息
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T08:14:41Z"
|
||||
generated_at: "2026-04-12T18:22:02Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2543be5bc4c6f188f955df580a6fef585ecbfc1be36ade5d34b1a9157e021bc5
|
||||
source_hash: 5d9484dd1de74d42f8dce4c3ac80d60c24864df30a7802e64893ef55506230fe
|
||||
source_path: channels/group-messages.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 群组消息（WhatsApp web 渠道）
|
||||
|
||||
目标：让 Clawd 能待在 WhatsApp 群组中，仅在被提及时唤醒，并将该线程与个人私信会话分开。
|
||||
目标：让 Clawd 待在 WhatsApp 群组中，只在被点名时唤醒，并将该线程与个人私信会话分开。
|
||||
|
||||
注意：`agents.list[].groupChat.mentionPatterns` 现在也用于 Telegram/Discord/Slack/iMessage；本文档重点介绍 WhatsApp 特有的行为。对于多智能体设置，请为每个智能体设置 `agents.list[].groupChat.mentionPatterns`（或使用 `messages.groupChat.mentionPatterns` 作为全局回退）。
|
||||
注意：`agents.list[].groupChat.mentionPatterns` 现在也被 Telegram/Discord/Slack/iMessage 使用；本文档侧重于 WhatsApp 特有的行为。对于多智能体设置，请为每个智能体设置 `agents.list[].groupChat.mentionPatterns`（或使用 `messages.groupChat.mentionPatterns` 作为全局回退）。
|
||||
|
||||
## 当前实现（2025-12-03）
|
||||
|
||||
- 激活模式：`mention`（默认）或 `always`。`mention` 需要一次提及（真实的 WhatsApp @ 提及，通过 `mentionedJids`、安全的正则模式，或文本中任意位置出现的机器人的 E.164 号码）。`always` 会在每条消息上唤醒智能体，但它应仅在能提供有意义价值时回复；否则返回精确的静默令牌 `NO_REPLY` / `no_reply`。默认值可在配置中通过 `channels.whatsapp.groups` 设置，并可通过 `/activation` 按群组覆盖。当设置了 `channels.whatsapp.groups` 时，它也会充当群组 allowlist（包含 `"*"` 可允许所有群组）。
|
||||
- 群组策略：`channels.whatsapp.groupPolicy` 控制是否接受群组消息（`open|disabled|allowlist`）。`allowlist` 使用 `channels.whatsapp.groupAllowFrom`（回退：显式的 `channels.whatsapp.allowFrom`）。默认值为 `allowlist`（在你添加发送者前会被阻止）。
|
||||
- 按群组划分的会话：会话键类似 `agent:<agentId>:whatsapp:group:<jid>`，因此像 `/verbose on` 或 `/think high` 这样的命令（作为独立消息发送）会限定在该群组内；个人私信状态不会受到影响。Heartbeat 会跳过群组线程。
|
||||
- 上下文注入：**仅待处理**的群组消息（默认 50 条）中，_未_触发运行的消息会以 `[Chat messages since your last reply - for context]` 为前缀注入，而触发消息会放在 `[Current message - respond to this]` 下。已经在会话中的消息不会再次注入。
|
||||
- 发送者显示：每个群组批次现在都会以 `[from: Sender Name (+E164)]` 结束，以便 Pi 知道是谁在发言。
|
||||
- 阅后即焚 / 查看一次：我们会先解包这些消息，再提取文本/提及，因此其中的提及仍可触发。
|
||||
- 群组系统提示词：在群组会话的第一轮（以及每次 `/activation` 更改模式时），我们会向系统提示词注入一段简短说明，例如 `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.`。如果元数据不可用，我们仍会告诉智能体这是一个群聊。
|
||||
- 激活模式：`mention`（默认）或 `always`。`mention` 需要一次点名（真实的 WhatsApp @ 提及，通过 `mentionedJids`、安全的正则模式，或文本中任意位置出现的机器人的 E.164 号码）。`always` 会在每条消息时唤醒智能体，但它应该只在能够提供有意义价值时回复；否则返回精确的静默令牌 `NO_REPLY` / `no_reply`。默认值可在配置中设置（`channels.whatsapp.groups`），并可通过 `/activation` 按群组覆盖。当设置了 `channels.whatsapp.groups` 时，它还会充当群组允许列表（包含 `"*"` 可允许全部）。
|
||||
- 群组策略：`channels.whatsapp.groupPolicy` 控制是否接受群组消息（`open|disabled|allowlist`）。`allowlist` 使用 `channels.whatsapp.groupAllowFrom`（回退：显式的 `channels.whatsapp.allowFrom`）。默认值为 `allowlist`（在你添加发送者之前会被阻止）。
|
||||
- 按群组划分的会话：会话键看起来像 `agent:<agentId>:whatsapp:group:<jid>`，因此诸如 `/verbose on`、`/trace on` 或 `/think high` 之类的命令（作为独立消息发送）仅作用于该群组；个人私信状态不会受影响。群组线程会跳过心跳消息。
|
||||
- 上下注入：**仅待处理的** 群组消息（默认 50 条）中，_未_ 触发运行的消息会被加前缀放在 `[Chat messages since your last reply - for context]` 下，而触发的那一行会放在 `[Current message - respond to this]` 下。已经在会话中的消息不会被重复注入。
|
||||
- 发送者呈现：每个群组批次现在都会以 `[from: Sender Name (+E164)]` 结尾，以便 Pi 知道是谁在说话。
|
||||
- 阅后即焚 / view-once：我们会在提取文本 / 提及之前先解包这些消息，因此其中的点名仍然会触发。
|
||||
- 群组系统提示：在群组会话的第一轮（以及每当 `/activation` 更改模式时），我们会向系统提示中注入一段简短说明，例如 `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.`。如果元数据不可用，我们仍会告诉智能体这是一个群聊。
|
||||
|
||||
## 配置示例（WhatsApp）
|
||||
|
||||
向 `~/.openclaw/openclaw.json` 添加一个 `groupChat` 代码块，这样即使 WhatsApp 从文本正文中去掉了可见的 `@`，显示名提及仍然能生效：
|
||||
向 `~/.openclaw/openclaw.json` 添加一个 `groupChat` 块，这样即使 WhatsApp 在文本正文中去掉可见的 `@`，显示名称点名也能生效：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -57,8 +57,8 @@ x-i18n:
|
||||
|
||||
说明：
|
||||
|
||||
- 这些正则表达式不区分大小写，并使用与其他配置正则界面相同的安全正则防护规则；无效模式和不安全的嵌套重复会被忽略。
|
||||
- 当有人点按联系人时，WhatsApp 仍会通过 `mentionedJids` 发送规范提及，因此号码回退很少需要，但作为安全兜底仍然很有用。
|
||||
- 这些正则表达式不区分大小写，并使用与其他配置正则表达式界面相同的安全正则保护规则；无效模式和不安全的嵌套重复会被忽略。
|
||||
- 当有人点按联系人时，WhatsApp 仍会通过 `mentionedJids` 发送规范提及，因此号码回退很少需要，但它是一个有用的安全兜底。
|
||||
|
||||
### 激活命令（仅限所有者）
|
||||
|
||||
@ -67,25 +67,25 @@ x-i18n:
|
||||
- `/activation mention`
|
||||
- `/activation always`
|
||||
|
||||
只有所有者号码（来自 `channels.whatsapp.allowFrom`，或在未设置时为机器人自己的 E.164 号码）可以更改此设置。在群组中以独立消息发送 `/status` 可查看当前激活模式。
|
||||
只有所有者号码（来自 `channels.whatsapp.allowFrom`，如果未设置则为机器人自己的 E.164）可以更改此项。在群组中以独立消息发送 `/status` 以查看当前激活模式。
|
||||
|
||||
## 使用方法
|
||||
|
||||
1. 将你的 WhatsApp 账户（运行 OpenClaw 的那个）添加到群组中。
|
||||
2. 说 `@openclaw …`（或包含该号码）。除非你将 `groupPolicy` 设为 `"open"`，否则只有在 allowlist 中的发送者才能触发它。
|
||||
3. 智能体提示词将包含最近的群组上下文以及尾部的 `[from: …]` 标记，以便它能回应正确的人。
|
||||
4. 会话级指令（`/verbose on`、`/think high`、`/new` 或 `/reset`、`/compact`）仅适用于该群组的会话；请将它们作为独立消息发送，以便正确注册。你的个人私信会话保持独立。
|
||||
1. 将你的 WhatsApp 账号（运行 OpenClaw 的那个）添加到群组中。
|
||||
2. 发送 `@openclaw …`（或包含该号码）。除非你设置 `groupPolicy: "open"`，否则只有允许列表中的发送者才能触发它。
|
||||
3. 智能体提示将包含最近的群组上下文以及末尾的 `[from: …]` 标记，以便它能回应正确的人。
|
||||
4. 会话级指令（`/verbose on`、`/trace on`、`/think high`、`/new` 或 `/reset`、`/compact`）仅适用于该群组的会话；请将它们作为独立消息发送，以便能够注册。你的个人私信会话保持独立。
|
||||
|
||||
## 测试 / 验证
|
||||
|
||||
- 手动冒烟测试：
|
||||
- 在群组中发送一个 `@openclaw` 提及，并确认回复中引用了发送者姓名。
|
||||
- 发送第二次提及，并验证历史记录代码块已包含，然后会在下一轮被清除。
|
||||
- 检查 Gateway 网关日志（使用 `--verbose` 运行），查看显示 `from: <groupJid>` 和 `[from: …]` 后缀的 `inbound web message` 条目。
|
||||
- 在群组中发送一次 `@openclaw` 点名，并确认收到的回复引用了发送者姓名。
|
||||
- 发送第二次点名，并验证历史块已被包含，然后在下一轮被清除。
|
||||
- 检查 Gateway 网关日志（使用 `--verbose` 运行），查看 `inbound web message` 条目，其中显示 `from: <groupJid>` 和 `[from: …]` 后缀。
|
||||
|
||||
## 已知注意事项
|
||||
|
||||
- 为避免噪声广播，Heartbeat 会有意跳过群组。
|
||||
- 回显抑制使用组合后的批次字符串；如果你连续两次发送相同文本且不带提及，只有第一次会收到回复。
|
||||
- 会话存储条目会在会话存储中显示为 `agent:<agentId>:whatsapp:group:<jid>`（默认位于 `~/.openclaw/agents/<agentId>/sessions/sessions.json`）；如果缺少该条目，只表示该群组尚未触发运行。
|
||||
- 群组中的输入状态指示器遵循 `agents.defaults.typingMode`（默认值：未被提及时为 `message`）。
|
||||
- 群组会有意跳过心跳消息，以避免产生嘈杂的广播。
|
||||
- 回显抑制使用合并后的整批字符串；如果你连续两次发送相同文本且没有提及，只有第一次会得到响应。
|
||||
- 会话存储条目会在会话存储中显示为 `agent:<agentId>:whatsapp:group:<jid>`（默认位于 `~/.openclaw/agents/<agentId>/sessions/sessions.json`）；缺少某个条目仅表示该群组尚未触发过一次运行。
|
||||
- 群组中的输入指示器遵循 `agents.defaults.typingMode`（默认：未被提及时为 `message`）。
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想了解活动记忆的用途
|
||||
- 你想为一个对话式智能体开启活动记忆
|
||||
- 你想为一个对话式智能体启用活动记忆
|
||||
- 你想调整活动记忆的行为，而不在所有地方都启用它
|
||||
summary: 一个由插件拥有的阻塞式 Memory 子智能体，会将相关记忆注入到交互式聊天会话中
|
||||
summary: 一个由插件拥有的阻塞型 Memory 子智能体，会将相关记忆注入到交互式聊天会话中
|
||||
title: 活动记忆
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T04:23:32Z"
|
||||
generated_at: "2026-04-12T18:22:05Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 59456805c28daaab394ba2a7f87e1104a1334a5cf32dbb961d5d232d9c471d84
|
||||
source_hash: dc15b2139618d9dbb0ba4d9951fb82a4d86076f7b8dc1a6bf2013bcce61878c4
|
||||
source_path: concepts/active-memory.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 活动记忆
|
||||
|
||||
活动记忆是一个可选的、由插件拥有的阻塞式 Memory 子智能体，会在符合条件的对话式会话中于主回复之前运行。
|
||||
活动记忆是一个可选的、由插件拥有的阻塞型 Memory 子智能体，会在符合条件的对话式会话中于主回复之前运行。
|
||||
|
||||
它之所以存在，是因为大多数记忆系统虽然能力强，但都偏被动。它们依赖主智能体来决定何时搜索记忆，或者依赖用户说出诸如“记住这个”或“搜索记忆”这样的话。等到那时，记忆本可以让回复显得自然的那个时机其实已经过去了。
|
||||
之所以存在它，是因为大多数记忆系统虽然能力很强，但都偏向被动。它们依赖主智能体来决定何时搜索记忆，或者依赖用户说出类似“记住这个”或“搜索记忆”这样的话。等到那时，记忆原本可以让回复显得自然的那个时刻其实已经过去了。
|
||||
|
||||
活动记忆会在生成主回复之前，为系统提供一次有边界的机会来提取相关记忆。
|
||||
活动记忆为系统提供了一次有边界的机会，在生成主回复之前呈现相关记忆。
|
||||
|
||||
## 将此内容粘贴到你的智能体中
|
||||
## 粘贴到你的智能体中
|
||||
|
||||
如果你想让你的智能体以一个自包含、默认安全的配置启用活动记忆，请将以下内容粘贴到你的智能体中：
|
||||
如果你想为你的智能体启用活动记忆，并使用一个自包含、默认安全的设置，请将以下内容粘贴到你的智能体中：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -50,7 +50,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
这会为 `main` 智能体启用该插件，默认将其限制为仅用于私信风格的会话，优先让它继承当前会话的模型，并且仅在没有可用的显式模型或继承模型时才使用已配置的回退模型。
|
||||
这会为 `main` 智能体开启该插件，默认将其限制为仅在私信风格的会话中运行，优先让它继承当前会话模型，并且只有在没有显式模型或继承模型可用时，才使用已配置的回退模型。
|
||||
|
||||
之后，重启 Gateway 网关：
|
||||
|
||||
@ -58,13 +58,14 @@ x-i18n:
|
||||
openclaw gateway
|
||||
```
|
||||
|
||||
若要在对话中实时查看它：
|
||||
要在对话中实时检查它：
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
/trace on
|
||||
```
|
||||
|
||||
## 开启活动记忆
|
||||
## 启用活动记忆
|
||||
|
||||
最安全的设置方式是：
|
||||
|
||||
@ -72,7 +73,7 @@ openclaw gateway
|
||||
2. 指定一个对话式智能体
|
||||
3. 仅在调优期间保持日志开启
|
||||
|
||||
先在 `openclaw.json` 中加入以下内容：
|
||||
先在 `openclaw.json` 中添加以下内容：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -106,10 +107,10 @@ openclaw gateway
|
||||
这意味着：
|
||||
|
||||
- `plugins.entries.active-memory.enabled: true` 会启用该插件
|
||||
- `config.agents: ["main"]` 仅让 `main` 智能体加入活动记忆
|
||||
- `config.allowedChatTypes: ["direct"]` 默认仅在私信风格的会话中启用活动记忆
|
||||
- 如果未设置 `config.model`，活动记忆会优先继承当前会话模型
|
||||
- `config.modelFallback` 可选地提供你自己的回退提供商/模型以用于回忆
|
||||
- `config.agents: ["main"]` 只让 `main` 智能体加入活动记忆
|
||||
- `config.allowedChatTypes: ["direct"]` 默认只在私信风格的会话中启用活动记忆
|
||||
- 如果 `config.model` 未设置，活动记忆会优先继承当前会话模型
|
||||
- `config.modelFallback` 可选，用于为召回提供你自己的回退提供商/模型
|
||||
- `config.promptStyle: "balanced"` 会为 `recent` 模式使用默认的通用提示风格
|
||||
- 活动记忆仍然只会在符合条件的交互式持久聊天会话中运行
|
||||
|
||||
@ -117,9 +118,9 @@ openclaw gateway
|
||||
|
||||
活动记忆会为模型注入隐藏的系统上下文。它不会向客户端暴露原始的 `<active_memory_plugin>...</active_memory_plugin>` 标签。
|
||||
|
||||
## 会话开关
|
||||
## 会话切换
|
||||
|
||||
当你想在不修改配置的情况下，为当前聊天会话暂停或恢复活动记忆时，请使用插件命令：
|
||||
当你想在不编辑配置的情况下，为当前聊天会话暂停或恢复活动记忆时，请使用插件命令：
|
||||
|
||||
```text
|
||||
/active-memory status
|
||||
@ -127,8 +128,8 @@ openclaw gateway
|
||||
/active-memory on
|
||||
```
|
||||
|
||||
这是会话级别的。它不会更改
|
||||
`plugins.entries.active-memory.enabled`、智能体目标设置或其他全局配置。
|
||||
这是会话级作用域。它不会更改
|
||||
`plugins.entries.active-memory.enabled`、智能体目标设定或其他全局配置。
|
||||
|
||||
如果你希望该命令写入配置，并为所有会话暂停或恢复活动记忆，请使用显式的全局形式：
|
||||
|
||||
@ -138,32 +139,34 @@ openclaw gateway
|
||||
/active-memory on --global
|
||||
```
|
||||
|
||||
全局形式会写入 `plugins.entries.active-memory.config.enabled`。它会保持
|
||||
`plugins.entries.active-memory.enabled` 为开启状态，以便之后仍可使用该命令重新启用活动记忆。
|
||||
全局形式会写入 `plugins.entries.active-memory.config.enabled`。它会保留
|
||||
`plugins.entries.active-memory.enabled` 为开启状态，以便该命令之后仍可用于重新开启活动记忆。
|
||||
|
||||
如果你想查看活动记忆在实时会话中具体做了什么，请为该会话开启详细模式：
|
||||
如果你想查看活动记忆在实时会话中的行为，请开启与你想看到的输出相匹配的会话开关：
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
/trace on
|
||||
```
|
||||
|
||||
开启详细模式后，OpenClaw 可以显示：
|
||||
启用后，OpenClaw 可以显示：
|
||||
|
||||
- 一行活动记忆状态，例如 `Active Memory: ok 842ms recent 34 chars`
|
||||
- 一条可读的调试摘要，例如 `Active Memory Debug: Lemon pepper wings with blue cheese.`
|
||||
- 当 `/verbose on` 时，显示活动记忆状态行，例如 `Active Memory: ok 842ms recent 34 chars`
|
||||
- 当 `/trace on` 时，显示可读的调试摘要，例如 `Active Memory Debug: Lemon pepper wings with blue cheese.`
|
||||
|
||||
这些行来源于同一次为隐藏系统上下文提供内容的活动记忆过程，但它们是为人类阅读而格式化的，而不是暴露原始提示标记。
|
||||
这些行源自同一次活动记忆流程，也正是它为隐藏系统上下文提供内容的那次流程，但它们是为人类阅读而格式化的，而不是暴露原始提示标记。它们会在正常的助手回复之后作为一条后续诊断消息发送，因此像 Telegram 这样的渠道客户端不会在回复前闪出一个单独的诊断气泡。
|
||||
|
||||
默认情况下，这个阻塞式 Memory 子智能体的转录记录是临时的，会在运行完成后删除。
|
||||
默认情况下，这个阻塞型 Memory 子智能体的转录是临时的，并会在运行完成后删除。
|
||||
|
||||
示例流程：
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
/trace on
|
||||
what wings should i order?
|
||||
```
|
||||
|
||||
预期可见回复形式：
|
||||
预期的可见回复形态：
|
||||
|
||||
```text
|
||||
...normal assistant reply...
|
||||
@ -174,13 +177,13 @@ what wings should i order?
|
||||
|
||||
## 何时运行
|
||||
|
||||
活动记忆使用两个门槛条件：
|
||||
活动记忆使用两个门控条件：
|
||||
|
||||
1. **配置选择加入**
|
||||
必须启用该插件，并且当前智能体 id 必须出现在
|
||||
`plugins.entries.active-memory.config.agents` 中。
|
||||
2. **严格的运行时资格**
|
||||
即使已启用且已被指定，活动记忆也只会在符合条件的交互式持久聊天会话中运行。
|
||||
2. **严格的运行时资格条件**
|
||||
即使已启用并已设定目标，活动记忆也只会在符合条件的交互式持久聊天会话中运行。
|
||||
|
||||
实际规则是：
|
||||
|
||||
@ -208,7 +211,7 @@ active memory runs
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
这意味着活动记忆默认会在私信风格的会话中运行，但不会在群组或渠道会话中运行，除非你明确为它们开启。
|
||||
这意味着，默认情况下活动记忆会在私信风格的会话中运行，但不会在群组或渠道会话中运行，除非你显式将它们加入。
|
||||
|
||||
示例：
|
||||
|
||||
@ -224,39 +227,39 @@ allowedChatTypes: ["direct", "group"]
|
||||
allowedChatTypes: ["direct", "group", "channel"]
|
||||
```
|
||||
|
||||
## 在哪里运行
|
||||
## 运行位置
|
||||
|
||||
活动记忆是一项对话增强功能，而不是平台范围的推理功能。
|
||||
活动记忆是一项对话增强功能，而不是一项平台范围内的推理功能。
|
||||
|
||||
| Surface | 运行活动记忆？ |
|
||||
| --- | --- |
|
||||
| Control UI / web chat 持久会话 | 是，如果插件已启用且智能体已被指定 |
|
||||
| 走同一持久聊天路径的其他交互式渠道会话 | 是，如果插件已启用且智能体已被指定 |
|
||||
| 无头单次运行 | 否 |
|
||||
| 心跳/后台运行 | 否 |
|
||||
| 通用内部 `agent-command` 路径 | 否 |
|
||||
| 子智能体/内部辅助执行 | 否 |
|
||||
| Surface | 是否运行活动记忆？ |
|
||||
| ------------------------------------------------------------------- | ------------------ |
|
||||
| Control UI / web chat 持久会话 | 是，如果插件已启用且该智能体已被设为目标 |
|
||||
| 同一持久聊天路径上的其他交互式渠道会话 | 是，如果插件已启用且该智能体已被设为目标 |
|
||||
| 无头一次性运行 | 否 |
|
||||
| 心跳/后台运行 | 否 |
|
||||
| 通用内部 `agent-command` 路径 | 否 |
|
||||
| 子智能体/内部辅助执行 | 否 |
|
||||
|
||||
## 为什么使用它
|
||||
|
||||
在以下情况下使用活动记忆：
|
||||
|
||||
- 会话是持久的并且面向用户
|
||||
- 智能体拥有有意义的长期记忆可供搜索
|
||||
- 连续性和个性化比原始提示的确定性更重要
|
||||
- 会话是持久的且面向用户
|
||||
- 智能体拥有可供搜索的有意义长期记忆
|
||||
- 连续性和个性化比原始提示确定性更重要
|
||||
|
||||
它特别适用于：
|
||||
它尤其适用于：
|
||||
|
||||
- 稳定偏好
|
||||
- 重复习惯
|
||||
- 应该自然浮现的长期用户上下文
|
||||
- 应该自然浮现出来的长期用户上下文
|
||||
|
||||
它不适合用于：
|
||||
|
||||
- 自动化
|
||||
- 内部工作器
|
||||
- 单次 API 任务
|
||||
- 那些隐藏的个性化会让人意外的场景
|
||||
- 内部工作进程
|
||||
- 一次性 API 任务
|
||||
- 那些隐藏个性化会让人意外的场景
|
||||
|
||||
## 它如何工作
|
||||
|
||||
@ -271,7 +274,7 @@ flowchart LR
|
||||
I --> M["Main Reply"]
|
||||
```
|
||||
|
||||
这个阻塞式 Memory 子智能体只能使用：
|
||||
这个阻塞型 Memory 子智能体只能使用：
|
||||
|
||||
- `memory_search`
|
||||
- `memory_get`
|
||||
@ -280,22 +283,22 @@ flowchart LR
|
||||
|
||||
## 查询模式
|
||||
|
||||
`config.queryMode` 控制这个阻塞式 Memory 子智能体能看到多少对话内容。
|
||||
`config.queryMode` 控制这个阻塞型 Memory 子智能体能看到多少对话内容。
|
||||
|
||||
## 提示风格
|
||||
|
||||
`config.promptStyle` 控制这个阻塞式 Memory 子智能体在决定是否返回记忆时有多积极或多严格。
|
||||
`config.promptStyle` 控制这个阻塞型 Memory 子智能体在决定是否返回记忆时有多积极或多严格。
|
||||
|
||||
可用风格：
|
||||
|
||||
- `balanced`：`recent` 模式的通用默认选项
|
||||
- `strict`：最不积极；最适合你希望附近上下文几乎不产生串扰时使用
|
||||
- `contextual`：最利于连续性；最适合对话历史应更重要时使用
|
||||
- `recall-heavy`：即使匹配较弱但仍然合理，也更愿意提取记忆
|
||||
- `precision-heavy`：除非匹配非常明显，否则会强烈倾向于返回 `NONE`
|
||||
- `preference-only`：针对最爱、习惯、日常、口味和反复出现的个人事实进行了优化
|
||||
- `balanced`：`recent` 模式的通用默认值
|
||||
- `strict`：最不积极；最适合你希望尽量减少附近上下文渗入的情况
|
||||
- `contextual`：最有利于连续性；最适合对话历史应更重要的情况
|
||||
- `recall-heavy`：更愿意在较弱但仍合理的匹配下呈现记忆
|
||||
- `precision-heavy`：除非匹配非常明显，否则会强烈倾向返回 `NONE`
|
||||
- `preference-only`：针对收藏、习惯、日常规律、口味和重复出现的个人事实进行了优化
|
||||
|
||||
当未设置 `config.promptStyle` 时，默认映射为：
|
||||
当 `config.promptStyle` 未设置时，默认映射为：
|
||||
|
||||
```text
|
||||
message -> strict
|
||||
@ -303,7 +306,7 @@ recent -> balanced
|
||||
full -> contextual
|
||||
```
|
||||
|
||||
如果你显式设置了 `config.promptStyle`，则以该覆盖值为准。
|
||||
如果你显式设置了 `config.promptStyle`，则以该覆盖设置为准。
|
||||
|
||||
示例：
|
||||
|
||||
@ -313,7 +316,7 @@ promptStyle: "preference-only"
|
||||
|
||||
## 模型回退策略
|
||||
|
||||
如果未设置 `config.model`，活动记忆会按以下顺序尝试解析模型：
|
||||
如果 `config.model` 未设置，活动记忆会按以下顺序尝试解析模型：
|
||||
|
||||
```text
|
||||
explicit plugin model
|
||||
@ -330,15 +333,16 @@ explicit plugin model
|
||||
modelFallback: "google/gemini-3-flash"
|
||||
```
|
||||
|
||||
如果无法解析出显式模型、继承模型或已配置的回退模型，活动记忆会跳过该轮回忆。
|
||||
如果没有解析出显式模型、继承模型或已配置回退模型，活动记忆会跳过该轮的召回。
|
||||
|
||||
`config.modelFallbackPolicy` 仅作为已弃用的兼容字段保留，以支持旧配置。它不再改变运行时行为。
|
||||
`config.modelFallbackPolicy` 仅作为已弃用的兼容字段保留，用于旧配置。
|
||||
它不再改变运行时行为。
|
||||
|
||||
## 高级逃生舱选项
|
||||
## 高级逃生舱
|
||||
|
||||
这些选项有意不属于推荐设置的一部分。
|
||||
这些选项有意不包含在推荐设置中。
|
||||
|
||||
`config.thinking` 可以覆盖这个阻塞式 Memory 子智能体的 thinking 级别：
|
||||
`config.thinking` 可以覆盖这个阻塞型 Memory 子智能体的 thinking 级别：
|
||||
|
||||
```json5
|
||||
thinking: "medium"
|
||||
@ -350,21 +354,22 @@ thinking: "medium"
|
||||
thinking: "off"
|
||||
```
|
||||
|
||||
不要默认启用它。活动记忆运行在回复路径中，因此额外的思考时间会直接增加用户可感知的延迟。
|
||||
默认不要启用它。活动记忆运行在回复路径中，因此额外的思考时间会直接增加用户可见的延迟。
|
||||
|
||||
`config.promptAppend` 会在默认活动记忆提示之后、对话上下文之前，附加额外的操作员指令：
|
||||
`config.promptAppend` 会在默认活动记忆提示之后、对话上下文之前追加额外的操作员指令：
|
||||
|
||||
```json5
|
||||
promptAppend: "Prefer stable long-term preferences over one-off events."
|
||||
```
|
||||
|
||||
`config.promptOverride` 会替换默认的活动记忆提示。OpenClaw 之后仍会附加对话上下文：
|
||||
`config.promptOverride` 会替换默认的活动记忆提示。OpenClaw
|
||||
仍会在其后追加对话上下文：
|
||||
|
||||
```json5
|
||||
promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
|
||||
```
|
||||
|
||||
除非你是在有意测试不同的回忆契约，否则不建议自定义提示。默认提示已针对“返回 `NONE` 或为主模型返回紧凑的用户事实上下文”这一目标进行了调优。
|
||||
除非你是在有意测试不同的召回契约，否则不建议进行提示自定义。默认提示已针对“返回 `NONE` 或返回适用于主模型的紧凑用户事实上下文”进行了优化。
|
||||
|
||||
### `message`
|
||||
|
||||
@ -376,8 +381,8 @@ Latest user message only
|
||||
|
||||
适用场景：
|
||||
|
||||
- 你想获得最快的行为
|
||||
- 你希望最强地偏向稳定偏好的回忆
|
||||
- 你希望获得最快的行为
|
||||
- 你希望对稳定偏好召回有最强偏向
|
||||
- 后续轮次不需要对话上下文
|
||||
|
||||
建议超时时间：
|
||||
@ -386,7 +391,7 @@ Latest user message only
|
||||
|
||||
### `recent`
|
||||
|
||||
发送最新的用户消息以及一小段最近的对话尾部内容。
|
||||
发送最新的用户消息以及最近的一小段对话尾部。
|
||||
|
||||
```text
|
||||
Recent conversation tail:
|
||||
@ -400,8 +405,8 @@ Latest user message:
|
||||
|
||||
适用场景：
|
||||
|
||||
- 你希望在速度与对话语境之间取得更好的平衡
|
||||
- 追问通常依赖最近几轮对话
|
||||
- 你希望在速度和对话上下文之间取得更好的平衡
|
||||
- 后续问题通常依赖最近几轮对话
|
||||
|
||||
建议超时时间：
|
||||
|
||||
@ -409,7 +414,7 @@ Latest user message:
|
||||
|
||||
### `full`
|
||||
|
||||
将完整对话发送给这个阻塞式 Memory 子智能体。
|
||||
将完整对话发送给这个阻塞型 Memory 子智能体。
|
||||
|
||||
```text
|
||||
Full conversation context:
|
||||
@ -421,15 +426,15 @@ user: ...
|
||||
|
||||
适用场景：
|
||||
|
||||
- 最强的回忆质量比延迟更重要
|
||||
- 对话中在线程较早位置包含重要的前置内容
|
||||
- 最强的召回质量比延迟更重要
|
||||
- 对话中包含位于线程较早位置的重要铺垫内容
|
||||
|
||||
建议超时时间：
|
||||
|
||||
- 相比 `message` 或 `recent` 明显提高
|
||||
- 相较于 `message` 或 `recent` 明显增加
|
||||
- 根据线程大小，从 `15000` ms 或更高开始
|
||||
|
||||
总体来说，超时时间应随着上下文大小增加而增加：
|
||||
一般来说，超时时间应随上下文大小增加：
|
||||
|
||||
```text
|
||||
message < recent < full
|
||||
@ -437,15 +442,15 @@ message < recent < full
|
||||
|
||||
## 转录持久化
|
||||
|
||||
活动记忆阻塞式 Memory 子智能体运行会在阻塞式 Memory 子智能体调用期间创建一个真实的 `session.jsonl` 转录文件。
|
||||
活动记忆阻塞型 Memory 子智能体运行会在阻塞型 Memory 子智能体调用期间创建一个真实的 `session.jsonl` 转录文件。
|
||||
|
||||
默认情况下，该转录是临时的：
|
||||
|
||||
- 它会写入临时目录
|
||||
- 它仅用于该阻塞式 Memory 子智能体运行
|
||||
- 运行结束后会立即删除
|
||||
- 它仅用于该次阻塞型 Memory 子智能体运行
|
||||
- 它会在运行结束后立即删除
|
||||
|
||||
如果你想出于调试或检查目的，将这些阻塞式 Memory 子智能体转录保留在磁盘上，请显式开启持久化：
|
||||
如果你想将这些阻塞型 Memory 子智能体转录保留在磁盘上以便调试或检查，请显式开启持久化：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -464,21 +469,21 @@ message < recent < full
|
||||
}
|
||||
```
|
||||
|
||||
启用后，活动记忆会将转录存储在目标智能体会话文件夹下的一个单独目录中，而不是主用户对话转录路径中。
|
||||
启用后，活动记忆会将转录存储在目标智能体会话文件夹下的单独目录中，而不是主用户对话转录路径中。
|
||||
|
||||
默认布局在概念上为：
|
||||
默认布局在概念上是：
|
||||
|
||||
```text
|
||||
agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
|
||||
```
|
||||
|
||||
你可以通过 `config.transcriptDir` 更改这个相对子目录。
|
||||
你可以通过 `config.transcriptDir` 更改这个相对的子目录。
|
||||
|
||||
请谨慎使用：
|
||||
|
||||
- 在繁忙会话中，阻塞式 Memory 子智能体转录可能会很快累积
|
||||
- `full` 查询模式可能会复制大量对话上下文
|
||||
- 这些转录包含隐藏提示上下文和已回忆出的记忆
|
||||
- 在繁忙会话中，阻塞型 Memory 子智能体转录可能会快速累积
|
||||
- `full` 查询模式可能会重复大量对话上下文
|
||||
- 这些转录包含隐藏的提示上下文和召回的记忆
|
||||
|
||||
## 配置
|
||||
|
||||
@ -490,32 +495,32 @@ plugins.entries.active-memory
|
||||
|
||||
最重要的字段有：
|
||||
|
||||
| Key | Type | 含义 |
|
||||
| 键 | 类型 | 含义 |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `enabled` | `boolean` | 启用插件本身 |
|
||||
| `config.agents` | `string[]` | 可使用活动记忆的智能体 id |
|
||||
| `config.model` | `string` | 可选的阻塞式 Memory 子智能体模型引用；未设置时，活动记忆会使用当前会话模型 |
|
||||
| `config.queryMode` | `"message" \| "recent" \| "full"` | 控制阻塞式 Memory 子智能体能看到多少对话内容 |
|
||||
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | 控制阻塞式 Memory 子智能体在决定是否返回记忆时有多积极或多严格 |
|
||||
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | 阻塞式 Memory 子智能体的高级 thinking 覆盖；默认值为 `off` 以保证速度 |
|
||||
| `config.promptOverride` | `string` | 高级完整提示替换；不建议正常使用 |
|
||||
| `config.promptAppend` | `string` | 追加到默认或覆盖提示之后的高级额外指令 |
|
||||
| `config.timeoutMs` | `number` | 阻塞式 Memory 子智能体的硬超时时间 |
|
||||
| `config.agents` | `string[]` | 允许使用活动记忆的智能体 id |
|
||||
| `config.model` | `string` | 可选的阻塞型 Memory 子智能体模型引用；未设置时，活动记忆会使用当前会话模型 |
|
||||
| `config.queryMode` | `"message" \| "recent" \| "full"` | 控制阻塞型 Memory 子智能体能看到多少对话内容 |
|
||||
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | 控制阻塞型 Memory 子智能体在决定是否返回记忆时有多积极或多严格 |
|
||||
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | 阻塞型 Memory 子智能体的高级 thinking 覆盖项；默认为 `off` 以保证速度 |
|
||||
| `config.promptOverride` | `string` | 高级完整提示替换；不建议日常使用 |
|
||||
| `config.promptAppend` | `string` | 追加到默认或覆盖提示后的高级额外说明 |
|
||||
| `config.timeoutMs` | `number` | 阻塞型 Memory 子智能体的硬超时时间 |
|
||||
| `config.maxSummaryChars` | `number` | active-memory 摘要允许的最大总字符数 |
|
||||
| `config.logging` | `boolean` | 在调优时输出活动记忆日志 |
|
||||
| `config.persistTranscripts` | `boolean` | 将阻塞式 Memory 子智能体转录保留在磁盘上，而不是删除临时文件 |
|
||||
| `config.transcriptDir` | `string` | 智能体会话文件夹下阻塞式 Memory 子智能体转录的相对目录 |
|
||||
| `config.logging` | `boolean` | 在调优期间输出活动记忆日志 |
|
||||
| `config.persistTranscripts` | `boolean` | 将阻塞型 Memory 子智能体转录保留在磁盘上，而不是删除临时文件 |
|
||||
| `config.transcriptDir` | `string` | 智能体会话文件夹下阻塞型 Memory 子智能体转录的相对子目录 |
|
||||
|
||||
有用的调优字段：
|
||||
|
||||
| Key | Type | 含义 |
|
||||
| 键 | 类型 | 含义 |
|
||||
| ----------------------------- | -------- | ------------------------------------------------------------- |
|
||||
| `config.maxSummaryChars` | `number` | active-memory 摘要允许的最大总字符数 |
|
||||
| `config.recentUserTurns` | `number` | 当 `queryMode` 为 `recent` 时要包含的先前用户轮次数 |
|
||||
| `config.recentAssistantTurns` | `number` | 当 `queryMode` 为 `recent` 时要包含的先前助手轮次数 |
|
||||
| `config.recentUserTurns` | `number` | 当 `queryMode` 为 `recent` 时要包含的先前用户轮次 |
|
||||
| `config.recentAssistantTurns` | `number` | 当 `queryMode` 为 `recent` 时要包含的先前助手轮次 |
|
||||
| `config.recentUserChars` | `number` | 每个最近用户轮次的最大字符数 |
|
||||
| `config.recentAssistantChars` | `number` | 每个最近助手轮次的最大字符数 |
|
||||
| `config.cacheTtlMs` | `number` | 对重复的相同查询进行缓存复用 |
|
||||
| `config.cacheTtlMs` | `number` | 对重复的相同查询复用缓存 |
|
||||
|
||||
## 推荐设置
|
||||
|
||||
@ -541,34 +546,79 @@ plugins.entries.active-memory
|
||||
}
|
||||
```
|
||||
|
||||
如果你想在调优时检查实时行为，请在会话中使用 `/verbose on`，而不是寻找单独的 active-memory 调试命令。
|
||||
如果你想在调优时检查实时行为，请使用 `/verbose on` 查看正常状态行，使用 `/trace on` 查看 active-memory 调试摘要，而不是去寻找单独的 active-memory 调试命令。在聊天渠道中，这些诊断行会在主助手回复之后发送，而不是之前。
|
||||
|
||||
然后再根据需要调整为：
|
||||
然后再调整为：
|
||||
|
||||
- 如果你想降低延迟，改用 `message`
|
||||
- 如果你认为更多上下文值得接受更慢的阻塞式 Memory 子智能体，则改用 `full`
|
||||
- 如果你想降低延迟，则使用 `message`
|
||||
- 如果你认为更多上下文值得接受更慢的阻塞型 Memory 子智能体，则使用 `full`
|
||||
|
||||
## 调试
|
||||
|
||||
如果活动记忆没有按预期显示：
|
||||
如果活动记忆没有如你预期那样显示：
|
||||
|
||||
1. 确认插件已在 `plugins.entries.active-memory.enabled` 下启用。
|
||||
1. 确认已在 `plugins.entries.active-memory.enabled` 下启用插件。
|
||||
2. 确认当前智能体 id 已列在 `config.agents` 中。
|
||||
3. 确认你正在通过交互式持久聊天会话进行测试。
|
||||
4. 打开 `config.logging: true` 并查看 Gateway 网关日志。
|
||||
5. 使用 `openclaw memory status --deep` 验证记忆搜索本身是否正常工作。
|
||||
3. 确认你是通过交互式持久聊天会话进行测试。
|
||||
4. 开启 `config.logging: true` 并查看 Gateway 网关日志。
|
||||
5. 使用 `openclaw memory status --deep` 验证记忆搜索本身是否正常。
|
||||
|
||||
如果记忆命中过于嘈杂，请收紧：
|
||||
|
||||
- `maxSummaryChars`
|
||||
|
||||
如果活动记忆过慢，请尝试：
|
||||
如果活动记忆过慢：
|
||||
|
||||
- 降低 `queryMode`
|
||||
- 降低 `timeoutMs`
|
||||
- 减少最近轮次数
|
||||
- 减少最近轮次数量
|
||||
- 降低每轮字符上限
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 嵌入提供商意外更改
|
||||
|
||||
活动记忆依赖于 `agents.defaults.memorySearch` 下正常的记忆搜索嵌入提供商。如果你没有显式设置该提供商，OpenClaw 会自动检测第一个可用的嵌入提供商。
|
||||
|
||||
这在真实部署中可能会令人困惑：
|
||||
|
||||
- 新增可用的 API 密钥可能会改变记忆搜索所使用的提供商
|
||||
- 某个命令或诊断界面可能会让选中的提供商看起来与实时记忆同步或搜索引导期间实际命中的路径不同
|
||||
- 托管提供商可能因配额或速率限制而失败，而这些错误只有在活动记忆开始于每次回复前发起召回搜索后才会显现
|
||||
|
||||
如果你在意可预测行为，请显式固定记忆嵌入提供商，而不要依赖自动检测。
|
||||
|
||||
示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
memorySearch: {
|
||||
provider: "ollama",
|
||||
model: "nomic-embed-text",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
或者，如果你想使用 Gemini 嵌入：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
memorySearch: {
|
||||
provider: "gemini",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
更改提供商后，重启 Gateway 网关，并在开启 `/trace on` 的情况下重新测试，这样活动记忆调试行就会反映新的嵌入路径。
|
||||
|
||||
## 相关页面
|
||||
|
||||
- [记忆搜索](/zh-CN/concepts/memory-search)
|
||||
|
||||
@ -4,40 +4,40 @@ read_when:
|
||||
summary: 智能体循环生命周期、流和等待语义
|
||||
title: 智能体循环
|
||||
x-i18n:
|
||||
generated_at: "2026-04-10T07:10:49Z"
|
||||
generated_at: "2026-04-12T18:22:03Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b6831a5b11e9100e49f650feca51ab44a2bef242ce1b5db2766d0b3b5c5ba729
|
||||
source_hash: 3c2986708b444055340e0c91b8fce7d32225fcccf3d197b797665fd36b1991a5
|
||||
source_path: concepts/agent-loop.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 智能体循环（OpenClaw）
|
||||
|
||||
智能体循环是智能体一次完整且“真实”的运行过程：输入接收 → 上下文组装 → 模型推理 →
|
||||
工具执行 → 流式回复 → 持久化。它是将一条消息转化为动作和最终回复的权威路径，同时保持会话状态一致。
|
||||
智能体循环是一次智能体完整的“真实”运行：接收输入 → 组装上下文 → 模型推理 →
|
||||
工具执行 → 流式回复 → 持久化。它是将一条消息转化为操作和最终回复的权威路径，同时保持会话状态一致。
|
||||
|
||||
在 OpenClaw 中，一个循环是每个会话一次单独的串行运行；当模型进行思考、调用工具并流式输出时，它会发出生命周期事件和流事件。本文档说明这个真实循环是如何端到端连接起来的。
|
||||
在 OpenClaw 中，循环是每个会话一次单独的串行运行；当模型进行思考、调用工具并流式输出时，它会发出生命周期事件和流事件。本文档解释了这个真实循环是如何端到端连接起来的。
|
||||
|
||||
## 入口点
|
||||
|
||||
- Gateway RPC：`agent` 和 `agent.wait`。
|
||||
- Gateway 网关 RPC：`agent` 和 `agent.wait`。
|
||||
- CLI：`agent` 命令。
|
||||
|
||||
## 工作原理（高级概览）
|
||||
|
||||
1. `agent` RPC 校验参数，解析会话（`sessionKey`/`sessionId`），持久化会话元数据，并立即返回 `{ runId, acceptedAt }`。
|
||||
2. `agentCommand` 运行智能体：
|
||||
- 解析模型以及 `thinking`/`verbose` 默认值
|
||||
- 解析模型以及 `thinking`/`verbose`/`trace` 默认值
|
||||
- 加载 Skills 快照
|
||||
- 调用 `runEmbeddedPiAgent`（`pi-agent-core` 运行时）
|
||||
- 如果嵌入式循环没有发出事件，则发出 **lifecycle end/error**
|
||||
- 如果嵌入循环未发出结束事件，则发出 **lifecycle end/error**
|
||||
3. `runEmbeddedPiAgent`：
|
||||
- 通过按会话划分的队列和全局队列将运行串行化
|
||||
- 解析模型和认证配置文件，并构建 Pi 会话
|
||||
- 通过按会话划分的队列和全局队列实现串行运行
|
||||
- 解析模型和认证配置，并构建 Pi 会话
|
||||
- 订阅 Pi 事件并流式传输 assistant/tool 增量
|
||||
- 强制执行超时，超出后中止运行
|
||||
- 返回负载和 usage 元数据
|
||||
- 强制执行超时；超出后中止运行
|
||||
- 返回负载和用量元数据
|
||||
4. `subscribeEmbeddedPiSession` 将 `pi-agent-core` 事件桥接到 OpenClaw `agent` 流：
|
||||
- 工具事件 => `stream: "tool"`
|
||||
- assistant 增量 => `stream: "assistant"`
|
||||
@ -46,122 +46,122 @@ x-i18n:
|
||||
- 等待 `runId` 对应的 **lifecycle end/error**
|
||||
- 返回 `{ status: ok|error|timeout, startedAt, endedAt, error? }`
|
||||
|
||||
## 排队 + 并发
|
||||
## 队列 + 并发
|
||||
|
||||
- 运行会按会话键（会话通道）串行化，并可选地再经过一个全局通道。
|
||||
- 运行会按会话键（会话通道）串行化，并且可选地经过全局通道。
|
||||
- 这可以防止工具/会话竞争，并保持会话历史一致。
|
||||
- 消息渠道可以选择排队模式（`collect`/`steer`/`followup`）并接入这个通道系统。
|
||||
- 消息渠道可以选择队列模式（collect/steer/followup），这些模式会接入该通道系统。
|
||||
参见 [命令队列](/zh-CN/concepts/queue)。
|
||||
|
||||
## 会话 + 工作区准备
|
||||
|
||||
- 工作区会被解析并创建；沙箱隔离运行可能会重定向到一个沙箱工作区根目录。
|
||||
- Skills 会被加载（或从快照复用），并注入到环境和提示词中。
|
||||
- 引导文件/上下文文件会被解析，并注入到系统提示报告中。
|
||||
- 会获取会话写锁；`SessionManager` 会在流式传输开始前打开并完成准备。
|
||||
- 工作区会被解析并创建；沙箱隔离运行可能会重定向到沙箱工作区根目录。
|
||||
- Skills 会被加载（或从快照复用），并注入到环境变量和提示词中。
|
||||
- 启动文件/上下文文件会被解析，并注入系统提示词报告中。
|
||||
- 会获取会话写锁；在开始流式传输之前，`SessionManager` 会被打开并完成准备。
|
||||
|
||||
## 提示词组装 + 系统提示词
|
||||
|
||||
- 系统提示词由 OpenClaw 的基础提示词、Skills 提示词、引导上下文和每次运行的覆盖项共同构建。
|
||||
- 会强制执行模型特定的限制和压缩保留 token。
|
||||
- 关于模型实际看到的内容，参见 [系统提示词](/zh-CN/concepts/system-prompt)。
|
||||
- 系统提示词由 OpenClaw 的基础提示词、Skills 提示词、启动上下文以及每次运行的覆盖项构建而成。
|
||||
- 会强制执行模型特定的限制和压缩预留 token。
|
||||
- 有关模型实际看到的内容，请参见 [系统提示词](/zh-CN/concepts/system-prompt)。
|
||||
|
||||
## Hook 点（你可以在哪里拦截）
|
||||
## Hook 点（你可以在哪些地方拦截）
|
||||
|
||||
OpenClaw 有两套 Hook 系统：
|
||||
|
||||
- **内部 Hook**（Gateway Hook）：用于命令和生命周期事件的事件驱动脚本。
|
||||
- **插件 Hook**：位于智能体/工具生命周期和 Gateway 管道内部的扩展点。
|
||||
- **内部 Hook**（Gateway 网关 Hooks）：针对命令和生命周期事件的事件驱动脚本。
|
||||
- **插件 Hook**：位于智能体/工具生命周期和 Gateway 网关流水线内部的扩展点。
|
||||
|
||||
### 内部 Hook（Gateway Hook）
|
||||
### 内部 Hook（Gateway 网关 Hooks）
|
||||
|
||||
- **`agent:bootstrap`**：在系统提示词最终确定之前、构建引导文件时运行。
|
||||
你可以用它添加/删除引导上下文文件。
|
||||
- **命令 Hook**：`/new`、`/reset`、`/stop` 以及其他命令事件（参见 Hooks 文档）。
|
||||
- **`agent:bootstrap`**：在系统提示词最终确定之前、构建启动文件时运行。
|
||||
用它来添加或删除启动上下文文件。
|
||||
- **命令 Hooks**：`/new`、`/reset`、`/stop` 和其他命令事件（参见 Hooks 文档）。
|
||||
|
||||
参见 [Hooks](/zh-CN/automation/hooks) 获取设置方式和示例。
|
||||
设置和示例请参见 [Hooks](/zh-CN/automation/hooks)。
|
||||
|
||||
### 插件 Hook（智能体 + Gateway 生命周期）
|
||||
### 插件 Hook（智能体 + Gateway 网关生命周期）
|
||||
|
||||
这些 Hook 在智能体循环或 Gateway 管道内部运行：
|
||||
这些 Hook 会在智能体循环或 Gateway 网关流水线内部运行：
|
||||
|
||||
- **`before_model_resolve`**：在会话开始前运行（无 `messages`），用于在模型解析前以确定性方式覆盖 provider/model。
|
||||
- **`before_prompt_build`**：在会话加载后运行（带 `messages`），可在提交提示词前注入 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。对每轮动态文本使用 `prependContext`；对应该位于系统提示空间中的稳定指导，使用 system-context 字段。
|
||||
- **`before_agent_start`**：遗留兼容 Hook，可能在任一阶段运行；优先使用上面这些明确的 Hook。
|
||||
- **`before_agent_reply`**：在内联动作之后、LLM 调用之前运行，允许插件接管当前轮次并返回合成回复，或完全静默该轮次。
|
||||
- **`before_model_resolve`**：在会话前运行（无 `messages`），用于在模型解析前以确定性方式覆盖提供商/模型。
|
||||
- **`before_prompt_build`**：在会话加载后运行（带有 `messages`），在提交提示词前注入 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。对每轮动态文本使用 `prependContext`，对应该位于系统提示词空间中的稳定指导使用系统上下文字段。
|
||||
- **`before_agent_start`**：用于兼容旧行为的 Hook，可能会在任一阶段运行；优先使用上面更明确的 Hook。
|
||||
- **`before_agent_reply`**：在内联操作之后、LLM 调用之前运行，使插件可以接管这一轮并返回合成回复，或完全静默这一轮。
|
||||
- **`agent_end`**：在完成后检查最终消息列表和运行元数据。
|
||||
- **`before_compaction` / `after_compaction`**：观察或标注压缩周期。
|
||||
- **`before_compaction` / `after_compaction`**：观察或注释压缩周期。
|
||||
- **`before_tool_call` / `after_tool_call`**：拦截工具参数/结果。
|
||||
- **`before_install`**：检查内置扫描结果，并可选择阻止 Skills 或插件安装。
|
||||
- **`tool_result_persist`**：在工具结果写入会话记录前同步转换结果。
|
||||
- **`message_received` / `message_sending` / `message_sent`**：入站 + 出站消息 Hook。
|
||||
- **`tool_result_persist`**：在工具结果写入会话记录前，同步转换工具结果。
|
||||
- **`message_received` / `message_sending` / `message_sent`**：入站和出站消息 Hook。
|
||||
- **`session_start` / `session_end`**：会话生命周期边界。
|
||||
- **`gateway_start` / `gateway_stop`**：Gateway 生命周期事件。
|
||||
- **`gateway_start` / `gateway_stop`**：Gateway 网关生命周期事件。
|
||||
|
||||
用于出站/工具保护的 Hook 决策规则：
|
||||
出站/工具防护的 Hook 决策规则：
|
||||
|
||||
- `before_tool_call`：`{ block: true }` 是终局决定，会阻止更低优先级的处理程序继续执行。
|
||||
- `before_tool_call`：`{ block: true }` 是终止性结果，并会阻止更低优先级的处理器继续执行。
|
||||
- `before_tool_call`：`{ block: false }` 是无操作，不会清除先前的阻止状态。
|
||||
- `before_install`：`{ block: true }` 是终局决定，会阻止更低优先级的处理程序继续执行。
|
||||
- `before_install`：`{ block: true }` 是终止性结果，并会阻止更低优先级的处理器继续执行。
|
||||
- `before_install`：`{ block: false }` 是无操作，不会清除先前的阻止状态。
|
||||
- `message_sending`：`{ cancel: true }` 是终局决定，会阻止更低优先级的处理程序继续执行。
|
||||
- `message_sending`：`{ cancel: true }` 是终止性结果，并会阻止更低优先级的处理器继续执行。
|
||||
- `message_sending`：`{ cancel: false }` 是无操作，不会清除先前的取消状态。
|
||||
|
||||
参见 [插件 Hook](/zh-CN/plugins/architecture#provider-runtime-hooks) 获取 Hook API 和注册细节。
|
||||
有关 Hook API 和注册细节，请参见 [插件 Hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
|
||||
|
||||
## 流式传输 + 部分回复
|
||||
|
||||
- assistant 增量会从 `pi-agent-core` 流式传出，并作为 `assistant` 事件发出。
|
||||
- 分块流式传输可以在 `text_end` 或 `message_end` 时发出部分回复。
|
||||
- 推理流式传输可以作为单独的流发出，也可以作为分块回复发出。
|
||||
- 关于分块和分块回复行为，参见 [流式传输](/zh-CN/concepts/streaming)。
|
||||
- 有关分块和分块回复行为，请参见 [流式传输](/zh-CN/concepts/streaming)。
|
||||
|
||||
## 工具执行 + 消息工具
|
||||
|
||||
- 工具开始/更新/结束事件会在 `tool` 流上发出。
|
||||
- 工具结果在记录/发出前会针对大小和图像负载进行清理。
|
||||
- 消息工具发送会被跟踪，以抑制重复的 assistant 确认。
|
||||
- 在记录/发出之前，工具结果会针对大小和图像负载进行清理。
|
||||
- 消息工具发送会被跟踪，以抑制重复的 assistant 确认消息。
|
||||
|
||||
## 回复整形 + 抑制
|
||||
## 回复塑形 + 抑制
|
||||
|
||||
- 最终负载由以下内容组装而成：
|
||||
- assistant 文本（以及可选的推理内容）
|
||||
- 内联工具摘要（当 `verbose` 开启且允许时）
|
||||
- 当模型出错时的 assistant 错误文本
|
||||
- 精确的静默令牌 `NO_REPLY` / `no_reply` 会从出站
|
||||
- 最终负载由以下内容组装：
|
||||
- assistant 文本（以及可选的推理）
|
||||
- 内联工具摘要（当 `verbose` 且允许时）
|
||||
- 模型报错时的 assistant 错误文本
|
||||
- 精确的静默标记 `NO_REPLY` / `no_reply` 会从出站
|
||||
负载中过滤掉。
|
||||
- 消息工具的重复内容会从最终负载列表中移除。
|
||||
- 如果没有可渲染的负载剩余且某个工具报错，则会发出一个后备工具错误回复
|
||||
- 消息工具重复项会从最终负载列表中移除。
|
||||
- 如果没有可渲染的负载剩下且某个工具报错，则会发出后备工具错误回复
|
||||
（除非某个消息工具已经发送了用户可见的回复）。
|
||||
|
||||
## 压缩 + 重试
|
||||
|
||||
- 自动压缩会发出 `compaction` 流事件，并且可能触发一次重试。
|
||||
- 在重试时，内存缓冲区和工具摘要会被重置，以避免重复输出。
|
||||
- 关于压缩管道，参见 [压缩](/zh-CN/concepts/compaction)。
|
||||
- 自动压缩会发出 `compaction` 流事件，并且可能触发重试。
|
||||
- 重试时，内存中的缓冲区和工具摘要会被重置，以避免重复输出。
|
||||
- 有关压缩流水线，请参见 [压缩](/zh-CN/concepts/compaction)。
|
||||
|
||||
## 事件流（当前）
|
||||
|
||||
- `lifecycle`：由 `subscribeEmbeddedPiSession` 发出（以及由 `agentCommand` 作为后备发出）
|
||||
- `lifecycle`：由 `subscribeEmbeddedPiSession` 发出（并由 `agentCommand` 作为后备发出）
|
||||
- `assistant`：来自 `pi-agent-core` 的流式增量
|
||||
- `tool`：来自 `pi-agent-core` 的流式工具事件
|
||||
|
||||
## 聊天渠道处理
|
||||
|
||||
- assistant 增量会被缓冲为聊天 `delta` 消息。
|
||||
- 在 **lifecycle end/error** 时会发出一个聊天 `final`。
|
||||
- 聊天 `final` 会在 **lifecycle end/error** 时发出。
|
||||
|
||||
## 超时
|
||||
|
||||
- `agent.wait` 默认值：30 秒（仅等待）。可通过 `timeoutMs` 参数覆盖。
|
||||
- 智能体运行时：`agents.defaults.timeoutSeconds` 默认值为 172800 秒（48 小时）；由 `runEmbeddedPiAgent` 中的中止计时器强制执行。
|
||||
- LLM 空闲超时：`agents.defaults.llm.idleTimeoutSeconds` 会在空闲窗口内未收到任何响应分块时中止模型请求。对于缓慢的本地模型或推理/工具调用型提供商，请显式设置它；设为 0 则禁用。如果未设置，OpenClaw 会在已配置 `agents.defaults.timeoutSeconds` 时使用该值，否则使用 120 秒。对于没有显式 LLM 或智能体超时的 cron 触发运行，会禁用空闲监视器，并依赖 cron 外层超时。
|
||||
- LLM 空闲超时：`agents.defaults.llm.idleTimeoutSeconds` 会在空闲窗口内未收到任何响应分块时中止模型请求。对于较慢的本地模型或推理/工具调用提供商，请显式设置；设为 0 可禁用。如果未设置，OpenClaw 会在已配置时使用 `agents.defaults.timeoutSeconds`，否则使用 120 秒。对于未显式设置 LLM 或智能体超时的 cron 触发运行，会禁用空闲监视器，并依赖 cron 外层超时。
|
||||
|
||||
## 可能提前结束的位置
|
||||
## 可能提前结束的情况
|
||||
|
||||
- 智能体超时（中止）
|
||||
- `AbortSignal`（取消）
|
||||
- Gateway 断开连接或 RPC 超时
|
||||
- Gateway 网关断开连接或 RPC 超时
|
||||
- `agent.wait` 超时（仅等待，不会停止智能体）
|
||||
|
||||
## 相关内容
|
||||
@ -169,5 +169,5 @@ OpenClaw 有两套 Hook 系统：
|
||||
- [工具](/zh-CN/tools) — 可用的智能体工具
|
||||
- [Hooks](/zh-CN/automation/hooks) — 由智能体生命周期事件触发的事件驱动脚本
|
||||
- [压缩](/zh-CN/concepts/compaction) — 长对话如何被总结
|
||||
- [Exec 审批](/zh-CN/tools/exec-approvals) — shell 命令的审批门控
|
||||
- [Exec 审批](/zh-CN/tools/exec-approvals) — shell 命令的审批门禁
|
||||
- [Thinking](/zh-CN/tools/thinking) — thinking/推理级别配置
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想了解在 OpenClaw 中“上下文”是什么意思
|
||||
- 你在调试为什么模型“知道”某件事（或忘记了它）
|
||||
- 你想了解 “context” 在 OpenClaw 中的含义
|
||||
- 你正在调试为什么模型“知道”某些内容（或为什么它忘记了这些内容）
|
||||
- 你想减少上下文开销（`/context`、`/status`、`/compact`）
|
||||
summary: 上下文：模型看到了什么、它是如何构建的，以及如何检查它
|
||||
summary: 上下文：模型会看到什么、它是如何构建的，以及如何检查它
|
||||
title: 上下文
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T12:42:44Z"
|
||||
generated_at: "2026-04-12T18:22:04Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a75b4cd65bf6385d46265b9ce1643310bc99d220e35ec4b4924096bed3ca4aa0
|
||||
source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d
|
||||
source_path: concepts/context.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -22,23 +22,23 @@ x-i18n:
|
||||
|
||||
- **系统提示词**（由 OpenClaw 构建）：规则、工具、Skills 列表、时间/运行时信息，以及注入的工作区文件。
|
||||
- **对话历史**：你在此会话中的消息 + 助手的消息。
|
||||
- **工具调用/结果 + 附件**：命令输出、文件读取、图像/音频等。
|
||||
- **工具调用/结果 + 附件**：命令输出、文件读取、图片/音频等。
|
||||
|
||||
上下文 _并不等同于_ “记忆”：记忆可以存储在磁盘上并在之后重新加载；上下文则是模型当前窗口中的内容。
|
||||
上下文 _不等同于_ “memory”：memory 可以存储到磁盘并在之后重新加载；上下文则是模型当前窗口中的内容。
|
||||
|
||||
## 快速开始（检查上下文）
|
||||
|
||||
- `/status` → 快速查看“你的窗口用了多少？”以及会话设置。
|
||||
- `/context list` → 查看注入了什么 + 粗略大小（每个文件 + 总计）。
|
||||
- `/context detail` → 更深入的明细：每个文件、每个工具 schema 大小、每个 skill 条目大小，以及系统提示词大小。
|
||||
- `/usage tokens` → 在普通回复后附加每条回复的用量页脚。
|
||||
- `/status` → 快速查看“我的窗口用了多少？”以及会话设置。
|
||||
- `/context list` → 查看注入了什么内容 + 大致大小（每个文件 + 总计）。
|
||||
- `/context detail` → 更深入的明细：按文件、按工具 schema 大小、按 Skills 条目大小，以及系统提示词大小。
|
||||
- `/usage tokens` → 在普通回复后追加每次回复的用量页脚。
|
||||
- `/compact` → 将较早的历史总结为一条紧凑条目，以释放窗口空间。
|
||||
|
||||
另请参阅：[Slash 命令](/zh-CN/tools/slash-commands)、[Token 使用与成本](/zh-CN/reference/token-use)、[压缩](/zh-CN/concepts/compaction)。
|
||||
另请参阅：[Slash commands](/zh-CN/tools/slash-commands)、[Token use & costs](/zh-CN/reference/token-use)、[Compaction](/zh-CN/concepts/compaction)。
|
||||
|
||||
## 示例输出
|
||||
|
||||
具体值会因模型、提供商、工具策略以及你的工作区内容而异。
|
||||
数值会因模型、提供商、工具策略以及你的工作区内容而有所不同。
|
||||
|
||||
### `/context list`
|
||||
|
||||
@ -90,22 +90,22 @@ Top tools (schema size):
|
||||
- 系统提示词（所有部分）。
|
||||
- 对话历史。
|
||||
- 工具调用 + 工具结果。
|
||||
- 附件/转录内容（图像/音频/文件）。
|
||||
- 附件/转录内容（图片/音频/文件）。
|
||||
- 压缩摘要和裁剪产物。
|
||||
- 提供商“包装层”或隐藏标头（不可见，但仍会计入）。
|
||||
- 提供商的“包装层”或隐藏头信息（你看不到，但依然计入）。
|
||||
|
||||
## OpenClaw 如何构建系统提示词
|
||||
|
||||
系统提示词由 **OpenClaw 拥有**，并会在每次运行时重新构建。它包括：
|
||||
系统提示词 **由 OpenClaw 持有**，并在每次运行时重新构建。它包括：
|
||||
|
||||
- 工具列表 + 简短说明。
|
||||
- 工具列表 + 简短描述。
|
||||
- Skills 列表（仅元数据；见下文）。
|
||||
- 工作区位置。
|
||||
- 时间（UTC + 如果已配置则转换后的用户时间）。
|
||||
- 运行时元数据（主机/OS/模型/思考设置）。
|
||||
- **Project Context** 下已注入的工作区引导文件。
|
||||
- 时间（UTC + 如果已配置则包含转换后的用户时间）。
|
||||
- 运行时元数据（主机/OS/模型/thinking）。
|
||||
- **Project Context** 下的注入工作区 bootstrap 文件。
|
||||
|
||||
完整明细参见：[系统提示词](/zh-CN/concepts/system-prompt)。
|
||||
完整细分说明请参阅：[System Prompt](/zh-CN/concepts/system-prompt)。
|
||||
|
||||
## 注入的工作区文件（Project Context）
|
||||
|
||||
@ -119,67 +119,61 @@ Top tools (schema size):
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md`（仅首次运行）
|
||||
|
||||
大文件会按文件使用 `agents.defaults.bootstrapMaxChars`（默认 `20000` 个字符）进行截断。OpenClaw 还会通过 `agents.defaults.bootstrapTotalMaxChars`（默认 `150000` 个字符）对所有文件的总引导注入量设置上限。`/context` 会显示 **原始大小与注入后大小**，以及是否发生了截断。
|
||||
大文件会按单文件通过 `agents.defaults.bootstrapMaxChars`（默认 `20000` 字符）进行截断。OpenClaw 还会对跨文件的 bootstrap 注入总量施加总上限 `agents.defaults.bootstrapTotalMaxChars`（默认 `150000` 字符）。`/context` 会显示 **原始大小与注入后大小**，以及是否发生了截断。
|
||||
|
||||
发生截断时，运行时可以在 Project Context 下方注入一个提示词内警告块。可通过 `agents.defaults.bootstrapPromptTruncationWarning` 进行配置（`off`、`once`、`always`；默认 `once`）。
|
||||
发生截断时，运行时可以在 Project Context 下方注入一个提示词内警告块。可通过 `agents.defaults.bootstrapPromptTruncationWarning` 配置此行为（`off`、`once`、`always`；默认 `once`）。
|
||||
|
||||
## Skills：默认注入 vs 按需加载
|
||||
## Skills：默认注入与按需加载
|
||||
|
||||
系统提示词包含一个精简的 **Skills 列表**（名称 + 描述 + 位置）。这个列表确实会带来开销。
|
||||
系统提示词会包含一个紧凑的 **Skills 列表**（名称 + 描述 + 位置）。这个列表本身就有实际开销。
|
||||
|
||||
Skill 指令默认 _不会_ 被包含。模型应仅在需要时通过 `read` 读取该 skill 的 `SKILL.md`。
|
||||
Skill 说明 _默认不会_ 被包含。模型应当只在需要时才使用 `read` 去读取该 Skill 的 `SKILL.md`。
|
||||
|
||||
## 工具：有两种成本
|
||||
## Tools：有两类成本
|
||||
|
||||
工具会通过两种方式影响上下文：
|
||||
Tools 会通过两种方式影响上下文：
|
||||
|
||||
1. 系统提示词中的 **工具列表文本**（你看到的 “Tooling”）。
|
||||
2. **工具 schema**（JSON）。这些内容会发送给模型，以便它调用工具。即使你看不到它们的纯文本形式，它们仍然会计入上下文。
|
||||
1. 系统提示词中的 **工具列表文本**（也就是你看到的 “Tooling”）。
|
||||
2. **工具 schema**（JSON）。这些内容会发送给模型，以便它可以调用工具。即使你看不到其纯文本形式，它们依然会计入上下文。
|
||||
|
||||
`/context detail` 会拆解最大的工具 schema，以便你查看主要开销来源。
|
||||
`/context detail` 会拆分显示最大的工具 schema，这样你就能看出主要开销来自哪里。
|
||||
|
||||
## 命令、指令和“内联快捷方式”
|
||||
|
||||
Slash 命令由 Gateway 网关 处理。这里有几种不同的行为：
|
||||
Slash commands 由 Gateway 网关处理。这里有几种不同的行为：
|
||||
|
||||
- **独立命令**：如果一条消息只有 `/...`，它会作为命令执行。
|
||||
- **指令**：`/think`、`/verbose`、`/reasoning`、`/elevated`、`/model`、`/queue` 会在模型看到消息之前被剥离。
|
||||
- 仅包含指令的消息会持久化会话设置。
|
||||
- **独立命令**：如果一条消息只有 `/...`，它会作为命令运行。
|
||||
- **指令**：`/think`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/model`、`/queue` 会在模型看到消息之前被剥离。
|
||||
- 只有指令的消息会持久化会话设置。
|
||||
- 普通消息中的内联指令会作为单条消息级别的提示。
|
||||
- **内联快捷方式**（仅限 allowlist 发送者）：普通消息中的某些 `/...` token 可以立即执行（例如：“hey /status”），并会在模型看到剩余文本之前被剥离。
|
||||
|
||||
详情参见：[Slash 命令](/zh-CN/tools/slash-commands)。
|
||||
详情请参阅：[Slash commands](/zh-CN/tools/slash-commands)。
|
||||
|
||||
## 会话、压缩和裁剪（哪些内容会持久化）
|
||||
## 会话、压缩与裁剪（哪些内容会持久化）
|
||||
|
||||
跨消息持久化哪些内容，取决于具体机制：
|
||||
|
||||
- **普通历史** 会持久保留在会话转录中，直到被策略压缩/裁剪。
|
||||
- **压缩** 会将摘要持久写入转录，并保留最近的消息不变。
|
||||
- **裁剪** 会从某次运行的 _内存中_ 提示词里移除旧的工具结果，但不会重写转录。
|
||||
- **普通历史** 会持久保存在会话转录中，直到按策略被压缩/裁剪。
|
||||
- **压缩** 会把摘要持久化到转录中，并保留最近的消息。
|
||||
- **裁剪** 会从某次运行的 _内存中_ 提示词里移除较旧的工具结果，但不会改写转录。
|
||||
|
||||
文档参见：[会话](/zh-CN/concepts/session)、[压缩](/zh-CN/concepts/compaction)、[会话裁剪](/zh-CN/concepts/session-pruning)。
|
||||
文档： [Session](/zh-CN/concepts/session)、[Compaction](/zh-CN/concepts/compaction)、[Session pruning](/zh-CN/concepts/session-pruning)。
|
||||
|
||||
默认情况下，OpenClaw 使用内置的 `legacy` 上下文引擎来进行组装和
|
||||
压缩。如果你安装了一个提供 `kind: "context-engine"` 的插件，并通过
|
||||
`plugins.slots.contextEngine` 选择它，OpenClaw 就会将上下文组装、`/compact`
|
||||
以及相关的子智能体上下文生命周期钩子委托给该引擎。`ownsCompaction: false`
|
||||
不会自动回退到 legacy 引擎；活动引擎仍必须正确实现 `compact()`。完整的
|
||||
可插拔接口、生命周期钩子和配置参见
|
||||
[Context Engine](/zh-CN/concepts/context-engine)。
|
||||
默认情况下，OpenClaw 使用内置的 `legacy` 上下文引擎来进行组装和压缩。如果你安装了一个提供 `kind: "context-engine"` 的插件，并通过 `plugins.slots.contextEngine` 选择它，OpenClaw 就会把上下文组装、`/compact` 以及相关的 subagent 上下文生命周期 hook 委托给该引擎。`ownsCompaction: false` 不会自动回退到 legacy 引擎；当前激活的引擎仍必须正确实现 `compact()`。完整的可插拔接口、生命周期 hook 和配置请参阅 [Context Engine](/zh-CN/concepts/context-engine)。
|
||||
|
||||
## `/context` 实际报告的是什么
|
||||
|
||||
`/context` 在可用时会优先使用最新的 **按运行构建** 的系统提示词报告：
|
||||
在可用时，`/context` 会优先使用最新的 **运行时已构建** 系统提示词报告：
|
||||
|
||||
- `System prompt (run)` = 从上一次嵌入式（支持工具）运行中捕获，并持久保存到会话存储中。
|
||||
- `System prompt (estimate)` = 当不存在运行报告时即时计算（或在使用不会生成该报告的 CLI 后端运行时计算）。
|
||||
- `System prompt (run)` = 从上一次嵌入式（支持工具）运行中捕获，并持久化在会话存储中。
|
||||
- `System prompt (estimate)` = 当不存在运行报告时动态计算得出（或者在使用不会生成该报告的 CLI 后端运行时）。
|
||||
|
||||
无论哪种方式，它报告的都是大小和主要贡献项；它 **不会** 转储完整的系统提示词或工具 schema。
|
||||
无论哪种方式，它都会报告大小和主要贡献项；它 **不会** 输出完整的系统提示词或工具 schema。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [Context Engine](/zh-CN/concepts/context-engine) — 通过插件进行自定义上下文注入
|
||||
- [压缩](/zh-CN/concepts/compaction) — 总结长对话
|
||||
- [系统提示词](/zh-CN/concepts/system-prompt) — 系统提示词的构建方式
|
||||
- [智能体循环](/zh-CN/concepts/agent-loop) — 完整的智能体执行周期
|
||||
- [Compaction](/zh-CN/concepts/compaction) — 总结长对话
|
||||
- [System Prompt](/zh-CN/concepts/system-prompt) — 系统提示词是如何构建的
|
||||
- [Agent Loop](/zh-CN/concepts/agent-loop) — 完整的智能体执行循环
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要检查原始模型输出中的推理泄漏
|
||||
- 你需要检查原始模型输出，以排查推理泄漏
|
||||
- 你想在迭代时以监视模式运行 Gateway 网关
|
||||
- 你需要一个可重复的调试工作流
|
||||
summary: 调试工具：监视模式、原始模型流，以及推理泄漏追踪
|
||||
title: 调试
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T22:30:00Z"
|
||||
generated_at: "2026-04-12T18:22:07Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4bc72e8d6cad3a1acaad066f381c82309583fabf304c589e63885f2685dc704e
|
||||
source_hash: bc31ce9b41e92a14c4309f32df569b7050b18024f83280930e53714d3bfcd5cc
|
||||
source_path: help/debugging.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 调试
|
||||
|
||||
本页介绍了用于流式输出的调试辅助工具，尤其适用于提供商将推理内容混入普通文本的情况。
|
||||
本页介绍用于流式输出的调试辅助工具，尤其适用于提供商将推理内容混入普通文本时的情况。
|
||||
|
||||
## 运行时调试覆盖
|
||||
|
||||
在聊天中使用 `/debug` 设置**仅运行时**的配置覆盖（保存在内存中，而非磁盘）。
|
||||
`/debug` 默认禁用；使用 `commands.debug: true` 启用。
|
||||
当你需要切换一些不常用设置，而又不想编辑 `openclaw.json` 时，这会很方便。
|
||||
在聊天中使用 `/debug` 来设置**仅运行时**的配置覆盖（存储在内存中，而不是磁盘）。
|
||||
`/debug` 默认禁用；可通过 `commands.debug: true` 启用。
|
||||
当你需要切换一些较少使用的设置，而不想编辑 `openclaw.json` 时，这会很方便。
|
||||
|
||||
示例：
|
||||
|
||||
@ -33,34 +33,49 @@ x-i18n:
|
||||
/debug reset
|
||||
```
|
||||
|
||||
`/debug reset` 会清除所有覆盖，并恢复到磁盘上的配置。
|
||||
`/debug reset` 会清除所有覆盖，并恢复为磁盘上的配置。
|
||||
|
||||
## 会话追踪输出
|
||||
|
||||
当你想在单个会话中查看插件拥有的追踪/调试行，而不启用完整详细模式时，请使用 `/trace`。
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
/trace
|
||||
/trace on
|
||||
/trace off
|
||||
```
|
||||
|
||||
将 `/trace` 用于插件诊断，例如 Active Memory 调试摘要。
|
||||
对于常规的详细状态/工具输出，继续使用 `/verbose`；对于仅运行时的配置覆盖，继续使用 `/debug`。
|
||||
|
||||
## Gateway 网关监视模式
|
||||
|
||||
为了快速迭代，可在文件监视器下运行 Gateway 网关：
|
||||
为了快速迭代，请在文件监视器下运行 Gateway 网关：
|
||||
|
||||
```bash
|
||||
pnpm gateway:watch
|
||||
```
|
||||
|
||||
它映射到：
|
||||
这对应于：
|
||||
|
||||
```bash
|
||||
node scripts/watch-node.mjs gateway --force
|
||||
```
|
||||
|
||||
监视器会在 `src/` 下与构建相关的文件、扩展源码文件、扩展的 `package.json` 和 `openclaw.plugin.json` 元数据、`tsconfig.json`、`package.json` 以及 `tsdown.config.ts` 发生变化时重启。
|
||||
监视器会在 `src/` 下与构建相关的文件、扩展源码文件、扩展的 `package.json` 和 `openclaw.plugin.json` 元数据、`tsconfig.json`、`package.json` 以及 `tsdown.config.ts` 发生变更时重启。
|
||||
扩展元数据变更会在不强制执行 `tsdown` 重建的情况下重启 Gateway 网关；源码和配置变更仍会先重建 `dist`。
|
||||
|
||||
在 `gateway:watch` 之后添加任何 Gateway 网关 CLI 标志，它们都会在每次重启时透传。
|
||||
现在，对于同一仓库和相同标志组合，重复运行相同的监视命令会替换旧的监视器，而不会留下重复的监视器父进程。
|
||||
在 `gateway:watch` 后添加任何 Gateway 网关 CLI 标志，它们都会在每次重启时透传。
|
||||
现在，对于同一仓库/标志组合重复运行相同的监视命令时，会替换旧的监视器，而不是留下重复的监视器父进程。
|
||||
|
||||
## 开发配置文件 + 开发 Gateway 网关（`--dev`）
|
||||
|
||||
使用开发配置文件来隔离状态，并为调试启动一个安全、可随时丢弃的环境。这里有**两个** `--dev` 标志：
|
||||
使用开发配置文件来隔离状态，并为调试启动一个安全、可丢弃的环境。这里有**两个** `--dev` 标志：
|
||||
|
||||
- **全局 `--dev`（配置文件）：** 将状态隔离到 `~/.openclaw-dev` 下，并将 Gateway 网关端口默认设为 `19001`（派生端口也会随之变化）。
|
||||
- **`gateway --dev`：** 告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区**（并跳过 BOOTSTRAP.md）**。
|
||||
- **全局 `--dev`（配置文件）：** 将状态隔离到 `~/.openclaw-dev` 下，并将 Gateway 网关端口默认为 `19001`（派生端口也会随之变化）。
|
||||
- **`gateway --dev`：** 告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区（并跳过 `BOOTSTRAP.md`）。
|
||||
|
||||
推荐流程（开发配置文件 + 开发引导）：
|
||||
|
||||
@ -71,21 +86,21 @@ OPENCLAW_PROFILE=dev openclaw tui
|
||||
|
||||
如果你还没有全局安装，请通过 `pnpm openclaw ...` 运行 CLI。
|
||||
|
||||
它会执行以下操作：
|
||||
具体作用如下：
|
||||
|
||||
1. **配置文件隔离**（全局 `--dev`）
|
||||
- `OPENCLAW_PROFILE=dev`
|
||||
- `OPENCLAW_STATE_DIR=~/.openclaw-dev`
|
||||
- `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
|
||||
- `OPENCLAW_GATEWAY_PORT=19001`（浏览器/canvas 端口也会相应变化）
|
||||
- `OPENCLAW_GATEWAY_PORT=19001`（browser/canvas 端口也会相应变化）
|
||||
|
||||
2. **开发引导**（`gateway --dev`）
|
||||
- 如果缺失则写入最小化配置（`gateway.mode=local`，绑定到 loopback）。
|
||||
- 将 `agent.workspace` 设为开发工作区。
|
||||
- 设置 `agent.skipBootstrap=true`（不使用 BOOTSTRAP.md）。
|
||||
- 如果缺失，则为工作区填充以下文件：
|
||||
- 如果缺失，则写入最小配置（`gateway.mode=local`，绑定到 loopback）。
|
||||
- 将 `agent.workspace` 设置为开发工作区。
|
||||
- 设置 `agent.skipBootstrap=true`（不使用 `BOOTSTRAP.md`）。
|
||||
- 如果缺失，则为工作区填充这些文件：
|
||||
`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`。
|
||||
- 默认身份：**C3‑PO**（礼仪机器人）。
|
||||
- 默认身份：**C3‑PO**（协议机器人）。
|
||||
- 在开发模式下跳过渠道提供商（`OPENCLAW_SKIP_CHANNELS=1`）。
|
||||
|
||||
重置流程（全新开始）：
|
||||
@ -94,16 +109,16 @@ OPENCLAW_PROFILE=dev openclaw tui
|
||||
pnpm gateway:dev:reset
|
||||
```
|
||||
|
||||
注意：`--dev` 是一个**全局**配置文件标志，有些运行器会吞掉它。
|
||||
如果你需要显式写出它，请使用环境变量形式：
|
||||
注意：`--dev` 是一个**全局**配置文件标志，某些运行器会吞掉它。
|
||||
如果你需要明确写出来，请使用环境变量形式：
|
||||
|
||||
```bash
|
||||
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
|
||||
```
|
||||
|
||||
`--reset` 会清除配置、凭证、会话以及开发工作区（使用 `trash`，而不是 `rm`），然后重新创建默认的开发环境。
|
||||
`--reset` 会清除配置、凭证、会话和开发工作区（使用 `trash`，而不是 `rm`），然后重新创建默认的开发环境。
|
||||
|
||||
提示：如果一个非开发模式的 Gateway 网关已经在运行（`launchd`/`systemd`），请先停止它：
|
||||
提示：如果一个非开发 Gateway 网关已经在运行（launchd/systemd），请先停止它：
|
||||
|
||||
```bash
|
||||
openclaw gateway stop
|
||||
@ -112,7 +127,7 @@ openclaw gateway stop
|
||||
## 原始流日志（OpenClaw）
|
||||
|
||||
OpenClaw 可以在任何过滤/格式化之前记录**原始 assistant 流**。
|
||||
这是查看推理内容是否以纯文本增量形式到达（或作为独立 thinking 块到达）的最佳方式。
|
||||
这是查看推理内容是否作为纯文本增量到达（或作为单独的 thinking 块到达）的最佳方式。
|
||||
|
||||
通过 CLI 启用：
|
||||
|
||||
@ -126,7 +141,7 @@ pnpm gateway:watch --raw-stream
|
||||
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
|
||||
```
|
||||
|
||||
等价的环境变量：
|
||||
等效环境变量：
|
||||
|
||||
```bash
|
||||
OPENCLAW_RAW_STREAM=1
|
||||
@ -139,7 +154,7 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
|
||||
|
||||
## 原始分块日志（pi-mono）
|
||||
|
||||
要在块被解析之前捕获**原始 OpenAI 兼容分块**，pi-mono 提供了一个单独的日志记录器：
|
||||
要在解析为块之前捕获**原始 OpenAI-compat 分块**，pi-mono 提供了一个单独的日志记录器：
|
||||
|
||||
```bash
|
||||
PI_RAW_STREAM=1
|
||||
@ -162,4 +177,4 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
|
||||
|
||||
- 原始流日志可能包含完整提示词、工具输出和用户数据。
|
||||
- 请将日志保留在本地，并在调试后删除。
|
||||
- 如果你要分享日志，请先清除密钥和个人身份信息（PII）。
|
||||
- 如果你要共享日志，请先清理其中的密钥和个人身份信息。
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -5,31 +5,32 @@ read_when:
|
||||
summary: 斜杠命令：文本与原生、配置，以及支持的命令
|
||||
title: 斜杠命令
|
||||
x-i18n:
|
||||
generated_at: "2026-04-10T21:20:39Z"
|
||||
generated_at: "2026-04-12T18:22:04Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2cc346361c3b1a63aae9ec0f28706f4cb0b866b6c858a3999101f6927b923b4a
|
||||
source_hash: 9ef6f54500fa2ce3b873a8398d6179a0882b8bf6fba38f61146c64671055505e
|
||||
source_path: tools/slash-commands.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 斜杠命令
|
||||
|
||||
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。
|
||||
仅限主机的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是其别名）。
|
||||
命令由 Gateway 网关处理。大多数命令必须作为**独立**消息发送，并且以 `/` 开头。
|
||||
仅主机可用的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是它的别名）。
|
||||
|
||||
这里有两个相关系统：
|
||||
|
||||
- **命令**：独立的 `/...` 消息。
|
||||
- **指令**：`/think`、`/fast`、`/verbose`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
|
||||
- 指令会在模型看到消息之前被剥离。
|
||||
- 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“内联提示”，**不会**持久化会话设置。
|
||||
- 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话，并回复一条确认信息。
|
||||
- 指令只会对**已授权的发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来源于渠道允许列表/配对以及 `commands.useAccessGroups`。
|
||||
未授权的发送者会看到指令被当作普通文本处理。
|
||||
- **指令**：`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
|
||||
- 在模型看到消息之前，指令会从消息中剥离。
|
||||
- 在普通聊天消息中（不是纯指令消息），它们会被当作“内联提示”，并且**不会**持久化为会话设置。
|
||||
- 在纯指令消息中（消息只包含指令），它们会持久化到会话，并回复一条确认信息。
|
||||
- 指令仅对**已授权的发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的
|
||||
允许列表；否则，授权来源于渠道允许列表/配对以及 `commands.useAccessGroups`。
|
||||
未授权的发送者会看到这些指令被当作普通文本处理。
|
||||
|
||||
还有一些**内联快捷方式**（仅限允许列表/已授权发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
它们会立即运行，在模型看到消息前被剥离，剩余文本会继续走正常流程。
|
||||
还有一些**内联快捷命令**（仅限已列入允许列表/已授权的发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
它们会立即运行，在模型看到消息之前被剥离，其余文本则继续按正常流程处理。
|
||||
|
||||
## 配置
|
||||
|
||||
@ -61,23 +62,24 @@ x-i18n:
|
||||
- `commands.text`（默认 `true`）启用在聊天消息中解析 `/...`。
|
||||
- 在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设为 `false`，文本命令仍然可用。
|
||||
- `commands.native`（默认 `"auto"`）注册原生命令。
|
||||
- Auto：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加 slash commands）；对不支持原生能力的提供商忽略。
|
||||
- 自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对于不支持原生命令的提供商则忽略。
|
||||
- 设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。
|
||||
- `false` 会在启动时清除之前在 Discord/Telegram 上注册的命令。Slack 命令由 Slack 应用管理，不会被自动移除。
|
||||
- `false` 会在启动时清除之前在 Discord/Telegram 上注册的命令。Slack 命令由 Slack 应用管理，不会自动移除。
|
||||
- `commands.nativeSkills`（默认 `"auto"`）在支持时以原生方式注册 **skill** 命令。
|
||||
- Auto：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 创建一个 slash command）。
|
||||
- 自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。
|
||||
- 设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
|
||||
- `commands.bash`（默认 `false`）启用 `! <cmd>` 以运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
|
||||
- `commands.bashForegroundMs`（默认 `2000`）控制 bash 在切换到后台模式前等待多久（`0` 表示立即转入后台）。
|
||||
- `commands.config`（默认 `false`）启用 `/config`（读取/写入 `openclaw.json`）。
|
||||
- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。
|
||||
- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入 OpenClaw 管理的 `mcp.servers` 下的 MCP 配置）。
|
||||
- `commands.plugins`（默认 `false`）启用 `/plugins`（插件发现/状态，以及安装 + 启用/禁用控制）。
|
||||
- `commands.debug`（默认 `false`）启用 `/debug`（仅运行时覆盖）。
|
||||
- `commands.restart`（默认 `true`）启用 `/restart` 以及 Gateway 网关重启工具操作。
|
||||
- `commands.ownerAllowFrom`（可选）为仅限所有者的命令/工具界面设置显式所有者允许列表。这与 `commands.allowFrom` 分开。
|
||||
- `commands.ownerDisplay` 控制系统提示中所有者 id 的显示方式：`raw` 或 `hash`。
|
||||
- `commands.ownerDisplaySecret` 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
|
||||
- `commands.allowFrom`（可选）为命令授权设置按提供商划分的允许列表。配置后，它会成为命令和指令的唯一授权来源（渠道允许列表/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。
|
||||
- `commands.ownerDisplaySecret` 可选地设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
|
||||
- `commands.allowFrom`（可选）为命令授权设置按提供商划分的允许列表。配置后，它将成为命令和指令的
|
||||
唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商专用键会覆盖它。
|
||||
- `commands.useAccessGroups`（默认 `true`）在未设置 `commands.allowFrom` 时，对命令强制执行允许列表/策略。
|
||||
|
||||
## 命令列表
|
||||
@ -93,50 +95,51 @@ x-i18n:
|
||||
|
||||
当前可用的内置命令：
|
||||
|
||||
- `/new [model]` 启动一个新会话；`/reset` 是重置别名。
|
||||
- `/new [model]` 启动新会话；`/reset` 是重置别名。
|
||||
- `/compact [instructions]` 压缩会话上下文。参见 [/concepts/compaction](/zh-CN/concepts/compaction)。
|
||||
- `/stop` 中止当前运行。
|
||||
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期时间。
|
||||
- `/think <off|minimal|low|medium|high|xhigh>` 设置思考级别。别名：`/thinking`、`/t`。
|
||||
- `/verbose on|off|full` 切换详细输出。别名：`/v`。
|
||||
- `/trace on|off` 为当前会话切换插件追踪输出。
|
||||
- `/fast [status|on|off]` 显示或设置快速模式。
|
||||
- `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。
|
||||
- `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 显示或设置 exec 默认值。
|
||||
- `/model [name|#|status]` 显示或设置模型。
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商，或列出某个提供商的模型。
|
||||
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及如 `debounce:2s cap:25 drop:summarize` 等选项。
|
||||
- `/help` 显示简短帮助摘要。
|
||||
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及 `debounce:2s cap:25 drop:summarize` 之类的选项。
|
||||
- `/help` 显示简要帮助摘要。
|
||||
- `/commands` 显示生成的命令目录。
|
||||
- `/tools [compact|verbose]` 显示当前智能体此刻可用的内容。
|
||||
- `/tools [compact|verbose]` 显示当前智能体此刻可以使用的内容。
|
||||
- `/status` 显示运行时状态，包括可用时的提供商使用量/配额。
|
||||
- `/tasks` 列出当前会话的活跃/最近后台任务。
|
||||
- `/tasks` 列出当前会话中活跃/最近的后台任务。
|
||||
- `/context [list|detail|json]` 说明上下文是如何组装的。
|
||||
- `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。
|
||||
- `/whoami` 显示你的发送者 id。别名：`/id`。
|
||||
- `/skill <name> [input]` 按名称运行一个 skill。
|
||||
- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。
|
||||
- `/approve <id> <decision>` 处理 exec 审批提示。
|
||||
- `/btw <question>` 提一个侧边问题，而不改变未来会话上下文。参见 [/tools/btw](/zh-CN/tools/btw)。
|
||||
- `/btw <question>` 在不改变未来会话上下文的情况下提出一个旁支问题。参见 [/tools/btw](/zh-CN/tools/btw)。
|
||||
- `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。
|
||||
- `/focus <target>` 将当前 Discord 线程或 Telegram 话题/会话绑定到一个会话目标。
|
||||
- `/unfocus` 移除当前绑定。
|
||||
- `/agents` 列出当前会话中线程绑定的智能体。
|
||||
- `/kill <id|#|all>` 中止一个或全部正在运行的子智能体。
|
||||
- `/agents` 列出当前会话中绑定到线程的智能体。
|
||||
- `/kill <id|#|all>` 中止一个或所有正在运行的子智能体。
|
||||
- `/steer <id|#> <message>` 向正在运行的子智能体发送引导。别名：`/tell`。
|
||||
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。
|
||||
- `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。
|
||||
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅所有者。需要 `commands.config: true`。
|
||||
- `/mcp show|get|set|unset` 读取或写入 OpenClaw 管理的 `mcp.servers` 下的 MCP 服务器配置。仅所有者。需要 `commands.mcp: true`。
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` 检查或修改插件状态。`/plugin` 是别名。写操作仅限所有者。需要 `commands.plugins: true`。
|
||||
- `/debug show|set|unset|reset` 管理仅运行时配置覆盖。仅限所有者。需要 `commands.debug: true`。
|
||||
- `/usage off|tokens|full|cost` 控制每次响应的使用量页脚，或打印本地成本摘要。
|
||||
- `/debug show|set|unset|reset` 管理仅运行时配置覆盖。仅所有者。需要 `commands.debug: true`。
|
||||
- `/usage off|tokens|full|cost` 控制每次响应的使用量页脚，或输出本地成本摘要。
|
||||
- `/tts on|off|status|provider|limit|summary|audio|help` 控制 TTS。参见 [/tools/tts](/zh-CN/tools/tts)。
|
||||
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用。
|
||||
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用它。
|
||||
- `/activation mention|always` 设置群组激活模式。
|
||||
- `/send on|off|inherit` 设置发送策略。仅限所有者。
|
||||
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true`，并且需要 `tools.elevated` 允许列表。
|
||||
- `!poll [sessionId]` 检查一个后台 bash 作业。
|
||||
- `!stop [sessionId]` 停止一个后台 bash 作业。
|
||||
- `/send on|off|inherit` 设置发送策略。仅所有者。
|
||||
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。
|
||||
- `!poll [sessionId]` 检查后台 bash 作业。
|
||||
- `!stop [sessionId]` 停止后台 bash 作业。
|
||||
|
||||
### 生成的 dock 命令
|
||||
|
||||
@ -151,13 +154,13 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
|
||||
内置插件可以添加更多斜杠命令。此仓库中当前的内置命令：
|
||||
|
||||
- `/dreaming [on|off|status|help]` 切换记忆 dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
|
||||
- `/dreaming [on|off|status|help]` 切换 memory dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [Pairing](/zh-CN/channels/pairing)。
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时启用高风险手机节点命令。
|
||||
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。
|
||||
- `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置 Codex app-server harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
|
||||
- 仅限 QQ Bot 的命令：
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置的 Codex 应用服务器 harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
|
||||
- 仅 QQ Bot 命令：
|
||||
- `/bot-ping`
|
||||
- `/bot-version`
|
||||
- `/bot-help`
|
||||
@ -166,66 +169,71 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
|
||||
### 动态 skill 命令
|
||||
|
||||
用户可调用的 Skills 也会作为斜杠命令暴露：
|
||||
用户可调用的 Skills 也会作为斜杠命令公开：
|
||||
|
||||
- `/skill <name> [input]` 始终可用，作为通用入口点。
|
||||
- 当 skill/插件注册它们时，Skills 也可能作为直接命令出现，例如 `/prose`。
|
||||
- `/skill <name> [input]` 始终可作为通用入口点使用。
|
||||
- 当 skill/插件注册它们时，skills 也可能显示为直接命令，例如 `/prose`。
|
||||
- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
|
||||
|
||||
说明：
|
||||
注意：
|
||||
|
||||
- 命令支持在命令与参数之间可选添加 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
|
||||
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，该文本会被视为消息正文。
|
||||
- 如需完整的提供商使用量明细，请使用 `openclaw status --usage`。
|
||||
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。
|
||||
- 命令支持在命令与参数之间可选使用 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
|
||||
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。
|
||||
- 要查看完整的提供商使用量细分，请使用 `openclaw status --usage`。
|
||||
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道的 `configWrites`。
|
||||
- 在多账号渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账号的 `configWrites`。
|
||||
- `/usage` 控制每次响应的使用量页脚；`/usage cost` 会根据 OpenClaw 会话日志输出本地成本摘要。
|
||||
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用。
|
||||
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/压缩包、npm 包，或 `clawhub:<pkg>`。
|
||||
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。
|
||||
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包或 `clawhub:<pkg>`。
|
||||
- `/plugins enable|disable` 会更新插件配置，并且可能提示你重启。
|
||||
- 仅限 Discord 的原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。
|
||||
- 仅 Discord 原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。
|
||||
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求有效启用线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
|
||||
- ACP 命令参考和运行时行为： [ACP Agents](/zh-CN/tools/acp-agents)。
|
||||
- `/verbose` 用于调试和额外可见性；在正常使用中请保持其为**关闭**。
|
||||
- `/fast on|off` 会持久化一个会话级覆盖。使用 Sessions UI 的 `inherit` 选项可清除它，并回退到配置默认值。
|
||||
- `/fast` 具有提供商特异性：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射为 `service_tier=priority`，而直接发送到 `api.anthropic.com` 的公开 Anthropic 请求（包括使用 OAuth 身份验证的流量）会将其映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
|
||||
- 工具失败摘要在相关时仍会显示，但详细失败文本仅在 `/verbose` 为 `on` 或 `full` 时才会包含。
|
||||
- `/reasoning`（以及 `/verbose`）在群组环境中存在风险：它们可能暴露你原本不打算公开的内部推理或工具输出。建议保持关闭，尤其是在群聊中。
|
||||
- `/verbose` 主要用于调试和额外可见性；正常使用时请保持**关闭**。
|
||||
- `/trace` 比 `/verbose` 更窄：它只显示插件自有的追踪/调试行，并保持普通的详细工具输出关闭。
|
||||
- `/fast on|off` 会持久化一个会话覆盖。使用 Sessions UI 的 `inherit` 选项可清除它，并回退到配置默认值。
|
||||
- `/fast` 是提供商相关的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射为 `service_tier=priority`，而直接发送到 `api.anthropic.com` 的公开 Anthropic 请求（包括通过 OAuth 认证的流量）会将其映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
|
||||
- 相关时仍会显示工具失败摘要，但详细失败文本仅在 `/verbose` 为 `on` 或 `full` 时包含。
|
||||
- `/reasoning`、`/verbose` 和 `/trace` 在群组环境中存在风险：它们可能暴露你原本无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。
|
||||
- `/model` 会立即持久化新的会话模型。
|
||||
- 如果智能体处于空闲状态，下一次运行会立即使用它。
|
||||
- 如果已有运行处于活跃状态，OpenClaw 会将实时切换标记为待处理，并且只会在一个干净的重试点重启到新模型。
|
||||
- 如果工具活动或回复输出已经开始，待处理切换可能会保持排队状态，直到后续重试机会或下一次用户回合。
|
||||
- **快速路径：** 来自允许列表发送者的纯命令消息会被立即处理（绕过队列 + 模型）。
|
||||
- 如果智能体空闲，下一次运行会立即使用它。
|
||||
- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在一个干净的重试点重启到新模型。
|
||||
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队到之后的重试机会，或直到用户下一轮输入。
|
||||
- **快速路径：** 来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。
|
||||
- **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。
|
||||
- **内联快捷方式（仅限允许列表发送者）：** 某些命令在嵌入普通消息时也可生效，并会在模型看到剩余文本前被剥离。
|
||||
- 示例：`hey /status` 会触发状态回复，剩余文本继续走正常流程。
|
||||
- **内联快捷命令（仅限允许列表发送者）：** 某些命令嵌入普通消息中时也可生效，并且会在模型看到其余文本之前被剥离。
|
||||
- 示例：`hey /status` 会触发一条状态回复，其余文本则继续按正常流程处理。
|
||||
- 当前包括：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
- 未授权的纯命令消息会被静默忽略，而内联 `/...` 标记会被视为普通文本。
|
||||
- **skill 命令：** `user-invocable` 的 Skills 也会作为斜杠命令暴露。名称会被清洗为 `a-z0-9_`（最多 32 个字符）；冲突时会添加数字后缀（例如 `_2`）。
|
||||
- `/skill <name> [input]` 按名称运行一个 skill（当原生命令限制阻止为每个 skill 创建单独命令时，这很有用）。
|
||||
- 未授权的纯命令消息会被静默忽略，而内联 `/...` 标记会被当作普通文本处理。
|
||||
- **skill 命令：** `user-invocable` Skills 会公开为斜杠命令。名称会被规范化为 `a-z0-9_`（最长 32 个字符）；冲突时会附加数字后缀（例如 `_2`）。
|
||||
- `/skill <name> [input]` 按名称运行一个 skill（当原生命令限制阻止按 skill 单独创建命令时，这很有用）。
|
||||
- 默认情况下，skill 命令会作为普通请求转发给模型。
|
||||
- Skills 可选择声明 `command-dispatch: tool`，以将命令直接路由到工具（确定性，无需模型）。
|
||||
- Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到某个工具（确定性、无模型）。
|
||||
- 示例：`/prose`（OpenProse 插件）——参见 [OpenProse](/zh-CN/prose)。
|
||||
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时，也会使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。
|
||||
- **原生命令参数：** Discord 对动态选项使用自动补全（省略必填参数时也会显示按钮菜单）。Telegram 和 Slack 在某个命令支持选项且你省略该参数时，会显示按钮菜单。
|
||||
|
||||
## `/tools`
|
||||
|
||||
`/tools` 回答的是一个运行时问题，而不是一个配置问题：**这个智能体现在在这段对话中可以使用什么**。
|
||||
`/tools` 回答的是一个运行时问题，而不是配置问题：**这个智能体现在在
|
||||
这个会话中能使用什么**。
|
||||
|
||||
- 默认的 `/tools` 是紧凑模式，并针对快速浏览进行了优化。
|
||||
- 默认的 `/tools` 是紧凑模式，针对快速浏览进行了优化。
|
||||
- `/tools verbose` 会添加简短说明。
|
||||
- 支持参数的原生命令界面也会暴露相同的模式切换：`compact|verbose`。
|
||||
- 结果是作用于会话范围的，因此更改智能体、渠道、线程、发送者授权或模型，都可能改变输出。
|
||||
- `/tools` 包括在运行时实际可达的工具，包括核心工具、已连接的插件工具和渠道自有工具。
|
||||
- 支持参数的原生命令界面会公开相同的模式切换，即 `compact|verbose`。
|
||||
- 结果是按会话范围限定的，因此更换智能体、渠道、线程、发送者授权或模型都可能
|
||||
改变输出。
|
||||
- `/tools` 包含在运行时实际可达的工具，包括核心工具、已连接的
|
||||
插件工具，以及渠道自有工具。
|
||||
|
||||
如需编辑 profile 和 override，请使用 Control UI Tools 面板或配置/目录界面，而不要把 `/tools` 当作静态目录。
|
||||
如需编辑 profile 和覆盖项，请使用 Control UI Tools 面板或配置/目录界面，而不要
|
||||
将 `/tools` 视为静态目录。
|
||||
|
||||
## 使用量界面（哪些内容显示在哪里）
|
||||
## 使用量界面（各处显示内容）
|
||||
|
||||
- **提供商使用量/配额**（例如“Claude 剩余 80%”）会在启用使用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一为“剩余百分比”；对于 MiniMax，仅提供剩余百分比字段时会在显示前取反，而 `model_remains` 响应会优先选择 chat-model 条目以及带模型标签的套餐标签。
|
||||
- `/status` 中的**令牌/缓存行**，在实时会话快照内容较少时，可以回退到最近一次转录使用量条目。现有的非零实时值仍然优先，且当存储总量缺失或更小时，转录回退还可以恢复当前活跃运行时模型标签以及一个更大的、面向提示词的总量。
|
||||
- **每次响应的令牌/成本** 由 `/usage off|tokens|full` 控制（附加到正常回复后）。
|
||||
- `/model status` 关注的是**模型/认证/端点**，而不是使用量。
|
||||
- **提供商使用量/配额**（例如：“Claude 剩余 80%”）会在启用使用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一规范为“剩余 %”；对于 MiniMax，仅剩余百分比字段会在显示前反转，而 `model_remains` 响应会优先使用聊天模型条目以及带模型标签的套餐标签。
|
||||
- `/status` 中的**令牌/缓存行**在实时会话快照信息不足时，可以回退到最近的转录使用量条目。现有的非零实时值仍然优先，转录回退还可以在已存储总量缺失或更小时，恢复当前活动运行时模型标签以及一个更偏向提示词的更大总量。
|
||||
- **每次响应的令牌/成本** 由 `/usage off|tokens|full` 控制（附加在普通回复后）。
|
||||
- `/model status` 关注的是**模型/凭证/端点**，而不是使用量。
|
||||
|
||||
## 模型选择（`/model`）
|
||||
|
||||
@ -244,14 +252,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
|
||||
说明：
|
||||
|
||||
- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型家族 + 可用提供商）。
|
||||
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个提交步骤。
|
||||
- `/model <#>` 会从该选择器中进行选择（并尽可能优先当前提供商）。
|
||||
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用。
|
||||
- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型系列 + 可用提供商）。
|
||||
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单以及提交步骤。
|
||||
- `/model <#>` 会从该选择器中进行选择（并在可能时优先当前提供商）。
|
||||
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）以及 API 模式（`api`，如果可用）。
|
||||
|
||||
## 调试覆盖
|
||||
|
||||
`/debug` 允许你设置**仅运行时**的配置覆盖（内存中，不写磁盘）。仅限所有者。默认禁用；通过 `commands.debug: true` 启用。
|
||||
`/debug` 让你设置**仅运行时**配置覆盖（内存中，不写磁盘）。仅所有者。默认禁用；通过 `commands.debug: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -266,11 +274,32 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
说明：
|
||||
|
||||
- 覆盖会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。
|
||||
- 使用 `/debug reset` 清除所有覆盖，并返回磁盘上的配置。
|
||||
- 使用 `/debug reset` 可清除所有覆盖，并返回到磁盘上的配置。
|
||||
|
||||
## 插件追踪输出
|
||||
|
||||
`/trace` 让你在不开启完整详细模式的情况下切换**会话范围的插件追踪/调试行**。
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
/trace
|
||||
/trace on
|
||||
/trace off
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 不带参数的 `/trace` 会显示当前会话的追踪状态。
|
||||
- `/trace on` 会为当前会话启用插件追踪行。
|
||||
- `/trace off` 会再次将其关闭。
|
||||
- 插件追踪行可能会出现在 `/status` 中，也可能作为普通 assistant 回复之后的附加诊断消息出现。
|
||||
- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时配置覆盖。
|
||||
- `/trace` 也不能替代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。
|
||||
|
||||
## 配置更新
|
||||
|
||||
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者。默认禁用；通过 `commands.config: true` 启用。
|
||||
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅所有者。默认禁用；通过 `commands.config: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -284,12 +313,12 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
|
||||
说明：
|
||||
|
||||
- 配置会在写入前进行校验；无效更改会被拒绝。
|
||||
- 写入前会验证配置；无效更改会被拒绝。
|
||||
- `/config` 更新会在重启后保留。
|
||||
|
||||
## MCP 更新
|
||||
|
||||
`/mcp` 会写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器定义。仅限所有者。默认禁用；通过 `commands.mcp: true` 启用。
|
||||
`/mcp` 会把 OpenClaw 管理的 MCP 服务器定义写入 `mcp.servers` 下。仅所有者。默认禁用；通过 `commands.mcp: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -302,8 +331,8 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
|
||||
说明：
|
||||
|
||||
- `/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 自有项目设置中。
|
||||
- 运行时适配器决定哪些传输实际上可执行。
|
||||
- `/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 自有的项目设置中。
|
||||
- 运行时适配器决定哪些传输实际上可以执行。
|
||||
|
||||
## 插件更新
|
||||
|
||||
@ -321,34 +350,34 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
|
||||
说明：
|
||||
|
||||
- `/plugins list` 和 `/plugins show` 会基于当前工作区加磁盘配置执行真实的插件发现。
|
||||
- `/plugins enable|disable` 仅更新插件配置；不会安装或卸载插件。
|
||||
- 在启用/禁用更改后，重启 gateway 以应用它们。
|
||||
- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实的插件发现。
|
||||
- `/plugins enable|disable` 只会更新插件配置；不会安装或卸载插件。
|
||||
- 启用/禁用变更后，请重启 Gateway 网关以应用它们。
|
||||
|
||||
## 界面说明
|
||||
|
||||
- **文本命令** 在正常聊天会话中运行（私信共享 `main`，群组有各自的会话）。
|
||||
- **文本命令** 在普通聊天会话中运行（私信共享 `main`，群组有各自的会话）。
|
||||
- **原生命令** 使用隔离会话：
|
||||
- Discord：`agent:<agentId>:discord:slash:<userId>`
|
||||
- Slack：`agent:<agentId>:slack:slash:<userId>`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）
|
||||
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 指向聊天会话）
|
||||
- **`/stop`** 以活跃聊天会话为目标，因此它可以中止当前运行。
|
||||
- **Slack：** `channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack slash command（名称与 `/help` 等相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮的形式提供。
|
||||
- Slack 原生命令例外：请注册 `/agentstatus`（不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍可使用。
|
||||
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定位到聊天会话）
|
||||
- **`/stop`** 以当前活动聊天会话为目标，因此它可以中止当前运行。
|
||||
- **Slack：** `channels.slack.slashCommand` 仍然支持单个 `/openclaw` 风格命令。如果你启用了 `commands.native`，则必须为每个内置命令在 Slack 中创建一个斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式传递。
|
||||
- Slack 原生例外：请注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。
|
||||
|
||||
## BTW 侧边问题
|
||||
## BTW 旁支问题
|
||||
|
||||
`/btw` 是一个关于当前会话的快捷**侧边问题**。
|
||||
`/btw` 是一个关于当前会话的快速**旁支问题**。
|
||||
|
||||
与普通聊天不同：
|
||||
|
||||
- 它会使用当前会话作为背景上下文，
|
||||
- 它会作为一个独立的**无工具**单次调用运行，
|
||||
- 它会作为一次独立的**无工具**单次调用运行，
|
||||
- 它不会改变未来的会话上下文，
|
||||
- 它不会写入转录历史，
|
||||
- 它会作为实时侧边结果交付，而不是普通的助手消息。
|
||||
- 它会作为实时旁支结果交付，而不是普通 assistant 消息。
|
||||
|
||||
这让 `/btw` 在你希望获得临时澄清、同时主任务继续进行时非常有用。
|
||||
这使得 `/btw` 在你希望主任务继续进行的同时，临时获取一个澄清时非常有用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -356,4 +385,4 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
/btw what are we doing right now?
|
||||
```
|
||||
|
||||
完整行为和客户端 UX 细节请参见 [BTW Side Questions](/zh-CN/tools/btw)。
|
||||
有关完整行为和客户端 UX 细节，请参见 [BTW Side Questions](/zh-CN/tools/btw)。
|
||||
|
||||
@ -1,109 +1,118 @@
|
||||
---
|
||||
read_when:
|
||||
- 调整 thinking、快速模式或 verbose 指令解析或默认值
|
||||
summary: 用于 /think、/fast、/verbose 和 reasoning 可见性的指令语法
|
||||
title: Thinking 级别
|
||||
- 调整思考、快速模式或详细输出指令的解析方式或默认值
|
||||
summary: '`/think`、`/fast`、`/verbose`、`/trace` 的指令语法，以及推理可见性'
|
||||
title: 思考级别
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T10:12:41Z"
|
||||
generated_at: "2026-04-12T18:22:23Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f60aeb6ab4c7ce858f725f589f54184b29d8c91994d18c8deafa75179b9a62cb
|
||||
source_hash: 4f3b1341281f07ba4e9061e3355845dca234be04cc0d358594312beeb7676e68
|
||||
source_path: tools/thinking.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Thinking 级别（`/think` 指令）
|
||||
# 思考级别（`/think` 指令）
|
||||
|
||||
## 它的作用
|
||||
|
||||
- 可在任何传入消息正文中使用的内联指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
|
||||
- 可在任何入站消息正文中使用内联指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
|
||||
- 级别（别名）：`off | minimal | low | medium | high | xhigh | adaptive`
|
||||
- minimal → “think”
|
||||
- low → “think hard”
|
||||
- medium → “think harder”
|
||||
- high → “ultrathink”（最大预算）
|
||||
- xhigh → “ultrathink+”（仅限 GPT-5.2 + Codex 模型）
|
||||
- adaptive → 由提供商管理的自适应 reasoning 预算（适用于 Anthropic Claude 4.6 模型家族）
|
||||
- `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 都映射到 `xhigh`。
|
||||
- `highest`、`max` 都映射到 `high`。
|
||||
- xhigh → “ultrathink+”（仅适用于 GPT-5.2 和 Codex 模型）
|
||||
- adaptive → 由提供商管理的自适应推理预算（支持 Anthropic Claude 4.6 模型系列）
|
||||
- `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 都映射为 `xhigh`。
|
||||
- `highest`、`max` 映射为 `high`。
|
||||
- 提供商说明：
|
||||
- 当未设置显式 thinking 级别时，Anthropic Claude 4.6 模型默认使用 `adaptive`。
|
||||
- 走 Anthropic-compatible 流式路径的 MiniMax（`minimax/*`）默认使用 `thinking: { type: "disabled" }`，除非你在模型参数或请求参数中显式设置 thinking。这样可以避免 MiniMax 的非原生 Anthropic 流格式泄露 `reasoning_content` 增量。
|
||||
- Z.AI（`zai/*`）仅支持二元 thinking（`on`/`off`）。任何非 `off` 级别都会被视为 `on`（映射到 `low`）。
|
||||
- Moonshot（`moonshot/*`）会将 `/think off` 映射到 `thinking: { type: "disabled" }`，将任何非 `off` 级别映射到 `thinking: { type: "enabled" }`。启用 thinking 时，Moonshot 仅接受 `tool_choice` 为 `auto|none`；OpenClaw 会将不兼容的值规范化为 `auto`。
|
||||
- 当未显式设置思考级别时，Anthropic Claude 4.6 模型默认使用 `adaptive`。
|
||||
- 在 Anthropic 兼容流式路径上，MiniMax（`minimax/*`）默认使用 `thinking: { type: "disabled" }`，除非你在模型参数或请求参数中显式设置 thinking。这样可避免 MiniMax 的非原生 Anthropic 流格式泄露 `reasoning_content` 增量。
|
||||
- Z.AI（`zai/*`）只支持二元 thinking（`on`/`off`）。任何非 `off` 级别都会被视为 `on`（映射为 `low`）。
|
||||
- Moonshot（`moonshot/*`）将 `/think off` 映射为 `thinking: { type: "disabled" }`，并将任何非 `off` 级别映射为 `thinking: { type: "enabled" }`。启用 thinking 时，Moonshot 只接受 `tool_choice` 为 `auto|none`；OpenClaw 会将不兼容的值规范化为 `auto`。
|
||||
|
||||
## 解析顺序
|
||||
|
||||
1. 消息中的内联指令（仅对该条消息生效）。
|
||||
2. 会话覆盖（通过发送仅包含指令的消息设置）。
|
||||
3. 按智能体的默认值（配置中的 `agents.list[].thinkingDefault`）。
|
||||
1. 消息上的内联指令（仅适用于该条消息）。
|
||||
2. 会话覆盖（通过发送仅包含指令的消息来设置）。
|
||||
3. 每个智能体的默认值（配置中的 `agents.list[].thinkingDefault`）。
|
||||
4. 全局默认值（配置中的 `agents.defaults.thinkingDefault`）。
|
||||
5. 回退：Anthropic Claude 4.6 模型为 `adaptive`，其他支持 reasoning 的模型为 `low`，否则为 `off`。
|
||||
5. 回退：Anthropic Claude 4.6 模型为 `adaptive`，其他支持推理的模型为 `low`，否则为 `off`。
|
||||
|
||||
## 设置会话默认值
|
||||
|
||||
- 发送一条**只包含该指令**的消息（允许空白字符），例如 `/think:medium` 或 `/t high`。
|
||||
- 该设置会固定到当前会话中（默认按发送者区分）；会通过 `/think:off` 或会话空闲重置来清除。
|
||||
- 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），命令会被拒绝并附带提示，会话状态保持不变。
|
||||
- 发送不带参数的 `/think`（或 `/think:`）可查看当前 thinking 级别。
|
||||
- 发送一条**仅包含该指令**的消息（允许空白），例如 `/think:medium` 或 `/t high`。
|
||||
- 该设置会保留在当前会话中（默认按发送者划分）；可通过 `/think:off` 或会话空闲重置来清除。
|
||||
- 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），该命令会被拒绝并给出提示，会话状态保持不变。
|
||||
- 发送不带参数的 `/think`（或 `/think:`）可查看当前思考级别。
|
||||
|
||||
## 按智能体应用
|
||||
|
||||
- **嵌入式 Pi**：解析后的级别会传递给进程内 Pi 智能体运行时。
|
||||
- **嵌入式 Pi**：解析后的级别会传递给进程内的 Pi 智能体运行时。
|
||||
|
||||
## 快速模式（`/fast`）
|
||||
|
||||
- 级别：`on|off`。
|
||||
- 仅包含指令的消息会切换会话快速模式覆盖，并回复 `Fast mode enabled.` / `Fast mode disabled.`。
|
||||
- 不带模式发送 `/fast`（或 `/fast status`）可查看当前实际生效的快速模式状态。
|
||||
- 发送不带模式的 `/fast`（或 `/fast status`）可查看当前生效的快速模式状态。
|
||||
- OpenClaw 按以下顺序解析快速模式：
|
||||
1. 内联/仅指令 `/fast on|off`
|
||||
1. 内联 / 仅指令 `/fast on|off`
|
||||
2. 会话覆盖
|
||||
3. 按智能体的默认值（`agents.list[].fastModeDefault`）
|
||||
4. 按模型配置：`agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
3. 每个智能体的默认值（`agents.list[].fastModeDefault`）
|
||||
4. 每个模型的配置：`agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
5. 回退：`off`
|
||||
- 对于 `openai/*`，快速模式会通过在受支持的 Responses 请求上发送 `service_tier=priority` 映射到 OpenAI 优先处理。
|
||||
- 对于 `openai-codex/*`，快速模式会在 Codex Responses 上发送相同的 `service_tier=priority` 标志。OpenClaw 会在这两条认证路径之间共用一个 `/fast` 开关。
|
||||
- 对于直连公开 `anthropic/*` 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，快速模式会映射到 Anthropic service tier：`/fast on` 设置 `service_tier=auto`，`/fast off` 设置 `service_tier=standard_only`。
|
||||
- 对于 Anthropic-compatible 路径上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
|
||||
- 当两者同时设置时，显式的 Anthropic `serviceTier` / `service_tier` 模型参数会覆盖快速模式默认值。对于非 Anthropic 代理 base URL，OpenClaw 仍会跳过 Anthropic service-tier 注入。
|
||||
- 对于 `openai/*`，快速模式会通过在受支持的 Responses 请求中发送 `service_tier=priority` 来映射为 OpenAI 优先级处理。
|
||||
- 对于 `openai-codex/*`，快速模式会在 Codex Responses 上发送相同的 `service_tier=priority` 标志。OpenClaw 在这两种认证路径上共用一个 `/fast` 开关。
|
||||
- 对于直接发送到 `anthropic/*` 的公共请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，快速模式会映射为 Anthropic 服务层级：`/fast on` 设置 `service_tier=auto`，`/fast off` 设置 `service_tier=standard_only`。
|
||||
- 对于 Anthropic 兼容路径上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）会将 `MiniMax-M2.7` 改写为 `MiniMax-M2.7-highspeed`。
|
||||
- 当两者都设置时，显式的 Anthropic `serviceTier` / `service_tier` 模型参数会覆盖快速模式默认值。对于非 Anthropic 代理 base URL，OpenClaw 仍会跳过注入 Anthropic 服务层级。
|
||||
|
||||
## Verbose 指令（`/verbose` 或 `/v`）
|
||||
## 详细输出指令（`/verbose` 或 `/v`）
|
||||
|
||||
- 级别：`on`（最简）| `full` | `off`（默认）。
|
||||
- 仅包含指令的消息会切换会话 verbose，并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示而不更改状态。
|
||||
- `/verbose off` 会存储一个显式会话覆盖；可在 Sessions UI 中选择 `inherit` 来清除。
|
||||
- 内联指令仅影响当前消息；其他情况适用会话/全局默认值。
|
||||
- 不带参数发送 `/verbose`（或 `/verbose:`）可查看当前 verbose 级别。
|
||||
- 当 verbose 开启时，会输出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为单独的仅元数据消息发回；如果可用，会以 `<emoji> <tool-name>: <arg>` 为前缀（路径/命令）。这些工具摘要会在每个工具启动时立即发送（单独气泡），而不是作为流式增量发送。
|
||||
- 在普通模式下，工具失败摘要仍然可见，但原始错误详情后缀会被隐藏，除非 verbose 为 `on` 或 `full`。
|
||||
- 当 verbose 为 `full` 时，工具输出也会在完成后转发（单独气泡，并截断到安全长度）。如果你在运行进行中切换 `/verbose on|full|off`，后续工具气泡会遵循新设置。
|
||||
- 级别：`on`（最少）| `full` | `off`（默认）。
|
||||
- 仅包含指令的消息会切换会话详细输出，并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示，不会更改状态。
|
||||
- `/verbose off` 会存储显式的会话覆盖；可在会话 UI 中选择 `inherit` 以清除它。
|
||||
- 内联指令仅影响该条消息；否则应用会话 / 全局默认值。
|
||||
- 发送不带参数的 `/verbose`（或 `/verbose:`）可查看当前详细输出级别。
|
||||
- 启用详细输出时，会发出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为单独的仅元数据消息发回；如果可用，会以 `<emoji> <tool-name>: <arg>` 为前缀（路径 / 命令）。这些工具摘要会在每个工具启动时立即发送（单独气泡），而不是作为流式增量发送。
|
||||
- 工具失败摘要在普通模式下仍然可见，但原始错误详情后缀会被隐藏，除非详细输出为 `on` 或 `full`。
|
||||
- 当详细输出为 `full` 时，工具输出也会在完成后转发（单独气泡，并截断到安全长度）。如果你在一次运行进行中切换 `/verbose on|full|off`，后续工具气泡会遵循新设置。
|
||||
|
||||
## Reasoning 可见性（`/reasoning`）
|
||||
## 插件追踪指令（`/trace`）
|
||||
|
||||
- 级别：`on` | `off`（默认）。
|
||||
- 仅包含指令的消息会切换会话插件追踪输出，并回复 `Plugin trace enabled.` / `Plugin trace disabled.`。
|
||||
- 内联指令仅影响该条消息；否则应用会话 / 全局默认值。
|
||||
- 发送不带参数的 `/trace`（或 `/trace:`）可查看当前追踪级别。
|
||||
- `/trace` 比 `/verbose` 更窄：它只暴露插件拥有的追踪 / 调试行，例如 Active Memory 调试摘要。
|
||||
- 追踪行可能出现在 `/status` 中，也可能作为普通助手回复后的附加诊断消息出现。
|
||||
|
||||
## 推理可见性（`/reasoning`）
|
||||
|
||||
- 级别：`on|off|stream`。
|
||||
- 仅包含指令的消息会切换是否在回复中显示 thinking 块。
|
||||
- 启用后，reasoning 会作为**单独消息**发送，并带有 `Reasoning:` 前缀。
|
||||
- `stream`（仅 Telegram）：在回复生成期间，将 reasoning 流式写入 Telegram 草稿气泡中，然后发送不包含 reasoning 的最终答案。
|
||||
- 启用后，推理会作为**单独消息**发送，并以 `Reasoning:` 为前缀。
|
||||
- `stream`（仅 Telegram）：在回复生成期间，将推理流式传输到 Telegram 草稿气泡中，然后发送不带推理内容的最终答案。
|
||||
- 别名：`/reason`。
|
||||
- 不带参数发送 `/reasoning`（或 `/reasoning:`）可查看当前 reasoning 级别。
|
||||
- 解析顺序：内联指令，然后会话覆盖，然后按智能体默认值（`agents.list[].reasoningDefault`），最后回退（`off`）。
|
||||
- 发送不带参数的 `/reasoning`（或 `/reasoning:`）可查看当前推理级别。
|
||||
- 解析顺序：内联指令，然后是会话覆盖，然后是每个智能体的默认值（`agents.list[].reasoningDefault`），最后是回退值（`off`）。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- Elevated mode 文档位于 [Elevated mode](/zh-CN/tools/elevated)。
|
||||
- 提权模式文档位于 [Elevated mode](/zh-CN/tools/elevated)。
|
||||
|
||||
## Heartbeats
|
||||
## 心跳
|
||||
|
||||
- Heartbeat 探测消息正文是已配置的 heartbeat 提示词（默认值：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。heartbeat 消息中的内联指令会照常生效（但应避免通过 heartbeat 更改会话默认值）。
|
||||
- Heartbeat 投递默认仅发送最终载荷。若还要发送单独的 `Reasoning:` 消息（如果可用），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或按智能体设置 `agents.list[].heartbeat.includeReasoning: true`。
|
||||
- 心跳探测正文是已配置的心跳提示（默认：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。心跳消息中的内联指令会像平常一样生效（但应避免通过心跳更改会话默认值）。
|
||||
- 心跳传递默认仅发送最终负载。若还要发送单独的 `Reasoning:` 消息（如果可用），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或按智能体设置 `agents.list[].heartbeat.includeReasoning: true`。
|
||||
|
||||
## Web 聊天 UI
|
||||
|
||||
- Web 聊天中的 thinking 选择器会在页面加载时，从传入会话存储/配置中镜像该会话的已存储级别。
|
||||
- 选择另一个级别会立即通过 `sessions.patch` 写入会话覆盖；它不会等到下一次发送，也不是一次性的 `thinkingOnce` 覆盖。
|
||||
- 第一个选项始终是 `Default (<resolved level>)`，其中解析后的默认值来自当前会话模型：Anthropic/Bedrock 上的 Claude 4.6 为 `adaptive`，其他支持 reasoning 的模型为 `low`，否则为 `off`。
|
||||
- 该选择器会保持提供商感知：
|
||||
- 页面加载时，Web 聊天思考选择器会镜像来自入站会话存储 / 配置的会话已存储级别。
|
||||
- 选择其他级别会立即通过 `sessions.patch` 写入会话覆盖；它不会等待下一次发送，也不是一次性的 `thinkingOnce` 覆盖。
|
||||
- 第一个选项始终是 `Default (<resolved level>)`，其中解析出的默认值来自当前会话模型：Anthropic/Bedrock 上的 Claude 4.6 为 `adaptive`，其他支持推理的模型为 `low`，否则为 `off`。
|
||||
- 选择器会保持提供商感知：
|
||||
- 大多数提供商显示 `off | minimal | low | medium | high | adaptive`
|
||||
- Z.AI 显示二元选项 `off | on`
|
||||
- `/think:<level>` 仍然可用，并会更新同一个已存储的会话级别，因此聊天指令和选择器会保持同步。
|
||||
- `/think:<level>` 仍然有效，并会更新同一个已存储的会话级别，因此聊天指令与选择器保持同步。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user