@termix-it/cryptoclaw 1.0.0

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-03T07:46:15Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b32867b9b93254fdd1077d0d97c203cabfdba3330bb941693c83feba8e5db0cc
+  source_path: concepts/context.md
+  workflow: 15
+---
+
+# 上下文
+
+"上下文"是 **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 + 如果配置了则转换为用户时间）。
+- 运行时元数据（主机/操作系统/模型/思考）。
+- 在**项目上下文**下注入的工作区引导文件。
+
+完整分解：[系统提示词](/concepts/system-prompt)。
+
+## 注入的工作区文件（项目上下文）
+
+默认情况下，OpenClaw 注入一组固定的工作区文件（如果存在）：
+
+- `AGENTS.md`
+- `SOUL.md`
+- `TOOLS.md`
+- `IDENTITY.md`
+- `USER.md`
+- `HEARTBEAT.md`
+- `BOOTSTRAP.md`（仅首次运行）
+
+大文件按文件使用 `agents.defaults.bootstrapMaxChars`（默认 `20000` 字符）截断。`/context` 显示**原始 vs 注入**大小以及是否发生了截断。
+
+## Skills：注入的内容 vs 按需加载的内容
+
+系统提示词包含一个紧凑的 **Skills 列表**（名称 + 描述 + 位置）。此列表有实际开销。
+
+Skill 指令默认*不*包含。模型应该**仅在需要时**`read` Skill 的 `SKILL.md`。
+
+## 工具：有两种成本
+
+工具以两种方式影响上下文：
+
+1. 系统提示词中的**工具列表文本**（你看到的"Tooling"）。
+2. **工具 schema**（JSON）。这些发送给模型以便它可以调用工具。它们计入上下文，即使你看不到它们作为纯文本。
+
+`/context detail` 分解最大的工具 schema，以便你可以看到什么占主导。
+
+## 命令、指令和"内联快捷方式"
+
+斜杠命令由 Gateway 网关处理。有几种不同的行为：
+
+- **独立命令**：仅为 `/...` 的消息作为命令运行。
+- **指令**：`/think`、`/verbose`、`/reasoning`、`/elevated`、`/model`、`/queue` 在模型看到消息之前被剥离。
+  - 仅指令消息会持久化会话设置。
+  - 正常消息中的内联指令作为每条消息的提示。
+- **内联快捷方式**（仅允许列表中的发送者）：正常消息中的某些 `/...` token 可以立即运行（例如："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/features.md

@@ -0,0 +1,59 @@
+---
+read_when:
+  - 你想了解 OpenClaw 支持的完整功能列表
+summary: OpenClaw 在渠道、路由、媒体和用户体验方面的功能。
+title: 功能
+x-i18n:
+  generated_at: "2026-02-04T17:53:22Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1b6aee0bfda751824cb6b3a99080b4c80c00ffb355a96f9cff1b596d55d15ed4
+  source_path: concepts/features.md
+  workflow: 15
+---
+
+## 亮点
+
+<Columns>
+  <Card title="渠道" icon="message-square">
+    通过单个 Gateway 网关支持 WhatsApp、Telegram、Discord 和 iMessage。
+  </Card>
+  <Card title="插件" icon="plug">
+    通过扩展添加 Mattermost 等更多平台。
+  </Card>
+  <Card title="路由" icon="route">
+    多智能体路由，支持隔离会话。
+  </Card>
+  <Card title="媒体" icon="image">
+    支持图片、音频和文档的收发。
+  </Card>
+  <Card title="应用与界面" icon="monitor">
+    Web 控制界面和 macOS 配套应用。
+  </Card>
+  <Card title="移动节点" icon="smartphone">
+    iOS 和 Android 节点，支持 Canvas。
+  </Card>
+</Columns>
+
+## 完整列表
+
+- 通过 WhatsApp Web（Baileys）集成 WhatsApp
+- Telegram 机器人支持（grammY）
+- Discord 机器人支持（channels.discord.js）
+- Mattermost 机器人支持（插件）
+- 通过本地 imsg CLI 集成 iMessage（macOS）
+- Pi 的智能体桥接，支持 RPC 模式和工具流式传输
+- 长响应的流式传输和分块处理
+- 多智能体路由，按工作区或发送者隔离会话
+- 通过 OAuth 进行 Anthropic 和 OpenAI 的订阅认证
+- 会话：私信合并为共享的 `main`；群组相互隔离
+- 群聊支持，通过提及激活
+- 图片、音频和文档的媒体支持
+- 可选的语音消息转录钩子
+- WebChat 和 macOS 菜单栏应用
+- iOS 节点，支持配对和 Canvas 界面
+- Android 节点，支持配对、Canvas、聊天和相机
+
+<Note>
+旧版 Claude、Codex、Gemini 和 Opencode 路径已被移除。Pi 是唯一的编程智能体路径。
+</Note>

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

@@ -0,0 +1,91 @@
+---
+read_when:
+  - 更改群组消息规则或提及设置时
+summary: WhatsApp 群组消息处理的行为和配置（mentionPatterns 在各平台间共享）
+title: 群组消息
+x-i18n:
+  generated_at: "2026-02-03T10:05:00Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 181a72f12f5021af77c2e4c913120f711e0c0bc271d218d75cb6fe80dab675bb
+  source_path: concepts/group-messages.md
+  workflow: 15
+---
+
+# 群组消息（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`）。