diff --git a/docs/zh-CN/automation/hooks.md b/docs/zh-CN/automation/hooks.md index 834bd82aa..9c68821fb 100644 --- a/docs/zh-CN/automation/hooks.md +++ b/docs/zh-CN/automation/hooks.md @@ -1,37 +1,37 @@ --- read_when: - - 你希望为 `/new`、`/reset`、`/stop` 以及智能体生命周期事件提供事件驱动自动化功能 - - 你希望构建、安装或调试 hooks -summary: Hooks：用于命令和生命周期事件的事件驱动自动化 -title: Hooks + - 你希望为 `/new`、`/reset`、`/stop` 和智能体生命周期事件提供事件驱动自动化功能 + - 你想要构建、安装或调试钩子 +summary: 钩子：用于命令和生命周期事件的事件驱动自动化 +title: 钩子 x-i18n: - generated_at: "2026-04-24T07:31:18Z" + generated_at: "2026-04-24T17:31:10Z" model: gpt-5.4 provider: openai - source_hash: 4e6246f25272208d9a9ff2f186bcd3a463c78ea24b833f0259174d0f7f0cbea6 + source_hash: 437b8b8dc37e9ec9c10bbdddc4d63184ccc46e89bc532aea0c5bd176404186f6 source_path: automation/hooks.md workflow: 15 --- -Hooks 是在 Gateway 网关内部发生某些事件时运行的小型脚本。它们可以从目录中被发现，并可通过 `openclaw hooks` 进行检查。只有在你启用 hooks，或至少配置了一个 hook 条目、hook pack、旧版处理器或额外 hook 目录后，Gateway 网关才会加载内部 hooks。 +钩子是在 Gateway 网关内部发生某些事件时运行的小型脚本。你可以从目录中发现它们，并使用 `openclaw hooks` 查看。只有在你启用钩子，或至少配置了一个钩子条目、hook pack、旧版处理器或额外钩子目录后，Gateway 网关才会加载内部钩子。 -OpenClaw 中有两类 hooks： +OpenClaw 中有两种钩子： -- **内部 hooks**（本页）：当智能体事件触发时，在 Gateway 网关内部运行，例如 `/new`、`/reset`、`/stop` 或生命周期事件。 -- **Webhooks**：外部 HTTP 端点，允许其他系统在 OpenClaw 中触发工作流。参见 [Webhooks](/zh-CN/automation/cron-jobs#webhooks)。 +- **内部钩子**（本页）：在 Gateway 网关内部运行，当智能体事件触发时执行，例如 `/new`、`/reset`、`/stop` 或生命周期事件。 +- **Webhooks**：外部 HTTP 端点，可让其他系统在 OpenClaw 中触发工作。请参阅 [Webhooks](/zh-CN/automation/cron-jobs#webhooks)。 -Hooks 也可以打包在插件中。`openclaw hooks list` 会同时显示独立 hooks 和由插件管理的 hooks。 +钩子也可以内置在插件中。`openclaw hooks list` 会同时显示独立钩子和由插件管理的钩子。 ## 快速开始 ```bash -# 列出可用 hooks +# 列出可用钩子 openclaw hooks list -# 启用一个 hook +# 启用一个钩子 openclaw hooks enable session-memory -# 检查 hook 状态 +# 检查钩子状态 openclaw hooks check # 获取详细信息 @@ -42,25 +42,25 @@ openclaw hooks info session-memory | 事件 | 触发时机 | | ------------------------ | ------------------------------------------------ | -| `command:new` | 发出 `/new` 命令时 | -| `command:reset` | 发出 `/reset` 命令时 | -| `command:stop` | 发出 `/stop` 命令时 | -| `command` | 任意命令事件（通用监听器） | -| `session:compact:before` | 在压缩汇总历史记录之前 | -| `session:compact:after` | 压缩完成之后 | -| `session:patch` | 修改会话属性时 | -| `agent:bootstrap` | 注入工作区 bootstrap 文件之前 | -| `gateway:startup` | 渠道启动并加载 hooks 之后 | -| `message:received` | 从任意渠道接收到入站消息时 | -| `message:transcribed` | 音频转写完成后 | -| `message:preprocessed` | 所有媒体和链接理解完成后 | -| `message:sent` | 出站消息已送达时 | +| `command:new` | 发出 `/new` 命令时 | +| `command:reset` | 发出 `/reset` 命令时 | +| `command:stop` | 发出 `/stop` 命令时 | +| `command` | 任意命令事件（通用监听器） | +| `session:compact:before` | 压缩在汇总历史记录之前 | +| `session:compact:after` | 压缩完成之后 | +| `session:patch` | 修改会话属性时 | +| `agent:bootstrap` | 注入工作区引导文件之前 | +| `gateway:startup` | 渠道启动且钩子已加载之后 | +| `message:received` | 来自任意渠道的入站消息 | +| `message:transcribed` | 音频转录完成之后 | +| `message:preprocessed` | 所有媒体和链接理解完成之后 | +| `message:sent` | 出站消息已送达 | -## 编写 hooks +## 编写钩子 -### Hook 结构 +### 钩子结构 -每个 hook 都是一个包含两个文件的目录： +每个钩子都是一个包含两个文件的目录： ``` my-hook/ @@ -68,32 +68,32 @@ my-hook/ └── handler.ts # 处理器实现 ``` -### `HOOK.md` 格式 +### HOOK.md 格式 ```markdown --- name: my-hook -description: "这个 hook 的简短说明" +description: "这个钩子的功能简要说明" metadata: { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } } --- -# 我的 Hook +# 我的钩子 -此处填写详细文档。 +详细文档写在这里。 ``` **元数据字段**（`metadata.openclaw`）： | 字段 | 说明 | | ---------- | ---------------------------------------------------- | -| `emoji` | CLI 中显示的 emoji | -| `events` | 要监听的事件数组 | -| `export` | 要使用的具名导出（默认为 `"default"`） | -| `os` | 所需平台（例如 `["darwin", "linux"]`） | +| `emoji` | 用于 CLI 显示的表情符号 | +| `events` | 要监听的事件数组 | +| `export` | 要使用的具名导出（默认是 `"default"`） | +| `os` | 所需平台（例如 `["darwin", "linux"]`） | | `requires` | 所需的 `bins`、`anyBins`、`env` 或 `config` 路径 | -| `always` | 跳过资格检查（布尔值） | -| `install` | 安装方式 | +| `always` | 绕过资格检查（布尔值） | +| `install` | 安装方法 | ### 处理器实现 @@ -113,7 +113,7 @@ const handler = async (event) => { export default handler; ``` -每个事件都包含：`type`、`action`、`sessionKey`、`timestamp`、`messages`（可 `push` 以向用户发送消息）以及 `context`（事件特定数据）。智能体和工具插件 hook 的上下文还可以包含 `trace`，这是一个只读、兼容 W3C 的诊断追踪上下文，插件可以将其传入结构化日志中，以便进行 OTEL 关联。 +每个事件都包含：`type`、`action`、`sessionKey`、`timestamp`、`messages`（可 push 以向用户发送消息）以及 `context`（特定于事件的数据）。智能体和工具插件钩子的上下文还可能包含 `trace`，这是一个只读且兼容 W3C 的诊断追踪上下文，插件可将其传递到结构化日志中，以便进行 OTEL 关联。 ### 事件上下文要点 @@ -127,45 +127,45 @@ export default handler; **消息事件**（`message:preprocessed`）：`context.bodyForAgent`（最终增强后的正文）、`context.from`、`context.channelId`。 -**Bootstrap 事件**（`agent:bootstrap`）：`context.bootstrapFiles`（可变数组）、`context.agentId`。 +**引导事件**（`agent:bootstrap`）：`context.bootstrapFiles`（可变数组）、`context.agentId`。 -**会话 patch 事件**（`session:patch`）：`context.sessionEntry`、`context.patch`（仅包含变更字段）、`context.cfg`。只有特权客户端可以触发 patch 事件。 +**会话补丁事件**（`session:patch`）：`context.sessionEntry`、`context.patch`（仅包含变更字段）、`context.cfg`。只有特权客户端才能触发补丁事件。 -**压缩事件**：`session:compact:before` 包含 `messageCount`、`tokenCount`。`session:compact:after` 额外包含 `compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`。 +**压缩事件**：`session:compact:before` 包含 `messageCount`、`tokenCount`。`session:compact:after` 还会增加 `compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`。 -## Hook 发现机制 +## 钩子发现 -Hooks 会从以下目录中发现，覆盖优先级按从低到高排序： +系统会按以下目录发现钩子，并按覆盖优先级从低到高排序： -1. **内置 hooks**：随 OpenClaw 一起发布 -2. **插件 hooks**：打包在已安装插件中的 hooks -3. **受管 hooks**：`~/.openclaw/hooks/`（用户安装，在各工作区间共享）。来自 `hooks.internal.load.extraDirs` 的额外目录与此具有相同优先级。 -4. **工作区 hooks**：`/hooks/`（每个智能体单独使用，默认禁用，需显式启用） +1. **内置钩子**：随 OpenClaw 一起提供 +2. **插件钩子**：内置在已安装插件中的钩子 +3. **托管钩子**：`~/.openclaw/hooks/`（用户安装，在各工作区之间共享）。`hooks.internal.load.extraDirs` 中的额外目录具有相同优先级。 +4. **工作区钩子**：`/hooks/`（每个智能体独有，默认禁用，需显式启用） -工作区 hooks 可以新增新的 hook 名称，但不能覆盖同名的内置、受管或插件提供的 hooks。 +工作区钩子可以添加新的钩子名称，但不能覆盖同名的内置钩子、托管钩子或插件提供的钩子。 -在启动时，除非已配置内部 hooks，否则 Gateway 网关会跳过内部 hook 发现。你可以通过 `openclaw hooks enable ` 启用一个内置或受管 hook、安装一个 hook pack，或设置 `hooks.internal.enabled=true` 来选择启用。当你启用一个具名 hook 时，Gateway 网关只会加载该 hook 的处理器；而 `hooks.internal.enabled=true`、额外 hook 目录和旧版处理器则会启用广泛发现。 +在内部钩子配置完成之前，Gateway 网关会在启动时跳过内部钩子发现。你可以使用 `openclaw hooks enable ` 启用一个内置或托管钩子、安装一个 hook pack，或设置 `hooks.internal.enabled=true` 来选择启用。当你启用一个具名钩子时，Gateway 网关只会加载该钩子的处理器；而 `hooks.internal.enabled=true`、额外钩子目录和旧版处理器则会启用广泛发现。 ### Hook packs -Hook packs 是通过 `package.json` 中的 `openclaw.hooks` 导出 hooks 的 npm 包。安装方式： +Hook pack 是通过 `package.json` 中的 `openclaw.hooks` 导出钩子的 npm 包。安装方式如下： ```bash openclaw plugins install ``` -npm spec 仅支持 registry 形式（包名 + 可选的精确版本或 dist-tag）。Git/URL/file 形式的 spec 和 semver 范围都会被拒绝。 +npm 规格仅支持注册表来源（包名 + 可选的精确版本或 dist-tag）。Git/URL/file 规格和 semver 范围会被拒绝。 -## 内置 hooks +## 内置钩子 -| Hook | 事件 | 功能 | +| 钩子 | 事件 | 功能 | | --------------------- | ------------------------------ | ----------------------------------------------------- | -| session-memory | `command:new`, `command:reset` | 将会话上下文保存到 `/memory/` | -| bootstrap-extra-files | `agent:bootstrap` | 从 glob 模式中注入额外的 bootstrap 文件 | -| command-logger | `command` | 将所有命令记录到 `~/.openclaw/logs/commands.log` | -| boot-md | `gateway:startup` | 在 gateway 启动时运行 `BOOT.md` | +| session-memory | `command:new`, `command:reset` | 将会话上下文保存到 `/memory/` | +| bootstrap-extra-files | `agent:bootstrap` | 从 glob 模式注入额外的引导文件 | +| command-logger | `command` | 将所有命令记录到 `~/.openclaw/logs/commands.log` | +| boot-md | `gateway:startup` | 在 gateway 启动时运行 `BOOT.md` | -启用任意内置 hook： +启用任意内置钩子： ```bash openclaw hooks enable @@ -175,7 +175,7 @@ openclaw hooks enable ### session-memory 详情 -提取最近 15 条用户/助手消息，通过 LLM 生成一个描述性文件名 slug，并保存到 `/memory/YYYY-MM-DD-slug.md`。要求已配置 `workspace.dir`。 +提取最近 15 条用户/助手消息，通过 LLM 生成描述性文件名 slug，并保存到 `/memory/YYYY-MM-DD-slug.md`。要求已配置 `workspace.dir`。 @@ -196,7 +196,7 @@ openclaw hooks enable } ``` -路径相对于工作区解析。只会加载已识别的 bootstrap 基础文件名（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。 +路径相对于工作区解析。仅会加载已识别的引导基础文件名（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。 @@ -208,13 +208,16 @@ openclaw hooks enable ### boot-md 详情 -在 gateway 启动时，从当前工作区运行 `BOOT.md`。 +在 gateway 启动时，从当前活动工作区运行 `BOOT.md`。 -## 插件 hooks +## 插件钩子 -插件可以通过插件 SDK 注册 hooks，以实现更深入的集成：拦截工具调用、修改提示词、控制消息流等等。插件 SDK 暴露了 28 个 hooks，覆盖模型解析、智能体生命周期、消息流、工具执行、子智能体协作和 gateway 生命周期。 +插件可以通过 插件 SDK 注册类型化钩子，以实现更深层的集成： +拦截工具调用、修改提示词、控制消息流等。 +当你需要 `before_tool_call`、`before_agent_reply`、 +`before_install` 或其他进程内生命周期钩子时，请使用插件钩子。 -完整的插件 hook 参考，包括 `before_tool_call`、`before_agent_reply`、`before_install` 以及所有其他插件 hooks，请参见 [Plugin Architecture](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 +完整的插件钩子参考，请参阅 [插件钩子](/zh-CN/plugins/hooks)。 ## 配置 @@ -232,7 +235,7 @@ openclaw hooks enable } ``` -每个 hook 的环境变量： +每个钩子的环境变量： ```json { @@ -249,7 +252,7 @@ openclaw hooks enable } ``` -额外 hook 目录： +额外钩子目录： ```json { @@ -264,16 +267,16 @@ openclaw hooks enable ``` -旧版 `hooks.internal.handlers` 数组配置格式仍然受支持，以保持向后兼容，但新的 hooks 应使用基于发现的系统。 +旧版 `hooks.internal.handlers` 数组配置格式仍然支持，以保持向后兼容，但新钩子应使用基于发现的系统。 ## CLI 参考 ```bash -# 列出所有 hooks（可添加 --eligible、--verbose 或 --json） +# 列出所有钩子（可添加 --eligible、--verbose 或 --json） openclaw hooks list -# 显示某个 hook 的详细信息 +# 显示某个钩子的详细信息 openclaw hooks info # 显示资格摘要 @@ -286,25 +289,25 @@ openclaw hooks disable ## 最佳实践 -- **保持处理器快速。** Hooks 会在命令处理期间运行。对于较重的工作，可使用 `void processInBackground(event)` 以即发即弃方式处理。 -- **优雅地处理错误。** 用 try/catch 包裹高风险操作；不要抛出异常，以便其他处理器仍可继续运行。 -- **尽早过滤事件。** 如果事件类型/动作不相关，立即返回。 -- **使用具体事件键。** 优先使用 `"events": ["command:new"]` 而不是 `"events": ["command"]`，以减少开销。 +- **保持处理器快速。** 钩子会在命令处理期间运行。对于耗时任务，请使用 `void processInBackground(event)` 以即发即弃方式处理。 +- **优雅地处理错误。** 将有风险的操作包裹在 try/catch 中；不要抛出异常，以便其他处理器仍可运行。 +- **尽早过滤事件。** 如果事件类型/操作无关，请立即返回。 +- **使用具体事件键。** 优先使用 `"events": ["command:new"]`，而不是 `"events": ["command"]`，以减少开销。 ## 故障排除 -### Hook 未被发现 +### 钩子未被发现 ```bash # 验证目录结构 ls -la ~/.openclaw/hooks/my-hook/ # 应显示：HOOK.md, handler.ts -# 列出所有已发现的 hooks +# 列出所有已发现的钩子 openclaw hooks list ``` -### Hook 不符合资格 +### 钩子不符合条件 ```bash openclaw hooks info my-hook @@ -312,15 +315,15 @@ openclaw hooks info my-hook 检查是否缺少二进制文件（PATH）、环境变量、配置值或操作系统兼容性。 -### Hook 未执行 +### 钩子未执行 -1. 确认 hook 已启用：`openclaw hooks list` -2. 重启你的 gateway 进程，以便重新加载 hooks。 +1. 验证钩子已启用：`openclaw hooks list` +2. 重启你的 gateway 进程，以便重新加载钩子。 3. 检查 gateway 日志：`./scripts/clawlog.sh | grep hook` ## 相关内容 -- [CLI Reference: hooks](/zh-CN/cli/hooks) +- [CLI 参考：hooks](/zh-CN/cli/hooks) - [Webhooks](/zh-CN/automation/cron-jobs#webhooks) -- [Plugin Architecture](/zh-CN/plugins/architecture-internals#provider-runtime-hooks) — 完整插件 hook 参考 -- [Configuration](/zh-CN/gateway/configuration-reference#hooks) +- [插件钩子](/zh-CN/plugins/hooks) — 进程内插件生命周期钩子 +- [配置](/zh-CN/gateway/configuration-reference#hooks) diff --git a/docs/zh-CN/automation/index.md b/docs/zh-CN/automation/index.md index f79f3d7d6..54e5a4c15 100644 --- a/docs/zh-CN/automation/index.md +++ b/docs/zh-CN/automation/index.md @@ -1,120 +1,123 @@ --- read_when: - 决定如何使用 OpenClaw 自动化工作 - - 在 heartbeat、cron、hooks 和常设指令之间进行选择 + - 在 heartbeat、cron、钩子和长期指令之间进行选择 - 寻找合适的自动化入口点 -summary: 自动化机制概览：任务、cron、hooks、常设指令和任务流 +summary: 自动化机制概览：任务、cron、钩子、长期指令，以及任务流 title: 自动化与任务 x-i18n: - generated_at: "2026-04-23T20:40:39Z" + generated_at: "2026-04-24T17:31:11Z" model: gpt-5.4 provider: openai - source_hash: 1b4615cc05a6d0ef7c92f44072d11a2541bc5e17b7acb88dc27ddf0c36b2dcab + source_hash: 54524eb5d1fcb2b2e3e51117339be1949d980afaef1f6ae71fcfd764049f3f47 source_path: automation/index.md workflow: 15 --- -OpenClaw 通过任务、计划作业、事件 hooks 和常设指令在后台运行工作。本页可帮助你选择合适的机制，并了解它们如何协同工作。 +OpenClaw 通过任务、定时作业、事件钩子和长期指令在后台运行工作。本页将帮助你选择合适的机制，并了解它们如何协同工作。 ## 快速决策指南 ```mermaid flowchart TD - START([What do you need?]) --> Q1{Schedule work?} - START --> Q2{Track detached work?} - START --> Q3{Orchestrate multi-step flows?} - START --> Q4{React to lifecycle events?} - START --> Q5{Give the agent persistent instructions?} + START([你需要什么？]) --> Q1{安排工作时间？} + START --> Q2{跟踪分离的工作？} + START --> Q3{编排多步骤流程？} + START --> Q4{响应生命周期事件？} + START --> Q5{给智能体持久化指令？} - Q1 -->|Yes| Q1a{Exact timing or flexible?} - Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"] - Q1a -->|Flexible| HEARTBEAT[Heartbeat] + Q1 -->|是| Q1a{精确时间还是灵活时间？} + Q1a -->|精确| CRON["计划任务（Cron）"] + Q1a -->|灵活| HEARTBEAT[Heartbeat] - Q2 -->|Yes| TASKS[Background Tasks] - Q3 -->|Yes| FLOW[Task Flow] - Q4 -->|Yes| HOOKS[Hooks] - Q5 -->|Yes| SO[Standing Orders] + Q2 -->|是| TASKS[后台任务] + Q3 -->|是| FLOW[任务流] + Q4 -->|是| HOOKS[钩子] + Q5 -->|是| SO[长期指令] ``` -| 用例 | 推荐方案 | 原因 | +| 使用场景 | 推荐机制 | 原因 | | --------------------------------------- | ---------------------- | ------------------------------------------------ | -| 在上午 9 点准时发送每日报告 | 计划任务（Cron） | 时间精确，执行隔离 | +| 每天早上 9 点准时发送日报 | 计划任务（Cron） | 时间精确，执行隔离 | | 20 分钟后提醒我 | 计划任务（Cron） | 一次性任务，时间精确（`--at`） | | 每周运行一次深度分析 | 计划任务（Cron） | 独立任务，可使用不同模型 | -| 每 30 分钟检查一次收件箱 | Heartbeat | 可与其他检查批量处理，且具备上下文感知 | +| 每 30 分钟检查一次收件箱 | Heartbeat | 可与其他检查批量执行，且具备上下文感知 | | 监控日历中的即将到来的事件 | Heartbeat | 非常适合周期性感知类任务 | -| 检查 subagent 或 ACP 运行的状态 | 后台任务 | 任务台账会跟踪所有分离工作 | +| 检查子智能体或 ACP 运行的状态 | 后台任务 | 任务台账会跟踪所有分离的工作 | | 审计运行了什么以及运行时间 | 后台任务 | `openclaw tasks list` 和 `openclaw tasks audit` | -| 多步骤研究后再总结 | Task Flow | 具备修订跟踪的持久化编排 | -| 在会话重置时运行脚本 | Hooks | 事件驱动，在生命周期事件上触发 | -| 在每次工具调用时执行代码 | Hooks | Hooks 可按事件类型过滤 | -| 始终在回复前检查合规性 | 常设指令 | 会自动注入到每个会话中 | +| 先进行多步骤研究再总结 | 任务流 | 具备修订跟踪的持久化编排 | +| 在会话重置时运行脚本 | 钩子 | 事件驱动，在生命周期事件发生时触发 | +| 在每次工具调用时执行代码 | 插件钩子 | 进程内钩子可以拦截工具调用 | +| 在回复前始终检查合规性 | 长期指令 | 自动注入到每个会话中 | -### 计划任务（Cron）与 Heartbeat +### 计划任务（Cron）与 Heartbeat 的区别 | 维度 | 计划任务（Cron） | Heartbeat | | --------------- | ----------------------------------- | ------------------------------------- | -| 时间控制 | 精确（cron 表达式、一次性任务） | 近似（默认每 30 分钟一次） | +| 时间控制 | 精确（cron 表达式、一次性任务） | 近似（默认每 30 分钟） | | 会话上下文 | 全新（隔离）或共享 | 完整的主会话上下文 | | 任务记录 | 始终创建 | 从不创建 | -| 交付方式 | 渠道、webhook 或静默 | 在主会话中内联显示 | +| 交付方式 | 渠道、webhook 或静默 | 直接内联到主会话中 | | 最适合 | 报告、提醒、后台作业 | 收件箱检查、日历、通知 | -当你需要精确时间控制或隔离执行时，使用计划任务（Cron）。当工作受益于完整会话上下文且可接受近似时间时，使用 Heartbeat。 +当你需要精确时间控制或隔离执行时，使用计划任务（Cron）。当工作受益于完整会话上下文且可以接受近似时间时，使用 Heartbeat。 ## 核心概念 ### 计划任务（cron） -Cron 是 Gateway 网关内置的精确定时调度器。它会持久化作业，在正确时间唤醒智能体，并可将输出发送到聊天渠道或 webhook 端点。支持一次性提醒、周期性表达式以及入站 webhook 触发器。 +Cron 是 Gateway 网关内置的精确定时调度器。它会持久化作业，在正确的时间唤醒智能体，并可将输出发送到聊天渠道或 webhook 端点。支持一次性提醒、循环表达式以及入站 webhook 触发器。 参见 [计划任务](/zh-CN/automation/cron-jobs)。 ### 任务 -后台任务台账会跟踪所有分离工作：ACP 运行、subagent 启动、隔离的 cron 执行以及 CLI 操作。任务是记录，不是调度器。使用 `openclaw tasks list` 和 `openclaw tasks audit` 来检查它们。 +后台任务台账会跟踪所有分离的工作：ACP 运行、子智能体启动、隔离的 cron 执行以及 CLI 操作。任务是记录，而不是调度器。使用 `openclaw tasks list` 和 `openclaw tasks audit` 来检查它们。 参见 [后台任务](/zh-CN/automation/tasks)。 -### Task Flow +### 任务流 -Task Flow 是位于后台任务之上的流程编排基础层。它通过托管和镜像同步模式、修订跟踪以及 `openclaw tasks flow list|show|cancel` 检查命令来管理持久化的多步骤流程。 +任务流是位于后台任务之上的流程编排底层。它通过托管和镜像同步模式、修订跟踪，以及用于检查的 `openclaw tasks flow list|show|cancel`，来管理持久化的多步骤流程。 -参见 [Task Flow](/zh-CN/automation/taskflow)。 +参见 [任务流](/zh-CN/automation/taskflow)。 -### 常设指令 +### 长期指令 -常设指令为智能体授予已定义程序的永久操作权限。它们位于工作区文件中（通常是 `AGENTS.md`），并会注入到每个会话中。可与 cron 结合，以实现基于时间的执行约束。 +长期指令为智能体授予已定义程序的永久操作权限。它们存在于工作区文件中（通常是 `AGENTS.md`），并会注入到每个会话中。可结合 cron 实现基于时间的强制执行。 -参见 [常设指令](/zh-CN/automation/standing-orders)。 +参见 [长期指令](/zh-CN/automation/standing-orders)。 -### Hooks +### 钩子 -Hooks 是由智能体生命周期事件（`/new`、`/reset`、`/stop`）、会话压缩、Gateway 网关启动、消息流以及工具调用触发的事件驱动脚本。Hooks 会自动从目录中发现，也可通过 `openclaw hooks` 管理。 +内部钩子是由智能体生命周期事件 +（`/new`、`/reset`、`/stop`）、会话压缩、Gateway 网关启动以及消息流触发的事件驱动脚本。系统会自动从目录中发现它们，并可通过 `openclaw hooks` 进行管理。对于进程内的工具调用拦截，请使用 +[插件钩子](/zh-CN/plugins/hooks)。 -参见 [Hooks](/zh-CN/automation/hooks)。 +参见 [钩子](/zh-CN/automation/hooks)。 ### Heartbeat -Heartbeat 是周期性的主会话轮次（默认每 30 分钟一次）。它会在一个具备完整会话上下文的智能体轮次中批量执行多项检查（收件箱、日历、通知）。Heartbeat 轮次不会创建任务记录。对于简单检查清单，可使用 `HEARTBEAT.md`；如果你希望在 heartbeat 内部执行仅在到期时运行的周期性检查，则可使用 `tasks:` 块。空的 heartbeat 文件会以 `empty-heartbeat-file` 跳过；仅到期任务模式会以 `no-tasks-due` 跳过。 +Heartbeat 是一种周期性的主会话轮次（默认每 30 分钟一次）。它会在一次智能体轮次中批量执行多个检查（收件箱、日历、通知），并保留完整的会话上下文。Heartbeat 轮次不会创建任务记录。若只需一个简短检查清单，请使用 `HEARTBEAT.md`；若你希望在 heartbeat 内部执行仅在到期时运行的周期性检查，请使用 `tasks:` 块。空的 heartbeat 文件会以 `empty-heartbeat-file` 跳过；仅到期任务模式会以 `no-tasks-due` 跳过。 参见 [Heartbeat](/zh-CN/gateway/heartbeat)。 ## 它们如何协同工作 -- **Cron** 负责精确计划（每日报告、每周回顾）和一次性提醒。所有 cron 执行都会创建任务记录。 -- **Heartbeat** 负责常规监控（收件箱、日历、通知），每 30 分钟在一次批处理轮次中完成。 -- **Hooks** 对特定事件（工具调用、会话重置、压缩）通过自定义脚本作出响应。 -- **常设指令** 为智能体提供持久上下文和权限边界。 -- **Task Flow** 在单个任务之上协调多步骤流程。 -- **任务** 会自动跟踪所有分离工作，以便你进行检查和审计。 +- **Cron** 处理精确计划（每日报告、每周回顾）和一次性提醒。所有 cron 执行都会创建任务记录。 +- **Heartbeat** 每 30 分钟以一次批处理轮次处理例行监控（收件箱、日历、通知）。 +- **钩子** 通过自定义脚本响应特定事件（会话重置、压缩、消息流）。插件钩子负责处理工具调用。 +- **长期指令** 为智能体提供持久化上下文和权限边界。 +- **任务流** 在单个任务之上协调多步骤流程。 +- **任务** 会自动跟踪所有分离的工作，以便你进行检查和审计。 ## 相关内容 -- [计划任务](/zh-CN/automation/cron-jobs) — 精确定时与一次性提醒 +- [计划任务](/zh-CN/automation/cron-jobs) — 精确调度和一次性提醒 - [后台任务](/zh-CN/automation/tasks) — 所有分离工作的任务台账 -- [Task Flow](/zh-CN/automation/taskflow) — 持久化多步骤流程编排 -- [Hooks](/zh-CN/automation/hooks) — 事件驱动的生命周期脚本 -- [常设指令](/zh-CN/automation/standing-orders) — 持久化智能体指令 +- [任务流](/zh-CN/automation/taskflow) — 持久化多步骤流程编排 +- [钩子](/zh-CN/automation/hooks) — 事件驱动的生命周期脚本 +- [插件钩子](/zh-CN/plugins/hooks) — 进程内的工具、提示词、消息和生命周期钩子 +- [长期指令](/zh-CN/automation/standing-orders) — 持久化智能体指令 - [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性的主会话轮次 - [配置参考](/zh-CN/gateway/configuration-reference) — 所有配置键名 diff --git a/docs/zh-CN/cli/hooks.md b/docs/zh-CN/cli/hooks.md index 373088992..0a946eb54 100644 --- a/docs/zh-CN/cli/hooks.md +++ b/docs/zh-CN/cli/hooks.md @@ -1,28 +1,28 @@ --- read_when: - 你想要管理智能体钩子 - - 你想要检查钩子的可用性或启用工作区钩子 + - 你想要检查钩子的可用性，或启用工作区钩子 summary: '`openclaw hooks` 的 CLI 参考（智能体钩子）' title: 钩子 x-i18n: - generated_at: "2026-04-24T03:14:44Z" + generated_at: "2026-04-24T17:31:12Z" model: gpt-5.4 provider: openai - source_hash: 84f209e90a5679b889112fc03e22ea94f486ded9db25b5238c0366283695a5b9 + source_hash: dd84cc984b24996c5509ce6b69f9bb76c61c4fa65b002809fdf5776abe67b48b source_path: cli/hooks.md workflow: 15 --- # `openclaw hooks` -管理智能体钩子（用于 `/new`、`/reset` 和 Gateway 网关启动等命令的事件驱动自动化）。 +管理智能体钩子（针对 `/new`、`/reset` 和 Gateway 网关启动等命令的事件驱动自动化）。 在不带子命令的情况下运行 `openclaw hooks`，等同于 `openclaw hooks list`。 相关内容： - 钩子：[Hooks](/zh-CN/automation/hooks) -- 插件钩子：[Plugin hooks](/zh-CN/plugins/architecture-internals#provider-runtime-hooks) +- 插件钩子：[插件钩子](/zh-CN/plugins/hooks) ## 列出所有钩子 @@ -30,12 +30,12 @@ x-i18n: openclaw hooks list ``` -列出从工作区、托管、额外和内置目录中发现的所有钩子。 -在至少配置了一个内部钩子之前，Gateway 网关启动时不会加载内部钩子处理器。 +列出从工作区、托管目录、额外目录和内置目录中发现的所有钩子。 +在至少配置了一个内部钩子之前，Gateway 网关启动时不会加载内部钩子处理程序。 **选项：** -- `--eligible`：仅显示可用钩子（要求已满足） +- `--eligible`：仅显示符合条件的钩子（满足要求） - `--json`：以 JSON 格式输出 - `-v, --verbose`：显示详细信息，包括缺失的要求 @@ -45,10 +45,10 @@ openclaw hooks list Hooks (4/4 ready) Ready: - 🚀 boot-md ✓ - 在 Gateway 网关启动时运行 BOOT.md - 📎 bootstrap-extra-files ✓ - 在智能体引导期间注入额外的工作区引导文件 - 📝 command-logger ✓ - 将所有命令事件记录到集中式审计文件 - 💾 session-memory ✓ - 在发出 /new 或 /reset 命令时将会话上下文保存到 memory + 🚀 boot-md ✓ - Run BOOT.md on gateway startup + 📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap + 📝 command-logger ✓ - Log all command events to a centralized audit file + 💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued ``` **示例（详细模式）：** @@ -57,7 +57,7 @@ Ready: openclaw hooks list --verbose ``` -显示不可用钩子缺失的要求。 +显示不符合条件的钩子缺失了哪些要求。 **示例（JSON）：** @@ -77,7 +77,7 @@ openclaw hooks info **参数：** -- ``：钩子名称或钩子键（例如 `session-memory`） +- ``：钩子名称或钩子键名（例如 `session-memory`） **选项：** @@ -94,7 +94,7 @@ openclaw hooks info session-memory ``` 💾 session-memory ✓ Ready -在发出 /new 或 /reset 命令时将会话上下文保存到 memory +Save session context to memory when /new or /reset command is issued Details: Source: openclaw-bundled @@ -107,13 +107,13 @@ Requirements: Config: ✓ workspace.dir ``` -## 检查钩子可用性 +## 检查钩子适用性 ```bash openclaw hooks check ``` -显示钩子可用性状态摘要（有多少已就绪，多少未就绪）。 +显示钩子适用状态的摘要（有多少已就绪，多少未就绪）。 **选项：** @@ -137,7 +137,7 @@ openclaw hooks enable 通过将特定钩子添加到你的配置中来启用它（默认是 `~/.openclaw/openclaw.json`）。 -**注意：** 工作区钩子默认处于禁用状态，除非你在此处或配置中启用它们。由插件管理的钩子会在 `openclaw hooks list` 中显示为 `plugin:`，不能在这里启用或禁用。请改为启用或禁用对应插件。 +**注意：** 工作区钩子默认禁用，必须在此处或配置中启用。由插件管理的钩子会在 `openclaw hooks list` 中显示为 `plugin:`，不能在这里启用或禁用。请改为启用或禁用对应插件。 **参数：** @@ -155,13 +155,13 @@ openclaw hooks enable session-memory ✓ Enabled hook: 💾 session-memory ``` -**它会执行以下操作：** +**它的作用：** -- 检查钩子是否存在且可用 -- 更新配置中的 `hooks.internal.entries..enabled = true` +- 检查钩子是否存在且符合条件 +- 在你的配置中更新 `hooks.internal.entries..enabled = true` - 将配置保存到磁盘 -如果该钩子来自 `/hooks/`，则必须执行此选择加入步骤，Gateway 网关才会加载它。 +如果钩子来自 `/hooks/`，则 Gateway 网关加载它之前必须完成此显式启用步骤。 **启用后：** @@ -198,34 +198,34 @@ openclaw hooks disable command-logger ## 说明 - `openclaw hooks list --json`、`info --json` 和 `check --json` 会将结构化 JSON 直接写入 stdout。 -- 由插件管理的钩子不能在这里启用或禁用；请改为启用或禁用其所属插件。 +- 由插件管理的钩子不能在这里启用或禁用；请改为启用或禁用所属插件。 ## 安装钩子包 ```bash -openclaw plugins install # 先从 ClawHub，然后从 npm +openclaw plugins install # 优先从 ClawHub，其次 npm openclaw plugins install --pin # 固定版本 openclaw plugins install # 本地路径 ``` 通过统一的插件安装器安装钩子包。 -`openclaw hooks install` 仍可作为兼容性别名使用，但它会打印弃用警告并转发到 `openclaw plugins install`。 +`openclaw hooks install` 仍可用作兼容性别名，但它会打印弃用警告，并转发到 `openclaw plugins install`。 -npm 规格必须是**仅注册表**格式（包名 + 可选的**精确版本**或 **dist-tag**）。Git / URL / 文件规格和 semver 范围会被拒绝。为了安全起见，依赖安装使用 `--ignore-scripts` 运行。 +Npm 规格仅支持 **registry-only**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file 规格和 semver 范围会被拒绝。出于安全考虑，依赖安装会使用 `--ignore-scripts` 运行。 -裸规格和 `@latest` 会保持在稳定通道。如果 npm 将这两者中的任意一种解析为预发布版本，OpenClaw 会停止并要求你使用预发布标签（如 `@beta`/`@rc`）或精确的预发布版本显式选择加入。 +不带后缀的规格和 `@latest` 会保持在稳定版本轨道上。如果 npm 将其中任意一种解析为预发布版本，OpenClaw 会停止并要求你显式选择加入，例如使用 `@beta`/`@rc` 这样的预发布标签，或精确的预发布版本号。 -**它会执行以下操作：** +**它的作用：** - 将钩子包复制到 `~/.openclaw/hooks/` - 在 `hooks.internal.entries.*` 中启用已安装的钩子 -- 在 `hooks.internal.installs` 下记录此次安装 +- 在 `hooks.internal.installs` 中记录安装信息 **选项：** - `-l, --link`：链接本地目录而不是复制（将其添加到 `hooks.internal.load.extraDirs`） -- `--pin`：将 npm 安装记录为 `hooks.internal.installs` 中精确解析后的 `name@version` +- `--pin`：将 npm 安装以精确解析后的 `name@version` 记录到 `hooks.internal.installs` **支持的归档格式：** `.zip`、`.tgz`、`.tar.gz`、`.tar` @@ -245,7 +245,7 @@ openclaw plugins install @openclaw/my-hook-pack openclaw plugins install -l ./my-hook-pack ``` -已链接的钩子包会被视为来自运维人员配置目录的托管钩子，而不是工作区钩子。 +链接的钩子包会被视为来自运维人员配置目录的托管钩子，而不是工作区钩子。 ## 更新钩子包 @@ -254,16 +254,16 @@ openclaw plugins update openclaw plugins update --all ``` -通过统一的插件更新器更新已跟踪的、基于 npm 的钩子包。 +通过统一的插件更新器更新已跟踪的基于 npm 的钩子包。 -`openclaw hooks update` 仍可作为兼容性别名使用，但它会打印弃用警告并转发到 `openclaw plugins update`。 +`openclaw hooks update` 仍可用作兼容性别名，但它会打印弃用警告，并转发到 `openclaw plugins update`。 **选项：** - `--all`：更新所有已跟踪的钩子包 -- `--dry-run`：显示将会发生的更改，但不写入 +- `--dry-run`：显示将会发生的变更，但不写入 -当存在已存储的完整性哈希，且获取到的制品哈希发生变化时，OpenClaw 会打印警告并在继续前请求确认。在 CI / 非交互式运行中，可使用全局 `--yes` 跳过提示。 +当存在已存储的完整性哈希且获取到的制品哈希发生变化时，OpenClaw 会打印警告并在继续前请求确认。在 CI 或非交互运行中，可使用全局 `--yes` 跳过提示。 ## 内置钩子 @@ -279,7 +279,7 @@ openclaw hooks enable session-memory **输出：** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md` -**参见：** [session-memory documentation](/zh-CN/automation/hooks#session-memory) +**参见：** [session-memory 文档](/zh-CN/automation/hooks#session-memory) ### bootstrap-extra-files @@ -291,11 +291,11 @@ openclaw hooks enable session-memory openclaw hooks enable bootstrap-extra-files ``` -**参见：** [bootstrap-extra-files documentation](/zh-CN/automation/hooks#bootstrap-extra-files) +**参见：** [bootstrap-extra-files 文档](/zh-CN/automation/hooks#bootstrap-extra-files) ### command-logger -将所有命令事件记录到集中式审计文件。 +将所有命令事件记录到集中式审计文件中。 **启用：** @@ -318,11 +318,11 @@ cat ~/.openclaw/logs/commands.log | jq . grep '"action":"new"' ~/.openclaw/logs/commands.log | jq . ``` -**参见：** [command-logger documentation](/zh-CN/automation/hooks#command-logger) +**参见：** [command-logger 文档](/zh-CN/automation/hooks#command-logger) ### boot-md -在 Gateway 网关启动时运行 `BOOT.md`（在渠道启动之后）。 +在 Gateway 网关启动时（渠道启动后）运行 `BOOT.md`。 **事件**：`gateway:startup` @@ -332,9 +332,9 @@ grep '"action":"new"' ~/.openclaw/logs/commands.log | jq . openclaw hooks enable boot-md ``` -**参见：** [boot-md documentation](/zh-CN/automation/hooks#boot-md) +**参见：** [boot-md 文档](/zh-CN/automation/hooks#boot-md) ## 相关内容 -- [CLI reference](/zh-CN/cli) -- [Automation hooks](/zh-CN/automation/hooks) +- [CLI 参考](/zh-CN/cli) +- [自动化钩子](/zh-CN/automation/hooks) diff --git a/docs/zh-CN/concepts/agent-loop.md b/docs/zh-CN/concepts/agent-loop.md index af6fb30fe..405a60ba5 100644 --- a/docs/zh-CN/concepts/agent-loop.md +++ b/docs/zh-CN/concepts/agent-loop.md @@ -1,49 +1,46 @@ --- read_when: - - 你需要一份关于智能体循环或生命周期事件的精确说明 + - 你需要一份关于智能体循环或生命周期事件的精确演练说明 - 你正在更改会话排队、转录写入或会话写锁行为 -summary: 智能体循环生命周期、流和等待语义 +summary: 智能体循环生命周期、流，以及等待语义 title: 智能体循环 x-i18n: - generated_at: "2026-04-24T03:15:24Z" + generated_at: "2026-04-24T17:31:10Z" model: gpt-5.4 provider: openai - source_hash: a413986168fe7eb1cb229e5ec45027d31fab889ca20ad53f289c8dfce98f7fab + source_hash: 09419b1181c682fe4feed3e30ae6d7e18e002279bedb702312d944fd93a85ac6 source_path: concepts/agent-loop.md workflow: 15 --- # 智能体循环（OpenClaw） -智能体循环是智能体一次完整、“真实”的运行：输入接收 → 上下文组装 → 模型推理 → -工具执行 → 流式回复 → 持久化。它是将一条消息 -转化为操作和最终回复的权威路径，同时保持会话状态一致。 +智能体循环是智能体一次完整的“真实”运行：输入接收 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。它是将一条消息转换为操作和最终回复的权威路径，同时保持会话状态一致。 -在 OpenClaw 中，一个循环是每个会话一次串行化的单次运行，在模型思考、调用工具和流式输出时 -会发出生命周期事件和流事件。本文档解释了这一真实循环如何端到端连接。 +在 OpenClaw 中，一个循环是每个会话对应的一次串行化运行；在模型思考、调用工具和流式输出内容时，它会发出生命周期事件和流事件。本文档说明这一真实循环如何端到端接线。 ## 入口点 - Gateway 网关 RPC：`agent` 和 `agent.wait`。 - CLI：`agent` 命令。 -## 工作原理（高层） +## 工作方式（高层概览） 1. `agent` RPC 验证参数，解析会话（sessionKey/sessionId），持久化会话元数据，并立即返回 `{ runId, acceptedAt }`。 2. `agentCommand` 运行智能体： - - 解析模型 + thinking/verbose/trace 默认值 + - 解析模型以及 thinking/verbose/trace 默认值 - 加载 Skills 快照 - 调用 `runEmbeddedPiAgent`（pi-agent-core 运行时） - - 如果嵌入式循环未发出 **lifecycle end/error**，则发出 **lifecycle end/error** + - 如果嵌入式循环未发出事件，则发出 **lifecycle end/error** 3. `runEmbeddedPiAgent`： - - 通过每会话队列 + 全局队列串行化运行 - - 解析模型 + 认证配置文件并构建 Pi 会话 + - 通过每会话队列和全局队列对运行进行串行化 + - 解析模型和凭证配置文件，并构建 Pi 会话 - 订阅 Pi 事件并流式传输 assistant/tool 增量 - - 强制超时 -> 超过时中止运行 + - 强制执行超时；超过时中止运行 - 返回负载和 usage 元数据 4. `subscribeEmbeddedPiSession` 将 pi-agent-core 事件桥接到 OpenClaw `agent` 流： - 工具事件 => `stream: "tool"` - - 助手增量 => `stream: "assistant"` + - assistant 增量 => `stream: "assistant"` - 生命周期事件 => `stream: "lifecycle"`（`phase: "start" | "end" | "error"`） 5. `agent.wait` 使用 `waitForAgentRun`： - 等待 `runId` 的 **lifecycle end/error** @@ -51,109 +48,103 @@ x-i18n: ## 排队 + 并发 -- 运行会按会话键（会话通道）串行化，并可选地通过一个全局通道。 +- 运行会按会话键（会话通道）串行化，也可以选择通过全局通道。 - 这可以防止工具/会话竞争，并保持会话历史一致。 -- 消息渠道可以选择队列模式（collect/steer/followup）来接入该通道系统。 +- 消息渠道可以选择队列模式（collect/steer/followup）来接入这一通道系统。 参见 [命令队列](/zh-CN/concepts/queue)。 -- 转录写入也受会话文件上的会话写锁保护。该锁 - 具备进程感知能力并且基于文件，因此它可以捕获绕过进程内队列或来自 - 其他进程的写入者。 -- 默认情况下，会话写锁不可重入。如果某个辅助函数有意在保持单一逻辑写入者的同时嵌套获取 - 同一把锁，则必须显式启用 +- 转录写入同样受会话文件上的会话写锁保护。该锁具有进程感知能力并基于文件，因此可以捕获绕过进程内队列或来自其他进程的写入者。 +- 会话写锁默认不可重入。如果某个辅助函数有意在保持单一逻辑写入者的前提下嵌套获取同一把锁，则必须显式启用 `allowReentrant: true`。 ## 会话 + 工作区准备 - 工作区会被解析并创建；沙箱隔离运行可能会重定向到沙箱工作区根目录。 -- Skills 会被加载（或从快照复用），并注入到环境变量和提示词中。 +- Skills 会被加载（或从快照复用），并注入到环境和提示词中。 - Bootstrap/上下文文件会被解析并注入到系统提示词报告中。 -- 会获取一个会话写锁；`SessionManager` 会在流式传输前打开并准备好。任何 - 后续的转录重写、压缩或截断路径，在打开或 - 修改转录文件之前都必须获取同一把锁。 +- 会先获取会话写锁；`SessionManager` 会在流式传输开始前打开并完成准备。任何后续的转录重写、压缩或截断路径，都必须在打开或修改转录文件之前获取同一把锁。 ## 提示词组装 + 系统提示词 -- 系统提示词由 OpenClaw 的基础提示词、Skills 提示词、bootstrap 上下文和每次运行的覆盖项构建而成。 -- 会强制执行特定于模型的限制和压缩保留令牌。 -- 有关模型实际看到的内容，请参见 [系统提示词](/zh-CN/concepts/system-prompt)。 +- 系统提示词由 OpenClaw 的基础提示词、Skills 提示词、bootstrap 上下文和每次运行的覆盖项共同构建。 +- 会强制执行特定于模型的限制和压缩预留 token。 +- 有关模型实际看到的内容，参见 [系统提示词](/zh-CN/concepts/system-prompt)。 -## Hook 点（你可以在哪些地方拦截） +## 钩子点（你可以拦截的位置） -OpenClaw 有两套 Hook 系统： +OpenClaw 有两套钩子系统： -- **内部 Hook**（Gateway 网关 Hook）：用于命令和生命周期事件的事件驱动脚本。 -- **插件 Hook**：位于智能体/工具生命周期和 Gateway 网关流水线中的扩展点。 +- **内部钩子**（Gateway 网关钩子）：用于命令和生命周期事件的事件驱动脚本。 +- **插件钩子**：位于智能体/工具生命周期和 Gateway 网关流水线内部的扩展点。 -### 内部 Hook（Gateway 网关 Hook） +### 内部钩子（Gateway 网关钩子） -- **`agent:bootstrap`**：在系统提示词最终确定前，构建 bootstrap 文件时运行。 +- **`agent:bootstrap`**：在系统提示词最终确定之前、构建 bootstrap 文件时运行。 用它来添加/移除 bootstrap 上下文文件。 -- **命令 Hook**：`/new`、`/reset`、`/stop` 和其他命令事件（参见 Hook 文档）。 +- **命令钩子**：`/new`、`/reset`、`/stop` 以及其他命令事件（参见 Hooks 文档）。 -设置和示例请参见 [Hooks](/zh-CN/automation/hooks)。 +设置和示例参见 [Hooks](/zh-CN/automation/hooks)。 -### 插件 Hook（智能体 + Gateway 网关生命周期） +### 插件钩子（智能体 + Gateway 网关生命周期） -这些 Hook 在智能体循环或 Gateway 网关流水线内部运行： +这些钩子在智能体循环或 Gateway 网关流水线内部运行： -- **`before_model_resolve`**：在会话前运行（无 `messages`），以确定性方式在模型解析前覆盖 provider/model。 -- **`before_prompt_build`**：在会话加载后运行（带有 `messages`），用于在提交提示词前注入 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。对每回合动态文本使用 `prependContext`，对应该位于系统提示词空间中的稳定指导使用系统上下文字段。 -- **`before_agent_start`**：旧版兼容 Hook，可能在任一阶段运行；优先使用上面更明确的 Hook。 -- **`before_agent_reply`**：在内联操作之后、LLM 调用之前运行，允许插件接管该回合并返回合成回复，或完全静默该回合。 +- **`before_model_resolve`**：在会话前运行（无 `messages`），用于在模型解析前确定性地覆盖 provider/model。 +- **`before_prompt_build`**：在会话加载后运行（带有 `messages`），用于在提交提示词前注入 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。对每轮动态文本使用 `prependContext`，对应该位于系统提示词空间中的稳定指导使用 system-context 字段。 +- **`before_agent_start`**：遗留兼容性钩子，可能在任一阶段运行；优先使用上面更明确的钩子。 +- **`before_agent_reply`**：在内联操作之后、LLM 调用之前运行，允许插件接管当前轮次并返回合成回复，或完全静默该轮次。 - **`agent_end`**：在完成后检查最终消息列表和运行元数据。 -- **`before_compaction` / `after_compaction`**：观察或注释压缩周期。 +- **`before_compaction` / `after_compaction`**：观察或标注压缩周期。 - **`before_tool_call` / `after_tool_call`**：拦截工具参数/结果。 -- **`before_install`**：检查内置扫描结果，并可选择阻止 Skills 或插件安装。 -- **`tool_result_persist`**：在工具结果写入 OpenClaw 自有的会话转录之前同步转换工具结果。 -- **`message_received` / `message_sending` / `message_sent`**：入站 + 出站消息 Hook。 +- **`before_install`**：检查内置扫描结果，并可选择阻止 skill 或插件安装。 +- **`tool_result_persist`**：在工具结果写入 OpenClaw 自有的会话转录之前，同步转换这些结果。 +- **`message_received` / `message_sending` / `message_sent`**：入站 + 出站消息钩子。 - **`session_start` / `session_end`**：会话生命周期边界。 - **`gateway_start` / `gateway_stop`**：Gateway 网关生命周期事件。 -出站/工具守卫的 Hook 决策规则： +用于出站/工具保护的钩子判定规则： -- `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 }` 为无操作，不会清除先前的取消。 +- `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 API 和注册详情，请参见 [插件 Hook](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 +有关钩子 API 和注册细节，参见 [插件钩子](/zh-CN/plugins/hooks)。 -不同 harness 可能会以不同方式适配这些 Hook。Codex app-server harness 将 -OpenClaw 插件 Hook 保持为已记录镜像表面的兼容性契约， -而 Codex 原生 Hook 仍然是一个独立的、更底层的 Codex 机制。 +不同 Harness 可能会以不同方式适配这些钩子。Codex app-server harness 将 +OpenClaw 插件钩子保留为已记录镜像表面的兼容性契约，而 Codex 原生钩子仍然是独立的、更底层的 Codex 机制。 ## 流式传输 + 部分回复 -- 助手增量从 pi-agent-core 流式传出，并作为 `assistant` 事件发出。 +- assistant 增量从 pi-agent-core 流式传出，并作为 `assistant` 事件发出。 - 分块流式传输可以在 `text_end` 或 `message_end` 时发出部分回复。 -- 推理流式传输可以作为单独的流发出，也可以作为分块回复发出。 -- 有关分块和分块回复行为，请参见 [流式传输](/zh-CN/concepts/streaming)。 +- 推理流式传输可以作为单独流发出，也可以作为块回复发出。 +- 有关分块和块回复行为，参见 [流式传输](/zh-CN/concepts/streaming)。 ## 工具执行 + 消息工具 -- 工具 start/update/end 事件会在 `tool` 流上发出。 -- 工具结果在记录/发出前，会针对大小和图像负载进行清理。 -- 消息工具发送会被跟踪，以抑制重复的助手确认信息。 +- 工具开始/更新/结束事件会在 `tool` 流上发出。 +- 在记录/发出之前，工具结果会针对大小和图像负载进行清理。 +- 会跟踪消息工具发送，以抑制重复的 assistant 确认信息。 ## 回复整形 + 抑制 - 最终负载由以下内容组装而成： - - 助手文本（以及可选的推理） - - 内联工具摘要（当 verbose 开启且允许时） - - 模型报错时的助手错误文本 -- 精确的静默令牌 `NO_REPLY` / `no_reply` 会从出站 + - assistant 文本（以及可选的推理内容） + - 内联工具摘要（在 verbose 开启且允许时） + - 模型出错时的 assistant 错误文本 +- 精确的静默 token `NO_REPLY` / `no_reply` 会从出站 负载中过滤掉。 -- 消息工具重复项会从最终负载列表中移除。 -- 如果没有剩余可渲染的负载且某个工具报错，则会发出一个后备工具错误回复 +- 会从最终负载列表中移除消息工具重复项。 +- 如果没有剩余可渲染负载，且某个工具出错，则会发出回退工具错误回复 （除非某个消息工具已经发送了用户可见的回复）。 ## 压缩 + 重试 -- 自动压缩会发出 `compaction` 流事件，并且可以触发重试。 -- 重试时，会重置内存缓冲区和工具摘要，以避免重复输出。 -- 有关压缩流水线，请参见 [压缩](/zh-CN/concepts/compaction)。 +- 自动压缩会发出 `compaction` 流事件，并且可能触发重试。 +- 重试时，内存缓冲区和工具摘要会被重置，以避免重复输出。 +- 有关压缩流水线，参见 [压缩](/zh-CN/concepts/compaction)。 ## 事件流（当前） @@ -163,26 +154,26 @@ OpenClaw 插件 Hook 保持为已记录镜像表面的兼容性契约， ## 聊天渠道处理 -- 助手增量会缓冲到聊天 `delta` 消息中。 -- 会在 **lifecycle end/error** 时发出聊天 `final`。 +- assistant 增量会被缓冲为聊天 `delta` 消息。 +- 聊天 `final` 会在 **lifecycle end/error** 时发出。 ## 超时 -- `agent.wait` 默认值：30 秒（仅等待）。可通过 `timeoutMs` 参数覆盖。 -- 智能体运行时：`agents.defaults.timeoutSeconds` 默认为 172800 秒（48 小时）；在 `runEmbeddedPiAgent` 的中止计时器中强制执行。 -- LLM 空闲超时：`agents.defaults.llm.idleTimeoutSeconds` 会在空闲窗口内未收到任何响应分块时中止模型请求。对于缓慢的本地模型或推理/工具调用提供商，请显式设置该值；设为 0 可禁用。如果未设置，OpenClaw 会在配置了 `agents.defaults.timeoutSeconds` 时使用该值，否则使用 120 秒。没有显式 LLM 或智能体超时的 cron 触发运行会禁用空闲监控，并依赖 cron 外层超时。 +- `agent.wait` 默认值：30 秒（仅等待）。可由 `timeoutMs` 参数覆盖。 +- 智能体运行时：`agents.defaults.timeoutSeconds` 默认值为 172800 秒（48 小时）；由 `runEmbeddedPiAgent` 中的中止计时器强制执行。 +- LLM 空闲超时：`agents.defaults.llm.idleTimeoutSeconds` 会在空闲窗口内未收到任何响应分块时中止模型请求。对于缓慢的本地模型或推理/工具调用 provider，请显式设置它；设为 0 可禁用。如果未设置，OpenClaw 会在已配置 `agents.defaults.timeoutSeconds` 时使用该值，否则使用 120 秒。对于未显式设置 LLM 或智能体超时的 cron 触发运行，会禁用空闲看门狗，并依赖 cron 外层超时。 -## 可能提前结束的地方 +## 可能提前结束的位置 -- 智能体超时（abort） +- 智能体超时（中止） - AbortSignal（取消） -- Gateway 网关断开或 RPC 超时 -- `agent.wait` 超时（仅停止等待，不会停止智能体） +- Gateway 网关断开连接或 RPC 超时 +- `agent.wait` 超时（仅等待，不会停止智能体） -## 相关 +## 相关内容 -- [工具](/zh-CN/tools) — 可用的智能体工具 -- [Hooks](/zh-CN/automation/hooks) — 由智能体生命周期事件触发的事件驱动脚本 -- [压缩](/zh-CN/concepts/compaction) — 长对话如何被总结 -- [Exec 审批](/zh-CN/tools/exec-approvals) — shell 命令的审批门控 -- [Thinking](/zh-CN/tools/thinking) — thinking/推理级别配置 +- [工具](/zh-CN/tools) —— 可供智能体使用的工具 +- [Hooks](/zh-CN/automation/hooks) —— 由智能体生命周期事件触发的事件驱动脚本 +- [压缩](/zh-CN/concepts/compaction) —— 长对话如何被总结 +- [Exec 审批](/zh-CN/tools/exec-approvals) —— shell 命令的审批门控 +- [Thinking](/zh-CN/tools/thinking) —— thinking/推理级别配置 diff --git a/docs/zh-CN/plugins/building-plugins.md b/docs/zh-CN/plugins/building-plugins.md index 9b9684f1a..5cf99e17c 100644 --- a/docs/zh-CN/plugins/building-plugins.md +++ b/docs/zh-CN/plugins/building-plugins.md @@ -1,49 +1,49 @@ --- read_when: - 你想要创建一个新的 OpenClaw 插件 - - 你需要一个用于插件开发的快速开始指南 + - 你需要一份插件开发的快速开始指南 - 你正在为 OpenClaw 添加一个新的渠道、提供商、工具或其他能力 sidebarTitle: Getting Started summary: 在几分钟内创建你的第一个 OpenClaw 插件 title: 构建插件 x-i18n: - generated_at: "2026-04-24T03:06:50Z" + generated_at: "2026-04-24T17:31:11Z" model: gpt-5.4 provider: openai - source_hash: c14f4c4dc3ae853e385f6beeb9529ea9e360f3d9c5b99dc717cf0851ed02cbc8 + source_hash: 2989d85ebb7ef73a80de25bce5b156f9939c91fd0672c318aa2349bf079f6bc0 source_path: plugins/building-plugins.md workflow: 15 --- -插件通过新增能力来扩展 OpenClaw：渠道、模型提供商、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或这些能力的任意组合。 +插件可为 OpenClaw 扩展新能力：渠道、模型提供商、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或以上任意组合。 -你不需要将你的插件添加到 OpenClaw 仓库中。发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm，用户即可通过 `openclaw plugins install ` 安装。OpenClaw 会先尝试 ClawHub，再自动回退到 npm。 +你不需要将你的插件添加到 OpenClaw 仓库中。发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm，用户即可使用 `openclaw plugins install ` 进行安装。OpenClaw 会先尝试 ClawHub，并在需要时自动回退到 npm。 ## 前提条件 -- Node >= 22，以及一个包管理器（npm 或 pnpm） +- Node >= 22 和一个包管理器（npm 或 pnpm） - 熟悉 TypeScript（ESM） - 对于仓库内插件：已克隆仓库并执行 `pnpm install` -## 你要构建哪种插件？ +## 插件类型 - 将 OpenClaw 连接到一个消息平台（Discord、IRC 等） + 将 OpenClaw 连接到消息平台（Discord、IRC 等） 添加一个模型提供商（LLM、代理或自定义端点） - - 注册智能体工具、事件 hook 或服务——继续阅读下文 + + 注册智能体工具、事件钩子或服务——继续阅读下文 -对于在新手引导/设置运行时无法保证已安装的渠道插件，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装完成之前，对实际配置写入采取失败即关闭的策略。 +对于在新手引导/设置运行时不保证已安装的渠道插件，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于声明安装要求，并在插件安装完成之前，针对实际配置写入采取默认拒绝策略。 ## 快速开始：工具插件 -本教程将创建一个注册智能体工具的最小插件。渠道插件和提供商插件有上方链接的专门指南。 +本演练将创建一个注册智能体工具的最小插件。渠道插件和提供商插件请参阅上方链接的专门指南。 @@ -80,7 +80,7 @@ x-i18n: ``` - 每个插件都需要一个清单，即使没有配置也一样。完整 schema 请参见 [Manifest](/zh-CN/plugins/manifest)。规范的 ClawHub 发布代码片段位于 `docs/snippets/plugin-publish/`。 + 每个插件都需要一个清单，即使没有配置也一样。完整 schema 请参见 [Manifest](/zh-CN/plugins/manifest)。规范的 ClawHub 发布片段位于 `docs/snippets/plugin-publish/`。 @@ -108,7 +108,7 @@ x-i18n: }); ``` - `definePluginEntry` 用于非渠道插件。对于渠道，请使用 `defineChannelPluginEntry` —— 参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。完整的入口点选项请参见 [入口点](/zh-CN/plugins/sdk-entrypoints)。 + `definePluginEntry` 用于非渠道插件。对于渠道插件，请使用 `defineChannelPluginEntry` —— 参见 [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins)。完整入口点选项请参见 [入口点](/zh-CN/plugins/sdk-entrypoints)。 @@ -135,15 +135,15 @@ x-i18n: ## 插件能力 -一个插件可以通过 `api` 对象注册任意数量的能力： +单个插件可以通过 `api` 对象注册任意数量的能力： | 能力 | 注册方法 | 详细指南 | | ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- | | 文本推理（LLM） | `api.registerProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins) | | CLI 推理后端 | `api.registerCliBackend(...)` | [CLI 后端](/zh-CN/gateway/cli-backends) | -| 渠道 / 消息传递 | `api.registerChannel(...)` | [渠道插件](/zh-CN/plugins/sdk-channel-plugins) | +| 渠道 / 消息 | `api.registerChannel(...)` | [渠道插件](/zh-CN/plugins/sdk-channel-plugins) | | 语音（TTS/STT） | `api.registerSpeechProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 实时转写 | `api.registerRealtimeTranscriptionProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 实时语音 | `api.registerRealtimeVoiceProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 图像生成 | `api.registerImageGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | @@ -151,44 +151,45 @@ x-i18n: | 视频生成 | `api.registerVideoGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 网页抓取 | `api.registerWebFetchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 网页搜索 | `api.registerWebSearchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 内嵌 Pi 扩展 | `api.registerEmbeddedExtensionFactory(...)` | [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api) | +| 嵌入式 Pi 扩展 | `api.registerEmbeddedExtensionFactory(...)` | [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api) | | 智能体工具 | `api.registerTool(...)` | 见下文 | | 自定义命令 | `api.registerCommand(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) | -| 事件 hook | `api.registerHook(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) | +| 插件钩子 | `api.on(...)` | [插件钩子](/zh-CN/plugins/hooks) | +| 内部事件钩子 | `api.registerHook(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) | | HTTP 路由 | `api.registerHttpRoute(...)` | [内部机制](/zh-CN/plugins/architecture-internals#gateway-http-routes) | | CLI 子命令 | `api.registerCli(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) | -完整的注册 API 请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。 +完整注册 API 请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。 -当插件需要 Pi 原生的内嵌运行器 hook 时，请使用 `api.registerEmbeddedExtensionFactory(...)`，例如在最终工具结果消息发出之前，对异步 `tool_result` 进行重写。如果这项工作不需要 Pi 扩展时序，优先使用常规 OpenClaw 插件 hook。 +当插件需要 Pi 原生的嵌入式运行器钩子时，请使用 `api.registerEmbeddedExtensionFactory(...)`，例如在最终工具结果消息发出前，对异步 `tool_result` 进行重写。如果工作不需要 Pi 扩展时序，请优先使用常规的 OpenClaw 插件钩子。 -如果你的插件注册了自定义 Gateway 网关 RPC 方法，请为它们使用插件专属前缀。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保留，并且总是解析为 `operator.admin`，即使插件请求了更窄的作用域也是如此。 +如果你的插件注册了自定义 Gateway 网关 RPC 方法，请为其使用插件专属前缀。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保留，并始终解析为 `operator.admin`，即使插件请求了更窄的作用域也是如此。 -需要注意的 hook 守卫语义： +需要注意的钩子守卫语义： -- `before_tool_call`：`{ block: true }` 为终止性结果，会阻止更低优先级的处理器继续执行。 +- `before_tool_call`：`{ block: true }` 是终局决定，会阻止更低优先级的处理器。 - `before_tool_call`：`{ block: false }` 会被视为未作决定。 -- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互，或任意渠道中的 `/approve` 命令提示用户批准。 -- `before_install`：`{ block: true }` 为终止性结果，会阻止更低优先级的处理器继续执行。 +- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互或任意渠道中的 `/approve` 命令提示用户批准。 +- `before_install`：`{ block: true }` 是终局决定，会阻止更低优先级的处理器。 - `before_install`：`{ block: false }` 会被视为未作决定。 -- `message_sending`：`{ cancel: true }` 为终止性结果，会阻止更低优先级的处理器继续执行。 +- `message_sending`：`{ cancel: true }` 是终局决定，会阻止更低优先级的处理器。 - `message_sending`：`{ cancel: false }` 会被视为未作决定。 -- `message_received`：当你需要入站线程/话题路由时，优先使用类型化的 `threadId` 字段。`metadata` 应保留给渠道专属的额外信息。 -- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，而不是渠道专属的 metadata 键。 +- `message_received`：当你需要入站线程/话题路由时，优先使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的附加信息。 +- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，而不是渠道特定的 metadata 键。 -`/approve` 命令同时处理 exec 审批和插件审批，并带有有界回退机制：当找不到某个 exec 审批 id 时，OpenClaw 会使用同一个 id 重新尝试插件审批。插件审批转发可以通过配置中的 `approvals.plugin` 独立设置。 +`/approve` 命令同时处理 exec 审批和插件审批，并带有有界回退机制：当找不到 exec 审批 id 时，OpenClaw 会使用同一个 id 重新尝试插件审批。插件审批转发可通过配置中的 `approvals.plugin` 独立设置。 -如果自定义审批流程需要检测这一相同的有界回退场景，请优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不是手动匹配审批过期字符串。 +如果自定义审批流程需要检测这个相同的有界回退场景，请优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不是手动匹配审批过期字符串。 -详情请参见 [SDK 概览 hook 决策语义](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。 +示例和钩子参考请参见 [插件钩子](/zh-CN/plugins/hooks)。 ## 注册智能体工具 -工具是 LLM 可以调用的类型化函数。它们可以是必需的（始终可用），也可以是可选的（用户选择启用）： +工具是 LLM 可调用的类型化函数。它们可以是必需的（始终可用），也可以是可选的（用户选择启用）： ```typescript register(api) { - // 必需工具——始终可用 + // Required tool — always available api.registerTool({ name: "my_tool", description: "Do a thing", @@ -198,7 +199,7 @@ register(api) { }, }); - // 可选工具——用户必须添加到允许列表 + // Optional tool — user must add to allowlist api.registerTool( { name: "workflow_tool", @@ -222,81 +223,81 @@ register(api) { ``` - 工具名称不得与核心工具冲突（冲突项会被跳过） -- 对于具有副作用或需要额外二进制依赖的工具，请使用 `optional: true` -- 用户可以通过将插件 id 添加到 `tools.allow` 来启用某个插件中的所有工具 +- 对于有副作用或需要额外二进制依赖的工具，请使用 `optional: true` +- 用户可以通过将插件 id 添加到 `tools.allow` 来启用某个插件的全部工具 ## 导入约定 -始终从精确的 `openclaw/plugin-sdk/` 路径导入： +始终从聚焦的 `openclaw/plugin-sdk/` 路径导入： ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; -// 错误：单体根路径（已弃用，将被移除） +// Wrong: monolithic root (deprecated, will be removed) import { ... } from "openclaw/plugin-sdk"; ``` -完整的子路径参考请参见 [SDK 概览](/zh-CN/plugins/sdk-overview)。 +完整子路径参考请参见 [SDK 概览](/zh-CN/plugins/sdk-overview)。 -在你的插件内部，请使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行内部导入——绝不要通过它自己的 SDK 路径导入你自己的插件。 +在你的插件内部，请使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行内部导入——绝不要通过其 SDK 路径导入你自己的插件。 -对于提供商插件，请将提供商专属辅助函数保留在这些包根级 barrel 中，除非该抽象确实是通用的。当前内置示例包括： +对于提供商插件，除非该接口确实足够通用，否则请将提供商特定的辅助函数保留在这些包根 barrel 文件中。当前内置示例包括： - Anthropic：Claude 流包装器以及 `service_tier` / beta 辅助函数 - OpenAI：提供商构建器、默认模型辅助函数、实时提供商 - OpenRouter：提供商构建器以及新手引导/配置辅助函数 -如果某个辅助函数只在一个内置提供商包内部有用，请将它保留在该包根级抽象层上，而不是将它提升到 `openclaw/plugin-sdk/*` 中。 +如果某个辅助函数只在一个内置提供商包内部有用，请将它保留在该包根级接口上，而不要将其提升到 `openclaw/plugin-sdk/*` 中。 -一些生成的 `openclaw/plugin-sdk/` 辅助抽象层仍然存在，用于内置插件的维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。请将这些视为保留接口，而不是新第三方插件的默认模式。 +一些生成的 `openclaw/plugin-sdk/` 辅助接口仍然存在，用于内置插件维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。请将这些视为保留接口，而不是新第三方插件的默认模式。 ## 提交前检查清单 -**package.json** 具有正确的 `openclaw` 元数据 -**openclaw.plugin.json** 清单文件存在且有效 +**package.json** 包含正确的 `openclaw` 元数据 +**openclaw.plugin.json** 清单文件已存在且有效 入口点使用 `defineChannelPluginEntry` 或 `definePluginEntry` -所有导入都使用精确的 `plugin-sdk/` 路径 +所有导入都使用聚焦的 `plugin-sdk/` 路径 内部导入使用本地模块，而不是 SDK 自导入 测试通过（`pnpm test -- /my-plugin/`） `pnpm check` 通过（仓库内插件） ## Beta 版本测试 -1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签看起来像 `v2026.3.N-beta.1`。你也可以为 OpenClaw 官方 X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以获取发布公告。 -2. 在 beta 标签一出现时，立即针对该 beta 标签测试你的插件。稳定版发布前的窗口期通常只有几个小时。 -3. 测试后，在 Discord 渠道 `plugin-forum` 中你插件所属的帖子里发送 `all good` 或说明哪里出问题了。如果你还没有帖子，就新建一个。 -4. 如果出现问题，请新建或更新一个标题为 `Beta blocker: - ` 的 issue，并添加 `beta-blocker` 标签。把 issue 链接发到你的帖子里。 -5. 向 `main` 提交一个标题为 `fix(): beta blocker - ` 的 PR，并在 PR 和你的 Discord 帖子中都附上该 issue 链接。贡献者不能给 PR 打标签，因此标题就是面向维护者和自动化系统的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题也可能照样发布。维护者会在 beta 测试期间关注这些帖子。 -6. 没有消息就表示一切正常。如果你错过了这个窗口，你的修复很可能会在下一个周期发布。 +1. 在 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上关注 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签通常类似 `v2026.3.N-beta.1`。你也可以为 OpenClaw 官方 X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以获取发布公告。 +2. Beta 标签一出现，就尽快用它测试你的插件。稳定版发布前的窗口期通常只有几个小时。 +3. 测试完成后，在 Discord 频道 `plugin-forum` 中你插件对应的帖子里回复 `all good` 或说明出现了什么问题。如果你还没有帖子，请创建一个。 +4. 如果出现问题，请新建或更新一个标题为 `Beta blocker: - ` 的 issue，并加上 `beta-blocker` 标签。把 issue 链接贴到你的帖子里。 +5. 向 `main` 提交一个标题为 `fix(): beta blocker - ` 的 PR，并在 PR 和你的 Discord 帖子中都链接该 issue。贡献者无法给 PR 打标签，因此这个标题就是面向维护者和自动化的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题也可能照常发布。维护者会在 Beta 测试期间关注这些帖子。 +6. 没有消息就表示一切正常。如果你错过了窗口期，你的修复很可能会在下一个周期发布。 ## 后续步骤 - + 构建一个消息渠道插件 - + 构建一个模型提供商插件 - - 导入映射和注册 API 参考 + + 导入映射与注册 API 参考 - + 通过 api.runtime 使用 TTS、搜索、子智能体 - + 测试工具和模式 - + 完整清单 schema 参考 ## 相关内容 -- [插件架构](/zh-CN/plugins/architecture) — 内部架构深入解析 -- [SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考 +- [Plugin Architecture](/zh-CN/plugins/architecture) — 插件架构内部机制深入解析 +- [SDK Overview](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考 - [Manifest](/zh-CN/plugins/manifest) — 插件清单格式 -- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 -- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 +- [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 +- [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 diff --git a/docs/zh-CN/plugins/google-meet.md b/docs/zh-CN/plugins/google-meet.md index 026e1bc86..a6f6bb336 100644 --- a/docs/zh-CN/plugins/google-meet.md +++ b/docs/zh-CN/plugins/google-meet.md @@ -1,33 +1,33 @@ --- read_when: - - 你希望一个 OpenClaw 智能体加入 Google Meet 通话 + - 你想让一个 OpenClaw 智能体加入 Google Meet 通话 - 你正在将 Chrome、Chrome 节点或 Twilio 配置为 Google Meet 传输方式 summary: Google Meet 插件：通过 Chrome 或 Twilio 加入明确的 Meet URL，并使用实时语音默认设置 title: Google Meet 插件 x-i18n: - generated_at: "2026-04-24T16:21:07Z" + generated_at: "2026-04-24T17:31:16Z" model: gpt-5.4 provider: openai - source_hash: 8ea964b8b5b7d68e3dbd4354b5bbeacce5bbe14b8fe0d703bb5f87c3c7cdff2f + source_hash: 103a54c57c46aa04073f54a210df31d981fe00e60f3a494438ec2597ed52f715 source_path: plugins/google-meet.md workflow: 15 --- -OpenClaw 的 Google Meet 参与者支持 —— 该插件在设计上是显式的： +OpenClaw 的 Google Meet 参与支持——该插件按设计是明确式的： -- 它只会加入明确的 `https://meet.google.com/...` URL。 +- 它只会加入一个明确的 `https://meet.google.com/...` URL。 - `realtime` 语音是默认模式。 -- 当需要更深入的推理或工具时，实时语音可以回调到完整的 OpenClaw 智能体。 -- 认证方式一开始是个人 Google OAuth 或已登录的 Chrome 配置文件。 +- 当需要更深入的推理或工具时，实时语音可以回调完整的 OpenClaw 智能体。 +- 认证起始方式为个人 Google OAuth 或已登录的 Chrome 配置文件。 - 没有自动的同意提示播报。 - 默认的 Chrome 音频后端是 `BlackHole 2ch`。 - Chrome 可以在本地运行，也可以在已配对的节点主机上运行。 - Twilio 接受拨入号码以及可选的 PIN 或 DTMF 序列。 -- CLI 命令是 `googlemeet`；`meet` 保留给更广泛的智能体电话会议工作流。 +- CLI 命令是 `googlemeet`；`meet` 保留给更广泛的智能体电话会议工作流使用。 ## 快速开始 -安装本地音频依赖，并配置一个后端实时语音提供商。OpenAI 是默认选项；Google Gemini Live 也可用，配置为 `realtime.provider: "google"`： +安装本地音频依赖，并配置一个后端实时语音提供商。OpenAI 是默认选项；Google Gemini Live 也可用，只需设置 `realtime.provider: "google"`： ```bash brew install blackhole-2ch sox @@ -36,13 +36,13 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -`blackhole-2ch` 会安装 `BlackHole 2ch` 虚拟音频设备。Homebrew 的安装程序需要重启后，macOS 才会暴露该设备： +`blackhole-2ch` 会安装 `BlackHole 2ch` 虚拟音频设备。Homebrew 的安装程序要求重启后，macOS 才会暴露该设备： ```bash sudo reboot ``` -重启后，验证这两部分是否都已就绪： +重启后，验证这两项都已就绪： ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -85,57 +85,57 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij } ``` -Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，选择 `BlackHole 2ch` 作为 OpenClaw 使用的麦克风/扬声器路径。为了获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的音频图；单个 BlackHole 设备足以完成首次冒烟测试，但可能会产生回声。 +Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，为 OpenClaw 使用的麦克风 / 扬声器路径选择 `BlackHole 2ch`。为了获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的音频图；单个 BlackHole 设备足以完成首次冒烟测试，但可能会产生回声。 ### 本地 Gateway 网关 + Parallels Chrome -你**不**需要在 macOS 虚拟机内运行完整的 OpenClaw Gateway 网关或配置模型 API 密钥，只是为了让虚拟机拥有 Chrome。你可以在本地运行 Gateway 网关和智能体，然后在虚拟机中运行一个节点主机。只需在虚拟机中启用一次内置插件，这样节点就会声明 Chrome 命令： +你**不**需要在 macOS VM 中运行完整的 OpenClaw Gateway 网关或配置模型 API 密钥，仅仅为了让 VM 托管 Chrome。你可以在本地运行 Gateway 网关和智能体，然后在 VM 中运行一个节点主机。只需在 VM 中启用一次内置插件，这样节点就会通告 Chrome 命令： -各组件运行位置如下： +各组件运行位置： -- Gateway 网关主机：OpenClaw Gateway 网关、智能体工作区、模型/API 密钥、实时提供商，以及 Google Meet 插件配置。 -- Parallels macOS 虚拟机：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch，以及一个已登录 Google 的 Chrome 配置文件。 -- 虚拟机中不需要：Gateway 网关服务、智能体配置、OpenAI/GPT 密钥或模型提供商设置。 +- Gateway 网关主机：OpenClaw Gateway 网关、智能体工作区、模型 / API 密钥、实时提供商，以及 Google Meet 插件配置。 +- Parallels macOS VM：OpenClaw CLI / 节点主机、Google Chrome、SoX、BlackHole 2ch，以及一个已登录 Google 的 Chrome 配置文件。 +- VM 中不需要：Gateway 网关服务、智能体配置、OpenAI / GPT 密钥，或模型提供商设置。 -安装虚拟机依赖： +安装 VM 依赖： ```bash brew install blackhole-2ch sox ``` -安装 BlackHole 后重启虚拟机，使 macOS 暴露 `BlackHole 2ch`： +安装 BlackHole 后重启 VM，这样 macOS 才会暴露 `BlackHole 2ch`： ```bash sudo reboot ``` -重启后，验证虚拟机可以看到音频设备和 SoX 命令： +重启后，验证 VM 能看到音频设备和 SoX 命令： ```bash system_profiler SPAudioDataType | grep -i BlackHole command -v rec play ``` -在虚拟机中安装或更新 OpenClaw，然后在那里启用内置插件： +在 VM 中安装或更新 OpenClaw，然后在其中启用内置插件： ```bash openclaw plugins enable google-meet ``` -在虚拟机中启动节点主机： +在 VM 中启动节点主机： ```bash openclaw node run --host --port 18789 --display-name parallels-macos ``` -如果 `` 是局域网 IP 且你未使用 TLS，则节点会拒绝明文 WebSocket，除非你为该受信任的私有网络显式启用： +如果 `` 是一个局域网 IP，且你未使用 TLS，那么除非你为该受信任的私有网络显式启用明文 WebSocket，否则节点会拒绝连接： ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -将节点安装为 LaunchAgent 时，也请使用相同的环境变量： +将该节点作为 LaunchAgent 安装时，也要使用相同的环境变量： ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -143,16 +143,16 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node restart ``` -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是进程环境变量，而不是 `openclaw.json` 设置。`openclaw node install` 会在安装命令中存在该变量时，将其保存到 LaunchAgent 环境中。 +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是进程环境变量，不是 `openclaw.json` 设置。`openclaw node install` 在安装命令存在该变量时，会将其保存到 LaunchAgent 环境中。 -从 Gateway 网关主机批准该节点： +在 Gateway 网关主机上批准该节点： ```bash openclaw devices list openclaw devices approve ``` -确认 Gateway 网关能看到该节点，并且它同时声明了 `googlemeet.chrome` 和浏览器能力/`browser.proxy`： +确认 Gateway 网关能看到该节点，并且它同时通告了 `googlemeet.chrome` 和浏览器能力 / `browser.proxy`： ```bash openclaw nodes status @@ -188,55 +188,57 @@ openclaw nodes status } ``` -现在可以像平常一样从 Gateway 网关主机加入： +现在可以从 Gateway 网关主机正常加入： ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -或者让智能体使用 `google_meet` 工具，并设置 `transport: "chrome-node"`。 +或者要求智能体使用 `google_meet` 工具，并设置 `transport: "chrome-node"`。 -如果你想执行一个单命令冒烟测试，用于创建或复用会话、说出一段已知短语并打印会话健康状态： +如果你想要一个单命令冒烟测试，用于创建或复用会话、说出一段已知短语并打印会话健康状态： ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -如果省略 `chromeNode.node`，只有在恰好有一个已连接节点同时声明 `googlemeet.chrome` 和浏览器控制时，OpenClaw 才会自动选择。如果连接了多个符合条件的节点，请将 `chromeNode.node` 设置为节点 id、显示名称或远程 IP。 +如果浏览器配置文件未登录、Meet 正在等待主持人准入，或者 Chrome 需要麦克风 / 摄像头权限，`join` / `test-speech` 结果会报告 `manualActionRequired: true`，并附带 `manualActionReason` 和 `manualActionMessage`。智能体应停止重试加入，向操作员报告该消息，并仅在浏览器中的手动操作完成后再重试。 + +如果省略 `chromeNode.node`，OpenClaw 只会在恰好有一个已连接节点同时通告 `googlemeet.chrome` 和浏览器控制能力时自动选择。如果连接了多个可用节点，请将 `chromeNode.node` 设置为节点 id、显示名称或远程 IP。 常见故障检查： -- `No connected Google Meet-capable node`：在虚拟机中启动 `openclaw node run`，批准配对，并确保已在虚拟机中运行 `openclaw plugins enable google-meet` 和 `openclaw plugins enable browser`。还要确认 Gateway 网关主机通过 `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` 允许这两个节点命令。 -- `BlackHole 2ch audio device not found on the node`：在虚拟机中安装 `blackhole-2ch` 并重启虚拟机。 -- Chrome 已打开但无法加入：在虚拟机内登录浏览器配置文件，或者保留 `chrome.guestName` 以供访客加入。访客自动加入通过 OpenClaw 的浏览器自动化和节点浏览器代理完成；请确保节点浏览器配置指向你想使用的配置文件，例如 `browser.defaultProfile: "user"` 或某个已命名的现有会话配置文件。 -- Meet 标签页重复：保持启用 `chrome.reuseExistingTab: true`。OpenClaw 会先激活同一 Meet URL 的现有标签页，再打开新标签页。 -- 无音频：在 Meet 中，将麦克风/扬声器路由到 OpenClaw 使用的虚拟音频设备路径；为了获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的路由方式。 +- `No connected Google Meet-capable node`：在 VM 中启动 `openclaw node run`，批准配对，并确保已在 VM 中运行 `openclaw plugins enable google-meet` 和 `openclaw plugins enable browser`。还要确认 Gateway 网关主机通过 `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` 允许了这两个节点命令。 +- `BlackHole 2ch audio device not found on the node`：在 VM 中安装 `blackhole-2ch` 并重启 VM。 +- Chrome 打开了但无法加入：在 VM 内的浏览器配置文件中登录，或者保持设置 `chrome.guestName` 以访客方式加入。访客自动加入会通过节点浏览器代理使用 OpenClaw 浏览器自动化；请确保节点浏览器配置指向你想使用的配置文件，例如 `browser.defaultProfile: "user"` 或一个已存在会话的命名配置文件。 +- 重复的 Meet 标签页：保持启用 `chrome.reuseExistingTab: true`。OpenClaw 会先激活相同 Meet URL 的现有标签页，再打开新标签页。 +- 没有音频：在 Meet 中，将麦克风 / 扬声器路由到 OpenClaw 使用的虚拟音频设备路径；为了获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的路由方式。 ## 安装说明 -Chrome 的实时默认路径使用两个外部工具： +Chrome 实时默认路径使用两个外部工具： -- `sox`：命令行音频工具。该插件使用它的 `rec` 和 `play` 命令来实现默认的 8 kHz G.711 mu-law 音频桥接。 -- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 `BlackHole 2ch` 音频设备，供 Chrome/Meet 路由使用。 +- `sox`：命令行音频工具。该插件使用它的 `rec` 和 `play` 命令作为默认的 8 kHz G.711 mu-law 音频桥接。 +- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 `BlackHole 2ch` 音频设备，供 Chrome / Meet 路由使用。 -OpenClaw 不内置也不分发上述任一软件包。文档要求用户通过 Homebrew 将它们作为主机依赖安装。SoX 的许可证为 `LGPL-2.0-only AND GPL-2.0-only`；BlackHole 为 GPL-3.0。如果你要构建一个将 BlackHole 与 OpenClaw 一起打包的安装器或设备，请审查 BlackHole 上游许可条款，或从 Existential Audio 获取单独授权。 +OpenClaw 不内置也不重新分发这两个软件包。文档要求用户通过 Homebrew 将它们作为主机依赖安装。SoX 的许可证为 `LGPL-2.0-only AND GPL-2.0-only`；BlackHole 为 GPL-3.0。如果你构建了一个将 BlackHole 与 OpenClaw 一起打包的安装器或一体机，请审查 BlackHole 上游许可条款，或从 Existential Audio 获取单独许可证。 ## 传输方式 ### Chrome -Chrome 传输会在 Google Chrome 中打开 Meet URL，并以已登录的 Chrome 配置文件身份加入。在 macOS 上，该插件会在启动前检查是否存在 `BlackHole 2ch`。如果已配置，它还会在打开 Chrome 之前运行音频桥接健康检查命令和启动命令。当 Chrome/音频运行在 Gateway 网关主机上时，请使用 `chrome`；当 Chrome/音频运行在已配对节点上，例如 Parallels macOS 虚拟机时，请使用 `chrome-node`。 +Chrome 传输会在 Google Chrome 中打开 Meet URL，并以已登录的 Chrome 配置文件身份加入。在 macOS 上，插件会在启动前检查 `BlackHole 2ch`。如果已配置，它还会在打开 Chrome 前运行音频桥健康检查命令和启动命令。当 Chrome / 音频运行在 Gateway 网关主机上时使用 `chrome`；当 Chrome / 音频运行在已配对节点（如 Parallels macOS VM）上时使用 `chrome-node`。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -将 Chrome 的麦克风和扬声器音频通过本地 OpenClaw 音频桥进行路由。如果未安装 `BlackHole 2ch`，加入操作会因设置错误而失败，而不是在没有音频路径的情况下静默加入。 +将 Chrome 的麦克风和扬声器音频路由到本地 OpenClaw 音频桥。如果未安装 `BlackHole 2ch`，加入操作会以设置错误失败，而不是静默加入却没有音频路径。 ### Twilio -Twilio 传输是一个严格的拨号计划，并委托给 Voice Call 插件处理。它不会解析 Meet 页面中的电话号码。 +Twilio 传输是一个严格的拨号计划，并委托给 Voice Call 插件执行。它不会解析 Meet 页面中的电话号码。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -256,21 +258,22 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ ## OAuth 和预检 -Google Meet Media API 访问首先使用个人 OAuth 客户端。配置 `oauth.clientId`，并可选配置 `oauth.clientSecret`，然后运行： +Google Meet Media API 访问优先使用个人 OAuth 客户端。配置 `oauth.clientId`，并可选配置 `oauth.clientSecret`，然后运行： ```bash openclaw googlemeet auth login --json ``` -该命令会打印一个包含刷新令牌的 `oauth` 配置块。它使用 PKCE、本地主机回调 `http://localhost:8085/oauth2callback`，并支持通过 `--manual` 进行手动复制/粘贴流程。 +该命令会打印一个包含刷新令牌的 `oauth` 配置块。它使用 PKCE、位于 `http://localhost:8085/oauth2callback` 的 localhost 回调，以及通过 `--manual` 启用的手动复制 / 粘贴流程。 -以下环境变量可作为后备： +支持以下环境变量作为回退： - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID` - `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` 或 `GOOGLE_MEET_CLIENT_SECRET` - `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` 或 `GOOGLE_MEET_REFRESH_TOKEN` - `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN` 或 `GOOGLE_MEET_ACCESS_TOKEN` -- `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` 或 `GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` +- `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` 或 + `GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` - `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` 或 `GOOGLE_MEET_DEFAULT_MEETING` - `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` 或 `GOOGLE_MEET_PREVIEW_ACK` @@ -280,17 +283,17 @@ openclaw googlemeet auth login --json openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -在进行媒体相关工作前运行预检： +在处理媒体之前运行预检： ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij ``` -只有在确认你的 Cloud 项目、OAuth 主体以及会议参与者都已加入 Google Workspace Developer Preview Program for Meet media APIs 之后，才将 `preview.enrollmentAcknowledged: true` 设为 true。 +只有在确认你的 Cloud 项目、OAuth 主体和会议参与者都已加入 Google Workspace Developer Preview Program for Meet media APIs 后，才设置 `preview.enrollmentAcknowledged: true`。 ## 配置 -常见的 Chrome 实时路径只需要启用该插件、安装 BlackHole、SoX，以及提供后端实时语音提供商密钥。OpenAI 是默认选项；要使用 Google Gemini Live，请设置 `realtime.provider: "google"`： +常见的 Chrome 实时路径只需要启用插件、安装 BlackHole、SoX，以及配置一个后端实时语音提供商密钥。OpenAI 是默认选项；设置 `realtime.provider: "google"` 可使用 Google Gemini Live： ```bash brew install blackhole-2ch sox @@ -318,18 +321,18 @@ export GEMINI_API_KEY=... - `defaultTransport: "chrome"` - `defaultMode: "realtime"` -- `chromeNode.node`：`chrome-node` 的可选节点 id/名称/IP +- `chromeNode.node`：用于 `chrome-node` 的可选节点 id / 名称 / IP - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`：在未登录的 Meet 访客界面使用的名称 -- `chrome.autoJoin: true`：在 `chrome-node` 上通过 OpenClaw 浏览器自动化尽力填写访客名称并点击立即加入 -- `chrome.reuseExistingTab: true`：激活现有 Meet 标签页而不是打开重复标签页 -- `chrome.waitForInCallMs: 20000`：等待 Meet 标签页报告已进入通话，然后再触发实时介绍 +- `chrome.guestName: "OpenClaw Agent"`：在未登录的 Meet 访客界面上使用的名称 +- `chrome.autoJoin: true`：通过 OpenClaw 浏览器自动化，在 `chrome-node` 上尽力填写访客名并点击 “立即加入” +- `chrome.reuseExistingTab: true`：激活现有 Meet 标签页，而不是打开重复标签页 +- `chrome.waitForInCallMs: 20000`：在触发实时介绍消息之前，等待 Meet 标签页报告已进入通话 - `chrome.audioInputCommand`：将 8 kHz G.711 mu-law 音频写入 stdout 的 SoX `rec` 命令 - `chrome.audioOutputCommand`：从 stdin 读取 8 kHz G.711 mu-law 音频的 SoX `play` 命令 - `realtime.provider: "openai"` - `realtime.toolPolicy: "safe-read-only"` -- `realtime.instructions`：简短的口头回复，较深入的问题使用 `openclaw_agent_consult` -- `realtime.introMessage`：实时桥接连接时的简短口头就绪检查；将其设置为 `""` 可静默加入 +- `realtime.instructions`：简短的语音回复，较深入的回答通过 `openclaw_agent_consult` +- `realtime.introMessage`：实时桥接连接时的简短语音就绪检查；将其设为 `""` 可静默加入 可选覆盖项： @@ -349,7 +352,7 @@ export GEMINI_API_KEY=... realtime: { provider: "google", toolPolicy: "owner", - introMessage: "准确地说：我在这里。", + introMessage: "Say exactly: I'm here.", providers: { google: { model: "gemini-2.5-flash-native-audio-preview-12-2025", @@ -360,7 +363,7 @@ export GEMINI_API_KEY=... } ``` -仅限 Twilio 的配置： +仅适用于 Twilio 的配置： ```json5 { @@ -388,30 +391,31 @@ export GEMINI_API_KEY=... } ``` -当 Chrome 运行在 Gateway 网关主机上时，使用 `transport: "chrome"`。当 Chrome 运行在已配对节点上（例如 Parallels 虚拟机）时，使用 `transport: "chrome-node"`。在这两种情况下，实时模型和 `openclaw_agent_consult` 都运行在 Gateway 网关主机上，因此模型凭证会保留在那里。 +当 Chrome 运行在 Gateway 网关主机上时，使用 `transport: "chrome"`。当 Chrome 运行在已配对节点（例如 Parallels VM）上时，使用 `transport: "chrome-node"`。在这两种情况下，实时模型和 `openclaw_agent_consult` 都运行在 Gateway 网关主机上，因此模型凭证会保留在那里。 -使用 `action: "status"` 可列出活动会话或检查某个会话 ID。使用带有 `sessionId` 和 `message` 的 `action: "speak"` 可让实时智能体立即发言。使用 `action: "test_speech"` 可创建或复用会话、触发一段已知短语，并在 Chrome 主机能够报告时返回 `inCall` 健康状态。使用 `action: "leave"` 可将会话标记为已结束。 +使用 `action: "status"` 可列出活动会话，或检查某个会话 ID。使用带有 `sessionId` 和 `message` 的 `action: "speak"` 可让实时智能体立即发声。使用 `action: "test_speech"` 可创建或复用会话，触发一段已知短语，并在 Chrome 主机能够报告时返回 `inCall` 健康状态。使用 `action: "leave"` 可将会话标记为已结束。 -`status` 在可用时包含 Chrome 健康状态： +`status` 在可用时会包含 Chrome 健康状态： - `inCall`：Chrome 看起来已进入 Meet 通话 - `micMuted`：尽力检测的 Meet 麦克风状态 -- `providerConnected` / `realtimeReady`：实时语音桥接状态 +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、等待 Meet 主持人准入、授予权限，或修复浏览器控制后语音功能才能工作 +- `providerConnected` / `realtimeReady`：实时语音桥状态 - `lastInputAt` / `lastOutputAt`：桥接最近一次接收或发送音频的时间 ```json { "action": "speak", "sessionId": "meet_...", - "message": "准确地说：我在这里，并且正在聆听。" + "message": "Say exactly: I'm here and listening." } ``` ## 实时智能体咨询 -Chrome 实时模式针对实时语音循环进行了优化。实时语音提供商会收听会议音频，并通过配置的音频桥进行发言。当实时模型需要更深入的推理、最新信息或常规 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。 +Chrome 实时模式针对实时语音循环进行了优化。实时语音提供商会听取会议音频，并通过已配置的音频桥发声。当实时模型需要更深入的推理、最新信息或常规 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。 -咨询工具会在后台运行常规 OpenClaw 智能体，附带最近的会议转录上下文，并向实时语音会话返回简洁的口头回答。然后，语音模型就可以将该回答说回会议中。 +咨询工具会在后台运行常规 OpenClaw 智能体，并带上最近的会议转录上下文，然后向实时语音会话返回一个简洁的口头回答。语音模型随后可以将该回答说回会议中。 `realtime.toolPolicy` 控制咨询运行方式： @@ -419,15 +423,15 @@ Chrome 实时模式针对实时语音循环进行了优化。实时语音提供 - `owner`：暴露咨询工具，并允许常规智能体使用正常的智能体工具策略。 - `none`：不向实时语音模型暴露咨询工具。 -咨询会话键按每个 Meet 会话进行作用域划分，因此在同一场会议中，后续咨询调用可以复用之前的咨询上下文。 +咨询会话键按 Meet 会话划分作用域，因此在同一场会议期间，后续咨询调用可以复用先前的咨询上下文。 -若要在 Chrome 完全加入通话后强制执行一次口头就绪检查： +如果要在 Chrome 完全加入通话后强制执行语音就绪检查： ```bash openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -若要执行完整的加入并发言冒烟测试： +用于完整的加入并发声冒烟测试： ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -437,16 +441,16 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ ## 说明 -Google Meet 的官方媒体 API 偏向接收，因此要在 Meet 通话中发言，仍然需要一个参与者路径。该插件让这一边界保持清晰可见：Chrome 负责浏览器参与和本地音频路由；Twilio 负责电话拨入参与。 +Google Meet 的官方媒体 API 偏向接收模式，因此要在 Meet 通话中发声，仍然需要一个参与者路径。该插件将这一边界保持为可见状态：Chrome 负责浏览器参与和本地音频路由；Twilio 负责电话拨入参与。 -Chrome 实时模式需要以下二者之一： +Chrome 实时模式需要以下两者之一： -- `chrome.audioInputCommand` 加 `chrome.audioOutputCommand`：OpenClaw 负责实时模型桥接，并在这些命令与所选实时语音提供商之间传输 8 kHz G.711 mu-law 音频。 -- `chrome.audioBridgeCommand`：一个外部桥接命令负责整个本地音频路径，并且必须在启动或验证其守护进程后退出。 +- `chrome.audioInputCommand` 加上 `chrome.audioOutputCommand`：OpenClaw 自行管理实时模型桥，并在这些命令与所选实时语音提供商之间传输 8 kHz G.711 mu-law 音频。 +- `chrome.audioBridgeCommand`：由外部桥接命令管理整个本地音频路径，并且必须在启动或验证其守护进程后退出。 -为了获得干净的双工音频，请将 Meet 输出和 Meet 麦克风路由到独立的虚拟设备，或使用类似 Loopback 的虚拟设备图。单个共享的 BlackHole 设备可能会将其他参与者的声音回传到通话中。 +为了获得干净的双工音频，请将 Meet 输出和 Meet 麦克风分别路由到不同的虚拟设备，或使用类似 Loopback 的虚拟设备图。单个共享的 BlackHole 设备可能会把其他参与者的声音回放进通话中。 -`googlemeet speak` 会触发 Chrome 会话的活动实时音频桥。`googlemeet leave` 会停止该桥。对于通过 Voice Call 插件委托的 Twilio 会话，`leave` 还会挂断底层语音通话。 +`googlemeet speak` 会触发 Chrome 会话的活动实时音频桥。`googlemeet leave` 会停止该桥。对于通过 Voice Call 插件委托的 Twilio 会话，`leave` 也会挂断底层语音通话。 ## 相关内容 diff --git a/docs/zh-CN/plugins/hooks.md b/docs/zh-CN/plugins/hooks.md new file mode 100644 index 000000000..c29e1dd22 --- /dev/null +++ b/docs/zh-CN/plugins/hooks.md @@ -0,0 +1,176 @@ +--- +read_when: + - 你正在构建一个插件，需要 `before_tool_call`、`before_agent_reply`、消息钩子或生命周期钩子 + - 你需要从插件中阻止、重写或要求批准工具调用 + - 你正在在内部钩子和插件钩子之间做选择 +summary: 插件钩子：拦截智能体、工具、消息、会话以及 Gateway 网关生命周期事件 +title: 插件钩子 +x-i18n: + generated_at: "2026-04-24T17:31:11Z" + model: gpt-5.4 + provider: openai + source_hash: 9e25ad31350ca129e99a7e6ec42ee699857b8aaa016479bd1f79be32a37784b4 + source_path: plugins/hooks.md + workflow: 15 +--- + +插件钩子是 OpenClaw 插件的进程内扩展点。当插件需要检查或更改智能体运行、工具调用、消息流、会话生命周期、子智能体路由、安装流程或 Gateway 网关启动时，请使用它们。 + +如果你想要一个由运维人员安装的小型 `HOOK.md` 脚本来处理命令和 Gateway 网关事件，例如 `/new`、`/reset`、`/stop`、`agent:bootstrap` 或 `gateway:startup`，请改用 [内部钩子](/zh-CN/automation/hooks)。 + +## 快速开始 + +在你的插件入口中，使用 `api.on(...)` 注册类型化的插件钩子： + +```typescript +import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; + +export default definePluginEntry({ + id: "tool-preflight", + name: "Tool Preflight", + register(api) { + api.on( + "before_tool_call", + async (event) => { + if (event.toolName !== "web_search") { + return; + } + + return { + requireApproval: { + title: "Run web search", + description: `Allow search query: ${String(event.params.query ?? "")}`, + severity: "info", + timeoutMs: 60_000, + timeoutBehavior: "deny", + }, + }; + }, + { priority: 50 }, + ); + }, +}); +``` + +钩子处理器会按 `priority` 的降序依次运行。相同优先级的钩子会保持注册顺序。 + +## 常见钩子 + +| Hook | 用途 | +| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| `before_tool_call` | 在工具运行前重写工具参数、阻止执行或请求用户批准。 | +| `after_tool_call` | 在执行后观察工具结果、错误和耗时。 | +| `before_prompt_build` | 在模型调用前添加动态上下文或系统提示词文本。 | +| `before_model_resolve` | 在加载会话消息前覆盖提供商或模型。 | +| `before_agent_reply` | 使用合成回复或静默来短路模型轮次。 | +| `llm_input` / `llm_output` | 为具备会话感知能力的插件观察提供商输入/输出。 | +| `agent_end` | 观察最终消息、成功状态和运行时长。 | +| `message_received` | 在渠道解析后观察传入的渠道消息。 | +| `message_sending` | 重写或取消发出的渠道消息。 | +| `message_sent` | 观察发出消息的最终成功或失败状态。 | +| `session_start` / `session_end` | 跟踪会话生命周期边界。 | +| `before_compaction` / `after_compaction` | 观察或注释压缩周期。 | +| `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` | 协调子智能体路由和完成结果的投递。 | +| `gateway_start` / `gateway_stop` | 随 Gateway 网关一起启动或停止插件服务。 | +| `before_install` | 检查 Skills 或插件安装扫描，并可选择阻止安装。 | + +## 工具调用策略 + +`before_tool_call` 会接收： + +- `event.toolName` +- `event.params` +- 可选的 `event.runId` +- 可选的 `event.toolCallId` +- 上下文字段，例如 `ctx.agentId`、`ctx.sessionKey`、`ctx.sessionId`，以及诊断信息 `ctx.trace` + +它可以返回： + +```typescript +type BeforeToolCallResult = { + params?: Record; + block?: boolean; + blockReason?: string; + requireApproval?: { + title: string; + description: string; + severity?: "info" | "warning" | "critical"; + timeoutMs?: number; + timeoutBehavior?: "allow" | "deny"; + onResolution?: (decision: string) => Promise | void; + }; +}; +``` + +规则： + +- `block: true` 是终止性决定，并会跳过更低优先级的处理器。 +- `block: false` 会被视为未作决定。 +- `params` 会重写执行时使用的工具参数。 +- `requireApproval` 会暂停智能体运行，并通过插件批准机制向用户发起请求。`/approve` 命令既可以批准 exec 批准，也可以批准插件批准。 +- 即使高优先级钩子请求了批准，低优先级的 `block: true` 仍然可以阻止执行。 + +## 提示词和模型钩子 + +新插件请使用特定阶段的钩子： + +- `before_model_resolve`：只接收当前提示词和附件元数据。返回 `providerOverride` 或 `modelOverride`。 +- `before_prompt_build`：接收当前提示词和会话消息。返回 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。 + +`before_agent_start` 仍然保留以兼容旧用法。优先使用上面这些明确的钩子，这样你的插件就不必依赖旧版的组合阶段。 + +需要使用 `llm_input`、`llm_output` 或 `agent_end` 的非内置插件必须设置： + +```json +{ + "plugins": { + "entries": { + "my-plugin": { + "hooks": { + "allowConversationAccess": true + } + } + } + } +} +``` + +修改提示词的钩子可以按插件通过 `plugins.entries..hooks.allowPromptInjection=false` 禁用。 + +## 消息钩子 + +对于渠道级路由和投递策略，请使用消息钩子： + +- `message_received`：观察传入内容、发送者、`threadId` 和元数据。 +- `message_sending`：重写 `content` 或返回 `{ cancel: true }`。 +- `message_sent`：观察最终成功或失败状态。 + +在使用渠道特定元数据之前，优先使用类型化的 `threadId` 和 `replyToId` 字段。 + +决策规则： + +- 带有 `cancel: true` 的 `message_sending` 是终止性决定。 +- 带有 `cancel: false` 的 `message_sending` 会被视为未作决定。 +- 被重写的 `content` 会继续传递给更低优先级的钩子，除非后续钩子取消投递。 + +## 安装钩子 + +`before_install` 会在内置的 Skills 和插件安装扫描完成后运行。 + +返回附加发现结果，或返回 `{ block: true, blockReason }` 来停止安装。 + +`block: true` 是终止性决定。`block: false` 会被视为未作决定。 + +## Gateway 网关生命周期 + +对于需要依赖 Gateway 网关所拥有状态的插件服务，请使用 `gateway_start`。上下文会暴露 `ctx.config`、`ctx.workspaceDir` 以及用于检查和更新 cron 的 `ctx.getCron?.()`。使用 `gateway_stop` 清理长期运行的资源。 + +不要依赖内部的 `gateway:startup` 钩子来运行由插件拥有的运行时服务。 + +## 相关内容 + +- [构建插件](/zh-CN/plugins/building-plugins) +- [插件 SDK 概览](/zh-CN/plugins/sdk-overview) +- [插件入口点](/zh-CN/plugins/sdk-entrypoints) +- [内部钩子](/zh-CN/automation/hooks) +- [插件架构内部机制](/zh-CN/plugins/architecture-internals) diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index c2c2ab5b0..49b565522 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -1,121 +1,120 @@ --- read_when: - 你需要知道应从哪个 SDK 子路径导入 - - 你想要一份 OpenClawPluginApi 上所有注册方法的参考文档 + - 你想查看 OpenClawPluginApi 上所有注册方法的参考说明 - 你正在查找某个特定的 SDK 导出项 sidebarTitle: SDK overview summary: 导入映射、注册 API 参考和 SDK 架构 title: 插件 SDK 概览 x-i18n: - generated_at: "2026-04-24T06:33:28Z" + generated_at: "2026-04-24T17:31:14Z" model: gpt-5.4 provider: openai - source_hash: 7f4209c245a3d3462c5d5f51ad3c6e4327240ed402fdbac3f01f8a761ba75233 + source_hash: 3a70b8241344da739b738d1cd6b4754f013212c752d6ca4d9f052d68f0ce8c30 source_path: plugins/sdk-overview.md workflow: 15 --- -插件 SDK 是插件与核心之间的类型化契约。本页是关于**该导入什么**以及**你可以注册什么**的参考文档。 +插件 SDK 是插件与核心之间的类型化契约。本页是关于**导入什么**以及**你可以注册什么**的参考。 - 想找操作指南而不是参考文档？ + 在找操作指南而不是参考页？ -- 第一个插件？从 [构建插件](/zh-CN/plugins/building-plugins) 开始。 -- 渠道插件？参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。 -- 提供商插件？参见 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 +- 第一个插件？从[构建插件](/zh-CN/plugins/building-plugins)开始。 +- 渠道插件？参见[渠道插件](/zh-CN/plugins/sdk-channel-plugins)。 +- 提供商插件？参见[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 +- 工具或生命周期钩子插件？参见[插件钩子](/zh-CN/plugins/hooks)。 ## 导入约定 -始终从特定子路径导入： +始终从特定的子路径导入： ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -每个子路径都是一个小型、独立的模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口点 / 构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总入口 surface 和共享辅助函数，例如 `buildChannelConfigSchema`。 +每个子路径都是一个小型、独立的模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的汇总表面和共享辅助工具，例如 `buildChannelConfigSchema`。 - 不要导入带有 provider 或 channel 品牌的便捷 seam（例如 - `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。 + 不要导入带有提供商或渠道品牌的便捷接缝层（例如 `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。 内置插件会在它们自己的 `api.ts` / - `runtime-api.ts` barrel 中组合通用 SDK 子路径；核心使用方应当使用这些插件本地的 - barrel，或者在需求确实跨渠道时添加一个窄化的通用 SDK 契约。 + `runtime-api.ts` barrel 中组合通用 SDK 子路径；核心使用方应使用这些插件本地的 + barrel，或者在需求确实跨渠道时添加一个狭义的通用 SDK 契约。 -生成的导出映射中仍然会出现少量内置插件辅助 seam（`plugin-sdk/feishu`、 -`plugin-sdk/zalo`、`plugin-sdk/matrix*` 及类似项）。它们仅供内置插件维护使用， +生成的导出映射中仍然会出现一小部分内置插件辅助接缝层（`plugin-sdk/feishu`、 +`plugin-sdk/zalo`、`plugin-sdk/matrix*` 及类似项）。它们仅用于维护内置插件， 不推荐作为新的第三方插件的导入路径。 ## 子路径参考 -插件 SDK 以一组按领域分组的窄化子路径形式公开（插件入口、渠道、提供商、认证、运行时、能力、内存，以及保留给内置插件辅助函数的路径）。如需查看按组分类并带链接的完整目录，请参见 -[插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。 +插件 SDK 以一组按领域分组的狭义子路径形式公开（插件入口、渠道、提供商、认证、运行时、能力、内存，以及保留给内置插件的辅助工具）。如需完整目录——按组分类并带链接——请参见[插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。 -这份包含 200 多个子路径的生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 +包含 200 多个子路径的生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 ## 注册 API -`register(api)` 回调会收到一个带有以下方法的 `OpenClawPluginApi` 对象： +`register(api)` 回调会收到一个包含以下方法的 `OpenClawPluginApi` 对象： ### 能力注册 -| 方法 | 注册内容 | -| ------------------------------------------------ | ----------------------------- | -| `api.registerProvider(...)` | 文本推理（LLM） | -| `api.registerAgentHarness(...)` | 实验性的底层智能体执行器 | -| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | -| `api.registerChannel(...)` | 消息渠道 | -| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | -| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 | -| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 | -| `api.registerMediaUnderstandingProvider(...)` | 图像 / 音频 / 视频分析 | -| `api.registerImageGenerationProvider(...)` | 图像生成 | -| `api.registerMusicGenerationProvider(...)` | 音乐生成 | -| `api.registerVideoGenerationProvider(...)` | 视频生成 | -| `api.registerWebFetchProvider(...)` | 网页抓取 / 抓取内容提供商 | -| `api.registerWebSearchProvider(...)` | Web 搜索 | +| 方法 | 注册内容 | +| ------------------------------------------------ | --------------------------- | +| `api.registerProvider(...)` | 文本推理（LLM） | +| `api.registerAgentHarness(...)` | 实验性的低层级智能体执行器 | +| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | +| `api.registerChannel(...)` | 消息渠道 | +| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | +| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转写 | +| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 | +| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 | +| `api.registerImageGenerationProvider(...)` | 图像生成 | +| `api.registerMusicGenerationProvider(...)` | 音乐生成 | +| `api.registerVideoGenerationProvider(...)` | 视频生成 | +| `api.registerWebFetchProvider(...)` | Web 抓取 / 爬取提供商 | +| `api.registerWebSearchProvider(...)` | Web 搜索 | ### 工具和命令 | 方法 | 注册内容 | | ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） | +| `api.registerTool(tool, opts?)` | 智能体工具（必需，或 `{ optional: true }`） | | `api.registerCommand(def)` | 自定义命令（绕过 LLM） | ### 基础设施 -| 方法 | 注册内容 | -| ----------------------------------------------- | ------------------------------------- | -| `api.registerHook(events, handler, opts?)` | 事件 hook | -| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | -| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | -| `api.registerGatewayDiscoveryService(service)` | 本地 Gateway 网关发现广播服务 | -| `api.registerCli(registrar, opts?)` | CLI 子命令 | -| `api.registerService(service)` | 后台服务 | -| `api.registerInteractiveHandler(registration)` | 交互式处理器 | -| `api.registerEmbeddedExtensionFactory(factory)` | Pi 嵌入式运行器扩展工厂 | -| `api.registerMemoryPromptSupplement(builder)` | 增量式内存相邻提示区段 | -| `api.registerMemoryCorpusSupplement(adapter)` | 增量式内存搜索 / 读取语料库 | +| 方法 | 注册内容 | +| ----------------------------------------------- | ---------------------------------- | +| `api.registerHook(events, handler, opts?)` | 事件钩子 | +| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | +| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | +| `api.registerGatewayDiscoveryService(service)` | 本地 Gateway 网关发现广播器 | +| `api.registerCli(registrar, opts?)` | CLI 子命令 | +| `api.registerService(service)` | 后台服务 | +| `api.registerInteractiveHandler(registration)` | 交互处理器 | +| `api.registerEmbeddedExtensionFactory(factory)` | Pi 嵌入式运行器扩展工厂 | +| `api.registerMemoryPromptSupplement(builder)` | 追加型内存邻近提示词片段 | +| `api.registerMemoryCorpusSupplement(adapter)` | 追加型内存搜索/读取语料库 | - 保留给核心管理用途的命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、 - `update.*`）始终保持为 `operator.admin`，即使插件试图为 Gateway 网关方法分配更窄的 - scope 也是如此。对于由插件拥有的方法，优先使用插件特定的前缀。 + 保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、 + `update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 + Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用插件专属前缀。 - 当插件需要在 OpenClaw 嵌入式运行期间使用 Pi 原生事件时序时，请使用 `api.registerEmbeddedExtensionFactory(...)`——例如必须在最终工具结果消息发出前完成的异步 `tool_result` - 重写。 + 当插件在 OpenClaw 嵌入式运行期间需要 Pi 原生事件时序时，使用 `api.registerEmbeddedExtensionFactory(...)`——例如，必须在最终工具结果消息发出之前完成的异步 `tool_result` 重写。 -这目前是一个内置插件 seam：只有内置插件可以注册它，并且它们必须在 -`openclaw.plugin.json` 中声明 `contracts.embeddedExtensionFactories: ["pi"]`。对于不需要这种更底层 seam 的所有场景，请继续使用普通的 OpenClaw 插件 hook。 +这是当前仅供内置插件使用的接缝层：只有内置插件可以注册它，并且它们必须在 +`openclaw.plugin.json` 中声明 `contracts.embeddedExtensionFactories: ["pi"]`。 +对于不需要该更低层级接缝层的场景，继续使用普通的 OpenClaw 插件钩子。 ### Gateway 网关发现注册 -`api.registerGatewayDiscoveryService(...)` 允许插件在本地发现传输协议（例如 mDNS/Bonjour）上广播活动中的 Gateway 网关。启用本地发现时，OpenClaw 会在 Gateway 网关启动期间调用该服务，传入当前 Gateway 网关端口和非机密 TXT 提示数据，并在 Gateway 网关关闭期间调用返回的 `stop` 处理器。 +`api.registerGatewayDiscoveryService(...)` 允许插件在本地发现传输协议（如 mDNS/Bonjour）上广播活动中的 Gateway 网关。启用本地发现时，OpenClaw 会在 Gateway 网关启动期间调用该服务，传入当前 Gateway 网关端口和非机密的 TXT 提示数据，并在 Gateway 网关关闭期间调用返回的 `stop` 处理器。 ```typescript api.registerGatewayDiscoveryService({ @@ -131,16 +130,16 @@ api.registerGatewayDiscoveryService({ }); ``` -Gateway 网关发现插件不得将已广播的 TXT 值视为机密信息或认证手段。设备发现只是路由提示；Gateway 网关认证和 TLS pinning 仍然负责信任控制。 +Gateway 网关发现插件不得将广播的 TXT 值视为机密信息或认证信息。设备发现只是路由提示；Gateway 网关认证和 TLS 固定仍然负责信任。 ### CLI 注册元数据 `api.registerCli(registrar, opts?)` 接受两类顶层元数据： -- `commands`：由 registrar 拥有的显式命令根 -- `descriptors`：在解析阶段使用的命令描述符，用于根 CLI 帮助、路由和懒加载插件 CLI 注册 +- `commands`：由注册器拥有的显式命令根 +- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析期命令描述符 -如果你希望插件命令在普通根 CLI 路径中保持懒加载，请提供 `descriptors`，覆盖该 registrar 暴露的每个顶层命令根。 +如果你希望插件命令在常规根 CLI 路径中保持延迟加载，请提供 `descriptors`，覆盖该注册器公开的每个顶层命令根。 ```typescript api.registerCli( @@ -152,7 +151,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "管理 Matrix 账号、验证、设备和资料状态", + description: "管理 Matrix 账户、验证、设备和个人资料状态", hasSubcommands: true, }, ], @@ -160,90 +159,90 @@ api.registerCli( ); ``` -只有在你不需要懒加载根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会安装基于 descriptor 的占位符来实现解析阶段的懒加载。 +仅在你不需要延迟根 CLI 注册时才单独使用 `commands`。这种预加载兼容路径仍受支持，但它不会为解析期延迟加载安装基于描述符的占位符。 ### CLI 后端注册 `api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。 -- 后端 `id` 会成为像 `codex-cli/gpt-5` 这样的模型引用中的 provider 前缀。 +- 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。 - 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的结构。 -- 用户配置仍然优先生效。OpenClaw 会先将 `agents.defaults.cliBackends.` 合并到插件默认值之上，然后再运行 CLI。 -- 当后端在合并后需要进行兼容性重写时，使用 `normalizeConfig`（例如规范化旧版 flag 结构）。 +- 用户配置仍然优先生效。OpenClaw 会先将 `agents.defaults.cliBackends.` 合并到插件默认值之上，再运行 CLI。 +- 当后端在合并后需要进行兼容性重写时，使用 `normalizeConfig`（例如规范化旧的标志结构）。 ### 独占槽位 | 方法 | 注册内容 | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅激活一个）。`assemble()` 回调会收到 `availableTools` 和 `citationsMode`，这样引擎就可以定制提示补充内容。 | +| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个处于活动状态）。`assemble()` 回调会收到 `availableTools` 和 `citationsMode`，以便引擎可以定制提示词追加内容。 | | `api.registerMemoryCapability(capability)` | 统一内存能力 | -| `api.registerMemoryPromptSection(builder)` | 内存提示区段构建器 | +| `api.registerMemoryPromptSection(builder)` | 内存提示词片段构建器 | | `api.registerMemoryFlushPlan(resolver)` | 内存刷新计划解析器 | | `api.registerMemoryRuntime(runtime)` | 内存运行时适配器 | ### 内存嵌入适配器 -| 方法 | 注册内容 | -| ---------------------------------------------- | ------------------------------------ | -| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的内存嵌入适配器 | +| 方法 | 注册内容 | +| ---------------------------------------------- | ----------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的内存嵌入适配器 | -- `registerMemoryCapability` 是首选的独占式内存插件 API。 -- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`， - 以便配套插件通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的内存制品， - 而不是深入访问特定内存插件的私有布局。 +- `registerMemoryCapability` 是首选的独占内存插件 API。 +- `registerMemoryCapability` 还可以公开 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的内存工件，而不必深入特定内存插件的私有布局。 - `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 - `registerMemoryRuntime` 是兼容旧版的独占式内存插件 API。 -- `registerMemoryEmbeddingProvider` 允许活动内存插件注册一个或多个嵌入适配器 id（例如 `openai`、`gemini` 或插件自定义 id）。 + `registerMemoryRuntime` 是兼容旧版的独占内存插件 API。 +- `registerMemoryEmbeddingProvider` 允许活动内存插件注册一个或多个嵌入适配器 ID（例如 `openai`、`gemini` 或自定义的插件定义 ID）。 - 用户配置（例如 `agents.defaults.memorySearch.provider` 和 - `agents.defaults.memorySearch.fallback`）会根据这些已注册的适配器 id 进行解析。 + `agents.defaults.memorySearch.fallback`）会根据这些已注册的适配器 ID 进行解析。 -### 事件与生命周期 +### 事件和生命周期 -| 方法 | 作用 | -| -------------------------------------------- | --------------------- | -| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook | -| `api.onConversationBindingResolved(handler)` | 会话绑定回调 | +| 方法 | 作用 | +| -------------------------------------------- | ----------------------- | +| `api.on(hookName, handler, opts?)` | 类型化生命周期钩子 | +| `api.onConversationBindingResolved(handler)` | 会话绑定回调 | -### Hook 决策语义 +有关示例、常见钩子名称和守卫语义，请参见[插件钩子](/zh-CN/plugins/hooks)。 -- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任一处理器设置了它，就会跳过优先级更低的处理器。 -- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 -- `before_install`：返回 `{ block: true }` 是终止性的。一旦任一处理器设置了它，就会跳过优先级更低的处理器。 -- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 -- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任一处理器声明已分发，就会跳过优先级更低的处理器以及默认的模型分发路径。 -- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任一处理器设置了它，就会跳过优先级更低的处理器。 -- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。 -- `message_received`：当你需要入站线程 / 话题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的额外信息。 +### 钩子决策语义 + +- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置了它，就会跳过更低优先级的处理器。 +- `before_tool_call`：返回 `{ block: false }` 会被视为未作出决定（等同于省略 `block`），而不是覆盖。 +- `before_install`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置了它，就会跳过更低优先级的处理器。 +- `before_install`：返回 `{ block: false }` 会被视为未作出决定（等同于省略 `block`），而不是覆盖。 +- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任意处理器声明已处理分发，就会跳过更低优先级的处理器以及默认的模型分发路径。 +- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任意处理器设置了它，就会跳过更低优先级的处理器。 +- `message_sending`：返回 `{ cancel: false }` 会被视为未作出决定（等同于省略 `cancel`），而不是覆盖。 +- `message_received`：当你需要传入线程/话题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的附加信息。 - `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到渠道特定的 `metadata`。 -- `gateway_start`：使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 表示由 Gateway 网关拥有的启动状态，而不要依赖内部 `gateway:startup` hook。 +- `gateway_start`：使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 获取 Gateway 网关自有的启动状态，而不要依赖内部 `gateway:startup` 钩子。 ### API 对象字段 -| 字段 | 类型 | 说明 | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | 插件 id | -| `api.name` | `string` | 显示名称 | -| `api.version` | `string?` | 插件版本（可选） | -| `api.description` | `string?` | 插件描述（可选） | -| `api.source` | `string` | 插件源路径 | -| `api.rootDir` | `string?` | 插件根目录（可选） | -| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动的内存运行时快照） | -| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件特定配置 | -| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | 作用域日志记录器（`debug`、`info`、`warn`、`error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动 / 设置前的轻量预启动 / 设置窗口 | -| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | +| 字段 | 类型 | 说明 | +| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- | +| `api.id` | `string` | 插件 ID | +| `api.name` | `string` | 显示名称 | +| `api.version` | `string?` | 插件版本（可选） | +| `api.description` | `string?` | 插件描述（可选） | +| `api.source` | `string` | 插件源路径 | +| `api.rootDir` | `string?` | 插件根目录（可选） | +| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动中的内存运行时快照） | +| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件专属配置 | +| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | 作用域日志记录器（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置之前的轻量级窗口 | +| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | ## 内部模块约定 -在你的插件内部，请使用本地 barrel 文件进行内部导入： +在你的插件内部，使用本地 barrel 文件进行内部导入： ``` my-plugin/ - api.ts # 供外部使用方使用的公共导出 + api.ts # 面向外部使用方的公共导出 runtime-api.ts # 仅供内部使用的运行时导出 index.ts # 插件入口点 - setup-entry.ts # 仅设置用的轻量入口点（可选） + setup-entry.ts # 仅设置用的轻量入口（可选） ``` @@ -252,20 +251,23 @@ my-plugin/ `./runtime-api.ts`。SDK 路径仅是对外契约。 -由 facade 加载的内置插件公共 surface（`api.ts`、`runtime-api.ts`、 -`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）会在 OpenClaw 已经运行时优先使用活动运行时配置快照。如果尚不存在运行时快照，它们会回退到磁盘上的已解析配置文件。 +通过 facade 加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、 +`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）会在 OpenClaw 已运行时优先使用活动运行时配置快照。如果此时尚不存在运行时快照，则回退到磁盘上的已解析配置文件。 -当某个辅助函数明确是 provider 特定的、且尚不适合放入通用 SDK 子路径时，provider 插件可以暴露一个窄化的插件本地契约 barrel。内置示例： +提供商插件可以公开一个狭义的插件本地契约 barrel，用于那些明确属于提供商特定、且暂时不适合放入通用 SDK 子路径的辅助工具。内置示例： -- **Anthropic**：用于 Claude beta-header 和 `service_tier` 流辅助函数的公共 `api.ts` / `contract-api.ts` seam。 -- **`@openclaw/openai-provider`**：`api.ts` 导出 provider 构建器、默认模型辅助函数和实时 provider 构建器。 -- **`@openclaw/openrouter-provider`**：`api.ts` 导出 provider 构建器以及新手引导 / 配置辅助函数。 +- **Anthropic**：公共 `api.ts` / `contract-api.ts` 接缝层，用于 Claude + beta-header 和 `service_tier` 流辅助工具。 +- **`@openclaw/openai-provider`**：`api.ts` 导出提供商构建器、 + 默认模型辅助工具和实时提供商构建器。 +- **`@openclaw/openrouter-provider`**：`api.ts` 导出提供商构建器 + 以及新手引导/配置辅助工具。 - 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。 - 如果某个辅助函数确实需要共享，应将其提升为中立的 SDK 子路径， - 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他 - 面向能力的 surface，而不是将两个插件耦合在一起。 + 扩展的生产代码也应避免导入 `openclaw/plugin-sdk/`。 + 如果某个辅助工具确实应被共享，请将其提升为中立的 SDK 子路径， + 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他 + 面向能力的表面，而不是将两个插件耦合在一起。 ## 相关内容 @@ -274,19 +276,19 @@ my-plugin/ `definePluginEntry` 和 `defineChannelPluginEntry` 选项。 - + 完整的 `api.runtime` 命名空间参考。 - 打包、manifest 和配置 schema。 + 打包、清单和配置模式。 测试工具和 lint 规则。 - 从已弃用 surface 迁移。 + 从已弃用表面迁移。 - 深入架构和能力模型。 + 深入了解架构和能力模型。 diff --git a/docs/zh-CN/start/hubs.md b/docs/zh-CN/start/hubs.md index c16741371..98577a422 100644 --- a/docs/zh-CN/start/hubs.md +++ b/docs/zh-CN/start/hubs.md @@ -1,22 +1,22 @@ --- read_when: - - 你想查看完整的文档地图 -summary: 链接到所有 OpenClaw 文档的枢纽页 -title: 文档枢纽 + - 你想要一份完整的文档地图 +summary: 链接到所有 OpenClaw 文档的中心页 +title: 文档中心页 x-i18n: - generated_at: "2026-04-24T04:07:51Z" + generated_at: "2026-04-24T17:31:33Z" model: gpt-5.4 provider: openai - source_hash: 711d23631ca29b122054b1a048058ec5bd787043e7ffc8c3108b17cf275c2c8e + source_hash: db591029047b57e65141c5992760a81b838580602b1073e94d1bc2690415c0aa source_path: start/hubs.md workflow: 15 --- -如果你是 OpenClaw 新手，请先阅读[入门指南](/zh-CN/start/getting-started)。 +如果你刚开始使用 OpenClaw，请先从 [入门指南](/zh-CN/start/getting-started) 开始。 -使用这些枢纽页来发现每一个页面，包括左侧导航中未出现的深度解析和参考文档。 +使用这些中心页来发现每一页文档，包括左侧导航中未显示的深度解析和参考文档。 ## 从这里开始 @@ -25,14 +25,14 @@ x-i18n: - [新手引导](/zh-CN/start/onboarding) - [新手引导（CLI）](/zh-CN/start/wizard) - [设置](/zh-CN/start/setup) -- [控制台（本地 Gateway 网关）](http://127.0.0.1:18789/) +- [Dashboard（本地 Gateway 网关）](http://127.0.0.1:18789/) - [帮助](/zh-CN/help) - [文档目录](/zh-CN/start/docs-directory) - [配置](/zh-CN/gateway/configuration) - [配置示例](/zh-CN/gateway/configuration-examples) - [OpenClaw 助手](/zh-CN/start/openclaw) - [展示](/zh-CN/start/showcase) -- [Lore](/zh-CN/start/lore) +- [设定](/zh-CN/start/lore) ## 安装 + 更新 @@ -45,7 +45,7 @@ x-i18n: - [架构](/zh-CN/concepts/architecture) - [功能](/zh-CN/concepts/features) -- [网络枢纽](/zh-CN/network) +- [网络中心](/zh-CN/network) - [智能体运行时](/zh-CN/concepts/agent) - [智能体工作区](/zh-CN/concepts/agent-workspace) - [记忆](/zh-CN/concepts/memory) @@ -59,7 +59,7 @@ x-i18n: - [队列](/zh-CN/concepts/queue) - [斜杠命令](/zh-CN/tools/slash-commands) - [RPC 适配器](/zh-CN/reference/rpc) -- [TypeBox schemas](/zh-CN/concepts/typebox) +- [TypeBox 模式](/zh-CN/concepts/typebox) - [时区处理](/zh-CN/concepts/timezone) - [在线状态](/zh-CN/concepts/presence) - [设备发现 + 传输协议](/zh-CN/gateway/discovery) @@ -67,13 +67,13 @@ x-i18n: - [渠道路由](/zh-CN/channels/channel-routing) - [群组](/zh-CN/channels/groups) - [群组消息](/zh-CN/channels/group-messages) -- [模型故障转移](/zh-CN/concepts/model-failover) +- [模型故障切换](/zh-CN/concepts/model-failover) - [OAuth](/zh-CN/concepts/oauth) -## 提供商 + 入口 +## 提供商 + 接入 -- [聊天渠道枢纽](/zh-CN/channels) -- [模型提供商枢纽](/zh-CN/providers/models) +- [聊天渠道中心](/zh-CN/channels) +- [模型提供商中心](/zh-CN/providers/models) - [WhatsApp](/zh-CN/channels/whatsapp) - [Telegram](/zh-CN/channels/telegram) - [Slack](/zh-CN/channels/slack) @@ -100,8 +100,8 @@ x-i18n: - [Doctor](/zh-CN/gateway/doctor) - [日志](/zh-CN/gateway/logging) - [沙箱隔离](/zh-CN/gateway/sandboxing) -- [控制台](/zh-CN/web/dashboard) -- [Control UI](/zh-CN/web/control-ui) +- [Dashboard](/zh-CN/web/dashboard) +- [控制 UI](/zh-CN/web/control-ui) - [远程访问](/zh-CN/gateway/remote) - [远程 Gateway 网关 README](/zh-CN/gateway/remote-gateway-readme) - [Tailscale](/zh-CN/gateway/tailscale) @@ -110,15 +110,15 @@ x-i18n: ## 工具 + 自动化 -- [工具界面](/zh-CN/tools) +- [工具总览](/zh-CN/tools) - [OpenProse](/zh-CN/prose) - [CLI 参考](/zh-CN/cli) - [Exec 工具](/zh-CN/tools/exec) - [PDF 工具](/zh-CN/tools/pdf) -- [提升权限模式](/zh-CN/tools/elevated) +- [提升模式](/zh-CN/tools/elevated) - [Cron 作业](/zh-CN/automation/cron-jobs) - [自动化与任务](/zh-CN/automation) -- [Thinking + verbose](/zh-CN/tools/thinking) +- [思考 + 详细输出](/zh-CN/tools/thinking) - [模型](/zh-CN/concepts/models) - [子智能体](/zh-CN/tools/subagents) - [智能体发送 CLI](/zh-CN/tools/agent-send) @@ -135,7 +135,7 @@ x-i18n: - [音频](/zh-CN/nodes/audio) - [位置命令](/zh-CN/nodes/location-command) - [语音唤醒](/zh-CN/nodes/voicewake) -- [Talk 模式](/zh-CN/nodes/talk) +- [对话模式](/zh-CN/nodes/talk) ## 平台 @@ -152,7 +152,7 @@ x-i18n: - [macOS 开发设置](/zh-CN/platforms/mac/dev-setup) - [macOS 菜单栏](/zh-CN/platforms/mac/menu-bar) - [macOS 语音唤醒](/zh-CN/platforms/mac/voicewake) -- [macOS 语音覆盖层](/zh-CN/platforms/mac/voice-overlay) +- [macOS 语音浮层](/zh-CN/platforms/mac/voice-overlay) - [macOS WebChat](/zh-CN/platforms/mac/webchat) - [macOS Canvas](/zh-CN/platforms/mac/canvas) - [macOS 子进程](/zh-CN/platforms/mac/child-process) @@ -171,6 +171,7 @@ x-i18n: - [插件概览](/zh-CN/tools/plugin) - [构建插件](/zh-CN/plugins/building-plugins) +- [插件钩子](/zh-CN/plugins/hooks) - [插件清单](/zh-CN/plugins/manifest) - [智能体工具](/zh-CN/plugins/building-plugins#registering-agent-tools) - [插件包](/zh-CN/plugins/bundles)