@gguf/claw 2026.2.1 → 2026.2.2

package/docs/zh-CN/concepts/channel-routing.md

@@ -0,0 +1,117 @@
+---
+read_when:
+  - 更改渠道路由或收件箱行为
+summary: 每个渠道（WhatsApp、Telegram、Discord、Slack）的路由规则及共享上下文
+title: 渠道路由
+x-i18n:
+  generated_at: "2026-02-01T20:22:21Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1a322b5187e32c82fc1e8aac02437e2eeb7ba84e7b3a1db89feeab1dcf7dbbab
+  source_path: concepts/channel-routing.md
+  workflow: 14
+---
+
+# 渠道与路由
+
+OpenClaw 将回复**路由回消息来源的渠道**。模型不会选择渠道；路由是确定性的，由主机配置控制。
+
+## 关键术语
+
+- **渠道**：`whatsapp`、`telegram`、`discord`、`slack`、`signal`、`imessage`、`webchat`。
+- **AccountId**：每个渠道的账户实例（在支持的情况下）。
+- **AgentId**：隔离的工作区 + 会话存储（"大脑"）。
+- **SessionKey**：用于存储上下文和控制并发的桶键。
+
+## 会话键格式（示例）
+
+私信会折叠到智能体的**主**会话：
+
+- `agent:<agentId>:<mainKey>`（默认：`agent:main:main`）
+
+群组和渠道按渠道隔离：
+
+- 群组：`agent:<agentId>:<channel>:group:<id>`
+- 渠道/房间：`agent:<agentId>:<channel>:channel:<id>`
+
+线程：
+
+- Slack/Discord 线程会在基础键后追加 `:thread:<threadId>`。
+- Telegram 论坛主题在群组键中嵌入 `:topic:<topicId>`。
+
+示例：
+
+- `agent:main:telegram:group:-1001234567890:topic:42`
+- `agent:main:discord:channel:123456:thread:987654`
+
+## 路由规则（如何选择智能体）
+
+路由为每条入站消息选择**一个智能体**：
+
+1. **精确对端匹配**（`bindings` 中的 `peer.kind` + `peer.id`）。
+2. **Guild 匹配**（Discord）通过 `guildId`。
+3. **Team 匹配**（Slack）通过 `teamId`。
+4. **账户匹配**（渠道上的 `accountId`）。
+5. **渠道匹配**（该渠道上的任意账户）。
+6. **默认智能体**（`agents.list[].default`，否则取列表第一项，兜底为 `main`）。
+
+匹配到的智能体决定使用哪个工作区和会话存储。
+
+## 广播组（运行多个智能体）
+
+广播组允许你为同一对端运行**多个智能体**，**在 OpenClaw 正常回复时**触发（例如：在 WhatsApp 群组中，经过提及/激活门控之后）。
+
+配置：
+
+```json5
+{
+  broadcast: {
+    strategy: "parallel",
+    "120363403215116621@g.us": ["alfred", "baerbel"],
+    "+15555550123": ["support", "logger"],
+  },
+}
+```
+
+参见：[广播组](/broadcast-groups)。
+
+## 配置概览
+
+- `agents.list`：命名的智能体定义（工作区、模型等）。
+- `bindings`：将入站渠道/账户/对端映射到智能体。
+
+示例：
+
+```json5
+{
+  agents: {
+    list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
+  },
+  bindings: [
+    { match: { channel: "slack", teamId: "T123" }, agentId: "support" },
+    { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
+  ],
+}
+```
+
+## 会话存储
+
+会话存储位于状态目录下（默认 `~/.openclaw`）：
+
+- `~/.openclaw/agents/<agentId>/sessions/sessions.json`
+- JSONL 记录文件与存储位于同一目录
+
+你可以通过 `session.store` 和 `{agentId}` 模板来覆盖存储路径。
+
+## WebChat 行为
+
+WebChat 连接到**所选智能体**，并默认使用该智能体的主会话。因此，WebChat 让你可以在一个地方查看该智能体的跨渠道上下文。
+
+## 回复上下文
+
+入站回复包含：
+
+- `ReplyToId`、`ReplyToBody` 和 `ReplyToSender`（在可用时）。
+- 引用的上下文会以 `[Replying to ...]` 块的形式追加到 `Body` 中。
+
+这在所有渠道中保持一致。

package/docs/zh-CN/concepts/compaction.md

