From e28a94bb79a83da04406e9cca989f34a1fbcf7b3 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 29 Apr 2026 09:15:46 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/automation/index.md | 130 ++++---- docs/zh-CN/ci.md | 343 ++++++++++--------- docs/zh-CN/gateway/config-agents.md | 463 +++++++++++++------------- docs/zh-CN/gateway/heartbeat.md | 205 ++++++------ docs/zh-CN/gateway/troubleshooting.md | 302 ++++++++--------- 5 files changed, 715 insertions(+), 728 deletions(-) diff --git a/docs/zh-CN/automation/index.md b/docs/zh-CN/automation/index.md index 28c98a1ff..67079e525 100644 --- a/docs/zh-CN/automation/index.md +++ b/docs/zh-CN/automation/index.md @@ -1,123 +1,121 @@ --- read_when: - 决定如何使用 OpenClaw 自动化工作 - - 在 heartbeat、cron、钩子和常设指令之间进行选择 + - 在心跳、cron、钩子和长期指令之间选择 - 寻找合适的自动化入口点 -summary: 自动化机制概览：任务、cron、钩子、常设指令和任务流 +summary: 自动化机制概览：任务、定时任务、钩子、常驻指令和任务流 title: 自动化与任务 x-i18n: - generated_at: "2026-04-26T01:45:57Z" - model: gpt-5.4 + generated_at: "2026-04-29T09:12:56Z" + model: gpt-5.5 provider: openai - source_hash: 6d2a2d3ef58830133e07b34f33c611664fc1032247e9dd81005adf7fc0c43cdb + source_hash: da79bdd32a231f90850697b94bf061a778e9d0ad81420119ccd3fa0d3bc16fc1 source_path: automation/index.md - workflow: 15 + workflow: 16 --- -OpenClaw 通过任务、定时作业、事件钩子和常设指令在后台运行工作。本页将帮助你选择合适的机制，并理解它们如何协同工作。 +OpenClaw 通过任务、计划作业、事件钩子和常设指令在后台运行工作。本页帮助你选择合适的机制，并了解它们如何配合。 ## 快速决策指南 ```mermaid flowchart TD - START([你需要什么？]) --> Q1{安排工作时间？} - START --> Q2{跟踪分离的工作？} - START --> Q3{编排多步骤流程？} - START --> Q4{响应生命周期事件？} - START --> Q5{给智能体持久指令？} + START([What do you need?]) --> Q1{Schedule work?} + START --> Q2{Track detached work?} + START --> Q3{Orchestrate multi-step flows?} + START --> Q4{React to lifecycle events?} + START --> Q5{Give the agent persistent instructions?} - Q1 -->|是| Q1a{精确时间还是灵活时间？} - Q1a -->|精确| CRON["定时任务（Cron）"] - Q1a -->|灵活| HEARTBEAT[Heartbeat] + Q1 -->|Yes| Q1a{Exact timing or flexible?} + Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"] + Q1a -->|Flexible| HEARTBEAT[Heartbeat] - Q2 -->|是| TASKS[后台任务] - Q3 -->|是| FLOW[任务流] - Q4 -->|是| HOOKS[钩子] - Q5 -->|是| SO[常设指令] + Q2 -->|Yes| TASKS[Background Tasks] + Q3 -->|Yes| FLOW[Task Flow] + Q4 -->|Yes| HOOKS[Hooks] + Q5 -->|Yes| SO[Standing Orders] ``` -| 用例 | 推荐方案 | 原因 | +| 用例 | 推荐 | 原因 | | --------------------------------------- | ---------------------- | ------------------------------------------------ | -| 每天早上 9 点准时发送日报 | 定时任务（Cron） | 时间精确，执行隔离 | -| 20 分钟后提醒我 | 定时任务（Cron） | 一次性任务，时间精确（`--at`） | -| 每周运行一次深度分析 | 定时任务（Cron） | 独立任务，可使用不同模型 | -| 每 30 分钟检查一次收件箱 | Heartbeat | 与其他检查批量处理，具备上下文感知 | -| 监控日历中的即将到来事件 | Heartbeat | 非常适合周期性感知 | -| 检查子智能体或 ACP 运行的状态 | 后台任务 | 任务台账会跟踪所有分离工作 | -| 审计运行了什么以及何时运行 | 后台任务 | `openclaw tasks list` 和 `openclaw tasks audit` | -| 先进行多步骤研究再总结 | 任务流 | 具备修订跟踪的持久化编排 | -| 在会话重置时运行脚本 | 钩子 | 事件驱动，在生命周期事件上触发 | -| 在每次工具调用时执行代码 | 插件钩子 | 进程内钩子可拦截工具调用 | -| 回复前始终检查合规性 | 常设指令 | 自动注入到每个会话中 | +| 在上午 9 点准时发送每日报告 | 计划任务（Cron） | 精确计时，隔离执行 | +| 20 分钟后提醒我 | 计划任务（Cron） | 使用精确计时的一次性任务（`--at`） | +| 运行每周深度分析 | 计划任务（Cron） | 独立任务，可使用不同模型 | +| 每 30 分钟检查收件箱 | 心跳 | 与其他检查批处理，感知上下文 | +| 监控日历中的即将到来的事件 | 心跳 | 自然适合周期性感知 | +| 检查子智能体或 ACP 运行的状态 | 后台任务 | 任务账本会跟踪所有分离的工作 | +| 审计运行了什么以及何时运行 | 后台任务 | `openclaw tasks list` 和 `openclaw tasks audit` | +| 多步骤研究后总结 | 任务流 | 带修订跟踪的持久编排 | +| 在会话重置时运行脚本 | 钩子 | 事件驱动，在生命周期事件上触发 | +| 每次工具调用时执行代码 | 插件钩子 | 进程内钩子可以拦截工具调用 | +| 回复前始终检查合规性 | 常设指令 | 自动注入到每个会话 | -### 定时任务（Cron）与 Heartbeat 的区别 +### 计划任务（Cron）与心跳 -| 维度 | 定时任务（Cron） | Heartbeat | +| 维度 | 计划任务（Cron） | 心跳 | | --------------- | ----------------------------------- | ------------------------------------- | -| 时间安排 | 精确（cron 表达式、一次性） | 近似（默认每 30 分钟） | -| 会话上下文 | 全新（隔离）或共享 | 完整的主会话上下文 | -| 任务记录 | 始终创建 | 从不创建 | -| 结果投递 | 渠道、webhook 或静默 | 在主会话中内联显示 | -| 最适合 | 报告、提醒、后台作业 | 收件箱检查、日历、通知 | +| 计时 | 精确（cron 表达式、一次性任务） | 近似（默认每 30 分钟） | +| 会话上下文 | 全新（隔离）或共享 | 完整主会话上下文 | +| 任务记录 | 始终创建 | 从不创建 | +| 交付 | 渠道、webhook 或静默 | 内联在主会话中 | +| 最适合 | 报告、提醒、后台作业 | 收件箱检查、日历、通知 | -当你需要精确定时或隔离执行时，使用定时任务（Cron）。当工作受益于完整会话上下文，且近似时间安排即可时，使用 Heartbeat。 +当你需要精确计时或隔离执行时，使用计划任务（Cron）。当工作受益于完整会话上下文且近似计时可以接受时，使用心跳。 ## 核心概念 -### 定时任务（cron） +### 计划任务（cron） -Cron 是 Gateway 网关内置的精确定时调度器。它会持久化作业，在合适时间唤醒智能体，并可将输出投递到聊天渠道或 webhook 端点。支持一次性提醒、周期性表达式和入站 webhook 触发器。 +Cron 是 Gateway 网关内置的精确计时调度器。它会持久化作业，在正确时间唤醒智能体，并可将输出交付到聊天渠道或 webhook 端点。支持一次性提醒、重复表达式和入站 webhook 触发器。 -参见 [定时任务](/zh-CN/automation/cron-jobs)。 +参见[计划任务](/zh-CN/automation/cron-jobs)。 ### 任务 -后台任务台账会跟踪所有分离工作：ACP 运行、子智能体生成、隔离的 cron 执行以及 CLI 操作。任务是记录，而不是调度器。使用 `openclaw tasks list` 和 `openclaw tasks audit` 进行查看。 +后台任务账本跟踪所有分离的工作：ACP 运行、子智能体生成、隔离 cron 执行和 CLI 操作。任务是记录，不是调度器。使用 `openclaw tasks list` 和 `openclaw tasks audit` 检查它们。 -参见 [后台任务](/zh-CN/automation/tasks)。 +参见[后台任务](/zh-CN/automation/tasks)。 ### 任务流 -任务流是位于后台任务之上的流程编排基础层。它通过托管和镜像同步模式、修订跟踪，以及 `openclaw tasks flow list|show|cancel` 检查命令，来管理持久化的多步骤流程。 +任务流是后台任务之上的流程编排基底。它通过托管和镜像同步模式、修订跟踪，以及用于检查的 `openclaw tasks flow list|show|cancel`，来管理持久的多步骤流程。 -参见 [任务流](/zh-CN/automation/taskflow)。 +参见[任务流](/zh-CN/automation/taskflow)。 ### 常设指令 -常设指令为已定义程序授予智能体永久性的操作权限。它们保存在工作区文件中（通常是 `AGENTS.md`），并注入到每个会话中。可与 cron 结合，以实现基于时间的执行约束。 +常设指令授予智能体对已定义程序的永久操作权限。它们位于工作区文件中（通常为 `AGENTS.md`），并会注入到每个会话中。可与 cron 结合，用于基于时间的执行。 -参见 [常设指令](/zh-CN/automation/standing-orders)。 +参见[常设指令](/zh-CN/automation/standing-orders)。 ### 钩子 -内部钩子是由智能体生命周期事件 -（`/new`、`/reset`、`/stop`）、会话压缩、Gateway 网关启动以及消息流触发的事件驱动脚本。系统会自动从目录中发现它们，并可通过 `openclaw hooks` 进行管理。对于进程内的工具调用拦截，请使用 -[插件钩子](/zh-CN/plugins/hooks)。 +内部钩子是由智能体生命周期事件（`/new`、`/reset`、`/stop`）、会话压缩、Gateway 网关启动和消息流触发的事件驱动脚本。它们会从目录中自动发现，并可通过 `openclaw hooks` 管理。对于进程内工具调用拦截，请使用[插件钩子](/zh-CN/plugins/hooks)。 -参见 [钩子](/zh-CN/automation/hooks)。 +参见[钩子](/zh-CN/automation/hooks)。 -### Heartbeat +### 心跳 -Heartbeat 是周期性的主会话轮次（默认每 30 分钟一次）。它会在一次智能体轮次中，结合完整会话上下文，批量执行多个检查（收件箱、日历、通知）。Heartbeat 轮次不会创建任务记录，也不会延长每日/空闲会话重置的新鲜度。使用 `HEARTBEAT.md` 可编写简短检查清单；如果你希望在 heartbeat 内部执行仅在到期时运行的周期性检查，可使用 `tasks:` 代码块。空的 heartbeat 文件会以 `empty-heartbeat-file` 跳过；仅到期任务模式会以 `no-tasks-due` 跳过。 +心跳是周期性的主会话轮次（默认每 30 分钟一次）。它在一个带完整会话上下文的智能体轮次中批处理多个检查（收件箱、日历、通知）。心跳轮次不会创建任务记录，也不会延长每日/空闲会话重置的新鲜度。使用 `HEARTBEAT.md` 放置一个小型清单；如果你希望在心跳自身内部进行仅到期的周期性检查，也可以使用 `tasks:` 块。空心跳文件会以 `empty-heartbeat-file` 跳过；仅到期任务模式会以 `no-tasks-due` 跳过。当 cron 工作处于活动或排队状态时，心跳会延后；`heartbeat.skipWhenBusy` 也可以在子智能体或嵌套通道繁忙时延后心跳。 -参见 [Heartbeat](/zh-CN/gateway/heartbeat)。 +参见[心跳](/zh-CN/gateway/heartbeat)。 -## 它们如何协同工作 +## 它们如何配合 -- **Cron** 处理精确定时安排（日报、每周回顾）和一次性提醒。所有 cron 执行都会创建任务记录。 -- **Heartbeat** 每 30 分钟在一次批处理轮次中处理常规监控（收件箱、日历、通知）。 -- **钩子** 响应特定事件（会话重置、压缩、消息流），运行自定义脚本。插件钩子负责工具调用。 +- **Cron** 处理精确计划（每日报告、每周回顾）和一次性提醒。所有 cron 执行都会创建任务记录。 +- **心跳** 在每 30 分钟一次的批处理轮次中处理例行监控（收件箱、日历、通知）。 +- **钩子** 通过自定义脚本响应特定事件（会话重置、压缩、消息流）。插件钩子覆盖工具调用。 - **常设指令** 为智能体提供持久上下文和权限边界。 - **任务流** 在单个任务之上协调多步骤流程。 -- **任务** 会自动跟踪所有分离工作，便于你检查和审计。 +- **任务** 自动跟踪所有分离的工作，以便你检查和审计。 ## 相关内容 -- [定时任务](/zh-CN/automation/cron-jobs) — 精确定时安排和一次性提醒 -- [后台任务](/zh-CN/automation/tasks) — 所有分离工作的任务台账 -- [任务流](/zh-CN/automation/taskflow) — 持久化的多步骤流程编排 +- [计划任务](/zh-CN/automation/cron-jobs) — 精确调度和一次性提醒 +- [后台任务](/zh-CN/automation/tasks) — 所有分离工作的任务账本 +- [任务流](/zh-CN/automation/taskflow) — 持久的多步骤流程编排 - [钩子](/zh-CN/automation/hooks) — 事件驱动的生命周期脚本 -- [插件钩子](/zh-CN/plugins/hooks) — 进程内工具、提示词、消息和生命周期钩子 -- [常设指令](/zh-CN/automation/standing-orders) — 持久化智能体指令 -- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性的主会话轮次 +- [插件钩子](/zh-CN/plugins/hooks) — 进程内工具、提示、消息和生命周期钩子 +- [常设指令](/zh-CN/automation/standing-orders) — 持久智能体指令 +- [心跳](/zh-CN/gateway/heartbeat) — 周期性主会话轮次 - [配置参考](/zh-CN/gateway/configuration-reference) — 所有配置键 diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index 45165c068..7fbd6c7d5 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -2,66 +2,67 @@ read_when: - 你需要了解某个 CI 作业为什么运行或未运行 - 你正在调试失败的 GitHub Actions 检查 -summary: CI 作业图、范围门禁和本地命令等效项 +summary: CI 作业图、范围门禁和本地命令等价项 title: CI 流水线 x-i18n: - generated_at: "2026-04-29T08:14:30Z" + generated_at: "2026-04-29T09:12:46Z" model: gpt-5.5 provider: openai - source_hash: fedb986b861ed53f97cb94eecd17b94b1f49008070fb87fb0fad8848ede82fb7 + source_hash: fe934a27ac3ad314869c9a3995fb83d0fa1bda61f6e31508ce518ce601b0e3d2 source_path: ci.md workflow: 16 --- -CI 在每次推送到 `main` 以及每个拉取请求时运行。它使用智能范围限定，在只有无关区域发生更改时跳过昂贵的作业。手动 `workflow_dispatch` 运行会有意绕过智能范围限定，并展开完整的常规 CI 图，用于候选发布版本或广泛验证；对于独立手动运行，Android 通道可通过 `include_android` 选择启用。仅发布用的插件预发布通道位于单独的 `Plugin Prerelease` 工作流中，并且只会从 `Full Release Validation` 或显式手动调度运行。 +CI 会在每次推送到 `main` 和每个拉取请求时运行。它使用智能范围划分，在只有无关区域发生变化时跳过昂贵的作业。手动 `workflow_dispatch` 运行会有意绕过智能范围划分，并为候选发布或广泛验证展开完整的常规 CI 图；对于独立的手动运行，Android lane 可通过 `include_android` 选择启用。仅发布使用的插件预发布 lane 位于单独的 `Plugin Prerelease` 工作流中，并且只会从 `Full Release Validation` 或显式手动调度运行。 -`check-dependencies` 分片会运行 `pnpm deadcode:dependencies`，这是一次生产 Knip 仅依赖项检查，固定到该脚本使用的最新 Knip 版本，并且在 `dlx` 安装时禁用 pnpm 的最小发布时间限制。它会拦截新出现的未使用、未列出、无法解析、二进制或 catalog 依赖项，但不会启用 Knip 的完整未使用文件模式；后者仍然是手动审计，因为 OpenClaw 会有意通过 manifests 和字符串 specifier 加载许多插件与运行时表面。 +`check-dependencies` 分片会运行 `pnpm deadcode:dependencies`，这是一个仅用于生产 Knip 依赖项的检查流程，固定到该脚本使用的最新 Knip 版本，并且为 `dlx` 安装禁用 pnpm 的最小发布年龄。它会拦截新增的未使用、未列出、未解析、二进制或目录依赖项，但不会启用 Knip 的完整未使用文件模式；后者仍然是手动审计，因为 OpenClaw 有意通过清单和字符串说明符加载许多插件和运行时表面。 -`Full Release Validation` 是用于“发布前运行所有内容”的手动总控工作流。它接受分支、标签或完整提交 SHA，使用该目标调度手动 `CI` 工作流，调度 `Plugin Prerelease` 以提供仅发布用的插件/包/静态/Docker 证明，并调度 `OpenClaw Release Checks` 以执行安装冒烟、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 通道。提供已发布包 spec 时，它还可以运行发布后的 `NPM Telegram Beta E2E` 工作流。`release_profile=minimum|stable|full` 控制传递给发布检查的 live/provider 覆盖范围：`minimum` 保留最快的 OpenAI/核心发布关键通道，`stable` 添加稳定的提供商/后端集合，`full` 运行广泛的 advisory provider/media 矩阵。总控工作流会记录已调度的子运行 ID，最终的 `Verify full validation` 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流重新运行后变为绿色，只需重新运行父验证器作业，以刷新总控结果和耗时摘要。 +`Full Release Validation` 是“发布前运行所有内容”的手动总控工作流。它接受分支、标签或完整提交 SHA，使用该目标调度手动 `CI` 工作流，调度 `Plugin Prerelease` 以提供仅发布使用的插件、包、静态和 Docker 证明，并调度 `OpenClaw Release Checks` 以执行安装冒烟、包验收、Docker 发布路径套件、实时/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram lane。提供已发布包规范时，它还可以运行发布后的 `NPM Telegram Beta E2E` 工作流。`release_profile=minimum|stable|full` 控制传入发布检查的实时/提供商覆盖宽度：`minimum` 保留最快的 OpenAI/核心发布关键 lane，`stable` 增加稳定的提供商/后端集合，`full` 运行广泛的建议提供商/媒体矩阵。该总控工作流会记录已调度的子运行 ID，最终的 `Verify full validation` 作业会重新检查当前子运行结论，并为每个子运行追加最慢作业表。如果某个子工作流重新运行后变绿，只需重新运行父验证器作业即可刷新总控结果和计时摘要。 -对于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。候选发布版本使用 `all`，只运行常规完整 CI 子项使用 `ci`，运行每个发布子项使用 `release-checks`，也可以在总控工作流中使用更窄的发布分组：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这样可以在完成聚焦修复后，将失败发布盒子的重新运行限制在有界范围内。 +对于恢复，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。对候选发布使用 `all`，仅对常规完整 CI 子项使用 `ci`，对每个发布子项使用 `release-checks`，或在总控中使用更窄的发布组：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。这会让一次失败的发布盒在针对性修复后保持重新运行范围有界。 -发布 live/E2E 子项保留广泛的原生 `pnpm test:live` 覆盖，但会通过 `scripts/test-live-shard.mjs` 将其作为命名分片运行（`native-live-src-agents`、`native-live-src-gateway-core`、按提供商过滤的 `native-live-src-gateway-profiles` 作业、`native-live-src-gateway-backends`、`native-live-test`、`native-live-extensions-a-k`、`native-live-extensions-l-n`、`native-live-extensions-openai`、`native-live-extensions-o-z-other`、`native-live-extensions-xai`、拆分的 media 音频/视频分片，以及按提供商过滤的音乐分片），而不是一个串行作业。这样保持相同文件覆盖的同时，让缓慢的 live provider 失败更容易重新运行和诊断。聚合的 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名称仍可用于手动一次性重新运行。 +发布实时/E2E 子项保留广泛的原生 `pnpm test:live` 覆盖，但它通过 `scripts/test-live-shard.mjs` 将其作为命名分片运行（`native-live-src-agents`、`native-live-src-gateway-core`、按提供商过滤的 `native-live-src-gateway-profiles` 作业、`native-live-src-gateway-backends`、`native-live-test`、`native-live-extensions-a-k`、`native-live-extensions-l-n`、`native-live-extensions-openai`、`native-live-extensions-o-z-other`、`native-live-extensions-xai`、拆分的媒体音频/视频分片，以及按提供商过滤的音乐分片），而不是一个串行作业。这样可以保持相同的文件覆盖，同时让缓慢的实时提供商失败更容易重新运行和诊断。聚合的 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名称仍然可用于手动一次性重新运行。 -原生 live media 分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中运行，该镜像由 `Live Media Runner Image` 工作流构建。该镜像预装 `ffmpeg` 和 `ffprobe`；media 作业只会在设置前验证这些二进制文件。将基于 Docker 的 live 套件保留在普通 Blacksmith runner 上，因为容器作业并不适合启动嵌套 Docker 测试。 +原生实时媒体分片运行在 `Live Media Runner Image` 工作流构建的 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中。该镜像预安装了 `ffmpeg` 和 `ffprobe`；媒体作业只会在设置前验证这些二进制文件。请将 Docker 支撑的实时套件保留在常规 Blacksmith runner 上，因为容器作业并不适合启动嵌套 Docker 测试。 -基于 Docker 的 live 模型/后端分片会针对每个选定提交使用单独的共享 `ghcr.io/openclaw/openclaw-live-test:` 镜像。live 发布工作流会构建并推送一次该镜像，随后 Docker live model、gateway、CLI backend、ACP bind 和 Codex harness 分片会以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。如果这些分片独立重建完整源 Docker 目标，则说明发布运行配置错误，并会在重复镜像构建上浪费总体耗时。 +Docker 支撑的实时模型/后端分片会为每个选定提交使用单独的共享 `ghcr.io/openclaw/openclaw-live-test:` 镜像。实时发布工作流会构建并推送该镜像一次，然后 Docker 实时模型、Gateway 网关、CLI 后端、ACP bind 和 Codex harness 分片会以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行。如果这些分片独立重建完整源 Docker 目标，说明发布运行配置错误，并会把时间浪费在重复镜像构建上。 -`OpenClaw Release Checks` 使用受信任的工作流 ref 将选定 ref 一次性解析为 `release-package-under-test` tarball，然后将该 artifact 传递给 live/E2E 发布路径 Docker 工作流和包验收分片。这样可以让发布盒子之间的包字节保持一致，并避免在多个子作业中重复打包同一个候选版本。 +`OpenClaw Release Checks` 使用受信任的工作流引用将选定引用解析一次为 `release-package-under-test` tarball，然后把该工件传递给实时/E2E 发布路径 Docker 工作流和包验收分片。这样可以让发布盒之间的包字节保持一致，并避免在多个子作业中重新打包同一个候选项。 -`Package Acceptance` 是用于验证包 artifact 的旁路运行工作流，不会阻塞发布工作流。它会从已发布的 npm spec、使用选定 `workflow_ref` harness 构建的受信任 `package_ref`、带 SHA-256 的 HTTPS tarball URL，或来自另一个 GitHub Actions 运行的 tarball artifact 中解析一个候选项，将其作为 `package-under-test` 上传，然后复用 Docker 发布/E2E 调度器，并使用该 tarball，而不是重新打包工作流 checkout。profile 覆盖 smoke、package、product、full 和自定义 Docker 通道选择。`package` profile 使用离线插件覆盖，因此已发布包验证不会受 live ClawHub 可用性约束。可选的 Telegram 通道会在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` artifact，同时保留已发布 npm spec 路径以支持独立调度。 +`Package Acceptance` 是用于验证包工件而不阻塞发布工作流的旁路运行工作流。它会从已发布的 npm 规范、使用选定 `workflow_ref` harness 构建的受信任 `package_ref`、带 SHA-256 的 HTTPS tarball URL，或另一个 GitHub Actions 运行中的 tarball 工件解析一个候选项，将其作为 `package-under-test` 上传，然后复用 Docker 发布/E2E 调度器，并使用该 tarball，而不是重新打包工作流检出。配置文件覆盖冒烟、包、产品、完整和自定义 Docker lane 选择。`package` 配置文件使用离线插件覆盖，因此已发布包验证不会受实时 ClawHub 可用性影响。可选的 Telegram lane 会在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` 工件，同时保留已发布 npm 规范路径用于独立调度。 ## 包验收 -当问题是“这个可安装的 OpenClaw 包作为产品是否可用？”时，使用 `Package Acceptance`。它不同于常规 CI：常规 CI 验证源码树，而包验收通过用户在安装或更新后实际使用的同一个 Docker E2E harness 来验证单个 tarball。 +当问题是“这个可安装的 OpenClaw 包作为产品是否可用？”时，使用 `Package Acceptance`。它不同于常规 CI：常规 CI 验证源代码树，而包验收通过用户在安装或更新后会使用的同一个 Docker E2E harness 来验证单个 tarball。 该工作流有四个作业： -1. `resolve_package` checkout `workflow_ref`，解析一个包候选项，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将两者作为 `package-under-test` artifact 上传，并在 GitHub 步骤摘要中打印来源、工作流 ref、包 ref、版本、SHA-256 和 profile。 -2. `docker_acceptance` 使用 `ref=workflow_ref` 和 `package_artifact_name=package-under-test` 调用 `openclaw-live-and-e2e-checks-reusable.yml`。可复用工作流会下载该 artifact，验证 tarball inventory，在需要时准备 package-digest Docker 镜像，并针对该包运行所选 Docker 通道，而不是打包工作流 checkout。当某个 profile 选择多个目标 `docker_lanes` 时，可复用工作流会先准备一次包和共享镜像，然后将这些通道展开为并行的目标 Docker 作业，并使用唯一 artifact。 -3. `package_telegram` 可选择调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时它会运行，并在 Package Acceptance 已解析包时安装同一个 `package-under-test` artifact；独立 Telegram 调度仍可安装已发布的 npm spec。 -4. 如果包解析、Docker 验收或可选 Telegram 通道失败，`summary` 会使工作流失败。 +1. `resolve_package` 检出 `workflow_ref`，解析一个包候选项，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将两者作为 `package-under-test` 工件上传，并在 GitHub 步骤摘要中打印来源、工作流引用、包引用、版本、SHA-256 和配置文件。 +2. `docker_acceptance` 使用 `ref=workflow_ref` 和 `package_artifact_name=package-under-test` 调用 `openclaw-live-and-e2e-checks-reusable.yml`。可复用工作流会下载该工件，验证 tarball 清单，在需要时准备 package-digest Docker 镜像，并针对该包运行选定的 Docker lane，而不是打包工作流检出。当某个配置文件选择多个目标 `docker_lanes` 时，可复用工作流会准备一次包和共享镜像，然后将这些 lane 展开为并行的目标 Docker 作业，并使用唯一工件。 +3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不是 `none` 时运行，并在包验收解析到包时安装同一个 `package-under-test` 工件；独立 Telegram 调度仍然可以安装已发布的 npm 规范。 +4. `summary` 会在包解析、Docker 验收或可选 Telegram lane 失败时让工作流失败。 -候选来源： +候选项来源： -- `source=npm`：只接受 `openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta/stable 的验收。 -- `source=ref`：打包受信任的 `package_ref` 分支、标签或完整提交 SHA。解析器会 fetch OpenClaw 分支/标签，验证选定提交可从仓库分支历史或发布标签到达，在 detached worktree 中安装依赖，并使用 `scripts/package-openclaw-for-docker.mjs` 打包。 +- `source=npm`：仅接受 `openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta/稳定版验收。 +- `source=ref`：打包受信任的 `package_ref` 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 分支/标签，验证选定提交可从仓库分支历史或发布标签访问，在分离的工作树中安装依赖项，并使用 `scripts/package-openclaw-for-docker.mjs` 打包。 - `source=url`：下载 HTTPS `.tgz`；必须提供 `package_sha256`。 -- `source=artifact`：从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 是可选项，但对于外部共享 artifact 应提供。 +- `source=artifact`：从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 是可选项，但对于外部共享的工件应提供。 -保持 `workflow_ref` 和 `package_ref` 分离。`workflow_ref` 是运行测试的受信任工作流/harness 代码。`package_ref` 是在 `source=ref` 时会被打包的源提交。这样当前测试 harness 就能验证较旧的受信任源提交，而无需运行旧的工作流逻辑。 +保持 `workflow_ref` 和 `package_ref` 分离。`workflow_ref` 是运行测试的受信任工作流/harness 代码。`package_ref` 是 `source=ref` 时会被打包的源提交。这允许当前测试 harness 验证较旧的受信任源提交，而无需运行旧的工作流逻辑。 -profile 映射到 Docker 覆盖范围： +配置文件映射到 Docker 覆盖： - `smoke`：`npm-onboard-channel-agent`、`gateway-network`、`config-reload` - `package`：`npm-onboard-channel-agent`、`doctor-switch`、`update-channel-switch`、`bundled-channel-deps-compat`、`plugins-offline`、`plugin-update` - `product`：`package` 加上 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui` -- `full`：带 OpenWebUI 的完整 Docker 发布路径分块 +- `full`：带 OpenWebUI 的完整 Docker 发布路径块 - `custom`：精确的 `docker_lanes`；当 `suite_profile=custom` 时必填 -发布检查会使用 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'` 和 `telegram_mode=mock-openai` 调用 Package Acceptance。发布路径 Docker 分块覆盖重叠的 package/update/plugin 通道，而 Package Acceptance 则针对同一个已解析包 tarball 保留 artifact 原生的 bundled-channel compat、离线插件和 Telegram 证明。Cross-OS 发布检查仍会覆盖特定于 OS 的 新手引导、安装器和平台行为；package/update 产品验证应从 Package Acceptance 开始。Windows 打包和安装器 fresh 通道还会验证已安装包可以从原始绝对 Windows 路径导入 browser-control override。 +发布检查会使用 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=custom`、`docker_lanes='bundled-channel-deps-compat plugins-offline'` 和 `telegram_mode=mock-openai` 调用包验收。发布路径 Docker 块覆盖重叠的包/更新/插件 lane，而包验收会针对同一个已解析包 tarball 保留工件原生的内置渠道兼容性、离线插件和 Telegram 证明。 +跨 OS 发布检查仍然覆盖 OS 特定的新手引导、安装器和平台行为；包/更新产品验证应从包验收开始。Windows 打包和安装器全新 lane 还会验证已安装包是否可以从原始绝对 Windows 路径导入 browser-control override。 -对于已经发布的包，Package Acceptance 有有界的旧版兼容窗口。截至 `2026.4.25` 的包，包括 `2026.4.25-beta.*`，可对 `dist/postinstall-inventory.json` 中已知的私有 QA 条目使用兼容路径，这些条目指向 tarball 省略的文件；当包未暴露该标志时，`doctor-switch` 可以跳过 `gateway install --wrapper` 持久化子用例；`update-channel-switch` 可以从 tarball 派生的假 git fixture 中裁剪缺失的 `pnpm.patchedDependencies`，并可以记录缺失的已持久化 `update.channel`；插件冒烟可以读取旧版 install-record 位置，或接受 marketplace install-record 持久化缺失；`plugin-update` 可以允许配置元数据迁移，但仍要求 install record 和 no-reinstall 行为保持不变。已发布的 `2026.4.26` 包也可以对已经发布的本地构建元数据 stamp 文件发出警告。之后的包必须满足现代契约；相同条件会失败，而不是警告或跳过。 +对于已经发布的包，包验收有有界的旧版兼容窗口。到 `2026.4.25` 为止的包（包括 `2026.4.25-beta.*`）可以对 `dist/postinstall-inventory.json` 中指向 tarball 省略文件的已知私有 QA 条目使用兼容路径；当包不暴露该标志时，`doctor-switch` 可以跳过 `gateway install --wrapper` 持久化子用例；`update-channel-switch` 可以从 tarball 派生的假 git fixture 中裁剪缺失的 `pnpm.patchedDependencies`，并可以记录缺失的持久化 `update.channel`；插件冒烟可以读取旧版安装记录位置，或接受缺少 marketplace 安装记录持久化；`plugin-update` 可以允许配置元数据迁移，同时仍要求安装记录和不重新安装行为保持不变。已发布的 `2026.4.26` 包也可以对已经发布的本地构建元数据标记文件发出警告。后续包必须满足现代契约；相同条件会失败，而不是警告或跳过。 示例： @@ -104,121 +105,115 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -调试失败的软件包验收运行时，先查看 `resolve_package` -摘要以确认软件包来源、版本和 SHA-256。然后检查 -`docker_acceptance` 子运行及其 Docker 构件： -`.artifacts/docker-tests/**/summary.json`、`failures.json`、通道日志、阶段 -耗时以及重新运行命令。优先重新运行失败的软件包配置文件或 -精确的 Docker 通道，而不是重新运行完整发布验证。 +调试失败的包验收运行时，先查看 `resolve_package` +摘要，确认包来源、版本和 SHA-256。然后检查 +`docker_acceptance` 子运行及其 Docker 工件： +`.artifacts/docker-tests/**/summary.json`、`failures.json`、流水线日志、阶段 +耗时和重跑命令。优先重跑失败的包配置文件或 +精确的 Docker 流水线，而不是重跑完整发布验证。 -QA Lab 在主智能范围工作流之外有专用的 CI 通道。 -`Parity gate` 工作流会在匹配的 PR 变更和手动派发时运行；它会 +QA Lab 在主智能作用域工作流之外有专用 CI 流水线。 +`Parity gate` 工作流会在匹配的 PR 变更和手动分派时运行；它会 构建私有 QA 运行时，并比较模拟 GPT-5.5 和 Opus 4.6 -智能体包。`QA-Lab - All Lanes` 工作流每晚在 `main` 上运行，也会在 -手动派发时运行；它会将模拟一致性门禁、实时 Matrix 通道以及实时 -Telegram 和 Discord 通道扇出为并行作业。实时作业使用 +智能体包。`QA-Lab - All Lanes` 工作流每晚在 `main` 上运行，并在 +手动分派时运行；它会将模拟一致性门、实时 Matrix 流水线，以及实时 +Telegram 和 Discord 流水线分发为并行作业。实时作业使用 `qa-live-shared` 环境，Telegram/Discord 使用 Convex 租约。发布 -检查会使用确定性的模拟提供商和符合模拟条件的模型（`mock-openai/gpt-5.5` 和 -`mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram 实时传输通道，这样 -渠道契约就能与实时模型延迟和普通提供商插件启动隔离。实时传输 Gateway 网关还会 -禁用内存搜索，因为 QA 一致性会单独覆盖内存行为；提供商连通性由单独的实时模型、 -原生提供商和 Docker 提供商套件覆盖。Matrix 对计划门禁和发布门禁使用 `--profile fast`， -仅在检出的 CLI 支持时添加 `--fail-fast`。CLI 默认值 +检查会使用确定性模拟提供商和模拟限定模型（`mock-openai/gpt-5.5` 和 +`mock-openai/gpt-5.5-alt`）运行 Matrix 和 Telegram 实时传输流水线， +这样渠道契约就能与实时模型延迟和正常提供商插件启动隔离开来。实时传输 Gateway 网关还 +会禁用内存搜索，因为 QA 一致性会单独覆盖内存行为； +提供商连通性由单独的实时模型、原生提供商和 Docker 提供商套件覆盖。Matrix 会为计划和发布门使用 `--profile fast`， +只有在检出的 CLI 支持时才添加 `--fail-fast`。CLI 默认值 和手动工作流输入仍为 `all`；手动 `matrix_profile=all` -派发始终会把完整 Matrix 覆盖分片为 `transport`、`media`、 -`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业。`OpenClaw Release Checks` 还会 -在发布批准前运行发布关键的 QA Lab 通道；其 QA 一致性 -门禁会把候选包和基线包作为并行通道作业运行，然后把 -两个构件下载到一个小型报告作业中，用于最终一致性比较。 -不要把 PR 落地路径置于 `Parity gate` 之后，除非变更实际 -触及 QA 运行时、模型包一致性，或一致性工作流拥有的相关面。 -对于普通渠道、配置、文档或单元测试修复，请将其视为可选 -信号，并遵循限定范围的 CI/检查证据。 +分派始终会把完整 Matrix 覆盖分片到 `transport`、`media`、 +`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业中。`OpenClaw Release Checks` 还会 +在发布审批前运行发布关键的 QA Lab 流水线；其 QA 一致性 +门会把候选包和基线包作为并行流水线作业运行，然后将 +两个工件下载到一个小型报告作业中，用于最终一致性比较。 +不要把 PR 落地路径置于 `Parity gate` 之后，除非变更确实 +触及 QA 运行时、模型包一致性，或一致性工作流拥有的表面。 +对于普通渠道、配置、文档或单元测试修复，把它视为可选 +信号，并遵循作用域化的 CI/检查证据。 `Duplicate PRs After Merge` 工作流是用于落地后重复项清理的手动维护者工作流。 -它默认执行空运行，并且仅在 `apply=true` 时关闭明确 +它默认 dry-run，且仅在 `apply=true` 时关闭明确 列出的 PR。在修改 GitHub 之前，它会验证 -已落地 PR 已合并，并且每个重复 PR 要么具有共享的引用 issue， -要么存在重叠的变更 hunk。 +已落地 PR 已合并，并且每个重复项都有共享的引用 issue +或重叠的变更 hunks。 -`CodeQL` 工作流有意作为窄范围的第一轮安全扫描器， +`CodeQL` 工作流有意作为窄范围的第一道安全扫描器， 而不是完整仓库扫描。每日和手动运行会使用高精度安全查询扫描 Actions 工作流代码 -以及风险最高的 JavaScript/TypeScript 凭证、机密、沙箱、cron 和 -Gateway 网关相关面。 -channel-runtime-boundary 作业会另外扫描核心渠道实现 -契约以及渠道插件运行时、Gateway 网关、插件 SDK、机密和 -审计触点，并归入 `/codeql-critical-security/channel-runtime-boundary` -类别，这样渠道安全信号可以扩展，而无需扩大基线 -JS/TS 类别。 +以及风险最高的 JavaScript/TypeScript 凭证、密钥、沙箱、cron 和 +网关表面。 +channel-runtime-boundary 作业会在 `/codeql-critical-security/channel-runtime-boundary` +类别下单独扫描核心渠道实现 +契约以及渠道插件运行时、Gateway 网关、插件 SDK、密钥和 +审计触点，这样渠道安全信号就能在不扩大基线 +JS/TS 类别的情况下扩展。 `CodeQL Android Critical Security` 工作流是计划运行的 Android -安全分片。它会在工作流完整性检查接受的最小 Blacksmith Linux runner 标签上 -为 CodeQL 手动构建 Android 应用，并将结果上传到 -`/codeql-critical-security/android` 类别下。 +安全分片。它会在 workflow sanity 接受的最小 Blacksmith Linux runner 标签上为 CodeQL +手动构建 Android 应用，并在 +`/codeql-critical-security/android` 类别下上传结果。 -`CodeQL macOS Critical Security` 工作流是每周/手动运行的 macOS +`CodeQL macOS Critical Security` 工作流是每周/手动 macOS 安全分片。它会在 Blacksmith macOS 上为 CodeQL 手动构建 macOS 应用， -从上传的 SARIF 中过滤掉依赖构建结果，并将结果 -上传到 `/codeql-critical-security/macos` 类别下。请将它保留在每日 -默认工作流之外，因为即使干净运行，macOS 构建也会主导运行时间。 +从上传的 SARIF中过滤掉依赖构建结果，并在 +`/codeql-critical-security/macos` 类别下上传结果。让它保持在每日 +默认工作流之外，因为即使干净时 macOS 构建也主导运行时长。 -`CodeQL Critical Quality` 工作流是匹配的非安全分片。它 -仅在较小的 Blacksmith Linux runner 上，针对窄范围高价值相关面运行错误严重级别的、 -非安全 JavaScript/TypeScript 质量查询。其 -core-auth-secrets 作业会扫描凭证、机密、沙箱、cron 和 Gateway 网关安全 -边界代码，并归入单独的 `/codeql-critical-quality/core-auth-secrets` -类别。config-boundary -作业会扫描配置架构、迁移、规范化和 IO 契约，并归入 -单独的 `/codeql-critical-quality/config-boundary` 类别。 -gateway-runtime-boundary 作业会扫描 Gateway 网关协议架构和服务器方法 -契约，并归入单独的 -`/codeql-critical-quality/gateway-runtime-boundary` 类别。 -channel-runtime-boundary 作业会扫描核心渠道实现契约，并归入 -单独的 `/codeql-critical-quality/channel-runtime-boundary` 类别。 -agent-runtime-boundary 作业会扫描命令执行、模型/提供商派发、 -自动回复派发与队列，以及 ACP 控制平面运行时契约，并归入 -单独的 `/codeql-critical-quality/agent-runtime-boundary` 类别。 -mcp-process-runtime-boundary 作业会扫描 MCP 服务器和工具桥、进程 -监督辅助工具以及出站投递契约，并归入单独的 -`/codeql-critical-quality/mcp-process-runtime-boundary` 类别。 -memory-runtime-boundary 作业会扫描内存宿主 SDK、内存运行时外观、 -内存插件 SDK 别名、内存运行时激活胶水代码以及内存 Doctor -命令，并归入单独的 `/codeql-critical-quality/memory-runtime-boundary` -类别。 -ui-control-plane 作业会扫描 Control UI 引导、本地持久化、Gateway 网关 -控制流以及任务控制平面运行时契约，并归入单独的 -`/codeql-critical-quality/ui-control-plane` 类别。 -web-media-runtime-boundary 作业会扫描核心网页 fetch/search、媒体 IO、媒体 -理解、图像生成和媒体生成运行时契约，并归入 -单独的 `/codeql-critical-quality/web-media-runtime-boundary` 类别。 -plugin-boundary 作业会扫描加载器、注册表、公共相关面和插件 SDK -入口点契约，并归入单独的 `/codeql-critical-quality/plugin-boundary` -类别。请让该工作流与安全工作流分离，以便质量发现可以被 -计划、度量、禁用或扩展，而不会遮蔽安全信号。 -Swift、Python 和内置插件的 CodeQL 扩展应仅在窄范围配置文件拥有稳定的 -运行时间和信号之后，作为有范围或分片的后续工作重新加入。 +`CodeQL Critical Quality` 工作流是配套的非安全分片。它 +只在较小的 Blacksmith Linux runner 上，对窄范围高价值表面运行错误严重级别、非安全的 JavaScript/TypeScript 质量查询。其 +core-auth-secrets 作业会在独立的 `/codeql-critical-quality/core-auth-secrets` +类别下扫描凭证、密钥、沙箱、cron 和网关安全 +边界代码。config-boundary +作业会在独立的 `/codeql-critical-quality/config-boundary` 类别下扫描配置 schema、迁移、规范化和 IO 契约。 +gateway-runtime-boundary 作业会在独立的 +`/codeql-critical-quality/gateway-runtime-boundary` 类别下扫描网关协议 schema 和服务器方法 +契约。 +channel-runtime-boundary 作业会在独立的 `/codeql-critical-quality/channel-runtime-boundary` 类别下扫描核心渠道实现契约。 +agent-runtime-boundary 作业会在独立的 `/codeql-critical-quality/agent-runtime-boundary` 类别下扫描命令执行、模型/提供商分派、 +自动回复分派和队列，以及 ACP 控制平面运行时契约。 +mcp-process-runtime-boundary 作业会在独立的 +`/codeql-critical-quality/mcp-process-runtime-boundary` 类别下扫描 MCP 服务器和工具桥、进程 +监管辅助函数，以及出站投递契约。 +memory-runtime-boundary 作业会在独立的 `/codeql-critical-quality/memory-runtime-boundary` +类别下扫描内存主机 SDK、内存运行时 facade、 +内存插件 SDK 别名、内存运行时激活胶水代码，以及内存 Doctor +命令。 +ui-control-plane 作业会在独立的 +`/codeql-critical-quality/ui-control-plane` 类别下扫描 Control UI 引导、本地持久化、Gateway 网关 +控制流和任务控制平面运行时契约。 +web-media-runtime-boundary 作业会在独立的 `/codeql-critical-quality/web-media-runtime-boundary` 类别下扫描核心 Web 获取/搜索、媒体 IO、媒体 +理解、图像生成和媒体生成运行时契约。 +plugin-boundary 作业会在独立的 `/codeql-critical-quality/plugin-boundary` +类别下扫描加载器、注册表、公共表面和插件 SDK +入口点契约。让该工作流与安全分离，这样质量发现就可以 +在不掩盖安全信号的情况下进行计划、度量、禁用或扩展。 +Swift、Python 和内置插件 CodeQL 扩展只应在窄配置文件具备稳定 +运行时和信号之后，作为有作用域或分片的后续工作重新添加。 -`Docs Agent` 工作流是事件驱动的 Codex 维护通道，用于让 -现有文档与最近落地的变更保持一致。它没有纯计划：一次 -在 `main` 上成功的非 bot push CI 运行可以触发它，手动派发也可以 -直接运行它。当 `main` 已继续前进，或最近一小时内已经创建过另一个未跳过的 Docs Agent -运行时，workflow-run 调用会跳过。运行时，它会 +`Docs Agent` 工作流是一个事件驱动的 Codex 维护流水线，用于保持 +现有文档与最近落地的变更一致。它没有纯计划：在 `main` 上 +成功的非机器人 push CI 运行可以触发它，手动分派也可以 +直接运行它。当 `main` 已前进，或最近一小时内已创建另一个未跳过的 Docs Agent 运行时，workflow-run 调用会跳过。运行时，它会 审查从上一个未跳过 Docs Agent 源 SHA 到当前 `main` 的提交范围， -因此一次每小时运行可以覆盖自上次文档检查以来累积的所有 main 变更。 +因此一次每小时运行可以覆盖自上次文档检查以来积累的所有 main 变更。 -`Test Performance Agent` 工作流是事件驱动的 Codex 维护通道， -用于处理慢测试。它没有纯计划：一次在 -`main` 上成功的非 bot push CI 运行可以触发它，但如果当天 UTC 日内另一个 workflow-run 调用已经 -运行过或正在运行，它会跳过。手动派发会绕过该每日活动 -门禁。该通道会构建完整套件的分组 Vitest 性能报告，让 Codex -只做保留覆盖率的小型测试性能修复，而不是进行大范围 -重构，然后重新运行完整套件报告，并拒绝会降低通过基线测试数量的 -变更。如果基线存在失败测试，Codex 只能修复 +`Test Performance Agent` 工作流是用于慢测试的事件驱动 Codex 维护流水线。 +它没有纯计划：在 `main` 上成功的非机器人 push CI 运行 +可以触发它，但如果当天 UTC 已经有另一个 workflow-run 调用运行过 +或正在运行，它会跳过。手动分派会绕过该每日活动 +门。该流水线会构建完整套件的分组 Vitest 性能报告，让 Codex +只做小型且保持覆盖率的测试性能修复，而不是大范围 +重构，然后重跑完整套件报告，并拒绝会降低 +通过基线测试计数的变更。如果基线有失败测试，Codex 只能修复 明显失败，且 agent 后的完整套件报告必须通过，之后 -才能提交任何内容。当 `main` 在 bot push 落地前前进时，该通道 -会 rebase 已验证补丁，重新运行 `pnpm check:changed`，并重试 push； -存在冲突的陈旧补丁会被跳过。它使用 GitHub 托管的 Ubuntu，以便 Codex -action 能保持与 docs agent 相同的 drop-sudo 安全姿态。 +才能提交任何内容。当 `main` 在机器人 push 落地前前进时，该流水线 +会 rebase 已验证补丁、重跑 `pnpm check:changed` 并重试 push； +有冲突的陈旧补丁会被跳过。它使用 GitHub 托管的 Ubuntu，这样 Codex +action 就能保持与 docs agent 相同的 drop-sudo 安全姿态。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -229,30 +224,30 @@ gh workflow run duplicate-after-merge.yml \ ## 作业概览 -| 作业 | 目的 | 运行时机 | +| 作业 | 用途 | 运行时机 | | -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | 检测仅文档变更、变更范围、变更插件，并构建 CI 清单 | 始终在非草稿 push 和 PR 上运行 | +| `preflight` | 检测仅文档变更、变更作用域、变更插件，并构建 CI manifest | 始终在非草稿 push 和 PR 上运行 | | `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 始终在非草稿 push 和 PR 上运行 | -| `security-dependency-audit` | 针对 npm 公告进行无依赖的生产 lockfile 审计 | 始终在非草稿 push 和 PR 上运行 | +| `security-dependency-audit` | 针对 npm advisory 的无依赖生产 lockfile 审计 | 始终在非草稿 push 和 PR 上运行 | | `security-fast` | 快速安全作业的必需聚合项 | 始终在非草稿 push 和 PR 上运行 | -| `build-artifacts` | 构建 `dist/`、Control UI、构建构件检查以及可复用的下游构件 | Node 相关变更 | -| `checks-fast-core` | 快速 Linux 正确性通道，例如内置/插件契约/协议检查 | Node 相关变更 | +| `build-artifacts` | 构建 `dist/`、Control UI、构建工件检查和可复用下游工件 | Node 相关变更 | +| `checks-fast-core` | 快速 Linux 正确性流水线，例如内置/插件契约/协议检查 | Node 相关变更 | | `checks-fast-contracts-channels` | 带有稳定聚合检查结果的分片渠道契约检查 | Node 相关变更 | -| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、内置、契约和插件通道 | Node 相关变更 | -| `check` | 分片主本地门禁等价项：生产类型、lint、守卫、测试类型和严格 smoke | Node 相关变更 | -| `check-additional` | 架构、边界、插件相关面守卫、软件包边界和 gateway-watch 分片 | Node 相关变更 | +| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、内置、契约和插件流水线 | Node 相关变更 | +| `check` | 分片主本地门等价项：生产类型、lint、guard、测试类型和严格 smoke | Node 相关变更 | +| `check-additional` | 架构、边界、插件表面 guard、包边界和 gateway-watch 分片 | Node 相关变更 | | `build-smoke` | 已构建 CLI smoke 测试和启动内存 smoke | Node 相关变更 | -| `checks` | 构建构件渠道测试的验证器 | Node 相关变更 | -| `checks-node-compat-node22` | Node 22 兼容性构建和 smoke 通道 | 发布的手动 CI 派发 | -| `check-docs` | 文档格式化、lint 和断链检查 | 文档已变更 | -| `skills-python` | 针对 Python 支持的 Skills 执行 Ruff + pytest | Python 技能相关变更 | -| `checks-windows` | Windows 特定的进程/路径测试以及共享运行时 import specifier 回归 | Windows 相关变更 | -| `macos-node` | 使用共享构建构件的 macOS TypeScript 测试通道 | macOS 相关变更 | +| `checks` | 已构建工件渠道测试的验证器 | Node 相关变更 | +| `checks-node-compat-node22` | Node 22 兼容性构建和 smoke 流水线 | 发布的手动 CI 分派 | +| `check-docs` | 文档格式、lint 和断链检查 | 文档变更 | +| `skills-python` | 面向 Python 支撑 Skills 的 Ruff + pytest | Python Skills 相关变更 | +| `checks-windows` | Windows 特定进程/路径测试以及共享运行时导入说明符回归 | Windows 相关变更 | +| `macos-node` | 使用共享构建工件的 macOS TypeScript 测试流水线 | macOS 相关变更 | | `macos-swift` | macOS 应用的 Swift lint、构建和测试 | macOS 相关变更 | -| `android` | 两种 flavor 的 Android 单元测试以及一个 debug APK 构建 | Android 相关变更 | -| `test-performance-agent` | 可信活动后的每日 Codex 慢测试优化 | Main CI 成功或手动派发 | +| `android` | 两个 flavor 的 Android 单元测试加一个 debug APK 构建 | Android 相关变更 | +| `test-performance-agent` | 可信活动后的每日 Codex 慢测试优化 | 主 CI 成功或手动分派 | -手动 CI 触发运行与普通 CI 运行相同的作业图，但会强制启用每个非 Android 作用域通道：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS 和 Control UI i18n。独立的手动 CI 触发仅在 `include_android=true` 时运行 Android；完整发布总控通过传入 `include_android=true` 启用 Android。插件预发布静态检查、仅发布使用的 `agentic-plugins` 分片、完整插件批量扫描以及插件预发布 Docker 通道不包含在 CI 中。Docker 预发布套件仅在 `Full Release Validation` 触发单独的 `Plugin Prerelease` workflow 且启用发布验证门禁时运行。手动运行使用唯一的并发组，因此候选发布完整套件不会被同一 ref 上的另一次 push 或 PR 运行取消。可选的 `target_ref` 输入允许可信调用方在分支、标签或完整提交 SHA 上运行该作业图，同时使用所选触发 ref 中的 workflow 文件。 +手动 CI 分发运行与普通 CI 相同的作业图，但会强制启用每个非 Android 作用域车道：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python skills、Windows、macOS 和 Control UI i18n。独立的手动 CI 分发仅在 `include_android=true` 时运行 Android；完整发布总控通过传递 `include_android=true` 启用 Android。插件预发布静态检查、仅发布使用的 `agentic-plugins` 分片、完整扩展批量扫描，以及插件预发布 Docker 车道都排除在 CI 之外。Docker 预发布套件仅在 `Full Release Validation` 分发启用发布验证门禁后，触发单独的 `Plugin Prerelease` 工作流时运行。手动运行使用唯一的并发组，因此候选发布完整套件不会被同一 ref 上的另一次 push 或 PR 运行取消。可选的 `target_ref` 输入允许受信任的调用方使用所选分发 ref 中的工作流文件，针对分支、标签或完整 commit SHA 运行该图。 ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -262,58 +257,60 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## 快速失败顺序 -作业按顺序排列，让低成本检查先于高成本检查失败： +作业按顺序排列，让低成本检查先于高成本作业失败： -1. `preflight` 决定哪些通道实际存在。`docs-scope` 和 `changed-scope` 逻辑是此作业中的步骤，不是独立作业。 -2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，无需等待更重的构件和平台矩阵作业。 -3. `build-artifacts` 与快速 Linux 通道重叠运行，因此下游消费者可以在共享构建就绪后立即开始。 -4. 更重的平台和运行时通道随后展开：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 +1. `preflight` 决定哪些车道实际存在。`docs-scope` 和 `changed-scope` 逻辑是此作业内的步骤，不是独立作业。 +2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而不等待更重的构件和平台矩阵作业。 +3. `build-artifacts` 与快速 Linux 车道重叠运行，因此下游消费者可在共享构建就绪后立即开始。 +4. 更重的平台和运行时车道随后扇出：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 -作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 -手动触发会跳过 changed-scope 检测，并让 preflight 清单表现得像每个作用域区域都已变更。 -CI workflow 编辑会验证 Node CI 作业图和 workflow lint，但本身不会强制运行 Windows、Android 或 macOS 原生构建；这些平台通道仍然限定为平台源代码变更。 -仅 CI 路由编辑、选定的低成本核心测试 fixture 编辑，以及范围很窄的插件契约辅助代码/测试路由编辑，会使用快速的仅 Node 清单路径：preflight、安全检查和单个 `checks-fast-core` 任务。当变更文件仅限于该快速任务直接覆盖的路由或辅助代码表面时，此路径会避开构建构件、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片和额外防护矩阵。 -Windows Node 检查限定于 Windows 特定的进程/路径包装器、npm/pnpm/UI 运行器辅助代码、包管理器配置，以及执行该通道的 CI workflow 表面；无关的源代码、插件、安装冒烟和仅测试变更仍留在 Linux Node 通道上，因此不会为普通测试分片已覆盖的内容占用 16-vCPU Windows worker。 -单独的 `install-smoke` workflow 通过自己的 `preflight` 作业复用相同的作用域脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。Pull request 会针对 Docker/包表面、内置插件包/清单变更，以及 Docker 冒烟作业覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面运行快速路径。仅源代码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI 冒烟，运行容器 gateway-network e2e，验证内置插件构建参数，并在 240 秒聚合命令超时内运行有界的内置插件 Docker profile，同时每个场景的 Docker 运行也会单独封顶。完整路径会为夜间计划运行、手动触发、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的 pull request 保留 QR 包安装和安装器 Docker/更新覆盖。`main` push（包括 merge commit）不会强制运行完整路径；当 changed-scope 逻辑会在 push 上请求完整覆盖时，workflow 会保留快速 Docker 冒烟，并把完整安装冒烟留给夜间或发布验证。较慢的 Bun 全局安装 image-provider 冒烟由 `run_bun_global_install_smoke` 单独门控；它会在夜间计划和发布检查 workflow 中运行，手动 `install-smoke` 触发可以选择加入，但 pull request 和 `main` push 不会运行它。QR 和安装器 Docker 测试保留各自面向安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享 `scripts/e2e/Dockerfile` 镜像：用于安装器/更新/插件依赖通道的裸 Node/Git runner，以及一个将相同 tarball 安装到 `/app` 中、用于普通功能通道的功能性镜像。Docker 通道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，runner 只执行选定计划。调度器使用 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 为每个通道选择镜像，然后以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行通道；用 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整默认 main-pool 槽位数 10，用 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整 provider 敏感 tail-pool 槽位数 10。重型通道上限默认是 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，这样 npm install 和多服务通道不会让 Docker 超额提交，而较轻通道仍可填满可用槽位。单个比有效上限更重的通道仍可从空池启动，然后独占运行直到释放容量。默认情况下，通道启动会错开 2 秒，以避免本地 Docker daemon 出现创建风暴；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合会预检 Docker，移除过期的 OpenClaw E2E 容器，输出活动通道状态，持久化通道耗时以便最长优先排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 进行调度器检查。默认情况下，它会在第一次失败后停止调度新的池化通道，并且每个通道都有 120 分钟的后备超时，可用 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；选定的 live/tail 通道使用更紧的按通道上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器通道，包括仅发布通道（例如 `install-e2e`）以及拆分的内置更新通道（例如 `bundled-channel-update-acpx`），同时跳过清理冒烟，以便智能体复现某个失败通道。可复用的 live/E2E workflow 会询问 `scripts/test-docker-all.mjs --plan-json` 需要哪些包、镜像类型、live 镜像、通道和凭证覆盖，然后 `scripts/docker-e2e.mjs` 将该计划转换为 GitHub 输出和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，下载当前运行的包构件，或从 `package_artifact_run_id` 下载包构件；验证 tarball 清单；在计划需要已安装包的通道时，通过 Blacksmith 的 Docker 层缓存构建并推送带包摘要标签的 bare/functional GHCR Docker E2E 镜像；并复用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或现有带包摘要的镜像，而不是重新构建。`Package Acceptance` workflow 是高级包门禁：它从 npm、可信 `package_ref`、HTTPS tarball 加 SHA-256，或之前的 workflow 构件解析候选包，然后将该单个 `package-under-test` 构件传入可复用 Docker E2E workflow。它将 `workflow_ref` 与 `package_ref` 分开，因此当前验收逻辑可以验证较旧的可信提交，而无需签出旧 workflow 代码。发布检查会为目标 ref 运行自定义 Package Acceptance 增量：内置渠道兼容性、离线插件 fixture，以及针对已解析 tarball 的 Telegram 包 QA。发布路径 Docker 套件使用较小的分块作业并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1`，因此每个分块只拉取它需要的镜像类型，并通过相同的加权调度器执行多个通道（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`、`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-plugins|plugins-runtime-services|plugins-runtime-install-a|plugins-runtime-install-b|plugins-runtime-install-c|plugins-runtime-install-d|bundled-channels`）。当完整 release-path 覆盖请求 OpenWebUI 时，OpenWebUI 会并入 `plugins-runtime-services`，并且仅为 OpenWebUI-only 触发保留独立的 `openwebui` 分块。旧版聚合分块名称 `package-update`、`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍可用于手动重跑，但发布 workflow 使用拆分分块，因此安装器 E2E 和内置插件安装/卸载扫描不会主导关键路径。`install-e2e` 通道别名仍然是两个 provider 安装器通道的聚合手动重跑别名。`bundled-channels` 分块运行拆分后的 `bundled-channel-*` 和 `bundled-channel-update-*` 通道，而不是串行一体化的 `bundled-channel-deps` 通道。每个分块都会上传 `.artifacts/docker-tests/`，其中包含通道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢通道表以及按通道重跑命令。workflow 的 `docker_lanes` 输入会针对准备好的镜像运行选定通道，而不是运行分块作业，这会把失败通道调试限定在一个有目标的 Docker 作业内，并为该次运行准备、下载或复用包构件；如果选定通道是 live Docker 通道，目标作业会为该次重跑在本地构建 live-test 镜像。生成的按通道 GitHub 重跑命令在这些值存在时会包含 `package_artifact_run_id`、`package_artifact_name` 和准备好的镜像输入，因此失败通道可以复用失败运行中的精确包和镜像。使用 `pnpm test:docker:rerun ` 从 GitHub 运行下载 Docker 构件并打印组合/按通道的目标重跑命令；使用 `pnpm test:docker:timings ` 获取慢通道和阶段关键路径摘要。计划的 live/E2E workflow 每天运行完整 release-path Docker 套件。内置更新矩阵按更新目标拆分，因此重复的 npm update 和 Doctor 修复过程可以与其他内置检查分片运行。 +作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。手动分发会跳过变更作用域检测，并让预检清单表现得像每个受作用域限制的区域都已变更。 +CI 工作流编辑会验证 Node CI 图以及工作流 lint，但其本身不会强制运行 Windows、Android 或 macOS 原生构建；这些平台车道仍只限于平台源文件变更。 +仅 CI 路由编辑、选定的低成本核心测试 fixture 编辑，以及窄范围插件契约辅助工具/测试路由编辑会使用快速的仅 Node 清单路径：预检、安全检查和单个 `checks-fast-core` 任务。当变更文件仅限于路由或辅助工具表面，且快速任务会直接覆盖这些表面时，此路径会避开构建构件、Node 22 兼容性、渠道契约、完整核心分片、内置插件分片和额外防护矩阵。 +Windows Node 检查的作用域限于 Windows 专用进程/路径包装器、npm/pnpm/UI runner 辅助工具、包管理器配置，以及执行该车道的 CI 工作流表面；无关的源文件、插件、安装冒烟和仅测试变更继续留在 Linux Node 车道上，因此不会为普通测试分片已经覆盖的内容占用一个 16-vCPU Windows worker。 +单独的 `install-smoke` 工作流通过自己的 `preflight` 作业复用同一个作用域脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。Pull request 会针对 Docker/包表面、内置插件包/清单变更，以及 Docker 冒烟作业会覆盖的核心插件/渠道/Gateway 网关/插件 SDK 表面运行快速路径。仅源代码的内置插件变更、仅测试编辑和仅文档编辑不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI 冒烟，运行容器 gateway-network e2e，验证一个内置扩展构建参数，并在 240 秒聚合命令超时下运行有界内置插件 Docker profile，同时每个场景的 Docker run 单独设限。完整路径为夜间计划运行、手动分发、workflow-call 发布检查，以及真正触及安装器/包/Docker 表面的 pull request 保留 QR 包安装和安装器 Docker/更新覆盖。`main` push（包括 merge commit）不会强制完整路径；当变更作用域逻辑会在 push 上请求完整覆盖时，工作流保留快速 Docker 冒烟，并将完整安装冒烟留给夜间或发布验证。较慢的 Bun 全局安装 image-provider 冒烟由 `run_bun_global_install_smoke` 单独门控；它会在夜间计划和发布检查工作流中运行，手动 `install-smoke` 分发也可以选择启用，但 pull request 和 `main` push 不会运行它。QR 和安装器 Docker 测试保留各自面向安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：一个用于安装器/更新/插件依赖车道的裸 Node/Git runner，以及一个将同一 tarball 安装到 `/app`、用于普通功能车道的功能镜像。Docker 车道定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，runner 只执行选定计划。调度器用 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 为每个车道选择镜像，然后用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行车道；用 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整默认 main-pool 槽位数 10，用 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整对提供商敏感的 tail-pool 槽位数 10。重车道上限默认为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，这样 npm install 和多服务车道不会让 Docker 过载，同时较轻的车道仍能填满可用槽位。单个比有效上限更重的车道仍可从空池启动，然后独占运行直到释放容量。车道启动默认错开 2 秒，以避免本地 Docker daemon 创建风暴；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合会预检 Docker、移除陈旧的 OpenClaw E2E 容器、输出活动车道状态、持久化车道耗时以便按最长优先排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 用于检查调度器。默认情况下，它会在首次失败后停止调度新的池化车道，并且每个车道都有 120 分钟的回退超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；选定的 live/tail 车道使用更严格的每车道上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器车道，包括仅发布车道（如 `install-e2e`）以及拆分的内置更新车道（如 `bundled-channel-update-acpx`），同时跳过清理冒烟，以便 agents 能复现单个失败车道。可复用的 live/E2E 工作流会向 `scripts/test-docker-all.mjs --plan-json` 询问需要哪些包、镜像类型、live 镜像、车道和凭证覆盖，然后 `scripts/docker-e2e.mjs` 会把该计划转换为 GitHub 输出和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw、下载当前运行的包构件，或从 `package_artifact_run_id` 下载包构件；验证 tarball 清单；当计划需要已安装包的车道时，通过 Blacksmith 的 Docker layer cache 构建并推送带有包摘要标签的裸/功能 GHCR Docker E2E 镜像；并复用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 输入或现有包摘要镜像，而不是重新构建。`Package Acceptance` 工作流是高级包门禁：它会从 npm、受信任的 `package_ref`、HTTPS tarball 加 SHA-256，或之前的工作流构件解析候选包，然后把这个单一的 `package-under-test` 构件传给可复用的 Docker E2E 工作流。它将 `workflow_ref` 与 `package_ref` 分开，这样当前验收逻辑无需检出旧工作流代码，就能验证较早的受信任 commit。发布检查会针对目标 ref 运行自定义 Package Acceptance delta：内置渠道兼容性、离线插件 fixture，以及基于已解析 tarball 的 Telegram 包 QA。发布路径 Docker 套件会运行更小的分块作业，并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1`，因此每个分块只拉取所需的镜像类型，并通过同一个加权调度器执行多个车道（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`、`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-plugins|plugins-runtime-services|plugins-runtime-install-a|plugins-runtime-install-b|plugins-runtime-install-c|plugins-runtime-install-d|bundled-channels`）。当完整 release-path 覆盖请求 OpenWebUI 时，它会并入 `plugins-runtime-services`，只有在仅 OpenWebUI 分发时才保留独立的 `openwebui` 分块。旧版聚合分块名称 `package-update`、`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍可用于手动重跑，但发布工作流使用拆分分块，这样安装器 E2E 和内置插件安装/卸载扫描不会主导关键路径。`install-e2e` 车道别名仍是两个提供商安装器车道的聚合手动重跑别名。`bundled-channels` 分块会运行拆分的 `bundled-channel-*` 和 `bundled-channel-update-*` 车道，而不是串行的全量一体 `bundled-channel-deps` 车道。每个分块都会上传 `.artifacts/docker-tests/`，其中包含车道日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢车道表，以及每车道重跑命令。工作流 `docker_lanes` 输入会在准备好的镜像上运行选定车道，而不是运行分块作业，从而将失败车道调试限制在一个目标 Docker 作业内，并为该运行准备、下载或复用包构件；如果选定车道是 live Docker 车道，目标作业会为该重跑在本地构建 live-test 镜像。生成的每车道 GitHub 重跑命令会在这些值存在时包含 `package_artifact_run_id`、`package_artifact_name` 和准备好的镜像输入，因此失败车道可以复用失败运行中的确切包和镜像。使用 `pnpm test:docker:rerun ` 从 GitHub 运行下载 Docker 构件，并打印组合/每车道目标重跑命令；使用 `pnpm test:docker:timings ` 查看慢车道和阶段关键路径摘要。计划的 live/E2E 工作流每天运行完整 release-path Docker 套件。内置更新矩阵按更新目标拆分，因此重复的 npm update 和 Doctor 修复流程可与其他内置检查一起分片。 -当前版本的 Docker 分块包括 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-b` 和 `bundled-channels-contracts`。聚合的 `bundled-channels` 分块仍可用于手动一次性重跑，`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍作为聚合的插件/运行时别名保留，但发布工作流会使用拆分后的分块，让渠道冒烟测试、更新目标、插件运行时检查以及内置插件安装/卸载扫测可以并行运行。定向的 `docker_lanes` 调度也会在一个共享的 package/image 准备步骤之后，将多个选中的运行道拆分为并行作业，并且内置渠道更新运行道会针对临时 npm 网络失败重试一次。 +当前发布 Docker 分块为 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-b` 和 `bundled-channels-contracts`。聚合 `bundled-channels` 分块仍可用于手动一次性重新运行，`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍是聚合插件/运行时别名，但发布工作流使用拆分后的分块，让渠道冒烟测试、更新目标、插件运行时检查以及内置插件安装/卸载扫描可以并行运行。定向 `docker_lanes` 调度也会在一次共享包/镜像准备步骤之后，将多个选中的 lane 拆分为并行作业，并且内置渠道更新 lane 会针对临时 npm 网络失败重试一次。 -本地变更运行道逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地检查门禁对架构边界的要求比广泛的 CI 平台范围更严格：核心生产变更会运行核心生产和核心测试类型检查以及核心 lint/guard；仅核心测试变更只运行核心测试类型检查以及核心 lint；插件生产变更会运行插件生产和插件测试类型检查以及插件 lint；仅插件测试变更会运行插件测试类型检查以及插件 lint。公开的插件 SDK 或插件契约变更会扩展到插件类型检查，因为插件依赖这些核心契约，但 Vitest 插件扫测属于显式测试工作。仅发布元数据的版本号提升会运行定向的版本/配置/根依赖检查。未知的根目录/配置变更会安全回退到所有检查运行道。 +本地变更 lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。该本地检查门禁在架构边界上比宽泛的 CI 平台范围更严格：核心生产变更会运行核心生产和核心测试类型检查，以及核心 lint/guard；仅核心测试变更只运行核心测试类型检查和核心 lint；插件生产变更会运行插件生产和插件测试类型检查，以及插件 lint；仅插件测试变更会运行插件测试类型检查和插件 lint。公共插件 SDK 或插件契约变更会扩展到插件类型检查，因为插件依赖这些核心契约，但 Vitest 插件扫描是显式测试工作。仅发布元数据的版本号更新会运行定向版本/配置/根依赖检查。未知的根目录/配置变更会安全回退到所有检查 lane。 本地变更测试路由位于 `scripts/test-projects.test-support.mjs`，并且 有意比 `check:changed` 更轻量：直接测试编辑会运行自身， 源代码编辑优先使用显式映射，然后是同级测试和导入图 依赖项。共享群组房间投递配置是显式映射之一： 对群组可见回复配置、源回复投递模式或 消息工具系统提示词的变更，会路由到核心回复测试以及 Discord 和 -Slack 投递回归测试，因此共享默认值变更会在第一次 PR -推送前失败。仅当变更覆盖整个 harness，导致轻量映射集合不是可信代理时， -才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 +Slack 投递回归测试，这样共享默认值变更会在第一个 PR +推送之前失败。只有当变更影响整个 harness，导致廉价映射集合不能作为可信代理时，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 -对于 Testbox 验证，请从仓库根目录运行，并优先为 -广泛证明使用新预热的 box。在对一个被复用、已过期或 -刚刚报告了意外大规模同步的 box 花费慢速门禁时间之前，请先在该 -box 内运行 `pnpm testbox:sanity`。当必需的根文件（如 +对于 Testbox 验证，请从仓库根目录运行，并优先使用新预热的 box 来做 +宽泛证明。在把慢速门禁花在复用、过期或刚报告异常大同步量的 box 上之前， +先在该 +box 内运行 `pnpm testbox:sanity`。当必要的根文件（如 `pnpm-lock.yaml`）消失，或 `git status --short` 显示至少 200 个 -已跟踪删除时，完整性检查会快速失败。这通常意味着远端同步状态不是 PR 的可信 -副本。此时应停止该 box 并预热一个新的，而不是调试 +已跟踪删除时，完整性检查会快速失败。这通常意味着远程同步状态不是 PR 的可信 +副本。请停止该 box 并预热一个新的，而不是调试 产品测试失败。对于有意的大规模删除 PR，请为该完整性检查运行设置 -`OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。 +`OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。如果本地 Blacksmith CLI 调用在同步 +阶段停留超过五分钟且没有同步后输出，`pnpm +testbox:run` 也会终止它。设置 +`OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可禁用该 guard，或者为异常大的本地 diff 使用更大的 +毫秒值。 -手动 CI 调度会运行 `checks-node-compat-node22` 作为广泛兼容性覆盖。Android 对独立手动 CI 通过 `include_android=true` 可选启用，并且始终为 `Full Release Validation` 启用。`Plugin Prerelease` 是成本更高的产品/package 覆盖，因此它是一个单独的工作流，由 `Full Release Validation` 调度，或由操作员显式调度。普通 pull request、`main` 推送和独立手动 CI 调度会关闭该套件。 +手动 CI 调度会运行 `checks-node-compat-node22` 作为宽泛兼容性覆盖。Android 对独立手动 CI 通过 `include_android=true` 选择加入，并且始终为 `Full Release Validation` 启用。`Plugin Prerelease` 是成本更高的产品/包覆盖，因此它是一个独立工作流，由 `Full Release Validation` 调度或由显式操作员调度。普通拉取请求、`main` 推送和独立手动 CI 调度都会关闭该套件。 -最慢的 Node 测试族会拆分或均衡，使每个作业保持较小规模而不预留过多 runner：渠道契约以三个加权分片运行，小型核心单元运行道成对运行，自动回复以四个均衡 worker 运行，并将回复子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片，agentic Gateway 网关/插件配置则分散到现有仅源代码 agentic Node 作业中，而不是等待构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。`Plugin Prerelease` 会在八个插件 worker 之间均衡内置插件测试；这些插件分片作业一次最多运行两个插件配置组，每组一个 Vitest worker，并使用更大的 Node heap，因此导入密集型插件批次不会创建额外的 CI 作业。广泛的 agents 运行道使用共享的 Vitest 文件并行调度器，因为它主要受导入/调度影响，而不是由单个慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片拥有尾部耗时。包含模式分片会使用 CI 分片名称记录计时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分完整配置和过滤后的分片。`check-additional` 将 package 边界编译/canary 工作放在一起，并将运行时拓扑架构与 Gateway 网关 watch 覆盖分开；边界 guard 分片会在一个作业内并发运行其小型独立 guard。Gateway 网关 watch、渠道测试和核心支持边界分片会在 `dist/` 和 `dist-runtime/` 已经构建完成后，在 `build-artifacts` 内并发运行，保留它们旧的检查名称作为轻量验证作业，同时避免两个额外的 Blacksmith worker 和第二个产物消费队列。 -Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试运行道仍会使用 SMS/call-log BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关推送上重复执行 debug APK 打包作业。 -当较新的推送落到同一个 PR 或 `main` ref 上时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已经被取代后继续排队。 -自动 CI 并发键带版本号（`CI-v7-*`），因此 GitHub 侧旧队列组中的僵尸作业无法无限期阻塞较新的 main 运行。手动全套件运行使用 `CI-manual-v1-*`，并且不会取消正在进行的运行。 +最慢的 Node 测试族会被拆分或均衡，让每个作业保持较小且不过度预留 runner：渠道契约作为三个加权分片运行，小型核心单元 lane 会成对运行，自动回复作为四个均衡 worker 运行，并将回复子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片，agentic Gateway 网关/插件配置会分布到现有的仅源代码 agentic Node 作业中，而不是等待构建产物。宽泛浏览器、QA、媒体和杂项插件测试使用它们专用的 Vitest 配置，而不是共享的插件兜底配置。`Plugin Prerelease` 会在八个插件 worker 之间均衡内置插件测试；这些插件分片作业一次最多运行两个插件配置组，每组一个 Vitest worker，并使用更大的 Node 堆，以便导入密集的插件批次不会创建额外的 CI 作业。宽泛智能体 lane 使用共享 Vitest 文件并行调度器，因为它主要受导入/调度限制，而不是由单个慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片占据尾部时间。包含模式分片会使用 CI 分片名称记录 timing 条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置和过滤后的分片。`check-additional` 将包边界编译/canary 工作放在一起，并将运行时拓扑架构与 Gateway 网关 watch 覆盖分开；边界 guard 分片会在一个作业内并发运行其小型独立 guard。Gateway 网关 watch、渠道测试和核心支持边界分片会在 `dist/` 和 `dist-runtime/` 已构建后，在 `build-artifacts` 内并发运行，保留它们旧的检查名称作为轻量验证器作业，同时避免两个额外的 Blacksmith worker 和第二个产物消费者队列。 +Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的 source set 或 manifest；它的单元测试 lane 仍会使用 SMS/通话记录 BuildConfig 标志编译该 flavor，同时避免在每次 Android 相关推送时重复打包 debug APK。 +当较新的推送落在同一个 PR 或 `main` ref 上时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一个 ref 的最新运行也失败，否则将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已被取代后继续排队。 +自动 CI 并发键带有版本号（`CI-v7-*`），因此 GitHub 侧旧队列组中的僵尸项无法无限期阻塞新的 main 运行。手动全套件运行使用 `CI-manual-v1-*`，且不会取消正在进行的运行。 -## 运行器 +## Runner -| 运行器 | 作业 | +| Runner | 作业 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`、快速安全作业和聚合（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速协议/契约/内置检查、分片的渠道契约检查、除 lint 外的 `check` 分片、`check-additional` 分片和聚合、Node 测试聚合验证器、文档检查、Python skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，以便 Blacksmith 矩阵可以更早排队 | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、较低权重的插件分片、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types` 和 `check-test-types` | +| `ubuntu-24.04` | `preflight`、快速安全作业和聚合（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速协议/契约/内置检查、分片渠道契约检查、除 lint 外的 `check` 分片、`check-additional` 分片和聚合、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，以便 Blacksmith 矩阵可以更早排队 | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、权重较低的插件分片、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types` 和 `check-test-types` | | `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、内置插件测试分片、`android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它仍然对 CPU 足够敏感，使用 8 vCPU 的成本高于节省；install-smoke Docker 构建中，32-vCPU 的排队时间成本高于节省 | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它对 CPU 仍足够敏感，以至于 8 vCPU 带来的成本高于节省；install-smoke Docker 构建中，32 vCPU 排队时间带来的成本也高于节省 | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | | `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 回退到 `macos-latest` | | `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 回退到 `macos-latest` | diff --git a/docs/zh-CN/gateway/config-agents.md b/docs/zh-CN/gateway/config-agents.md index 9dad0212e..d26dd3092 100644 --- a/docs/zh-CN/gateway/config-agents.md +++ b/docs/zh-CN/gateway/config-agents.md @@ -1,22 +1,20 @@ --- read_when: - - 调整智能体默认值（模型、思考、工作区、心跳、媒体、Skills） + - 调整智能体默认设置（模型、思考、工作区、心跳、媒体、Skills） - 配置多智能体路由和绑定 - - 调整会话、消息投递和 talk-mode 行为 -summary: 智能体默认值、多智能体路由、会话、消息和对话配置 + - 调整会话、消息递送和对话模式行为 +summary: 智能体默认值、多智能体路由、会话、消息和 talk 配置 title: 配置 — 智能体 x-i18n: - generated_at: "2026-04-28T11:51:01Z" + generated_at: "2026-04-29T09:12:55Z" model: gpt-5.5 provider: openai - source_hash: a664de6b9abf629f31b55927b73610896cf86dafd57cf6708ebbbc9c5e188a0d + source_hash: 0b093332d62836f3564f248e67e68b058777d84f78e8f1e99ab258f44839c400 source_path: gateway/config-agents.md workflow: 16 --- -智能体范围的配置键位于 `agents.*`、`multiAgent.*`、`session.*`、 -`messages.*` 和 `talk.*` 下。关于渠道、工具、Gateway 网关运行时以及其他 -顶层键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。 +智能体作用域的配置键位于 `agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下。对于渠道、工具、Gateway 网关运行时以及其他顶层键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。 ## 智能体默认值 @@ -32,7 +30,7 @@ x-i18n: ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示词的运行时行中。如果未设置，OpenClaw 会从工作区向上遍历并自动检测。 +可选的仓库根目录，会显示在系统提示的运行时行中。如果未设置，OpenClaw 会从工作区开始向上遍历来自动检测。 ```json5 { @@ -42,8 +40,7 @@ x-i18n: ### `agents.defaults.skills` -可选的默认 Skills 允许列表，供未设置 -`agents.list[].skills` 的智能体使用。 +对于未设置 `agents.list[].skills` 的智能体，可选的默认 Skills 允许列表。 ```json5 { @@ -61,12 +58,11 @@ x-i18n: - 省略 `agents.defaults.skills`，默认不限制 Skills。 - 省略 `agents.list[].skills` 以继承默认值。 - 设置 `agents.list[].skills: []` 表示没有 Skills。 -- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合； - 它不会与默认值合并。 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用自动创建工作区启动文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -76,10 +72,10 @@ x-i18n: ### `agents.defaults.contextInjection` -控制何时将工作区引导文件注入系统提示词。默认值：`"always"`。 +控制工作区启动文件何时注入到系统提示中。默认值：`"always"`。 -- `"continuation-skip"`：安全的续接轮次（在已完成的助手响应之后）会跳过工作区引导的重新注入，从而减少提示词大小。心跳运行和压缩后的重试仍会重建上下文。 -- `"never"`：在每个轮次都禁用工作区引导和上下文文件注入。仅用于完全自行掌控提示词生命周期的智能体（自定义上下文引擎、会构建自身上下文的原生运行时，或专门不需要引导的工作流）。心跳和压缩恢复轮次也会跳过注入。 +- `"continuation-skip"`：安全的延续轮次（在已完成的助手响应之后）会跳过工作区启动重新注入，从而减小提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。 +- `"never"`：在每一轮禁用工作区启动和上下文文件注入。仅对完全拥有自身提示生命周期的智能体使用此项（自定义上下文引擎、构建自身上下文的原生运行时，或专门的无启动工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。 ```json5 { @@ -89,7 +85,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -每个工作区引导文件在截断前的最大字符数。默认值：`12000`。 +每个工作区启动文件在截断前的最大字符数。默认值：`12000`。 ```json5 { @@ -99,7 +95,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -跨所有工作区引导文件注入的最大总字符数。默认值：`60000`。 +跨所有工作区启动文件注入的最大总字符数。默认值：`60000`。 ```json5 { @@ -109,12 +105,11 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -控制引导上下文被截断时，智能体可见的警告文本。 -默认值：`"once"`。 +控制启动上下文被截断时智能体可见的警告文本。默认值：`"once"`。 -- `"off"`：从不向系统提示词注入警告文本。 +- `"off"`：绝不向系统提示注入警告文本。 - `"once"`：每个唯一截断签名只注入一次警告（推荐）。 -- `"always"`：只要存在截断，每次运行都注入警告。 +- `"always"`：存在截断时，每次运行都注入警告。 ```json5 { @@ -122,34 +117,24 @@ x-i18n: } ``` -### 上下文预算所有权映射 +### 上下文预算归属图 -OpenClaw 有多个高容量提示词/上下文预算，并且它们有意按子系统拆分， -而不是全部流经一个通用旋钮。 +OpenClaw 有多个高容量提示/上下文预算，它们按子系统有意拆分，而不是全部流经一个通用开关。 -- `agents.defaults.bootstrapMaxChars` / - `agents.defaults.bootstrapTotalMaxChars`： - 常规工作区引导注入。 -- `agents.defaults.startupContext.*`： - 一次性的重置/启动模型运行前序内容，包括最近的每日 - `memory/*.md` 文件。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置。 -- `skills.limits.*`： - 注入系统提示词的紧凑 Skills 列表。 -- `agents.defaults.contextLimits.*`： - 有界运行时摘录和注入的运行时自有块。 -- `memory.qmd.limits.*`： - 已索引记忆搜索片段和注入大小。 +- `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`：普通工作区启动注入。 +- `agents.defaults.startupContext.*`：一次性重置/启动模型运行前奏，包括最近的每日 `memory/*.md` 文件。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置。 +- `skills.limits.*`：注入到系统提示中的紧凑 Skills 列表。 +- `agents.defaults.contextLimits.*`：有界运行时摘录和注入的运行时拥有块。 +- `memory.qmd.limits.*`：索引化内存搜索片段和注入大小。 -仅当某个智能体需要不同预算时，才使用匹配的按智能体覆盖项： +仅当某个智能体需要不同预算时，使用匹配的每智能体覆盖： - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -控制在重置/启动模型运行时注入的首轮启动前序内容。 -裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置， -因此它们不会加载此前序内容。 +控制在重置/启动模型运行时注入的首轮启动前奏。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置，因此不会加载此前奏。 ```json5 { @@ -170,7 +155,7 @@ OpenClaw 有多个高容量提示词/上下文预算，并且它们有意按子 #### `agents.defaults.contextLimits` -有界运行时上下文表面的共享默认值。 +有界运行时上下文界面的共享默认值。 ```json5 { @@ -187,15 +172,14 @@ OpenClaw 有多个高容量提示词/上下文预算，并且它们有意按子 } ``` -- `memoryGetMaxChars`：添加截断元数据和续接提示前，默认的 `memory_get` 摘录上限。 +- `memoryGetMaxChars`：添加截断元数据和继续提示之前，默认的 `memory_get` 摘录上限。 - `memoryGetDefaultLines`：省略 `lines` 时，默认的 `memory_get` 行窗口。 - `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 - `postCompactionMaxChars`：压缩后刷新注入期间使用的 AGENTS.md 摘录上限。 #### `agents.list[].contextLimits` -共享 `contextLimits` 旋钮的按智能体覆盖项。省略的字段会继承自 -`agents.defaults.contextLimits`。 +共享 `contextLimits` 开关的每智能体覆盖。省略的字段会从 `agents.defaults.contextLimits` 继承。 ```json5 { @@ -221,7 +205,7 @@ OpenClaw 有多个高容量提示词/上下文预算，并且它们有意按子 #### `skills.limits.maxSkillsPromptChars` -注入系统提示词的紧凑 Skills 列表全局上限。这不会影响按需读取 `SKILL.md` 文件。 +注入到系统提示中的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 ```json5 { @@ -235,7 +219,7 @@ OpenClaw 有多个高容量提示词/上下文预算，并且它们有意按子 #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Skills 提示词预算的按智能体覆盖项。 +Skills 提示预算的每智能体覆盖。 ```json5 { @@ -254,11 +238,9 @@ Skills 提示词预算的按智能体覆盖项。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图像块中最长图像边的最大像素尺寸。 -默认值：`1200`。 +在提供商调用之前，转录/工具图像块中图像最长边的最大像素大小。默认值：`1200`。 -较低的值通常会降低大量截图运行的视觉 token 用量和请求负载大小。 -较高的值会保留更多视觉细节。 +较低的值通常会减少大量截图运行中的视觉令牌用量和请求载荷大小。较高的值会保留更多视觉细节。 ```json5 { @@ -268,7 +250,7 @@ Skills 提示词预算的按智能体覆盖项。 ### `agents.defaults.userTimezone` -系统提示词上下文的时区（不是消息时间戳）。回退到主机时区。 +系统提示上下文使用的时区（不是消息时间戳）。回退到主机时区。 ```json5 { @@ -278,7 +260,7 @@ Skills 提示词预算的按智能体覆盖项。 ### `agents.defaults.timeFormat` -系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。 +系统提示中的时间格式。默认值：`auto`（操作系统偏好设置）。 ```json5 { @@ -337,55 +319,55 @@ Skills 提示词预算的按智能体覆盖项。 - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 字符串形式只设置主模型。 - - 对象形式设置主模型以及有序故障切换模型。 + - 对象形式设置主模型以及有序故障转移模型。 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由 `image` 工具路径用作其视觉模型配置。 - - 当选定/默认模型无法接受图像输入时，也用作回退路由。 - - 优先使用显式 `provider/model` 引用。为兼容性也接受裸 ID；如果某个裸 ID 在 `models.providers.*.models` 中唯一匹配一个已配置且支持图像的条目，OpenClaw 会将其限定到该提供商。配置中存在歧义匹配时，需要显式提供商前缀。 + - 被 `image` 工具路径用作其视觉模型配置。 + - 当所选/默认模型无法接受图像输入时，也用作回退路由。 + - 优先使用显式的 `provider/model` 引用。为兼容性也接受裸 ID；如果裸 ID 与 `models.providers.*.models` 中已配置且支持图像的条目唯一匹配，OpenClaw 会将其限定到该提供商。已配置匹配存在歧义时，需要显式提供商前缀。 - `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享的图像生成能力以及未来任何生成图像的工具/插件表面使用。 + - 被共享图像生成能力以及任何未来生成图像的工具/插件界面使用。 - 典型值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`、用于 fal 的 `fal/fal-ai/flux/dev`、用于 OpenAI Images 的 `openai/gpt-image-2`，或用于透明背景 OpenAI PNG/WebP 输出的 `openai/gpt-image-1.5`。 - - 如果你直接选择提供商/模型，也要配置匹配的提供商凭证（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 + - 如果你直接选择提供商/模型，也要配置匹配的提供商凭证（例如用于 `google/*` 的 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，用于 `openai/gpt-image-2` / `openai/gpt-image-1.5` 的 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，用于 `fal/*` 的 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 - `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享的音乐生成能力以及内置 `music_generate` 工具使用。 + - 被共享音乐生成能力和内置 `music_generate` 工具使用。 - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。 - - 如果省略，`music_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 + - 如果省略，`music_generate` 仍可推断由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 - 如果你直接选择提供商/模型，也要配置匹配的提供商凭证/API 密钥。 - `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享的视频生成能力以及内置 `video_generate` 工具使用。 + - 被共享视频生成能力和内置 `video_generate` 工具使用。 - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 + - 如果省略，`video_generate` 仍可推断由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 - 如果你直接选择提供商/模型，也要配置匹配的提供商凭证/API 密钥。 - - 内置 Qwen 视频生成提供商最多支持 1 个输出视频、1 个输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 + - 内置 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 - `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由 `pdf` 工具用于模型路由。 - - 如果省略，PDF 工具会回退到 `imageModel`，然后回退到解析后的会话/默认模型。 -- `pdfMaxBytesMb`：调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。 -- `pdfMaxPages`：`pdf` 工具中提取回退模式考虑的默认最大页数。 -- `verboseDefault`：智能体的默认详细级别。值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 -- `elevatedDefault`：智能体的默认提升输出级别。值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如，用 API 密钥访问时为 `openai/gpt-5.5`，用 Codex OAuth 时为 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（已弃用的兼容行为，因此优先使用显式 `provider/model`）。如果该提供商不再公开配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露过期的已移除提供商默认值。 + - 被 `pdf` 工具用于模型路由。 + - 如果省略，PDF 工具会回退到 `imageModel`，然后回退到解析出的会话/默认模型。 +- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。 +- `pdfMaxPages`：`pdf` 工具中提取回退模式默认考虑的最大页数。 +- `verboseDefault`：智能体的默认详细级别。值：`"off"`、`"on"`、`"full"`。默认：`"off"`。 +- `elevatedDefault`：智能体的默认提升输出级别。值：`"off"`、`"on"`、`"ask"`、`"full"`。默认：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如用于 API 密钥访问的 `openai/gpt-5.5`，或用于 Codex OAuth 的 `openai-codex/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该确切模型 ID 唯一匹配的已配置提供商，只有之后才会回退到已配置的默认提供商（已弃用的兼容性行为，因此优先使用显式 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露过时的已移除提供商默认值。 - `models`：为 `/model` 配置的模型目录和允许列表。每个条目可以包含 `alias`（快捷方式）和 `params`（提供商特定，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。 - - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换。 - - 提供商作用域的配置/新手引导流程会将选定的提供商模型合并到此映射中，并保留已配置的无关提供商。 + - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换。 + - 按提供商限定范围的配置/新手引导流程会将所选提供商模型合并到此映射中，并保留已配置的无关提供商。 - 对于直接 OpenAI Responses 模型，会自动启用服务器端压缩。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务器端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。 -- `params`：应用于所有模型的全局默认提供商参数。在 `agents.defaults.params` 设置（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 ID）按键覆盖。详情参见 [提示缓存](/zh-CN/reference/prompt-caching)。 -- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，额外请求体优先；非原生 completions 路由之后仍会剥离仅 OpenAI 使用的 `store`。 -- `params.chat_template_kwargs`：vLLM/OpenAI 兼容的聊天模板参数，会合并到顶层 `api: "openai-completions"` 请求体中。对于关闭思考的 `vllm/nemotron-3-*`，内置 vLLM 插件会自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`；显式 `chat_template_kwargs` 会覆盖生成的默认值，而 `extra_body.chat_template_kwargs` 仍具有最终优先级。对于 vLLM Qwen 思考控制，在该模型条目上将 `params.qwenThinkingFormat` 设置为 `"chat-template"` 或 `"top-level"`。 -- `params.preserveThinking`：仅 Z.AI 可选择启用的保留思考。启用且思考开启时，OpenClaw 会发送 `thinking.clear_thinking: false` 并重放之前的 `reasoning_content`；参见 [Z.AI 思考与保留思考](/zh-CN/providers/zai#thinking-and-preserved-thinking)。 -- `agentRuntime`：默认低级智能体运行时策略。省略的 ID 默认使用 OpenClaw Pi。使用 `id: "pi"` 强制使用内置 PI 执行框架，使用 `id: "auto"` 允许已注册的插件执行框架认领受支持模型，使用已注册的执行框架 ID（如 `id: "codex"`），或使用受支持的 CLI 后端别名（如 `id: "claude-cli"`）。设置 `fallback: "none"` 可禁用自动 PI 回退。除非你在同一覆盖作用域中设置 `fallback: "pi"`，否则 `codex` 等显式插件运行时默认封闭失败。将模型引用保持为规范的 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧版运行时提供商前缀。了解这与提供商/模型选择的区别，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 -- 改变这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退添加/移除命令）会保存规范对象形式，并尽可能保留现有回退列表。 -- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍会串行化）。默认值：4。 +- `params`：应用到所有模型的全局默认提供商参数。在 `agents.defaults.params` 设置（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 ID）按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求正文中。如果它与生成的请求键冲突，额外正文优先；非原生 completions 路由之后仍会剥离仅 OpenAI 支持的 `store`。 +- `params.chat_template_kwargs`：vLLM/OpenAI 兼容聊天模板参数，会合并到顶层 `api: "openai-completions"` 请求正文中。对于关闭 thinking 的 `vllm/nemotron-3-*`，内置 vLLM 插件会自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`；显式 `chat_template_kwargs` 会覆盖生成的默认值，而 `extra_body.chat_template_kwargs` 仍拥有最终优先级。对于 vLLM Qwen thinking 控制，请在该模型条目上将 `params.qwenThinkingFormat` 设置为 `"chat-template"` 或 `"top-level"`。 +- `params.preserveThinking`：仅 Z.AI 可选择启用的保留 thinking。启用且 thinking 开启时，OpenClaw 会发送 `thinking.clear_thinking: false` 并重放之前的 `reasoning_content`；参见 [Z.AI thinking 和保留 thinking](/zh-CN/providers/zai#thinking-and-preserved-thinking)。 +- `agentRuntime`：默认低级智能体运行时策略。省略 ID 时默认使用 OpenClaw Pi。使用 `id: "pi"` 强制使用内置 PI 执行框架，使用 `id: "auto"` 让已注册的插件执行框架声明支持的模型，使用已注册的执行框架 ID（如 `id: "codex"`），或使用受支持的 CLI 后端别名（如 `id: "claude-cli"`）。设置 `fallback: "none"` 可禁用自动 PI 回退。显式插件运行时（如 `codex`）默认会失败关闭，除非你在同一覆盖范围内设置 `fallback: "pi"`。保持模型引用规范为 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧版运行时提供商前缀。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，了解它与提供商/模型选择的区别。 +- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退添加/移除命令）会保存规范对象形式，并尽可能保留现有回退列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认：4。 ### `agents.defaults.agentRuntime` -`agentRuntime` 控制哪个低级执行器运行智能体回合。大多数 -部署应保留默认 OpenClaw Pi 运行时。当受信任 -插件提供原生执行框架（例如内置 Codex 应用服务器执行框架）时， -或当你想使用受支持的 CLI 后端（例如 Claude CLI）时，可使用它。关于心智 -模型，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 +`agentRuntime` 控制哪个低级执行器运行智能体轮次。大多数 +部署应保持默认 OpenClaw Pi 运行时。当可信 +插件提供原生执行框架（例如内置 Codex app-server 执行框架）， +或你想使用受支持的 CLI 后端（例如 Claude CLI）时，请使用它。关于心智 +模型，请参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 ```json5 { @@ -401,14 +383,14 @@ Skills 提示词预算的按智能体覆盖项。 } ``` -- `id`：`"auto"`、`"pi"`、已注册的插件执行框架 ID，或受支持的 CLI 后端别名。内置 Codex 插件注册 `codex`；内置 Anthropic 插件提供 `claude-cli` CLI 后端。 -- `fallback`：`"pi"` 或 `"none"`。在 `id: "auto"` 中，省略的回退默认值为 `"pi"`，这样旧配置在没有插件执行框架认领运行时仍可继续使用 PI。在显式插件运行时模式中（例如 `id: "codex"`），省略的回退默认值为 `"none"`，因此缺失执行框架会失败，而不是静默使用 PI。运行时覆盖不会从更宽作用域继承回退；当你有意需要该兼容回退时，请在显式运行时旁一起设置 `fallback: "pi"`。选定的插件执行框架失败始终会直接暴露。 -- 环境覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `id`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 会覆盖该进程的回退。 -- 对于仅 Codex 部署，设置 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。你也可以显式设置 `agentRuntime.fallback: "none"` 以提升可读性；它是显式插件运行时的默认值。 -- 对于 Claude CLI 部署，优先使用 `model: "anthropic/claude-opus-4-7"` 加 `agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 模型引用仍可兼容使用，但新配置应保持提供商/模型选择为规范形式，并将执行后端放在 `agentRuntime.id` 中。 +- `id`：`"auto"`、`"pi"`、已注册的插件执行框架 ID，或受支持的 CLI 后端别名。内置 Codex 插件会注册 `codex`；内置 Anthropic 插件提供 `claude-cli` CLI 后端。 +- `fallback`：`"pi"` 或 `"none"`。在 `id: "auto"` 中，省略的回退默认是 `"pi"`，因此当没有插件执行框架声明某次运行时，旧配置仍可继续使用 PI。在显式插件运行时模式中，例如 `id: "codex"`，省略的回退默认是 `"none"`，因此缺少执行框架时会失败，而不是静默使用 PI。运行时覆盖不会从更广范围继承回退；当你有意需要该兼容性回退时，请与显式运行时一起设置 `fallback: "pi"`。所选插件执行框架失败总是会直接暴露。 +- 环境覆盖：`OPENCLAW_AGENT_RUNTIME=` 覆盖 `id`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 覆盖该进程的回退。 +- 对于仅 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。你也可以显式设置 `agentRuntime.fallback: "none"` 以提高可读性；它是显式插件运行时的默认值。 +- 对于 Claude CLI 部署，优先使用 `model: "anthropic/claude-opus-4-7"` 加 `agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 模型引用仍可用于兼容性，但新配置应保持提供商/模型选择规范，并将执行后端放入 `agentRuntime.id`。 - 较旧的运行时策略键会由 `openclaw doctor --fix` 重写为 `agentRuntime`。 -- 执行框架选择会在第一次嵌入式运行后按会话 ID 固定。配置/环境变更会影响新的或重置的会话，而不会影响现有转录记录。带有转录历史但没有记录固定项的旧版会话会被视为已固定到 PI。`/status` 会报告有效运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。 -- 这只控制文本智能体回合执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 +- 第一次嵌入式运行后，执行框架选择会按会话 ID 固定。配置/环境变更会影响新的或重置的会话，而不会影响现有转录。具有转录历史但没有记录固定值的旧会话会被视为固定到 PI。`/status` 会报告有效运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。 +- 这只控制文本智能体轮次执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 **内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： @@ -416,7 +398,7 @@ Skills 提示词预算的按智能体覆盖项。 | ------------------- | ------------------------------------------ | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.5` or `openai-codex/gpt-5.5` | +| `gpt` | `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` | | `gpt-mini` | `openai/gpt-5.4-mini` | | `gpt-nano` | `openai/gpt-5.4-nano` | | `gemini` | `google/gemini-3.1-pro-preview` | @@ -425,13 +407,13 @@ Skills 提示词预算的按智能体覆盖项。 你配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 用于工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可禁用它。 -Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `adaptive` 思考。 +Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`。 +Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可禁用它。 +Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -用于纯文本回退运行的可选 CLI 后端（无工具调用）。当 API 提供商失败时，可用作备用方案。 +纯文本回退运行（无工具调用）可选 CLI 后端。当 API 提供商失败时，可用作备用方案。 ```json5 { @@ -462,11 +444,11 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada - CLI 后端以文本优先；工具始终禁用。 - 设置 `sessionArg` 时支持会话。 -- 当 `imageArg` 接受文件路径时，支持图像透传。 +- 当 `imageArg` 接受文件路径时，支持图片透传。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的系统提示词。可在默认层级（`agents.defaults.systemPromptOverride`）或每个智能体（`agents.list[].systemPromptOverride`）设置。每智能体的值优先；空值或仅包含空白的值会被忽略。适用于受控提示词实验。 +用固定字符串替换整个由 OpenClaw 组装的系统提示词。可在默认级别（`agents.defaults.systemPromptOverride`）或每个智能体（`agents.list[].systemPromptOverride`）设置。每个智能体的值优先；空值或仅包含空白字符的值会被忽略。适用于受控的提示词实验。 ```json5 { @@ -480,7 +462,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada ### `agents.defaults.promptOverlays` -按模型家族应用的、独立于提供商的提示词叠加层。GPT-5 系列模型 ID 会在各提供商间收到共享行为契约；`personality` 仅控制友好的交互风格层。 +按模型系列应用的、与提供商无关的提示词叠加层。GPT-5 系列模型 ID 会在各提供商间接收共享行为契约；`personality` 仅控制友好交互风格层。 ```json5 { @@ -496,9 +478,9 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada } ``` -- `"friendly"`（默认）和 `"on"` 启用友好的交互风格层。 +- `"friendly"`（默认）和 `"on"` 启用友好交互风格层。 - `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍会启用。 -- 当此共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 +- 未设置此共享设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 ### `agents.defaults.heartbeat` @@ -515,6 +497,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes session: "main", to: "+15555550123", directPolicy: "allow", // allow (default) | block @@ -529,14 +512,15 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 -- `includeSystemPromptSection`：为 false 时，从系统提示词中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入启动上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告负载。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 +- `includeSystemPromptSection`：为 false 时，会从系统提示词中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入启动上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：为 true 时，会在心跳运行期间抑制工具错误警告载荷。 - `timeoutSeconds`：心跳智能体轮次在中止前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。 -- `directPolicy`：直接/私信投递策略。`allow`（默认）允许向直接目标投递。`block` 抑制向直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行使用轻量启动上下文，并且仅保留工作区启动文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳都会在没有既往对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同隔离模式。将每次心跳的 token 成本从约 100K 降至约 2-5K token。 -- 每智能体：设置 `agents.list[].heartbeat`。当任何智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 +- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 抑制直接目标投递，并发出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，心跳运行会使用轻量启动上下文，并且只保留工作区启动文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳都会在没有先前对话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。将每次心跳的 token 成本从约 100K 降至约 2-5K token。 +- `skipWhenBusy`：为 true 时，心跳运行会因额外繁忙通道而推迟：子智能体或嵌套命令工作。即使没有此标志，Cron 通道也始终会推迟心跳。 +- 每个智能体：设置 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 - 心跳会运行完整的智能体轮次，间隔越短消耗的 token 越多。 ### `agents.defaults.compaction` @@ -572,22 +556,22 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada } ``` -- `mode`：`default` 或 `safeguard`（用于长历史的分块摘要）。参见[压缩](/zh-CN/concepts/compaction)。 -- `provider`：已注册的压缩提供商插件的 ID。设置后，会调用该提供商的 `summarize()`，而不是内置 LLM 摘要。失败时回退到内置方式。设置提供商会强制 `mode: "safeguard"`。参见[压缩](/zh-CN/concepts/compaction)。 +- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见[压缩](/zh-CN/concepts/compaction)。 +- `provider`：已注册压缩提供商插件的 ID。设置后，会调用该提供商的 `summarize()`，而不是内置 LLM 摘要。失败时回退到内置摘要。设置提供商会强制使用 `mode: "safeguard"`。参见[压缩](/zh-CN/concepts/compaction)。 - `timeoutSeconds`：OpenClaw 中止单次压缩操作前允许的最长秒数。默认值：`900`。 -- `keepRecentTokens`：用于逐字保留最新转录尾部的 Pi 截断点预算。手动 `/compact` 在显式设置时会遵循此值；否则手动压缩是硬检查点。 +- `keepRecentTokens`：用于逐字保留最近转录尾部的 Pi 截点预算。手动 `/compact` 在显式设置时会遵循此值；否则手动压缩是一个硬检查点。 - `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要期间前置内置的不透明标识符保留指引。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `qualityGuard`：用于 safeguard 摘要的格式异常输出重试检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审计。 -- `postCompactionSections`：可选的 AGENTS.md H2/H3 章节名称，用于在压缩后重新注入。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。未设置或显式设置为该默认组合时，也会接受较旧的 `Every Session`/`Safety` 标题作为旧版回退。 -- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应保持使用一个模型，而压缩摘要应在另一个模型上运行时使用；未设置时，压缩使用会话的主模型。 -- `maxActiveTranscriptBytes`：可选字节阈值（`number` 或类似 `"20mb"` 的字符串），当活动 JSONL 增长超过阈值时，会在运行前触发普通本地压缩。需要 `truncateAfterCompaction`，以便成功压缩后能够轮换到更小的后继转录。未设置或为 `0` 时禁用。 -- `notifyUser`：为 `true` 时，会在压缩开始和完成时向用户发送简短通知（例如，“正在压缩上下文...”和“压缩完成”）。默认禁用，以保持压缩静默。 -- `memoryFlush`：自动压缩前的静默智能体轮次，用于存储持久记忆。当此清理轮次应保留在本地模型上时，将 `model` 设为精确的提供商/模型，例如 `ollama/qwen3:8b`；该覆盖不会继承活动会话的回退链。当工作区为只读时跳过。 +- `qualityGuard`：针对 safeguard 摘要格式异常输出的重试检查。默认在 safeguard 模式下启用；设置 `enabled: false` 可跳过审计。 +- `postCompactionSections`：压缩后要重新注入的可选 AGENTS.md H2/H3 章节名称。默认值为 `["Session Startup", "Red Lines"]`；设置 `[]` 可禁用重新注入。当未设置或显式设置为该默认组合时，较旧的 `Every Session`/`Safety` 标题也会作为旧版回退被接受。 +- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应保留一个模型、但压缩摘要应在另一个模型上运行时使用；未设置时，压缩会使用会话的主模型。 +- `maxActiveTranscriptBytes`：可选字节阈值（`number` 或类似 `"20mb"` 的字符串），当活动 JSONL 超过该阈值时，会在运行前触发普通本地压缩。需要 `truncateAfterCompaction`，这样成功压缩后才能轮转到更小的后继转录。未设置或为 `0` 时禁用。 +- `notifyUser`：为 `true` 时，会在压缩开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认禁用，以保持压缩静默。 +- `memoryFlush`：自动压缩前的静默智能体轮次，用于存储持久记忆。当此维护轮次应保持在本地模型上时，将 `model` 设置为精确的提供商/模型，例如 `ollama/qwen3:8b`；该覆盖不会继承活动会话的回退链。工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 之前，从内存上下文中裁剪**旧工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 前，从内存上下文中剪除**旧工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -611,23 +595,23 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada -- `mode: "cache-ttl"` 启用裁剪过程。 -- `ttl` 控制裁剪在多久后可以再次运行（从上次缓存触达之后计算）。 -- 裁剪会先对过大的工具结果进行软裁剪，然后在需要时硬清除较旧的工具结果。 +- `mode: "cache-ttl"` 启用剪除流程。 +- `ttl` 控制剪除在上次缓存触碰后多久可以再次运行。 +- 剪除会先软修剪过大的工具结果，然后在需要时硬清除更旧的工具结果。 -**软裁剪**会保留开头 + 结尾，并在中间插入 `...`。 +**软修剪**会保留开头 + 结尾，并在中间插入 `...`。 **硬清除**会用占位符替换整个工具结果。 -注意： +说明： -- 图像块永远不会被裁剪/清除。 -- 比例基于字符（近似值），不是精确 token 计数。 -- 如果助理消息少于 `keepLastAssistants` 条，则会跳过裁剪。 +- 图片块永远不会被修剪/清除。 +- 比率按字符计算（近似值），不是精确的 token 数。 +- 如果助理消息少于 `keepLastAssistants` 条，则会跳过剪除。 -行为细节参见[会话裁剪](/zh-CN/concepts/session-pruning)。 +行为详情请参见[会话剪除](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -647,9 +631,9 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 - 渠道覆盖：`channels..blockStreamingCoalesce`（以及每账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。每智能体覆盖：`agents.list[].humanDelay`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。每个智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节参见[流式传输](/zh-CN/concepts/streaming)。 +行为和分块详情请参见[流式传输](/zh-CN/concepts/streaming)。 ### 输入状态指示器 @@ -673,7 +657,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南参见[沙箱隔离](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南请参见[沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -773,19 +757,19 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada **后端：** - `docker`：本地 Docker 运行时（默认） -- `ssh`：通用 SSH 支持的远程运行时 +- `ssh`：通用的 SSH 支持远程运行时 - `openshell`：OpenShell 运行时 -选择 `backend: "openshell"` 时，运行时专属设置会移至 +选择 `backend: "openshell"` 时，运行时特定设置会移至 `plugins.entries.openshell.config`。 **SSH 后端配置：** -- `target`：采用 `user@host[:port]` 形式的 SSH 目标 +- `target`：采用 `user@host[:port]` 格式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按作用域划分工作区的远程绝对根目录 +- `workspaceRoot`：用于按作用域工作区的绝对远程根目录 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时具现化为临时文件的内联内容或 SecretRefs +- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时物化为临时文件的内联内容或 SecretRef - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 **SSH 凭证优先级：** @@ -793,26 +777,26 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前，从活动的密钥运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从活动 secrets 运行时快照中解析 **SSH 后端行为：** -- 创建或重新创建后，对远程工作区执行一次种子初始化 -- 随后保持远程 SSH 工作区为权威来源 +- 在创建或重新创建后，仅初始化一次远程工作区 +- 然后保持远程 SSH 工作区为权威版本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 **工作区访问：** -- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域划分的沙箱工作区 +- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域沙箱工作区 - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` - `rw`：智能体工作区以读写方式挂载到 `/workspace` **作用域：** -- `session`：每个会话一个容器和工作区 -- `agent`：每个智能体一个容器和工作区（默认） +- `session`：每个会话一个容器 + 工作区 +- `agent`：每个智能体一个容器 + 工作区（默认） - `shared`：共享容器和工作区（无跨会话隔离） **OpenShell 插件配置：** @@ -843,30 +827,30 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada **OpenShell 模式：** -- `mirror`：在执行前从本地为远程写入种子内容，执行后同步回来；本地工作区保持为权威来源 -- `remote`：创建沙箱时对远程执行一次种子初始化，随后保持远程工作区为权威来源 +- `mirror`：执行前从本地初始化远程，执行后同步回来；本地工作区保持为权威版本 +- `remote`：创建沙箱时初始化一次远程，然后保持远程工作区为权威版本 -在 `remote` 模式下，种子步骤之后，在 OpenClaw 外部进行的主机本地编辑不会自动同步到沙箱中。 -传输方式是通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。 +在 `remote` 模式下，在 OpenClaw 外部进行的主机本地编辑不会在初始化步骤后自动同步进沙箱。 +传输方式是通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期和可选的镜像同步。 **`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根目录和 root 用户。 -**容器默认使用 `network: "none"`** — 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。 -`"host"` 会被阻止。默认情况下，`"container:"` 会被阻止，除非你明确设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（应急开关）。 +**容器默认为 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。 +`"host"` 会被阻止。`"container:"` 默认会被阻止，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急破例）。 -**传入附件** 会被暂存到活动工作区中的 `media/inbound/*`。 +**入站附件** 会暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载其他主机目录；全局绑定和按智能体绑定会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局绑定和按智能体绑定会合并。 -**沙箱浏览器**（`sandbox.browser.enabled`）：容器内的 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短期有效的令牌 URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示词。不需要在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 凭证，OpenClaw 会发出短期有效的令牌 URL（而不是在共享 URL 中暴露密码）。 - `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确需要全局桥接连通性时，才设置为 `bridge`。 -- `cdpSourceRange` 可选地将容器边缘的 CDP 入站访问限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将其他主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 -- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机调优： +- `network` 默认为 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确想要全局桥接连通性时，才设置为 `bridge`。 +- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制为一个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 +- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -885,14 +869,15 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短期有效的 - `--metrics-recording-only` - `--disable-extensions`（默认启用） - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用；如果 WebGL/3D 使用场景需要，可以用 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用它们。 + 默认启用；如果 WebGL/3D 使用需要，可以通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用。 - 如果你的工作流依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展。 - `--renderer-process-limit=2` 可通过 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 更改；设置为 `0` 可使用 Chromium 的 默认进程限制。 - 当启用 `noSandbox` 时，还会加上 `--no-sandbox`。 - - 默认值是容器镜像基线；若要更改容器默认值，请使用带自定义入口点的自定义浏览器镜像。 + - 默认值是容器镜像基线；使用带自定义 + 入口点的自定义浏览器镜像来更改容器默认值。 @@ -907,12 +892,12 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `agents.list`（按智能体覆盖） -使用 `agents.list[].tts` 为某个智能体指定自己的 TTS 提供商、语音、模型、 -风格或自动 TTS 模式。智能体块会在全局 -`messages.tts` 之上执行深度合并，因此共享凭证可以保留在同一处，而各个 -智能体只覆盖所需的语音或提供商字段。活动智能体的 -覆盖适用于自动朗读回复、`/tts audio`、`/tts status` 和 -`tts` 智能体工具。查看[文本转语音](/zh-CN/tools/tts#per-agent-voice-overrides) +使用 `agents.list[].tts` 为智能体指定自己的 TTS 提供商、语音、模型、 +风格或自动 TTS 模式。智能体块会深度合并到全局 +`messages.tts` 之上，因此共享凭证可以保留在一个位置，而各个 +智能体只覆盖它们需要的语音或提供商字段。活动智能体的 +覆盖适用于自动语音回复、`/tts audio`、`/tts status` 和 +`tts` 智能体工具。请参阅 [文本转语音](/zh-CN/tools/tts#per-agent-voice-overrides) 了解提供商示例和优先级。 ```json5 @@ -967,28 +952,28 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`：稳定的智能体 id（必填）。 -- `default`：设置多个时，第一个生效（会记录警告）。如果没有设置，则列表第一项是默认值。 -- `model`：字符串形式会设置严格的每个智能体主模型，不使用模型回退；对象形式 `{ primary }` 也同样严格，除非你添加 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 让该智能体启用回退，或使用 `{ primary, fallbacks: [] }` 明确设置严格行为。只覆盖 `primary` 的 Cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 -- `params`：每个智能体的流式参数，会合并覆盖 `agents.defaults.models` 中选定的模型条目。用它为特定智能体覆盖 `cacheRetention`、`temperature` 或 `maxTokens` 等设置，而不必复制整个模型目录。 -- `tts`：可选的每个智能体文本转语音覆盖。该块会深度合并覆盖 `messages.tts`，因此请将共享的提供商凭据和回退策略保留在 `messages.tts` 中，并且只在这里设置人设专用值，例如提供商、语音、模型、风格或自动模式。 -- `skills`：可选的每个智能体技能允许列表。如果省略，则智能体会在设置了 `agents.defaults.skills` 时继承它；显式列表会替换默认值而不是合并，`[]` 表示没有技能。 -- `thinkingDefault`：可选的每个智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当没有设置每条消息或会话级覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。选定的提供商/模型配置文件会控制哪些值有效；对于 Google Gemini，`adaptive` 会保留提供商自有的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。 -- `reasoningDefault`：可选的每个智能体默认推理可见性（`on | off | stream`）。当没有设置每条消息或会话级推理覆盖时适用。 -- `fastModeDefault`：可选的每个智能体快速模式默认值（`true | false`）。当没有设置每条消息或会话级快速模式覆盖时适用。 -- `agentRuntime`：可选的每个智能体底层运行时策略覆盖。使用 `{ id: "codex" }` 可让一个智能体仅使用 Codex，而其他智能体在 `auto` 模式下保留默认 Pi 回退。 -- `runtime`：可选的每个智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用带有 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）的 `type: "acp"`。 +- `id`：稳定的智能体 ID（必需）。 +- `default`：设置多个时，第一个生效（会记录警告）。如果都未设置，列表中的第一项为默认值。 +- `model`：字符串形式会设置严格的每智能体主模型，且没有模型回退；对象形式 `{ primary }` 同样严格，除非你添加 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 让该智能体启用回退，或使用 `{ primary, fallbacks: [] }` 明确指定严格行为。只覆盖 `primary` 的 Cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 +- `params`：每智能体的流参数，会合并覆盖 `agents.defaults.models` 中所选模型条目。用它为智能体设置特定覆盖项，例如 `cacheRetention`、`temperature` 或 `maxTokens`，无需复制整个模型目录。 +- `tts`：可选的每智能体文本转语音覆盖项。该块会深度合并覆盖 `messages.tts`，因此请把共享的提供商凭据和回退策略放在 `messages.tts` 中，并且这里只设置角色特定值，例如提供商、voice、模型、style 或自动模式。 +- `skills`：可选的每智能体 skill 允许列表。如果省略，智能体会在设置了 `agents.defaults.skills` 时继承它；显式列表会替换默认值而不是合并，`[]` 表示没有 skills。 +- `thinkingDefault`：可选的每智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当没有设置每消息或会话级覆盖时，为该智能体覆盖 `agents.defaults.thinkingDefault`。所选提供商/模型配置控制哪些值有效；对于 Google Gemini，`adaptive` 会保留提供商拥有的动态 thinking（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。 +- `reasoningDefault`：可选的每智能体默认 reasoning 可见性（`on | off | stream`）。当没有设置每消息或会话级 reasoning 覆盖时应用。 +- `fastModeDefault`：可选的每智能体 fast mode 默认值（`true | false`）。当没有设置每消息或会话级 fast-mode 覆盖时应用。 +- `agentRuntime`：可选的每智能体底层运行时策略覆盖项。使用 `{ id: "codex" }` 可让一个智能体仅使用 Codex，而其他智能体在 `auto` 模式下保留默认 Pi 回退。 +- `runtime`：可选的每智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 - `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 - `identity` 会派生默认值：从 `emoji` 派生 `ackReaction`，从 `name`/`emoji` 派生 `mentionPatterns`。 -- `subagents.allowAgents`：显式 `sessions_spawn.agentId` 目标的智能体 id 允许列表（`["*"]` = 任意；默认值：仅同一智能体）。当需要允许自目标 `agentId` 调用时，请包含请求者 id。 -- 沙箱继承保护：如果请求者会话已沙箱隔离，`sessions_spawn` 会拒绝将以非沙箱方式运行的目标。 -- `subagents.requireAgentId`：为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认值：false）。 +- `subagents.allowAgents`：用于显式 `sessions_spawn.agentId` 目标的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。当应允许自目标 `agentId` 调用时，请包含请求者 ID。 +- 沙箱继承保护：如果请求者会话处于沙箱隔离中，`sessions_spawn` 会拒绝会以非沙箱隔离方式运行的目标。 +- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关内运行多个隔离的智能体。请参阅 [多智能体](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关内运行多个隔离的智能体。请参阅[多智能体](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1007,11 +992,11 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 绑定匹配字段 -- `type`（可选）：`route` 用于常规路由（缺少 type 时默认为 route），`acp` 用于持久 ACP 对话绑定。 -- `match.channel`（必填） +- `type`（可选）：`route` 表示普通路由（缺失 type 时默认使用 route），`acp` 表示持久 ACP 对话绑定。 +- `match.channel`（必需） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；特定渠道） +- `match.guildId` / `match.teamId`（可选；渠道特定） - `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1023,13 +1008,13 @@ scripts/sandbox-browser-setup.sh # optional browser image 5. `match.accountId: "*"`（渠道范围） 6. 默认智能体 -在每一层中，第一个匹配的 `bindings` 条目生效。 +在每一层级内，第一个匹配的 `bindings` 条目生效。 -对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + 账号 + `match.peer.id`）解析，并且不会使用上面的路由绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + 账号 + `match.peer.id`）解析，并且不会使用上面的 route 绑定层级顺序。 -### 每个智能体的访问配置文件 +### 每智能体访问配置文件 - + ```json5 { @@ -1047,7 +1032,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1122,7 +1107,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -优先级详情请参见 [Multi-Agent 沙箱和工具](/zh-CN/tools/multi-agent-sandbox-tools)。 +参见 [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools)，了解优先级详情。 --- @@ -1174,35 +1159,35 @@ scripts/sandbox-browser-setup.sh # optional browser image -- **`scope`**：群组聊天上下文的基础会话分组策略。 - - `per-sender`（默认）：每个发送者在一个渠道上下文中获得一个隔离的会话。 - - `global`：一个渠道上下文中的所有参与者共享单个会话（仅在确实需要共享上下文时使用）。 +- **`scope`**：群聊上下文的基础会话分组策略。 + - `per-sender`（默认）：每个发送者在渠道上下文中获得一个隔离的会话。 + - `global`：渠道上下文中的所有参与者共享单个会话（仅在确实需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - - `per-peer`：跨渠道按发送者 id 隔离。 + - `per-peer`：跨渠道按发送者 ID 隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 id 映射到带提供商前缀的对等方，以便跨渠道共享会话。`/dock_discord` 等停靠命令使用同一映射，将当前会话的回复路由切换到另一个已链接的渠道对等方；参见[渠道停靠](/zh-CN/concepts/channel-docking)。 -- **`reset`**：主要重置策略。`daily` 在本地时间 `atHour` 重置；`idle` 在 `idleMinutes` 后重置。两者都配置时，先过期者生效。每日重置的新鲜度使用会话行的 `sessionStartedAt`；空闲重置的新鲜度使用 `lastInteractionAt`。心跳、cron 唤醒、exec 通知和 Gateway 网关记账等后台/系统事件写入可以更新 `updatedAt`，但它们不会让每日/空闲会话保持新鲜。 +- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，用于跨渠道共享会话。诸如 `/dock_discord` 的停靠命令使用同一映射，将当前会话的回复路由切换到另一个已关联的渠道对端；参见 [渠道停靠](/zh-CN/concepts/channel-docking)。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。两者都配置时，先过期者生效。每日重置的新鲜度使用会话行的 `sessionStartedAt`；空闲重置的新鲜度使用 `lastInteractionAt`。后台/系统事件写入（如心跳、cron 唤醒、exec 通知和 Gateway 网关记账）可以更新 `updatedAt`，但它们不会让每日/空闲会话保持新鲜。 - **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 - **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。 - - 如果父会话 `totalTokens` 高于此值，OpenClaw 会启动新的线程会话，而不是继承父会话的转录历史。 - - 设为 `0` 可禁用此保护，并始终允许父会话分叉。 -- **`mainKey`**：旧版字段。运行时始终使用 `"main"` 作为主直接聊天桶。 -- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间，智能体之间的最大往返回合数（整数，范围：`0`–`5`）。`0` 会禁用乒乓式串联。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 可作为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 生效。 + - 如果父级 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父级转录历史。 + - 设为 `0` 可禁用此保护，并始终允许父级分叉。 +- **`mainKey`**：旧版字段。运行时始终为主直接聊天桶使用 `"main"`。 +- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间，智能体之间的最大来回回复轮数（整数，范围：`0`–`5`）。`0` 会禁用来回链式回复。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，带旧版 `dm` 别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个拒绝规则胜出。 - **`maintenance`**：会话存储清理 + 保留控制。 - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 - - `pruneAfter`：陈旧条目的年龄截断值（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。运行时会以小的高水位缓冲批量写入清理，以适配生产规模上限；`openclaw sessions cleanup --enforce` 会立即应用该上限。 - - `rotateBytes`：已弃用并被忽略；`openclaw doctor --fix` 会从较旧配置中移除它。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认为 `pruneAfter`；设为 `false` 可禁用。 + - `pruneAfter`：过期条目的年龄截止值（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。运行时会使用一个很小的高水位缓冲区批量写入清理，以适配生产规模上限；`openclaw sessions cleanup --enforce` 会立即应用该上限。 + - `rotateBytes`：已弃用且会被忽略；`openclaw doctor --fix` 会将其从旧配置中移除。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留时间。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会先移除最旧的工件/会话。 - - `highWaterBytes`：预算清理后的可选目标值。默认为 `maxDiskBytes` 的 `80%`。 + - `highWaterBytes`：预算清理后的可选目标。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可以覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认的非活动自动取消聚焦时间，以小时为单位（`0` 禁用；提供商可以覆盖） - - `maxAgeHours`：默认的硬性最大年龄，以小时为单位（`0` 禁用；提供商可以覆盖） + - `idleHours`：默认的非活动自动取消聚焦小时数（`0` 禁用；提供商可以覆盖） + - `maxAgeHours`：默认的硬性最大年龄小时数（`0` 禁用；提供商可以覆盖） @@ -1240,36 +1225,36 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 响应前缀 -按渠道/账户覆盖项：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +每个渠道/账号覆盖项：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析规则（最具体者优先）：账户 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 派生 `[{identity.name}]`。 +解析顺序（最具体者优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生 `[{identity.name}]`。 **模板变量：** -| 变量 | 描述 | 示例 | +| 变量 | 说明 | 示例 | | ----------------- | -------------------- | --------------------------- | | `{model}` | 简短模型名称 | `claude-opus-4-6` | | `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | | `{provider}` | 提供商名称 | `anthropic` | | `{thinkingLevel}` | 当前思考级别 | `high`, `low`, `off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| `{identity.name}` | 智能体身份名称 |（与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 -### 确认回应 +### 确认回应表情 -- 默认使用活动智能体的 `identity.emoji`，否则使用 `"👀"`。设置为 `""` 可禁用。 -- 按渠道覆盖项：`channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解析顺序：账户 → 渠道 → `messages.ackReaction` → 身份回退值。 -- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles 等支持回应的渠道上，在回复后移除确认回应。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期 Status 回应。 - 在 Slack 和 Discord 上，未设置时，如果确认回应处于活动状态，Status 回应会保持启用。 - 在 Telegram 上，需要显式设置为 `true` 才能启用生命周期 Status 回应。 +- 默认为活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 +- 每个渠道覆盖项：`channels..ackReaction`、`channels..accounts..ackReaction`。 +- 解析顺序：账号 → 渠道 → `messages.ackReaction` → 身份回退值。 +- 范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在支持 reaction 的渠道（如 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles）上，会在回复后移除确认回应。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reaction。 + 在 Slack 和 Discord 上，未设置时，如果确认回应 reaction 处于活动状态，会保持状态 reaction 启用。 + 在 Telegram 上，需要显式设置为 `true` 才能启用生命周期状态 reaction。 ### 入站防抖 -将同一发送者快速发送的纯文本消息合并为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 +将同一发送者快速发送的纯文本消息合并为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1319,13 +1304,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好设置，`/tts status` 会显示有效状态。 -- `summaryModel` 会为自动摘要覆盖 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需选择启用）。 +- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好设置，`/tts status` 会显示生效状态。 +- `summaryModel` 会覆盖 `agents.defaults.model.primary`，用于自动摘要。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（选择加入）。 - API 密钥会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- 内置语音提供商由插件拥有。如果设置了 `plugins.allow`，请包含你要使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 `edge` 提供商 ID 可作为 `microsoft` 的别名使用。 +- 内置语音提供商由插件拥有。如果设置了 `plugins.allow`，请包含你要使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 `edge` 提供商 id 会作为 `microsoft` 的别名被接受。 - `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，然后是 `https://api.openai.com/v1`。 -- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音验证。 +- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容的 TTS 服务器，并放宽模型/语音验证。 --- @@ -1360,20 +1345,20 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- 配置多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的一个键。 +- 配置多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 - 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 -- 语音 ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 +- Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 仅当未配置 Talk API 密钥时，才会使用 `ELEVENLABS_API_KEY` 回退。 -- `providers.*.voiceAliases` 让 Talk 指令可以使用友好名称。 -- `providers.mlx.modelId` 选择 macOS 本地 MLX helper 使用的 Hugging Face 仓库。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。 -- macOS MLX 播放会通过内置的 `openclaw-mlx-tts` helper（如果存在）或 `PATH` 上的可执行文件运行；`OPENCLAW_MLX_TTS_BIN` 会为开发覆盖 helper 路径。 -- `speechLocale` 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域设置 ID。未设置时使用设备默认值。 -- `silenceTimeoutMs` 控制 Talk 模式在用户沉默后等待多久才发送转录文本。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- `ELEVENLABS_API_KEY` 回退仅在未配置 Talk API 密钥时适用。 +- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 +- `providers.mlx.modelId` 选择 macOS 本地 MLX 辅助程序使用的 Hugging Face 仓库。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。 +- macOS MLX 播放会在存在时通过内置 `openclaw-mlx-tts` 辅助程序运行，或通过 `PATH` 上的可执行文件运行；`OPENCLAW_MLX_TTS_BIN` 会覆盖开发用的辅助程序路径。 +- `speechLocale` 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域设置 id。留空则使用设备默认值。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久再发送转录。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- -## 相关内容 +## 相关 - [配置参考](/zh-CN/gateway/configuration-reference) — 所有其他配置键 - [配置](/zh-CN/gateway/configuration) — 常见任务和快速设置 diff --git a/docs/zh-CN/gateway/heartbeat.md b/docs/zh-CN/gateway/heartbeat.md index c688460bf..8a46573cc 100644 --- a/docs/zh-CN/gateway/heartbeat.md +++ b/docs/zh-CN/gateway/heartbeat.md @@ -1,46 +1,46 @@ --- read_when: - 调整心跳节奏或消息传递 - - 为定时任务选择心跳还是 cron + - 在 heartbeat 和 cron 之间为定时任务做选择 sidebarTitle: Heartbeat summary: 心跳轮询消息和通知规则 title: 心跳 x-i18n: - generated_at: "2026-04-28T11:52:15Z" + generated_at: "2026-04-29T09:12:45Z" model: gpt-5.5 provider: openai - source_hash: 4a88385f08704b724a22f0d55719043861f94ed6890d2fbaadb3b399ee27c6d2 + source_hash: 2bafae7cafb9163015a112c074d36ab070c71d1d7ba1c7c0834e6720521f4275 source_path: gateway/heartbeat.md workflow: 16 --- -**Heartbeat 与 cron？** 请参阅 [自动化与任务](/zh-CN/automation)，了解何时使用它们。 +**Heartbeat 还是 cron？** 有关何时使用哪一种，请参阅 [自动化与任务](/zh-CN/automation)。 -Heartbeat 会在主会话中运行**周期性智能体轮次**，让模型可以暴露任何需要关注的事项，而不会向你发送垃圾消息。 +Heartbeat 会在主会话中运行**周期性的智能体轮次**，这样模型就能浮现需要注意的事项，而不会对你刷屏。 -Heartbeat 是一个定时的主会话轮次，它**不会**创建[后台任务](/zh-CN/automation/tasks)记录。任务记录用于分离式工作（ACP 运行、子智能体、隔离的 cron 作业）。 +Heartbeat 是一个计划的主会话轮次，它**不会**创建 [后台任务](/zh-CN/automation/tasks)记录。任务记录用于脱离当前会话的工作（ACP 运行、子智能体、隔离的 cron 作业）。 -故障排除：[定时任务](/zh-CN/automation/cron-jobs#troubleshooting) +故障排除：[计划任务](/zh-CN/automation/cron-jobs#troubleshooting) ## 快速开始（初学者） - - 保持启用 heartbeat（默认是 `30m`，对于 Anthropic OAuth/token 认证，包括 Claude CLI 复用，则为 `1h`），或设置你自己的节奏。 + + 保持启用 heartbeat（默认是 `30m`；对于 Anthropic OAuth/token 凭证，包括复用 Claude CLI，则是 `1h`），或设置你自己的频率。 - - 在 Agent 工作区中创建一个很小的 `HEARTBEAT.md` 清单或 `tasks:` 块。 + + 在 Agent 工作区中创建一个简短的 `HEARTBEAT.md` 清单或 `tasks:` 块。 - + `target: "none"` 是默认值；设置 `target: "last"` 可路由到最近一次联系人。 - + - 启用 heartbeat 推理投递以提高透明度。 - - 如果 heartbeat 运行只需要 `HEARTBEAT.md`，使用轻量级引导上下文。 + - 如果 heartbeat 运行只需要 `HEARTBEAT.md`，则使用轻量级引导上下文。 - 启用隔离会话，避免每次 heartbeat 都发送完整对话历史。 - - 将 heartbeat 限制在活跃时段内（本地时间）。 + - 将 heartbeat 限制在活跃时段（本地时间）。 @@ -57,6 +57,7 @@ Heartbeat 是一个定时的主会话轮次，它**不会**创建[后台任务]( directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress lightContext: true, // optional: only inject HEARTBEAT.md from bootstrap files isolatedSession: true, // optional: fresh session each run (no conversation history) + skipWhenBusy: true, // optional: also defer when subagent or nested lanes are busy // activeHours: { start: "08:00", end: "24:00" }, // includeReasoning: true, // optional: send separate `Reasoning:` message too }, @@ -67,31 +68,32 @@ Heartbeat 是一个定时的主会话轮次，它**不会**创建[后台任务]( ## 默认值 -- 间隔：`30m`（当检测到的认证模式是 Anthropic OAuth/token 认证，包括 Claude CLI 复用时，为 `1h`）。设置 `agents.defaults.heartbeat.every` 或每个智能体的 `agents.list[].heartbeat.every`；使用 `0m` 禁用。 +- 间隔：`30m`（当检测到的凭证模式是 Anthropic OAuth/token 凭证，包括复用 Claude CLI 时为 `1h`）。设置 `agents.defaults.heartbeat.every` 或按智能体设置 `agents.list[].heartbeat.every`；使用 `0m` 可禁用。 - 提示正文（可通过 `agents.defaults.heartbeat.prompt` 配置）：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` -- heartbeat 提示会作为用户消息**逐字**发送。只有在默认智能体启用 heartbeat 时，系统提示才包含 “Heartbeat” 章节，并且该运行会在内部打上标记。 -- 使用 `0m` 禁用 heartbeat 时，普通运行也会从引导上下文中省略 `HEARTBEAT.md`，因此模型不会看到仅用于 heartbeat 的指令。 -- 活跃时段（`heartbeat.activeHours`）会按配置的时区检查。在窗口之外，heartbeat 会跳过，直到窗口内的下一个 tick。 +- heartbeat 提示会作为用户消息**逐字**发送。只有在默认智能体启用 heartbeat 时，系统提示才会包含 “Heartbeat” 部分，并且该运行会在内部被标记。 +- 当通过 `0m` 禁用 heartbeat 时，正常运行也会从引导上下文中省略 `HEARTBEAT.md`，这样模型不会看到仅用于 heartbeat 的指令。 +- 活跃时段（`heartbeat.activeHours`）会按配置的时区检查。在窗口之外，heartbeat 会被跳过，直到窗口内的下一次 tick。 +- 当 cron 工作处于活动或排队状态时，heartbeat 会自动延后。设置 `heartbeat.skipWhenBusy: true` 还会在额外繁忙通道（子智能体或嵌套命令工作）中延后；这对本地 Ollama 和其他受限的单运行时主机很有用。 ## heartbeat 提示的用途 默认提示有意保持宽泛： -- **后台任务**：“Consider outstanding tasks” 会提醒智能体检查后续事项（收件箱、日历、提醒、排队的工作），并暴露任何紧急事项。 -- **人工检查**：“Checkup sometimes on your human during day time” 会提醒偶尔发送一条轻量的“有什么需要吗？”消息，但会使用你配置的本地时区来避免夜间垃圾消息（请参阅[时区](/zh-CN/concepts/timezone)）。 +- **后台任务**：“Consider outstanding tasks” 会提示智能体检查后续事项（收件箱、日历、提醒、排队工作），并浮现任何紧急内容。 +- **真人确认**：“Checkup sometimes on your human during day time” 会提示偶尔发送一条轻量级的“anything you need?”消息，但会使用你配置的本地时区来避免夜间刷屏（参见[时区](/zh-CN/concepts/timezone)）。 Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但 heartbeat 运行本身不会创建任务记录。 -如果你希望 heartbeat 执行非常具体的事情（例如“检查 Gmail PubSub 统计信息”或“验证 Gateway 网关健康状况”），请将 `agents.defaults.heartbeat.prompt`（或 `agents.list[].heartbeat.prompt`）设置为自定义正文（逐字发送）。 +如果你希望 heartbeat 执行非常具体的事项（例如 “check Gmail PubSub stats” 或 “verify gateway health”），请将 `agents.defaults.heartbeat.prompt`（或 `agents.list[].heartbeat.prompt`）设置为自定义正文（逐字发送）。 ## 响应契约 -- 如果没有需要关注的事项，请回复 **`HEARTBEAT_OK`**。 -- 在 heartbeat 运行期间，当 `HEARTBEAT_OK` 出现在回复的**开头或结尾**时，OpenClaw 会将其视为确认。该 token 会被剥离；如果剩余内容 **≤ `ackMaxChars`**（默认：300），回复会被丢弃。 -- 如果 `HEARTBEAT_OK` 出现在回复**中间**，则不会被特殊处理。 -- 对于警报，**不要**包含 `HEARTBEAT_OK`；只返回警报文本。 +- 如果没有需要注意的事项，请回复 **`HEARTBEAT_OK`**。 +- 在 heartbeat 运行期间，当 `HEARTBEAT_OK` 出现在回复的**开头或结尾**时，OpenClaw 会将其视为确认。该 token 会被移除；如果剩余内容 **≤ `ackMaxChars`**（默认：300），则回复会被丢弃。 +- 如果 `HEARTBEAT_OK` 出现在回复的**中间**，不会被特殊处理。 +- 对于告警，**不要**包含 `HEARTBEAT_OK`；只返回告警文本。 -在 heartbeat 之外，消息开头/结尾处意外出现的 `HEARTBEAT_OK` 会被剥离并记录；仅包含 `HEARTBEAT_OK` 的消息会被丢弃。 +在 heartbeat 之外，消息开头/结尾误出现的 `HEARTBEAT_OK` 会被移除并记录日志；只有 `HEARTBEAT_OK` 的消息会被丢弃。 ## 配置 @@ -105,6 +107,7 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但 includeReasoning: false, // default: false (deliver separate Reasoning: message when available) lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes target: "last", // default: none | options: last | none | (core or plugin, e.g. "bluebubbles") to: "+15551234567", // optional channel-specific override accountId: "ops-bot", // optional multi-account channel id @@ -119,14 +122,14 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但 ### 范围和优先级 - `agents.defaults.heartbeat` 设置全局 heartbeat 行为。 -- `agents.list[].heartbeat` 在其上合并；如果任何智能体有 `heartbeat` 块，**只有这些智能体**会运行 heartbeat。 +- `agents.list[].heartbeat` 在其上合并；如果任何智能体有 `heartbeat` 块，则**只有这些智能体**会运行 heartbeat。 - `channels.defaults.heartbeat` 为所有渠道设置可见性默认值。 - `channels..heartbeat` 覆盖渠道默认值。 -- `channels..accounts..heartbeat`（多账号渠道）覆盖每个渠道的设置。 +- `channels..accounts..heartbeat`（多账号渠道）覆盖按渠道设置。 -### 每个智能体的 heartbeat +### 按智能体配置 heartbeat -如果任何 `agents.list[]` 条目包含 `heartbeat` 块，**只有这些智能体**会运行 heartbeat。每个智能体的块会合并到 `agents.defaults.heartbeat` 之上（因此你可以设置一次共享默认值，并按智能体覆盖）。 +如果任何 `agents.list[]` 条目包含 `heartbeat` 块，则**只有这些智能体**会运行 heartbeat。按智能体的块会合并在 `agents.defaults.heartbeat` 之上（因此你可以只设置一次共享默认值，并按智能体覆盖）。 示例：两个智能体，只有第二个智能体运行 heartbeat。 @@ -158,7 +161,7 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但 ### 活跃时段示例 -将 heartbeat 限制在特定时区的工作时间内： +将 heartbeat 限制在特定时区的工作时段： ```json5 { @@ -178,22 +181,22 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但 } ``` -在此窗口之外（东部时间上午 9 点之前或晚上 10 点之后），heartbeat 会被跳过。窗口内的下一个定时 tick 将正常运行。 +在这个窗口之外（美东时间上午 9 点前或晚上 10 点后），heartbeat 会被跳过。窗口内的下一次计划 tick 会正常运行。 ### 24/7 设置 -如果你希望 heartbeat 全天运行，请使用以下模式之一： +如果你希望 heartbeat 全天运行，请使用以下任一模式： -- 完全省略 `activeHours`（没有时间窗口限制；这是默认行为）。 +- 完全省略 `activeHours`（无时间窗口限制；这是默认行为）。 - 设置全天窗口：`activeHours: { start: "00:00", end: "24:00" }`。 -不要将 `start` 和 `end` 时间设置为相同（例如从 `08:00` 到 `08:00`）。这会被视为零宽度窗口，因此 heartbeat 将始终被跳过。 +不要将 `start` 和 `end` 设置为相同时间（例如从 `08:00` 到 `08:00`）。这会被视为零宽度窗口，因此 heartbeat 总是被跳过。 ### 多账号示例 -使用 `accountId` 定位到 Telegram 等多账号渠道上的特定账号： +使用 `accountId` 定向到 Telegram 等多账号渠道上的特定账号： ```json5 { @@ -229,30 +232,33 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但 heartbeat 运行的可选模型覆盖（`provider/model`）。 - 启用时，在可用时还会投递单独的 `Reasoning:` 消息（形状与 `/reasoning on` 相同）。 + 启用后，也会在可用时投递单独的 `Reasoning:` 消息（形态与 `/reasoning on` 相同）。 - 为 true 时，heartbeat 运行会使用轻量级引导上下文，并仅保留工作区引导文件中的 `HEARTBEAT.md`。 + 为 true 时，heartbeat 运行会使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。 - 为 true 时，每次 heartbeat 都会在没有先前对话历史的新会话中运行。使用与 cron `sessionTarget: "isolated"` 相同的隔离模式。可大幅降低每次 heartbeat 的 token 成本。与 `lightContext: true` 结合使用可获得最大节省。投递路由仍使用主会话上下文。 + 为 true 时，每次 heartbeat 都会在没有先前对话历史的新会话中运行。使用与 cron `sessionTarget: "isolated"` 相同的隔离模式。可大幅降低每次 heartbeat 的 token 成本。与 `lightContext: true` 结合可获得最大节省。投递路由仍使用主会话上下文。 + + + 为 true 时，heartbeat 运行会在额外繁忙通道上延后：子智能体或嵌套命令工作。即使没有此标志，cron 通道也始终会延后 heartbeat，因此本地模型主机不会同时运行 cron 和 heartbeat 提示。 heartbeat 运行的可选会话键。 - `main`（默认）：智能体主会话。 - 显式会话键（从 `openclaw sessions --json` 或 [sessions CLI](/zh-CN/cli/sessions) 复制）。 -- 会话键格式：请参阅[会话](/zh-CN/concepts/session)和[群组](/zh-CN/channels/groups)。 +- 会话键格式：参见[会话](/zh-CN/concepts/session)和[群组](/zh-CN/channels/groups)。 -- `last`：投递到上次使用的外部渠道。 -- 显式渠道：任何已配置的渠道或插件 ID，例如 `discord`、`matrix`、`telegram` 或 `whatsapp`。 +- `last`：投递到最近使用的外部渠道。 +- 显式渠道：任何已配置渠道或插件 ID，例如 `discord`、`matrix`、`telegram` 或 `whatsapp`。 - `none`（默认）：运行 heartbeat，但**不向外部投递**。 - 控制直接/私信投递行为。`allow`：允许直接/私信 heartbeat 投递。`block`：抑制直接/私信投递（`reason=dm-blocked`）。 + 控制 direct/DM 投递行为。`allow`：允许 direct/DM heartbeat 投递。`block`：抑制 direct/DM 投递（`reason=dm-blocked`）。 @@ -260,7 +266,7 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但 - 多账号渠道的可选账号 ID。当 `target: "last"` 时，如果解析出的最近渠道支持账号，则该账号 ID 会应用于它；否则会被忽略。如果账号 ID 与解析出的渠道中已配置的账号不匹配，则会跳过投递。 + 多账号渠道的可选账号 ID。当 `target: "last"` 时，如果解析出的最近渠道支持账号，则账号 ID 会应用于该渠道；否则会被忽略。如果账号 ID 与解析渠道的已配置账号不匹配，则会跳过投递。 @@ -272,49 +278,50 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但 - 为 true 时，会在 heartbeat 运行期间抑制工具错误警告载荷。 + 为 true 时，在心跳运行期间抑制工具错误警告载荷。 - 将 heartbeat 运行限制在一个时间窗口内。对象包含 `start`（HH:MM，包含；使用 `00:00` 表示一天开始）、`end`（HH:MM，不包含；允许 `24:00` 表示一天结束）和可选的 `timezone`。 + 将心跳运行限制在某个时间窗口内。对象包含 `start`（HH:MM，包含；使用 `00:00` 表示一天开始）、`end`（HH:MM，不包含；允许用 `24:00` 表示一天结束），以及可选的 `timezone`。 -- 省略或 `"user"`：如果设置了你的 `agents.defaults.userTimezone`，则使用它，否则回退到主机系统时区。 -- `"local"`：始终使用主机系统时区。 +- 省略或 `"user"`：如果设置了你的 `agents.defaults.userTimezone`，则使用它；否则回退到宿主系统时区。 +- `"local"`：始终使用宿主系统时区。 - 任意 IANA 标识符（例如 `America/New_York`）：直接使用；如果无效，则回退到上面的 `"user"` 行为。 -- 对于活动窗口，`start` 和 `end` 不能相等；相等值会被视为零宽度（始终在窗口外）。 -- 在活动窗口外，心跳会被跳过，直到窗口内的下一个 tick。 +- 对于活跃窗口，`start` 和 `end` 不能相等；相等值会被视为零宽度（始终位于窗口外）。 +- 在活跃窗口之外，心跳会被跳过，直到窗口内的下一个 tick。 -## 交付行为 +## 投递行为 - - - 默认情况下，心跳在智能体的主会话中运行（`agent::`），或当 `session.scope = "global"` 时在 `global` 中运行。设置 `session` 可覆盖为特定渠道会话（Discord/WhatsApp 等）。 - - `session` 只影响运行上下文；交付由 `target` 和 `to` 控制。 - - 若要交付到特定渠道/收件人，请设置 `target` + `to`。使用 `target: "last"` 时，交付会使用该会话的最后一个外部渠道。 - - 心跳交付默认允许直接/私信目标。设置 `directPolicy: "block"` 可抑制直接目标发送，同时仍运行心跳轮次。 - - 如果主队列繁忙，心跳会被跳过并稍后重试。 + + - 默认情况下，心跳在智能体的主会话中运行（`agent::`），或者当 `session.scope = "global"` 时在 `global` 中运行。设置 `session` 可覆盖为特定渠道会话（Discord/WhatsApp 等）。 + - `session` 只影响运行上下文；投递由 `target` 和 `to` 控制。 + - 要投递到特定渠道/接收者，请设置 `target` + `to`。使用 `target: "last"` 时，投递会使用该会话最后一个外部渠道。 + - 心跳投递默认允许直接/私信目标。设置 `directPolicy: "block"` 可在仍然运行心跳轮次的同时抑制直接目标发送。 + - 如果主队列、目标会话 lane、cron lane 或活跃的 cron 作业正忙，心跳会被跳过并稍后重试。 + - 如果 `skipWhenBusy: true`，子智能体和嵌套 lane 也会延迟心跳运行。 - 如果 `target` 未解析到外部目的地，运行仍会发生，但不会发送出站消息。 - - - 如果 `showOk`、`showAlerts` 和 `useIndicator` 全部禁用，运行会预先以 `reason=alerts-disabled` 被跳过。 - - 如果只禁用告警交付，OpenClaw 仍可运行心跳、更新到期任务时间戳、恢复会话空闲时间戳，并抑制对外告警载荷。 - - 如果解析出的心跳目标支持输入状态，OpenClaw 会在心跳运行期间显示输入中。这使用心跳会向其发送聊天输出的同一目标，并且会被 `typingMode: "never"` 禁用。 + + - 如果 `showOk`、`showAlerts` 和 `useIndicator` 全部禁用，运行会预先以 `reason=alerts-disabled` 跳过。 + - 如果只禁用了提醒投递，OpenClaw 仍可运行心跳、更新到期任务时间戳、恢复会话空闲时间戳，并抑制对外提醒载荷。 + - 如果解析出的心跳目标支持正在输入状态，OpenClaw 会在心跳运行处于活跃状态时显示正在输入。这使用与心跳发送聊天输出相同的目标，并可通过 `typingMode: "never"` 禁用。 - - - 仅心跳回复**不会**保持会话活跃。心跳元数据可能会更新会话行，但空闲过期使用最后一条真实用户/渠道消息的 `lastInteractionAt`，每日过期使用 `sessionStartedAt`。 - - Control UI 和 WebChat 历史会隐藏心跳提示和仅 OK 确认。底层会话转录仍可包含这些轮次，用于审计/重放。 - - 分离的[后台任务](/zh-CN/automation/tasks)可以入队系统事件，并在主会话应快速注意某事时唤醒心跳。该唤醒不会让心跳运行成为后台任务。 + + - 仅心跳回复**不会**让会话保持活跃。心跳元数据可能会更新会话行，但空闲过期使用最后一条真实用户/渠道消息的 `lastInteractionAt`，每日过期使用 `sessionStartedAt`。 + - Control UI 和 WebChat 历史会隐藏心跳提示词和仅 OK 确认。底层会话转录仍可包含这些轮次，用于审计/重放。 + - 分离的[后台任务](/zh-CN/automation/tasks)可以入队一个系统事件，并在主会话需要快速注意某事时唤醒心跳。该唤醒不会让心跳运行变成后台任务。 ## 可见性控制 -默认情况下，交付告警内容时会抑制 `HEARTBEAT_OK` 确认。你可以按渠道或按账号调整： +默认情况下，`HEARTBEAT_OK` 确认会被抑制，而提醒内容会被投递。你可以按渠道或按账号调整： ```yaml channels: @@ -338,10 +345,10 @@ channels: ### 每个标志的作用 - `showOk`：当模型返回仅 OK 回复时，发送 `HEARTBEAT_OK` 确认。 -- `showAlerts`：当模型返回非 OK 回复时，发送告警内容。 -- `useIndicator`：为 UI 状态界面发出指示器事件。 +- `showAlerts`：当模型返回非 OK 回复时，发送提醒内容。 +- `useIndicator`：为 UI Status 表面发出指示器事件。 -如果**三者**都为 false，OpenClaw 会完全跳过心跳运行（不调用模型）。 +如果**三者全部**为 false，OpenClaw 会完全跳过心跳运行（不调用模型）。 ### 按渠道与按账号示例 @@ -368,20 +375,20 @@ channels: | 目标 | 配置 | | ---------------------------------------- | ---------------------------------------------------------------------------------------- | -| 默认行为（静默 OK，开启告警） | _(无需配置)_ | +| 默认行为（静默 OK，开启提醒） | _(无需配置)_ | | 完全静默（无消息，无指示器） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | | 仅指示器（无消息） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | -| 只在一个渠道中显示 OK | `channels.telegram.heartbeat: { showOk: true }` | +| 仅在一个渠道中显示 OK | `channels.telegram.heartbeat: { showOk: true }` | ## HEARTBEAT.md（可选） -如果工作区中存在 `HEARTBEAT.md` 文件，默认提示会告诉智能体读取它。可以把它看作你的“心跳检查清单”：小巧、稳定，并且适合每 30 分钟包含一次。 +如果工作区中存在 `HEARTBEAT.md` 文件，默认提示词会让智能体读取它。可以把它看作你的“心跳检查清单”：小巧、稳定，并且适合每 30 分钟包含一次。 -在正常运行中，只有为默认智能体启用心跳指导时，才会注入 `HEARTBEAT.md`。用 `0m` 禁用心跳节奏或设置 `includeSystemPromptSection: false` 会将它从正常引导上下文中省略。 +在普通运行中，只有为默认智能体启用心跳指导时，才会注入 `HEARTBEAT.md`。使用 `0m` 禁用心跳节奏，或设置 `includeSystemPromptSection: false`，会将它从普通引导上下文中省略。 -如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和像 `# Heading` 这样的 markdown 标题），OpenClaw 会跳过心跳运行以节省 API 调用。该跳过会报告为 `reason=empty-heartbeat-file`。如果文件缺失，心跳仍会运行，并由模型决定要做什么。 +如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和像 `# Heading` 这样的 Markdown 标题），OpenClaw 会跳过心跳运行以节省 API 调用。该跳过会报告为 `reason=empty-heartbeat-file`。如果文件缺失，心跳仍会运行，并由模型决定要做什么。 -保持它很小（简短检查清单或提醒），以避免提示膨胀。 +保持它很小（简短检查清单或提醒），以避免提示词膨胀。 示例 `HEARTBEAT.md`： @@ -395,7 +402,7 @@ channels: ### `tasks:` 块 -`HEARTBEAT.md` 还支持一个小型结构化 `tasks:` 块，用于心跳内部基于间隔的检查。 +`HEARTBEAT.md` 还支持一个小型结构化 `tasks:` 块，用于在心跳自身内部执行基于间隔的检查。 示例： @@ -416,61 +423,61 @@ tasks: ``` - - - OpenClaw 会解析 `tasks:` 块，并按各自的 `interval` 检查每个任务。 - - 只有**到期**任务会被包含在该 tick 的心跳提示中。 + + - OpenClaw 会解析 `tasks:` 块，并按每个任务自己的 `interval` 检查它。 + - 每个 tick 只会把**到期**任务包含进心跳提示词。 - 如果没有任务到期，心跳会被完全跳过（`reason=no-tasks-due`），以避免浪费模型调用。 - - `HEARTBEAT.md` 中的非任务内容会被保留，并在到期任务列表后作为附加上下文追加。 - - 任务上次运行时间戳存储在会话状态（`heartbeatTaskState`）中，因此间隔能在正常重启后保留。 - - 任务时间戳只会在心跳运行完成其正常回复路径后推进。被跳过的 `empty-heartbeat-file` / `no-tasks-due` 运行不会将任务标记为已完成。 + - `HEARTBEAT.md` 中的非任务内容会被保留，并作为额外上下文追加到到期任务列表之后。 + - 任务上次运行时间戳存储在会话状态中（`heartbeatTaskState`），因此间隔能跨普通重启保留。 + - 只有在一次心跳运行完成其正常回复路径后，任务时间戳才会推进。被跳过的 `empty-heartbeat-file` / `no-tasks-due` 运行不会将任务标记为已完成。 -当你希望一个心跳文件保存多个周期性检查，而不是每个 tick 都为所有检查付费时，任务模式很有用。 +当你希望一个心跳文件容纳多个周期性检查，而无需每个 tick 都为它们全部付费时，任务模式很有用。 ### 智能体可以更新 HEARTBEAT.md 吗？ 可以，如果你要求它这样做。 -`HEARTBEAT.md` 只是智能体工作区中的一个普通文件，所以你可以在普通聊天中告诉智能体，例如： +`HEARTBEAT.md` 只是智能体工作区中的普通文件，因此你可以在普通聊天中告诉智能体，例如： - “更新 `HEARTBEAT.md`，添加每日日历检查。” - “重写 `HEARTBEAT.md`，让它更短并专注于收件箱跟进。” -如果你希望它主动发生，也可以在心跳提示中包含一行明确内容，例如：“如果检查清单变得过时，请用更好的版本更新 HEARTBEAT.md。” +如果你希望这件事主动发生，也可以在心跳提示词中包含一个明确行，例如：“如果检查清单变得过时，请用更好的版本更新 HEARTBEAT.md。” -不要把机密（API 密钥、电话号码、私有令牌）放入 `HEARTBEAT.md`，它会成为提示上下文的一部分。 +不要把密钥（API 密钥、电话号码、私有令牌）放进 `HEARTBEAT.md`，它会成为提示词上下文的一部分。 ## 手动唤醒（按需） -你可以用以下命令入队系统事件并触发立即心跳： +你可以用以下命令入队一个系统事件并触发立即心跳： ```bash openclaw system event --text "Check for urgent follow-ups" --mode now ``` -如果多个智能体配置了 `heartbeat`，手动唤醒会立即运行每个此类智能体心跳。 +如果多个智能体配置了 `heartbeat`，手动唤醒会立即运行每个智能体的心跳。 -使用 `--mode next-heartbeat` 可等待下一次计划 tick。 +使用 `--mode next-heartbeat` 等待下一次计划 tick。 -## 推理交付（可选） +## 推理投递（可选） -默认情况下，心跳只交付最终“答案”载荷。 +默认情况下，心跳只投递最终“答案”载荷。 -如果你需要透明度，请启用： +如果你想要透明度，请启用： - `agents.defaults.heartbeat.includeReasoning: true` -启用后，心跳还会交付一条带 `Reasoning:` 前缀的单独消息（形状与 `/reasoning on` 相同）。当智能体管理多个会话/codex，并且你想看到它为什么决定 ping 你时，这会很有用，但它也可能泄露比你想要更多的内部细节。建议在群聊中保持关闭。 +启用后，心跳还会投递一条以 `Reasoning:` 为前缀的单独消息（形状与 `/reasoning on` 相同）。当智能体正在管理多个会话/codex，并且你想看到它为什么决定 ping 你时，这可能很有用，但它也可能泄露比你想要更多的内部细节。建议在群聊中保持关闭。 ## 成本意识 -心跳会运行完整的智能体轮次。更短的间隔会消耗更多 token。要降低成本： +心跳会运行完整智能体轮次。更短间隔会消耗更多 token。要降低成本： -- 使用 `isolatedSession: true`，避免发送完整对话历史（每次运行约从 100K token 降到约 2-5K）。 +- 使用 `isolatedSession: true`，避免发送完整对话历史（从约 100K token 降到每次约 2-5K）。 - 使用 `lightContext: true`，将引导文件限制为仅 `HEARTBEAT.md`。 - 设置更便宜的 `model`（例如 `ollama/llama3.2:1b`）。 - 保持 `HEARTBEAT.md` 小巧。 @@ -478,11 +485,11 @@ openclaw system event --text "Check for urgent follow-ups" --mode now ## 心跳后的上下文溢出 -如果心跳使用较小的本地模型，例如具有 32k 窗口的 Ollama 模型，并且下一次主会话轮次报告上下文溢出，请检查上一次心跳是否将会话留在了心跳模型上。当最后一个运行时模型匹配已配置的 `heartbeat.model` 时，OpenClaw 的重置消息会指出这一点。 +如果心跳使用较小的本地模型，例如带 32k 窗口的 Ollama 模型，并且下一次主会话轮次报告上下文溢出，请检查上一次心跳是否将会话留在了心跳模型上。当最后一个运行时模型匹配配置的 `heartbeat.model` 时，OpenClaw 的重置消息会指出这一点。 -使用 `isolatedSession: true` 在新会话中运行心跳，将它与 `lightContext: true` 结合以获得最小提示，或选择上下文窗口足够容纳共享会话的心跳模型。 +使用 `isolatedSession: true` 在全新会话中运行心跳，将它与 `lightContext: true` 结合以获得最小提示词，或者选择上下文窗口足够大的心跳模型来适配共享会话。 -## 相关 +## 相关内容 - [自动化和任务](/zh-CN/automation) — 所有自动化机制一览 - [后台任务](/zh-CN/automation/tasks) — 如何跟踪分离的工作 diff --git a/docs/zh-CN/gateway/troubleshooting.md b/docs/zh-CN/gateway/troubleshooting.md index a4c9f1a27..2f779fe32 100644 --- a/docs/zh-CN/gateway/troubleshooting.md +++ b/docs/zh-CN/gateway/troubleshooting.md @@ -1,24 +1,24 @@ --- read_when: - 故障排除中心将你引导到这里，以便进行更深入的诊断 - - 你需要基于稳定症状的运行手册章节，并包含确切命令 + - 你需要基于稳定症状的运行手册章节，并包含精确命令 sidebarTitle: Troubleshooting summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除运行手册 title: 故障排除 x-i18n: - generated_at: "2026-04-28T20:56:35Z" + generated_at: "2026-04-29T09:12:46Z" model: gpt-5.5 provider: openai - source_hash: 2ad4332803ad43f90e793fba71a0fce874b63cb4d4711c6a308ecfa030257cb3 + source_hash: 48735a68daa92678867a9cafb3ceeb37063bb91dee8c4c94e185f74eb0296fcb source_path: gateway/troubleshooting.md workflow: 16 --- -这是深度运行手册。如果你想先走快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。 +此页面是深入运行手册。如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。 ## 命令阶梯 -先按此顺序运行这些命令： +按以下顺序先运行这些命令： ```bash openclaw status @@ -30,15 +30,15 @@ openclaw channels status --probe 预期的健康信号： -- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok`，以及一行 `Capability: ...`。 +- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok` 和一行 `Capability: ...`。 - `openclaw doctor` 未报告阻塞性的配置/服务问题。 -- `openclaw channels status --probe` 显示每个账户的实时传输状态；在支持的地方，还会显示探测/审计结果，例如 `works` 或 `audit ok`。 +- `openclaw channels status --probe` 显示每个账号的实时传输状态，并在受支持时显示探测/审计结果，例如 `works` 或 `audit ok`。 ## 分裂安装和新版配置保护 -当 Gateway 网关服务在更新后意外停止，或者日志显示某个 `openclaw` 二进制文件比上次写入 `openclaw.json` 的版本更旧时，使用本节。 +当 Gateway 网关服务在更新后意外停止，或日志显示某个 `openclaw` 二进制文件比上次写入 `openclaw.json` 的版本更旧时，使用此方法。 -OpenClaw 会用 `meta.lastTouchedVersion` 标记配置写入。只读命令仍可检查由新版 OpenClaw 写入的配置，但来自旧版二进制文件的进程和服务变更会拒绝继续。被阻止的操作包括 Gateway 网关服务启动、停止、重启、卸载、强制服务重装、服务模式 Gateway 网关启动，以及 `gateway --force` 端口清理。 +OpenClaw 会用 `meta.lastTouchedVersion` 标记配置写入。只读命令仍可检查由较新版 OpenClaw 写入的配置，但来自旧版二进制文件的进程和服务变更会被拒绝继续执行。被阻止的操作包括 Gateway 网关服务启动、停止、重启、卸载、强制服务重装、服务模式 Gateway 网关启动，以及 `gateway --force` 端口清理。 ```bash which openclaw @@ -48,10 +48,10 @@ openclaw config get meta.lastTouchedVersion ``` - + 修复 `PATH`，让 `openclaw` 解析到较新的安装，然后重新运行该操作。 - + 从较新的安装重新安装目标 Gateway 网关服务： ```bash @@ -60,18 +60,18 @@ openclaw config get meta.lastTouchedVersion ``` - - 移除仍指向旧 `openclaw` 二进制文件的过期系统包或旧包装器条目。 + + 删除仍指向旧 `openclaw` 二进制文件的过期系统包或旧包装器条目。 -仅在有意降级或紧急恢复时，为单条命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常操作请保持未设置。 +仅在有意降级或紧急恢复时，为单个命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常操作时保持未设置。 -## Anthropic 429 长上下文需要额外用量资格 +## Anthropic 429 长上下文需要额外用量 -当日志/错误包含：`HTTP 429: rate_limit_error: Extra usage is required for long context requests` 时，使用本节。 +当日志/错误包含以下内容时使用：`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。 ```bash openclaw logs --follow @@ -81,37 +81,37 @@ openclaw config get agents.defaults.models 查找： -- 选中的 Anthropic Opus/Sonnet 模型启用了 `params.context1m: true`。 -- 当前 Anthropic 凭证不符合长上下文用量资格。 +- 选中的 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。 +- 当前 Anthropic 凭证没有资格使用长上下文。 - 请求只在需要 1M beta 路径的长会话/模型运行中失败。 修复选项： - - 对该模型禁用 `context1m`，回退到普通上下文窗口。 + + 为该模型禁用 `context1m`，以回退到普通上下文窗口。 - - 使用符合长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API key。 + + 使用有资格发起长上下文请求的 Anthropic 凭证，或切换到 Anthropic API 密钥。 - - 配置回退模型，让 Anthropic 长上下文请求被拒绝时运行仍能继续。 + + 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时继续运行。 相关： - [Anthropic](/zh-CN/providers/anthropic) -- [Token 使用和费用](/zh-CN/reference/token-use) +- [令牌用量和费用](/zh-CN/reference/token-use) - [为什么我会看到来自 Anthropic 的 HTTP 429？](/zh-CN/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) ## 本地 OpenAI 兼容后端通过直接探测，但智能体运行失败 -在以下情况使用本节： +在以下情况使用： -- `curl ... /v1/models` 可用 -- 很小的直接 `/v1/chat/completions` 调用可用 -- OpenClaw 模型运行只在普通智能体轮次上失败 +- `curl ... /v1/models` 正常工作 +- 极小的直接 `/v1/chat/completions` 调用正常工作 +- OpenClaw 模型运行只在正常智能体轮次中失败 ```bash curl http://127.0.0.1:1234/v1/models @@ -124,26 +124,26 @@ openclaw logs --follow 查找： -- 直接的小调用成功，但 OpenClaw 运行只在更大的 prompt 上失败 -- 即使直接 `/v1/chat/completions` 使用相同的裸模型 ID 可用，仍出现 `model_not_found` 或 404 错误 -- 后端报错称 `messages[].content` 预期为字符串 +- 直接的小型调用成功，但 OpenClaw 运行只在更大的提示词上失败 +- 即使直接 `/v1/chat/completions` 使用相同的裸模型 ID 正常工作，也出现 `model_not_found` 或 404 错误 +- 后端错误提示 `messages[].content` 期望字符串 - 使用 OpenAI 兼容本地后端时，间歇出现 `incomplete turn detected ... stopReason=stop payloads=0` 警告 -- 只在更大的 prompt token 数量或完整智能体运行时 prompt 中出现的后端崩溃 +- 只在更大提示词令牌数或完整智能体运行时提示词下出现的后端崩溃 - - - 本地 MLX/vLLM 风格服务器出现 `model_not_found` → 确认 `baseUrl` 包含 `/v1`，`api` 对 `/v1/chat/completions` 后端是 `"openai-completions"`，并且 `models.providers..models[].id` 是提供商本地的裸 ID。选择时带一次提供商前缀，例如 `mlx/mlx-community/Qwen3-30B-A3B-6bit`；目录条目保持为 `mlx-community/Qwen3-30B-A3B-6bit`。 - - `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化 Chat Completions 内容片段。修复：设置 `models.providers..models[].compat.requiresStringContent: true`。 - - `incomplete turn detected ... stopReason=stop payloads=0` → 后端完成了 Chat Completions 请求，但没有为该轮次返回用户可见的助手文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次；持续失败通常意味着后端正在发出空内容/非文本内容，或抑制最终回答文本。 - - 直接的小请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输很可能已经正确；后端在更大的智能体运行时 prompt 形态上失败。 - - 禁用工具后失败减少但未消失 → 工具 schema 是压力的一部分，但剩余问题仍是上游模型/服务器容量限制或后端 bug。 + + - 本地 MLX/vLLM 风格服务器出现 `model_not_found` → 验证 `baseUrl` 包含 `/v1`，`api` 对 `/v1/chat/completions` 后端为 `"openai-completions"`，并且 `models.providers..models[].id` 是提供商本地的裸 ID。选择它时使用一次提供商前缀，例如 `mlx/mlx-community/Qwen3-30B-A3B-6bit`；目录条目保持为 `mlx-community/Qwen3-30B-A3B-6bit`。 + - `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化 Chat Completions 内容部分。修复：设置 `models.providers..models[].compat.requiresStringContent: true`。 + - `incomplete turn detected ... stopReason=stop payloads=0` → 后端完成了 Chat Completions 请求，但没有为该轮返回用户可见的助手文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次；持续失败通常表示后端正在发出空内容/非文本内容，或抑制最终答案文本。 + - 直接的小型请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输很可能已经正确；后端在更大的智能体运行时提示词形状上失败。 + - 禁用工具后失败减少但没有消失 → 工具 schema 是压力的一部分，但剩余问题仍然是上游模型/服务器容量或后端 bug。 - - 1. 对仅支持字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。 + + 1. 为只支持字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。 2. 对无法可靠处理 OpenClaw 工具 schema 表面的模型/后端设置 `compat.supportsTools: false`。 - 3. 尽可能降低 prompt 压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用长上下文支持更强的后端。 - 4. 如果直接的小请求一直通过，而 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并用已被接受的 payload 形态向上游提交复现。 + 3. 在可行时降低提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或具有更强长上下文支持的后端。 + 4. 如果小型直接请求持续通过，而 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并用已接受的载荷形状向上游提交复现。 @@ -155,7 +155,7 @@ openclaw logs --follow ## 没有回复 -如果渠道已上线但没有任何回复，请先检查路由和策略，再重新连接任何东西。 +如果渠道已启动但没有任何响应，请先检查路由和策略，再重新连接任何东西。 ```bash openclaw status @@ -169,7 +169,7 @@ openclaw logs --follow - 私信发送者的配对待处理。 - 群组提及门控（`requireMention`、`mentionPatterns`）。 -- 渠道/群组 allowlist 不匹配。 +- 渠道/群组允许列表不匹配。 常见特征： @@ -183,9 +183,9 @@ openclaw logs --follow - [群组](/zh-CN/channels/groups) - [配对](/zh-CN/channels/pairing) -## 控制面板控制 UI 连接 +## 控制台控制 UI 连接 -当控制面板/控制 UI 无法连接时，验证 URL、身份验证模式和安全上下文假设。 +当控制台/控制 UI 无法连接时，验证 URL、认证模式和安全上下文假设。 ```bash openclaw gateway status @@ -197,40 +197,40 @@ openclaw gateway status --json 查找： -- 正确的探测 URL 和控制面板 URL。 -- 客户端和 Gateway 网关之间的身份验证模式/token 不匹配。 -- 需要设备身份时却使用 HTTP。 +- 正确的探测 URL 和控制台 URL。 +- 客户端与 Gateway 网关之间的认证模式/令牌不匹配。 +- 在需要设备身份的位置使用 HTTP。 - - - `device identity required` → 非安全上下文或缺少设备身份验证。 - - `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 浏览器来源连接，但没有显式 allowlist）。 - - `device nonce required` / `device nonce mismatch` → 客户端未完成基于 challenge 的设备身份验证流程（`connect.challenge` + `device.nonce`）。 - - `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的 payload（或过期时间戳）。 - - `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可使用缓存的设备 token 执行一次受信任重试。 - - 该缓存 token 重试会复用与已配对设备 token 一起存储的缓存 scope 集。显式 `deviceToken` / 显式 `scopes` 调用方则保留其请求的 scope 集。 - - 在该重试路径之外，连接身份验证优先级为：先显式共享 token/密码，然后显式 `deviceToken`，然后已存储设备 token，最后 bootstrap token。 - - 在异步 Tailscale Serve Control UI 路径上，来自相同 `{scope, ip}` 的失败尝试会在限制器记录失败前被串行化。因此，同一客户端发起的两个并发错误重试，第二次可能显示 `retry later`，而不是两个普通不匹配。 - - 来自浏览器来源 loopback 客户端的 `too many failed authentication attempts (retry later)` → 该相同规范化 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源使用单独的桶。 - - 该重试后仍重复出现 `unauthorized` → 共享 token/设备 token 漂移；刷新 token 配置，并在需要时重新批准/轮换设备 token。 - - `gateway connect failed:` → 主机/端口/url 目标错误。 + + - `device identity required` → 非安全上下文或缺少设备认证。 + - `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或你正从非 loopback 浏览器来源连接，且没有显式允许列表）。 + - `device nonce required` / `device nonce mismatch` → 客户端未完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。 + - `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误载荷（或过期时间戳）。 + - `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可以使用缓存设备令牌进行一次可信重试。 + - 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留其请求的作用域集合。 + - 在该重试路径之外，连接认证优先级依次为显式共享令牌/密码、显式 `deviceToken`、已存储设备令牌、引导令牌。 + - 在异步 Tailscale Serve 控制 UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败前被串行化。因此，来自同一客户端的两个错误并发重试可能会让第二次尝试显示 `retry later`，而不是两个普通不匹配。 + - 浏览器来源 loopback 客户端出现 `too many failed authentication attempts (retry later)` → 来自同一规范化 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源使用单独的桶。 + - 该重试后仍反复出现 `unauthorized` → 共享令牌/设备令牌漂移；刷新令牌配置，并在需要时重新批准/轮换设备令牌。 + - `gateway connect failed:` → 主机/端口/URL 目标错误。 -### 身份验证详细代码快速对照 +### 认证详情代码快速映射 使用失败 `connect` 响应中的 `error.details.code` 来选择下一步操作： -| 详细代码 | 含义 | 建议操作 | -| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享令牌。 | 在客户端粘贴/设置令牌后重试。对于仪表板路径：`openclaw config get gateway.auth.token`，然后粘贴到 Control UI 设置中。 | -| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关认证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存令牌重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方会保留请求的作用域。如果仍然失败，请运行 [令牌漂移恢复检查清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 | -| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备令牌已过期或被撤销。 | 使用 [设备 CLI](/zh-CN/cli/devices) 轮换/重新批准设备令牌，然后重新连接。 | -| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后运行 `openclaw devices approve `。在你审查请求的访问权限后，作用域/角色升级使用相同流程。 | +| 详细代码 | 含义 | 建议操作 | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享令牌。 | 在客户端中粘贴/设置令牌并重试。对于控制台路径：`openclaw config get gateway.auth.token`，然后粘贴到 Control UI 设置中。 | +| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关认证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次受信任重试。缓存令牌重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方会保留请求的作用域。如果仍然失败，请运行 [令牌漂移恢复检查清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 | +| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备令牌已过期或被撤销。 | 使用 [设备 CLI](/zh-CN/cli/devices) 轮换/重新批准设备令牌，然后重新连接。 | +| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后运行 `openclaw devices approve `。作用域/角色升级在你审核请求的访问权限后使用同一流程。 | -使用共享 Gateway 网关令牌/密码进行身份验证的直接回环后端 RPC 不应依赖 CLI 的已配对设备作用域基线。如果子智能体或其他内部调用仍然因 `scope-upgrade` 失败，请确认调用方正在使用 `client.id: "gateway-client"` 和 `client.mode: "backend"`，并且未强制使用显式 `deviceIdentity` 或设备令牌。 +使用共享 Gateway 网关令牌/密码认证的直接 loopback 后端 RPC 不应依赖 CLI 的配对设备作用域基线。如果子智能体或其他内部调用仍然因 `scope-upgrade` 失败，请验证调用方正在使用 `client.id: "gateway-client"` 和 `client.mode: "backend"`，并且没有强制指定显式 `deviceIdentity` 或设备令牌。 设备认证 v2 迁移检查： @@ -247,17 +247,17 @@ openclaw gateway status 客户端等待 Gateway 网关发出的 `connect.challenge`。 - - 客户端签名与 challenge 绑定的载荷。 + + 客户端签名与挑战绑定的 payload。 - 客户端发送带有相同 challenge nonce 的 `connect.params.device.nonce`。 + 客户端发送带有相同挑战 nonce 的 `connect.params.device.nonce`。 如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝： -- 已配对设备令牌会话只能管理**自己的**设备，除非调用方也拥有 `operator.admin` +- 配对设备令牌会话只能管理**自己的**设备，除非调用方也具有 `operator.admin` - `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的操作员作用域 相关： @@ -266,7 +266,7 @@ openclaw gateway status - [Control UI](/zh-CN/web/control-ui) - [设备](/zh-CN/cli/devices) - [远程访问](/zh-CN/gateway/remote) -- [可信代理认证](/zh-CN/gateway/trusted-proxy-auth) +- [受信代理认证](/zh-CN/gateway/trusted-proxy-auth) ## Gateway 网关服务未运行 @@ -285,28 +285,28 @@ openclaw gateway status --deep # also scan system-level services - 带退出提示的 `Runtime: stopped`。 - 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。 - 端口/监听器冲突。 -- 使用 `--deep` 时出现额外的 launchd/systemd/schtasks 安装。 +- 使用 `--deep` 时出现额外的 launchd/systemd/schtasks 安装项。 - `Other gateway-like services detected (best effort)` 清理提示。 - - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → local Gateway 网关模式未启用，或配置文件被覆盖并丢失了 `gateway.mode`。修复：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新标记预期的 local 模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。 - - `refusing to bind gateway ... without auth` → 非回环绑定缺少有效的 Gateway 网关认证路径（令牌/密码，或在已配置时使用可信代理）。 + - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 本地 Gateway 网关模式未启用，或配置文件被覆盖并丢失了 `gateway.mode`。修复：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup`，以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径为 `~/.openclaw/openclaw.json`。 + - `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径（令牌/密码，或已配置的受信代理）的情况下绑定到非 loopback 地址。 - `another gateway instance is already listening` / `EADDRINUSE` → 端口冲突。 - - `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数设置应在每台机器上只保留一个 Gateway 网关；如果确实需要多个，请隔离端口 + 配置/状态/工作区。请参阅 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。 - - Doctor 提示 `System-level OpenClaw gateway service detected` → 存在 systemd 系统单元，而用户级服务缺失。在允许 Doctor 安装用户服务前，请移除或禁用重复项；如果该系统单元是预期的 supervisor，请设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。 - - `Gateway service port does not match current gateway config` → 已安装的 supervisor 仍然固定旧的 `--port`。运行 `openclaw doctor --fix` 或 `openclaw gateway install --force`，然后重启 Gateway 网关服务。 + - `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数设置应保持每台机器一个 Gateway 网关；如果确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。 + - Doctor 输出 `System-level OpenClaw gateway service detected` → 存在 systemd 系统单元，而用户级服务缺失。在允许 Doctor 安装用户服务之前，请移除或禁用重复项；如果系统单元是预期的监督器，请设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。 + - `Gateway service port does not match current gateway config` → 已安装的监督器仍然固定旧的 `--port`。运行 `openclaw doctor --fix` 或 `openclaw gateway install --force`，然后重启 Gateway 网关服务。 相关： -- [后台 exec 和进程工具](/zh-CN/gateway/background-process) +- [后台执行和进程工具](/zh-CN/gateway/background-process) - [配置](/zh-CN/gateway/configuration) - [Doctor](/zh-CN/gateway/doctor) -## Gateway 网关恢复了 last-known-good 配置 +## Gateway 网关恢复了最后已知良好配置 当 Gateway 网关启动，但日志显示它恢复了 `openclaw.json` 时使用此项。 @@ -322,19 +322,19 @@ openclaw doctor - `Config auto-restored from last-known-good` - `gateway: invalid config was restored from last-known-good backup` - `config reload restored last-known-good config after invalid-config` -- 活动配置旁边带时间戳的 `openclaw.json.clobbered.*` 文件 +- 活动配置旁带时间戳的 `openclaw.json.clobbered.*` 文件 - 以 `Config recovery warning` 开头的主智能体系统事件 - 被拒绝的配置在启动或热重载期间未通过验证。 - - OpenClaw 将被拒绝的载荷保留为 `.clobbered.*`。 - - 活动配置已从最后一次验证通过的 last-known-good 副本恢复。 - - 下一个主智能体轮次会收到警告，不要盲目重写被拒绝的配置。 - - 如果所有验证问题都位于 `plugins.entries....` 下，OpenClaw 不会恢复整个文件。插件本地失败会保持显眼，同时无关的用户设置仍保留在活动配置中。 + - OpenClaw 将被拒绝的 payload 保留为 `.clobbered.*`。 + - 活动配置已从最后验证通过的最后已知良好副本恢复。 + - 下一轮主智能体会收到警告，不要盲目重写被拒绝的配置。 + - 如果所有验证问题都位于 `plugins.entries....` 下，OpenClaw 不会恢复整个文件。插件本地失败会保持显眼，而无关的用户设置仍留在活动配置中。 - + ```bash CONFIG="$(openclaw config file)" ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head @@ -344,18 +344,18 @@ openclaw doctor ``` - - `.clobbered.*` 存在 → 外部直接编辑或启动读取已被恢复。 - - `.rejected.*` 存在 → OpenClaw 拥有的配置写入在提交前未通过 schema 或覆盖检查。 - - `Config write rejected:` → 该写入尝试丢弃必需结构、大幅缩小文件，或持久化无效配置。 - - `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为被覆盖，因为与 last-known-good 备份相比，它丢失了字段或大小。 - - `Config last-known-good promotion skipped` → 候选配置包含经过遮蔽的密钥占位符，例如 `***`。 + - 存在 `.clobbered.*` → 已恢复外部直接编辑或启动读取的内容。 + - 存在 `.rejected.*` → OpenClaw 所拥有的配置写入在提交前未通过 schema 或覆盖检查。 + - `Config write rejected:` → 该写入尝试删除必需结构、显著缩小文件，或持久化无效配置。 + - `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为被覆盖，因为它与最后已知良好备份相比丢失了字段或大小。 + - `Config last-known-good promotion skipped` → 候选内容包含 `***` 等已遮盖的密钥占位符。 1. 如果恢复后的活动配置正确，请保留它。 - 2. 仅从 `.clobbered.*` 或 `.rejected.*` 复制预期键名，然后使用 `openclaw config set` 或 `config.patch` 应用它们。 - 3. 在重启前运行 `openclaw config validate`。 - 4. 如果你手动编辑，请保留完整 JSON5 配置，而不是只保留你想更改的局部对象。 + 2. 仅从 `.clobbered.*` 或 `.rejected.*` 复制预期键，然后使用 `openclaw config set` 或 `config.patch` 应用它们。 + 3. 重启前运行 `openclaw config validate`。 + 4. 如果手动编辑，请保留完整的 JSON5 配置，而不是只保留你想更改的局部对象。 @@ -368,7 +368,7 @@ openclaw doctor ## Gateway 网关探测警告 -当 `openclaw gateway probe` 能到达某个目标，但仍打印警告块时使用此项。 +当 `openclaw gateway probe` 连接到某个目标，但仍打印警告块时使用此项。 ```bash openclaw gateway probe @@ -379,16 +379,16 @@ openclaw gateway probe --ssh user@gateway-host 查找： - JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。 -- 警告是否关于 SSH 回退、多个 Gateway 网关、缺失作用域或未解析的认证引用。 +- 警告是否与 SSH 回退、多个 Gateway 网关、缺失作用域或未解析的认证引用有关。 常见特征： -- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍然尝试了直接配置/回环目标。 -- `multiple reachable gateways detected` → 多个目标返回了响应。通常这表示有意的多 Gateway 网关设置，或存在过期/重复监听器。 -- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；配对设备身份，或使用带有 `operator.read` 的凭据。 -- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → 连接成功，但完整诊断 RPC 集超时或失败。将其视为一个可达但诊断降级的 Gateway 网关；比较 `--json` 输出中的 `connect.ok` 和 `connect.rpcOk`。 -- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但此客户端在获得正常操作员访问权限前仍需要配对/批准。 -- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 失败目标在此命令路径中无法使用认证材料。 +- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试直接探测已配置/loopback 目标。 +- `multiple reachable gateways detected` → 多个目标响应。通常这意味着有意的多 Gateway 网关设置，或存在过期/重复监听器。 +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；请配对设备身份，或使用具有 `operator.read` 的凭据。 +- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → 连接成功，但完整诊断 RPC 集超时或失败。将其视为可达但诊断能力降级的 Gateway 网关；比较 `--json` 输出中的 `connect.ok` 和 `connect.rpcOk`。 +- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但此客户端在正常操作员访问前仍需要配对/批准。 +- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在此命令路径中，失败目标的认证材料不可用。 相关： @@ -411,13 +411,13 @@ openclaw config get channels 查找： - 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。 -- 群组 allowlist 和提及要求。 +- 群组允许列表和提及要求。 - 缺失的渠道 API 权限/作用域。 常见特征： -- `mention required` → 消息被群组提及策略忽略。 -- `pairing` / 待批准跟踪 → 发送者未获批准。 +- `mention required` → 消息因群组提及策略被忽略。 +- `pairing` / 待审批跟踪 → 发送者未获批准。 - `missing_scope`、`not_in_channel`、`Forbidden`、`401/403` → 渠道认证/权限问题。 相关： @@ -429,7 +429,7 @@ openclaw config get channels ## Cron 和心跳投递 -如果 Cron 或心跳没有运行或没有投递，请先验证调度器状态，再验证投递目标。 +如果 cron 或心跳没有运行，或没有投递，先验证调度器状态，再验证投递目标。 ```bash openclaw cron status @@ -439,21 +439,21 @@ openclaw system heartbeat last openclaw logs --follow ``` -查找： +查看： - Cron 已启用，并且存在下一次唤醒时间。 - 作业运行历史状态（`ok`、`skipped`、`error`）。 -- 心跳跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 +- 心跳跳过原因（`quiet-hours`、`requests-in-flight`、`cron-in-progress`、`lanes-busy`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 - - - `cron: scheduler disabled; jobs will not run automatically` → Cron 已禁用。 + + - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。 - `cron: timer tick failed` → 调度器 tick 失败；检查文件/日志/运行时错误。 - - `heartbeat skipped` 且 `reason=quiet-hours` → 处于活跃时段窗口之外。 + - `heartbeat skipped` 且 `reason=quiet-hours` → 不在活跃时间窗口内。 - `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / Markdown 标题，因此 OpenClaw 会跳过模型调用。 - - `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但本次 tick 没有到期任务。 - - `heartbeat: unknown accountId` → 心跳投递目标的账号 ID 无效。 - - `heartbeat skipped` 且 `reason=dm-blocked` → 心跳目标解析为私信样式目的地，而 `agents.defaults.heartbeat.directPolicy`（或每智能体覆盖项）设置为 `block`。 + - `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但本次 tick 没有任何任务到期。 + - `heartbeat: unknown accountId` → 心跳投递目标的账户 ID 无效。 + - `heartbeat skipped` 且 `reason=dm-blocked` → 心跳目标解析为私信式目标，而 `agents.defaults.heartbeat.directPolicy`（或每智能体覆盖项）设置为 `block`。 @@ -461,12 +461,12 @@ openclaw logs --follow 相关： - [心跳](/zh-CN/gateway/heartbeat) -- [计划任务](/zh-CN/automation/cron-jobs) -- [计划任务：故障排除](/zh-CN/automation/cron-jobs#troubleshooting) +- [定时任务](/zh-CN/automation/cron-jobs) +- [定时任务：故障排除](/zh-CN/automation/cron-jobs#troubleshooting) -## 节点已配对，工具失败 +## 节点已配对，但工具失败 -如果节点已配对但工具失败，请隔离前台、权限和批准状态。 +如果节点已配对但工具失败，请隔离前台、权限和审批状态。 ```bash openclaw nodes status @@ -476,28 +476,28 @@ openclaw logs --follow openclaw status ``` -查找： +查看： -- 节点在线，并具有预期能力。 +- 节点在线，并具备预期能力。 - 摄像头/麦克风/位置/屏幕的操作系统权限授权。 -- Exec 批准和允许列表状态。 +- Exec 审批和允许列表状态。 常见特征： - `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须在前台。 - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少操作系统权限。 -- `SYSTEM_RUN_DENIED: approval required` → Exec 批准待处理。 +- `SYSTEM_RUN_DENIED: approval required` → exec 审批待处理。 - `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表阻止。 相关： -- [Exec 批准](/zh-CN/tools/exec-approvals) +- [Exec 审批](/zh-CN/tools/exec-approvals) - [节点故障排除](/zh-CN/nodes/troubleshooting) - [节点](/zh-CN/nodes/index) ## 浏览器工具失败 -当 Gateway 网关本身健康但浏览器工具操作失败时，请使用此流程。 +当浏览器工具操作失败但 Gateway 网关本身健康时使用这一节。 ```bash openclaw browser status @@ -507,7 +507,7 @@ openclaw logs --follow openclaw doctor ``` -查找： +查看： - `plugins.allow` 是否已设置且包含 `browser`。 - 有效的浏览器可执行文件路径。 @@ -515,33 +515,33 @@ openclaw doctor - `existing-session` / `user` 配置文件的本地 Chrome 可用性。 - + - `unknown command "browser"` 或 `unknown command 'browser'` → 内置浏览器插件被 `plugins.allow` 排除。 - 浏览器工具缺失 / 不可用，但 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此插件从未加载。 - `Failed to start Chrome CDP on port` → 浏览器进程启动失败。 - `browser.executablePath not found` → 配置的路径无效。 - - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议方案，例如 `file:` 或 `ftp:`。 - - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口无效或超出范围。 + - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不支持的 scheme，例如 `file:` 或 `ftp:`。 + - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。 - `Playwright is not available in this gateway build; '' is unsupported.` → 当前 Gateway 网关安装缺少内置浏览器插件的 `playwright-core` 运行时依赖；运行 `openclaw doctor --fix`，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍可工作，但导航、AI 快照、CSS 选择器元素截图和 PDF 导出仍不可用。 - + - `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 尚无法附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器打开，批准第一次附加提示，然后重试。如果不需要登录状态，优先使用托管的 `openclaw` 配置文件。 - `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。 - `Remote CDP for profile "" is not reachable` → 配置的远程 CDP 端点无法从 Gateway 网关主机访问。 - - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可达目标，或 HTTP 端点已响应但 CDP WebSocket 仍无法打开。 + - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可达目标，或 HTTP 端点已响应但仍无法打开 CDP WebSocket。 - + - `fullPage is not supported for element screenshots` → 截图请求将 `--full-page` 与 `--ref` 或 `--element` 混用。 - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 截图调用必须使用页面捕获或快照 `--ref`，而不是 CSS `--element`。 - `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要快照 ref，而不是 CSS 选择器。 - - `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件上每次调用发送一个上传。 + - `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件上，每次调用发送一个上传。 - `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件上的对话框钩子不支持超时覆盖。 - `existing-session type does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:type` 省略 `timeoutMs`，或在需要自定义超时时使用托管/CDP 浏览器配置文件。 - `existing-session evaluate does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:evaluate` 省略 `timeoutMs`，或在需要自定义超时时使用托管/CDP 浏览器配置文件。 - `response body is not supported for existing-session profiles yet.` → `responsebody` 仍需要托管浏览器或原始 CDP 配置文件。 - - 附加专用或远程 CDP 配置文件上的过期视口 / 深色模式 / 区域设置 / 离线覆盖 → 运行 `openclaw browser stop --browser-profile ` 关闭活跃控制会话，并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。 + - 仅附加或远程 CDP 配置文件上的过期视口 / 深色模式 / 区域设置 / 离线覆盖 → 运行 `openclaw browser stop --browser-profile ` 关闭活跃控制会话，并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。 @@ -551,12 +551,12 @@ openclaw doctor - [浏览器（OpenClaw 托管）](/zh-CN/tools/browser) - [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting) -## 如果你升级后某些东西突然坏了 +## 如果你升级后某些内容突然损坏 -大多数升级后的故障来自配置漂移，或现在会强制执行的更严格默认值。 +大多数升级后故障来自配置漂移，或现在开始强制执行更严格的默认值。 - + ```bash openclaw gateway status openclaw config get gateway.mode @@ -566,8 +566,8 @@ openclaw doctor 要检查的内容： - - 如果 `gateway.mode=remote`，CLI 调用可能会指向远程，而你的本地服务是正常的。 - - 显式 `--url` 调用不会回退到已存储的凭证。 + - 如果 `gateway.mode=remote`，CLI 调用可能正在指向远程，而你的本地服务本身正常。 + - 显式 `--url` 调用不会回退到存储的凭证。 常见特征： @@ -575,7 +575,7 @@ openclaw doctor - `unauthorized` → 端点可达，但认证错误。 - + ```bash openclaw config get gateway.bind openclaw config get gateway.auth.mode @@ -586,16 +586,16 @@ openclaw doctor 要检查的内容： - - 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享令牌/密码认证，或正确配置的非 loopback `trusted-proxy` 部署。 - - `gateway.token` 等旧键不会替代 `gateway.auth.token`。 + - 非 local loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享令牌/密码认证，或正确配置的非 local loopback `trusted-proxy` 部署。 + - 旧键（如 `gateway.token`）不能替代 `gateway.auth.token`。 常见特征： - - `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径。 - - `Connectivity probe: failed` 且运行时正在运行 → Gateway 网关存活，但当前认证/url 无法访问。 + - `refusing to bind gateway ... without auth` → 非 local loopback 绑定没有有效的 Gateway 网关认证路径。 + - `Connectivity probe: failed` 且运行时正在运行 → Gateway 网关存活，但使用当前认证/url 无法访问。 - + ```bash openclaw devices list openclaw pairing list --channel [--account ] @@ -605,13 +605,13 @@ openclaw doctor 要检查的内容： - - 仪表板/节点的待处理设备批准。 - - 策略或身份变更后的待处理私信配对批准。 + - dashboard/节点的待处理设备审批。 + - 策略或身份更改后的待处理私信配对审批。 常见特征： - `device identity required` → 设备认证未满足。 - - `pairing required` → 发送者/设备必须获批准。 + - `pairing required` → 发送者/设备必须获批。 @@ -627,7 +627,7 @@ openclaw gateway restart - [认证](/zh-CN/gateway/authentication) - [后台 exec 和进程工具](/zh-CN/gateway/background-process) -- [Gateway 网关拥有的配对](/zh-CN/gateway/pairing) +- [Gateway 网关托管的配对](/zh-CN/gateway/pairing) ## 相关