@captain-app/openclaw 2026.2.4

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

@@ -0,0 +1,94 @@
+---
+read_when:
+  - 更改自动回复执行或并发设置时
+summary: 用于序列化入站自动回复运行的命令队列设计
+title: 命令队列
+x-i18n:
+  generated_at: "2026-02-03T10:05:28Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 2104c24d200fb4f9620e52a19255cd614ababe19d78f3ee42936dc6d0499b73b
+  source_path: concepts/queue.md
+  workflow: 15
+---
+
+# 命令队列（2026-01-16）
+
+我们通过一个小型进程内队列序列化入站自动回复运行（所有渠道），以防止多个智能体运行发生冲突，同时仍允许跨会话的安全并行。
+
+## 为什么需要
+
+- 自动回复运行可能开销很大（LLM 调用），当多条入站消息接近同时到达时可能发生冲突。
+- 序列化可以避免竞争共享资源（会话文件、日志、CLI stdin），并降低上游速率限制的可能性。
+
+## 工作原理
+
+- 一个支持通道感知的 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 + promises。
+
+## 故障排除
+
+- 如果命令似乎卡住，启用详细日志并查找"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-03T07:46:35Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 9b0aa2d1abea7050ba848a2db038ccc3e6e2d83c6eb4e3843a2ead0ab847574a
+  source_path: concepts/session-pruning.md
+  workflow: 15
+---
+
+# 会话剪枝
+
+会话剪枝在每次 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 重置很重要：** 一旦剪枝运行，缓存窗口会重置，因此后续请求可以重用新缓存的提示，而不是再次重新缓存完整历史。
+- **它不做什么：** 剪枝不会添加 token 或"双倍"成本；它只改变该 TTL 后第一个请求缓存的内容。
+
+## 可以剪枝的内容
+
+- 仅 `toolResult` 消息。
+- 用户 + 助手消息**永远不会**被修改。
+- 最后 `keepLastAssistants` 条助手消息受保护；该截止点之后的工具结果不会被剪枝。
+- 如果没有足够的助手消息来确定截止点，则跳过剪枝。
+- 包含**图像块**的工具结果会被跳过（永不修剪/清除）。
+
+## 上下文窗口估算
+
+剪枝使用估算的上下文窗口（字符 ≈ token × 4）。基础窗口按以下顺序解析：
+
+1. `models.providers.*.models[].contextWindow` 覆盖。
+2. 模型定义 `contextWindow`（来自模型注册表）。
+3. 默认 `200000` token。
+
+如果设置了 `agents.defaults.contextTokens`，它将被视为解析窗口的上限（最小值）。
+
+## 模式
+
+### cache-ttl
+
+- 仅当最后一次 Anthropic 调用早于 `ttl`（默认 `5m`）时才运行剪枝。
+- 运行时：与之前相同的软修剪 + 硬清除行为。
+
+## 软剪枝 vs 硬剪枝
+
+- **软修剪**：仅用于过大的工具结果。
+  - 保留头部 + 尾部，插入 `...`，并附加一个包含原始大小的注释。
+  - 跳过包含图像块的结果。
+- **硬清除**：用 `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-03T07:46:54Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: cb6e0982ebf507bcf9de4bb17719759c2b6d3e519731c845580a55279084e4c8
+  source_path: concepts/session-tool.md
+  workflow: 15
+---
+
+# 会话工具
+
+目标：小型、不易误用的工具集，使智能体能够列出会话、获取历史记录并向另一个会话发送消息。
+
+## 工具名称
+
+- `sessions_list`
+- `sessions_history`
+- `sessions_send`
+- `sessions_spawn`
+
+## 键模型
+
+- 主直接聊天桶始终是字面键 `"main"`（解析为当前智能体的主键）。
+- 群聊使用 `agent:<agentId>:<channel>:group:<id>` 或 `agent:<agentId>:<channel>:channel:<id>`（传递完整键）。
+- 定时任务使用 `cron:<job.id>`。
+- Hooks 使用 `hook:<uuid>`，除非明确设置。
+- Node 会话使用 `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` 映射。
+- 对于 cron/hook/node，`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`。
+
+行为：
+
+- 使用 `deliver: false` 启动新的 `agent:<agentId>:subagent:<uuid>` 会话。
+- 子智能体默认使用完整工具集**减去会话工具**（可通过 `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-03T07:47:44Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 147c8d1a4b6b4864cb16ad942feba80181b6b0e29afa765e7958f8c2483746b5
+  source_path: concepts/session.md
+  workflow: 15
+---
+
+# 会话管理
+
+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>`
+  - Webhooks：`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", // keep group keys separate
+    dmScope: "main", // DM continuity (set per-channel-peer/per-account-channel-peer for shared inboxes)
+    identityLinks: {
+      alice: ["telegram:123456789", "discord:987654321012345678"],
+    },
+    reset: {
+      // Defaults: mode=daily, atHour=4 (gateway host local time).
+      // If you also set idleMinutes, whichever expires first wins.
+      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 Web 凭证上次刷新时间（有助于发现重新链接需求）。
+- 发送 `/context list` 或 `/context detail` 查看系统提示中的内容和注入的工作区文件（以及最大的上下文贡献者）。
+- 单独发送 `/stop` 消息可中止当前运行、清除该会话的排队后续操作，并停止从中生成的任何子智能体运行（回复包含已停止的数量）。
+- 单独发送 `/compact`（可选指令）消息可总结旧上下文并释放窗口空间。参见 [/concepts/compaction](/concepts/compaction)。
+- 可以直接打开 JSONL 对话记录查看完整轮次。
+
+## 提示
+
+- 将主键专用于 1:1 通信；让群组保留各自的键。
+- 自动清理时，删除单个键而不是整个存储，以保留其他地方的上下文。
+
+## 会话来源元数据
+
+每个会话条目记录其来源（尽力而为）在 `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)。