@@ -0,0 +1,67 @@
+---
+read_when:
+  - 你想了解自动压缩和 /compact
+  - 你正在调试长会话触及上下文限制的问题
+summary: 上下文窗口 + 压缩：OpenClaw 如何将会话保持在模型限制内
+title: 压缩
+x-i18n:
+  generated_at: "2026-02-01T20:22:17Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: e1d6791f2902044b5798ebf9320a7d055d37211eff4be03caa35d7e328ae803c
+  source_path: concepts/compaction.md
+  workflow: 14
+---
+
+# 上下文窗口与压缩
+
+每个模型都有一个**上下文窗口**（可见的最大 token 数）。长时间运行的对话会累积消息和工具结果；一旦窗口空间紧张，OpenClaw 会**压缩**较早的历史记录以保持在限制范围内。
+
+## 什么是压缩
+
+压缩会将**较早的对话总结**为一条紧凑的摘要条目，并保持近期消息不变。摘要存储在会话历史中，因此后续请求使用的是：
+
+- 压缩摘要
+- 压缩点之后的近期消息
+
+压缩会**持久化**到会话的 JSONL 历史记录中。
+
+## 配置
+
+有关 `agents.defaults.compaction` 设置，请参阅[压缩配置与模式](/concepts/compaction)。
+
+## 自动压缩（默认开启）
+
+当会话接近或超过模型的上下文窗口时，OpenClaw 会触发自动压缩，并可能使用压缩后的上下文重试原始请求。
+
+你会看到：
+
+- 详细模式下显示 `🧹 Auto-compaction complete`
+- `/status` 显示 `🧹 Compactions: <count>`
+
+在压缩之前，OpenClaw 可以运行一次**静默记忆刷写**轮次，将持久化笔记写入磁盘。详情及配置请参阅[记忆](/concepts/memory)。
+
+## 手动压缩
+
+使用 `/compact`（可选附带指令）强制执行一次压缩：
+
+```
+/compact Focus on decisions and open questions
+```
+
+## 上下文窗口来源
+
+上下文窗口因模型而异。OpenClaw 使用已配置提供商目录中的模型定义来确定限制。
+
+## 压缩与修剪
+
+- **压缩**：总结并**持久化**到 JSONL 中。
+- **会话修剪**：仅裁剪旧的**工具结果**，**在内存中**按请求进行。
+
+有关修剪的详情，请参阅 [/concepts/session-pruning](/concepts/session-pruning)。
+
+## 提示
+
+- 当会话感觉过时或上下文臃肿时，使用 `/compact`。
+- 大型工具输出已被截断；修剪可以进一步减少工具结果的堆积。
+- 如果你需要全新开始，`/new` 或 `/reset` 会启动一个新的会话 ID。

package/docs/zh-CN/concepts/context.md

