openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-23 05:41:41 +00:00
parent e5b3955e3f
commit c926e1705f
5 changed files with 209 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
docs/zh-CN/automation/taskflow.md
View File

@ -1,43 +1,43 @@
---
read_when:
- 你想了解 Task Flow 与后台任务之间的关系
- 你在发行说明或文档中遇到 Task Flow 或 openclaw tasks flow
- 你想检查或管理持久化流程状态
summary: 位于后台任务之上的 Task Flow 流程编排层
title: Task Flow
- 你在发布说明或文档中遇到了 Task Flow 或 openclaw tasks flow
- 你想检查或管理持久化的 flow 状态
summary: 任务流是位于后台任务之上的 flow 编排层
title: 任务流
x-i18n:
generated_at: "2026-04-05T08:13:15Z"
generated_at: "2026-04-23T05:40:52Z"
model: gpt-5.4
provider: openai
source_hash: 172871206b839845db807d9c627015890f7733b862e276853d5dbfbe29e03883
source_hash: f94a3cda89db5bfcc6c396358bc3fcee40f9313e102dc697d985f40707381468
source_path: automation/taskflow.md
workflow: 15
---
# Task Flow
# 任务流
Task Flow 是位于[后台任务](/automation/tasks)之上的流程编排基础层。它管理具有自身状态、修订跟踪和同步语义的持久化多步骤流程，而单个任务仍然是分离工作的基本单元。
任务流是位于 [后台任务](/zh-CN/automation/tasks) 之上的 flow 编排基础层。它管理具有自身状态、修订跟踪和同步语义的持久化多步骤 flow，而单个任务仍然是分离工作的基本单位。
## 何时使用 Task Flow
## 何时使用任务流
当工作跨越多个顺序或分支步骤，并且你需要在 Gateway 网关重启后仍能持续跟踪进度时，请使用 Task Flow。对于单个后台操作，普通的[任务](/automation/tasks)就已足够。
当工作跨越多个顺序或分支步骤，并且你需要在 Gateway 网关重启后仍能持续跟踪进度时，请使用任务流。对于单个后台操作，普通的 [任务](/zh-CN/automation/tasks) 就已足够。
| 场景 | 使用方式 |
| ------------------------------------- | -------------------- |
| 单个后台作业 | 普通任务 |
| 多步骤流水线（A 然后 B 然后 C） | Task Flow（托管） |
| 观察外部创建的任务 | Task Flow（镜像） |
| 多步骤流水线（A 然后 B 然后 C） | 任务流（托管） |
| 观察外部创建的任务 | 任务流（镜像） |
| 一次性提醒 | Cron 作业 |
## 同步模式
### 托管模式
Task Flow 端到端地拥有整个生命周期。它将任务创建为流程步骤，推动其完成，并自动推进流程状态。
任务流端到端拥有整个生命周期。它将任务创建为 flow 步骤，驱动它们完成，并自动推进 flow 状态。
示例：一个每周报告流程，(1) 收集数据，(2) 生成报告，以及 (3) 发送报告。Task Flow 会将每个步骤创建为后台任务，等待完成，然后移动到下一个步骤。
示例：一个每周报告 flow，执行以下步骤：(1) 收集数据，(2) 生成报告，以及 (3) 发送报告。任务流会将每个步骤创建为后台任务，等待完成，然后移动到下一个步骤。
```
```text
Flow: weekly-report
Step 1: gather-data → task created → succeeded
Step 2: generate-report → task created → succeeded
@ -46,44 +46,44 @@ Flow: weekly-report
### 镜像模式
Task Flow 会观察外部创建的任务，并在不接管任务创建的情况下保持流程状态同步。当任务来自 cron 作业、CLI 命令或其他来源，而你希望以流程形式统一查看其进度时，这种模式非常有用。
任务流会观察外部创建的任务，并在不接管任务创建所有权的情况下保持 flow 状态同步。当任务来自 Cron 作业、CLI 命令或其他来源，而你希望以 flow 的形式统一查看其进度时，这种方式非常有用。
示例：三个彼此独立的 cron 作业共同组成了一个“早间运维”例程。镜像流程会跟踪它们的整体进度，但不会控制它们何时或如何运行。
示例：三个彼此独立的 Cron 作业，共同组成一个“晨间运维”流程。镜像 flow 会跟踪它们的整体进度，而不控制它们何时或如何运行。
## 持久化状态与修订跟踪
## 持久化状态和修订跟踪
每个流程都会持久化自身状态并跟踪修订，因此即使 Gateway 网关重启，进度也能保留。修订跟踪可在多个来源同时尝试推进同一流程时进行冲突检测。
每个 flow 都会持久化自己的状态并跟踪修订，因此在 Gateway 网关重启后进度仍然会保留。修订跟踪支持在多个来源尝试并发推进同一个 flow 时进行冲突检测。
## 取消行为
`openclaw tasks flow cancel` 会在流程上设置粘性取消意图。流程中的活动任务会被取消，且不会启动任何新步骤。该取消意图会在重启后继续保留，因此即使 Gateway 网关在所有子任务终止之前重启，被取消的流程仍会保持取消状态。
`openclaw tasks flow cancel` 会在 flow 上设置粘性的取消意图。flow 中的活动任务会被取消，并且不会启动任何新步骤。取消意图会在重启后保留，因此即使 Gateway 网关在所有子任务终止之前重启，被取消的 flow 仍会保持为已取消状态。
## CLI 命令
```bash
# List active and recent flows
# 列出活动和最近的 flow
openclaw tasks flow list
# Show details for a specific flow
# 显示特定 flow 的详细信息
openclaw tasks flow show <lookup>
# Cancel a running flow and its active tasks
# 取消一个正在运行的 flow 及其活动任务
openclaw tasks flow cancel <lookup>
```
| 命令 | 说明 |
| --------------------------------- | --------------------------------------------- |
| `openclaw tasks flow list` | 显示已跟踪流程的状态和同步模式 |
| `openclaw tasks flow show <id>` | 按流程 id 或查找键检查单个流程 |
| `openclaw tasks flow cancel <id>` | 取消正在运行的流程及其活动任务 |
| `openclaw tasks flow list` | 显示已跟踪的 flow，包括状态和同步模式 |
| `openclaw tasks flow show <id>` | 按 flow id 或查找键检查单个 flow |
| `openclaw tasks flow cancel <id>` | 取消一个正在运行的 flow 及其活动任务 |
## 流程与任务的关系
## flow 与任务的关系
流程用于协调任务，而不是替代任务。单个流程在其生命周期内可能会驱动多个后台任务。使用 `openclaw tasks` 检查单个任务记录，使用 `openclaw tasks flow` 检查负责协调的流程。
flow 负责协调任务，而不是取代任务。一个 flow 在其整个生命周期中可能会驱动多个后台任务。使用 `openclaw tasks` 检查单个任务记录，使用 `openclaw tasks flow` 检查编排这些任务的 flow。
## 相关内容
- [后台任务](/automation/tasks) — 流程所协调的分离工作台账
- [CLI：tasks](/cli/index#tasks) — `openclaw tasks flow` 的 CLI 命令参考
- [自动化概览](/automation) — 一览所有自动化机制
- [Cron 作业](/automation/cron-jobs) — 可能会输入到流程中的定时作业
- [后台任务](/zh-CN/automation/tasks) — flow 协调的分离工作账本
- [CLI：任务](/cli/tasks) — `openclaw tasks flow` 的 CLI 命令参考
- [自动化概览](/zh-CN/automation) — 一览所有自动化机制
- [Cron 作业](/zh-CN/automation/cron-jobs) — 可能输入到 flow 中的计划作业

182
docs/zh-CN/automation/tasks.md
View File

@ -1,44 +1,44 @@
---
read_when:
- 检查正在进行中或最近已完成的后台工作
- 调试分离式智能体运行的交付失败问题
- 调试已分离的智能体运行的交付失败问题
- 了解后台运行与会话、cron 和心跳之间的关系
summary: ACP 运行、子智能体、隔离的 cron 作业和 CLI 操作的后台任务跟踪
summary: 用于 ACP 运行、子智能体、隔离的 cron 作业和 CLI 操作的后台任务跟踪
title: 后台任务
x-i18n:
generated_at: "2026-04-21T19:01:00Z"
generated_at: "2026-04-23T05:40:52Z"
model: gpt-5.4
provider: openai
source_hash: a4cd666b3eaffde8df0b5e1533eb337e44a0824824af6f8a240f18a89f71b402
source_hash: 5cd0b0db6c20cc677aa5cc50c42e09043d4354e026ca33c020d804761c331413
source_path: automation/tasks.md
workflow: 15
---
# 后台任务
> **在找调度功能？** 请参阅 [Automation & Tasks](/zh-CN/automation)，以选择合适的机制。本页介绍的是如何**跟踪**后台工作，而不是如何调度它。
> **在找调度方式？** 请参阅 [Automation & Tasks](/zh-CN/automation) 以选择合适的机制。本页介绍的是后台工作的**跟踪**，而不是如何调度它。
后台任务用于跟踪**在你的主会话之外**运行的工作：
ACP 运行、子智能体派生、隔离的 cron 作业执行，以及由 CLI 发起的操作。
ACP 运行、子智能体生成、隔离的 cron 作业执行，以及由 CLI 发起的操作。
任务**不会**替代会话、cron 作业或心跳——它们是记录这些分离式工作“发生了什么、何时发生、以及是否成功”的**活动台账**。
任务**不会**取代会话、cron 作业或心跳——它们是记录已分离工作“发生了什么、何时发生、是否成功”的**活动台账**。
<Note>
并非每次智能体运行都会创建任务。心跳轮次和普通交互式聊天不会。所有 cron 执行、ACP 派生、子智能体派生以及 CLI 智能体命令都会创建任务。
并非每一次智能体运行都会创建任务。心跳轮次和普通的交互式聊天不会。所有 cron 执行、ACP 生成、子智能体生成以及 CLI 智能体命令都会创建任务。
</Note>
## TL;DR
- 任务是**记录**，不是调度器——cron 和心跳决定工作**何时**运行，任务跟踪**发生了什么**。
- 任务是**记录**，不是调度器——cron 和心跳决定工作**何时**运行，任务负责跟踪**发生了什么**。
- ACP、子智能体、所有 cron 作业和 CLI 操作都会创建任务。心跳轮次不会。
- 每个任务都会经历 `queued → running → terminal`（succeeded、failed、timed_out、cancelled 或 lost）。
- 只要 cron 运行时仍然拥有该作业，cron 任务就会保持活动状态；而由聊天支持的 CLI 任务只有在其所属运行上下文仍处于活动状态时才会保持活动状态。
- 完成采用推送驱动：分离式工作完成后可以直接通知，或唤醒请求方会话/心跳，因此状态轮询循环通常不是合适的模式。
- 隔离的 cron 运行和子智能体完成时，会尽力在最终清理记账前，为其子会话清理已跟踪的浏览器标签页/进程。
- 隔离的 cron 交付会在后代子智能体工作仍在收尾时抑制过时的父级中间回复，并在后代最终输出先于交付到达时优先使用该最终输出。
- 完成通知会直接发送到渠道，或排队等待下一次心跳。
- 只要 cron 运行时仍然拥有该作业，cron 任务就会保持活跃；而由聊天支持的 CLI 任务只会在其所属运行上下文仍然活跃时保持活跃。
- 完成采用推送驱动：已分离的工作可以在结束时直接通知，或唤醒请求方的会话/心跳，因此轮询状态的循环通常不是正确方式。
- 隔离的 cron 运行和子智能体完成时，会尽最大努力为其子会话清理已跟踪的浏览器标签页/进程，然后再做最终清理记账。
- 隔离的 cron 交付会在后代子智能体工作仍在收尾时，抑制过时的中间父级回复；如果最终的后代输出先到达，则优先使用它。
- 完成通知会直接发送到某个渠道，或排队等待下一次心跳。
- `openclaw tasks list` 显示所有任务；`openclaw tasks audit` 用于发现问题。
- 终态记录会保留 7 天，之后自动清理。
- 终态记录会保留 7 天，之后自动清除。
## 快速开始
@ -53,7 +53,7 @@ openclaw tasks list --status running
# 显示特定任务的详细信息（按 ID、run ID 或 session key）
openclaw tasks show <lookup>
# 取消正在运行的任务（终止子会话）
# 取消一个正在运行的任务（终止子会话）
openclaw tasks cancel <lookup>
# 更改任务的通知策略
@ -76,23 +76,23 @@ openclaw tasks flow cancel <lookup>
| 来源 | 运行时类型 | 何时创建任务记录 | 默认通知策略 |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
| ACP 后台运行 | `acp` | 派生 ACP 子会话时 | `done_only` |
| 子智能体编排 | `subagent` | 通过 `sessions_spawn` 派生子智能体时 | `done_only` |
| cron 作业（所有类型） | `cron` | 每次 cron 执行时（主会话和隔离式均包括） | `silent` |
| ACP 后台运行 | `acp` | 生成子 ACP 会话时 | `done_only` |
| 子智能体编排 | `subagent` | 通过 `sessions_spawn` 生成子智能体时 | `done_only` |
| Cron 作业（所有类型） | `cron` | 每次 cron 执行时（主会话和隔离模式） | `silent` |
| CLI 操作 | `cli` | 通过 Gateway 网关运行的 `openclaw agent` 命令 | `silent` |
| 智能体媒体作业 | `cli` | 由会话支持的 `video_generate` 运行 | `silent` |
主会话 cron 任务默认使用 `silent` 通知策略——它们会创建记录以供跟踪，但不会生成通知。隔离的 cron 任务同样默认使用 `silent`，但由于它们在自己的会话中运行，因此更容易被看到。
主会话 cron 任务默认使用 `silent` 通知策略——它们会创建记录用于跟踪，但不会生成通知。隔离的 cron 任务也默认使用 `silent`，但因为它们在自己的会话中运行，所以更容易被看到。
由会话支持的 `video_generate` 运行也使用 `silent` 通知策略。它们仍会创建任务记录，但完成结果会通过内部唤醒返还给原始智能体会话，以便智能体自行写入后续消息并附加已完成的视频。如果你启用了 `tools.media.asyncCompletion.directSend`，异步 `music_generate` 和 `video_generate` 完成时会先尝试直接发送到渠道，失败后再回退到唤醒请求方会话的路径。
由会话支持的 `video_generate` 运行同样使用 `silent` 通知策略。它们仍会创建任务记录，但完成后会通过内部唤醒交还给原始智能体会话，这样智能体就可以自行编写后续消息并附加已完成的视频。如果你启用了 `tools.media.asyncCompletion.directSend`，异步 `music_generate` 和 `video_generate` 完成时会优先尝试直接向渠道发送，失败后再回退到唤醒请求方会话的路径。
当某个由会话支持的 `video_generate` 任务仍处于活动状态时，该工具也会充当护栏：在同一会话中重复调用 `video_generate` 时，不会启动第二个并发生成，而是返回当前活动任务的状态。当你希望从智能体侧显式查询进度/状态时，请使用 `action: "status"`。
当某个由会话支持的 `video_generate` 任务仍处于活动状态时，该工具还会充当护栏：同一会话中重复调用 `video_generate` 不会启动第二个并发生成，而是返回当前活动任务的状态。当你希望智能体端显式查询进度/状态时，请使用 `action: "status"`。
**以下情况不会创建任务：**
**不会创建任务的情况：**
- 心跳轮次——主会话；请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)
- 心跳轮次——主会话；参见 [Heartbeat](/zh-CN/gateway/heartbeat)
- 普通交互式聊天轮次
- 直接的 `/command` 响应
- 直接 `/command` 响应
## 任务生命周期
@ -111,47 +111,47 @@ stateDiagram-v2
| 状态 | 含义 |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | 已创建，等待智能体启动 |
| `running` | 智能体轮次正在执行 |
| `running` | 智能体轮次正在主动执行 |
| `succeeded` | 已成功完成 |
| `failed` | 以错误结束 |
| `timed_out` | 超过配置的超时时间 |
| `cancelled` | 操作员通过 `openclaw tasks cancel` 停止 |
| `lost` | 运行时在 5 分钟宽限期后失去了权威性支撑状态 |
| `failed` | 已带错误完成 |
| `timed_out` | 超过已配置的超时时间 |
| `cancelled` | 由操作员通过 `openclaw tasks cancel` 停止 |
| `lost` | 运行时在 5 分钟宽限期后丢失了权威的后备状态 |
状态转换会自动发生——当关联的智能体运行结束时，任务状态会更新为对应结果。
状态转换会自动发生——关联的智能体运行结束后，任务状态会更新为对应结果。
`lost` 具备运行时感知能力：
`lost` 是感知运行时类型的：
- ACP 任务：支撑它的 ACP 子会话元数据已消失。
- 子智能体任务：支撑它的子会话已从目标智能体存储中消失。
- cron 任务：cron 运行时不再将该作业标记为活动状态。
- CLI 任务：隔离子会话任务使用子会话；由聊天支持的 CLI 任务则改为使用实时运行上下文，因此残留的渠道/群组/私聊会话行不会让它们继续保持活动状态。
- ACP 任务：后备的 ACP 子会话元数据消失。
- 子智能体任务：后备子会话从目标智能体存储中消失。
- Cron 任务：cron 运行时不再将该作业跟踪为活动状态。
- CLI 任务：隔离的子会话任务使用子会话；而由聊天支持的 CLI 任务则改为使用实时运行上下文，因此残留的渠道/群组/私信会话行不会让它们继续保持活跃。
## 交付与通知
当任务进入终态时，OpenClaw 会通知你。存在两种交付路径：
当任务进入终态时，OpenClaw 会通知你。有两种交付路径：
**直接交付**——如果任务具有渠道目标（`requesterOrigin`），完成消息会直接发送到该渠道（Telegram、Discord、Slack 等）。对于子智能体完成，OpenClaw 还会在可用时保留已绑定的线程/话题路由，并可在直接交付前，从请求方会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`）中补全缺失的 `to` / account。
**直接交付**——如果任务有渠道目标（即 `requesterOrigin`），完成消息会直接发送到该渠道（Telegram、Discord、Slack 等）。对于子智能体完成，OpenClaw 还会在可用时保留已绑定的线程/话题路由，并且在直接交付前，如果缺失 `to` / account，也可以从请求方会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`）中补全。
**会话排队交付**——如果直接交付失败或未设置来源，更新将作为系统事件排入请求方会话，并在下一次心跳时呈现。
**会话排队交付**——如果直接交付失败，或者没有设置来源，则更新会作为系统事件排入请求方会话，并在下一次心跳时显示出来。
<Tip>
任务完成会立即触发一次心跳唤醒，因此你可以快速看到结果——不必等待下一次计划中的心跳触发。
任务完成会立即触发一次心跳唤醒，这样你可以更快看到结果——你不必等到下一次计划中的心跳轮询。
</Tip>
这意味着常见工作流是基于推送的：只需启动一次分离式工作，然后让运行时在完成时唤醒你或通知你。只有在你需要调试、干预或执行显式审计时，才需要轮询任务状态。
这意味着通常的工作流是基于推送的：只需启动一次已分离工作，然后让运行时在完成时唤醒你或通知你。只有在你需要调试、干预或进行显式审计时，才去轮询任务状态。
### 通知策略
控制你希望收到每个任务多少信息：
控制你希望收到多少任务通知：
| 策略 | 交付内容 |
| 策略 | 会交付什么 |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only`（默认） | 仅终态（succeeded、failed 等）——**这是默认值** |
| `state_changes` | 每次状态转换和进度更新 |
| `silent` | 完全不通知 |
可在任务运行期间更改策略：
你可以在任务运行时更改策略：
```bash
openclaw tasks notify <lookup> state_changes
@ -165,7 +165,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
输出列：任务 ID、类型、状态、交付、运行 ID、子会话、摘要。
输出列：任务 ID、类型、状态、交付、Run ID、子会话、摘要。
### `tasks show`
@ -173,7 +173,7 @@ openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--j
openclaw tasks show <lookup>
```
查找令牌支持任务 ID、运行 ID 或会话键。会显示完整记录，包括时间信息、交付状态、错误和终态摘要。
查找标记可以接受任务 ID、run ID 或 session key。显示完整记录，包括时间、交付状态、错误和终态摘要。
### `tasks cancel`
@ -181,7 +181,7 @@ openclaw tasks show <lookup>
openclaw tasks cancel <lookup>
```
对于 ACP 和子智能体任务，这会终止子会话。对于由 CLI 跟踪的任务，取消会记录到任务注册表中（不存在单独的子运行时句柄）。状态会转换为 `cancelled`，并在适用时发送交付通知。
对于 ACP 和子智能体任务，这会终止子会话。对于由 CLI 跟踪的任务，取消操作会记录到任务注册表中（不存在单独的子运行时句柄）。状态会切换为 `cancelled`，并在适用时发送交付通知。
### `tasks notify`
@ -195,16 +195,16 @@ openclaw tasks notify <lookup> <done_only|state_changes|silent>
openclaw tasks audit [--json]
```
用于发现运维问题。检测到问题时，这些发现也会出现在 `openclaw status` 中。
用于发现运维问题。如果检测到问题，这些发现也会出现在 `openclaw status` 中。
| 发现项 | 严重级别 | 触发条件 |
| ------------------------- | -------- | ----------------------------------------------------- |
| `stale_queued` | warn | 处于 queued 超过 10 分钟 |
| `stale_running` | error | 处于 running 超过 30 分钟 |
| `lost` | error | 由运行时支撑的任务所有权已消失 |
| `stale_queued` | warn | 处于排队状态超过 10 分钟 |
| `stale_running` | error | 运行中超过 30 分钟 |
| `lost` | error | 由运行时支持的任务归属消失 |
| `delivery_failed` | warn | 交付失败且通知策略不是 `silent` |
| `missing_cleanup` | warn | 终态任务没有清理时间戳 |
| `inconsistent_timestamps` | warn | 时间线违反约束（例如结束时间早于开始时间） |
| `missing_cleanup` | warn | 已终态任务缺少清理时间戳 |
| `inconsistent_timestamps` | warn | 时间线冲突（例如结束早于开始） |
### `tasks maintenance`
@ -213,20 +213,20 @@ openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
用它来预览或应用任务及 Task Flow 状态的对账、清理时间戳补写和清理裁剪。
使用它来预览或应用任务及 Task Flow 状态的对账、清理标记和清除。
对账具备运行时感知能力：
对账是感知运行时类型的：
- ACP/子智能体任务会检查其支撑的子会话。
- cron 任务会检查 cron 运行时是否仍拥有该作业。
- 由聊天支持的 CLI 任务会检查所属的实时运行上下文，而不只是聊天会话行。
- ACP/子智能体任务会检查其后备子会话。
- Cron 任务会检查 cron 运行时是否仍然拥有该作业。
- 由聊天支持的 CLI 任务会检查所属的实时运行上下文，而不只是聊天会话记录行。
完成清理同样具备运行时感知能力：
完成后的清理同样是感知运行时类型的：
- 子智能体完成时，会尽力先关闭该子会话已跟踪的浏览器标签页/进程，然后再继续公告清理。
- 隔离的 cron 完成时，会尽力先关闭该 cron 会话已跟踪的浏览器标签页/进程，然后再让该运行完全结束。
- 隔离的 cron 交付会在需要时等待后代子智能体后续处理完成，并抑制过时的父级确认文本，而不是将其作为结果公告。
- 子智能体完成交付会优先使用最新的可见助手文本；如果该文本为空，则回退到经清理的最新 tool/toolResult 文本；仅包含超时工具调用的运行可折叠为简短的部分进度摘要。终态失败的运行会公告失败状态，而不会重放已捕获的回复文本。
- 子智能体完成时，会尽最大努力在继续公告清理之前关闭子会话已跟踪的浏览器标签页/进程。
- 隔离的 cron 完成时，会尽最大努力在运行完全拆除之前关闭 cron 会话已跟踪的浏览器标签页/进程。
- 隔离的 cron 交付会在需要时等待后代子智能体后续工作完成，并抑制过时的父级确认文本，而不是将其公告出去。
- 子智能体完成交付时会优先选择最新的可见助手文本；如果该文本为空，则回退为清洗后的最新 tool/toolResult 文本，而仅包含超时工具调用的运行则可以折叠为简短的部分进度摘要。终态失败的运行会公告失败状态，而不会重放捕获到的回复文本。
- 清理失败不会掩盖真实的任务结果。
### `tasks flow list|show|cancel`
@ -237,87 +237,87 @@ openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
当你关心的是编排中的 Task Flow，而不是单个后台任务记录时，请使用这些命令。
当你关心的是编排中的 Task Flow，而不是某一条单独的后台任务记录时，请使用这些命令。
## 聊天任务面板（`/tasks`）
## 聊天任务看板（`/tasks`）
在任意聊天会话中使用 `/tasks`，可查看与该会话关联的后台任务。该面板会显示活动中和最近已完成的任务，包括运行时、状态、时间信息，以及进度或错误详情。
在任意聊天会话中使用 `/tasks`，即可查看与该会话关联的后台任务。该看板会显示活动中和最近完成的任务，包括运行时、状态、耗时，以及进度或错误详情。
当当前会话没有可见的关联任务时，`/tasks` 会回退为显示智能体本地任务计数，
这样你仍然可以获得概览，而不会泄露其他会话的详细信息。
当当前会话没有可见的关联任务时，`/tasks` 会回退为显示智能体本地的任务计数，
这样你仍然可以获得概览，而不会泄露其他会话的细节。
如需查看完整的操作员台账，请使用 CLI：`openclaw tasks list`。
## 状态集成（任务压力）
`openclaw status` 包含一个可快速查看的任务摘要：
`openclaw status` 包含一个可一眼看懂的任务摘要：
```
Tasks: 3 queued · 2 running · 1 issues
```
该摘要报告：
该摘要会报告：
- **active** —— `queued` + `running` 的数量
- **failures** —— `failed` + `timed_out` + `lost` 的数量
- **byRuntime** —— 按 `acp`、`subagent`、`cron`、`cli` 的细分统计
- **active** — `queued` + `running` 的数量
- **failures** — `failed` + `timed_out` + `lost` 的数量
- **byRuntime** — 按 `acp`、`subagent`、`cron`、`cli` 分类的明细
`/status` 和 `session_status` 工具都会使用带清理感知的任务快照：优先显示活动任务，隐藏陈旧的已完成记录，并且仅在没有活动工作剩余时才显示最近失败的任务。这样可以让状态卡聚焦于当前真正重要的内容。
`/status` 和 `session_status` 工具都使用具备清理感知能力的任务快照：优先显示活动任务，隐藏过时的已完成记录，只有在没有活动工作剩余时才显示最近的失败项。这样可以让状态卡片聚焦于当前真正重要的内容。
## 存储与维护
### 任务存储位置
任务记录持久化保存在以下 SQLite 路径中：
任务记录持久化存储在 SQLite 中，路径为：
```
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
注册表会在 Gateway 网关启动时加载到内存中，并将写入同步到 SQLite，以便在重启后仍能保持持久性。
注册表会在 Gateway 网关启动时加载到内存中，并将写入同步到 SQLite，以确保在重启后仍具备持久性。
### 自动维护
清扫器每 **60 秒** 运行一次，处理以下三件事：
清扫器每 **60 秒**运行一次，并处理三件事：
1. **对账** —— 检查活动任务是否仍有权威性的运行时支撑。ACP/子智能体任务使用子会话状态，cron 任务使用活动作业所有权，由聊天支持的 CLI 任务使用所属运行上下文。如果该支撑状态消失超过 5 分钟，任务会被标记为 `lost`。
2. **清理时间戳补写** —— 为终态任务设置 `cleanupAfter` 时间戳（`endedAt + 7 days`）。
3. **裁剪** —— 删除超过其 `cleanupAfter` 日期的记录。
1. **对账** —— 检查活动任务是否仍然有权威的运行时后备状态。ACP/子智能体任务使用子会话状态，cron 任务使用活动作业归属，而由聊天支持的 CLI 任务使用其所属运行上下文。如果该后备状态消失超过 5 分钟，任务会被标记为 `lost`。
2. **清理标记** —— 为终态任务设置 `cleanupAfter` 时间戳（`endedAt + 7 days`）。
3. **清除** —— 删除超过其 `cleanupAfter` 日期的记录。
**保留期**：终态任务记录会保留 **7 天**，之后自动清理。无需配置。
**保留期**：终态任务记录会保留 **7 天**，之后自动清除。无需配置。
## 任务与其他系统的关系
### 任务与 Task Flow
[Task Flow](/zh-CN/automation/taskflow) 是位于后台任务之上的流程编排层。单个 flow 在其生命周期内可能通过受管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单个任务记录，使用 `openclaw tasks flow` 检查编排中的 flow。
[Task Flow](/zh-CN/automation/taskflow) 是位于后台任务之上的流程编排层。单个 flow 在其生命周期内可以通过托管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单个任务记录，使用 `openclaw tasks flow` 检查负责编排的 flow。
详情请参阅 [Task Flow](/zh-CN/automation/taskflow)。
详见 [Task Flow](/zh-CN/automation/taskflow)。
### 任务与 cron
cron 作业**定义**保存在 `~/.openclaw/cron/jobs.json`；运行时执行状态保存在其旁边的 `~/.openclaw/cron/jobs-state.json` 中。**每一次** cron 执行都会创建一条任务记录——无论是主会话还是隔离式执行。主会话 cron 任务默认使用 `silent` 通知策略，因此它们会被跟踪，但不会生成通知。
cron 作业的**定义**位于 `~/.openclaw/cron/jobs.json`；运行时执行状态则位于同目录下的 `~/.openclaw/cron/jobs-state.json`。**每一次** cron 执行都会创建任务记录——无论是主会话还是隔离模式。主会话 cron 任务默认使用 `silent` 通知策略，因此它们会被跟踪，但不会生成通知。
请参阅 [Cron Jobs](/zh-CN/automation/cron-jobs)。
详见 [Cron Jobs](/zh-CN/automation/cron-jobs)。
### 任务与心跳
心跳运行属于主会话轮次——它们不会创建任务记录。当任务完成时，它可以触发一次心跳唤醒，以便你及时看到结果。
心跳运行属于主会话轮次——它们不会创建任务记录。当某个任务完成时，它可以触发一次心跳唤醒，以便你及时看到结果。
请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)。
详见 [Heartbeat](/zh-CN/gateway/heartbeat)。
### 任务与会话
一个任务可能会引用 `childSessionKey`（工作运行的位置）和 `requesterSessionKey`（发起它的人）。会话是对话上下文；任务是在其之上的活动跟踪。
一个任务可能会引用 `childSessionKey`（工作运行的位置）和 `requesterSessionKey`（是谁发起了它）。会话是对话上下文；任务则是在其之上的活动跟踪层。
### 任务与智能体运行
任务的 `runId` 会链接到执行该工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务状态——你无需手动管理生命周期。
任务的 `runId` 会链接到执行该工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务状态——你无需手动管理其生命周期。
## 相关内容
- [Automation & Tasks](/zh-CN/automation) —— 所有自动化机制总览
- [Automation & Tasks](/zh-CN/automation) —— 所有自动化机制一览
- [Task Flow](/zh-CN/automation/taskflow) —— 位于任务之上的流程编排
- [Scheduled Tasks](/zh-CN/automation/cron-jobs) —— 调度后台工作
- [Heartbeat](/zh-CN/gateway/heartbeat) —— 周期性的主会话轮次
- [CLI: Tasks](/cli/index#tasks) —— CLI 命令参考
- [CLI: Tasks](/cli/tasks) —— CLI 命令参考

19
docs/zh-CN/providers/index.md
View File

@ -5,10 +5,10 @@ read_when:
summary: OpenClaw 支持的模型提供商（LLM）
title: 提供商目录
x-i18n:
generated_at: "2026-04-23T02:13:10Z"
generated_at: "2026-04-23T05:40:53Z"
model: gpt-5.4
provider: openai
source_hash: bcef929e6757f18aad19b810426c49bdb273a9c65781bb3a21cc50d6d17014b5
source_hash: 5a62f8af86fa23f248163d1a23929c628f5bcc757366d0fdb12157f995f8024d
source_path: providers/index.md
workflow: 15
---
@ -17,7 +17,7 @@ x-i18n:
OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份验证，然后将默认模型设置为 `provider/model`。
在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/ 等）？请参见 [渠道](/zh-CN/channels)。
在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（plugin）/等）吗？请参阅 [Channels](/zh-CN/channels)。
## 快速开始
@ -32,8 +32,9 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
## 提供商文档
- [阿里巴巴 Model Studio](/zh-CN/providers/alibaba)
- [Alibaba Model Studio](/zh-CN/providers/alibaba)
- [Amazon Bedrock](/zh-CN/providers/bedrock)
- [Amazon Bedrock Mantle](/zh-CN/providers/bedrock-mantle)
- [Anthropic（API + Claude CLI）](/zh-CN/providers/anthropic)
- [Arcee AI（Trinity 模型）](/zh-CN/providers/arcee)
- [BytePlus（国际版）](/zh-CN/concepts/model-providers#byteplus-international)
@ -41,13 +42,14 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
- [Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)
- [ComfyUI](/zh-CN/providers/comfy)
- [DeepSeek](/zh-CN/providers/deepseek)
- [ElevenLabs](/zh-CN/providers/elevenlabs)
- [fal](/zh-CN/providers/fal)
- [Fireworks](/zh-CN/providers/fireworks)
- [GitHub Copilot](/zh-CN/providers/github-copilot)
- [GLM 模型](/zh-CN/providers/glm)
- [Google（Gemini）](/zh-CN/providers/google)
- [Groq（LPU 推理）](/zh-CN/providers/groq)
- [Hugging Face（推理）](/zh-CN/providers/huggingface)
- [Hugging Face（Inference）](/zh-CN/providers/huggingface)
- [inferrs（本地模型）](/zh-CN/providers/inferrs)
- [Kilocode](/zh-CN/providers/kilocode)
- [LiteLLM（统一 Gateway 网关）](/zh-CN/providers/litellm)
@ -69,7 +71,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
- [StepFun](/zh-CN/providers/stepfun)
- [Synthetic](/zh-CN/providers/synthetic)
- [Together AI](/zh-CN/providers/together)
- [Venice（Venice AI，以隐私为中心）](/zh-CN/providers/venice)
- [Venice（Venice AI，注重隐私）](/zh-CN/providers/venice)
- [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)
- [vLLM（本地模型）](/zh-CN/providers/vllm)
- [Volcengine（Doubao）](/zh-CN/providers/volcengine)
@ -95,7 +97,6 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
## 社区工具
- [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请核实 Anthropic 的政策/条款）
- [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请确认 Anthropic 的政策/条款）
如需查看完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，
请参见 [模型提供商](/zh-CN/concepts/model-providers)。
如需查看完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。

20
docs/zh-CN/providers/models.md
View File

@ -1,25 +1,25 @@
---
read_when:
- 你想选择一个模型提供商
- 你想查看 LLM 认证 + 模型选择的快速设置示例
- 你想查看 LLM 身份验证 + 模型选择的快速设置示例
summary: OpenClaw 支持的模型提供商（LLM）
title: 模型提供商快速开始
x-i18n:
generated_at: "2026-04-07T09:37:22Z"
generated_at: "2026-04-23T05:40:53Z"
model: gpt-5.4
provider: openai
source_hash: 59ee4c2f993fe0ae05fe34f52bc6f3e0fc9a76b10760f56b20ad251e25ee9f20
source_hash: 9b002903bd0a1872e77d871f283ae426c74356936c5776c710711d7328427fca
source_path: providers/models.md
workflow: 15
---
# 模型提供商
OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证，然后将默认模型设置为 `provider/model`。
OpenClaw 可以使用许多 LLM 提供商。选择一个，完成身份验证，然后将默认模型设置为 `provider/model`。
## 快速开始（两步）
1. 使用提供商完成认证（通常通过 `openclaw onboard`）。
1. 使用提供商完成身份验证（通常通过 `openclaw onboard`）。
2. 设置默认模型：
```json5
@ -30,9 +30,9 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证
## 支持的提供商（入门集合）
- [Alibaba Model Studio](/zh-CN/providers/alibaba)
- [Anthropic（API + Claude CLI）](/zh-CN/providers/anthropic)
- [阿里云百炼](/zh-CN/providers/alibaba)
- [Amazon Bedrock](/zh-CN/providers/bedrock)
- [Anthropic（API + Claude CLI）](/zh-CN/providers/anthropic)
- [BytePlus（国际版）](/zh-CN/concepts/model-providers#byteplus-international)
- [Chutes](/zh-CN/providers/chutes)
- [ComfyUI](/zh-CN/providers/comfy)
@ -56,10 +56,10 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证
- [xAI](/zh-CN/providers/xai)
- [Z.AI](/zh-CN/providers/zai)
## 其他内置变体
## 其他内置提供商变体
- `anthropic-vertex` - 当 Vertex 凭证可用时，隐式支持 Google Vertex 上的 Anthropic；没有单独的新手引导认证选项
- `anthropic-vertex` - 当 Vertex 凭证可用时，隐式支持 Google Vertex 上的 Anthropic；无需单独选择新手引导身份验证选项
- `copilot-proxy` - 本地 VS Code Copilot Proxy 桥接；使用 `openclaw onboard --auth-choice copilot-proxy`
- `google-gemini-cli` - 非官方的 Gemini CLI OAuth 流程；需要本地安装 `gemini`（`brew install gemini-cli` 或 `npm install -g @google/gemini-cli`）；默认模型为 `google-gemini-cli/gemini-3-flash-preview`；使用 `openclaw onboard --auth-choice google-gemini-cli` 或 `openclaw models auth login --provider google-gemini-cli --set-default`
如需查看完整的提供商目录（xAI、Groq、Mistral 等）以及高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。
有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，参见 [模型提供商](/zh-CN/concepts/model-providers)。

132
docs/zh-CN/tools/plugin.md
View File

@ -7,17 +7,17 @@ sidebarTitle: Install and Configure
summary: 安装、配置和管理 OpenClaw 插件
title: 插件
x-i18n:
generated_at: "2026-04-23T00:37:18Z"
generated_at: "2026-04-23T05:40:51Z"
model: gpt-5.4
provider: openai
source_hash: 120c96e5b80b6dc9f6c842f9d04ada595f32e21a311128ae053828747a793033
source_hash: fb81789de548aed0cd0404e8c42a2d9ce00d0e9163f944e07237b164d829ac40
source_path: tools/plugin.md
workflow: 15
---
# 插件
插件可为 OpenClaw 扩展新能力：渠道、模型提供商、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起提供），另一些则是**外部**插件（由社区发布到 npm）。
插件通过提供新能力来扩展 OpenClaw：渠道、模型提供商、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是 **核心** 插件（随 OpenClaw 一起提供），另一些是 **外部** 插件（由社区发布到 npm）。
## 快速开始
@ -45,12 +45,12 @@ x-i18n:
openclaw gateway restart
```
然后在你的配置文件中通过 `plugins.entries.\<id\>.config` 进行配置。
然后在你的配置文件中，通过 `plugins.entries.\<id\>.config` 进行配置。
</Step>
</Steps>
如果你更喜欢聊天原生控制方式，请启用 `commands.plugins: true`，然后使用：
如果你更喜欢在聊天中直接控制，请启用 `commands.plugins: true` 并使用：
```text
/plugin install clawhub:@openclaw/voice-call
@ -58,11 +58,11 @@ x-i18n:
/plugin enable voice-call
```
安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:<pkg>`，或裸包规范（优先 ClawHub，其次回退到 npm）。
安装路径使用与 CLI 相同的解析器：本地路径 / 归档文件、显式 `clawhub:<pkg>`，或裸包规范（优先 ClawHub，然后回退到 npm）。
如果配置无效，安装通常会以关闭失败的方式结束，并引导你运行 `openclaw doctor --fix`。唯一的恢复例外是针对选择启用 `openclaw.install.allowInvalidConfigRecovery` 的插件，提供一条范围很窄的内置插件重新安装路径。
如果配置无效，安装通常会以安全失败方式结束，并提示你运行 `openclaw doctor --fix`。唯一的恢复例外，是针对选择启用 `openclaw.install.allowInvalidConfigRecovery` 的插件，提供了一条受限的内置插件重新安装路径。
打包分发的 OpenClaw 安装不会急切安装每个内置插件的运行时依赖树。当某个由 OpenClaw 自有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于活动状态时，启动修复只会在导入该插件前修复它声明的运行时依赖。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。
打包分发的 OpenClaw 安装不会预先安装每个内置插件的全部运行时依赖树。当某个 OpenClaw 自带的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于活动状态时，启动修复只会在导入该插件前修复它声明的运行时依赖。外部插件和自定义加载路径仍然必须通过 `openclaw plugins install` 安装。
## 插件类型
@ -71,11 +71,11 @@ OpenClaw 可识别两种插件格式：
| 格式 | 工作方式 | 示例 |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
| **Bundle** | 兼容 Codex/Claude/Cursor 的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
两者都会显示在 `openclaw plugins list` 中。有关 Bundle 详情，请参阅 [Plugin Bundles](/zh-CN/plugins/bundles)。
两种格式都会显示在 `openclaw plugins list` 中。有关 Bundle 的详细信息，请参阅 [插件 Bundle](/zh-CN/plugins/bundles)。
如果你正在编写原生插件，请先阅读 [Building Plugins](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
如果你要编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
## 官方插件
@ -101,9 +101,9 @@ OpenClaw 可识别两种插件格式：
`vercel-ai-gateway`、`volcengine`、`xiaomi`、`zai`
</Accordion>
<Accordion title="内存插件">
<Accordion title="Memory 插件">
- `memory-core` — 内置内存搜索（默认通过 `plugins.slots.memory` 使用）
- `memory-lancedb` — 按需安装的长期记忆，支持自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
- `memory-lancedb` — 按需安装的长期记忆，带自动回忆 / 捕获功能（设置 `plugins.slots.memory = "memory-lancedb"`）
</Accordion>
<Accordion title="语音提供商（默认启用）">
@ -111,12 +111,12 @@ OpenClaw 可识别两种插件格式：
</Accordion>
<Accordion title="其他">
- `browser` — 内置浏览器插件，用于 browser 工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时，以及默认浏览器控制服务（默认启用；替换它之前请先禁用）
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用）
- `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用）
</Accordion>
</AccordionGroup>
在找第三方插件？请参阅 [Community Plugins](/zh-CN/plugins/community)。
在找第三方插件？请参阅 [社区插件](/zh-CN/plugins/community)。
## 配置
@ -134,56 +134,56 @@ OpenClaw 可识别两种插件格式：
}
```
| 字段 | 说明 |
| 字段 | 描述 |
| ---------------- | --------------------------------------------------------- |
| `enabled` | 主开关（默认：`true`） |
| `allow` | 插件允许列表（可选） |
| `deny` | 插件拒绝列表（可选；拒绝优先生效） |
| `load.paths` | 额外插件文件/目录 |
| `slots` | 独占插槽选择器（例如 `memory`、`contextEngine`） |
| `deny` | 插件拒绝列表（可选；拒绝优先） |
| `load.paths` | 额外的插件文件 / 目录 |
| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） |
| `entries.\<id\>` | 每个插件的开关 + 配置 |
配置变更**需要重启 Gateway 网关**。如果 Gateway 网关正以启用配置监听和进程内重启的方式运行（默认的 `openclaw gateway` 路径），则通常会在配置写入后不久自动执行该重启。
配置更改 **需要重启 Gateway 网关**。如果 Gateway 网关正在以启用配置监视和进程内重启的方式运行（默认的 `openclaw gateway` 路径），那么在配置写入完成后，通常会自动在稍后片刻执行重启。
<Accordion title="插件状态：已禁用、缺失、无效">
- **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。
- **缺失**：配置引用了某个插件 id，但在发现阶段未找到该插件。
- **已禁用**：插件存在，但被启用规则关闭。配置会被保留。
- **缺失**：配置引用了某个插件 ID，但在发现过程中未找到。
- **无效**：插件存在，但其配置与声明的 schema 不匹配。
</Accordion>
## 发现顺序与优先级
## 发现与优先级
OpenClaw 按以下顺序扫描插件（先匹配者优先）：
OpenClaw 按以下顺序扫描插件（先匹配者胜出）：
<Steps>
<Step title="配置路径">
`plugins.load.paths` — 显式文件或目录路径。
</Step>
<Step title="工作区扩展">
<Step title="工作区插件">
`\<workspace\>/.openclaw/<plugin-root>/*.ts` 和 `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`。
</Step>
<Step title="全局扩展">
<Step title="全局插件">
`~/.openclaw/<plugin-root>/*.ts` 和 `~/.openclaw/<plugin-root>/*/index.ts`。
</Step>
<Step title="内置插件">
随 OpenClaw 一起提供。许多默认启用（模型提供商、语音）。
其他则需要显式启用。
随 OpenClaw 一起提供。许多默认启用（模型提供商、语音等）。
其他插件则需要显式启用。
</Step>
</Steps>
### 启用规则
- `plugins.enabled: false` 会禁用所有插件
- `plugins.deny` 始终优先于 allow
- `plugins.deny` 总是优先于 allow
- `plugins.entries.\<id\>.enabled: false` 会禁用该插件
- 来自工作区的插件**默认禁用**（必须显式启用）
- 来源于工作区的插件 **默认禁用**（必须显式启用）
- 内置插件遵循内建的默认启用集合，除非被覆盖
- 独占插槽可为该插槽中被选中的插件强制启用
- 独占槽位可以为该槽位强制启用所选插件
## 插件插槽（独占类别）
## 插件槽位（独占类别）
某些类别是独占的（同一时间只能有一个处于活动状态）：
@ -191,32 +191,32 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）：
{
plugins: {
slots: {
memory: "memory-core", // 或 "none" 以禁用
memory: "memory-core", // 或 "none" 表示禁用
contextEngine: "legacy", // 或某个插件 id
},
},
}
```
| 插槽 | 控制内容 | 默认值 |
| 槽位 | 控制内容 | 默认值 |
| --------------- | --------------------- | ------------------- |
| `memory` | 活动内存插件 | `memory-core` |
| `contextEngine` | 活动上下文引擎 | `legacy`（内建） |
| `memory` | 活动的内存插件 | `memory-core` |
| `contextEngine` | 活动的上下文引擎 | `legacy`（内建） |
## CLI 参考
```bash
openclaw plugins list # 精简清单
openclaw plugins list # 简明清单
openclaw plugins list --enabled # 仅显示已加载插件
openclaw plugins list --verbose # 每个插件的详细信息行
openclaw plugins list --json # 机器可读清单
openclaw plugins inspect <id> # 深度详情
openclaw plugins inspect <id> --json # 机器可读
openclaw plugins inspect --all # 全量表格
openclaw plugins info <id> # inspect 的别名
openclaw plugins inspect --all # 整体范围表格
openclaw plugins info <id> # inspect 别名
openclaw plugins doctor # 诊断
openclaw plugins install <package> # 安装（优先 ClawHub，其次 npm）
openclaw plugins install <package> # 安装（优先 ClawHub，然后 npm）
openclaw plugins install clawhub:<pkg> # 仅从 ClawHub 安装
openclaw plugins install <spec> --force # 覆盖现有安装
openclaw plugins install <path> # 从本地路径安装
@ -228,7 +228,7 @@ openclaw plugins install <spec> --dangerously-force-unsafe-install
openclaw plugins update <id-or-npm-spec> # 更新单个插件
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
openclaw plugins update --all # 更新全部
openclaw plugins uninstall <id> # 删除配置/安装记录
openclaw plugins uninstall <id> # 删除配置 / 安装记录
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
@ -237,25 +237,25 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
内置插件随 OpenClaw 一起提供。许多默认启用（例如内置模型提供商、内置语音提供商，以及内置浏览器插件）。其他内置插件仍然需要 `openclaw plugins enable <id>`。
内置插件随 OpenClaw 一起提供。许多插件默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）。其他内置插件仍然需要执行 `openclaw plugins enable <id>`。
`--force` 会原地覆盖现有已安装插件或 hook 包。对于已跟踪的 npm 插件，日常升级请使用 `openclaw plugins update <id-or-npm-spec>`。该选项不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到受管理的安装目标。
`--force` 会原地覆盖现有已安装的插件或 hook 包。对于已跟踪的 npm 插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到受管理的安装目标。
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包规范时，会将包名解析回已跟踪的插件记录，并为未来更新记录新的规范。传入不带版本的包名时，会将一个精确固定版本的安装移回该注册表的默认发布线。如果已安装的 npm 插件已匹配解析出的版本和记录的制品标识，OpenClaw 会跳过更新，而不会下载、重新安装或重写配置。
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包规范时，会把包名解析回已跟踪的插件记录，并记录新的规范以供后续更新。传入不带版本的包名时，会将精确固定版本的安装切回注册表默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的制品标识，OpenClaw 会跳过更新，而不会下载、重新安装或重写配置。
`--pin` 仅适用于 npm。不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 规范。
`--dangerously-force-unsafe-install` 是用于处理内置危险代码扫描器误报的“破窗”覆盖选项。它允许插件安装和插件更新在遇到内置 `critical` 级别发现后继续进行，但仍不会绕过插件 `before_install` 策略阻止或扫描失败阻止。
`--dangerously-force-unsafe-install` 是一种紧急覆盖选项，用于处理内置危险代码扫描器的误报。它允许插件安装和插件更新在遇到内置 `critical` 发现后继续进行，但仍然不会绕过插件 `before_install` 策略阻止或扫描失败阻止。
这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skill 依赖安装则改用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是单独的 ClawHub Skill 下载/安装流程。
此 CLI 标志仅适用于插件安装 / 更新流程。由 Gateway 网关支持的 Skills 依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖；而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载 / 安装流程。
兼容的 Bundle 会参与相同的插件 list/inspect/enable/disable 流程。当前运行时支持包括 Bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 以及清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
兼容的 Bundle 会参与相同的插件 list / inspect / enable / disable 流程。当前运行时支持包括 Bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
`openclaw plugins inspect <id>` 还会报告检测到的 Bundle 能力，以及对由 Bundle 支持的插件而言受支持或不受支持的 MCP 和 LSP 服务器条目。
`openclaw plugins inspect <id>` 还会报告检测到的 Bundle 能力，以及对于基于 Bundle 的插件所支持或不支持的 MCP 和 LSP 服务器条目。
Marketplace 来源可以是 Claude 已知 marketplace 名称（来自 `~/.claude/plugins/known_marketplaces.json`）、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保持在已克隆的 marketplace 仓库内，并且只能使用相对路径来源。
Marketplace 来源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保持在克隆出的 marketplace 仓库内，并且只能使用相对路径来源。
有关完整详情，请参阅 [`openclaw plugins` CLI 参考](/cli/plugins)。
有关完整细节，请参阅 [`openclaw plugins` CLI 参考](/cli/plugins)。
## 插件 API 概览
@ -279,7 +279,7 @@ export default definePluginEntry({
});
```
OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。对于较旧的插件，加载器仍会回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公开契约。
常见注册方法：
@ -288,11 +288,11 @@ OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api
| `registerProvider` | 模型提供商（LLM） |
| `registerChannel` | 聊天渠道 |
| `registerTool` | 智能体工具 |
| `registerHook` / `on(...)` | 生命周期 hooks |
| `registerHook` / `on(...)` | 生命周期 hook |
| `registerSpeechProvider` | 文本转语音 / STT |
| `registerRealtimeTranscriptionProvider` | 流式 STT |
| `registerRealtimeVoiceProvider` | 双向实时语音 |
| `registerMediaUnderstandingProvider` | 图像/音频分析 |
| `registerMediaUnderstandingProvider` | 图像 / 音频分析 |
| `registerImageGenerationProvider` | 图像生成 |
| `registerMusicGenerationProvider` | 音乐生成 |
| `registerVideoGenerationProvider` | 视频生成 |
@ -303,22 +303,22 @@ OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api
| `registerContextEngine` | 上下文引擎 |
| `registerService` | 后台服务 |
类型化生命周期 hooks 的 hook 守卫行为：
类型化生命周期 hook 的守卫行为：
- `before_tool_call`：`{ block: true }` 为终止性结果；会跳过更低优先级的处理器。
- `before_tool_call`：`{ block: false }` 为 no-op，不会清除更早的阻止结果。
- `before_install`：`{ block: true }` 为终止性结果；会跳过更低优先级的处理器。
- `before_install`：`{ block: false }` 为 no-op，不会清除更早的阻止结果。
- `message_sending`：`{ cancel: true }` 为终止性结果；会跳过更低优先级的处理器。
- `message_sending`：`{ cancel: false }` 为 no-op，不会清除更早的取消结果。
- `before_tool_call`：`{ block: true }` 为终止结果；较低优先级的处理器会被跳过。
- `before_tool_call`：`{ block: false }` 是空操作，不会清除先前的阻止。
- `before_install`：`{ block: true }` 为终止结果；较低优先级的处理器会被跳过。
- `before_install`：`{ block: false }` 是空操作，不会清除先前的阻止。
- `message_sending`：`{ cancel: true }` 为终止结果；较低优先级的处理器会被跳过。
- `message_sending`：`{ cancel: false }` 是空操作，不会清除先前的取消。
有关完整的类型化 hook 行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
## 相关内容
- [Building Plugins](/zh-CN/plugins/building-plugins) — 创建你自己的插件
- [Plugin Bundles](/zh-CN/plugins/bundles) — Codex/Claude/Cursor Bundle 兼容性
- [Plugin Manifest](/zh-CN/plugins/manifest) — 清单 schema
- [Registering Tools](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
- [Plugin Internals](/zh-CN/plugins/architecture) — 能力模型和加载流水线
- [Community Plugins](/zh-CN/plugins/community) — 第三方列表
- [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件
- [插件 Bundle](/zh-CN/plugins/bundles) — Codex/Claude/Cursor Bundle 兼容性
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema
- [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线
- [社区插件](/zh-CN/plugins/community) — 第三方列表