@gguf/claw 2026.2.1 → 2026.2.2

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

@@ -0,0 +1,94 @@
+---
+read_when:
+  - 更改自动回复执行或并发机制
+summary: 序列化入站自动回复运行的命令队列设计
+title: 命令队列
+x-i18n:
+  generated_at: "2026-02-01T20:23:48Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 2104c24d200fb4f9620e52a19255cd614ababe19d78f3ee42936dc6d0499b73b
+  source_path: concepts/queue.md
+  workflow: 14
+---
+
+# 命令队列（2026-01-16）
+
+我们通过一个轻量的进程内队列来序列化入站自动回复运行（所有渠道），以防止多个智能体运行发生冲突，同时仍允许跨会话的安全并行。
+
+## 原因
+
+- 自动回复运行可能开销很大（LLM 调用），当多条入站消息几乎同时到达时可能发生冲突。
+- 序列化可以避免争用共享资源（会话文件、日志、CLI 标准输入），并降低触发上游速率限制的概率。
+
+## 工作原理
+
+- 一个支持通道感知的 FIFO 队列以可配置的并发上限逐通道排空（未配置的通道默认为 1；main 默认为 4，subagent 默认为 8）。
+- `runEmbeddedPiAgent` 按**会话键**（通道 `session:<key>`）入队，以保证每个会话同一时间只有一个活跃运行。
+- 每个会话运行随后被排入**全局通道**（默认为 `main`），因此整体并行度受 `agents.defaults.maxConcurrent` 限制。
+- 启用详细日志时，如果排队的运行在启动前等待超过约 2 秒，会发出一条简短通知。
+- 输入指示器在入队时仍会立即触发（当渠道支持时），因此在等待期间用户体验不受影响。
+
+## 队列模式（按渠道）
+
+入站消息可以引导当前运行、等待后续轮次，或两者兼顾：
+
+- `steer`：立即注入当前运行（在下一个工具边界后取消待执行的工具调用）。如果未在流式传输，则回退为 followup。
+- `followup`：在当前运行结束后排队等待下一个智能体轮次。
+- `collect`：将所有排队消息合并为**单个**后续轮次（默认）。如果消息针对不同的渠道/线程，它们会单独排空以保留路由。
+- `steer-backlog`（又名 `steer+backlog`）：立即引导**并且**保留消息用于后续轮次。
+- `interrupt`（旧版）：中止该会话的活跃运行，然后运行最新消息。
+- `queue`（旧版别名）：等同于 `steer`。
+
+steer-backlog 意味着在引导运行之后你还能获得后续响应，因此流式传输界面可能看起来像重复内容。如果希望每条入站消息只获得一次响应，请优先使用 `collect`/`steer`。
+发送 `/queue collect` 作为独立命令（按会话生效），或设置 `messages.queue.byChannel.discord: "collect"`。
+
+默认值（配置中未设置时）：
+
+- 所有界面 → `collect`
+
+通过 `messages.queue` 进行全局或按渠道配置：
+
+```json5
+{
+  messages: {
+    queue: {
+      mode: "collect",
+      debounceMs: 1000,
+      cap: 20,
+      drop: "summarize",
+      byChannel: { discord: "collect" },
+    },
+  },
+}
+```
+
+## 队列选项
+
+选项适用于 `followup`、`collect` 和 `steer-backlog`（以及 `steer` 回退为 followup 时）：
+
+- `debounceMs`：在启动后续轮次前等待静默期（防止"继续，继续"的情况）。
+- `cap`：每个会话的最大排队消息数。
+- `drop`：溢出策略（`old`、`new`、`summarize`）。
+
+summarize 会保留一个被丢弃消息的简短要点列表，并将其作为合成的后续提示词注入。
+默认值：`debounceMs: 1000`、`cap: 20`、`drop: summarize`。
+
+## 按会话覆盖
+
+- 发送 `/queue <mode>` 作为独立命令，可将该模式存储到当前会话。
+- 选项可以组合使用：`/queue collect debounce:2s cap:25 drop:summarize`
+- `/queue default` 或 `/queue reset` 清除会话覆盖。
+
+## 作用范围与保证
+
+- 适用于所有使用 Gateway网关回复管道的入站渠道的自动回复智能体运行（WhatsApp 网页版、Telegram、Slack、Discord、Signal、iMessage、网页聊天等）。
+- 默认通道（`main`）在进程范围内适用于入站消息和主心跳；设置 `agents.defaults.maxConcurrent` 以允许多个会话并行。
+- 可能存在其他通道（如 `cron`、`subagent`），以便后台任务可以并行运行而不阻塞入站回复。
+- 按会话通道保证同一时间只有一个智能体运行接触给定会话。
+- 无外部依赖或后台工作线程；纯 TypeScript + Promise 实现。
+
+## 故障排除
+
+- 如果命令似乎卡住，启用详细日志并查找 "queued for …ms" 行，以确认队列正在正常排空。
+- 如果需要查看队列深度，启用详细日志并观察队列计时行。

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