@@ -0,0 +1,168 @@
+---
+read_when:
+  - 你想了解 OpenClaw 中"上下文"的含义
+  - 你在调试为什么模型"知道"某些内容（或遗忘了它）
+  - 你想减少上下文开销（/context、/status、/compact）
+summary: 上下文：模型看到的内容、如何构建以及如何检查
+title: 上下文
+x-i18n:
+  generated_at: "2026-02-01T20:22:35Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b32867b9b93254fdd1077d0d97c203cabfdba3330bb941693c83feba8e5db0cc
+  source_path: concepts/context.md
+  workflow: 14
+---
+
+# 上下文
+
+"上下文"是 **OpenClaw 在一次运行中发送给模型的所有内容**。它受模型的**上下文窗口**（token 限制）约束。
+
+初学者心智模型：
+
+- **系统提示词**（由 OpenClaw 构建）：规则、工具、Skills 列表、时间/运行时信息，以及注入的工作区文件。
+- **对话历史**：你的消息 + 助手在本次会话中的消息。
+- **工具调用/结果 + 附件**：命令输出、文件读取、图片/音频等。
+
+上下文与"记忆"_不是同一回事_：记忆可以存储在磁盘上并在之后重新加载；上下文是当前模型窗口内的内容。
+
+## 快速开始（检查上下文）
+
+- `/status` → 快速查看"我的窗口还剩多少空间？"以及会话设置。
+- `/context list` → 查看注入了哪些内容及大致大小（按文件和总计）。
+- `/context detail` → 更深入的分解：按文件、按工具 schema 大小、按 Skills 条目大小，以及系统提示词大小。
+- `/usage tokens` → 在正常回复后附加每次回复的用量信息。
+- `/compact` → 将较早的历史记录总结为一个压缩条目，以释放窗口空间。
+
+另请参阅：[斜杠命令](/tools/slash-commands)、[Token 用量与费用](/token-use)、[压缩](/concepts/compaction)。
+
+## 示例输出
+
+数值因模型、提供商、工具策略和工作区内容而异。
+
+### `/context list`
+
+```
+🧠 Context breakdown
+Workspace: <workspaceDir>
+Bootstrap max/file: 20,000 chars
+Sandbox: mode=non-main sandboxed=false
+System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
+
+Injected workspace files:
+- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
+- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
+- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
+- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
+- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
+- HEARTBEAT.md: MISSING | raw 0 | injected 0
+- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)
+
+Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
+Tools: read, edit, write, exec, process, browser, message, sessions_send, …
+Tool list (system prompt text): 1,032 chars (~258 tok)
+Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
+Tools: (same as above)
+
+Session tokens (cached): 14,250 total / ctx=32,000
+```
+
+### `/context detail`
+
+```
+🧠 Context breakdown (detailed)
+…
+Top skills (prompt entry size):
+- frontend-design: 412 chars (~103 tok)
+- oracle: 401 chars (~101 tok)
+… (+10 more skills)
+
+Top tools (schema size):
+- browser: 9,812 chars (~2,453 tok)
+- exec: 6,240 chars (~1,560 tok)
+… (+N more tools)
+```
+
+## 哪些内容计入上下文窗口
+
+模型接收到的所有内容都会计入，包括：
+
+- 系统提示词（所有部分）。
+- 对话历史。
+- 工具调用 + 工具结果。
+- 附件/转录内容（图片/音频/文件）。
+- 压缩摘要和修剪产物。
+- 提供商的"包装器"或隐藏头信息（不可见，但仍会计入）。
+
+## OpenClaw 如何构建系统提示词
+
+系统提示词由 **OpenClaw 拥有**，每次运行时重新构建。它包括：
+
+- 工具列表 + 简短描述。
+- Skills 列表（仅元数据；见下文）。
+- 工作区位置。
+- 时间（UTC + 如已配置则转换为用户时间）。
+- 运行时元数据（主机/操作系统/模型/思考模式）。
+- 在 **Project Context** 下注入的工作区引导文件。
+
+完整分解：[系统提示词](/concepts/system-prompt)。
+
+## 注入的工作区文件（Project Context）
+
+默认情况下，OpenClaw 会注入一组固定的工作区文件（如果存在）：
+
+- `AGENTS.md`
+- `SOUL.md`
+- `TOOLS.md`
+- `IDENTITY.md`
+- `USER.md`
+- `HEARTBEAT.md`
+- `BOOTSTRAP.md`（仅首次运行）
+
+大文件会按 `agents.defaults.bootstrapMaxChars`（默认 `20000` 字符）逐文件截断。`/context` 会显示**原始大小与注入大小**的对比，以及是否发生了截断。
+
+## Skills：注入的内容与按需加载的内容
+
+系统提示词中包含一个紧凑的**Skills 列表**（名称 + 描述 + 位置）。此列表会产生实际开销。
+
+Skills 指令默认*不会*包含在内。模型应在**需要时**才 `read` Skills 的 `SKILL.md`。
+
+## 工具：两种开销
+
+工具以两种方式影响上下文：
+
+1. 系统提示词中的**工具列表文本**（即你看到的"Tooling"部分）。
+2. **工具 schema**（JSON）。这些会发送给模型以便其调用工具。即使你看不到它们的纯文本形式，它们也会计入上下文。
+
+`/context detail` 会分解最大的工具 schema，让你了解哪些占用最多。
+
+## 命令、指令和"内联快捷方式"
+
+斜杠命令由 Gateway网关处理。有几种不同的行为：
+
+- **独立命令**：仅包含 `/...` 的消息作为命令运行。
+- **指令**：`/think`、`/verbose`、`/reasoning`、`/elevated`、`/model`、`/queue` 会在模型看到消息之前被移除。
+  - 仅含指令的消息会持久化会话设置。
+  - 普通消息中的内联指令作为单次消息提示生效。
+- **内联快捷方式**（仅限白名单发送者）：普通消息中的某些 `/...` 标记可以立即执行（例如："hey /status"），并在模型看到剩余文本之前被移除。
+
+详情：[斜杠命令](/tools/slash-commands)。
+
+## 会话、压缩和修剪（哪些内容会持久化）
+
+跨消息持久化的内容取决于机制：
+
+- **普通历史**会持久化在会话转录中，直到被策略压缩/修剪。
+- **压缩**会将摘要持久化到转录中，并保留最近的消息不变。
+- **修剪**会从运行的*内存中*提示词里移除旧的工具结果，但不会重写转录。
+
+文档：[会话](/concepts/session)、[压缩](/concepts/compaction)、[会话修剪](/concepts/session-pruning)。
+
+## `/context` 实际报告的内容
+
+`/context` 优先使用最新的**运行时构建的**系统提示词报告（如果可用）：
+
+- `System prompt (run)` = 从上一次嵌入式（具有工具能力的）运行中捕获，并持久化在会话存储中。
+- `System prompt (estimate)` = 当不存在运行报告时（或通过不生成该报告的 CLI 后端运行时）即时计算。
+
+无论哪种方式，它都会报告大小和主要贡献者；它**不会**输出完整的系统提示词或工具 schema。

