From 99c86150bb18d48eab2eb24caaead2cada1c60cb Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 30 Apr 2026 18:27:16 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/agent-loop.md | 143 ++++++++++++++---------------- docs/zh-CN/concepts/queue.md | 94 +++++++++++--------- 2 files changed, 117 insertions(+), 120 deletions(-) diff --git a/docs/zh-CN/concepts/agent-loop.md b/docs/zh-CN/concepts/agent-loop.md index 4b4e5d837..5f4c38dc7 100644 --- a/docs/zh-CN/concepts/agent-loop.md +++ b/docs/zh-CN/concepts/agent-loop.md @@ -1,24 +1,22 @@ --- read_when: - - 你需要关于智能体循环或生命周期事件的精确演练 - - 你正在更改会话队列、会话记录写入或会话写入锁行为 + - 你需要一份关于智能体循环或生命周期事件的精确逐步说明 + - 你正在更改会话排队、对话记录写入或会话写入锁行为 summary: Agent loop 生命周期、流和等待语义 title: Agent loop x-i18n: - generated_at: "2026-04-29T15:58:15Z" + generated_at: "2026-04-30T18:26:40Z" model: gpt-5.5 provider: openai - source_hash: 902d543bd71dd517a810d825cbe92e244fe89230f47eeada72477c657a2bec32 + source_hash: 5466893253e1f82482284ff82db56f4c3fca018bf12e4114fad76d37cad954df source_path: concepts/agent-loop.md workflow: 16 --- -智能体循环是智能体一次完整的“真实”运行：输入接收 → 上下文组装 → 模型推理 → -工具执行 → 流式回复 → 持久化。它是权威路径，将一条消息 -转化为动作和最终回复，同时保持会话状态一致。 +智能体循环是智能体完整的“真实”运行：接收 → 上下文组装 → 模型推理 → +工具执行 → 流式回复 → 持久化。它是将消息转化为操作和最终回复的权威路径，同时保持会话状态一致。 -在 OpenClaw 中，一个循环是每个会话一次单独、串行化的运行，会在模型思考、调用工具 -和流式输出时发出生命周期与流事件。本文说明这个真实循环如何端到端连接。 +在 OpenClaw 中，一个循环是每个会话的一次串行运行，会在模型思考、调用工具和流式输出时发出生命周期和流事件。本文档说明这个真实循环如何端到端接线。 ## 入口点 @@ -32,146 +30,137 @@ x-i18n: - 解析模型 + thinking/verbose/trace 默认值 - 加载 Skills 快照 - 调用 `runEmbeddedPiAgent`（pi-agent-core 运行时） - - 如果嵌入式循环没有发出事件，则发出 **lifecycle end/error** + - 如果嵌入式循环未发出生命周期 end/error，则发出 **lifecycle end/error** 3. `runEmbeddedPiAgent`： - 通过每会话 + 全局队列串行化运行 - - 解析模型 + 凭证配置文件并构建 Pi 会话 - - 订阅 Pi 事件并流式传输 assistant/tool 增量 - - 强制执行超时 -> 超过后中止运行 - - 返回 payload + 用量元数据 + - 解析模型 + 凭证配置，并构建 Pi 会话 + - 订阅 Pi 事件并流式传输助手/工具增量 + - 强制超时 -> 超过时中止运行 + - 对于 Codex app-server 轮次，在终端事件之前，如果已接受的轮次停止产生 app-server 进度，则中止该轮次 + - 返回 payload + usage 元数据 4. `subscribeEmbeddedPiSession` 将 pi-agent-core 事件桥接到 OpenClaw `agent` 流： - 工具事件 => `stream: "tool"` - - assistant 增量 => `stream: "assistant"` + - 助手增量 => `stream: "assistant"` - 生命周期事件 => `stream: "lifecycle"`（`phase: "start" | "end" | "error"`） 5. `agent.wait` 使用 `waitForAgentRun`： - 等待 `runId` 的 **lifecycle end/error** - 返回 `{ status: ok|error|timeout, startedAt, endedAt, error? }` -## 排队 + 并发 +## 队列 + 并发 -- 运行会按会话键（会话 lane）串行化，并可选择经过全局 lane。 -- 这可以防止工具/会话竞态，并保持会话历史一致。 -- 消息渠道可以选择队列模式（collect/steer/followup）来接入这个 lane 系统。 - 参见 [Command Queue](/zh-CN/concepts/queue)。 -- 转录写入也会受到会话文件上的会话写锁保护。该锁 - 感知进程且基于文件，因此能捕获绕过进程内队列或来自 - 另一个进程的写入者。 -- 会话写锁默认不可重入。如果某个 helper 有意在保持一个逻辑写入者的同时 - 嵌套获取同一个锁，它必须通过 - `allowReentrant: true` 显式选择加入。 +- 运行按会话键（会话通道）串行化，并可选通过全局通道。 +- 这会防止工具/会话竞争，并保持会话历史一致。 +- 消息渠道可以选择队列模式（collect/steer/followup），这些模式会馈入此通道系统。 + 参见 [命令队列](/zh-CN/concepts/queue)。 +- 转录写入也受会话文件上的会话写锁保护。该锁感知进程并基于文件，因此可以捕获绕过进程内队列或来自其他进程的写入者。 +- 会话写锁默认不可重入。如果某个 helper 有意在保持一个逻辑写入者的同时嵌套获取同一把锁，它必须用 `allowReentrant: true` 显式选择加入。 ## 会话 + 工作区准备 -- 工作区会被解析并创建；沙箱隔离运行可能会重定向到沙箱工作区根目录。 -- Skills 会被加载（或从快照复用）并注入到环境变量和提示词中。 -- Bootstrap/上下文文件会被解析，并注入到系统提示词报告中。 -- 会获取会话写锁；`SessionManager` 会在流式传输前打开并准备好。任何 - 后续转录重写、压缩或截断路径，在打开或 - 变更转录文件前都必须获取同一把锁。 +- 解析并创建工作区；沙箱隔离运行可能会重定向到沙箱工作区根目录。 +- 加载 Skills（或从快照复用），并注入到 env 和提示词中。 +- 解析 bootstrap/context 文件，并注入到系统提示词报告中。 +- 获取会话写锁；在流式传输前打开并准备 `SessionManager`。任何后续转录重写、压缩或截断路径，在打开或修改转录文件前都必须获取同一把锁。 ## 提示词组装 + 系统提示词 -- 系统提示词由 OpenClaw 的基础提示词、Skills 提示词、bootstrap 上下文和每次运行覆盖项构建而成。 +- 系统提示词由 OpenClaw 的基础提示词、Skills 提示词、bootstrap 上下文和每次运行的覆盖项构建。 - 会强制执行模型特定限制和压缩预留 token。 -- 参见 [系统提示词](/zh-CN/concepts/system-prompt) 了解模型会看到什么。 +- 参见 [系统提示词](/zh-CN/concepts/system-prompt) 了解模型看到的内容。 ## 钩子点（你可以拦截的位置） OpenClaw 有两套钩子系统： - **内部钩子**（Gateway 网关钩子）：用于命令和生命周期事件的事件驱动脚本。 -- **插件钩子**：智能体/工具生命周期和 Gateway 网关管线中的扩展点。 +- **插件钩子**：智能体/工具生命周期和 Gateway 网关流水线中的扩展点。 ### 内部钩子（Gateway 网关钩子） - **`agent:bootstrap`**：在系统提示词最终确定前构建 bootstrap 文件时运行。 - 用它添加/移除 bootstrap 上下文文件。 -- **命令钩子**：`/new`、`/reset`、`/stop` 以及其他命令事件（参见 Hooks 文档）。 + 用它来添加/移除 bootstrap 上下文文件。 +- **命令钩子**：`/new`、`/reset`、`/stop` 和其他命令事件（参见 Hooks 文档）。 参见 [Hooks](/zh-CN/automation/hooks) 获取设置和示例。 ### 插件钩子（智能体 + Gateway 网关生命周期） -这些钩子会在智能体循环或 Gateway 网关管线内运行： +这些钩子在智能体循环或 Gateway 网关流水线内运行： -- **`before_model_resolve`**：在会话前运行（无 `messages`），用于在模型解析前确定性地覆盖提供商/模型。 -- **`before_prompt_build`**：在会话加载后运行（带 `messages`），用于在提交提示词前注入 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。将 `prependContext` 用于每轮动态文本，将 system-context 字段用于应位于系统提示词空间中的稳定指导。 +- **`before_model_resolve`**：在会话前运行（没有 `messages`），用于在模型解析前确定性地覆盖提供商/模型。 +- **`before_prompt_build`**：在会话加载后运行（带 `messages`），用于在提交提示词前注入 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。将 `prependContext` 用于每轮动态文本，将系统上下文字段用于应放在系统提示词空间中的稳定指导。 - **`before_agent_start`**：旧版兼容钩子，可能在任一阶段运行；优先使用上面的显式钩子。 -- **`before_agent_reply`**：在内联动作之后、LLM 调用之前运行，让插件接管本轮并返回合成回复，或完全静默本轮。 +- **`before_agent_reply`**：在内联操作之后、LLM 调用之前运行，让插件声明接管本轮并返回合成回复，或完全静默本轮。 - **`agent_end`**：在完成后检查最终消息列表和运行元数据。 - **`before_compaction` / `after_compaction`**：观察或标注压缩周期。 - **`before_tool_call` / `after_tool_call`**：拦截工具参数/结果。 -- **`before_install`**：检查内置扫描发现，并可选择阻止 skill 或插件安装。 -- **`tool_result_persist`**：在工具结果写入 OpenClaw 拥有的会话转录前，同步转换工具结果。 +- **`before_install`**：检查内置扫描发现，并可选阻止 skill 或插件安装。 +- **`tool_result_persist`**：在工具结果写入 OpenClaw 拥有的会话转录之前，同步转换工具结果。 - **`message_received` / `message_sending` / `message_sent`**：入站 + 出站消息钩子。 - **`session_start` / `session_end`**：会话生命周期边界。 - **`gateway_start` / `gateway_stop`**：Gateway 网关生命周期事件。 -出站/工具保护的钩子决策规则： +出站/工具防护的钩子决策规则： -- `before_tool_call`：`{ block: true }` 是终止性的，会停止较低优先级的处理器。 +- `before_tool_call`：`{ block: true }` 是终止性的，并会停止较低优先级 handler。 - `before_tool_call`：`{ block: false }` 是无操作，不会清除先前的阻止。 -- `before_install`：`{ block: true }` 是终止性的，会停止较低优先级的处理器。 +- `before_install`：`{ block: true }` 是终止性的，并会停止较低优先级 handler。 - `before_install`：`{ block: false }` 是无操作，不会清除先前的阻止。 -- `message_sending`：`{ cancel: true }` 是终止性的，会停止较低优先级的处理器。 +- `message_sending`：`{ cancel: true }` 是终止性的，并会停止较低优先级 handler。 - `message_sending`：`{ cancel: false }` 是无操作，不会清除先前的取消。 参见 [插件钩子](/zh-CN/plugins/hooks) 获取钩子 API 和注册细节。 -Harness 可以用不同方式适配这些钩子。Codex app-server harness 将 -OpenClaw 插件钩子保留为已记录镜像 -表面的兼容性契约，而 Codex 原生钩子仍是独立的低层 Codex 机制。 +Harness 可能会以不同方式适配这些钩子。Codex app-server harness 将 OpenClaw 插件钩子保留为已记录镜像表面的兼容性契约，而 Codex 原生钩子仍然是单独的较低层 Codex 机制。 ## 流式传输 + 部分回复 -- Assistant 增量从 pi-agent-core 流式传输，并作为 `assistant` 事件发出。 +- 助手增量从 pi-agent-core 流式传输，并作为 `assistant` 事件发出。 - 分块流式传输可以在 `text_end` 或 `message_end` 上发出部分回复。 -- 推理流式传输可以作为单独的流发出，也可以作为分块回复发出。 -- 参见 [Streaming](/zh-CN/concepts/streaming) 了解分块和分块回复行为。 +- 推理流可以作为单独流发出，也可以作为块回复发出。 +- 参见 [流式传输](/zh-CN/concepts/streaming) 了解分块和块回复行为。 ## 工具执行 + 消息工具 - 工具 start/update/end 事件会在 `tool` 流上发出。 -- 工具结果在记录/发出前会针对大小和图片 payload 进行清理。 -- 消息工具发送会被跟踪，以抑制重复的 assistant 确认。 +- 工具结果在记录/发出前会针对大小和图片 payload 进行净化。 +- 会跟踪消息工具发送，以抑制重复的助手确认。 -## 回复整形 + 抑制 +## 回复塑形 + 抑制 - 最终 payload 由以下内容组装： - - assistant 文本（以及可选推理） + - 助手文本（以及可选推理） - 内联工具摘要（当 verbose + 允许时） - - 模型出错时的 assistant 错误文本 -- 精确静默 token `NO_REPLY` / `no_reply` 会从出站 - payload 中过滤掉。 + - 模型出错时的助手错误文本 +- 精确静默 token `NO_REPLY` / `no_reply` 会从出站 payload 中过滤。 - 消息工具重复项会从最终 payload 列表中移除。 -- 如果没有剩余可渲染的 payload 且某个工具出错，则会发出回退工具错误回复 - （除非消息工具已经发送了用户可见回复）。 +- 如果没有剩余可渲染 payload 且某个工具出错，则会发出后备工具错误回复（除非消息工具已经发送了用户可见回复）。 ## 压缩 + 重试 -- 自动压缩会发出 `compaction` 流事件，并可触发重试。 +- 自动压缩会发出 `compaction` 流事件，并可能触发重试。 - 重试时，内存缓冲区和工具摘要会被重置，以避免重复输出。 -- 参见 [Compaction](/zh-CN/concepts/compaction) 了解压缩管线。 +- 参见 [压缩](/zh-CN/concepts/compaction) 了解压缩流水线。 ## 事件流（当前） -- `lifecycle`：由 `subscribeEmbeddedPiSession` 发出（并由 `agentCommand` 作为回退发出） +- `lifecycle`：由 `subscribeEmbeddedPiSession` 发出（并由 `agentCommand` 作为后备发出） - `assistant`：来自 pi-agent-core 的流式增量 - `tool`：来自 pi-agent-core 的流式工具事件 ## 聊天渠道处理 -- Assistant 增量会被缓冲到聊天 `delta` 消息中。 -- 聊天 `final` 会在 **lifecycle end/error** 上发出。 +- 助手增量会缓冲为聊天 `delta` 消息。 +- 聊天 `final` 会在 **lifecycle end/error** 时发出。 ## 超时 -- `agent.wait` 默认值：30 秒（仅等待）。`timeoutMs` 参数可覆盖。 -- 智能体运行时：`agents.defaults.timeoutSeconds` 默认 172800 秒（48 小时）；在 `runEmbeddedPiAgent` 中通过中止计时器强制执行。 -- Cron 运行时：隔离的智能体轮次 `timeoutSeconds` 归 cron 所有。调度器在执行开始时启动该计时器，在配置的截止时间中止底层运行，然后在记录超时前执行有界清理，避免陈旧子会话让 lane 卡住。 -- 卡住会话恢复：启用诊断后，`diagnostics.stuckSessionWarnMs` 会检测长时间 `processing` 的会话。活动嵌入式运行、活动回复操作和活动会话 lane 任务默认仅发出警告；如果诊断显示该会话没有活动工作，watchdog 会释放受影响的会话 lane，使排队的启动工作可以排出。 -- 模型空闲超时：当响应分块未在空闲窗口前到达时，OpenClaw 会中止模型请求。`models.providers..timeoutSeconds` 会为缓慢的本地/自托管提供商延长此空闲 watchdog；否则 OpenClaw 会在配置了 `agents.defaults.timeoutSeconds` 时使用它，并默认封顶为 120 秒。没有显式模型或智能体超时的 cron 触发运行会禁用空闲 watchdog，并依赖 cron 外层超时。 -- 提供商 HTTP 请求超时：`models.providers..timeoutSeconds` 适用于该提供商的模型 HTTP fetch，包括连接、headers、body、SDK 请求超时、总体受保护 fetch 中止处理和模型流空闲 watchdog。对于 Ollama 等缓慢的本地/自托管提供商，应先使用此项，再提高整个智能体运行时超时。 +- `agent.wait` 默认值：30 秒（仅等待）。`timeoutMs` 参数会覆盖。 +- 智能体运行时：`agents.defaults.timeoutSeconds` 默认值为 172800 秒（48 小时）；在 `runEmbeddedPiAgent` 中由中止计时器强制执行。 +- Cron 运行时：隔离智能体轮次的 `timeoutSeconds` 由 cron 拥有。调度器在执行开始时启动该计时器，在配置的截止时间中止底层运行，然后在记录超时前运行有界清理，确保陈旧子会话不会让通道卡住。 +- 卡住会话恢复：启用诊断后，`diagnostics.stuckSessionWarnMs` 会检测长时间处于 `processing` 的会话。默认情况下，活跃嵌入式运行、活跃回复操作和活跃会话通道任务仅发出警告；如果诊断显示该会话没有活跃工作，watchdog 会释放受影响的会话通道，使排队的启动工作可以排空。 +- 模型空闲超时：当空闲窗口到期前未收到响应块时，OpenClaw 会中止模型请求。`models.providers..timeoutSeconds` 会为缓慢的本地/自托管提供商扩展此空闲 watchdog；否则，OpenClaw 会在已配置时使用 `agents.defaults.timeoutSeconds`，默认上限为 120 秒。没有显式模型或智能体超时的 cron 触发运行会禁用空闲 watchdog，并依赖 cron 外层超时。 +- 提供商 HTTP 请求超时：`models.providers..timeoutSeconds` 适用于该提供商的模型 HTTP fetch，包括连接、headers、body、SDK 请求超时、总 guarded-fetch 中止处理，以及模型流空闲 watchdog。对于 Ollama 等缓慢的本地/自托管提供商，应先使用此项，再提高整个智能体运行时超时。 ## 可能提前结束的位置 @@ -182,8 +171,8 @@ OpenClaw 插件钩子保留为已记录镜像 ## 相关 -- [Tools](/zh-CN/tools) — 可用的智能体工具 +- [工具](/zh-CN/tools) — 可用的智能体工具 - [Hooks](/zh-CN/automation/hooks) — 由智能体生命周期事件触发的事件驱动脚本 -- [Compaction](/zh-CN/concepts/compaction) — 长对话如何被摘要 -- [Exec Approvals](/zh-CN/tools/exec-approvals) — shell 命令的审批门禁 -- [Thinking](/zh-CN/tools/thinking) — thinking/reasoning 级别配置 +- [压缩](/zh-CN/concepts/compaction) — 长对话如何摘要 +- [Exec Approvals](/zh-CN/tools/exec-approvals) — shell 命令的批准门禁 +- [思考](/zh-CN/tools/thinking) — 思考/推理级别配置 diff --git a/docs/zh-CN/concepts/queue.md b/docs/zh-CN/concepts/queue.md index 30fbed5b8..6484b21d5 100644 --- a/docs/zh-CN/concepts/queue.md +++ b/docs/zh-CN/concepts/queue.md @@ -1,58 +1,62 @@ --- read_when: - - 更改自动回复执行或并发设置 - - 说明 /queue 模式或消息导向行为 -summary: 自动回复队列模式、默认值和按会话覆盖 + - 更改自动回复执行或并发 + - 解释 /queue 模式或消息引导行为 +summary: 自动回复队列模式、默认值和按会话覆盖设置 title: 命令队列 x-i18n: - generated_at: "2026-04-30T00:29:38Z" + generated_at: "2026-04-30T18:26:37Z" model: gpt-5.5 provider: openai - source_hash: 2ac0c0ded9558b080714fa4b8be0d552f985911bf19b427020f9654ae4955b2d + source_hash: fbf1bb1ffd4ce06fa138f63e31651b8821226d9c95dd6b93d68326a5fb91fdd0 source_path: concepts/queue.md workflow: 16 --- -我们通过一个很小的进程内队列串行化入站自动回复运行（所有渠道），以防多个 agent 运行相互冲突，同时仍允许跨会话的安全并行。 +我们通过一个极小的进程内队列串行化入站自动回复运行（所有渠道），以防止多个智能体运行相互冲突，同时仍允许跨会话安全并行。 -## 为什么 +## 原因 -- 自动回复运行可能很昂贵（LLM 调用），并且在多条入站消息接近同时到达时可能发生冲突。 -- 串行化可以避免竞争共享资源（会话文件、日志、CLI stdin），并降低触发上游速率限制的概率。 +- 自动回复运行可能开销较高（LLM 调用），并且当多条入站消息接近同时到达时可能发生冲突。 +- 串行化可避免争用共享资源（会话文件、日志、CLI stdin），并降低触发上游速率限制的概率。 -## 工作原理 +## 工作方式 -- 一个感知 lane 的 FIFO 队列会按可配置的并发上限排空每个 lane（未配置 lane 默认 1；main 默认 4，subagent 默认 8）。 -- `runEmbeddedPiAgent` 按**会话键**（lane `session:`）入队，保证每个会话同时只有一个活跃运行。 -- 每个会话运行随后会被排入一个**全局 lane**（默认 `main`），因此总体并行度受 `agents.defaults.maxConcurrent` 限制。 -- 启用详细日志时，如果已排队的运行在开始前等待超过约 2 秒，会发出一条简短提示。 -- 输入状态指示器仍会在入队时立即触发（如果渠道支持），因此在等待轮到我们期间，用户体验保持不变。 +- 一个感知 lane 的 FIFO 队列会按可配置的并发上限排空每个 lane（未配置的 lane 默认值为 1；main 默认值为 4，subagent 默认值为 8）。 +- `runEmbeddedPiAgent` 按 **会话键**（lane `session:`）入队，以保证每个会话同一时间只有一个活动运行。 +- 然后，每个会话运行都会被排入一个 **全局 lane**（默认 `main`），使整体并行度受 `agents.defaults.maxConcurrent` 限制。 +- 启用详细日志时，如果排队的运行在开始前等待超过约 2 秒，会发出一条简短通知。 +- 输入指示器仍会在入队时立即触发（如果渠道支持），因此用户体验在等待轮到我们时保持不变。 ## 默认值 -未设置时，所有入站渠道表面都使用： +未设置时，所有入站渠道界面使用： - `mode: "steer"` - `debounceMs: 500` - `cap: 20` - `drop: "summarize"` -`steer` 是默认值，因为它能让活跃模型轮次保持响应，而不启动第二个会话运行。它会排空在下一个模型边界之前到达的所有 steering 消息。如果当前运行无法接受 steering，OpenClaw 会回退到一个 followup 队列条目。 +`steer` 是默认值，因为它能保持活动模型轮次响应迅速，而无需 +启动第二个会话运行。它会排空在下一个模型边界之前到达的所有 Steering 消息。如果当前运行无法接受 steering， +OpenClaw 会回退到一个 followup 队列条目。 ## 队列模式 入站消息可以 steer 当前运行、等待 followup 轮次，或两者都做： -- `steer`：将 steering 消息排入活跃运行时。Pi 会在**当前助手轮次完成其工具调用执行后**、下一次 LLM 调用前交付所有待处理的 steering 消息；Codex app-server 会接收一个批量的 `turn/steer`。如果运行未处于活跃流式传输状态，或 steering 不可用，OpenClaw 会回退到一个 followup 队列条目。 -- `queue`（旧版）：旧的一次一个 steering。Pi 会在每个模型边界交付一条已排队的 steering 消息；Codex app-server 会接收单独的 `turn/steer` 请求。除非你需要之前的串行化行为，否则优先使用 `steer`。 -- `followup`：将每条消息入队，以便在当前运行结束后的后续 agent 轮次中处理。 -- `collect`：在安静窗口之后，将已排队的消息合并为**单个** followup 轮次。如果消息目标是不同渠道/线程，它们会分别排空以保留路由。 -- `steer-backlog`（又名 `steer+backlog`）：现在 steer，**并且**保留同一条消息用于 followup 轮次。 -- `interrupt`（旧版）：中止该会话的活跃运行，然后运行最新消息。 +- `steer`：将 Steering 消息排入活动运行时。Pi 会在 **当前 assistant 轮次执行完其工具调用之后**、下一次 LLM 调用之前，交付所有待处理的 Steering 消息；Codex app-server 会接收一个批量的 `turn/steer`。如果该运行未处于活动流式传输状态，或 steering 不可用，OpenClaw 会回退到一个 followup 队列条目。 +- `queue`（旧版）：旧的一次一条 steering。Pi 会在每个模型边界交付一条排队的 Steering 消息；Codex app-server 会接收单独的 `turn/steer` 请求。除非你需要以前的串行化行为，否则优先使用 `steer`。 +- `followup`：在当前运行结束后，将每条消息入队，供后续智能体轮次处理。 +- `collect`：在静默窗口之后，将排队的消息合并为 **单个** followup 轮次。如果消息面向不同渠道/线程，它们会单独排空以保留路由。 +- `steer-backlog`（也称为 `steer+backlog`）：立即 steer，**并且** 保留同一条消息用于 followup 轮次。 +- `interrupt`（旧版）：中止该会话的活动运行，然后运行最新消息。 -Steer-backlog 意味着你可能会在 steered 运行之后得到 followup 响应，因此流式传输表面看起来可能像重复。若你希望每条入站消息只得到一个响应，请优先使用 `collect`/`steer`。 +Steer-backlog 表示你可能会在被 steered 的运行之后得到一个 followup 响应，因此 +流式传输界面可能看起来像重复响应。如果你希望每条入站消息只有 +一个响应，请优先使用 `collect`/`steer`。 -有关特定运行时的时序和依赖行为，请参见 +有关特定运行时的时序和依赖行为，请参阅 [Steering queue](/zh-CN/concepts/queue-steering)。 通过 `messages.queue` 进行全局配置或按渠道配置： @@ -75,46 +79,50 @@ Steer-backlog 意味着你可能会在 steered 运行之后得到 followup 响 选项适用于 `followup`、`collect` 和 `steer-backlog`（也适用于 steering 回退到 followup 时的 `steer` 或旧版 `queue`）： -- `debounceMs`：排空已排队 followup 前的安静窗口。裸数字表示毫秒；`/queue` 选项接受单位 `ms`、`s`、`m`、`h` 和 `d`。 -- `cap`：每个会话的最大排队消息数。低于 `1` 的值会被忽略。 -- `drop: "summarize"`：默认值。按需丢弃最旧的队列条目，保留紧凑摘要，并将其作为合成 followup prompt 注入。 -- `drop: "old"`：按需丢弃最旧的队列条目，不保留摘要。 +- `debounceMs`：排空排队 followup 之前的静默窗口。裸数字表示毫秒；`/queue` 选项接受单位 `ms`、`s`、`m`、`h` 和 `d`。 +- `cap`：每个会话最多排队的消息数。低于 `1` 的值会被忽略。 +- `drop: "summarize"`：默认值。按需丢弃最旧的排队条目，保留紧凑摘要，并将其作为合成 followup prompt 注入。 +- `drop: "old"`：按需丢弃最旧的排队条目，不保留摘要。 - `drop: "new"`：当队列已满时拒绝最新消息。 默认值：`debounceMs: 500`、`cap: 20`、`drop: summarize`。 ## 优先级 -对于模式选择，OpenClaw 按以下顺序解析： +对于模式选择，OpenClaw 的解析顺序为： -1. 内联或已存储的每会话 `/queue` 覆盖。 +1. 内联或已存储的按会话 `/queue` 覆盖。 2. `messages.queue.byChannel.`。 3. `messages.queue.mode`。 4. 默认 `steer`。 -对于选项，内联或已存储的 `/queue` 选项优先于配置。然后依次应用渠道特定 debounce（`messages.queue.debounceMsByChannel`）、插件 debounce 默认值、全局 `messages.queue` 选项以及内置默认值。`cap` 和 `drop` 是全局/会话选项，不是按渠道的配置键。 +对于选项，内联或已存储的 `/queue` 选项优先于配置。然后依次应用 +渠道特定 debounce（`messages.queue.debounceMsByChannel`）、插件 +debounce 默认值、全局 `messages.queue` 选项以及内置默认值。`cap` 和 `drop` 是全局/会话选项，而不是按渠道的配置 +键名。 -## 每会话覆盖 +## 按会话覆盖 -- 发送 `/queue ` 作为独立命令，以存储当前会话的模式。 -- 选项可以组合：`/queue collect debounce:0.5s cap:25 drop:summarize` +- 将 `/queue ` 作为独立命令发送，以存储当前会话的模式。 +- 选项可以组合使用：`/queue collect debounce:0.5s cap:25 drop:summarize` - `/queue default` 或 `/queue reset` 会清除会话覆盖。 -## 范围和保证 +## 范围与保证 -- 适用于所有使用 Gateway 网关回复管线的入站渠道中的自动回复 agent 运行（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat 等）。 -- 默认 lane（`main`）对入站 + 主 Heartbeat 是进程级的；设置 `agents.defaults.maxConcurrent` 可允许多个会话并行运行。 -- 可能存在额外 lane（例如 `cron`、`cron-nested`、`nested`、`subagent`），因此后台作业可以并行运行，而不会阻塞入站回复。隔离的 cron agent 轮次会持有一个 `cron` 槽位，而其内部 agent 执行使用 `cron-nested`；两者都使用 `cron.maxConcurrentRuns`。共享的非 cron `nested` 流程会保持自身的 lane 行为。这些分离运行会作为[后台任务](/zh-CN/automation/tasks)被跟踪。 -- 每会话 lane 保证同一时间只有一个 agent 运行会触碰给定会话。 +- 适用于所有使用 Gateway 网关回复管线的入站渠道中的自动回复智能体运行（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat 等）。 +- 默认 lane（`main`）在进程范围内用于入站 + 主 Heartbeat；设置 `agents.defaults.maxConcurrent` 以允许多个会话并行。 +- 可能存在其他 lane（例如 `cron`、`cron-nested`、`nested`、`subagent`），以便后台作业可以并行运行，而不会阻塞入站回复。隔离的 cron 智能体轮次在其内部智能体执行使用 `cron-nested` 时会占用一个 `cron` slot；两者都使用 `cron.maxConcurrentRuns`。共享的非 cron `nested` 流程会保留自身的 lane 行为。这些分离运行会作为 [后台任务](/zh-CN/automation/tasks) 跟踪。 +- 按会话 lane 保证同一时间只有一个智能体运行会触及给定会话。 - 无外部依赖或后台 worker 线程；纯 TypeScript + promises。 ## 故障排除 -- 如果命令看起来卡住，请启用详细日志并查找 “queued for …ms” 行，以确认队列正在排空。 +- 如果命令似乎卡住，请启用详细日志并查找 “queued for …ms” 行，以确认队列正在排空。 - 如果你需要队列深度，请启用详细日志并观察队列时序行。 -- 启用诊断后，在超过 `diagnostics.stuckSessionWarnMs` 后仍停留在 `processing` 的会话会记录一条 stuck-session 警告。活跃的嵌入式运行、活跃的回复操作以及活跃的 lane 任务默认仍仅发出警告；没有活跃会话工作的过期启动簿记可以释放受影响的会话 lane，使已排队工作得以排空。 +- Codex app-server 中接受一个轮次后停止发出进度的运行，会由 Codex adapter 中断，以便活动会话 lane 可以释放，而不是等待外层运行超时。 +- 启用诊断时，保持 `processing` 超过 `diagnostics.stuckSessionWarnMs` 的会话会记录卡住会话警告。默认情况下，活动嵌入式运行、活动回复操作和活动 lane 任务仍仅发出警告；如果陈旧的启动记账没有活动会话工作，则可以释放受影响的会话 lane，使排队工作得以排空。 -## 相关 +## 相关内容 - [会话管理](/zh-CN/concepts/session) - [Steering queue](/zh-CN/concepts/queue-steering)