@@ -0,0 +1,76 @@
+---
+read_when:
+  - 更新提供商重试行为或默认值
+  - 调试提供商发送错误或速率限制
+summary: 出站提供商调用的重试策略
+title: 重试策略
+x-i18n:
+  generated_at: "2026-02-01T20:23:37Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 55bb261ff567f46ce447be9c0ee0c5b5e6d2776287d7662762656c14108dd607
+  source_path: concepts/retry.md
+  workflow: 14
+---
+
+# 重试策略
+
+## 目标
+
+- 按 HTTP 请求重试，而非按多步骤流程重试。
+- 通过仅重试当前步骤来保持顺序。
+- 避免重复执行非幂等操作。
+
+## 默认值
+
+- 尝试次数：3
+- 最大延迟上限：30000 毫秒
+- 抖动：0.1（10%）
+- 提供商默认值：
+  - Telegram 最小延迟：400 毫秒
+  - Discord 最小延迟：500 毫秒
+
+## 行为
+
+### Discord
+
+- 仅在速率限制错误（HTTP 429）时重试。
+- 可用时使用 Discord `retry_after`，否则使用指数退避。
+
+### Telegram
+
+- 在瞬态错误时重试（429、超时、连接/重置/关闭、暂时不可用）。
+- 可用时使用 `retry_after`，否则使用指数退避。
+- Markdown 解析错误不会重试；会回退为纯文本。
+
+## 配置
+
+在 `~/.openclaw/openclaw.json` 中按提供商设置重试策略：
+
+```json5
+{
+  channels: {
+    telegram: {
+      retry: {
+        attempts: 3,
+        minDelayMs: 400,
+        maxDelayMs: 30000,
+        jitter: 0.1,
+      },
+    },
+    discord: {
+      retry: {
+        attempts: 3,
+        minDelayMs: 500,
+        maxDelayMs: 30000,
+        jitter: 0.1,
+      },
+    },
+  },
+}
+```
+
+## 注意事项
+
+- 重试按请求应用（消息发送、媒体上传、表情回应、投票、贴纸）。
+- 组合流程不会重试已完成的步骤。

package/docs/zh-CN/concepts/session-pruning.md

