diff --git a/docs/zh-CN/automation/cron-jobs.md b/docs/zh-CN/automation/cron-jobs.md index 073c8ce75..cac12c48d 100644 --- a/docs/zh-CN/automation/cron-jobs.md +++ b/docs/zh-CN/automation/cron-jobs.md @@ -1,25 +1,25 @@ --- read_when: - - 调度后台作业或唤醒任务 + - 安排后台作业或唤醒任务 - 将外部触发器（webhooks、Gmail）接入 OpenClaw - - 为计划任务决定使用 heartbeat 还是 cron -summary: 用于 Gateway 网关调度器的计划任务、webhooks 和 Gmail PubSub 触发器 -title: 计划任务 + - 为定时任务在心跳和 cron 之间做出选择 +summary: 用于 Gateway 网关 调度器的定时任务、webhooks 和 Gmail PubSub 触发器 +title: 定时任务 x-i18n: - generated_at: "2026-04-25T05:53:14Z" + generated_at: "2026-04-26T01:24:04Z" model: gpt-5.4 provider: openai - source_hash: 9ed4dc7222b601b37d98cf1575ced7fd865987882a8c5b28245c5d2423b4cc56 + source_hash: 339bb43e7fa34d4307221b4587402d31ebad7642dee36e32f5a91ca44fa06775 source_path: automation/cron-jobs.md workflow: 15 --- -Cron 是 Gateway 网关内置的调度器。它会持久化作业，在正确的时间唤醒智能体，并可将输出回传到聊天渠道或 webhook 端点。 +Cron 是 Gateway 网关 的内置调度器。它会持久化作业，在正确的时间唤醒智能体，并且可以将输出回传到聊天渠道或 webhook 端点。 ## 快速开始 ```bash -# 添加一次性提醒 +# 添加一个一次性提醒 openclaw cron add \ --name "Reminder" \ --at "2026-02-01T16:00:00Z" \ @@ -38,102 +38,104 @@ openclaw cron runs --id ## cron 的工作方式 -- Cron 在 **Gateway 网关** 进程**内部**运行（不是在模型内部）。 -- 作业定义持久化保存在 `~/.openclaw/cron/jobs.json`，因此重启不会丢失调度计划。 -- 运行时执行状态保存在旁边的 `~/.openclaw/cron/jobs-state.json`。如果你用 git 跟踪 cron 定义，请跟踪 `jobs.json`，并将 `jobs-state.json` 加入 gitignore。 -- 拆分之后，较旧版本的 OpenClaw 可以读取 `jobs.json`，但可能会将作业视为全新作业，因为运行时字段现在保存在 `jobs-state.json` 中。 +- Cron 运行在 **Gateway 网关** 进程内部（而不是在模型内部）。 +- 作业定义会持久化到 `~/.openclaw/cron/jobs.json`，因此重启不会丢失调度。 +- 运行时执行状态会持久化到相邻的 `~/.openclaw/cron/jobs-state.json`。如果你用 git 跟踪 cron 定义，请跟踪 `jobs.json`，并将 `jobs-state.json` 添加到 `.gitignore`。 +- 拆分之后，较旧版本的 OpenClaw 可以读取 `jobs.json`，但可能会将作业视为全新作业，因为运行时字段现在存放在 `jobs-state.json` 中。 - 所有 cron 执行都会创建[后台任务](/zh-CN/automation/tasks)记录。 -- 一次性作业（`--at`）默认在成功后自动删除。 -- 隔离的 cron 运行会尽力关闭其 `cron:` 会话所跟踪的浏览器标签页 / 进程，因此分离的浏览器自动化不会在运行完成后留下孤儿进程。 -- 隔离的 cron 运行还会防止陈旧的确认回复。如果第一个结果只是临时状态更新（例如 `on it`、`pulling everything together` 以及类似提示），并且没有后代子智能体运行仍负责最终答案，OpenClaw 会在交付前再次提示一次以获取实际结果。 +- 一次性作业（`--at`）在成功后默认自动删除。 +- 隔离的 cron 运行会尽力在运行完成时关闭其 `cron:` 会话所跟踪的浏览器标签页/进程，这样分离的浏览器自动化就不会留下孤儿进程。 +- 隔离的 cron 运行还会防止陈旧的确认式回复。如果第一个结果只是中间状态更新（例如 `on it`、`pulling everything together` 之类的提示），并且没有任何后代子智能体运行仍负责最终答案，OpenClaw 会在交付前再次提示一次以获取实际结果。 -cron 的任务协调由运行时负责：只要 cron 运行时仍将该作业标记为正在运行，活动的 cron 任务就会保持存活，即使旧的子会话行仍然存在也是如此。一旦运行时不再拥有该作业且 5 分钟宽限期到期，维护过程就可以将任务标记为 `lost`。 +cron 的任务对账由运行时负责：只要 cron 运行时仍将该作业跟踪为正在运行，对应的活跃 cron 任务就会保持存活，即使旧的子会话行仍然存在也是如此。一旦运行时不再拥有该作业，并且 5 分钟宽限期结束，维护流程就可以将任务标记为 `lost`。 ## 调度类型 -| 类型 | CLI 标志 | 描述 | -| ------- | --------- | ---- | +| 类型 | CLI 标志 | 描述 | +| ------- | --------- | ------------------------------------------------ | | `at` | `--at` | 一次性时间戳（ISO 8601 或类似 `20m` 的相对时间） | -| `every` | `--every` | 固定间隔 | -| `cron` | `--cron` | 5 字段或 6 字段的 cron 表达式，可选 `--tz` | +| `every` | `--every` | 固定间隔 | +| `cron` | `--cron` | 5 字段或 6 字段的 cron 表达式，可选 `--tz` | -不带时区的时间戳会按 UTC 处理。添加 `--tz America/New_York` 可按本地挂钟时间调度。 +不带时区的时间戳会被视为 UTC。添加 `--tz America/New_York` 可按本地挂钟时间调度。 -每小时整点循环表达式会自动错峰，最多延后 5 分钟，以降低负载尖峰。使用 `--exact` 可强制精确时间，或使用 `--stagger 30s` 指定明确的错峰窗口。 +每小时整点重复表达式会自动错开最多 5 分钟，以减少负载峰值。使用 `--exact` 可强制精确时间，或使用 `--stagger 30s` 指定明确的错开窗口。 -### 月中的某一天和星期几使用 OR 逻辑 +### day-of-month 和 day-of-week 使用 OR 逻辑 -Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当“月中的某一天”和“星期几”两个字段都不是通配符时，croner 会在**任一**字段匹配时触发——而不是两个都匹配。这是标准的 Vixie cron 行为。 +Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当 day-of-month 和 day-of-week 字段都不是通配符时，croner 会在**任一**字段匹配时触发，而不是两个都匹配时才触发。这是标准的 Vixie cron 行为。 ``` -# 预期："每月 15 日上午 9 点，但仅当这天是周一" -# 实际："每月 15 日上午 9 点，以及每个周一上午 9 点" +# 预期："15 日上午 9 点，且仅当它是星期一时" +# 实际： "每月每个 15 日上午 9 点，以及每周每个星期一上午 9 点" 0 9 15 * 1 ``` -这会每月触发约 5–6 次，而不是每月 0–1 次。OpenClaw 在这里使用 Croner 默认的 OR 行为。若要同时要求两个条件，请使用 Croner 的 `+` 星期几修饰符（`0 9 15 * +1`），或者仅基于其中一个字段调度，并在你的作业提示词或命令中校验另一个条件。 +这样每月会触发约 5–6 次，而不是 0–1 次。OpenClaw 在这里使用 Croner 默认的 OR 行为。若要同时要求两个条件，请使用 Croner 的 `+` day-of-week 修饰符（`0 9 15 * +1`），或者只在一个字段上调度，并在你的作业提示或命令中对另一个条件进行守护判断。 -## 执行方式 +## 执行样式 -| 方式 | `--session` 值 | 运行位置 | 最适合 | -| --------------- | ------------------- | ------------------------ | ------ | -| 主会话 | `main` | 下一次 heartbeat 轮次 | 提醒、系统事件 | -| 隔离 | `isolated` | 专用 `cron:` | 报告、后台事务 | -| 当前会话 | `current` | 在创建时绑定 | 依赖上下文的循环工作 | -| 自定义会话 | `session:custom-id` | 持久命名会话 | 基于历史构建的工作流 | +| 样式 | `--session` 值 | 运行位置 | 最适合 | +| -------------- | ----------------- | ------------------------ | ----------------------------- | +| 主会话 | `main` | 下一次心跳回合 | 提醒、系统事件 | +| 隔离 | `isolated` | 专用 `cron:` | 报告、后台杂务 | +| 当前会话 | `current` | 在创建时绑定 | 需要上下文感知的重复工作 | +| 自定义会话 | `session:custom-id` | 持久化命名会话 | 基于历史构建的工作流 | -**主会话**作业会排入一个系统事件，并可选唤醒 heartbeat（`--wake now` 或 `--wake next-heartbeat`）。**隔离**作业会以全新会话运行一个专用智能体轮次。**自定义会话**（`session:xxx`）会在多次运行之间保留上下文，从而支持例如基于先前摘要构建的每日站会等工作流。 +**主会话**作业会排入一个系统事件，并可选择唤醒心跳（`--wake now` 或 `--wake next-heartbeat`）。**隔离**作业会以全新会话运行一个专用智能体回合。**自定义会话**（`session:xxx`）会在多次运行之间持久化上下文，从而支持类似基于先前摘要构建的每日站会工作流。 -对于隔离作业，“全新会话”表示每次运行都有新的 transcript / session id。OpenClaw 可能会保留安全的偏好设置，例如 thinking / fast / verbose 设置、标签以及用户显式选择的模型 / 凭证覆盖，但不会继承旧 cron 记录中的环境会话上下文：渠道 / 群组路由、发送或排队策略、提权、来源或 ACP 运行时绑定。如果循环作业应有意建立在同一会话上下文之上，请使用 `current` 或 `session:`。 +对于隔离作业，“全新会话”意味着每次运行都会有新的 transcript/session id。OpenClaw 可能会携带安全的偏好设置，例如 thinking/fast/verbose 设置、标签，以及用户显式选择的 model/auth 覆盖，但不会继承旧 cron 行中的环境对话上下文：渠道/群组路由、发送或排队策略、权限提升、来源或 ACP 运行时绑定。如果某个重复作业应有意基于同一对话上下文继续运行，请使用 `current` 或 `session:`。 -对于隔离作业，运行时拆除现在包括尽力清理该 cron 会话的浏览器。清理失败会被忽略，因此实际的 cron 结果仍然优先。 +对于隔离作业，运行时清理现在还包括尽力清理该 cron 会话的浏览器。清理失败会被忽略，因此真正的 cron 结果仍然优先。 -隔离的 cron 运行还会通过共享的运行时清理路径，释放为该作业创建的所有内置 MCP 运行时实例。这与主会话和自定义会话的 MCP 客户端销毁方式一致，因此隔离的 cron 作业不会在多次运行间泄漏 stdio 子进程或长期存在的 MCP 连接。 +隔离的 cron 运行还会通过共享运行时清理路径，释放该作业创建的所有内置 MCP 运行时实例。这与主会话和自定义会话的 MCP 客户端销毁方式一致，因此隔离的 cron 作业不会在多次运行之间泄漏 stdio 子进程或长期存在的 MCP 连接。 -当隔离的 cron 运行协调子智能体时，交付也会优先使用最终的后代输出，而不是陈旧的父级临时文本。如果后代仍在运行，OpenClaw 会抑制该部分父级更新，而不是把它公布出去。 +当隔离的 cron 运行编排子智能体时，交付也会优先选择最终的后代输出，而不是陈旧的父级中间文本。如果后代仍在运行，OpenClaw 会抑制该父级部分更新，而不是对外宣布它。 -对于纯文本的 Discord 通知目标，OpenClaw 只会发送一次规范的最终助手文本，而不会同时重放流式 / 中间文本负载和最终答案。媒体和结构化的 Discord 负载仍会作为独立负载交付，以避免附件和组件被丢弃。 +对于仅文本的 Discord announce 目标，OpenClaw 只会发送一次规范的最终 assistant 文本，而不是同时重放流式/中间文本负载和最终答案。媒体和结构化的 Discord 负载仍会作为单独负载交付，以避免附件和组件丢失。 ### 隔离作业的负载选项 -- `--message`：提示词文本（隔离模式必需） +- `--message`：提示文本（隔离模式必需） - `--model` / `--thinking`：模型和 thinking 级别覆盖 - `--light-context`：跳过工作区引导文件注入 - `--tools exec,read`：限制作业可使用的工具 -`--model` 会为该作业使用所选且被允许的模型。如果请求的模型不被允许，cron 会记录警告，并改为回退到该作业的智能体 / 默认模型选择。已配置的回退链仍然适用，但单纯的模型覆盖在没有显式的按作业回退列表时，不再把智能体主模型追加为隐藏的额外重试目标。 +`--model` 会为该作业使用所选的允许模型。如果请求的模型不被允许，cron 会记录警告，并回退到该作业的智能体/默认模型选择。已配置的回退链仍然适用，但仅指定模型覆盖且没有显式按作业设置回退列表时，不再将智能体主模型作为隐藏的额外重试目标附加进去。 隔离作业的模型选择优先级如下： 1. Gmail hook 模型覆盖（当运行来自 Gmail 且该覆盖被允许时） 2. 按作业负载中的 `model` -3. 用户选择的已存储 cron 会话模型覆盖 -4. 智能体 / 默认模型选择 +3. 用户选择并存储的 cron 会话模型覆盖 +4. 智能体/默认模型选择 -Fast mode 也会遵循解析后的实时选择。如果所选模型配置带有 `params.fastMode`，隔离的 cron 默认会使用它。已存储的会话 `fastMode` 覆盖在任一方向上都仍然优先于配置。 +Fast 模式也会遵循解析后的实时选择。如果所选模型配置具有 `params.fastMode`，隔离的 cron 默认会使用它。已存储的会话 `fastMode` 覆盖仍然优先于配置，无论方向如何。 -如果某个隔离运行遇到实时模型切换交接，cron 会使用切换后的 provider / 模型重试，并在重试前为当前运行持久化该实时选择。当切换同时携带新的 auth profile 时，cron 也会为当前运行持久化该 auth profile 覆盖。重试次数有上限：在初始尝试加上 2 次切换重试之后，cron 会中止，而不是无限循环。 +如果隔离运行遇到实时模型切换交接，cron 会使用切换后的 provider/模型重试，并在重试前为当前运行持久化该实时选择。当切换同时携带新的 auth 配置文件时，cron 也会为当前运行持久化该 auth 配置文件覆盖。重试是有界的：在初始尝试加上 2 次切换重试之后，cron 会中止，而不是无限循环。 ## 交付与输出 -| 模式 | 发生的情况 | -| ---------- | ---------- | -| `announce` | 如果智能体未发送，则回退交付最终文本到目标 | -| `webhook` | 向某个 URL `POST` 完成事件负载 | -| `none` | 运行器不做回退交付 | +| 模式 | 发生的情况 | +| ---------- | -------------------------------------------------------------- | +| `announce` | 如果智能体未发送，则回退交付最终文本到目标 | +| `webhook` | 将完成事件负载 POST 到某个 URL | +| `none` | 运行器不执行回退交付 | -使用 `--announce --channel telegram --to "-1001234567890"` 可交付到渠道。对于 Telegram forum topics，使用 `-1001234567890:topic:123`。Slack / Discord / Mattermost 目标应使用显式前缀（`channel:`、`user:`）。 +使用 `--announce --channel telegram --to "-1001234567890"` 可进行渠道交付。对于 Telegram forum topic，请使用 `-1001234567890:topic:123`。Slack/Discord/Mattermost 目标应使用显式前缀（`channel:`、`user:`）。Matrix 房间 ID 区分大小写；请使用精确的房间 ID，或使用来自 Matrix 的 `room:!room:server` 形式。 -对于隔离作业，聊天交付是共享的。如果存在聊天路由，即使作业使用 `--no-deliver`，智能体仍可使用 `message` 工具。如果智能体发送到了已配置 / 当前目标，OpenClaw 会跳过回退通知。否则，`announce`、`webhook` 和 `none` 只控制运行器如何在智能体轮次结束后处理最终回复。 +对于隔离作业，聊天交付是共享的。如果聊天路由可用，即使作业使用了 `--no-deliver`，智能体仍可使用 `message` 工具。如果智能体发送到了已配置/当前目标，OpenClaw 就会跳过回退 announce。否则，`announce`、`webhook` 和 `none` 仅控制运行器在智能体回合结束后如何处理最终回复。 + +当智能体从活动聊天中创建隔离提醒时，OpenClaw 会为回退 announce 路由存储保留下来的实时交付目标。内部会话键名可能是小写；当当前聊天上下文可用时，不会基于这些键名重建 provider 交付目标。 失败通知遵循单独的目标路径： -- `cron.failureDestination` 设置失败通知的全局默认值。 -- `job.delivery.failureDestination` 可按作业覆盖它。 -- 如果两者都未设置，且作业已通过 `announce` 交付，失败通知现在会回退到该主要通知目标。 -- `delivery.failureDestination` 仅在 `sessionTarget="isolated"` 的作业中受支持，除非主要交付模式是 `webhook`。 +- `cron.failureDestination` 设置失败通知的全局默认目标。 +- `job.delivery.failureDestination` 可按作业覆盖该设置。 +- 如果两者都未设置，且该作业已通过 `announce` 交付，则失败通知现在会回退到该主 announce 目标。 +- `delivery.failureDestination` 仅在 `sessionTarget="isolated"` 作业中受支持，除非主交付模式是 `webhook`。 ## CLI 示例 @@ -148,7 +150,7 @@ openclaw cron add \ --wake now ``` -带交付的循环隔离作业： +带交付的重复隔离作业： ```bash openclaw cron add \ @@ -178,7 +180,7 @@ openclaw cron add \ ## Webhooks -Gateway 网关可以暴露 HTTP webhook 端点以接收外部触发器。在配置中启用： +Gateway 网关 可以暴露 HTTP webhook 端点以供外部触发器使用。在配置中启用： ```json5 { @@ -192,12 +194,12 @@ Gateway 网关可以暴露 HTTP webhook 端点以接收外部触发器。在配 ### 身份验证 -每个请求都必须通过请求头携带 hook token： +每个请求都必须通过请求头包含 hook token： - `Authorization: Bearer `（推荐） - `x-openclaw-token: ` -不接受查询字符串中的 token。 +查询字符串中的 token 会被拒绝。 ### POST /hooks/wake @@ -215,7 +217,7 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \ ### POST /hooks/agent -运行一个隔离的智能体轮次： +运行一个隔离的智能体回合： ```bash curl -X POST http://127.0.0.1:18789/hooks/agent \ @@ -228,16 +230,16 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \ ### 映射 hooks（POST /hooks/\） -自定义 hook 名称通过配置中的 `hooks.mappings` 解析。映射可以使用模板或代码转换，将任意负载转换为 `wake` 或 `agent` 动作。 +自定义 hook 名称会通过配置中的 `hooks.mappings` 进行解析。映射可以使用模板或代码转换，将任意负载转换为 `wake` 或 `agent` 动作。 ### 安全性 -- 将 hook 端点置于 loopback、tailnet 或受信任的反向代理之后。 -- 使用专用的 hook token；不要复用 gateway 认证 token。 +- 将 hook 端点放在 local loopback、tailnet 或受信任的反向代理之后。 +- 使用专用 hook token；不要复用 gateway 身份验证 token。 - 将 `hooks.path` 保持在专用子路径下；`/` 会被拒绝。 -- 设置 `hooks.allowedAgentIds` 以限制显式的 `agentId` 路由。 +- 设置 `hooks.allowedAgentIds` 以限制显式 `agentId` 路由。 - 保持 `hooks.allowRequestSessionKey=false`，除非你确实需要由调用方选择会话。 -- 如果你启用了 `hooks.allowRequestSessionKey`，也请设置 `hooks.allowedSessionKeyPrefixes` 以限制允许的会话键形态。 +- 如果你启用了 `hooks.allowRequestSessionKey`，也应同时设置 `hooks.allowedSessionKeyPrefixes`，以约束允许的会话键名形态。 - 默认情况下，hook 负载会包裹安全边界。 ## Gmail PubSub 集成 @@ -254,9 +256,9 @@ openclaw webhooks gmail setup --account openclaw@gmail.com 这会写入 `hooks.gmail` 配置、启用 Gmail 预设，并为推送端点使用 Tailscale Funnel。 -### Gateway 网关自动启动 +### Gateway 网关 自动启动 -当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway 网关会在启动时启动 `gog gmail watch serve`，并自动续订 watch。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可选择退出。 +当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway 网关 会在启动时运行 `gog gmail watch serve` 并自动续订 watch。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可选择退出。 ### 手动一次性设置 @@ -330,10 +332,10 @@ openclaw cron edit --clear-agent 模型覆盖说明： -- `openclaw cron add|edit --model ...` 会更改作业所选的模型。 -- 如果该模型被允许，那个精确的 provider / 模型 就会传递到隔离的智能体运行。 -- 如果不被允许，cron 会发出警告，并回退到该作业的智能体 / 默认模型选择。 -- 已配置的回退链仍然适用，但普通的 `--model` 覆盖在没有显式按作业回退列表时，不再静默回退到智能体主模型作为额外重试目标。 +- `openclaw cron add|edit --model ...` 会更改作业的所选模型。 +- 如果该模型被允许，该精确 provider/模型 会传递到隔离的智能体运行中。 +- 如果不被允许，cron 会发出警告，并回退到该作业的智能体/默认模型选择。 +- 已配置的回退链仍然适用，但普通的 `--model` 覆盖若没有显式的按作业回退列表，将不再静默回退到智能体主模型作为额外的重试目标。 ## 配置 @@ -355,13 +357,13 @@ openclaw cron edit --clear-agent } ``` -运行时状态 sidecar 由 `cron.store` 派生：像 `~/clawd/cron/jobs.json` 这样的 `.json` 存储会使用 `~/clawd/cron/jobs-state.json`，而没有 `.json` 后缀的存储路径则会追加 `-state.json`。 +运行时状态 sidecar 基于 `cron.store` 推导：像 `~/clawd/cron/jobs.json` 这样的 `.json` 存储会使用 `~/clawd/cron/jobs-state.json`，而不带 `.json` 后缀的存储路径则会附加 `-state.json`。 禁用 cron：`cron.enabled: false` 或 `OPENCLAW_SKIP_CRON=1`。 -**一次性重试**：瞬时错误（速率限制、过载、网络、服务器错误）最多重试 3 次，并使用指数退避。永久错误会立即禁用。 +**一次性重试**：瞬态错误（限流、过载、网络、服务器错误）会以指数退避最多重试 3 次。永久错误会立即禁用。 -**循环重试**：重试之间使用指数退避（30 秒到 60 分钟）。在下一次成功运行后，退避会重置。 +**重复作业重试**：重试之间采用指数退避（30 秒到 60 分钟）。在下一次成功运行后，退避会重置。 **维护**：`cron.sessionRetention`（默认 `24h`）会清理隔离运行的会话条目。`cron.runLog.maxBytes` / `cron.runLog.keepLines` 会自动清理运行日志文件。 @@ -383,27 +385,28 @@ openclaw doctor ### Cron 未触发 - 检查 `cron.enabled` 和 `OPENCLAW_SKIP_CRON` 环境变量。 -- 确认 Gateway 网关在持续运行。 +- 确认 Gateway 网关 持续运行。 - 对于 `cron` 调度，验证时区（`--tz`）与主机时区是否一致。 - 运行输出中的 `reason: not-due` 表示通过 `openclaw cron run --due` 检查手动运行时，该作业尚未到期。 -### Cron 已触发但没有交付 +### Cron 已触发但未交付 -- 交付模式为 `none` 表示预期不会有运行器回退发送。当存在聊天路由时，智能体仍可通过 `message` 工具直接发送。 -- 交付目标缺失 / 无效（`channel` / `to`）表示已跳过出站发送。 -- 渠道认证错误（`unauthorized`、`Forbidden`）表示交付被凭证阻止。 -- 如果隔离运行只返回静默 token（`NO_REPLY` / `no_reply`），OpenClaw 会抑制直接出站交付，也会抑制回退排队摘要路径，因此不会向聊天回发任何内容。 -- 如果应由智能体自行向用户发送消息，请检查该作业是否有可用路由（带有先前聊天记录的 `channel: "last"`，或显式的 channel / target）。 +- 交付模式 `none` 表示不会进行运行器回退发送。若聊天路由可用，智能体仍可通过 `message` 工具直接发送。 +- 缺少/无效的交付目标（`channel`/`to`）意味着出站已被跳过。 +- 对于 Matrix，复制的或旧作业中小写化的 `delivery.to` 房间 ID 可能会失败，因为 Matrix 房间 ID 区分大小写。请将作业编辑为来自 Matrix 的精确 `!room:server` 或 `room:!room:server` 值。 +- 渠道身份验证错误（`unauthorized`、`Forbidden`）表示交付因凭据问题被阻止。 +- 如果隔离运行只返回静默 token（`NO_REPLY` / `no_reply`），OpenClaw 会抑制直接出站交付，也会抑制回退的排队摘要路径，因此不会有任何内容回发到聊天。 +- 如果智能体本应自行向用户发送消息，请检查该作业是否具有可用路由（带先前聊天记录的 `channel: "last"`，或显式的渠道/目标）。 ### 时区注意事项 -- 未指定 `--tz` 的 cron 会使用 gateway 主机时区。 -- 未指定时区的 `at` 调度会按 UTC 处理。 +- 不带 `--tz` 的 cron 使用 gateway 主机时区。 +- 不带时区的 `at` 调度会被视为 UTC。 - Heartbeat `activeHours` 使用已配置的时区解析。 ## 相关内容 -- [Automation & Tasks](/zh-CN/automation) — 所有自动化机制概览 -- [Background Tasks](/zh-CN/automation/tasks) — cron 执行的任务账本 -- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性的主会话轮次 -- [Timezone](/zh-CN/concepts/timezone) — 时区配置 +- [Automation & Tasks](/zh-CN/automation) —— 所有自动化机制一览 +- [Background Tasks](/zh-CN/automation/tasks) —— cron 执行的任务台账 +- [Heartbeat](/zh-CN/gateway/heartbeat) —— 定期主会话回合 +- [Timezone](/zh-CN/concepts/timezone) —— 时区配置 diff --git a/docs/zh-CN/channels/matrix.md b/docs/zh-CN/channels/matrix.md index 3b4efc8f2..0e9568001 100644 --- a/docs/zh-CN/channels/matrix.md +++ b/docs/zh-CN/channels/matrix.md @@ -5,22 +5,22 @@ read_when: summary: Matrix 支持状态、设置和配置示例 title: Matrix x-i18n: - generated_at: "2026-04-25T21:53:54Z" + generated_at: "2026-04-26T01:24:04Z" model: gpt-5.4 provider: openai - source_hash: faa07a34cbf7b660675298dd0570d1f09b00d578466e7e65e6909c9677bdbccf + source_hash: 1850d51aba7279a3d495c346809b4df26d7da4b7611c5a8c9ab70f9a2b3c827d source_path: channels/matrix.md workflow: 15 --- -Matrix 是 OpenClaw 的一个内置渠道插件。 -它使用官方的 `matrix-js-sdk`，并支持私信、房间、线程、媒体、回应、投票、位置和端到端加密。 +Matrix 是 OpenClaw 的内置渠道插件。 +它使用官方 `matrix-js-sdk`，并支持私信、房间、线程、媒体、回应、投票、位置和端到端加密。 ## 内置插件 -Matrix 会作为内置插件随当前的 OpenClaw 版本一起发布，因此正常的打包构建不需要单独安装。 +Matrix 作为内置插件随当前 OpenClaw 版本一起发布，因此普通打包构建无需单独安装。 -如果你使用的是较旧的构建版本，或是不包含 Matrix 的自定义安装，请手动安装： +如果你使用的是较旧版本，或是不包含 Matrix 的自定义安装，请手动安装： 从 npm 安装： @@ -28,7 +28,7 @@ Matrix 会作为内置插件随当前的 OpenClaw 版本一起发布，因此正 openclaw plugins install @openclaw/matrix ``` -从本地检出目录安装： +从本地检出安装： ```bash openclaw plugins install ./path/to/local/matrix-plugin @@ -39,15 +39,15 @@ openclaw plugins install ./path/to/local/matrix-plugin ## 设置 1. 确保 Matrix 插件可用。 - - 当前打包的 OpenClaw 版本已经内置了它。 - - 较旧版本或自定义安装可以使用上面的命令手动添加。 + - 当前打包的 OpenClaw 版本已内置该插件。 + - 较旧版本/自定义安装可使用上述命令手动添加。 2. 在你的 homeserver 上创建一个 Matrix 账户。 -3. 配置 `channels.matrix`，使用以下任一方式： +3. 使用以下任一方式配置 `channels.matrix`： - `homeserver` + `accessToken`，或 - `homeserver` + `userId` + `password`。 4. 重启 Gateway 网关。 -5. 与机器人开始一个私信，或将它邀请到一个房间中。 - - 只有当 `channels.matrix.autoJoin` 允许时，新的 Matrix 邀请才会生效。 +5. 与机器人发起私信，或邀请它加入房间。 + - 只有在 `channels.matrix.autoJoin` 允许时，新的 Matrix 邀请才会生效。 交互式设置路径： @@ -56,10 +56,10 @@ openclaw channels add openclaw configure --section channels ``` -Matrix 向导会询问以下内容： +Matrix 向导会询问： - homeserver URL -- 认证方式：访问令牌或密码 +- 认证方式：access token 或密码 - 用户 ID（仅密码认证） - 可选设备名称 - 是否启用端到端加密 @@ -67,24 +67,24 @@ Matrix 向导会询问以下内容： 向导的关键行为： -- 如果 Matrix 认证环境变量已经存在，并且该账户的认证尚未保存在配置中，向导会提供一个环境变量快捷方式，以便将认证信息保留在环境变量中。 -- 账户名称会标准化为账户 ID。例如，`Ops Bot` 会变成 `ops-bot`。 -- 私信允许列表条目可直接接受 `@user:server`；显示名称仅在实时目录查找找到唯一精确匹配时才有效。 -- 房间允许列表条目可直接接受房间 ID 和别名。优先使用 `!room:server` 或 `#alias:server`；未解析的名称会在运行时被允许列表解析忽略。 -- 在邀请自动加入的允许列表模式下，只能使用稳定的邀请目标：`!roomId:server`、`#alias:server` 或 `*`。纯房间名称会被拒绝。 -- 如需在保存前解析房间名称，请使用 `openclaw channels resolve --channel matrix "Project Room"`。 +- 如果 Matrix 认证环境变量已存在，并且该账户尚未在配置中保存认证信息，向导会提供一个环境变量快捷方式，以便将认证信息保留在环境变量中。 +- 账户名称会规范化为账户 ID。例如，`Ops Bot` 会变成 `ops-bot`。 +- 私信 allowlist 条目可直接接受 `@user:server`；显示名称仅在实时目录查找找到一个精确匹配时才有效。 +- 房间 allowlist 条目可直接接受房间 ID 和别名。优先使用 `!room:server` 或 `#alias:server`；无法解析的名称会在运行时被 allowlist 解析忽略。 +- 在邀请自动加入 allowlist 模式中，只能使用稳定的邀请目标：`!roomId:server`、`#alias:server` 或 `*`。纯房间名称会被拒绝。 +- 若要在保存前解析房间名称，请使用 `openclaw channels resolve --channel matrix "Project Room"`。 `channels.matrix.autoJoin` 默认为 `off`。 -如果你不设置它，机器人将不会加入被邀请的房间或新的私信式邀请，因此除非你先手动加入，否则它不会出现在新的群组或被邀请的私信中。 +如果你不设置它，机器人将不会加入被邀请的房间或新的私信式邀请，因此除非你先手动加入，否则它不会出现在新群组或被邀请的私信中。 -设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，可以限制它接受哪些邀请；或者如果你希望它加入每一个邀请，请设置 `autoJoin: "always"`。 +如果你想限制它接受哪些邀请，请设置 `autoJoin: "allowlist"` 并同时配置 `autoJoinAllowlist`；如果你希望它加入每一个邀请，请设置 `autoJoin: "always"`。 在 `allowlist` 模式下，`autoJoinAllowlist` 仅接受 `!roomId:server`、`#alias:server` 或 `*`。 -允许列表示例： +Allowlist 示例： ```json5 { @@ -114,7 +114,7 @@ Matrix 向导会询问以下内容： } ``` -基于令牌的最小设置： +最小化的基于 token 的设置： ```json5 { @@ -129,7 +129,7 @@ Matrix 向导会询问以下内容： } ``` -基于密码的设置（登录后会缓存令牌）： +基于密码的设置（登录后会缓存 token）： ```json5 { @@ -147,9 +147,9 @@ Matrix 向导会询问以下内容： Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 默认账户使用 `credentials.json`；命名账户使用 `credentials-.json`。 -当这里存在缓存凭证时，即使当前认证没有直接在配置中设置，OpenClaw 在设置、Doctor 和渠道状态发现中也会将 Matrix 视为已配置。 +当该位置存在缓存凭证时，即使当前认证未直接在配置中设置，OpenClaw 也会在设置、Doctor 和渠道状态发现中将 Matrix 视为已配置。 -对应的环境变量（当配置键未设置时使用）： +对应的环境变量（当未设置配置键时使用）： - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -158,7 +158,7 @@ Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -对于非默认账户，请使用带账户作用域的环境变量： +对于非默认账户，请使用账户范围环境变量： - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -172,7 +172,7 @@ Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -对于标准化后的账户 ID `ops-bot`，请使用： +对于规范化账户 ID `ops-bot`，请使用： - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` @@ -180,13 +180,13 @@ Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 Matrix 会转义账户 ID 中的标点，以避免带作用域的环境变量发生冲突。 例如，`-` 会变成 `_X2D_`，因此 `ops-prod` 会映射为 `MATRIX_OPS_X2D_PROD_*`。 -只有当这些认证环境变量已经存在，并且所选账户尚未在配置中保存 Matrix 认证时，交互式向导才会提供环境变量快捷方式。 +只有当这些认证环境变量已经存在，且所选账户尚未在配置中保存 Matrix 认证信息时，交互式向导才会提供环境变量快捷方式。 `MATRIX_HOMESERVER` 不能通过工作区 `.env` 设置；请参阅 [Workspace `.env` files](/zh-CN/gateway/security)。 ## 配置示例 -这是一个启用了私信配对、房间允许列表和端到端加密的实用基线配置： +这是一个实用的基础配置，启用了私信配对、房间 allowlist 和端到端加密： ```json5 { @@ -221,16 +221,13 @@ Matrix 会转义账户 ID 中的标点，以避免带作用域的环境变量发 } ``` -`autoJoin` 适用于所有 Matrix 邀请，包括私信式邀请。OpenClaw 无法在邀请发生时可靠地 -将被邀请的房间分类为私信还是群组，因此所有邀请都会先经过 `autoJoin`。 -`dm.policy` 会在机器人加入后、并且该房间被分类为私信之后再生效。 +`autoJoin` 适用于所有 Matrix 邀请，包括私信式邀请。OpenClaw 无法在邀请时可靠地区分被邀请房间是私信还是群组，因此所有邀请都会先经过 `autoJoin`。`dm.policy` 会在机器人加入之后、且房间被分类为私信后才生效。 ## 流式预览 -Matrix 回复流式传输为可选启用。 +Matrix 回复流式传输需要主动启用。 -当你希望 OpenClaw 发送一个单一的实时预览回复、在模型生成文本时原地编辑这个预览，并在 -回复完成后将其定稿时，请将 `channels.matrix.streaming` 设置为 `"partial"`： +当你希望 OpenClaw 发送一条单独的实时预览回复、在模型生成文本时原地编辑该预览，并在回复完成后将其定稿时，请将 `channels.matrix.streaming` 设置为 `"partial"`： ```json5 { @@ -242,32 +239,32 @@ Matrix 回复流式传输为可选启用。 } ``` -- `streaming: "off"` 是默认值。OpenClaw 会等待最终回复并发送一次。 -- `streaming: "partial"` 会为当前助手块创建一条可编辑的预览消息，使用普通的 Matrix 文本消息。这会保留 Matrix 传统的“预览优先”通知行为，因此默认客户端可能会在第一段流式预览文本出现时通知，而不是在最终块完成时通知。 -- `streaming: "quiet"` 会为当前助手块创建一条可编辑的静默预览通知。只有当你同时为最终定稿的预览编辑配置了接收者推送规则时，才应使用此选项。 -- `blockStreaming: true` 会启用单独的 Matrix 进度消息。启用预览流式传输时，Matrix 会保留当前块的实时草稿，并将已完成的块保留为单独的消息。 -- 当启用了预览流式传输且 `blockStreaming` 为关闭时，Matrix 会原地编辑实时草稿，并在该块或该轮完成时将同一事件定稿。 -- 如果预览内容已经无法放进单个 Matrix 事件，OpenClaw 会停止预览流式传输，并回退到普通的最终投递。 -- 媒体回复仍会正常发送附件。如果一个过期的预览不再能被安全复用，OpenClaw 会先将其删除，再发送最终的媒体回复。 -- 预览编辑会产生额外的 Matrix API 调用。如果你希望采用最保守的速率限制行为，请保持流式传输关闭。 +- `streaming: "off"` 是默认值。OpenClaw 会等待最终回复，然后发送一次。 +- `streaming: "partial"` 会为当前助手块创建一条可编辑的预览消息，使用普通 Matrix 文本消息。这会保留 Matrix 传统的“预览优先”通知行为，因此标准客户端可能会在第一段流式预览文本到达时通知，而不是在最终块完成时通知。 +- `streaming: "quiet"` 会为当前助手块创建一条可编辑的静默预览通知。仅当你同时为最终定稿的预览编辑配置了接收者推送规则时才应使用它。 +- `blockStreaming: true` 会启用独立的 Matrix 进度消息。启用预览流式传输后，Matrix 会保留当前块的实时草稿，并将已完成的块保留为独立消息。 +- 当预览流式传输开启且 `blockStreaming` 关闭时，Matrix 会原地编辑实时草稿，并在块或轮次结束时定稿同一个事件。 +- 如果预览内容已无法容纳在单个 Matrix 事件中，OpenClaw 会停止预览流式传输，并回退到普通的最终发送。 +- 媒体回复仍会正常发送附件。如果陈旧预览已无法安全复用，OpenClaw 会在发送最终媒体回复前将其清除。 +- 预览编辑会产生额外的 Matrix API 调用。如果你希望采用最保守的速率限制行为，请保持关闭流式传输。 `blockStreaming` 本身不会启用草稿预览。 -使用 `streaming: "partial"` 或 `streaming: "quiet"` 来启用预览编辑；然后仅当你还希望已完成的助手块作为单独的进度消息保留可见时，再额外设置 `blockStreaming: true`。 +如需预览编辑，请使用 `streaming: "partial"` 或 `streaming: "quiet"`；只有当你还希望已完成的助手块作为独立进度消息保留可见时，才再添加 `blockStreaming: true`。 -如果你需要默认 Matrix 通知而不配置自定义推送规则，请使用 `streaming: "partial"` 获得“预览优先”行为，或保持 `streaming` 关闭以仅进行最终投递。对于 `streaming: "off"`： +如果你需要标准 Matrix 通知而不使用自定义推送规则，请使用 `streaming: "partial"` 获得“预览优先”行为，或保持 `streaming` 关闭以仅发送最终结果。使用 `streaming: "off"` 时： -- `blockStreaming: true` 会将每个已完成的块作为普通的可通知 Matrix 消息发送。 -- `blockStreaming: false` 只会将最终完成的回复作为普通的可通知 Matrix 消息发送。 +- `blockStreaming: true` 会将每个已完成块作为普通可通知的 Matrix 消息发送。 +- `blockStreaming: false` 只会将最终完成的回复作为普通可通知的 Matrix 消息发送。 ### 自托管静默定稿预览的推送规则 -静默流式传输（`streaming: "quiet"`）只会在一个块或一轮对话定稿时通知接收者——必须有一个按用户配置的推送规则匹配最终定稿预览标记。完整设置（接收者令牌、pusher 检查、规则安装、各 homeserver 说明）请参阅 [Matrix push rules for quiet previews](/zh-CN/channels/matrix-push-rules)。 +静默流式传输（`streaming: "quiet"`）只有在一个块或轮次定稿后才会通知接收者——每个用户都必须有一条推送规则来匹配定稿预览标记。完整设置（接收者 token、pusher 检查、规则安装、各 homeserver 注意事项）请参阅 [Matrix push rules for quiet previews](/zh-CN/channels/matrix-push-rules)。 ## 机器人对机器人房间 默认情况下，来自其他已配置 OpenClaw Matrix 账户的 Matrix 消息会被忽略。 -当你明确希望启用智能体之间的 Matrix 流量时，请使用 `allowBots`： +如果你有意启用智能体之间的 Matrix 通信，请使用 `allowBots`： ```json5 { @@ -284,17 +281,17 @@ Matrix 回复流式传输为可选启用。 } ``` -- `allowBots: true` 会接受来自其他已配置 Matrix 机器人账户、且位于允许房间和私信中的消息。 -- `allowBots: "mentions"` 仅在这些消息在房间中明确提及此机器人时才接受。私信仍然允许。 -- `groups..allowBots` 会覆盖该房间的账户级设置。 -- OpenClaw 仍会忽略来自同一 Matrix 用户 ID 的消息，以避免自回复循环。 -- Matrix 在这里不会暴露原生的机器人标记；OpenClaw 将“由机器人撰写”视为“由此 OpenClaw Gateway 网关上另一个已配置的 Matrix 账户发送”。 +- `allowBots: true` 会在允许的房间和私信中接受来自其他已配置 Matrix 机器人账户的消息。 +- `allowBots: "mentions"` 仅当这些消息在房间中明确提及此机器人时才接受。私信仍然允许。 +- `groups..allowBots` 会覆盖某个房间的账户级设置。 +- OpenClaw 仍会忽略来自相同 Matrix 用户 ID 的消息，以避免自回复循环。 +- Matrix 在这里不会暴露原生机器人标记；OpenClaw 将“由机器人发送”视为“由此 OpenClaw Gateway 网关上另一已配置的 Matrix 账户发送”。 -在共享房间中启用机器人对机器人流量时，请使用严格的房间允许列表和提及要求。 +在共享房间中启用机器人对机器人通信时，请使用严格的房间 allowlist 和提及要求。 ## 加密和验证 -在加密（端到端加密）房间中，出站图像事件会使用 `thumbnail_file`，因此图像预览会与完整附件一起加密。未加密房间仍使用普通的 `thumbnail_url`。无需配置——插件会自动检测端到端加密状态。 +在加密的（端到端加密）房间中，出站图片事件使用 `thumbnail_file`，因此图片预览会与完整附件一起加密。未加密房间仍使用普通的 `thumbnail_url`。无需任何配置——插件会自动检测端到端加密状态。 启用加密： @@ -312,7 +309,7 @@ Matrix 回复流式传输为可选启用。 } ``` -验证命令（全部都支持使用 `--verbose` 输出诊断信息，并使用 `--json` 输出机器可读格式）： +验证命令（全部支持 `--verbose` 用于诊断，支持 `--json` 输出机器可读结果）： ```bash openclaw matrix verify status @@ -330,7 +327,7 @@ openclaw matrix verify status --verbose openclaw matrix verify status --include-recovery-key --json ``` -引导交叉签名和验证状态： +引导跨签名和验证状态： ```bash openclaw matrix verify bootstrap @@ -342,7 +339,7 @@ openclaw matrix verify bootstrap openclaw matrix verify bootstrap --verbose ``` -在引导前强制重置全新的交叉签名身份： +在引导前强制重置跨签名身份： ```bash openclaw matrix verify bootstrap --force-reset-cross-signing @@ -357,24 +354,21 @@ openclaw matrix verify device "" 此命令会报告三个独立状态： - `Recovery key accepted`：Matrix 已接受该恢复密钥，用于秘密存储或设备信任。 -- `Backup usable`：可以使用受信任的恢复材料加载房间密钥备份。 -- `Device verified by owner`：当前 OpenClaw 设备已获得完整的 Matrix 交叉签名身份信任。 +- `Backup usable`：可使用受信任的恢复材料加载房间密钥备份。 +- `Device verified by owner`：当前 OpenClaw 设备已获得完整的 Matrix 跨签名身份信任。 -详细输出或 JSON 输出中的 `Signed by owner` 仅用于诊断。除非 `Cross-signing verified` 同时也是 `yes`，否则 OpenClaw 不会 -将其视为足够条件。 +详细输出或 JSON 输出中的 `Signed by owner` 仅用于诊断。除非 `Cross-signing verified` 同时为 `yes`，否则 OpenClaw 不会将其视为充分条件。 -当完整的 Matrix 身份信任尚未完成时，即使恢复密钥可以解锁备份材料， -该命令仍会以非零状态退出。在这种情况下，请通过另一个 Matrix 客户端完成 -自我验证： +即使恢复密钥可以解锁备份材料，只要完整的 Matrix 身份信任尚未完成，该命令仍会以非零状态退出。 +在这种情况下，请从另一个 Matrix 客户端完成自验证： ```bash openclaw matrix verify self ``` -在另一个 Matrix 客户端中接受该请求，比较 SAS 表情符号或十进制数字，并且仅在它们匹配时输入 `yes`。该命令会等待 Matrix 报告 -`Cross-signing verified: yes` 后才会成功退出。 +在另一个 Matrix 客户端中接受该请求，比较 SAS 表情符号或十进制数字，并且仅在它们匹配时输入 `yes`。该命令会等待 Matrix 报告 `Cross-signing verified: yes` 后才成功退出。 -仅当你明确希望替换当前交叉签名身份时，才使用 `verify bootstrap --force-reset-cross-signing`。 +仅当你有意替换当前跨签名身份时，才使用 `verify bootstrap --force-reset-cross-signing`。 详细设备验证信息： @@ -406,13 +400,13 @@ openclaw matrix verify backup restore openclaw matrix verify backup restore --recovery-key "" ``` -交互式自我验证流程： +交互式自验证流程： ```bash openclaw matrix verify self ``` -对于更底层的验证流程或入站验证请求，请使用： +如需更底层的操作或处理入站验证请求，请使用： ```bash openclaw matrix verify accept @@ -429,19 +423,17 @@ openclaw matrix verify confirm-sas openclaw matrix verify backup restore --verbose ``` -删除当前服务器备份并创建一个全新的备份基线。如果存储的 -备份密钥无法被干净地加载，此重置还可以重新创建秘密存储，以便 -未来的冷启动能够加载新的备份密钥： +删除当前服务器备份并创建新的备份基线。如果存储的备份密钥无法被干净地加载，此重置还可以重新创建秘密存储，以便未来冷启动时可以加载新的备份密钥： ```bash openclaw matrix verify backup reset --yes ``` -所有 `verify` 命令默认都采用简洁输出（包括安静的内部 SDK 日志），仅在使用 `--verbose` 时显示详细诊断信息。 -编写脚本时，请使用 `--json` 获取完整的机器可读输出。 +所有 `verify` 命令默认都很简洁（包括安静的内部 SDK 日志），只有在使用 `--verbose` 时才显示详细诊断。 +编写脚本时请使用 `--json` 以获得完整的机器可读输出。 -在多账户设置中，Matrix CLI 命令会使用隐式的 Matrix 默认账户，除非你传入 `--account `。 -如果你配置了多个命名账户，请先设置 `channels.matrix.defaultAccount`，否则这些隐式 CLI 操作会停止并要求你显式选择一个账户。 +在多账户设置中，除非你传入 `--account `，否则 Matrix CLI 命令会使用隐式的 Matrix 默认账户。 +如果你配置了多个命名账户，请先设置 `channels.matrix.defaultAccount`，否则这些隐式 CLI 操作会停止并要求你明确选择一个账户。 当你希望验证或设备操作明确针对某个命名账户时，请使用 `--account`： ```bash @@ -450,35 +442,34 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -当某个命名账户的加密被禁用或不可用时，Matrix 警告和验证错误会指向该账户的配置键，例如 `channels.matrix.accounts.assistant.encryption`。 +当某个命名账户禁用了加密或该账户不可用加密时，Matrix 警告和验证错误会指向该账户的配置键，例如 `channels.matrix.accounts.assistant.encryption`。 - - 只有当你自己的交叉签名身份对某个设备进行签名时，OpenClaw 才会将该设备视为已验证。`verify status --verbose` 会显示三个信任信号： + + 只有当你自己的跨签名身份对某个设备进行了签名时，OpenClaw 才会将该设备视为已验证。`verify status --verbose` 会暴露三个信任信号： - `Locally trusted`：仅被此客户端信任 - - `Cross-signing verified`：SDK 报告已通过交叉签名完成验证 - - `Signed by owner`：已由你自己的 self-signing 密钥签名 + - `Cross-signing verified`：SDK 报告已通过跨签名验证 + - `Signed by owner`：已由你自己的自签名密钥签名 - 只有在存在交叉签名验证时，`Verified by owner` 才会变为 `yes`。 - 仅有本地信任或所有者签名本身，并不足以让 OpenClaw 将 - 该设备视为完全已验证。 + 只有在存在跨签名验证时，`Verified by owner` 才会变为 `yes`。 + 仅有本地信任或仅有所有者签名，都不足以让 OpenClaw 将该设备视为已完全验证。 - - `verify bootstrap` 是用于加密账户的修复和设置命令。按顺序，它会执行： + + `verify bootstrap` 是加密账户的修复与设置命令。按顺序，它会： - - 引导秘密存储，尽可能复用现有恢复密钥 - - 引导交叉签名并上传缺失的公开交叉签名密钥 - - 标记并交叉签名当前设备 + - 引导秘密存储，并在可能时复用现有恢复密钥 + - 引导跨签名并上传缺失的公开跨签名密钥 + - 标记并跨签名当前设备 - 如果服务器端房间密钥备份尚不存在，则创建一个 - 如果 homeserver 需要 UIA 才能上传交叉签名密钥，OpenClaw 会先尝试无认证，然后尝试 `m.login.dummy`，最后尝试 `m.login.password`（需要 `channels.matrix.password`）。仅在你有意丢弃当前身份时才使用 `--force-reset-cross-signing`。 + 如果 homeserver 需要 UIA 才能上传跨签名密钥，OpenClaw 会先尝试无认证，然后尝试 `m.login.dummy`，最后尝试 `m.login.password`（需要 `channels.matrix.password`）。仅在有意丢弃当前身份时才使用 `--force-reset-cross-signing`。 - + 如果你希望未来的加密消息继续可用，并接受丢失无法恢复的旧历史记录： ```bash @@ -487,33 +478,31 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` - 添加 `--account ` 可指定某个命名账户。这也可以在当前备份秘密无法被安全加载时重新创建秘密存储。 - 仅当你明确希望旧恢复密钥 - 不再能解锁新的备份基线时，才添加 `--rotate-recovery-key`。 + 添加 `--account ` 可针对某个命名账户。这也可以在当前备份密钥无法安全加载时重新创建秘密存储。 + 仅当你有意让旧恢复密钥不再能够解锁新的备份基线时，才添加 `--rotate-recovery-key`。 - 当 `encryption: true` 时，`startupVerification` 默认为 `"if-unverified"`。启动时，未验证设备会在另一个 Matrix 客户端中请求自我验证，同时跳过重复请求并应用冷却时间。你可以通过 `startupVerificationCooldownHours` 调整，或通过 `startupVerification: "off"` 禁用。 + 当 `encryption: true` 时，`startupVerification` 默认为 `"if-unverified"`。启动时，未验证设备会在另一个 Matrix 客户端中请求自验证，同时跳过重复请求并应用冷却时间。可通过 `startupVerificationCooldownHours` 调整，或通过 `startupVerification: "off"` 禁用。 - 启动时还会执行一次保守的加密 bootstrap 流程，复用当前的秘密存储和交叉签名身份。如果 bootstrap 状态已损坏，即使没有 `channels.matrix.password`，OpenClaw 也会尝试进行受保护的修复；如果 homeserver 需要密码 UIA，启动时会记录警告，但不会导致致命错误。已被所有者签名的设备会被保留。 + 启动时还会运行一次保守的加密 bootstrap 检查，复用当前的秘密存储和跨签名身份。如果 bootstrap 状态损坏，即使没有 `channels.matrix.password`，OpenClaw 也会尝试受保护的修复；如果 homeserver 需要密码 UIA，启动时会记录警告，但不会导致致命错误。已由所有者签名的设备会被保留。 完整升级流程请参阅 [Matrix migration](/zh-CN/install/migrating-matrix)。 - Matrix 会将验证生命周期通知作为 `m.notice` 消息发布到严格的私信验证房间中：请求、就绪（带有“通过表情符号验证”指引）、开始/完成，以及在可用时提供 SAS（表情符号/十进制）详情。 + Matrix 会将验证生命周期通知作为 `m.notice` 消息发布到严格的私信验证房间中：请求、就绪（附带“通过表情符号验证”指引）、开始/完成，以及在可用时显示 SAS（表情符号/十进制）详情。 - 来自另一个 Matrix 客户端的入站请求会被跟踪并自动接受。对于自我验证，OpenClaw 会自动启动 SAS 流程，并在表情符号验证可用后自动确认自己这一侧——但你仍然需要在 Matrix 客户端中比较并确认“它们匹配”。 + 来自另一个 Matrix 客户端的入站请求会被跟踪并自动接受。对于自验证，OpenClaw 会自动启动 SAS 流程，并在表情符号验证可用后自动确认自身这一侧——你仍然需要在你的 Matrix 客户端中进行比较并确认“它们匹配”。 - 验证系统通知不会被转发到智能体聊天处理流水线。 + 验证系统通知不会转发到智能体聊天管道。 - 如果 `verify status` 显示当前设备已不再列在 - homeserver 上，请创建一个新的 OpenClaw Matrix 设备。对于密码登录： + 如果 `verify status` 显示当前设备已不再列在 homeserver 上，请创建一个新的 OpenClaw Matrix 设备。对于密码登录： ```bash openclaw matrix account add \ @@ -524,8 +513,7 @@ openclaw matrix account add \ --device-name OpenClaw-Gateway ``` - 对于令牌认证，请在你的 Matrix 客户端或管理界面中创建一个新的访问令牌， - 然后更新 OpenClaw： + 对于 token 认证，请在你的 Matrix 客户端或管理界面中创建一个新的 access token，然后更新 OpenClaw： ```bash openclaw matrix account add \ @@ -534,13 +522,12 @@ openclaw matrix account add \ --access-token '' ``` - 将 `assistant` 替换为失败命令中的账户 ID，或者对默认账户省略 - `--account`。 + 将 `assistant` 替换为失败命令中的账户 ID，或省略 `--account` 以使用默认账户。 - - 旧的由 OpenClaw 管理的设备可能会不断累积。列出并清理： + + 由 OpenClaw 管理的旧设备可能会不断积累。可列出并清理： ```bash openclaw matrix devices list @@ -550,65 +537,65 @@ openclaw matrix devices prune-stale - Matrix 端到端加密使用官方 `matrix-js-sdk` Rust 加密路径，并使用 `fake-indexeddb` 作为 IndexedDB shim。加密状态会持久化到 `crypto-idb-snapshot.json`（受限文件权限）。 + Matrix 端到端加密使用官方 `matrix-js-sdk` Rust 加密路径，并使用 `fake-indexeddb` 作为 IndexedDB shim。加密状态会持久化到 `crypto-idb-snapshot.json`（文件权限较严格）。 - 加密运行时状态位于 `~/.openclaw/matrix/accounts//__//` 下，其中包括同步存储、加密存储、恢复密钥、IDB 快照、线程绑定和启动验证状态。当令牌发生变化但账户身份保持不变时，OpenClaw 会复用现有的最佳根目录，因此之前的状态仍然可见。 + 加密运行时状态位于 `~/.openclaw/matrix/accounts//__//` 下，其中包括同步存储、加密存储、恢复密钥、IDB 快照、线程绑定和启动验证状态。当 token 变化但账户身份保持不变时，OpenClaw 会复用现有的最佳根目录，以便先前状态仍然可见。 ## 配置文件管理 -使用以下命令为所选账户更新 Matrix 自身配置文件： +使用以下命令更新所选账户的 Matrix 自身资料： ```bash openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -当你希望明确指定某个命名 Matrix 账户时，请添加 `--account `。 +当你希望明确针对某个命名 Matrix 账户时，请添加 `--account `。 -Matrix 可直接接受 `mxc://` 头像 URL。当你传入 `http://` 或 `https://` 头像 URL 时，OpenClaw 会先将其上传到 Matrix，然后把解析后的 `mxc://` URL 回写到 `channels.matrix.avatarUrl`（或所选账户的覆盖配置）中。 +Matrix 可直接接受 `mxc://` 头像 URL。当你传入 `http://` 或 `https://` 头像 URL 时，OpenClaw 会先将其上传到 Matrix，然后将解析后的 `mxc://` URL 回写到 `channels.matrix.avatarUrl`（或所选账户覆盖项）中。 ## 线程 -Matrix 同时支持用于自动回复和消息工具发送的原生 Matrix 线程。 +Matrix 同时支持自动回复和消息工具发送使用原生 Matrix 线程。 -- `dm.sessionScope: "per-user"`（默认）会使 Matrix 私信路由按发送者范围进行，因此多个私信房间在解析到同一对端时可以共享一个会话。 -- `dm.sessionScope: "per-room"` 会将每个 Matrix 私信房间隔离到各自独立的会话键中，同时仍使用普通的私信认证和允许列表检查。 -- 显式的 Matrix 会话绑定仍具有更高优先级，因此已绑定的房间和线程会保留其选定的目标会话。 -- `threadReplies: "off"` 会让回复保持在顶层，并将入站线程消息保留在父级会话上。 -- `threadReplies: "inbound"` 仅当入站消息本来就在某个线程中时，才会在线程内回复。 -- `threadReplies: "always"` 会让房间回复保持在线程中，以触发消息为根，并从第一条触发消息开始，通过匹配的线程作用域会话来路由该会话。 -- `dm.threadReplies` 仅对私信覆盖顶层设置。例如，你可以让房间线程保持隔离，同时让私信保持扁平。 -- 入站线程消息会将线程根消息作为额外的智能体上下文包含进来。 -- 当目标是同一个房间，或同一个私信用户目标时，消息工具发送会自动继承当前 Matrix 线程，除非显式提供了 `threadId`。 -- 仅当当前会话元数据能够证明它是在同一个 Matrix 账户下、面向同一私信对端时，才会触发同一会话的私信用户目标复用；否则 OpenClaw 会回退到普通的按用户范围路由。 -- 当 OpenClaw 发现某个 Matrix 私信房间与同一个共享 Matrix 私信会话中的另一个私信房间冲突时，如果启用了线程绑定，并存在 `dm.sessionScope` 提示，它会在该房间中发布一次性 `m.notice`，其中包含 `/focus` 逃生入口。 -- Matrix 支持运行时线程绑定。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 和线程绑定的 `/acp spawn` 都可在 Matrix 房间和私信中使用。 +- `dm.sessionScope: "per-user"`（默认）会让 Matrix 私信路由保持按发送者范围划分，因此多个私信房间在解析为同一对端时可以共享一个会话。 +- `dm.sessionScope: "per-room"` 会将每个 Matrix 私信房间隔离为各自独立的会话键，同时仍使用普通的私信认证和 allowlist 检查。 +- 显式 Matrix 会话绑定的优先级仍高于 `dm.sessionScope`，因此已绑定的房间和线程会保留其所选目标会话。 +- `threadReplies: "off"` 会让回复保持在顶层，并将入站线程消息保留在父会话上。 +- `threadReplies: "inbound"` 仅当入站消息本身已经在该线程中时，才在线程内回复。 +- `threadReplies: "always"` 会让房间回复保持在线程中，并以触发消息为线程根，从第一条触发消息开始通过对应的线程范围会话来路由该对话。 +- `dm.threadReplies` 仅覆盖私信的顶层设置。例如，你可以让房间线程保持隔离，同时让私信保持平铺。 +- 入站线程消息会将线程根消息作为额外智能体上下文包含进来。 +- 当目标是同一房间或同一私信用户目标时，消息工具发送会自动继承当前 Matrix 线程，除非显式提供了 `threadId`。 +- 仅当当前会话元数据能够证明它是同一 Matrix 账户上的同一私信对端时，才会启用同会话私信用户目标复用；否则 OpenClaw 会回退到普通的按用户范围路由。 +- 当 OpenClaw 发现某个 Matrix 私信房间与同一共享 Matrix 私信会话上的另一个私信房间发生冲突时，如果启用了线程绑定，并且提供了 `dm.sessionScope` 提示，它会在该房间中发布一次性 `m.notice`，其中包含 `/focus` 逃生口。 +- Matrix 支持运行时线程绑定。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及线程绑定的 `/acp spawn` 都可在 Matrix 房间和私信中使用。 - 当 `threadBindings.spawnSubagentSessions=true` 时，顶层 Matrix 房间/私信中的 `/focus` 会创建一个新的 Matrix 线程，并将其绑定到目标会话。 -- 在现有 Matrix 线程中运行 `/focus` 或 `/acp spawn --thread here` 时，则会改为绑定当前线程本身。 +- 在现有 Matrix 线程中运行 `/focus` 或 `/acp spawn --thread here`，则会改为绑定当前线程。 ## ACP 会话绑定 -可以将 Matrix 房间、私信和现有 Matrix 线程转换为持久 ACP 工作区，而无需更改聊天界面。 +Matrix 房间、私信和现有 Matrix 线程都可以变为持久 ACP 工作区，而无需更改聊天界面。 -快速操作流程： +快速操作员流程： - 在你希望继续使用的 Matrix 私信、房间或现有线程中运行 `/acp spawn codex --bind here`。 -- 在顶层 Matrix 私信或房间中，当前私信/房间会保留为聊天界面，后续消息会路由到新建的 ACP 会话。 +- 在顶层 Matrix 私信或房间中，当前私信/房间会保持为聊天界面，后续消息会路由到新建的 ACP 会话。 - 在现有 Matrix 线程中，`--bind here` 会将当前线程原地绑定。 -- `/new` 和 `/reset` 会原地重置同一个已绑定的 ACP 会话。 +- `/new` 和 `/reset` 会原地重置同一个已绑定 ACP 会话。 - `/acp close` 会关闭 ACP 会话并移除绑定。 说明： - `--bind here` 不会创建子 Matrix 线程。 -- 仅当使用 `/acp spawn --thread auto|here` 且 OpenClaw 需要创建或绑定子 Matrix 线程时，才需要 `threadBindings.spawnAcpSessions`。 +- 只有在 `/acp spawn --thread auto|here` 场景下，OpenClaw 需要创建或绑定子 Matrix 线程时，才需要 `threadBindings.spawnAcpSessions`。 ### 线程绑定配置 -Matrix 会继承来自 `session.threadBindings` 的全局默认值，同时也支持按渠道覆盖： +Matrix 会继承来自 `session.threadBindings` 的全局默认值，并且也支持按渠道覆盖： - `threadBindings.enabled` - `threadBindings.idleHours` @@ -616,7 +603,7 @@ Matrix 会继承来自 `session.threadBindings` 的全局默认值，同时也 - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Matrix 线程绑定的 spawn 标志需要显式启用： +Matrix 线程绑定的 spawn 标志为主动启用： - 设置 `threadBindings.spawnSubagentSessions: true`，以允许顶层 `/focus` 创建并绑定新的 Matrix 线程。 - 设置 `threadBindings.spawnAcpSessions: true`，以允许 `/acp spawn --thread auto|here` 将 ACP 会话绑定到 Matrix 线程。 @@ -626,19 +613,19 @@ Matrix 线程绑定的 spawn 标志需要显式启用： Matrix 支持出站回应操作、入站回应通知以及入站确认回应。 - 出站回应工具受 `channels["matrix"].actions.reactions` 控制。 -- `react` 会向指定的 Matrix 事件添加一个回应。 -- `reactions` 会列出指定 Matrix 事件当前的回应摘要。 +- `react` 会向特定 Matrix 事件添加一个回应。 +- `reactions` 会列出特定 Matrix 事件当前的回应摘要。 - `emoji=""` 会移除机器人账户自己在该事件上的回应。 - `remove: true` 只会移除机器人账户的指定表情回应。 -确认回应使用标准的 OpenClaw 解析顺序： +确认回应使用标准 OpenClaw 解析顺序： - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` - 智能体身份 emoji 回退值 -确认回应作用域按以下顺序解析： +确认回应范围按以下顺序解析： - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` @@ -652,28 +639,28 @@ Matrix 支持出站回应操作、入站回应通知以及入站确认回应。 行为： -- `reactionNotifications: "own"` 会在 `m.reaction` 事件目标是机器人撰写的 Matrix 消息时，转发新增的 `m.reaction` 事件。 +- `reactionNotifications: "own"` 会在目标为机器人所发送的 Matrix 消息时，转发新增的 `m.reaction` 事件。 - `reactionNotifications: "off"` 会禁用回应系统事件。 -- 回应移除不会被合成为系统事件，因为 Matrix 将其显示为 redaction，而不是独立的 `m.reaction` 移除事件。 +- 回应移除不会被合成为系统事件，因为 Matrix 将其表现为 redaction，而不是独立的 `m.reaction` 移除事件。 ## 历史上下文 -- `channels.matrix.historyLimit` 控制当 Matrix 房间消息触发智能体时，作为 `InboundHistory` 包含的最近房间消息数量。它会回退到 `messages.groupChat.historyLimit`；如果两者都未设置，则有效默认值为 `0`。设置为 `0` 可禁用。 -- Matrix 房间历史仅限房间。私信仍然使用普通会话历史。 -- Matrix 房间历史是“仅待处理”的：OpenClaw 会缓冲尚未触发回复的房间消息，然后在提及或其他触发到来时对该窗口进行快照。 +- `channels.matrix.historyLimit` 控制当 Matrix 房间消息触发智能体时，有多少条最近的房间消息会作为 `InboundHistory` 包含进去。它会回退到 `messages.groupChat.historyLimit`；如果两者都未设置，则有效默认值为 `0`。设置为 `0` 可禁用。 +- Matrix 房间历史仅限房间。私信仍使用普通会话历史。 +- Matrix 房间历史为“仅待处理”：OpenClaw 会缓冲尚未触发回复的房间消息，然后在提及或其他触发到来时对该窗口进行快照。 - 当前触发消息不会包含在 `InboundHistory` 中；它会保留在该轮的主入站正文中。 -- 对同一 Matrix 事件的重试会复用原始历史快照，而不会漂移到更新的房间消息。 +- 对同一个 Matrix 事件的重试会复用原始历史快照，而不是漂移到更新的房间消息上。 ## 上下文可见性 -Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文，例如获取的回复文本、线程根消息和待处理历史。 +Matrix 支持共享的 `contextVisibility` 控制，用于控制补充房间上下文，例如获取到的回复文本、线程根消息和待处理历史。 -- `contextVisibility: "all"` 是默认值。补充上下文会按接收时的样子保留。 -- `contextVisibility: "allowlist"` 会将补充上下文过滤为通过当前房间/用户允许列表检查的发送者。 -- `contextVisibility: "allowlist_quote"` 的行为类似于 `allowlist`，但仍会保留一条显式引用回复。 +- `contextVisibility: "all"` 是默认值。补充上下文会按接收时原样保留。 +- `contextVisibility: "allowlist"` 会将补充上下文过滤为仅保留通过当前房间/用户 allowlist 检查的发送者内容。 +- `contextVisibility: "allowlist_quote"` 的行为与 `allowlist` 相同，但仍会保留一个显式引用回复。 此设置影响的是补充上下文的可见性，而不是入站消息本身是否可以触发回复。 -触发授权仍来自 `groupPolicy`、`groups`、`groupAllowFrom` 和私信策略设置。 +触发授权仍然来自 `groupPolicy`、`groups`、`groupAllowFrom` 和私信策略设置。 ## 私信和房间策略 @@ -698,7 +685,7 @@ Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文 } ``` -有关提及门控和允许列表行为，请参阅 [Groups](/zh-CN/channels/groups)。 +有关提及门控和 allowlist 行为，请参阅 [Groups](/zh-CN/channels/groups)。 Matrix 私信的配对示例： @@ -707,13 +694,13 @@ openclaw pairing list matrix openclaw pairing approve matrix ``` -如果某个尚未获批的 Matrix 用户在批准前持续向你发送消息，OpenClaw 会复用同一个待处理配对代码，并且在短暂冷却后，可能会再次发送提醒回复，而不是生成新代码。 +如果某个未批准的 Matrix 用户在批准前持续向你发送消息，OpenClaw 会复用同一个待处理配对码，并且可能会在短暂冷却后再次发送提醒回复，而不是生成新的配对码。 有关共享的私信配对流程和存储布局，请参阅 [Pairing](/zh-CN/channels/pairing)。 ## 直接房间修复 -如果私信状态不同步，OpenClaw 可能会保留过时的 `m.direct` 映射，使其指向旧的一对一房间，而不是当前正在使用的私信。可使用以下命令检查某个对端的当前映射： +如果私信状态不同步，OpenClaw 最终可能会保留过期的 `m.direct` 映射，使其指向旧的单聊房间而不是当前活动私信。可使用以下命令检查某个对端的当前映射： ```bash openclaw matrix direct inspect --user-id @alice:example.org @@ -728,46 +715,46 @@ openclaw matrix direct repair --user-id @alice:example.org 修复流程： - 优先选择已在 `m.direct` 中映射的严格 1:1 私信 -- 如果没有，则回退到当前已加入、且与该用户对应的任意严格 1:1 私信 -- 如果不存在健康的私信，则创建一个新的直接房间并重写 `m.direct` +- 如果没有，则回退到当前已加入的、与该用户的任意严格 1:1 私信 +- 如果不存在健康的私信，则创建一个新的 direct room 并重写 `m.direct` -修复流程不会自动删除旧房间。它只会选择健康的私信并更新映射，以便新的 Matrix 发送、验证通知和其他私信流程再次指向正确的房间。 +修复流程不会自动删除旧房间。它只会选择健康的私信并更新映射，这样新的 Matrix 发送、验证通知和其他私信流程才会再次指向正确的房间。 -## Exec 批准 +## Exec 审批 -Matrix 可以作为 Matrix 账户的原生批准客户端。原生 -私信/渠道路由控制项仍位于 exec 批准配置下： +Matrix 可以作为 Matrix 账户的原生审批客户端。原生 +私信/渠道路由控制项仍位于 exec 审批配置下： - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers`（可选；会回退到 `channels.matrix.dm.allowFrom`） +- `channels.matrix.execApprovals.approvers`（可选；回退到 `channels.matrix.dm.allowFrom`） - `channels.matrix.execApprovals.target`（`dm` | `channel` | `both`，默认值：`dm`） - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -批准人必须是 Matrix 用户 ID，例如 `@owner:example.org`。当 `enabled` 未设置或为 `"auto"`，并且至少能解析出一个批准人时，Matrix 会自动启用原生批准。Exec 批准优先使用 `execApprovals.approvers`，也可以回退到 `channels.matrix.dm.allowFrom`。插件批准通过 `channels.matrix.dm.allowFrom` 进行授权。设置 `enabled: false` 可显式禁用 Matrix 作为原生批准客户端。否则，批准请求会回退到其他已配置的批准路由或批准回退策略。 +审批人必须是 Matrix 用户 ID，例如 `@owner:example.org`。当 `enabled` 未设置或为 `"auto"`，且至少有一个审批人可被解析时，Matrix 会自动启用原生审批。Exec 审批会优先使用 `execApprovals.approvers`，也可以回退到 `channels.matrix.dm.allowFrom`。插件审批通过 `channels.matrix.dm.allowFrom` 授权。设置 `enabled: false` 可显式禁用 Matrix 作为原生审批客户端。否则，审批请求会回退到其他已配置的审批路由或审批回退策略。 -Matrix 原生路由同时支持两种批准类型： +Matrix 原生路由同时支持两种审批类型： -- `channels.matrix.execApprovals.*` 控制 Matrix 批准提示的原生私信/渠道扇出模式。 -- Exec 批准使用来自 `execApprovals.approvers` 或 `channels.matrix.dm.allowFrom` 的 exec 批准人集合。 -- 插件批准使用来自 `channels.matrix.dm.allowFrom` 的 Matrix 私信允许列表。 -- Matrix 回应快捷方式和消息更新同时适用于 exec 批准和插件批准。 +- `channels.matrix.execApprovals.*` 控制 Matrix 审批提示的原生私信/渠道扇出模式。 +- Exec 审批使用来自 `execApprovals.approvers` 或 `channels.matrix.dm.allowFrom` 的 exec 审批人集合。 +- 插件审批使用来自 `channels.matrix.dm.allowFrom` 的 Matrix 私信 allowlist。 +- Matrix 回应快捷方式和消息更新同时适用于 exec 审批和插件审批。 -投递规则： +发送规则： -- `target: "dm"` 会将批准提示发送到批准人的私信 +- `target: "dm"` 会将审批提示发送到审批人的私信 - `target: "channel"` 会将提示发回源 Matrix 房间或私信 -- `target: "both"` 会同时发送到批准人的私信以及源 Matrix 房间或私信 +- `target: "both"` 会同时发送到审批人的私信以及源 Matrix 房间或私信 -Matrix 批准提示会在主批准消息上植入回应快捷方式： +Matrix 审批提示会在主审批消息上植入回应快捷方式： - `✅` = 允许一次 - `❌` = 拒绝 -- `♾️` = 在有效 exec 策略允许该决定时始终允许 +- `♾️` = 始终允许，前提是该决定在有效 exec 策略中被允许 -批准人可以对该消息添加回应，或使用回退斜杠命令：`/approve allow-once`、`/approve allow-always` 或 `/approve deny`。 +审批人可以对该消息做出回应，或使用回退 slash 命令：`/approve allow-once`、`/approve allow-always` 或 `/approve deny`。 -只有已解析的批准人可以执行批准或拒绝。对于 exec 批准，渠道投递会包含命令文本，因此仅应在受信任的房间中启用 `channel` 或 `both`。 +只有已解析的审批人才能批准或拒绝。对于 exec 审批，渠道发送会包含命令文本，因此仅应在受信任房间中启用 `channel` 或 `both`。 按账户覆盖： @@ -775,11 +762,11 @@ Matrix 批准提示会在主批准消息上植入回应快捷方式： 相关文档：[Exec approvals](/zh-CN/tools/exec-approvals) -## 斜杠命令 +## Slash 命令 -Matrix 斜杠命令（例如 `/new`、`/reset`、`/model`）可直接在私信中使用。在房间中，OpenClaw 还会识别以前缀为机器人自身 Matrix 提及的斜杠命令，因此 `@bot:server /new` 会触发命令路径，而无需自定义提及正则。这使机器人能够响应房间风格的 `@mention /command` 帖子，例如 Element 和类似客户端在用户先补全机器人名称再输入命令时发出的消息。 +Matrix slash 命令（例如 `/new`、`/reset`、`/model`）可直接在私信中使用。在房间中，OpenClaw 还会识别带有机器人自身 Matrix 提及前缀的 slash 命令，因此 `@bot:server /new` 会触发命令路径，而无需自定义提及正则。这使得机器人能够响应 Element 和类似客户端在用户先补全机器人名称、再输入命令时产生的房间式 `@mention /command` 帖子。 -授权规则仍然适用：命令发送者必须像普通消息一样满足私信或房间的允许列表/所有者策略。 +授权规则仍然适用：命令发送者必须像普通消息一样满足私信或房间的 allowlist/所有者策略。 ## 多账户 @@ -812,21 +799,21 @@ Matrix 斜杠命令（例如 `/new`、`/reset`、`/model`）可直接在私信 ``` 顶层 `channels.matrix` 值会作为命名账户的默认值，除非某个账户进行了覆盖。 -你可以使用 `groups..account` 将继承的房间条目限定到某一个 Matrix 账户。 -没有 `account` 的条目会在所有 Matrix 账户之间共享，而设置了 `account: "default"` 的条目在默认账户直接配置在顶层 `channels.matrix.*` 时仍然有效。 -部分共享认证默认值本身不会创建单独的隐式默认账户。只有当该默认账户具有新的认证信息（`homeserver` 加 `accessToken`，或 `homeserver` 加 `userId` 和 `password`）时，OpenClaw 才会合成顶层 `default` 账户；命名账户仍然可以仅凭 `homeserver` 加 `userId` 保持可发现，并在后续缓存凭证满足认证时生效。 -如果 Matrix 已经恰好有一个命名账户，或 `defaultAccount` 指向现有命名账户键，那么单账户到多账户的修复/设置提升会保留该账户，而不是创建新的 `accounts.default` 条目。只有 Matrix 认证/bootstrap 键会移动到被提升的账户中；共享投递策略键会保留在顶层。 -当你希望 OpenClaw 在隐式路由、探测和 CLI 操作中优先使用某个命名 Matrix 账户时，请设置 `defaultAccount`。 -如果配置了多个 Matrix 账户，且其中一个账户 ID 为 `default`，那么即使未设置 `defaultAccount`，OpenClaw 也会隐式使用该账户。 +你可以通过 `groups..account` 将继承的房间条目限定到某一个 Matrix 账户。 +未设置 `account` 的条目会在所有 Matrix 账户之间共享，而设置了 `account: "default"` 的条目在默认账户直接配置在顶层 `channels.matrix.*` 时也仍然有效。 +部分共享认证默认值本身不会创建一个单独的隐式默认账户。只有当该默认值具有新的认证信息（`homeserver` 加 `accessToken`，或 `homeserver` 加 `userId` 和 `password`）时，OpenClaw 才会合成顶层 `default` 账户；而命名账户即使只有 `homeserver` 和 `userId`，只要后续缓存凭证满足认证要求，仍可保持可发现状态。 +如果 Matrix 已经只有一个命名账户，或者 `defaultAccount` 指向某个现有命名账户键，那么从单账户到多账户的修复/设置提升会保留该账户，而不是新建一个新的 `accounts.default` 条目。只有 Matrix 认证/bootstrap 键会移动到该提升后的账户中；共享的发送策略键仍保留在顶层。 +如果你希望 OpenClaw 在隐式路由、探测和 CLI 操作中优先使用某个命名 Matrix 账户，请设置 `defaultAccount`。 +如果配置了多个 Matrix 账户，且其中一个账户 id 是 `default`，那么即使 `defaultAccount` 未设置，OpenClaw 也会隐式使用该账户。 如果你配置了多个命名账户，请设置 `defaultAccount`，或为依赖隐式账户选择的 CLI 命令传入 `--account `。 -当你希望为某一条命令覆盖该隐式选择时，请为 `openclaw matrix verify ...` 和 `openclaw matrix devices ...` 传入 `--account `。 +当你希望为单个命令覆盖该隐式选择时，请为 `openclaw matrix verify ...` 和 `openclaw matrix devices ...` 传入 `--account `。 -共享多账户模式请参阅 [Configuration reference](/zh-CN/gateway/config-channels#multi-account-all-channels)。 +有关共享多账户模式，请参阅 [Configuration reference](/zh-CN/gateway/config-channels#multi-account-all-channels)。 ## 私有/LAN homeserver -默认情况下，出于 SSRF 防护考虑，OpenClaw 会阻止私有/内部 Matrix homeserver，除非你 -为每个账户显式选择启用。 +默认情况下，出于 SSRF 保护，OpenClaw 会阻止私有/内部 Matrix homeserver，除非你 +按账户显式选择启用。 如果你的 homeserver 运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为该 Matrix 账户启用 `network.dangerouslyAllowPrivateNetwork`： @@ -855,8 +842,8 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -此选择启用仅允许受信任的私有/内部目标。公开的明文 homeserver，例如 -`http://matrix.example.org:8008`，仍会被阻止。应尽可能优先使用 `https://`。 +此选择启用仅允许受信任的私有/内部目标。像 +`http://matrix.example.org:8008` 这样的公共明文 homeserver 仍会被阻止。请尽可能优先使用 `https://`。 ## 代理 Matrix 流量 @@ -875,21 +862,26 @@ openclaw matrix account add \ ``` 命名账户可通过 `channels.matrix.accounts..proxy` 覆盖顶层默认值。 -OpenClaw 对运行时 Matrix 流量和账户状态探测使用同一代理设置。 +OpenClaw 会对运行时 Matrix 流量和账户状态探测使用相同的代理设置。 ## 目标解析 -在 OpenClaw 要求你提供房间或用户目标的任何地方，Matrix 都接受以下目标形式： +在 OpenClaw 要求你提供房间或用户目标的任何位置，Matrix 都接受以下目标形式： - 用户：`@user:server`、`user:@user:server` 或 `matrix:user:@user:server` - 房间：`!room:server`、`room:!room:server` 或 `matrix:room:!room:server` - 别名：`#alias:server`、`channel:#alias:server` 或 `matrix:channel:#alias:server` +Matrix 房间 ID 区分大小写。在配置显式发送目标、cron 作业、绑定或 allowlist 时， +请使用 Matrix 中房间 ID 的准确大小写形式。 +OpenClaw 会将内部会话键规范化以便存储，因此这些小写键 +不能作为 Matrix 发送 ID 的可靠来源。 + 实时目录查找会使用已登录的 Matrix 账户： - 用户查找会查询该 homeserver 上的 Matrix 用户目录。 -- 房间查找会直接接受显式房间 ID 和别名，然后回退到搜索该账户已加入的房间名称。 -- 已加入房间名称查找属于尽力而为。如果某个房间名称无法解析为 ID 或别名，则在运行时允许列表解析中会被忽略。 +- 房间查找会直接接受显式房间 ID 和别名，然后回退为搜索该账户已加入房间的名称。 +- 已加入房间名称查找是尽力而为的。如果某个房间名称无法解析为 ID 或别名，它会在运行时 allowlist 解析中被忽略。 ## 配置参考 @@ -897,58 +889,58 @@ OpenClaw 对运行时 Matrix 流量和账户状态探测使用同一代理设置 - `name`：账户的可选标签。 - `defaultAccount`：配置了多个 Matrix 账户时的首选账户 ID。 - `homeserver`：homeserver URL，例如 `https://matrix.example.org`。 -- `network.dangerouslyAllowPrivateNetwork`：允许此 Matrix 账户连接到私有/内部 homeserver。当 homeserver 解析到 `localhost`、LAN/Tailscale IP，或像 `matrix-synapse` 这样的内部主机时，请启用此项。 -- `proxy`：用于 Matrix 流量的可选 HTTP(S) 代理 URL。命名账户可使用各自的 `proxy` 覆盖顶层默认值。 -- `userId`：完整的 Matrix 用户 ID，例如 `@bot:example.org`。 -- `accessToken`：基于令牌认证的访问令牌。`channels.matrix.accessToken` 和 `channels.matrix.accounts..accessToken` 在 env/file/exec 提供商中均支持明文值和 SecretRef 值。请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 +- `network.dangerouslyAllowPrivateNetwork`：允许此 Matrix 账户连接到私有/内部 homeserver。当 homeserver 解析到 `localhost`、LAN/Tailscale IP 或诸如 `matrix-synapse` 之类的内部主机时，请启用此项。 +- `proxy`：用于 Matrix 流量的可选 HTTP(S) 代理 URL。命名账户可以用它们自己的 `proxy` 覆盖顶层默认值。 +- `userId`：完整 Matrix 用户 ID，例如 `@bot:example.org`。 +- `accessToken`：基于 token 认证的 access token。`channels.matrix.accessToken` 和 `channels.matrix.accounts..accessToken` 支持明文值和 SecretRef 值，适用于 env/file/exec 提供商。请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 - `password`：基于密码登录的密码。支持明文值和 SecretRef 值。 - `deviceId`：显式 Matrix 设备 ID。 - `deviceName`：用于密码登录的设备显示名称。 -- `avatarUrl`：用于配置文件同步和 `profile set` 更新的已存储自身头像 URL。 -- `initialSyncLimit`：启动同步期间获取的最大事件数量。 +- `avatarUrl`：用于资料同步和 `profile set` 更新的已存储自头像 URL。 +- `initialSyncLimit`：启动同步期间获取的最大事件数。 - `encryption`：启用端到端加密。 - `allowlistOnly`：当为 `true` 时，会将 `open` 房间策略升级为 `allowlist`，并强制所有活动私信策略（除 `disabled` 外，包括 `pairing` 和 `open`）变为 `allowlist`。不影响 `disabled` 策略。 - `allowBots`：允许来自其他已配置 OpenClaw Matrix 账户的消息（`true` 或 `"mentions"`）。 - `groupPolicy`：`open`、`allowlist` 或 `disabled`。 - `contextVisibility`：补充房间上下文可见性模式（`all`、`allowlist`、`allowlist_quote`）。 -- `groupAllowFrom`：房间流量的允许列表用户 ID。完整 Matrix 用户 ID 最安全；当监视器运行时，在启动时以及允许列表变更时会解析精确目录匹配。无法解析的名称会被忽略。 +- `groupAllowFrom`：房间流量的用户 ID allowlist。完整 Matrix 用户 ID 最安全；当监视器运行时，会在启动时以及 allowlist 发生变化时解析精确目录匹配。无法解析的名称会被忽略。 - `historyLimit`：作为群组历史上下文包含的最大房间消息数。会回退到 `messages.groupChat.historyLimit`；如果两者都未设置，则有效默认值为 `0`。设置为 `0` 可禁用。 - `replyToMode`：`off`、`first`、`all` 或 `batched`。 - `markdown`：出站 Matrix 文本的可选 Markdown 渲染配置。 -- `streaming`：`off`（默认）、`"partial"`、`"quiet"`、`true` 或 `false`。`"partial"` 和 `true` 会启用使用普通 Matrix 文本消息的“预览优先”草稿更新。`"quiet"` 会为自托管推送规则设置使用不通知的预览通知。`false` 等同于 `"off"`。 -- `blockStreaming`：当草稿预览流式传输处于活动状态时，`true` 会为已完成的助手块启用单独的进度消息。 +- `streaming`：`off`（默认）、`"partial"`、`"quiet"`、`true` 或 `false`。`"partial"` 和 `true` 会使用普通 Matrix 文本消息启用“预览优先”的草稿更新。`"quiet"` 会为自托管推送规则设置使用不通知的预览通知。`false` 等同于 `"off"`。 +- `blockStreaming`：当草稿预览流式传输处于活动状态时，`true` 会为已完成的助手块启用独立的进度消息。 - `threadReplies`：`off`、`inbound` 或 `always`。 -- `threadBindings`：按渠道覆盖线程绑定的会话路由和生命周期。 -- `startupVerification`：启动时自动自我验证请求模式（`if-unverified`、`off`）。 -- `startupVerificationCooldownHours`：重试自动启动验证请求前的冷却时间。 -- `textChunkLimit`：出站消息分块的字符数上限（当 `chunkMode` 为 `length` 时适用）。 +- `threadBindings`：线程绑定会话路由和生命周期的按渠道覆盖。 +- `startupVerification`：启动时的自动自验证请求模式（`if-unverified`、`off`）。 +- `startupVerificationCooldownHours`：自动启动验证请求重试前的冷却时间。 +- `textChunkLimit`：出站消息分块大小（按字符计；当 `chunkMode` 为 `length` 时适用）。 - `chunkMode`：`length` 按字符数拆分消息；`newline` 按行边界拆分。 -- `responsePrefix`：为此渠道的所有出站回复添加的可选前缀字符串。 -- `ackReaction`：此渠道/账户的可选确认回应覆盖值。 -- `ackReactionScope`：可选确认回应作用域覆盖值（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 +- `responsePrefix`：为该渠道所有出站回复添加的可选前缀字符串。 +- `ackReaction`：该渠道/账户的可选确认回应覆盖值。 +- `ackReactionScope`：可选确认回应范围覆盖值（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 - `reactionNotifications`：入站回应通知模式（`own`、`off`）。 -- `mediaMaxMb`：用于出站发送和入站媒体处理的媒体大小上限，单位为 MB。 +- `mediaMaxMb`：用于出站发送和入站媒体处理的媒体大小上限（MB）。 - `autoJoin`：邀请自动加入策略（`always`、`allowlist`、`off`）。默认值：`off`。适用于所有 Matrix 邀请，包括私信式邀请。 -- `autoJoinAllowlist`：当 `autoJoin` 为 `allowlist` 时允许的房间/别名。别名条目会在处理邀请期间解析为房间 ID；OpenClaw 不信任被邀请房间所声明的别名状态。 +- `autoJoinAllowlist`：当 `autoJoin` 为 `allowlist` 时允许的房间/别名。在邀请处理期间，别名条目会被解析为房间 ID；OpenClaw 不信任被邀请房间声称的别名状态。 - `dm`：私信策略块（`enabled`、`policy`、`allowFrom`、`sessionScope`、`threadReplies`）。 -- `dm.policy`：控制 OpenClaw 加入房间并将其分类为私信后对私信的访问权限。它不会改变邀请是否会自动加入。 -- `dm.allowFrom`：私信流量的允许列表用户 ID。完整 Matrix 用户 ID 最安全；当监视器运行时，在启动时以及允许列表变更时会解析精确目录匹配。无法解析的名称会被忽略。 -- `dm.sessionScope`：`per-user`（默认）或 `per-room`。当你希望每个 Matrix 私信房间即使面对相同对端也保持独立上下文时，请使用 `per-room`。 -- `dm.threadReplies`：仅用于私信的线程策略覆盖（`off`、`inbound`、`always`）。它会覆盖顶层 `threadReplies` 设置，对私信中的回复放置和会话隔离都生效。 -- `execApprovals`：Matrix 原生 exec 批准投递（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。 -- `execApprovals.approvers`：允许批准 exec 请求的 Matrix 用户 ID。当 `dm.allowFrom` 已经标识批准人时，此项可选。 +- `dm.policy`：控制 OpenClaw 加入房间并将其分类为私信之后的私信访问权限。它不会改变邀请是否会被自动加入。 +- `dm.allowFrom`：私信流量的用户 ID allowlist。完整 Matrix 用户 ID 最安全；当监视器运行时，会在启动时以及 allowlist 发生变化时解析精确目录匹配。无法解析的名称会被忽略。 +- `dm.sessionScope`：`per-user`（默认）或 `per-room`。如果你希望每个 Matrix 私信房间即使对端相同也保持独立上下文，请使用 `per-room`。 +- `dm.threadReplies`：仅私信的线程策略覆盖值（`off`、`inbound`、`always`）。它会覆盖顶层 `threadReplies` 设置，同时影响私信中的回复位置和会话隔离。 +- `execApprovals`：Matrix 原生 exec 审批发送（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。 +- `execApprovals.approvers`：允许批准 exec 请求的 Matrix 用户 ID。当 `dm.allowFrom` 已经标识审批人时，该项可选。 - `execApprovals.target`：`dm | channel | both`（默认值：`dm`）。 -- `accounts`：命名的按账户覆盖项。顶层 `channels.matrix` 值会作为这些条目的默认值。 -- `groups`：按房间的策略映射。优先使用房间 ID 或别名；无法解析的房间名称会在运行时被忽略。解析之后，会话/群组身份使用稳定的房间 ID。 -- `groups..account`：在多账户设置中，将一个继承的房间条目限制到特定 Matrix 账户。 -- `groups..allowBots`：针对已配置机器人发送者的房间级覆盖（`true` 或 `"mentions"`）。 -- `groups..users`：按房间的发送者允许列表。 -- `groups..tools`：按房间的工具允许/拒绝覆盖。 -- `groups..autoReply`：房间级提及门控覆盖。`true` 会禁用该房间的提及要求；`false` 会强制重新启用。 +- `accounts`：按账户命名的覆盖项。顶层 `channels.matrix` 值会作为这些条目的默认值。 +- `groups`：按房间划分的策略映射。优先使用房间 ID 或别名；无法解析的房间名称会在运行时被忽略。解析后，会话/群组身份使用稳定的房间 ID。 +- `groups..account`：在多账户设置中，将一条继承的房间条目限制到特定 Matrix 账户。 +- `groups..allowBots`：针对已配置机器人发送者的房间级覆盖值（`true` 或 `"mentions"`）。 +- `groups..users`：按房间划分的发送者 allowlist。 +- `groups..tools`：按房间划分的工具允许/拒绝覆盖。 +- `groups..autoReply`：房间级提及门控覆盖值。`true` 会禁用该房间的提及要求；`false` 会强制重新启用。 - `groups..skills`：可选的房间级 Skills 过滤器。 -- `groups..systemPrompt`：可选的房间级系统提示片段。 +- `groups..systemPrompt`：可选的房间级 system prompt 片段。 - `rooms`：`groups` 的旧别名。 -- `actions`：按操作的工具门控（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 +- `actions`：按操作划分的工具门控（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 ## 相关内容 diff --git a/docs/zh-CN/cli/cron.md b/docs/zh-CN/cli/cron.md index 212124386..14c83ac84 100644 --- a/docs/zh-CN/cli/cron.md +++ b/docs/zh-CN/cli/cron.md @@ -1,14 +1,14 @@ --- read_when: - - 你想要计划任务和唤醒功能 + - 你想要定时作业和唤醒功能 - 你正在调试 cron 执行和日志 summary: '`openclaw cron` 的 CLI 参考（调度并运行后台作业）' title: Cron x-i18n: - generated_at: "2026-04-25T05:53:11Z" + generated_at: "2026-04-26T01:24:06Z" model: gpt-5.4 provider: openai - source_hash: 281c0e0e5a3139d2b9cb7cc02afe3b9a9d4a20228a7891eb45c55b7e22c5e1c4 + source_hash: 55cadcf73550367d399b7ca78e842f12a8113f2ec8749f59dadf2bbb5f8417ae source_path: cli/cron.md workflow: 15 --- @@ -21,48 +21,49 @@ x-i18n: - Cron 作业：[Cron 作业](/zh-CN/automation/cron-jobs) -提示：运行 `openclaw cron --help` 可查看完整命令范围。 +提示：运行 `openclaw cron --help` 可查看完整命令说明。 -注意：`openclaw cron list` 和 `openclaw cron show ` 会预览解析后的投递路由。对于 `channel: "last"`，预览会显示该路由是从主/当前会话解析得出，还是会以失败关闭。 +注意：`openclaw cron list` 和 `openclaw cron show ` 会预览解析后的投递路由。对于 `channel: "last"`，预览会显示该路由是从主/当前会话解析得到，还是会以失败关闭。 -注意：独立的 `cron add` 作业默认使用 `--announce` 投递。使用 `--no-deliver` 可将输出保持为内部可见。`--deliver` 仍然保留为 `--announce` 的已弃用别名。 +注意：隔离的 `cron add` 作业默认使用 `--announce` 投递。使用 `--no-deliver` 可将输出保留为内部内容。`--deliver` 仍保留为已弃用的 `--announce` 别名。 -注意：独立 cron 聊天投递是共享的。`--announce` 是用于最终回复的运行器后备投递；`--no-deliver` 会禁用该后备方式，但当聊天路由可用时，不会移除智能体的 `message` 工具。 +注意：隔离的 cron 聊天投递是共享的。`--announce` 是运行器用于最终回复的后备投递方式；`--no-deliver` 会禁用该后备方式，但当聊天路由可用时，不会移除智能体的 `message` 工具。 -注意：一次性（`--at`）作业默认在成功后删除。使用 `--keep-after-run` 可在运行后保留它们。 +注意：一次性（`--at`）作业在成功后默认会删除。使用 `--keep-after-run` 可在运行后保留它们。 -注意：`--session` 支持 `main`、`isolated`、`current` 和 `session:`。使用 `current` 可在创建时绑定到当前活动会话，或使用 `session:` 指定一个显式的持久会话键。 +注意：`--session` 支持 `main`、`isolated`、`current` 和 `session:`。使用 `current` 可在创建时绑定到当前活动会话，或使用 `session:` 指定显式的持久会话键。 -注意：`--session isolated` 会为每次运行创建一个新的转录/会话 id。安全偏好设置和用户显式选择的模型/认证覆盖项可以继承，但环境中的对话上下文不会继承：渠道/群组路由、发送/排队策略、权限提升、来源和 ACP 运行时绑定都会为新的独立运行重置。 +注意：`--session isolated` 会为每次运行创建新的转录/会话 id。安全偏好设置和用户显式选择的模型/认证覆盖可以继承，但环境性的对话上下文不会继承：渠道/群组路由、发送/排队策略、提权、来源以及 ACP 运行时绑定都会为新的隔离运行重置。 -注意：对于一次性的 CLI 作业，无偏移量的 `--at` 日期时间默认按 UTC 处理，除非你同时传入 `--tz `，此时会将该本地墙钟时间按给定时区解释。 +注意：对于一次性的 CLI 作业，无偏移量的 `--at` 日期时间默认按 UTC 处理，除非你同时传入 `--tz `，此时会将该本地墙上时间按给定时区解释。 -注意：循环作业现在会在连续错误后使用指数退避重试（30 秒 → 1 分钟 → 5 分钟 → 15 分钟 → 60 分钟），并在下一次成功运行后恢复正常调度。 +注意：循环作业现在会在连续出错后使用指数退避重试（30s → 1m → 5m → 15m → 60m），并在下一次成功运行后恢复正常调度。 注意：`openclaw cron run` 现在会在手动运行被加入执行队列后立即返回。成功响应包含 `{ ok: true, enqueued: true, runId }`；使用 `openclaw cron runs --id ` 可跟踪最终结果。 -注意：`openclaw cron run ` 默认会强制运行。使用 `--due` 可保留较早的“仅在到期时运行”行为。 +注意：`openclaw cron run ` 默认会强制运行。使用 `--due` 可保持旧版“仅在到期时运行”的行为。 -注意：独立 cron 轮次会抑制过时的、仅确认性质的回复。如果第一个结果只是中间状态更新，并且没有后代子智能体运行负责给出最终答案，cron 会再提示一次以获取真实结果后再投递。 +注意：隔离 cron 运行会抑制过时的、仅作确认的回复。如果第一个结果只是中间状态更新，且没有后代子智能体运行负责给出最终答案，cron 会再次提示一次以获取真实结果后再投递。 -注意：如果独立 cron 运行只返回静默令牌（`NO_REPLY` / `no_reply`），cron 会同时抑制直接对外投递和后备排队摘要路径，因此不会向聊天回发任何内容。 +注意：如果一次隔离 cron 运行仅返回静默令牌（`NO_REPLY` / `no_reply`），cron 会同时抑制直接对外投递和后备的排队摘要路径，因此不会向聊天回传任何内容。 -注意：`cron add|edit --model ...` 会为该作业使用所选的允许模型。如果该模型不被允许，cron 会发出警告，并回退到该作业的智能体/默认模型选择。已配置的回退链仍然适用，但如果只是普通模型覆盖且没有显式的每作业回退列表，就不会再把智能体主模型作为隐藏的额外重试目标附加进去。 +注意：`cron add|edit --model ...` 会为作业使用所选的允许模型。如果该模型不被允许，cron 会发出警告，并回退到作业的智能体/默认模型选择。已配置的后备链仍然生效，但仅有模型覆盖且没有显式的按作业后备列表时，不再将智能体主模型作为隐藏的额外重试目标附加进去。 -注意：独立 cron 的模型优先级依次为：先 Gmail-hook 覆盖，然后是每作业的 `--model`，再然后是任何用户选择并存储的 cron 会话模型覆盖，最后才是常规的智能体/默认选择。 +注意：隔离 cron 的模型优先级为：先 Gmail-hook 覆盖，再按作业的 `--model`，然后是任何用户选择并存储的 cron 会话模型覆盖，最后才是正常的智能体/默认选择。 -注意：独立 cron 快速模式遵循已解析的实时模型选择。模型配置 `params.fastMode` 默认生效，但已存储的会话 `fastMode` 覆盖仍然优先于配置。 +注意：隔离 cron 的快速模式遵循解析后的实时模型选择。模型配置中的 `params.fastMode` 默认生效，但已存储的会话 `fastMode` 覆盖仍优先于配置。 -注意：如果独立运行抛出 `LiveSessionModelSwitchError`，cron 会在重试前为当前运行持久化切换后的 provider/模型（以及存在时切换后的认证配置覆盖）。外层重试循环限制为初始尝试后的 2 次切换重试，之后会中止，而不是无限循环。 +注意：如果隔离运行抛出 `LiveSessionModelSwitchError`，cron 会在重试前为当前运行持久化切换后的 provider/模型（以及存在时切换后的认证配置覆盖）。外层重试循环在初次尝试后最多进行 2 次切换重试，之后会中止，而不是无限循环。 注意：失败通知会优先使用 `delivery.failureDestination`，其次使用全局 `cron.failureDestination`，最后在未配置显式失败目标时回退到作业的主 announce 目标。 注意：保留/清理由配置控制： -- `cron.sessionRetention`（默认 `24h`）会清理已完成的独立运行会话。 +- `cron.sessionRetention`（默认 `24h`）会清理已完成的隔离运行会话。 - `cron.runLog.maxBytes` + `cron.runLog.keepLines` 会清理 `~/.openclaw/cron/runs/.jsonl`。 -升级说明：如果你有早于当前投递/存储格式的旧 cron 作业，请运行 `openclaw doctor --fix`。Doctor 现在会规范化旧版 cron 字段（`jobId`、`schedule.cron`、顶层投递字段，包括旧版 `threadId`、负载中的 `provider` 投递别名），并在配置了 `cron.webhook` 时，将简单的 `notify: true` webhook 后备作业迁移为显式 webhook 投递。 +升级说明：如果你有在当前投递/存储格式之前创建的旧 cron 作业，请运行 +`openclaw doctor --fix`。Doctor 现在会规范化旧版 cron 字段（`jobId`、`schedule.cron`、顶层投递字段，包括旧版 `threadId`、负载中的 `provider` 投递别名），并在配置了 `cron.webhook` 时，将简单的 `notify: true` webhook 后备作业迁移为显式 webhook 投递。 ## 常见编辑 @@ -72,42 +73,43 @@ x-i18n: openclaw cron edit --announce --channel telegram --to "123456789" ``` -为独立作业禁用投递： +为隔离作业禁用投递： ```bash openclaw cron edit --no-deliver ``` -为独立作业启用轻量级引导上下文： +为隔离作业启用轻量级引导上下文： ```bash openclaw cron edit --light-context ``` -向特定渠道 announce： +向特定渠道发送公告： ```bash openclaw cron edit --announce --channel slack --to "channel:C1234567890" ``` -创建一个带轻量级引导上下文的独立作业： +创建带有轻量级引导上下文的隔离作业： ```bash openclaw cron add \ - --name "Lightweight morning brief" \ + --name "轻量级晨间简报" \ --cron "0 7 * * *" \ --session isolated \ - --message "Summarize overnight updates." \ + --message "总结夜间更新。" \ --light-context \ --no-deliver ``` -`--light-context` 仅适用于独立智能体轮次作业。对于 cron 运行，轻量模式会保持引导上下文为空，而不是注入完整的工作区引导集。 +`--light-context` 仅适用于隔离的智能体轮次作业。对于 cron 运行，轻量级模式会保持引导上下文为空，而不是注入完整的工作区引导集合。 投递归属说明： -- 独立 cron 聊天投递是共享的。当聊天路由可用时，智能体可以使用 `message` 工具直接发送。 -- `announce` 仅在智能体未直接发送到已解析目标时，后备投递最终回复。`webhook` 会将完成后的负载发布到某个 URL。`none` 会禁用运行器后备投递。 +- 隔离 cron 聊天投递是共享的。当聊天路由可用时，智能体可以使用 `message` 工具直接发送。 +- `announce` 仅在智能体未直接发送到解析出的目标时，才会后备投递最终回复。`webhook` 会将完成后的负载发送到 URL。`none` 会禁用运行器后备投递。 +- 从活动聊天创建的提醒会保留当前聊天投递目标，用于后备 announce 投递。内部会话键可能为小写；不要将其用作区分大小写的 provider id（例如 Matrix 房间 id）的真实来源。 ## 常见管理命令 @@ -121,7 +123,7 @@ openclaw cron run --due openclaw cron runs --id --limit 50 ``` -`cron runs` 条目包含投递诊断信息，其中包括预期的 cron 目标、已解析的目标、message-tool 发送、后备使用情况以及已投递状态。 +`cron runs` 条目包含投递诊断信息，包括预期的 cron 目标、解析后的目标、message-tool 发送情况、后备使用情况以及已投递状态。 智能体/会话重定向： @@ -132,7 +134,7 @@ openclaw cron edit --session current openclaw cron edit --session "session:daily-brief" ``` -投递微调： +投递调整： ```bash openclaw cron edit --announce --channel slack --to "channel:C1234567890" @@ -143,11 +145,11 @@ openclaw cron edit --no-deliver 失败投递说明： -- `delivery.failureDestination` 支持用于独立作业。 -- 主会话作业仅在主投递模式为 `webhook` 时，才能使用 `delivery.failureDestination`。 -- 如果你未设置任何失败目标，并且该作业已经向某个渠道 announce，失败通知会复用同一个 announce 目标。 +- `delivery.failureDestination` 支持用于隔离作业。 +- 主会话作业仅当主投递模式为 `webhook` 时，才可使用 `delivery.failureDestination`。 +- 如果你未设置任何失败目标，而该作业已向某个渠道进行 announce，则失败通知会复用同一个 announce 目标。 ## 相关内容 - [CLI 参考](/zh-CN/cli) -- [计划任务](/zh-CN/automation/cron-jobs) +- [定时任务](/zh-CN/automation/cron-jobs)