package/docs/zh-CN/concepts/group-messages.md

@@ -0,0 +1,91 @@
+---
+read_when:
+  - 更改群组消息规则或提及方式时
+summary: WhatsApp 群组消息处理的行为与配置（mentionPatterns 在各平台间共享）
+title: 群组消息
+x-i18n:
+  generated_at: "2026-02-01T20:22:33Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 181a72f12f5021af77c2e4c913120f711e0c0bc271d218d75cb6fe80dab675bb
+  source_path: concepts/group-messages.md
+  workflow: 14
+---
+
+# 群组消息（WhatsApp 网页渠道）
+
+目标：让 Clawd 驻留在 WhatsApp 群组中，仅在被提及时唤醒，并将该线程与个人私聊会话隔离。
+
+注意：`agents.list[].groupChat.mentionPatterns` 现在也被 Telegram/Discord/Slack/iMessage 使用；本文档重点介绍 WhatsApp 特定的行为。对于多智能体配置，请为每个智能体设置 `agents.list[].groupChat.mentionPatterns`（或使用 `messages.groupChat.mentionPatterns` 作为全局回退）。
+
+## 已实现的功能（2025-12-03）
+
+- 激活模式：`mention`（默认）或 `always`。`mention` 需要一次提及（通过 `mentionedJids` 实现的 WhatsApp 原生 @提及、正则匹配，或消息文本中包含机器人的 E.164 号码）。`always` 会在每条消息时唤醒智能体，但智能体仅在能提供有价值的回复时才会响应；否则返回静默令牌 `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` 或 `/think high` 等命令（作为独立消息发送）仅作用于该群组；个人私聊状态不受影响。群组线程会跳过心跳。
+- 上下文注入：**仅待处理的**群组消息（默认 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.` 如果元数据不可用，我们仍然会告知智能体这是一个群聊。
+
+## 配置示例（WhatsApp）
+
+在 `~/.openclaw/openclaw.json` 中添加 `groupChat` 块，以便在 WhatsApp 去除文本正文中可见的 `@` 时，显示名称提及仍然有效：
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groups: {
+        "*": { requireMention: true },
+      },
+    },
+  },
+  agents: {
+    list: [
+      {
+        id: "main",
+        groupChat: {
+          historyLimit: 50,
+          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
+        },
+      },
+    ],
+  },
+}
+```
+
+说明：
+
+- 正则表达式不区分大小写；它们涵盖了 `@openclaw` 这样的显示名称提及，以及带或不带 `+`/空格的原始号码。
+- 当用户点击联系人时，WhatsApp 仍会通过 `mentionedJids` 发送规范提及，因此号码回退方式很少需要，但作为安全保障很有用。
+
+### 激活命令（仅限所有者）
+
+使用群聊命令：
+
+- `/activation mention`
+- `/activation always`
+
+只有所有者号码（来自 `channels.whatsapp.allowFrom`，未设置时使用机器人自身的 E.164 号码）可以更改此设置。在群组中发送 `/status` 作为独立消息即可查看当前激活模式。
+
+## 使用方法
+
+1. 将你的 WhatsApp 账号（运行 OpenClaw 的账号）添加到群组。
+2. 发送 `@openclaw …`（或包含号码）。除非设置了 `groupPolicy: "open"`，否则只有白名单中的发送者才能触发。
+3. 智能体提示词将包含最近的群组上下文以及末尾的 `[from: …]` 标记，以便它能回复正确的人。
+4. 会话级指令（`/verbose on`、`/think high`、`/new` 或 `/reset`、`/compact`）仅适用于该群组的会话；请将它们作为独立消息发送以确保生效。你的个人私聊会话保持独立。
+
+## 测试 / 验证
+
+- 手动冒烟测试：
+  - 在群组中发送 `@openclaw` 提及，确认回复中引用了发送者名称。
+  - 再次发送提及，验证历史消息块已包含并在下一轮清除。
+- 检查 Gateway网关日志（使用 `--verbose` 运行）查看 `inbound web message` 条目，确认其显示 `from: <groupJid>` 和 `[from: …]` 后缀。
+
+## 已知注意事项
+
+- 群组有意跳过心跳以避免嘈杂的广播。
+- 回声抑制使用组合的批次字符串；如果你在没有提及的情况下发送两次相同文本，只有第一次会收到响应。
+- 会话存储条目将以 `agent:<agentId>:whatsapp:group:<jid>` 的形式出现在会话存储中（默认为 `~/.openclaw/agents/<agentId>/sessions/sessions.json`）；缺少条目仅表示该群组尚未触发过运行。
+- 群组中的输入指示器遵循 `agents.defaults.typingMode`（默认：未被提及时为 `message`）。