@@ -0,0 +1,129 @@
+---
+read_when:
+  - 你想减少工具输出导致的 LLM 上下文增长
+  - 你正在调优 agents.defaults.contextPruning
+summary: 会话裁剪：通过修剪工具结果来减少上下文膨胀
+x-i18n:
+  generated_at: "2026-02-01T20:23:53Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 9b0aa2d1abea7050ba848a2db038ccc3e6e2d83c6eb4e3843a2ead0ab847574a
+  source_path: concepts/session-pruning.md
+  workflow: 14
+---
+
+# 会话裁剪
+
+会话裁剪在每次 LLM 调用之前修剪内存上下文中的**旧工具结果**。它**不会**重写磁盘上的会话历史（`*.jsonl`）。
+
+## 运行时机
+
+- 当启用 `mode: "cache-ttl"` 且该会话的上次 Anthropic 调用时间超过 `ttl` 时触发。
+- 仅影响该请求发送给模型的消息。
+- 仅对 Anthropic API 调用（以及 OpenRouter Anthropic 模型）生效。
+- 为获得最佳效果，请将 `ttl` 与模型的 `cacheControlTtl` 保持一致。
+- 裁剪后，TTL 窗口会重置，后续请求将继续使用缓存直到 `ttl` 再次过期。
+
+## 智能默认值（Anthropic）
+
+- **OAuth 或 setup-token** 配置文件：启用 `cache-ttl` 裁剪，并将心跳设置为 `1h`。
+- **API 密钥**配置文件：启用 `cache-ttl` 裁剪，将心跳设置为 `30m`，并将 Anthropic 模型的 `cacheControlTtl` 默认设为 `1h`。
+- 如果你显式设置了这些值中的任何一个，OpenClaw **不会**覆盖它们。
+
+## 改善效果（成本 + 缓存行为）
+
+- **为什么要裁剪：** Anthropic 提示缓存仅在 TTL 内生效。如果会话空闲超过 TTL，下一次请求将重新缓存完整提示，除非你先对其进行修剪。
+- **哪些费用会降低：** 裁剪减少了 TTL 过期后首次请求的 **cacheWrite** 大小。
+- **为什么 TTL 重置很重要：** 裁剪运行后，缓存窗口会重置，因此后续请求可以复用新缓存的提示，而不是再次重新缓存完整历史。
+- **它不会做什么：** 裁剪不会增加令牌或"翻倍"成本；它只改变 TTL 过期后首次请求的缓存内容。
+
+## 可裁剪的内容
+
+- 仅限 `toolResult` 消息。
+- 用户和助手消息**永远不会**被修改。
+- 最后 `keepLastAssistants` 条助手消息受保护；该截止点之后的工具结果不会被裁剪。
+- 如果助手消息数量不足以确定截止点，则跳过裁剪。
+- 包含**图片块**的工具结果会被跳过（永远不会被修剪/清除）。
+
+## 上下文窗口估算
+
+裁剪使用估算的上下文窗口（字符数 ≈ 令牌数 × 4）。基础窗口按以下顺序解析：
+
+1. `models.providers.*.models[].contextWindow` 覆盖值。
+2. 模型定义中的 `contextWindow`（来自模型注册表）。
+3. 默认 `200000` 令牌。
+
+如果设置了 `agents.defaults.contextTokens`，它将作为解析窗口的上限（取最小值）。
+
+## 模式
+
+### cache-ttl
+
+- 仅当上次 Anthropic 调用时间超过 `ttl`（默认 `5m`）时才运行裁剪。
+- 运行时：与之前相同的软修剪 + 硬清除行为。
+
+## 软裁剪与硬裁剪
+
+- **软修剪**：仅针对超大的工具结果。
+  - 保留头部和尾部，插入 `...`，并附加一条包含原始大小的说明。
+  - 跳过包含图片块的结果。
+- **硬清除**：用 `hardClear.placeholder` 替换整个工具结果。
+
+## 工具选择
+
+- `tools.allow` / `tools.deny` 支持 `*` 通配符。
+- 拒绝优先。
+- 匹配不区分大小写。
+- 允许列表为空 => 允许所有工具。
+
+## 与其他限制的交互
+
+- 内置工具已经会截断自身的输出；会话裁剪是一个额外的保护层，防止长时间运行的对话在模型上下文中积累过多的工具输出。
+- 压缩是独立的：压缩会进行摘要并持久化，裁剪则是每次请求的临时操作。参见 [/concepts/compaction](/concepts/compaction)。
+
+## 默认值（启用时）
+
+- `ttl`：`"5m"`
+- `keepLastAssistants`：`3`
+- `softTrimRatio`：`0.3`
+- `hardClearRatio`：`0.5`
+- `minPrunableToolChars`：`50000`
+- `softTrim`：`{ maxChars: 4000, headChars: 1500, tailChars: 1500 }`
+- `hardClear`：`{ enabled: true, placeholder: "[Old tool result content cleared]" }`
+
+## 示例
+
+默认（关闭）：
+
+```json5
+{
+  agent: {
+    contextPruning: { mode: "off" },
+  },
+}
+```
+
+启用 TTL 感知裁剪：
+
+```json5
+{
+  agent: {
+    contextPruning: { mode: "cache-ttl", ttl: "5m" },
+  },
+}
+```
+
+将裁剪限制为特定工具：
+
+```json5
+{
+  agent: {
+    contextPruning: {
+      mode: "cache-ttl",
+      tools: { allow: ["exec", "read"], deny: ["*image*"] },
+    },
+  },
+}
+```
+
+参见配置参考：[Gateway网关配置](/gateway/configuration)

package/docs/zh-CN/concepts/session-tool.md

@@ -0,0 +1,200 @@
+---
+read_when:
+  - 添加或修改会话工具
+summary: 智能体会话工具：列出会话、获取历史记录和发送跨会话消息
+title: 会话工具
+x-i18n:
+  generated_at: "2026-02-01T20:24:08Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: cb6e0982ebf507bcf9de4bb17719759c2b6d3e519731c845580a55279084e4c8
+  source_path: concepts/session-tool.md
+  workflow: 14
+---
+
+# 会话工具
+
+目标：提供小型、不易误用的工具集，使智能体能够列出会话、获取历史记录以及向其他会话发送消息。
+
+## 工具名称
+
+- `sessions_list`
+- `sessions_history`
+- `sessions_send`
+- `sessions_spawn`
+
+## 键模型
+
+- 主私聊桶始终使用字面键 `"main"`（解析为当前智能体的主键）。
+- 群聊使用 `agent:<agentId>:<channel>:group:<id>` 或 `agent:<agentId>:<channel>:channel:<id>`（传入完整键）。
+- 定时任务使用 `cron:<job.id>`。
+- 钩子使用 `hook:<uuid>`，除非显式设置。
+- 节点会话使用 `node-<nodeId>`，除非显式设置。
+
+`global` 和 `unknown` 是保留值，永远不会被列出。如果 `session.scope = "global"`，我们会将其别名为 `main` 供所有工具使用，这样调用方永远看不到 `global`。
+
+## sessions_list
+
+以行数组形式列出会话。
+
+参数：
+
+- `kinds?: string[]` 过滤器：`"main" | "group" | "cron" | "hook" | "node" | "other"` 的任意组合
+- `limit?: number` 最大行数（默认：服务器默认值，上限如 200）
+- `activeMinutes?: number` 仅返回 N 分钟内更新的会话
+- `messageLimit?: number` 0 = 不返回消息（默认 0）；>0 = 包含最近 N 条消息
+
+行为：
+
+- `messageLimit > 0` 时会获取每个会话的 `chat.history` 并包含最近 N 条消息。
+- 列表输出中会过滤工具结果；使用 `sessions_history` 获取工具消息。
+- 在**沙箱隔离**的智能体会话中运行时，会话工具默认为**仅已生成可见**（见下文）。
+
+行结构（JSON）：
+
+- `key`：会话键（字符串）
+- `kind`：`main | group | cron | hook | node | other`
+- `channel`：`whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown`
+- `displayName`（群组显示标签，如可用）
+- `updatedAt`（毫秒）
+- `sessionId`
+- `model`、`contextTokens`、`totalTokens`
+- `thinkingLevel`、`verboseLevel`、`systemSent`、`abortedLastRun`
+- `sendPolicy`（会话覆盖，如已设置）
+- `lastChannel`、`lastTo`
+- `deliveryContext`（规范化的 `{ channel, to, accountId }`，如可用）
+- `transcriptPath`（根据存储目录 + sessionId 推导的尽力路径）
+- `messages?`（仅当 `messageLimit > 0` 时）
+
+## sessions_history
+
+获取单个会话的对话记录。
+
+参数：
+
+- `sessionKey`（必需；接受会话键或来自 `sessions_list` 的 `sessionId`）
+- `limit?: number` 最大消息数（服务器限制上限）
+- `includeTools?: boolean`（默认 false）
+
+行为：
+
+- `includeTools=false` 过滤 `role: "toolResult"` 的消息。
+- 以原始对话记录格式返回消息数组。
+- 当传入 `sessionId` 时，OpenClaw 会将其解析为对应的会话键（缺失的 ID 会报错）。
+
+## sessions_send
+
+向另一个会话发送消息。
+
+参数：
+
+- `sessionKey`（必需；接受会话键或来自 `sessions_list` 的 `sessionId`）
+- `message`（必需）
+- `timeoutSeconds?: number`（默认 >0；0 = 即发即忘）
+
+行为：
+
+- `timeoutSeconds = 0`：入队并返回 `{ runId, status: "accepted" }`。
+- `timeoutSeconds > 0`：等待最多 N 秒完成，然后返回 `{ runId, status: "ok", reply }`。
+- 如果等待超时：`{ runId, status: "timeout", error }`。运行继续；稍后调用 `sessions_history`。
+- 如果运行失败：`{ runId, status: "error", error }`。
+- 通知投递在主运行完成后运行，属于尽力而为；`status: "ok"` 不保证通知已成功投递。
+- 通过 Gateway网关 `agent.wait`（服务器端）等待，因此重连不会中断等待。
+- 智能体间消息上下文会注入到主运行中。
+- 主运行完成后，OpenClaw 运行**回复往返循环**：
+  - 第 2 轮及之后在请求方和目标智能体之间交替。
+  - 回复 `REPLY_SKIP` 可停止来回往返。
+  - 最大轮数为 `session.agentToAgent.maxPingPongTurns`（0–5，默认 5）。
+- 循环结束后，OpenClaw 运行**智能体间通知步骤**（仅目标智能体）：
+  - 回复 `ANNOUNCE_SKIP` 可保持静默。
+  - 其他任何回复都会发送到目标渠道。
+  - 通知步骤包含原始请求 + 第 1 轮回复 + 最新的往返回复。
+
+## Channel 字段
+
+- 对于群组，`channel` 是会话条目上记录的渠道。
+- 对于私聊，`channel` 从 `lastChannel` 映射。
+- 对于定时任务/钩子/节点，`channel` 为 `internal`。
+- 如果缺失，`channel` 为 `unknown`。
+
+## 安全 / 发送策略
+
+基于策略的按渠道/聊天类型阻止（非按会话 ID）。
+
+```json
+{
+  "session": {
+    "sendPolicy": {
+      "rules": [
+        {
+          "match": { "channel": "discord", "chatType": "group" },
+          "action": "deny"
+        }
+      ],
+      "default": "allow"
+    }
+  }
+}
+```
+
+运行时覆盖（按会话条目）：
+
+- `sendPolicy: "allow" | "deny"`（未设置 = 继承配置）
+- 可通过 `sessions.patch` 或仅所有者的 `/send on|off|inherit`（独立消息）设置。
+
+执行点：
+
+- `chat.send` / `agent`（Gateway网关）
+- 自动回复投递逻辑
+
+## sessions_spawn
+
+在隔离会话中生成子智能体运行，并将结果通知回请求方的聊天渠道。
+
+参数：
+
+- `task`（必需）
+- `label?`（可选；用于日志/UI）
+- `agentId?`（可选；如允许，在另一个智能体 ID 下生成）
+- `model?`（可选；覆盖子智能体模型；无效值会报错）
+- `runTimeoutSeconds?`（默认 0；设置后，N 秒后中止子智能体运行）
+- `cleanup?`（`delete|keep`，默认 `keep`）
+
+允许列表：
+
+- `agents.list[].subagents.allowAgents`：允许通过 `agentId` 使用的智能体 ID 列表（`["*"]` 允许任意）。默认：仅请求方智能体。
+
+发现：
+
+- 使用 `agents_list` 发现哪些智能体 ID 可用于 `sessions_spawn`。
+
+行为：
+
+- 启动一个新的 `agent:<agentId>:subagent:<uuid>` 会话，设置 `deliver: false`。
+- 子智能体默认使用完整工具集**减去会话工具**（可通过 `tools.subagents.tools` 配置）。
+- 子智能体不允许调用 `sessions_spawn`（不允许子智能体生成子智能体）。
+- 始终非阻塞：立即返回 `{ status: "accepted", runId, childSessionKey }`。
+- 完成后，OpenClaw 运行子智能体**通知步骤**并将结果发布到请求方的聊天渠道。
+- 在通知步骤中回复 `ANNOUNCE_SKIP` 可保持静默。
+- 通知回复规范化为 `Status`/`Result`/`Notes`；`Status` 来自运行时结果（非模型文本）。
+- 子智能体会话在 `agents.defaults.subagents.archiveAfterMinutes`（默认：60）后自动归档。
+- 通知回复包含统计行（运行时间、token 数、sessionKey/sessionId、对话记录路径和可选费用）。
+
+## 沙箱会话可见性
+
+沙箱隔离的会话可以使用会话工具，但默认只能看到通过 `sessions_spawn` 生成的会话。
+
+配置：
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        // 默认: "spawned"
+        sessionToolsVisibility: "spawned", // 或 "all"
+      },
+    },
+  },
+}
+```

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

@@ -0,0 +1,166 @@
+---
+read_when:
+  - 修改会话处理或存储时
+summary: 聊天的会话管理规则、键和持久化
+title: 会话管理
+x-i18n:
+  generated_at: "2026-02-01T20:24:31Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 147c8d1a4b6b4864cb16ad942feba80181b6b0e29afa765e7958f8c2483746b5
+  source_path: concepts/session.md
+  workflow: 14
+---
+
+# 会话管理
+
+OpenClaw 将**每个智能体一个私聊会话**视为主会话。私聊归并到 `agent:<agentId>:<mainKey>`（默认 `main`），而群组/频道聊天拥有各自独立的键。`session.mainKey` 会被遵循。
+
+使用 `session.dmScope` 控制**私信**的分组方式：
+
+- `main`（默认）：所有私信共享主会话以保持连续性。
+- `per-peer`：按发送者 ID 跨渠道隔离。
+- `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
+- `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号收件箱）。
+  使用 `session.identityLinks` 将带提供商前缀的对端 ID 映射到规范身份，这样在使用 `per-peer`、`per-channel-peer` 或 `per-account-channel-peer` 时，同一个人可以跨渠道共享私信会话。
+
+## Gateway网关是权威数据源
+
+所有会话状态均由 **Gateway网关**（"主" OpenClaw）管理。UI 客户端（macOS 应用、WebChat 等）必须向 Gateway网关查询会话列表和令牌计数，而不是读取本地文件。
+
+- 在**远程模式**下，你关心的会话存储位于远程 Gateway网关主机上，而不是你的 Mac 上。
+- UI 中显示的令牌计数来自 Gateway网关存储字段（`inputTokens`、`outputTokens`、`totalTokens`、`contextTokens`）。客户端不会解析 JSONL 记录来"修正"总数。
+
+## 状态存储位置
+
+- 在 **Gateway网关主机**上：
+  - 存储文件：`~/.openclaw/agents/<agentId>/sessions/sessions.json`（每个智能体）。
+- 对话记录：`~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl`（Telegram 话题会话使用 `.../<SessionId>-topic-<threadId>.jsonl`）。
+- 存储是一个 `sessionKey -> { sessionId, updatedAt, ... }` 的映射。删除条目是安全的；它们会按需重新创建。
+- 群组条目可能包含 `displayName`、`channel`、`subject`、`room` 和 `space`，用于在 UI 中标记会话。
+- 会话条目包含 `origin` 元数据（标签 + 路由提示），以便 UI 能够解释会话的来源。
+- OpenClaw **不会**读取旧版 Pi/Tau 会话文件夹。
+
+## 会话修剪
+
+OpenClaw 默认在 LLM 调用之前从内存上下文中修剪**旧的工具结果**。
+这**不会**重写 JSONL 历史记录。请参见 [/concepts/session-pruning](/concepts/session-pruning)。
+
+## 压缩前记忆刷写
+
+当会话接近自动压缩时，OpenClaw 可以运行一次**静默记忆刷写**轮次，提醒模型将持久笔记写入磁盘。这仅在工作区可写时运行。请参见[记忆](/concepts/memory)和[压缩](/concepts/compaction)。
+
+## 传输层 → 会话键的映射
+
+- 私聊遵循 `session.dmScope`（默认 `main`）。
+  - `main`：`agent:<agentId>:<mainKey>`（跨设备/渠道保持连续性）。
+    - 多个电话号码和渠道可以映射到同一个智能体主键；它们充当一个对话的传输通道。
+  - `per-peer`：`agent:<agentId>:dm:<peerId>`。
+  - `per-channel-peer`：`agent:<agentId>:<channel>:dm:<peerId>`。
+  - `per-account-channel-peer`：`agent:<agentId>:<channel>:<accountId>:dm:<peerId>`（accountId 默认为 `default`）。
+  - 如果 `session.identityLinks` 匹配到带提供商前缀的对端 ID（例如 `telegram:123`），规范键将替换 `<peerId>`，使同一个人跨渠道共享会话。
+- 群聊隔离状态：`agent:<agentId>:<channel>:group:<id>`（房间/频道使用 `agent:<agentId>:<channel>:channel:<id>`）。
+  - Telegram 论坛话题在群组 ID 后附加 `:topic:<threadId>` 以实现隔离。
+  - 旧版 `group:<id>` 键仍被识别以支持迁移。
+- 入站上下文可能仍使用 `group:<id>`；渠道从 `Provider` 推断并规范化为 `agent:<agentId>:<channel>:group:<id>` 的规范形式。
+- 其他来源：
+  - 定时任务：`cron:<job.id>`
+  - Webhook：`hook:<uuid>`（除非由 hook 显式设置）
+  - 节点运行：`node-<nodeId>`
+
+## 生命周期
+
+- 重置策略：会话持续复用直到过期，过期在下一条入站消息时评估。
+- 每日重置：默认为 **Gateway网关主机本地时间凌晨 4:00**。当会话的最后更新早于最近一次每日重置时间时，会话即为过期。
+- 空闲重置（可选）：`idleMinutes` 添加一个滑动空闲窗口。当同时配置了每日重置和空闲重置时，**先到期的那个**强制创建新会话。
+- 旧版仅空闲模式：如果设置了 `session.idleMinutes` 但没有任何 `session.reset`/`resetByType` 配置，OpenClaw 会保持仅空闲模式以向后兼容。
+- 按类型覆盖（可选）：`resetByType` 允许你为 `dm`、`group` 和 `thread` 会话覆盖策略（thread = Slack/Discord 线程、Telegram 话题、连接器提供的 Matrix 线程）。
+- 按渠道覆盖（可选）：`resetByChannel` 覆盖特定渠道的重置策略（适用于该渠道的所有会话类型，优先级高于 `reset`/`resetByType`）。
+- 重置触发器：精确的 `/new` 或 `/reset`（加上 `resetTriggers` 中的额外项）会启动一个新的会话 ID，并将消息的剩余部分继续传递。`/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）来设置新会话的模型。如果单独发送 `/new` 或 `/reset`，OpenClaw 会运行一个简短的"问候"轮次来确认重置。
+- 手动重置：从存储中删除特定键或移除 JSONL 记录；下一条消息会重新创建它们。
+- 隔离的定时任务每次运行都会创建一个新的 `sessionId`（不复用空闲会话）。
+
+## 发送策略（可选）
+
+无需列出单个 ID 即可按特定会话类型阻止投递。
+
+```json5
+{
+  session: {
+    sendPolicy: {
+      rules: [
+        { action: "deny", match: { channel: "discord", chatType: "group" } },
+        { action: "deny", match: { keyPrefix: "cron:" } },
+      ],
+      default: "allow",
+    },
+  },
+}
+```
+
+运行时覆盖（仅限所有者）：
+
+- `/send on` → 允许此会话发送
+- `/send off` → 禁止此会话发送
+- `/send inherit` → 清除覆盖并使用配置规则
+  请将这些作为独立消息发送以确保生效。
+
+## 配置（可选的重命名示例）
+
+```json5
+// ~/.openclaw/openclaw.json
+{
+  session: {
+    scope: "per-sender", // 保持群组键独立
+    dmScope: "main", // 私信连续性（共享收件箱请设置 per-channel-peer/per-account-channel-peer）
+    identityLinks: {
+      alice: ["telegram:123456789", "discord:987654321012345678"],
+    },
+    reset: {
+      // 默认值：mode=daily，atHour=4（Gateway网关主机本地时间）。
+      // 如果同时设置了 idleMinutes，先到期的优先。
+      mode: "daily",
+      atHour: 4,
+      idleMinutes: 120,
+    },
+    resetByType: {
+      thread: { mode: "daily", atHour: 4 },
+      dm: { mode: "idle", idleMinutes: 240 },
+      group: { mode: "idle", idleMinutes: 120 },
+    },
+    resetByChannel: {
+      discord: { mode: "idle", idleMinutes: 10080 },
+    },
+    resetTriggers: ["/new", "/reset"],
+    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
+    mainKey: "main",
+  },
+}
+```
+
+## 检查
+
+- `openclaw status` — 显示存储路径和最近的会话。
+- `openclaw sessions --json` — 转储所有条目（使用 `--active <minutes>` 进行筛选）。
+- `openclaw gateway call sessions.list --params '{}'` — 从运行中的 Gateway网关获取会话（使用 `--url`/`--token` 访问远程 Gateway网关）。
+- 在聊天中发送 `/status` 作为独立消息，可查看智能体是否可达、会话上下文使用了多少、当前的思考/详细模式开关，以及 WhatsApp 网页凭证的最后刷新时间（有助于发现需要重新链接的情况）。
+- 发送 `/context list` 或 `/context detail` 查看系统提示词和注入的工作区文件中的内容（以及最大的上下文贡献者）。
+- 发送 `/stop` 作为独立消息，可中止当前运行、清除该会话的排队后续消息，并停止由其生成的任何子智能体运行（回复中包含已停止的数量）。
+- 发送 `/compact`（可选指令）作为独立消息，可总结旧的上下文并释放窗口空间。请参见 [/concepts/compaction](/concepts/compaction)。
+- JSONL 记录可以直接打开以查看完整的对话轮次。
+
+## 提示
+
+- 将主键专用于一对一对话；让群组保持各自独立的键。
+- 自动化清理时，删除单个键而不是整个存储，以保留其他地方的上下文。
+
+## 会话来源元数据
+
+每个会话条目在 `origin` 中记录其来源（尽力而为）：
+
+- `label`：人类可读标签（从对话标签 + 群组主题/频道解析）
+- `provider`：规范化的渠道 ID（包括扩展）
+- `from`/`to`：入站信封中的原始路由 ID
+- `accountId`：提供商账号 ID（多账号时）
+- `threadId`：渠道支持时的线程/话题 ID
+  来源字段为私信、频道和群组填充。如果连接器仅更新投递路由（例如，保持私信主会话活跃），它仍应提供入站上下文，以便会话保留其说明性元数据。扩展可以通过在入站上下文中发送 `ConversationLabel`、`GroupSubject`、`GroupChannel`、`GroupSpace` 和 `SenderName`，并调用 `recordSessionMetaFromInbound`（或将相同的上下文传递给 `updateLastRoute`）来实现。

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

@@ -0,0 +1,17 @@
+---
+read_when:
+  - 你查找了 docs/sessions.md；规范文档位于 docs/session.md
+summary: 会话管理文档的别名
+title: 会话
+x-i18n:
+  generated_at: "2026-02-01T20:23:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 7f1e39c3c07b9bb5cdcda361399cf1ce1226ebae3a797d8f93e734aa6a4d00e2
+  source_path: concepts/sessions.md
+  workflow: 14
+---
+
+# 会话
+
+规范的会话管理文档位于[会话管理](/concepts/session)。