diff --git a/docs/zh-CN/automation/tasks.md b/docs/zh-CN/automation/tasks.md index 9a0abbfb1..7fc530112 100644 --- a/docs/zh-CN/automation/tasks.md +++ b/docs/zh-CN/automation/tasks.md @@ -1,49 +1,49 @@ --- read_when: - - 检查正在进行或最近完成的后台工作 - - 调试分离式智能体运行的交付失败 - - 了解后台运行任务与会话、cron 和心跳之间的关系 + - 查看正在进行或最近完成的后台工作 + - 调试分离式智能体运行的投递失败 + - 了解后台运行与会话、cron 和心跳的关系 sidebarTitle: Background tasks -summary: ACP 运行、子智能体、隔离的 cron 作业和 CLI 操作的后台任务跟踪 +summary: 用于 ACP 运行、子智能体、隔离的 cron 作业和 CLI 操作的后台任务跟踪 title: 后台任务 x-i18n: - generated_at: "2026-04-28T11:45:09Z" + generated_at: "2026-04-28T20:08:43Z" model: gpt-5.5 provider: openai - source_hash: 54843ab3831dceb3df810a17dbe97e2824d99bae2233291a70f52aca168778b4 + source_hash: ff4f22f98148b01c1b044a5213a5946eac8c5d763f0d22c992e6a4a2297bc308 source_path: automation/tasks.md workflow: 16 --- -想要查找调度相关内容？请参阅 [自动化和任务](/zh-CN/automation) 以选择合适的机制。本页是后台工作的活动台账，而不是调度器。 +在查找调度功能？请参阅 [自动化和任务](/zh-CN/automation) 以选择合适的机制。本页是后台工作的活动台账，而不是调度器。 -后台任务跟踪在**主对话会话之外**运行的工作：ACP 运行、子智能体生成、隔离的 cron 作业执行，以及 CLI 发起的操作。 +后台任务跟踪**主对话会话之外**运行的工作：ACP 运行、子智能体生成、隔离的 cron 作业执行，以及 CLI 发起的操作。 -任务**不会**替代会话、cron 作业或心跳；它们是记录已分离工作发生了什么、何时发生以及是否成功的**活动台账**。 +任务**不会**取代会话、cron 作业或心跳；它们是记录分离工作发生了什么、何时发生以及是否成功的**活动台账**。 并非每次智能体运行都会创建任务。心跳轮次和普通交互式聊天不会。所有 cron 执行、ACP 生成、子智能体生成和 CLI 智能体命令都会创建任务。 -## TL;DR +## 摘要 -- 任务是**记录**，不是调度器；cron 和心跳决定工作_何时_运行，任务跟踪_发生了什么_。 +- 任务是**记录**，不是调度器；cron 和心跳决定工作在_何时_运行，任务跟踪_发生了什么_。 - ACP、子智能体、所有 cron 作业和 CLI 操作都会创建任务。心跳轮次不会。 - 每个任务都会经历 `queued → running → terminal`（succeeded、failed、timed_out、cancelled 或 lost）。 -- 只要 cron 运行时仍拥有该作业，cron 任务就会保持活动状态；如果内存中的运行时状态已消失，任务维护会先检查持久化的 cron 运行历史，再将任务标记为 lost。 -- 完成是推送驱动的：分离的工作可以直接通知，或在完成时唤醒请求者会话/心跳，因此状态轮询循环通常不是合适的形态。 -- 隔离的 cron 运行和子智能体完成会尽力为其子会话清理已跟踪的浏览器标签页/进程，然后再执行最终清理账务处理。 -- 当后代子智能体工作仍在收尾时，隔离的 cron 投递会抑制陈旧的临时父级回复，并且如果最终后代输出在投递前到达，会优先使用该输出。 -- 完成通知会直接投递到某个渠道，或排队等待下一次心跳。 +- 只要 cron 运行时仍然拥有该作业，cron 任务就会保持活动；如果内存中的运行时状态已消失，任务维护会先检查持久化 cron 运行历史，然后才将任务标记为 lost。 +- 完成由推送驱动：分离工作完成时可以直接通知，或唤醒请求方会话/心跳，因此状态轮询循环通常不是合适的形态。 +- 隔离的 cron 运行和子智能体完成会尽力为其子会话清理已跟踪的浏览器标签页/进程，然后再进行最终清理记账。 +- 当后代子智能体工作仍在排空时，隔离的 cron 送达会抑制过时的中间父级回复，并且如果最终后代输出在送达前到达，则优先使用该输出。 +- 完成通知会直接送达到渠道，或排队等待下一次心跳。 - `openclaw tasks list` 显示所有任务；`openclaw tasks audit` 暴露问题。 - 终态记录会保留 7 天，然后自动清理。 ## 快速开始 - + ```bash # List all tasks (newest first) openclaw tasks list @@ -60,7 +60,7 @@ x-i18n: openclaw tasks show ``` - + ```bash # Cancel a running task (kills the child session) openclaw tasks cancel @@ -81,7 +81,7 @@ x-i18n: ``` - + ```bash # Inspect TaskFlow state openclaw tasks flow list @@ -93,28 +93,28 @@ x-i18n: ## 什么会创建任务 -| 来源 | 运行时类型 | 创建任务记录的时机 | 默认通知策略 | -| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | -| ACP 后台运行 | `acp` | 生成子 ACP 会话 | `done_only` | -| 子智能体编排 | `subagent` | 通过 `sessions_spawn` 生成子智能体 | `done_only` | -| Cron 作业（所有类型） | `cron` | 每次 cron 执行（主会话和隔离） | `silent` | -| CLI 操作 | `cli` | 通过 Gateway 网关运行的 `openclaw agent` 命令 | `silent` | -| 智能体媒体作业 | `cli` | 由会话支撑的 `video_generate` 运行 | `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"`。 - + - 心跳轮次：主会话；参见 [心跳](/zh-CN/gateway/heartbeat) - 普通交互式聊天轮次 - - 直接的 `/command` 响应 + - 直接 `/command` 响应 @@ -135,48 +135,48 @@ stateDiagram-v2 | Status | 含义 | | ----------- | -------------------------------------------------------------------------- | -| `queued` | 已创建，等待智能体启动 | +| `queued` | 已创建，正在等待智能体启动 | | `running` | 智能体轮次正在主动执行 | | `succeeded` | 已成功完成 | | `failed` | 已完成但出现错误 | | `timed_out` | 超过配置的超时时间 | -| `cancelled` | 操作者通过 `openclaw tasks cancel` 停止 | -| `lost` | 运行时在 5 分钟宽限期后失去了权威后备状态 | +| `cancelled` | 操作员通过 `openclaw tasks cancel` 停止 | +| `lost` | 运行时在 5 分钟宽限期后丢失了权威支撑状态 | -状态转换会自动发生；当关联的智能体运行结束时，任务状态会更新为匹配结果。 +转换会自动发生；当关联的智能体运行结束时，任务状态会更新为匹配的状态。 -对于活动任务记录，智能体运行完成结果具有权威性。成功的分离运行会最终确定为 `succeeded`，普通运行错误会最终确定为 `failed`，超时或中止结果会最终确定为 `timed_out`。如果操作者已经取消任务，或运行时已经记录了更强的终态（例如 `failed`、`timed_out` 或 `lost`），后续的成功信号不会把该终态降级。 +智能体运行完成是活动任务记录的权威依据。成功的分离运行会最终记为 `succeeded`，普通运行错误会最终记为 `failed`，超时或中止结果会最终记为 `timed_out`。如果操作员已经取消该任务，或者运行时已经记录了更强的终态，例如 `failed`、`timed_out` 或 `lost`，后续的成功信号不会降级该终态。 -`lost` 具备运行时感知能力： +`lost` 具有运行时感知能力： -- ACP 任务：后备 ACP 子会话元数据消失。 -- 子智能体任务：后备子会话从目标智能体存储中消失。 -- Cron 任务：cron 运行时不再将该作业跟踪为活动状态，并且持久化的 cron 运行历史没有显示该运行的终态结果。离线 CLI 审计不会把自身空的进程内 cron 运行时状态视为权威。 -- CLI 任务：隔离子会话任务使用子会话；由聊天支撑的 CLI 任务改用实时运行上下文，因此残留的渠道/群组/直接会话行不会使它们保持活动。由 Gateway 网关支撑的 `openclaw agent` 运行也会根据其运行结果最终确定，因此已完成的运行不会一直处于活动状态，直到清扫器将其标记为 `lost`。 +- ACP 任务：支撑的 ACP 子会话元数据已消失。 +- 子智能体任务：支撑的子会话已从目标智能体存储中消失。 +- Cron 任务：cron 运行时不再将该作业跟踪为活动状态，并且持久化 cron 运行历史未显示该运行的终态结果。离线 CLI 审计不会将其自身空的进程内 cron 运行时状态视为权威依据。 +- CLI 任务：隔离的子会话任务使用子会话；由聊天支撑的 CLI 任务改用实时运行上下文，因此残留的渠道/群组/私信会话行不会让它们保持活动。由 Gateway 网关支撑的 `openclaw agent` 运行也会根据其运行结果最终确定状态，因此已完成的运行不会一直保持活动，直到清理器将它们标记为 `lost`。 -## 投递和通知 +## 送达和通知 -当任务到达终态时，OpenClaw 会通知你。有两条投递路径： +当任务达到终态时，OpenClaw 会通知你。有两条送达路径： -**直接投递**：如果任务有渠道目标（`requesterOrigin`），完成消息会直接发送到该渠道（Telegram、Discord、Slack 等）。对于子智能体完成，OpenClaw 还会在可用时保留已绑定的线程/主题路由，并且可以在放弃直接投递前，从请求者会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`）补齐缺失的 `to` / 账户。 +**直接送达**：如果任务有渠道目标（`requesterOrigin`），完成消息会直接发送到该渠道（Telegram、Discord、Slack 等）。对于子智能体完成，OpenClaw 还会在可用时保留绑定的线程/主题路由，并且可以在放弃直接送达前，从请求方会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`）补齐缺失的 `to` / 账号。 -**会话排队投递**：如果直接投递失败或未设置来源，更新会作为系统事件排入请求者会话，并在下一次心跳时显示。 +**会话排队送达**：如果直接送达失败或未设置来源，更新会作为系统事件排队到请求方会话中，并在下一次心跳时浮现。 -任务完成会触发一次即时心跳唤醒，因此你可以很快看到结果；不必等待下一次计划的心跳 tick。 +任务完成会触发一次即时心跳唤醒，因此你能快速看到结果；无需等待下一次计划的心跳节拍。 -这意味着常规工作流是基于推送的：启动一次分离工作，然后让运行时在完成时唤醒或通知你。只有在需要调试、干预或显式审计时，才轮询任务状态。 +这意味着常规工作流是推送式的：启动一次分离工作，然后让运行时在完成时唤醒或通知你。只有在需要调试、干预或显式审计时，才轮询任务状态。 ### 通知策略 -控制每个任务的通知量： +控制你收到每个任务多少信息： -| 策略 | 投递内容 | +| 策略 | 送达内容 | | --------------------- | ----------------------------------------------------------------------- | | `done_only`（默认） | 仅终态（succeeded、failed 等）；**这是默认值** | | `state_changes` | 每次状态转换和进度更新 | -| `silent` | 完全不通知 | +| `silent` | 完全不送达 | 在任务运行时更改策略： @@ -192,7 +192,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` - 输出列：任务 ID、种类、Status、投递、运行 ID、子会话、摘要。 + 输出列：任务 ID、类别、Status、送达、运行 ID、子会话、摘要。 @@ -200,7 +200,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - 查询令牌接受任务 ID、运行 ID 或会话键。显示完整记录，包括计时、投递状态、错误和终态摘要。 + 查询标记接受任务 ID、运行 ID 或会话键。显示完整记录，包括时序、送达状态、错误和终态摘要。 @@ -208,7 +208,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - 对于 ACP 和子智能体任务，这会终止子会话。对于由 CLI 跟踪的任务，取消会记录在任务注册表中（没有单独的子运行时句柄）。状态会转换为 `cancelled`，并在适用时发送投递通知。 + 对于 ACP 和子智能体任务，这会终止子会话。对于由 CLI 跟踪的任务，取消操作会记录在任务注册表中（没有单独的子运行时句柄）。Status 会转换为 `cancelled`，并在适用时发送送达通知。 @@ -221,14 +221,14 @@ openclaw tasks notify state_changes openclaw tasks audit [--json] ``` - 暴露运维问题。检测到问题时，发现项也会出现在 `openclaw status` 中。 + 暴露运行问题。检测到问题时，发现项也会出现在 `openclaw status` 中。 | 发现项 | 严重性 | 触发条件 | | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | | `stale_queued` | warn | 排队超过 10 分钟 | | `stale_running` | error | 运行超过 30 分钟 | - | `lost` | warn/error | 运行时支撑的任务所有权消失；保留的丢失任务在 `cleanupAfter` 前警告，之后变为错误 | - | `delivery_failed` | warn | 交付失败且通知策略不是 `silent` | + | `lost` | warn/error | 由运行时支持的任务所有权消失；保留的丢失任务在 `cleanupAfter` 前发出警告，之后变为错误 | + | `delivery_failed` | warn | 投递失败且通知策略不是 `silent` | | `missing_cleanup` | warn | 终止任务没有清理时间戳 | | `inconsistent_timestamps` | warn | 时间线违规（例如结束早于开始） | @@ -239,20 +239,20 @@ openclaw tasks notify state_changes openclaw tasks maintenance --apply [--json] ``` - 用它预览或应用任务和 Task Flow 状态的协调、清理标记和修剪。 + 使用此命令可预览或应用针对任务和任务流状态的协调、清理标记和修剪。 协调会感知运行时： - - ACP/subagent 任务会检查其后端子会话。 - - Cron 任务会检查 cron 运行时是否仍然拥有该作业，然后先从持久化的 cron 运行日志/作业状态恢复终止状态，再回退为 `lost`。只有 Gateway 网关进程对内存中的 cron 活动作业集合具有权威性；离线 CLI 审计使用持久历史记录，但不会仅因本地 Set 为空就将 cron 任务标记为丢失。 - - 聊天支撑的 CLI 任务会检查所属的实时运行上下文，而不只是聊天会话行。 + - ACP/子智能体任务会检查其背后的子会话。 + - Cron 任务会检查 cron 运行时是否仍拥有该作业，然后先从持久化的 cron 运行日志/作业状态恢复终止状态，再回退到 `lost`。只有 Gateway 网关进程对内存中的 cron 活动作业集合具有权威性；离线 CLI 审计会使用持久历史记录，但不会仅因为该本地 Set 为空就将 cron 任务标记为丢失。 + - 由聊天支持的 CLI 任务会检查所属的实时运行上下文，而不只是聊天会话行。 完成清理也会感知运行时： - - 子智能体完成时会尽力关闭为子会话跟踪的浏览器标签页/进程，然后继续公告清理。 - - 隔离 cron 完成时会尽力关闭为 cron 会话跟踪的浏览器标签页/进程，然后才完全拆除该次运行。 - - 隔离 cron 交付会在需要时等待后代子智能体跟进，并抑制过期的父级确认文本，而不是公告它。 - - 子智能体完成交付优先使用最新可见的助手文本；如果为空，则回退到清理后的最新工具/toolResult 文本，而仅因超时结束的工具调用运行可以折叠为简短的部分进展摘要。终止的失败运行会公告失败状态，而不会重放捕获的回复文本。 + - 子智能体完成后，会尽力在公告清理继续之前关闭为子会话跟踪的浏览器标签页/进程。 + - 隔离 cron 完成后，会尽力在运行完全拆除前关闭为 cron 会话跟踪的浏览器标签页/进程。 + - 隔离 cron 投递会在需要时等待后代子智能体的后续操作，并抑制过期的父级确认文本，而不是公告它。 + - 子智能体完成投递优先使用最新可见的助手文本；如果为空，则回退到经过清理的最新工具/toolResult 文本；仅超时的工具调用运行可以折叠为简短的部分进度摘要。终止失败的运行会公告失败状态，而不会重放捕获的回复文本。 - 清理失败不会掩盖真实的任务结果。 @@ -263,22 +263,22 @@ openclaw tasks notify state_changes openclaw tasks flow cancel ``` - 当你关心的是编排中的 Task Flow，而不是某一条单独的后台任务记录时，使用这些命令。 + 当你关心的是编排任务流，而不是某一条单独的后台任务记录时，请使用这些命令。 -## 聊天任务板（`/tasks`） +## 聊天任务看板（`/tasks`） -在任何聊天会话中使用 `/tasks` 查看链接到该会话的后台任务。该任务板会显示活动任务和最近完成的任务，包括运行时、Status、时间信息，以及进度或错误详情。 +在任意聊天会话中使用 `/tasks` 查看链接到该会话的后台任务。看板会显示活动任务和最近完成的任务，以及运行时、Status、计时、进度或错误详情。 -当当前会话没有可见的已链接任务时，`/tasks` 会回退到智能体本地任务计数，因此你仍可获得概览，同时不会泄露其他会话的详情。 +当当前会话没有可见的链接任务时，`/tasks` 会回退到智能体本地任务计数，这样你仍能获得概览，而不会泄露其他会话的详情。 -若要查看完整的操作员账本，请使用 CLI：`openclaw tasks list`。 +要查看完整的操作员账本，请使用 CLI：`openclaw tasks list`。 ## Status 集成（任务压力） -`openclaw status` 包含一目了然的任务摘要： +`openclaw status` 包含一眼可见的任务摘要： ``` Tasks: 3 queued · 2 running · 1 issues @@ -290,74 +290,77 @@ Tasks: 3 queued · 2 running · 1 issues - **failures** — `failed` + `timed_out` + `lost` 的数量 - **byRuntime** — 按 `acp`、`subagent`、`cron`、`cli` 的明细 -`/status` 和 `session_status` 工具都使用感知清理状态的任务快照：优先显示活动任务，隐藏过期的已完成行，并且只有在没有活动工作剩余时才显示最近失败。这让 Status 卡片聚焦于当前真正重要的内容。 +`/status` 和 `session_status` 工具都使用感知清理的任务快照：优先显示活动任务，隐藏过期的已完成行，并且只有在没有剩余活动工作时才显示最近失败。这会让状态卡片聚焦于当前真正重要的内容。 ## 存储和维护 -### 任务存储位置 +### 任务存放位置 -任务记录会持久化到 SQLite： +任务记录持久化在 SQLite 中，位置为： ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -注册表在 Gateway 网关启动时加载到内存，并将写入同步到 SQLite，以便在重启后保持持久性。 -Gateway 网关通过使用 SQLite 的默认自动检查点阈值，以及定期和关机时的 `TRUNCATE` 检查点，来限制 SQLite 预写日志大小。 +注册表会在 Gateway 网关启动时加载到内存，并将写入同步到 SQLite，以便在重启后保持持久性。 +Gateway 网关通过 SQLite 的默认自动检查点阈值，以及周期性和关闭时的 `TRUNCATE` 检查点，限制 SQLite 预写日志大小。 ### 自动维护 -清扫器每 **60 秒** 运行一次，并处理三件事： +清扫器每 **60 秒** 运行一次，并处理四件事： - 检查活动任务是否仍有权威运行时支撑。ACP/subagent 任务使用子会话状态，cron 任务使用活动作业所有权，聊天支撑的 CLI 任务使用所属运行上下文。如果该支撑状态消失超过 5 分钟，任务会被标记为 `lost`。 + 检查活动任务是否仍有权威运行时支持。ACP/子智能体任务使用子会话状态，cron 任务使用活动作业所有权，由聊天支持的 CLI 任务使用所属运行上下文。如果该支持状态消失超过 5 分钟，任务会被标记为 `lost`。 + + + 关闭终止的父级拥有的一次性 ACP 会话，并且仅在没有剩余活动对话绑定时关闭过期的终止持久 ACP 会话。 - 在终止任务上设置 `cleanupAfter` 时间戳（endedAt + 7 天）。在保留期间，丢失任务仍会在审计中显示为警告；当 `cleanupAfter` 过期或清理元数据缺失后，它们会变为错误。 + 为终止任务设置 `cleanupAfter` 时间戳（endedAt + 7 天）。在保留期内，丢失任务仍会在审计中显示为警告；在 `cleanupAfter` 过期后，或当清理元数据缺失时，它们会变为错误。 - 删除超过 `cleanupAfter` 日期的记录。 + 删除超过其 `cleanupAfter` 日期的记录。 -**保留期：** 终止任务记录会保留 **7 天**，然后自动修剪。无需配置。 +**保留：** 终止任务记录会保留 **7 天**，然后自动修剪。无需配置。 -## 任务如何关联到其他系统 +## 任务与其他系统的关系 - - [Task Flow](/zh-CN/automation/taskflow) 是后台任务之上的流编排层。单个流可以在其生命周期内使用托管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单个任务记录，使用 `openclaw tasks flow` 检查编排流。 + + [任务流](/zh-CN/automation/taskflow) 是后台任务之上的流程编排层。单个流程可能在其生命周期内使用托管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单条任务记录，使用 `openclaw tasks flow` 检查编排流程。 - 详见 [Task Flow](/zh-CN/automation/taskflow)。 + 了解详情请参阅[任务流](/zh-CN/automation/taskflow)。 - 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 作业](/zh-CN/automation/cron-jobs)。 - 心跳运行是主会话轮次，它们不会创建任务记录。当任务完成时，它可以触发一次心跳唤醒，让你及时看到结果。 + 心跳运行属于主会话轮次，不会创建任务记录。任务完成时，它可以触发一次心跳唤醒，让你及时看到结果。 - 参见 [Heartbeat](/zh-CN/gateway/heartbeat)。 + 请参阅[心跳](/zh-CN/gateway/heartbeat)。 任务可以引用 `childSessionKey`（工作运行的位置）和 `requesterSessionKey`（启动它的人）。会话是对话上下文；任务是在其之上的活动跟踪。 - 任务的 `runId` 会链接到执行该工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务 Status，你不需要手动管理生命周期。 + 任务的 `runId` 会链接到执行工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务 Status，你不需要手动管理生命周期。 -## 相关内容 +## 相关 -- [自动化与任务](/zh-CN/automation) — 所有自动化机制概览 +- [自动化与任务](/zh-CN/automation) — 所有自动化机制一览 - [CLI：任务](/zh-CN/cli/tasks) — CLI 命令参考 -- [Heartbeat](/zh-CN/gateway/heartbeat) — 定期主会话轮次 +- [心跳](/zh-CN/gateway/heartbeat) — 周期性主会话轮次 - [计划任务](/zh-CN/automation/cron-jobs) — 调度后台工作 -- [Task Flow](/zh-CN/automation/taskflow) — 任务之上的流编排 +- [任务流](/zh-CN/automation/taskflow) — 任务之上的流程编排 diff --git a/docs/zh-CN/channels/telegram.md b/docs/zh-CN/channels/telegram.md index 59c36dd90..990bbad82 100644 --- a/docs/zh-CN/channels/telegram.md +++ b/docs/zh-CN/channels/telegram.md @@ -1,18 +1,18 @@ --- read_when: - - 开发 Telegram 功能或网络钩子 + - 处理 Telegram 功能或网络钩子 summary: Telegram 机器人支持状态、能力和配置 title: Telegram x-i18n: - generated_at: "2026-04-28T19:31:51Z" + generated_at: "2026-04-28T20:08:19Z" model: gpt-5.5 provider: openai - source_hash: dadd8d0a735b8d8ee75eb44ad0ce018f81c6774aee3bd69f0804e9e731352546 + source_hash: 663fd2eecc7f2ff02622f5fde1a6ae3c97427f7aeda26f89a230529f3284df8b source_path: channels/telegram.md workflow: 16 --- -可用于生产环境中的机器人私信和群组，基于 grammY。默认模式是长轮询；webhook 模式为可选。 +可用于生产环境的机器人私信和群组，基于 grammY。长轮询是默认模式；webhook 模式可选。 @@ -30,7 +30,7 @@ x-i18n: - 打开 Telegram 并与 **@BotFather** 聊天（确认用户名正好是 `@BotFather`）。 + 打开 Telegram 并与 **@BotFather** 聊天（确认用户名完全是 `@BotFather`）。 运行 `/newbot`，按提示操作，并保存令牌。 @@ -51,7 +51,7 @@ x-i18n: } ``` - 环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。 + 环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。 Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置令牌，然后启动 Gateway 网关。 @@ -64,36 +64,36 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - 配对码会在 1 小时后过期。 + 配对码将在 1 小时后过期。 - 将机器人添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy` 以匹配你的访问模型。 + 将机器人添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy`，使其与你的访问模型匹配。 -令牌解析顺序会感知账户。实践中，配置值优先于环境变量回退，而 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。 +令牌解析顺序支持账号感知。实际使用中，配置值优先于环境变量回退，并且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账号。 -## Telegram 端设置 +## Telegram 侧设置 - Telegram 机器人的默认设置是**隐私模式**，这会限制它们能接收哪些群组消息。 + Telegram 机器人默认启用**隐私模式**，这会限制它们能接收的群组消息。 如果机器人必须看到所有群组消息，可以： - 通过 `/setprivacy` 禁用隐私模式，或 - 将机器人设为群组管理员。 - 切换隐私模式后，请在每个群组中移除并重新添加机器人，以便 Telegram 应用该更改。 + 切换隐私模式时，请在每个群组中移除并重新添加机器人，以便 Telegram 应用更改。 - 管理员状态由 Telegram 群组设置控制。 + 管理员状态在 Telegram 群组设置中控制。 管理员机器人会接收所有群组消息，这对始终在线的群组行为很有用。 @@ -118,23 +118,25 @@ openclaw pairing approve telegram - `open`（要求 `allowFrom` 包含 `"*"`） - `disabled` + `dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到机器人用户名的 Telegram 账号都能向机器人发出命令。仅在有意公开且工具严格受限的机器人中使用；单所有者机器人应使用包含数字用户 ID 的 `allowlist`。 + `channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。 - `dmPolicy: "allowlist"` 且 `allowFrom` 为空会阻止所有私信，并会被配置验证拒绝。 - 设置只会要求数字用户 ID。 - 如果你已升级且配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。 - 如果你之前依赖配对存储的允许列表文件，`openclaw doctor --fix` 可以在允许列表流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。 + `dmPolicy: "allowlist"` 搭配空的 `allowFrom` 会阻止所有私信，并会被配置校验拒绝。 + 设置流程只会要求数字用户 ID。 + 如果你已升级且配置中包含 `@username` allowlist 条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。 + 如果你之前依赖配对存储的 allowlist 文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚未显式配置 ID 时）。 - 对于单所有者机器人，建议使用 `dmPolicy: "allowlist"` 并设置显式数字 `allowFrom` ID，以便将访问策略持久保存在配置中（而不是依赖先前的配对批准）。 + 对于单所有者机器人，建议使用 `dmPolicy: "allowlist"` 并显式设置数字 `allowFrom` ID，以便在配置中保持持久的访问策略（而不是依赖之前的配对批准）。 - 常见困惑：批准私信配对并不意味着“此发送者在所有地方都已获授权”。 - 配对只授予私信访问权限。群组发送者授权仍来自显式配置允许列表。 - 如果你希望“我只授权一次，私信和群组命令都能使用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`。 + 常见误解：私信配对批准并不表示“该发送者在所有地方都已授权”。 + 配对只授予私信访问权限。群组发送者授权仍来自显式配置的 allowlist。 + 如果你希望“我授权一次后，私信和群组命令都可用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`。 ### 查找你的 Telegram 用户 ID - 更安全（无需第三方机器人）： + 更安全（不使用第三方机器人）： - 1. 向你的机器人发送私信。 + 1. 给你的机器人发送私信。 2. 运行 `openclaw logs --follow`。 3. 读取 `from.id`。 @@ -144,18 +146,18 @@ openclaw pairing approve telegram curl "https://api.telegram.org/bot/getUpdates" ``` - 第三方方法（隐私性较低）：`@userinfobot` 或 `@getidsbot`。 + 第三方方法（隐私较低）：`@userinfobot` 或 `@getidsbot`。 - - 两项控制会一起生效： + + 两项控制会共同生效： 1. **允许哪些群组**（`channels.telegram.groups`） - 没有 `groups` 配置： - - 使用 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查 - - 使用 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`） - - 已配置 `groups`：作为允许列表生效（显式 ID 或 `"*"`） + - 搭配 `groupPolicy: "open"`：任何群组都能通过群组 ID 检查 + - 搭配 `groupPolicy: "allowlist"`（默认）：在添加 `groups` 条目（或 `"*"`）之前，群组会被阻止 + - 已配置 `groups`：作为 allowlist 生效（显式 ID 或 `"*"`） 2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`） - `open` @@ -165,14 +167,14 @@ curl "https://api.telegram.org/bot/getUpdates" `groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。 `groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。 不要将 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 应放在 `channels.telegram.groups` 下。 - 非数字条目会在发送者授权中被忽略。 - 安全边界（`2026.2.25+`）：群组发送者授权**不会**继承私信配对存储批准。 + 非数字条目会被发送者授权忽略。 + 安全边界（`2026.2.25+`）：群组发送者身份验证**不会**继承私信配对存储批准。 配对仅限私信。对于群组，请设置 `groupAllowFrom` 或按群组/按话题设置 `allowFrom`。 如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。 - 单所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。 - 运行时说明：如果完全缺少 `channels.telegram`，运行时默认采用故障关闭的 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。 + 单所有者机器人的实用模式：将你的用户 ID 设置到 `channels.telegram.allowFrom`，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。 + 运行时说明：如果完全缺失 `channels.telegram`，运行时默认采用失败关闭的 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。 - 示例：允许一个特定群组中的任何成员： + 示例：允许某个特定群组中的任何成员： ```json5 { @@ -189,7 +191,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 示例：只允许一个特定群组内的特定用户： + 示例：仅允许某个特定群组中的特定用户： ```json5 { @@ -207,11 +209,11 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - 常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。 + 常见错误：`groupAllowFrom` 不是 Telegram 群组 allowlist。 - - 将类似 `-1001234567890` 的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。 - - 当你想限制已允许群组内哪些人可以触发机器人时，将类似 `8734062810` 的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 - - 只有当你希望已允许群组的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。 + - 将 `-1001234567890` 这样的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。 + - 当你想限制允许群组内哪些人可以触发机器人时，将 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 + - 仅当你希望允许群组中的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。 @@ -232,9 +234,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - 这些只会更新会话状态。使用配置来持久保存。 + 这些只更新会话状态。使用配置来实现持久化。 - 持久配置示例： + 持久化配置示例： ```json5 { @@ -251,7 +253,7 @@ curl "https://api.telegram.org/bot/getUpdates" 获取群组聊天 ID： - 将群组消息转发给 `@userinfobot` / `@getidsbot` - - 或从 `openclaw logs --follow` 中读取 `chat.id` + - 或从 `openclaw logs --follow` 读取 `chat.id` - 或检查 Bot API `getUpdates` @@ -260,19 +262,19 @@ curl "https://api.telegram.org/bot/getUpdates" ## 运行时行为 - Telegram 由 Gateway 网关进程拥有。 -- 路由是确定性的：Telegram 入站会回复到 Telegram（模型不会选择渠道）。 -- 入站消息会规范化为共享渠道信封，并带有回复元数据和媒体占位符。 +- 路由是确定性的：Telegram 入站回复会回到 Telegram（模型不会选择渠道）。 +- 入站消息会规范化为共享渠道信封，包含回复元数据和媒体占位符。 - 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:` 以保持话题隔离。 -- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用线程感知会话键进行路由，并为回复保留线程 ID。 +- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用支持线程感知的会话键进行路由，并为回复保留线程 ID。 - 长轮询使用 grammY runner，并按聊天/按线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。 -- 每个 Gateway 网关进程内都会保护长轮询，确保同一时间只有一个活跃轮询器可以使用一个机器人令牌。如果你仍然看到 `getUpdates` 409 冲突，很可能是另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一令牌。 -- 默认情况下，长轮询看门狗会在 120 秒内没有完成的 `getUpdates` 活性检测后触发重启。只有当你的部署在长时间运行工作期间仍出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围是 `30000` 到 `600000`；支持按账户覆盖。 +- 长轮询在每个 Gateway 网关进程内受保护，因此同一时间只有一个活动 poller 能使用机器人令牌。如果你仍看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部 poller 正在使用同一令牌。 +- 默认情况下，长轮询 watchdog 会在 120 秒内没有完成的 `getUpdates` 存活性后触发重启。只有当你的部署在长时间运行的工作期间仍出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。 - Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。 ## 功能参考 - + OpenClaw 可以实时流式传输部分回复： - 直接聊天：预览消息 + `editMessageText` @@ -281,11 +283,11 @@ curl "https://api.telegram.org/bot/getUpdates" 要求： - `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`） - - `progress` 在 Telegram 上映射为 `partial`（兼容跨渠道命名） + - 在 Telegram 上，`progress` 映射为 `partial`（与跨渠道命名兼容） - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（默认：预览流式传输启用时为 `true`） - 会检测旧版 `channels.telegram.streamMode` 和布尔 `streaming` 值；运行 `openclaw doctor --fix` 将它们迁移到 `channels.telegram.streaming.mode` - 工具进度预览更新是工具运行时显示的简短“Working...”行，例如命令执行、文件读取、计划更新或补丁摘要。Telegram 默认保持启用这些内容，以匹配 `v2026.4.22` 及之后版本发布的 OpenClaw 行为。若要保留答案文本的已编辑预览，但隐藏工具进度行，请设置： + 工具进度预览更新是在工具运行时显示的简短 “Working...” 行，例如命令执行、文件读取、计划更新或补丁摘要。Telegram 默认保持启用这些更新，以匹配 `v2026.4.22` 及更高版本中已发布的 OpenClaw 行为。要保留用于答案文本的已编辑预览，但隐藏工具进度行，请设置： ```json { @@ -302,43 +304,43 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 仅当你想要只交付最终结果时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立的“Working...”消息发送。批准提示、媒体负载和错误仍会通过正常最终交付路由。若你只想在隐藏工具进度状态行的同时保留答案预览编辑，请使用 `streaming.preview.toolProgress: false`。 + 仅当你希望只交付最终结果时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度杂讯会被抑制，而不是作为独立的 “Working...” 消息发送。批准提示、媒体载荷和错误仍会通过正常的最终交付路由。仅当你只想保留答案预览编辑，同时隐藏工具进度状态行时，才使用 `streaming.preview.toolProgress: false`。 对于纯文本回复： - - 较短的私信/群组/话题预览：OpenClaw 保留同一条预览消息，并在原处执行最终编辑 - - 超过约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间 + - 较短的私信/群组/话题预览：OpenClaw 会保留同一条预览消息，并在原处执行最终编辑 + - 约一分钟以上的旧预览：OpenClaw 会将完整回复作为新的最终消息发送，然后清理预览，使 Telegram 的可见时间戳反映完成时间，而不是预览创建时间 - 对于复杂回复（例如媒体负载），OpenClaw 会回退到正常最终交付，然后清理预览消息。 + 对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终交付，然后清理预览消息。 - 预览流式传输独立于分块流式传输。当 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 + 预览流式传输与分块流式传输是分开的。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 - 如果原生草稿传输不可用/被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。 + 如果原生草稿传输不可用或被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。 仅限 Telegram 的推理流： - - `/reasoning stream` 在生成时将推理发送到实时预览 - - 最终答案发送时不包含推理文本 + - `/reasoning stream` 会在生成过程中把推理发送到实时预览 + - 最终回答发送时不包含推理文本 - + 出站文本使用 Telegram `parse_mode: "HTML"`。 - 类 Markdown 文本会渲染为 Telegram 安全的 HTML。 - 原始模型 HTML 会被转义，以减少 Telegram 解析失败。 - - 如果 Telegram 拒绝已解析的 HTML，OpenClaw 会以纯文本重试。 + - 如果 Telegram 拒绝解析后的 HTML，OpenClaw 会以纯文本重试。 - 链接预览默认启用，可以通过 `channels.telegram.linkPreview: false` 禁用。 + 链接预览默认启用，可通过 `channels.telegram.linkPreview: false` 禁用。 - Telegram 命令菜单注册在启动时通过 `setMyCommands` 处理。 + Telegram 命令菜单注册会在启动时通过 `setMyCommands` 处理。 原生命令默认值： - - `commands.native: "auto"` 为 Telegram 启用原生命令 + - `commands.native: "auto"` 会为 Telegram 启用原生命令 添加自定义命令菜单条目： @@ -357,23 +359,23 @@ curl "https://api.telegram.org/bot/getUpdates" 规则： - - 名称会被规范化（去掉前导 `/`，转为小写） + - 名称会被规范化（去掉开头的 `/`，转换为小写） - 有效模式：`a-z`、`0-9`、`_`，长度 `1..32` - 自定义命令不能覆盖原生命令 - - 冲突/重复项会被跳过并记录日志 + - 冲突或重复项会被跳过并记录日志 - 注意： + 备注： - 自定义命令只是菜单条目；它们不会自动实现行为 - - 插件/skill 命令即使未显示在 Telegram 菜单中，输入时仍然可以工作 + - 插件/Skill 命令即使未显示在 Telegram 菜单中，输入时仍可能工作 - 如果原生命令被禁用，内置项会被移除。已配置时，自定义/插件命令仍可能注册。 + 如果禁用原生命令，内置命令会被移除。自定义/插件命令在已配置时仍可能注册。 常见设置失败： - - `setMyCommands failed` 带有 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然溢出；减少插件/skill/自定义命令，或禁用 `channels.telegram.commands.native`。 - - 当直接 Bot API curl 命令可用，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 失败并显示 `404: Not Found` 时，可能表示 `channels.telegram.apiRoot` 被设置成了完整的 `/bot` 端点。`apiRoot` 必须只是 Bot API 根路径，并且 `openclaw doctor --fix` 会移除意外追加的 `/bot`。 - - `getMe returned 401` 表示 Telegram 拒绝了已配置的机器人令牌。使用当前 BotFather 令牌更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。 + - `setMyCommands failed` 带有 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然超出限制；请减少插件/Skill/自定义命令，或禁用 `channels.telegram.commands.native`。 + - 当直接使用 Bot API curl 命令可工作，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 以 `404: Not Found` 失败时，可能表示 `channels.telegram.apiRoot` 被设置成了完整的 `/bot` 端点。`apiRoot` 必须只是 Bot API 根地址，`openclaw doctor --fix` 会移除意外追加的 `/bot`。 + - `getMe returned 401` 表示 Telegram 拒绝了已配置的 bot token。请使用当前 BotFather token 更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。 - `setMyCommands failed` 带有网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。 ### 设备配对命令（`device-pair` 插件） @@ -385,12 +387,12 @@ curl "https://api.telegram.org/bot/getUpdates" 3. `/pair pending` 列出待处理请求（包括角色/作用域） 4. 批准请求： - `/pair approve ` 用于显式批准 - - 只有一个待处理请求时使用 `/pair approve` - - `/pair approve latest` 用于最新请求 + - `/pair approve` 用于只有一个待处理请求时 + - `/pair approve latest` 用于最近的请求 - 设置代码携带短期有效的 bootstrap 令牌。内置 bootstrap 移交会将主节点令牌保持在 `scopes: []`；任何被移交的操作员令牌都会被限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap 作用域检查带有角色前缀，因此该操作员 allowlist 只满足操作员请求；非操作员角色仍需要其自身角色前缀下的作用域。 + 设置代码携带一个短生命周期的引导 token。内置引导交接会把主节点 token 保持在 `scopes: []`；任何交接出的 operator token 都会限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。引导作用域检查带有角色前缀，因此该 operator 允许列表只满足 operator 请求；非 operator 角色仍需要其自身角色前缀下的作用域。 - 如果设备使用已更改的凭证详细信息（例如角色/作用域/公钥）重试，之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 + 如果设备使用已变更的认证详情重试（例如角色/作用域/公钥），先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。 @@ -437,7 +439,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist`（默认） - 旧版 `capabilities: ["inlineButtons"]` 映射到 `inlineButtons: "all"`。 + 旧版 `capabilities: ["inlineButtons"]` 会映射到 `inlineButtons: "all"`。 消息操作示例： @@ -471,7 +473,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `editMessage`（`chatId`、`messageId`、`content`） - `createForumTopic`（`chatId`、`name`、可选 `iconColor`、`iconCustomEmojiId`） - 渠道消息操作会暴露符合人体工学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。 + 渠道消息操作会公开符合人体工学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。 门控控制： @@ -480,8 +482,8 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker`（默认：禁用） - 注意：`edit` 和 `topic-create` 当前默认启用，并且没有单独的 `channels.telegram.actions.*` 开关。 - 运行时发送使用当前有效的配置/密钥快照（启动/重载），因此操作路径不会在每次发送时执行临时 SecretRef 重新解析。 + 注意：`edit` 和 `topic-create` 目前默认启用，并且没有单独的 `channels.telegram.actions.*` 开关。 + 运行时发送使用活动的配置/密钥快照（启动/重新加载），因此操作路径不会在每次发送时执行临时 SecretRef 重新解析。 反应移除语义：[/tools/reactions](/zh-CN/tools/reactions) @@ -491,7 +493,7 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram 支持在生成输出中使用显式回复线程标签： - `[[reply_to_current]]` 回复触发消息 - - `[[reply_to:]]` 回复特定 Telegram 消息 ID + - `[[reply_to:]]` 回复特定的 Telegram 消息 ID `channels.telegram.replyToMode` 控制处理方式： @@ -499,29 +501,29 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - 启用回复线程，并且原始 Telegram 文本或标题可用时，OpenClaw 会自动包含原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 代码单元，因此较长消息会从开头引用；如果 Telegram 拒绝该引用，则回退为普通回复。 + 启用回复线程后，如果原始 Telegram 文本或说明文字可用，OpenClaw 会自动包含原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 码元，因此更长的消息会从开头引用，并在 Telegram 拒绝引用时回退为普通回复。 - 注意：`off` 会禁用隐式回复串联。显式 `[[reply_to_*]]` 标签仍会被遵守。 + 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。 - + 论坛超级群组： - - 话题会话键追加 `:topic:` - - 回复和正在输入状态会指向该话题串 + - 话题会话键会追加 `:topic:` + - 回复和正在输入状态会发送到话题线程 - 话题配置路径： `channels.telegram.groups..topics.` - 通用话题（`threadId=1`）特例： + 常规话题（`threadId=1`）的特殊情况： - - 发送消息时省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`） - - 正在输入操作仍包含 `message_thread_id` + - 消息发送会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`） + - 正在输入操作仍会包含 `message_thread_id` 话题继承：话题条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 - `agentId` 仅属于话题，不会从群组默认值继承。 + `agentId` 仅适用于话题，不会从群组默认值继承。 - **按话题进行智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这让每个话题都有自己隔离的工作区、记忆和会话。示例： + **按话题路由智能体**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这会为每个话题提供自己隔离的工作区、记忆和会话。示例： ```json5 { @@ -541,24 +543,24 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 随后每个话题都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3` + 每个话题随后都会拥有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3` - **持久 ACP 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定（`bindings[]`，其中 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的带话题限定的 id）固定 ACP harness 会话。目前范围限定为群组/超级群组中的论坛话题。参见 [ACP Agents](/zh-CN/tools/acp-agents)。 + **持久 ACP 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定来固定 ACP harness 会话（`bindings[]`，带有 `type: "acp"` 和 `match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的话题限定 ID）。目前作用域限定为群组/超级群组中的论坛话题。参见 [ACP 智能体](/zh-CN/tools/acp-agents)。 - **从聊天中生成绑定到话题串的 ACP**：`/acp spawn --thread here|auto` 会将当前话题绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在话题内置顶生成确认消息。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。 + **从聊天生成线程绑定 ACP**：`/acp spawn --thread here|auto` 会把当前话题绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在话题内固定生成确认消息。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。 - 模板上下文会暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保留私信路由，但使用支持话题串的会话键。 + 模板上下文会公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保留私信路由，但使用线程感知的会话键。 ### 音频消息 - Telegram 会区分语音消息和音频文件。 + Telegram 区分语音便条和音频文件。 - 默认：音频文件行为 - - 在智能体回复中使用标签 `[[audio_as_voice]]` 可强制按语音消息发送 - - 入站语音消息转录会在智能体上下文中被框定为机器生成的、不可信文本；提及检测仍使用原始转录，因此受提及门控的语音消息会继续工作。 + - 在智能体回复中使用标签 `[[audio_as_voice]]` 可强制以语音便条发送 + - 入站语音便条转录会在智能体上下文中被框定为机器生成的、不受信任的文本；提及检测仍使用原始转录，因此受提及门控的语音消息会继续工作。 消息操作示例： @@ -574,7 +576,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### 视频消息 - Telegram 会区分视频文件和视频消息。 + Telegram 区分视频文件和视频便条。 消息操作示例： @@ -588,7 +590,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 视频消息不支持说明文字；提供的消息文本会单独发送。 + 视频便条不支持说明文字；提供的消息文本会单独发送。 ### 贴纸 @@ -610,7 +612,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - 贴纸会被描述一次（如果可能），并缓存以减少重复的视觉调用。 + 贴纸会被描述一次（如果可行），并被缓存以减少重复的视觉调用。 启用贴纸操作： @@ -637,7 +639,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 搜索缓存的贴纸： + 搜索已缓存的贴纸： ```json5 { @@ -650,8 +652,8 @@ curl "https://api.telegram.org/bot/getUpdates" - - Telegram 回应会作为 `message_reaction` 更新到达（与消息载荷分开）。 + + Telegram 反应会作为 `message_reaction` 更新到达（与消息载荷分开）。 启用后，OpenClaw 会将如下系统事件加入队列： @@ -662,37 +664,37 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.reactionNotifications`：`off | own | all`（默认：`own`） - `channels.telegram.reactionLevel`：`off | ack | minimal | extensive`（默认：`minimal`） - 说明： + 备注： - - `own` 表示仅限用户对机器人所发送消息的回应（通过已发送消息缓存尽力而为）。 - - 回应事件仍会遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权的发送者会被丢弃。 - - Telegram 不会在回应更新中提供话题串 ID。 - - 非论坛群组会路由到群组聊天会话 - - 论坛群组会路由到群组通用话题会话（`:topic:1`），而不是确切的来源话题 + - `own` 表示仅用户对机器人发送消息的回应（通过已发送消息缓存尽力而为）。 + - 回应事件仍遵循 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。 + - Telegram 不会在回应更新中提供话题 ID。 + - 非论坛群组路由到群聊会话 + - 论坛群组路由到群组通用话题会话（`:topic:1`），而不是确切的原始话题 - 轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。 + 用于轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。 - - 当 OpenClaw 正在处理入站消息时，`ackReaction` 会发送确认 emoji。 + + `ackReaction` 会在 OpenClaw 处理传入消息时发送一个确认表情符号。 解析顺序： - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 "👀"） + - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） - 说明： + 注意： - - Telegram 期望使用 unicode emoji（例如 "👀"）。 - - 使用 `""` 可为某个渠道或账号禁用回应。 + - Telegram 期望使用 unicode 表情符号（例如 "👀"）。 + - 使用 `""` 可为某个渠道或账号禁用该回应。 - 默认启用渠道配置写入（`configWrites !== false`）。 + 渠道配置写入默认启用（`configWrites !== false`）。 Telegram 触发的写入包括： @@ -714,28 +716,28 @@ curl "https://api.telegram.org/bot/getUpdates" - 默认使用长轮询。若使用 webhook 模式，请设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选设置 `webhookPath`、`webhookHost`、`webhookPort`（默认值为 `/telegram-webhook`、`127.0.0.1`、`8787`）。 + 默认使用长轮询。对于 webhook 模式，设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选设置 `webhookPath`、`webhookHost`、`webhookPort`（默认值为 `/telegram-webhook`、`127.0.0.1`、`8787`）。 本地监听器绑定到 `127.0.0.1:8787`。对于公网入口，可以在本地端口前放置反向代理，或有意设置 `webhookHost: "0.0.0.0"`。 - webhook 模式会先校验请求防护、Telegram secret token 和 JSON 正文，然后再向 Telegram 返回 `200`。 - OpenClaw 随后会通过与长轮询相同的按聊天/按话题 bot 通道异步处理更新，因此缓慢的智能体轮次不会阻塞 Telegram 的投递 ACK。 + webhook 模式会先验证请求防护、Telegram secret token 和 JSON 正文，然后再向 Telegram 返回 `200`。 + 随后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道异步处理更新，因此较慢的智能体轮次不会阻塞 Telegram 的投递 ACK。 - `channels.telegram.textChunkLimit` 默认值为 4000。 - - `channels.telegram.chunkMode="newline"` 会优先按段落边界（空行）拆分，再按长度拆分。 - - `channels.telegram.mediaMaxMb`（默认 100）限制入站和出站 Telegram 媒体大小。 - - `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时时间（未设置时使用 grammY 默认值）。 - - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在误报轮询停滞重启时，在 `30000` 到 `600000` 之间调整。 + - `channels.telegram.chunkMode="newline"` 会优先按段落边界（空行）分割，然后再按长度分割。 + - `channels.telegram.mediaMaxMb`（默认 100）限制传入和传出的 Telegram 媒体大小。 + - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。 + - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在轮询停滞重启出现误报时，才在 `30000` 到 `600000` 之间调整。 - 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。 - 回复/引用/转发的补充上下文目前会按收到的内容传递。 - - Telegram allowlist 主要控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 + - Telegram 允许列表主要控制谁能触发智能体，并不是完整的补充上下文脱敏边界。 - 私信历史控制： - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - `channels.telegram.retry` 配置适用于 Telegram 发送辅助能力（CLI/工具/actions），用于可恢复的出站 API 错误。 + - `channels.telegram.retry` 配置适用于 Telegram 发送辅助逻辑（CLI/工具/操作），用于可恢复的出站 API 错误。 CLI 发送目标可以是数字聊天 ID 或用户名： @@ -754,53 +756,53 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - 仅 Telegram 的投票标志： + 仅限 Telegram 的投票标志： - - `--poll-duration-seconds` (5-600) + - `--poll-duration-seconds`（5-600） - `--poll-anonymous` - `--poll-public` - - `--thread-id` 用于论坛话题（或使用 `:topic:` 目标） + - 用于论坛话题的 `--thread-id`（或使用 `:topic:` 目标） Telegram 发送还支持： - - 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 来提供内联键盘 - - 当 bot 可以在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递 + - 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 创建内联键盘 + - 当机器人可以在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递 - 使用 `--force-document` 将出站图片和 GIF 作为文档发送，而不是压缩照片或动画媒体上传 - Action 门控： + 操作限制： - `channels.telegram.actions.sendMessage=false` 会禁用出站 Telegram 消息，包括投票 - - `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保留常规发送功能 + - `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保留常规发送能力 - Telegram 支持在审批人私信中进行执行审批，也可以选择在来源聊天或话题中发布提示。审批人必须是数字 Telegram 用户 ID。 + Telegram 支持在审批者私信中进行执行审批，并且可以选择在原始聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。 配置路径： - - `channels.telegram.execApprovals.enabled`（至少有一个审批人可解析时自动启用） - - `channels.telegram.execApprovals.approvers`（回退到 `allowFrom` / `defaultTo` 中的数字 owner ID） - - `channels.telegram.execApprovals.target`: `dm`（默认）| `channel` | `both` + - `channels.telegram.execApprovals.enabled`（当至少一个审批者可解析时自动启用） + - `channels.telegram.execApprovals.approvers`（回退到来自 `allowFrom` / `defaultTo` 的数字所有者 ID） + - `channels.telegram.execApprovals.target`：`dm`（默认）| `channel` | `both` - `agentFilter`、`sessionFilter` - 渠道投递会在聊天中显示命令文本；仅在受信任的群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。执行审批默认在 30 分钟后过期。 + 渠道投递会在聊天中显示命令文本；仅在可信群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。执行审批默认在 30 分钟后过期。 - 内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过执行审批解析。 + 内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标界面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 通过插件审批解析；其他 ID 会先通过执行审批解析。 - 参见 [执行审批](/zh-CN/tools/exec-approvals)。 + 参见[执行审批](/zh-CN/tools/exec-approvals)。 ## 错误回复控制 -当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以抑制该错误。两个配置键控制此行为： +当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以将其抑制。两个配置键控制此行为： -| 键 | 值 | 默认值 | 描述 | -| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 向同一聊天发送错误回复之间的最短时间。防止服务中断期间出现错误刷屏。 | +| 键 | 值 | 默认值 | 描述 | +| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 | +| `channels.telegram.errorCooldownMs` | 数字（毫秒） | `60000` | 同一聊天两次错误回复之间的最短时间。防止故障期间出现错误刷屏。 | 支持按账号、按群组和按话题覆盖（继承方式与其他 Telegram 配置键相同）。 @@ -823,50 +825,50 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## 故障排除 - + - 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。 - BotFather：`/setprivacy` -> Disable - - 然后移除 bot 并重新添加到群组 - - 当配置期望接收未提及的群组消息时，`openclaw channels status` 会发出警告。 - - `openclaw channels status --probe` 可以检查明确的数字群组 ID；通配符 `"*"` 无法探测成员关系。 + - 然后将机器人从群组移除并重新添加 + - 当配置期望接收未提及机器人的群组消息时，`openclaw channels status` 会发出警告。 + - `openclaw channels status --probe` 可以检查明确的数字群组 ID；通配符 `"*"` 无法进行成员资格探测。 - 快速会话测试：`/activation always`。 - + - - 当存在 `channels.telegram.groups` 时，必须列出该群组（或包含 `"*"`） - - 验证 bot 是否为群组成员 - - 查看日志：`openclaw logs --follow` 获取跳过原因 + - 当 `channels.telegram.groups` 存在时，群组必须被列出（或包含 `"*"`） + - 验证机器人在群组中的成员资格 + - 查看日志：使用 `openclaw logs --follow` 查找跳过原因 - + - 授权你的发送者身份（配对和/或数字 `allowFrom`） - 即使群组策略为 `open`，命令授权仍然适用 - - `setMyCommands failed` 并带有 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单 - - `setMyCommands failed` 并带有网络/fetch 错误，通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性问题 + - `setMyCommands failed` 并伴随 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生菜单 + - `setMyCommands failed` 并伴随网络/获取错误，通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题 - + - - `getMe returned 401` 是配置的 bot token 出现 Telegram 认证失败。 - - 在 BotFather 中重新复制或重新生成 bot token，然后更新默认账号的 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts..botToken` 或 `TELEGRAM_BOT_TOKEN`。 - - 启动期间的 `deleteWebhook 401 Unauthorized` 也是认证失败；将其视为“没有 webhook 存在”只会把同一个错误 token 失败推迟到后续 API 调用。 + - `getMe returned 401` 是配置的机器人令牌发生 Telegram 身份验证失败。 + - 在 BotFather 中重新复制或重新生成机器人令牌，然后为默认账号更新 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts..botToken` 或 `TELEGRAM_BOT_TOKEN`。 + - 启动期间出现 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“webhook 不存在”只会把同一个错误令牌失败推迟到后续 API 调用。 - - Node 22+ 加自定义 fetch/proxy 时，如果 AbortSignal 类型不匹配，可能触发立即中止行为。 - - 某些主机会先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站可能导致间歇性 Telegram API 失败。 + - 如果 AbortSignal 类型不匹配，Node 22+ 和自定义 fetch/代理可能触发立即中止行为。 + - 某些主机会先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出口可能导致间歇性 Telegram API 失败。 - 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复的网络错误重试。 - - 如果日志包含 `Polling stall detected`，OpenClaw 会在默认 120 秒内没有完成的长轮询活性信号后，重启轮询并重建 Telegram 传输。 - - 只有当长时间运行的 `getUpdates` 调用健康，但你的主机仍报告误报的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的 proxy、DNS、IPv6 或 TLS 出站问题。 - - 在直接出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用： + - 如果日志包含 `Polling stall detected`，OpenClaw 默认会在 120 秒内没有完成的长轮询活性信号后重启轮询并重建 Telegram 传输。 + - 仅当长时间运行的 `getUpdates` 调用是健康的，但你的主机仍然报告误报的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出口问题。 + - 在直接出口/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用： ```yaml channels: @@ -875,7 +877,7 @@ channels: ``` - Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）和 `dnsResultOrder=ipv4first`。 - - 如果你的主机是 WSL2，或明确使用仅 IPv4 行为效果更好，请强制选择地址族： + - 如果你的主机是 WSL2，或明确在仅 IPv4 行为下工作得更好，请强制选择地址族： ```yaml channels: @@ -884,11 +886,7 @@ channels: autoSelectFamily: false ``` - - 默认情况下，已允许 RFC 2544 基准测试范围答案（`198.18.0.0/15`） - 用于 Telegram 媒体下载。如果受信任的 fake-IP 或 - transparent proxy 在媒体下载期间将 `api.telegram.org` 重写为其他 - private/internal/special-use 地址，你可以选择启用 - 仅 Telegram 的绕过： + - 默认情况下，RFC 2544 基准范围答案（`198.18.0.0/15`）已经允许用于 Telegram 媒体下载。如果可信的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写到其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过： ```yaml channels: @@ -897,25 +895,21 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - 同样的选择启用也可按账号在 - `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` 使用。 - - 如果你的 proxy 将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持 - dangerous 标志关闭。Telegram 媒体默认已经允许 RFC 2544 - 基准测试范围。 + - 同一个选择启用也可按账号设置： + `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`。 + - 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已经允许 RFC 2544 基准范围。 `channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram - 媒体 SSRF 防护。仅在受信任且由 operator 控制的 proxy - 环境中使用，例如 Clash、Mihomo 或 Surge fake-IP 路由，且它们会在 - RFC 2544 基准测试范围之外合成 private 或 special-use 答案。 - 对于普通公网 Telegram 访问，请保持关闭。 + 媒体 SSRF 保护。仅在可信且由操作员控制的代理环境中使用，例如 Clash、Mihomo 或 Surge fake-IP 路由，并且它们会合成 RFC 2544 基准 + 范围之外的私有或特殊用途答案。正常公网 Telegram 访问应保持关闭。 - - 环境变量覆盖（临时）： + - 环境覆盖（临时）： - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - 验证 DNS 答案： + - 验证 DNS 应答： ```bash dig +short api.telegram.org A @@ -929,29 +923,29 @@ dig +short api.telegram.org AAAA ## 配置参考 -主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。 +主要参考：[Telegram 配置参考](/zh-CN/gateway/config-channels#telegram)。 -- 启动/身份验证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝） +- 启动/认证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝） - 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、顶层 `bindings[]`（`type: "acp"`） -- 执行审批：`execApprovals`、`accounts.*.execApprovals` +- 执行批准：`execApprovals`、`accounts.*.execApprovals` - 命令/菜单：`commands.native`、`commands.nativeSkills`、`customCommands` -- 线程/回复：`replyToMode` +- 会话串/回复：`replyToMode` - 流式传输：`streaming`（预览）、`streaming.preview.toolProgress`、`blockStreaming` - 格式/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix` - 媒体/网络：`mediaMaxMb`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy` -- 自定义 API 根路径：`apiRoot`（仅 Bot API 根路径；不要包含 `/bot`） +- 自定义 API 根：`apiRoot`（仅 Bot API 根；不要包含 `/bot`） - webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost` - 操作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - 表情回应：`reactionNotifications`、`reactionLevel` - 错误：`errorPolicy`、`errorCooldownMs` -- 写入/历史记录：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` +- 写入/历史：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` -多账号优先级：配置两个或更多账号 ID 时，请设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`），以明确默认路由。否则 OpenClaw 会回退到第一个规范化后的账号 ID，并且 `openclaw doctor` 会发出警告。命名账号会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 值。 +多账号优先级：配置两个或更多账号 ID 时，请设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`），以显式指定默认路由。否则，OpenClaw 会回退到第一个规范化后的账号 ID，并且 `openclaw doctor` 会发出警告。命名账号会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 值。 ## 相关内容 @@ -961,7 +955,7 @@ dig +short api.telegram.org AAAA 将 Telegram 用户配对到 Gateway 网关。 - 群组和话题的允许列表行为。 + 群组和话题允许列表行为。 将入站消息路由到智能体。 diff --git a/docs/zh-CN/cli/infer.md b/docs/zh-CN/cli/infer.md index 0e000df13..3e388a3b2 100644 --- a/docs/zh-CN/cli/infer.md +++ b/docs/zh-CN/cli/infer.md @@ -2,24 +2,24 @@ read_when: - 添加或修改 `openclaw infer` 命令 - 设计稳定的无头能力自动化 -summary: 推理优先的 CLI，用于提供商支持的模型、图像、音频、TTS、视频、Web 和嵌入工作流 +summary: 推理优先的 CLI，用于由提供商支持的模型、图像、音频、TTS、视频、网络和嵌入工作流 title: 推理 CLI x-i18n: - generated_at: "2026-04-28T17:56:04Z" + generated_at: "2026-04-28T20:08:29Z" model: gpt-5.5 provider: openai - source_hash: b284a884605ee7c0095652bf1b947dbc2ce78ef70532a161d97553379f348f6b + source_hash: 8a154cf11a09f6c60117740f42937da3a0e6942931dde6eee6d902fb6e0ba461 source_path: cli/infer.md workflow: 16 --- -`openclaw infer` 是提供商支持的推理工作流的规范无界面接口。 +`openclaw infer` 是由提供商支持的推理工作流的规范无头界面。 -它有意公开的是能力族，而不是原始 Gateway 网关 RPC 名称，也不是原始智能体工具 ID。 +它有意暴露能力系列，而不是原始 gateway RPC 名称，也不是原始智能体工具 id。 -## 将 infer 转换为技能 +## 将 infer 转换为一个技能 -将以下内容复制并粘贴给智能体： +复制并粘贴这段内容给智能体： ```text Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`. @@ -29,11 +29,11 @@ Focus on model runs, image generation, video generation, audio transcription, TT 一个好的基于 infer 的技能应该： - 将常见用户意图映射到正确的 infer 子命令 -- 为它覆盖的工作流包含几个规范的 infer 示例 +- 为它覆盖的工作流包含一些规范 infer 示例 - 在示例和建议中优先使用 `openclaw infer ...` -- 避免在技能正文中重新记录整个 infer 接口 +- 避免在技能正文中重新记录整个 infer 界面 -典型的 infer 聚焦型技能覆盖范围： +典型的 infer 聚焦技能覆盖范围： - `openclaw infer model run` - `openclaw infer image generate` @@ -44,17 +44,17 @@ Focus on model runs, image generation, video generation, audio transcription, TT ## 为什么使用 infer -`openclaw infer` 为 OpenClaw 中由提供商支持的推理任务提供一个一致的 CLI。 +`openclaw infer` 为 OpenClaw 内由提供商支持的推理任务提供一个一致的 CLI。 -优势： +优点： -- 使用 OpenClaw 中已配置的提供商和模型，而不是为每个后端临时接入一次性包装器。 -- 将模型、图像、音频转录、TTS、视频、Web 和嵌入工作流放在同一个命令树下。 +- 使用 OpenClaw 中已配置的提供商和模型，而不是为每个后端连接一次性包装器。 +- 将模型、图像、音频转录、TTS、视频、Web 和嵌入工作流放在一个命令树下。 - 为脚本、自动化和智能体驱动的工作流使用稳定的 `--json` 输出形状。 -- 当任务本质上是“运行推理”时，优先使用 OpenClaw 官方接口。 -- 对大多数 infer 命令使用正常本地路径，无需 Gateway 网关。 +- 当任务本质上是“运行推理”时，优先使用 OpenClaw 第一方界面。 +- 对大多数 infer 命令使用普通本地路径，而不要求 Gateway 网关。 -对于端到端提供商检查，在较低层级的提供商测试通过后，优先使用 `openclaw infer ...`。它会在发出提供商请求之前，演练已发布的 CLI、配置加载、默认智能体解析、内置插件激活、运行时依赖修复以及共享能力运行时。 +对于端到端提供商检查，在较低层级的提供商测试通过后，优先使用 `openclaw infer ...`。它会在发起提供商请求之前演练已发布的 CLI、配置加载、默认智能体解析、内置插件激活、运行时依赖修复，以及共享能力运行时。 ## 命令树 @@ -113,36 +113,37 @@ Focus on model runs, image generation, video generation, audio transcription, TT | 任务 | 命令 | 备注 | | ---------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -| 运行文本/模型提示词 | `openclaw infer model run --prompt "..." --json` | 默认使用正常本地路径 | +| 运行文本/模型提示词 | `openclaw infer model run --prompt "..." --json` | 默认使用普通本地路径 | | 在图像上运行模型提示词 | `openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model` | 对多个图像输入重复使用 `--file` | | 生成图像 | `openclaw infer image generate --prompt "..." --json` | 从现有文件开始时使用 `image edit` | | 描述图像文件 | `openclaw infer image describe --file ./image.png --prompt "..." --json` | `--model` 必须是支持图像的 `` | | 转录音频 | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` 必须是 `` | | 合成语音 | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` 面向 Gateway 网关 | -| 生成视频 | `openclaw infer video generate --prompt "..." --json` | 支持诸如 `--resolution` 的提供商提示 | +| 生成视频 | `openclaw infer video generate --prompt "..." --json` | 支持诸如 `--resolution` 之类的提供商提示 | | 描述视频文件 | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` 必须是 `` | | 搜索 Web | `openclaw infer web search --query "..." --json` | | -| 获取网页 | `openclaw infer web fetch --url https://example.com --json` | | +| 获取 Web 页面 | `openclaw infer web fetch --url https://example.com --json` | | | 创建嵌入 | `openclaw infer embedding create --text "..." --json` | | ## 行为 -- `openclaw infer ...` 是这些工作流的主要 CLI 接口。 +- `openclaw infer ...` 是这些工作流的主要 CLI 界面。 - 当输出会被另一个命令或脚本消费时，使用 `--json`。 - 当需要特定后端时，使用 `--provider` 或 `--model provider/model`。 - 对于 `image describe`、`audio transcribe` 和 `video describe`，`--model` 必须使用 `` 形式。 -- 对于 `image describe`，显式的 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。`codex/` 会运行一个有边界的 Codex 应用服务器图像理解回合；`openai-codex/` 使用 OpenAI Codex OAuth 提供商路径。 +- 对于 `image describe`，显式 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中支持图像。`codex/` 会运行一个有界的 Codex 应用服务器图像理解回合；`openai-codex/` 使用 OpenAI Codex OAuth 提供商路径。 - 无状态执行命令默认使用本地。 - Gateway 网关管理的状态命令默认使用 Gateway 网关。 -- 正常本地路径不要求 Gateway 网关正在运行。 -- 本地 `model run` 是精简的一次性提供商补全。它会解析已配置的智能体模型和认证，但不会启动聊天智能体回合、加载工具或打开内置 MCP 服务器。 -- `model run --file` 接受图像文件，检测其 MIME 类型，并将它们与提供的提示词一起发送给所选模型。对多个图像重复使用 `--file`。 +- 普通本地路径不要求 Gateway 网关正在运行。 +- 本地 `model run` 是一个轻量的一次性提供商补全。它会解析已配置的智能体模型和凭证，但不会启动聊天智能体回合、加载工具，或打开内置 MCP 服务器。 +- `model run --file` 接受图像文件，检测其 MIME 类型，并将其连同提供的提示词发送到选定模型。对多个图像重复使用 `--file`。 - `model run --file` 会拒绝非图像输入。音频文件使用 `infer audio transcribe`，视频文件使用 `infer video describe`。 -- `model run --gateway` 会演练 Gateway 网关路由、已保存认证、提供商选择和嵌入式运行时，但仍作为原始模型探针运行：它会发送提供的提示词和任何图像附件，不包含之前的会话转录、bootstrap/AGENTS 上下文、上下文引擎组装、工具或内置 MCP 服务器。 +- `model run --gateway` 会演练 Gateway 网关路由、已保存凭证、提供商选择和嵌入式运行时，但仍作为原始模型探针运行：它会发送提供的提示词和任何图像附件，不包含先前的会话转录、bootstrap/AGENTS 上下文、上下文引擎组装、工具或内置 MCP 服务器。 +- `model run --gateway --model ` 需要受信任的操作员 Gateway 网关凭证，因为该请求要求 Gateway 网关运行一次性提供商/模型覆盖。 ## 模型 -使用 `model` 进行提供商支持的文本推理以及模型/提供商检查。 +使用 `model` 进行由提供商支持的文本推理以及模型/提供商检查。 ```bash openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json @@ -152,7 +153,7 @@ openclaw infer model providers --json openclaw infer model inspect --name gpt-5.5 --json ``` -使用完整的 `` 引用来冒烟测试特定提供商，而无需启动 Gateway 网关或加载完整的智能体工具接口： +使用完整的 `` 引用来冒烟测试特定提供商，而无需启动 Gateway 网关或加载完整的智能体工具界面： ```bash openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --json @@ -166,14 +167,14 @@ openclaw infer model run --local --model ollama/qwen2.5vl:7b --prompt "Describe 备注： -- 本地 `model run` 是用于检查提供商/模型/认证健康状况的最窄 CLI 冒烟测试，因为它只将提供的提示词发送给所选模型。 -- 本地 `model run --file` 保持这条精简路径，并将图像内容直接附加到单个用户消息。常见图像文件（如 PNG、JPEG 和 WebP）在其 MIME 类型被检测为 `image/*` 时可用；不受支持或无法识别的文件会在调用提供商之前失败。 -- 当你想直接测试所选多模态文本模型时，`model run --file` 最合适。当你想使用 OpenClaw 的图像理解提供商选择和默认图像模型路由时，使用 `infer image describe`。 -- 所选模型必须支持图像输入；纯文本模型可能会在提供商层拒绝请求。 +- 本地 `model run` 是用于检查提供商/模型/凭证健康状况的最窄 CLI 冒烟测试，因为它只把提供的提示词发送到选定模型。 +- 本地 `model run --file` 保持这条轻量路径，并将图像内容直接附加到单个用户消息。PNG、JPEG 和 WebP 等常见图像文件在其 MIME 类型被检测为 `image/*` 时可以工作；不支持或无法识别的文件会在调用提供商之前失败。 +- 当你想直接测试选定的多模态文本模型时，`model run --file` 最合适。当你想使用 OpenClaw 的图像理解提供商选择和默认图像模型路由时，使用 `infer image describe`。 +- 选定模型必须支持图像输入；纯文本模型可能会在提供商层拒绝该请求。 - `model run --prompt` 必须包含非空白文本；空提示词会在调用本地提供商或 Gateway 网关之前被拒绝。 -- 当提供商未返回文本输出时，本地 `model run` 会以非零状态退出，因此不可达的本地提供商和空补全不会看起来像成功的探针。 -- 当你需要测试 Gateway 网关路由、智能体运行时设置或 Gateway 网关管理的提供商状态，同时保持模型输入为原始形式时，使用 `model run --gateway`。当你想要完整的智能体上下文、工具、记忆和会话转录时，使用 `openclaw agent` 或聊天接口。 -- `model auth login`、`model auth logout` 和 `model auth status` 管理已保存的提供商认证状态。 +- 当提供商没有返回文本输出时，本地 `model run` 会以非零状态退出，因此不可达的本地提供商和空补全不会看起来像成功探针。 +- 当你需要测试 Gateway 网关路由、智能体运行时设置，或 Gateway 网关管理的提供商状态，同时保持模型输入为原始输入时，使用 `model run --gateway`。当你需要完整的智能体上下文、工具、记忆和会话转录时，使用 `openclaw agent` 或聊天界面。 +- `model auth login`、`model auth logout` 和 `model auth status` 管理已保存的提供商凭证状态。 ## 图像 @@ -196,10 +197,10 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --p 备注： - 从现有输入文件开始时，使用 `image edit`。 -- 对于支持参考图像编辑几何提示的提供商/模型，将 `--size`、`--aspect-ratio` 或 `--resolution` 与 `image edit` 一起使用。 -- 使用 `--output-format png --background transparent` 和 `--model openai/gpt-image-1.5` 输出透明背景的 OpenAI PNG；`--openai-background` 仍可作为 OpenAI 专用别名使用。未声明支持背景的提供商会将该提示报告为被忽略的覆盖项。 +- 对支持参考图像编辑几何提示的提供商/模型，将 `--size`、`--aspect-ratio` 或 `--resolution` 与 `image edit` 搭配使用。 +- 将 `--output-format png --background transparent` 与 `--model openai/gpt-image-1.5` 搭配使用，以获得透明背景的 OpenAI PNG 输出；`--openai-background` 仍可作为 OpenAI 专属别名使用。未声明支持背景的提供商会将该提示报告为被忽略的覆盖。 - 使用 `image providers --json` 验证哪些内置图像提供商可被发现、已配置、已选中，以及每个提供商公开哪些生成/编辑能力。 -- 使用 `image generate --model --json` 作为图像生成变更最窄的实时 CLI 冒烟测试。示例： +- 使用 `image generate --model --json` 作为图像生成变更的最窄实时 CLI 冒烟测试。示例： ```bash openclaw infer image providers --json @@ -211,13 +212,13 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --p ``` JSON 响应会报告 `ok`、`provider`、`model`、`attempts` 和写入的 - 输出路径。设置 `--output` 时，最终扩展名可能会跟随 + 输出路径。设置 `--output` 时，最终扩展名可能会遵循 提供商返回的 MIME 类型。 -- 对于 `image describe` 和 `image describe-many`，使用 `--prompt` 给视觉模型一条特定于任务的指令，例如 OCR、比较、UI 检查或简洁配图说明。 -- 对于较慢的本地视觉模型或冷启动的 Ollama，使用 `--timeout-ms`。 -- 对于 `image describe`，`--model` 必须是支持图像的 ``。 -- 对于本地 Ollama 视觉模型，先拉取模型，并将 `OLLAMA_API_KEY` 设置为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。 +- 对于 `image describe` 和 `image describe-many`，使用 `--prompt` 给视觉模型提供特定任务指令，例如 OCR、比较、UI 检查或简洁图注。 +- 对较慢的本地视觉模型或冷启动的 Ollama，使用 `--timeout-ms`。 +- 对于 `image describe`，`--model` 必须是具备图像能力的 ``。 +- 对于本地 Ollama 视觉模型，请先拉取模型，并将 `OLLAMA_API_KEY` 设置为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。 ## 音频 @@ -236,7 +237,7 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso ## TTS -使用 `tts` 进行语音合成和 TTS 提供商状态管理。 +使用 `tts` 进行语音合成和 TTS 提供商状态检查。 ```bash openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json @@ -247,7 +248,7 @@ openclaw infer tts status --json 注意： -- `tts status` 默认使用 Gateway 网关，因为它反映由 Gateway 网关管理的 TTS 状态。 +- `tts status` 默认使用 gateway，因为它反映由 gateway 管理的 TTS 状态。 - 使用 `tts providers`、`tts voices` 和 `tts set-provider` 检查并配置 TTS 行为。 ## 视频 @@ -268,7 +269,7 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js ## Web -使用 `web` 进行搜索和获取工作流。 +使用 `web` 执行搜索和获取工作流。 ```bash openclaw infer web search --query "OpenClaw docs" --json @@ -283,7 +284,7 @@ openclaw infer web providers --json ## 嵌入 -使用 `embedding` 创建向量并检查嵌入提供商。 +使用 `embedding` 进行向量创建和嵌入提供商检查。 ```bash openclaw infer embedding create --text "friendly lobster" --json @@ -293,7 +294,7 @@ openclaw infer embedding providers --json ## JSON 输出 -Infer 命令会将 JSON 输出规范化到共享封套下： +Infer 命令会在共享封套下规范化 JSON 输出： ```json { @@ -318,11 +319,11 @@ Infer 命令会将 JSON 输出规范化到共享封套下： - `outputs` - `error` -对于生成媒体命令，`outputs` 包含 OpenClaw 写入的文件。自动化时请使用 -该数组中的 `path`、`mimeType`、`size` 和任何媒体特定尺寸， -而不是解析供人阅读的 stdout。 +对于生成媒体命令，`outputs` 包含 OpenClaw 写入的文件。请使用 +该数组中的 `path`、`mimeType`、`size` 和任何媒体特定尺寸 +进行自动化处理，而不是解析面向人类的 stdout。 -## 常见问题 +## 常见陷阱 ```bash # Bad diff --git a/docs/zh-CN/gateway/protocol.md b/docs/zh-CN/gateway/protocol.md index fd90a101c..7a5f023a5 100644 --- a/docs/zh-CN/gateway/protocol.md +++ b/docs/zh-CN/gateway/protocol.md @@ -2,25 +2,25 @@ read_when: - 实现或更新 Gateway 网关 WS 客户端 - 调试协议不匹配或连接失败 - - 重新生成协议架构/模型 + - 正在重新生成协议模式/模型 summary: Gateway 网关 WebSocket 协议：握手、帧、版本控制 title: Gateway 网关协议 x-i18n: - generated_at: "2026-04-28T11:53:37Z" + generated_at: "2026-04-28T20:08:34Z" model: gpt-5.5 provider: openai - source_hash: ab961f1ec245e93f5f88a641f558124c36c4c828ba66ff3a2ccd41ba1f12b646 + source_hash: 95845fc2aa56b0a53cf8c62c517b70d2624b15e707d84503c791af572360aff2 source_path: gateway/protocol.md workflow: 16 --- -Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输协议**。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明其**角色** + **作用域**。 +Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输协议**。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明它们的**角色** + **作用域**。 -## 传输 +## 传输协议 -- WebSocket，包含 JSON 负载的文本帧。 +- WebSocket，使用带 JSON 载荷的文本帧。 - 第一帧**必须**是 `connect` 请求。 -- 连接前帧上限为 64 KiB。握手成功后，客户端应遵循 `hello-ok.policy.maxPayload` 和 `hello-ok.policy.maxBufferedBytes` 限制。启用诊断后，过大的入站帧和缓慢的出站缓冲区会在 Gateway 网关关闭或丢弃受影响帧之前发出 `payload.large` 事件。这些事件会保留大小、限制、表面和安全原因代码。它们不会保留消息正文、附件内容、原始帧正文、令牌、Cookie 或秘密值。 +- 连接前帧大小上限为 64 KiB。握手成功后，客户端应遵循 `hello-ok.policy.maxPayload` 和 `hello-ok.policy.maxBufferedBytes` 限制。启用诊断后，超大入站帧和缓慢出站缓冲区会在 Gateway 网关关闭或丢弃受影响帧之前发出 `payload.large` 事件。这些事件会保留大小、限制、表面和安全原因码。它们不会保留消息正文、附件内容、原始帧正文、令牌、Cookie 或机密值。 ## 握手（connect） @@ -95,7 +95,7 @@ Gateway 网关 → 客户端： } ``` -`server`、`features`、`snapshot` 和 `policy` 都是 schema（`src/gateway/protocol/schema/frames.ts`）要求的字段。`auth` 也是必需的，并报告协商后的角色/作用域。`canvasHostUrl` 是可选的。 +`server`、`features`、`snapshot` 和 `policy` 都是 schema（`src/gateway/protocol/schema/frames.ts`）要求的字段。`auth` 也是必需字段，并报告协商后的角色/作用域。`canvasHostUrl` 是可选字段。 未签发设备令牌时，`hello-ok.auth` 会报告协商后的权限，不包含令牌字段： @@ -108,9 +108,9 @@ Gateway 网关 → 客户端： } ``` -受信任的同进程后端客户端（`client.id: "gateway-client"`、`client.mode: "backend"`）在通过共享 Gateway 网关令牌/密码认证时，可以在直接 loopback 连接上省略 `device`。此路径保留给内部控制平面 RPC，并避免过期的 CLI/设备配对基线阻塞本地后端工作，例如子智能体会话更新。远程客户端、浏览器来源客户端、节点客户端，以及显式设备令牌/设备身份客户端，仍使用正常的配对和作用域升级检查。 +受信任的同进程后端客户端（`client.id: "gateway-client"`、`client.mode: "backend"`）在使用共享 Gateway 网关令牌/密码进行身份验证时，可以在直接 local loopback 连接上省略 `device`。此路径保留给内部控制平面 RPC，可避免过期的 CLI/设备配对基线阻塞本地后端工作，例如子智能体会话更新。远程客户端、浏览器源客户端、节点客户端，以及显式设备令牌/设备身份客户端仍使用正常的配对和作用域升级检查。 -签发设备令牌时，`hello-ok` 还包含： +签发设备令牌时，`hello-ok` 还会包含： ```json { @@ -122,7 +122,7 @@ Gateway 网关 → 客户端： } ``` -在受信任的启动交接期间，`hello-ok.auth` 也可能在 `deviceTokens` 中包含额外的有界角色条目： +在受信任的引导交接期间，`hello-ok.auth` 也可能在 `deviceTokens` 中包含其他有边界的角色条目： ```json { @@ -141,7 +141,7 @@ Gateway 网关 → 客户端： } ``` -对于内置的节点/operator 启动流程，主节点令牌保持 `scopes: []`，任何交接的 operator 令牌都保持限定在启动 operator 允许列表内（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）。启动作用域检查保持角色前缀：operator 条目只满足 operator 请求，非 operator 角色仍需要其自身角色前缀下的作用域。 +对于内置节点/operator 引导流程，主节点令牌保持 `scopes: []`，任何交接出的 operator 令牌都保持限定在引导 operator 允许列表（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）内。引导作用域检查保持角色前缀规则：operator 条目只满足 operator 请求，非 operator 角色仍需要其自身角色前缀下的作用域。 ### 节点示例 @@ -178,13 +178,13 @@ Gateway 网关 → 客户端： } ``` -## 帧格式 +## 分帧 - **请求**：`{type:"req", id, method, params}` - **响应**：`{type:"res", id, ok, payload|error}` - **事件**：`{type:"event", event, payload, seq?, stateVersion?}` -有副作用的方法需要**幂等键**（见 schema）。 +有副作用的方法需要**幂等键**（参见 schema）。 ## 角色 + 作用域 @@ -195,7 +195,7 @@ Gateway 网关 → 客户端： ### 作用域（operator） -常用作用域： +常见作用域： - `operator.read` - `operator.write` @@ -206,35 +206,35 @@ Gateway 网关 → 客户端： 带有 `includeSecrets: true` 的 `talk.config` 需要 `operator.talk.secrets`（或 `operator.admin`）。 -插件注册的 Gateway 网关 RPC 方法可以请求自己的 operator 作用域，但保留的核心管理员前缀（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终解析为 `operator.admin`。 +插件注册的 Gateway 网关 RPC 方法可以请求自己的 operator 作用域，但保留的核心 admin 前缀（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终解析为 `operator.admin`。 -方法作用域只是第一道门槛。某些通过 `chat.send` 到达的斜杠命令会在此基础上应用更严格的命令级检查。例如，持久化的 `/config set` 和 `/config unset` 写入需要 `operator.admin`。 +方法作用域只是第一道门槛。某些通过 `chat.send` 到达的斜杠命令会在此之上应用更严格的命令级检查。例如，持久化的 `/config set` 和 `/config unset` 写入需要 `operator.admin`。 -`node.pair.approve` 在基础方法作用域之上还有一个额外的审批时作用域检查： +`node.pair.approve` 也会在基础方法作用域之上进行额外的批准时作用域检查： - 无命令请求：`operator.pairing` -- 带有非 exec 节点命令的请求：`operator.pairing` + `operator.write` +- 带非 exec 节点命令的请求：`operator.pairing` + `operator.write` - 包含 `system.run`、`system.run.prepare` 或 `system.which` 的请求：`operator.pairing` + `operator.admin` -### 能力/命令/权限（node） +### 能力/命令/权限（节点） 节点在连接时声明能力声明： -- `caps`：高级能力类别。 +- `caps`：高层能力类别。 - `commands`：用于调用的命令允许列表。 - `permissions`：细粒度开关（例如 `screen.record`、`camera.capture`）。 -Gateway 网关将这些视为**声明**，并强制执行服务端允许列表。 +Gateway 网关将这些视为**声明**，并执行服务端允许列表。 ## 在线状态 - `system-presence` 返回按设备身份键控的条目。 -- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，因此即使设备同时以 **operator** 和 **node** 连接，UI 也可以为每个设备显示一行。 -- `node.list` 包含可选的 `lastSeenAtMs` 和 `lastSeenReason` 字段。已连接节点会将其当前连接时间报告为 `lastSeenAtMs`，原因是 `connect`；当受信任节点事件更新其配对元数据时，已配对节点也可以报告持久的后台在线状态。 +- 在线状态条目包括 `deviceId`、`roles` 和 `scopes`，因此 UI 即使在设备同时以 **operator** 和 **node** 身份连接时，也能为每个设备显示单行。 +- `node.list` 包含可选的 `lastSeenAtMs` 和 `lastSeenReason` 字段。已连接节点会将其当前连接时间报告为 `lastSeenAtMs`，原因是 `connect`；当受信任节点事件更新其配对元数据时，已配对节点也可以报告持久后台在线状态。 ### 节点后台存活事件 -节点可以使用 `event: "node.presence.alive"` 调用 `node.event`，以记录已配对节点在后台唤醒期间仍然存活，而不将其标记为已连接。 +节点可以调用带有 `event: "node.presence.alive"` 的 `node.event`，以记录某个已配对节点在后台唤醒期间处于存活状态，而不将其标记为已连接。 ```json { @@ -243,7 +243,7 @@ Gateway 网关将这些视为**声明**，并强制执行服务端允许列表 } ``` -`trigger` 是一个封闭枚举：`background`、`silent_push`、`bg_app_refresh`、`significant_location`、`manual` 或 `connect`。未知触发器字符串在持久化前会由 Gateway 网关规范化为 `background`。该事件仅对已认证的节点设备会话持久；无设备或未配对会话返回 `handled: false`。 +`trigger` 是封闭枚举：`background`、`silent_push`、`bg_app_refresh`、`significant_location`、`manual` 或 `connect`。未知触发器字符串会在持久化前由 Gateway 网关规范化为 `background`。该事件仅对已认证的节点设备会话持久化；无设备或未配对会话返回 `handled: false`。 成功的 Gateway 网关返回结构化结果： @@ -256,52 +256,52 @@ Gateway 网关将这些视为**声明**，并强制执行服务端允许列表 } ``` -较旧的 Gateway 网关仍可能为 `node.event` 返回 `{ "ok": true }`；客户端应将其视为已确认的 RPC，而不是持久在线状态持久化。 +较旧的 Gateway 网关对 `node.event` 仍可能返回 `{ "ok": true }`；客户端应将其视为已确认的 RPC，而不是持久在线状态持久化。 -## 广播事件作用域限定 +## 广播事件作用域 -服务端推送的 WebSocket 广播事件受作用域限制，因此配对作用域或仅节点会话不会被动接收会话内容。 +服务端推送的 WebSocket 广播事件受作用域限制，因此配对作用域会话或仅节点会话不会被动接收会话内容。 - **聊天、智能体和工具结果帧**（包括流式 `agent` 事件和工具调用结果）至少需要 `operator.read`。没有 `operator.read` 的会话会完全跳过这些帧。 -- **插件定义的 `plugin.*` 广播**根据插件注册方式，受限于 `operator.write` 或 `operator.admin`。 +- **插件定义的 `plugin.*` 广播**会根据插件注册方式限制为 `operator.write` 或 `operator.admin`。 - **Status 和传输事件**（`heartbeat`、`presence`、`tick`、连接/断开生命周期等）保持不受限制，因此每个已认证会话都能观察传输健康状态。 -- **未知广播事件族**默认受作用域限制（失败关闭），除非已注册的处理程序显式放宽限制。 +- **未知广播事件族**默认受作用域限制（失败关闭），除非已注册处理程序显式放宽限制。 -每个客户端连接都会保留自己的按客户端序列号，因此即使不同客户端看到事件流中不同的作用域过滤子集，广播也会在该 socket 上保持单调顺序。 +每个客户端连接都会保留自己的逐客户端序列号，因此即使不同客户端看到的事件流子集因作用域过滤而不同，广播也能在该 socket 上保持单调顺序。 ## 常见 RPC 方法族 -公开 WS 表面比上面的握手/认证示例更广。这不是生成的转储，`hello-ok.features.methods` 是一个保守的发现列表，基于 `src/gateway/server-methods-list.ts` 加载的插件/渠道方法导出构建。请将其视为功能发现，而不是对 `src/gateway/server-methods/*.ts` 的完整枚举。 +公共 WS 表面比上面的握手/认证示例更广。这不是生成的转储 — `hello-ok.features.methods` 是从 `src/gateway/server-methods-list.ts` 加上已加载插件/渠道方法导出构建的保守设备发现列表。请将其视为功能设备发现，而不是 `src/gateway/server-methods/*.ts` 的完整枚举。 - + - `health` 返回缓存的或新探测的 Gateway 网关健康快照。 - - `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它保留事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称和会话 ID 等运行元数据。它不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie 或秘密值。需要 operator 读取作用域。 - - `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅包含给具备管理员作用域的 operator 客户端。 - - `gateway.identity.get` 返回中继和配对流程使用的 Gateway 网关设备身份。 - - `system-presence` 返回已连接 operator/节点设备的当前在线状态快照。 - - `system-event` 追加系统事件，并可以更新/广播在线状态上下文。 - - `last-heartbeat` 返回最近持久化的心跳事件。 + - `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它保留事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称和会话 ID 等运行元数据。它不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie 或机密值。需要 operator read 作用域。 + - `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅包含给具有 admin 作用域的 operator 客户端。 + - `gateway.identity.get` 返回 relay 和配对流程使用的 Gateway 网关设备身份。 + - `system-presence` 返回已连接 operator/node 设备的当前在线状态快照。 + - `system-event` 追加一个系统事件，并可以更新/广播在线状态上下文。 + - `last-heartbeat` 返回最新持久化的心跳事件。 - `set-heartbeats` 切换 Gateway 网关上的心跳处理。 - + - `models.list` 返回运行时允许的模型目录。传入 `{ "view": "configured" }` 获取适合选择器大小的已配置模型（先是 `agents.defaults.models`，然后是 `models.providers.*.models`），或传入 `{ "view": "all" }` 获取完整目录。 - - `usage.status` 返回提供商用量窗口/剩余额度摘要。 - - `usage.cost` 返回某个日期范围内的聚合成本用量摘要。 - - `doctor.memory.status` 返回活动默认智能体工作区的向量内存/缓存嵌入就绪状态。仅在调用方明确需要实时嵌入提供商 ping 时，传入 `{ "probe": true }` 或 `{ "deep": true }`。 - - `sessions.usage` 返回按会话划分的用量摘要。 - - `sessions.usage.timeseries` 返回一个会话的时间序列用量。 - - `sessions.usage.logs` 返回一个会话的用量日志条目。 + - `usage.status` 返回提供商使用窗口/剩余额度摘要。 + - `usage.cost` 返回日期范围内的聚合成本使用摘要。 + - `doctor.memory.status` 返回活动默认 Agent 工作区的向量内存/缓存嵌入就绪状态。仅当调用方明确想要实时嵌入提供商 ping 时，才传入 `{ "probe": true }` 或 `{ "deep": true }`。 + - `sessions.usage` 返回每个会话的使用摘要。 + - `sessions.usage.timeseries` 返回一个会话的时间序列使用情况。 + - `sessions.usage.logs` 返回一个会话的使用日志条目。 - - `channels.status` 返回内置 + 捆绑渠道/插件的状态摘要。 - - `channels.logout` 会在渠道支持登出时登出特定渠道/账号。 - - `web.login.start` 为当前支持二维码的网页渠道提供商启动二维码/网页登录流程。 - - `web.login.wait` 等待该二维码/网页登录流程完成，并在成功后启动渠道。 + - `channels.status` 返回内置 + 随附渠道/插件 Status 摘要。 + - `channels.logout` 会在渠道支持登出时登出指定渠道/账户。 + - `web.login.start` 为当前支持 QR 的 Web 渠道提供商启动 QR/Web 登录流程。 + - `web.login.wait` 等待该 QR/Web 登录流程完成，并在成功后启动该渠道。 - `push.test` 向已注册的 iOS 节点发送测试 APNs 推送。 - `voicewake.get` 返回已存储的唤醒词触发器。 - `voicewake.set` 更新唤醒词触发器并广播变更。 @@ -309,44 +309,44 @@ Gateway 网关将这些视为**声明**，并强制执行服务端允许列表 - - `send` 是直接出站投递 RPC，用于在聊天运行器之外按渠道/账号/会话线程目标发送消息。 - - `logs.tail` 返回已配置的 Gateway 网关文件日志尾部内容，支持游标/限制和最大字节数控制。 + - `send` 是用于在聊天运行器之外按渠道/账户/线程目标直接发送的出站投递 RPC。 + - `logs.tail` 返回已配置的 Gateway 网关文件日志尾部，并带有游标/限制和最大字节控制。 - - `talk.config` 返回生效的 Talk 配置载荷；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。 - - `talk.mode` 为 WebChat/Control UI 客户端设置/广播当前 Talk 模式状态。 - - `talk.speak` 通过活动 Talk 语音提供商合成语音。 - - `tts.status` 返回 TTS 启用状态、活动提供商、回退提供商和提供商配置状态。 + - `talk.config` 返回有效的 Talk 配置载荷；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。 + - `talk.mode` 设置/广播 WebChat/Control UI 客户端的当前 Talk 模式状态。 + - `talk.speak` 通过活动的 Talk 语音提供商合成语音。 + - `tts.status` 返回 TTS 启用状态、活动提供商、备用提供商和提供商配置状态。 - `tts.providers` 返回可见的 TTS 提供商清单。 - - `tts.enable` 和 `tts.disable` 切换 TTS 偏好设置状态。 + - `tts.enable` 和 `tts.disable` 切换 TTS 偏好状态。 - `tts.setProvider` 更新首选 TTS 提供商。 - `tts.convert` 运行一次性文本转语音转换。 - - `secrets.reload` 重新解析活动 SecretRefs，并且仅在完全成功时替换运行时密钥状态。 + - `secrets.reload` 重新解析活动的 SecretRefs，并且仅在完全成功时替换运行时密钥状态。 - `secrets.resolve` 为特定命令/目标集合解析面向命令目标的密钥分配。 - `config.get` 返回当前配置快照和哈希。 - - `config.set` 写入已验证的配置载荷。 + - `config.set` 写入经过验证的配置载荷。 - `config.patch` 合并部分配置更新。 - - `config.apply` 验证 + 替换完整配置载荷。 - - `config.schema` 返回 Control UI 和 CLI 工具使用的实时配置架构载荷：架构、`uiHints`、版本和生成元数据，包括运行时可以加载时的插件 + 渠道架构元数据。该架构包含字段 `title` / `description` 元数据，这些元数据派生自 UI 使用的相同标签和帮助文本，包括在存在匹配字段文档时的嵌套对象、通配符、数组项以及 `anyOf` / `oneOf` / `allOf` 组合分支。 - - `config.schema.lookup` 返回一个配置路径的路径范围查找载荷：规范化路径、浅层架构节点、匹配的提示 + `hintPath`，以及用于 UI/CLI 下钻的直接子项摘要。查找架构节点会保留面向用户的文档和常见验证字段（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数字/字符串/数组/对象边界，以及 `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` 等标志）。子项摘要公开 `key`、规范化 `path`、`type`、`required`、`hasChildren`，以及匹配的 `hint` / `hintPath`。 + - `config.apply` 验证并替换完整配置载荷。 + - `config.schema` 返回 Control UI 和 CLI 工具使用的实时配置架构载荷：架构、`uiHints`、版本和生成元数据，包括运行时能够加载时的插件 + 渠道架构元数据。该架构包含字段 `title` / `description` 元数据，这些元数据派生自 UI 使用的同一组标签和帮助文本；当存在匹配的字段文档时，也包括嵌套对象、通配符、数组项以及 `anyOf` / `oneOf` / `allOf` 组合分支。 + - `config.schema.lookup` 为一个配置路径返回路径限定的查找载荷：规范化路径、浅层架构节点、匹配的提示 + `hintPath`，以及用于 UI/CLI 下钻的直接子项摘要。查找架构节点会保留面向用户的文档和常见验证字段（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数字/字符串/数组/对象边界，以及 `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` 等标志）。子项摘要公开 `key`、规范化的 `path`、`type`、`required`、`hasChildren`，以及匹配的 `hint` / `hintPath`。 - `update.run` 运行 Gateway 网关更新流程，并且仅在更新本身成功时安排重启。 - `update.status` 返回最新缓存的更新重启哨兵，包括可用时重启后的运行版本。 - - `wizard.start`、`wizard.next`、`wizard.status` 和 `wizard.cancel` 通过 WS RPC 公开新手引导向导。 + - `wizard.start`、`wizard.next`、`wizard.status` 和 `wizard.cancel` 通过 WS RPC 暴露新手引导向导。 - `agents.list` 返回已配置的智能体条目。 - - `agents.create`、`agents.update` 和 `agents.delete` 管理智能体记录和工作区连接。 - - `agents.files.list`、`agents.files.get` 和 `agents.files.set` 管理为智能体公开的引导工作区文件。 - - `agent.identity.get` 返回智能体或会话的生效助手身份。 - - `agent.wait` 等待一次运行结束，并在可用时返回终止快照。 + - `agents.create`、`agents.update` 和 `agents.delete` 管理智能体记录和工作区接线。 + - `agents.files.list`、`agents.files.get` 和 `agents.files.set` 管理为智能体暴露的引导工作区文件。 + - `agent.identity.get` 返回智能体或会话的有效助手身份。 + - `agent.wait` 等待运行完成，并在可用时返回终止快照。 @@ -355,7 +355,7 @@ Gateway 网关将这些视为**声明**，并强制执行服务端允许列表 - `sessions.subscribe` 和 `sessions.unsubscribe` 为当前 WS 客户端切换会话变更事件订阅。 - `sessions.messages.subscribe` 和 `sessions.messages.unsubscribe` 为一个会话切换转录/消息事件订阅。 - `sessions.preview` 返回特定会话键的有界转录预览。 - - `sessions.resolve` 解析会话目标或将其规范化。 + - `sessions.resolve` 解析或规范化会话目标。 - `sessions.create` 创建新的会话条目。 - `sessions.send` 向现有会话发送消息。 - `sessions.steer` 是活动会话的中断并引导变体。 @@ -363,42 +363,42 @@ Gateway 网关将这些视为**声明**，并强制执行服务端允许列表 - `sessions.patch` 更新会话元数据/覆盖项。 - `sessions.reset`、`sessions.delete` 和 `sessions.compact` 执行会话维护。 - `sessions.get` 返回完整存储的会话行。 - - 聊天执行仍使用 `chat.history`、`chat.send`、`chat.abort` 和 `chat.inject`。`chat.history` 会为 UI 客户端进行显示规范化：从可见文本中剥离内联指令标签，剥离纯文本工具调用 XML 载荷（包括 `...`、`...`、`...`、`...` 以及被截断的工具调用块）和泄露的 ASCII/全角模型控制令牌，省略精确 `NO_REPLY` / `no_reply` 等纯静默令牌助手行，并且超大行可以替换为占位符。 + - 聊天执行仍使用 `chat.history`、`chat.send`、`chat.abort` 和 `chat.inject`。`chat.history` 会针对 UI 客户端进行显示规范化：从可见文本中剥离内联指令标签，剥离纯文本工具调用 XML 载荷（包括 `...`、`...`、`...`、`...` 和被截断的工具调用块）以及泄漏的 ASCII/全角模型控制令牌，省略纯静默令牌助手行，例如精确的 `NO_REPLY` / `no_reply`，并且可用占位符替换过大的行。 - `device.pair.list` 返回待处理和已批准的配对设备。 - `device.pair.approve`、`device.pair.reject` 和 `device.pair.remove` 管理设备配对记录。 - - `device.token.rotate` 在其已批准角色和调用方范围边界内轮换配对设备令牌。 - - `device.token.revoke` 在其已批准角色和调用方范围边界内撤销配对设备令牌。 + - `device.token.rotate` 在已批准的角色和调用方作用域边界内轮换配对设备令牌。 + - `device.token.revoke` 在已批准的角色和调用方作用域边界内撤销配对设备令牌。 - - `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject`、`node.pair.remove` 和 `node.pair.verify` 覆盖节点配对和引导验证。 + - `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject`、`node.pair.remove` 和 `node.pair.verify` 涵盖节点配对和引导验证。 - `node.list` 和 `node.describe` 返回已知/已连接节点状态。 - - `node.rename` 更新配对节点标签。 + - `node.rename` 更新已配对节点标签。 - `node.invoke` 将命令转发到已连接节点。 - `node.invoke.result` 返回调用请求的结果。 - `node.event` 将节点发起的事件带回 Gateway 网关。 - - `node.canvas.capability.refresh` 刷新作用域内的画布能力令牌。 + - `node.canvas.capability.refresh` 刷新限定作用域的画布能力令牌。 - `node.pending.pull` 和 `node.pending.ack` 是已连接节点队列 API。 - `node.pending.enqueue` 和 `node.pending.drain` 管理离线/断开连接节点的持久待处理工作。 - - `exec.approval.request`、`exec.approval.get`、`exec.approval.list` 和 `exec.approval.resolve` 覆盖一次性 exec 审批请求以及待处理审批查找/重放。 - - `exec.approval.waitDecision` 等待一个待处理 exec 审批并返回最终决定（超时则返回 `null`）。 + - `exec.approval.request`、`exec.approval.get`、`exec.approval.list` 和 `exec.approval.resolve` 涵盖一次性 exec 审批请求以及待处理审批查找/重放。 + - `exec.approval.waitDecision` 等待一个待处理的 exec 审批，并返回最终决定（超时则返回 `null`）。 - `exec.approvals.get` 和 `exec.approvals.set` 管理 Gateway 网关 exec 审批策略快照。 - `exec.approvals.node.get` 和 `exec.approvals.node.set` 通过节点中继命令管理节点本地 exec 审批策略。 - - `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision` 和 `plugin.approval.resolve` 覆盖插件定义的审批流程。 + - `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision` 和 `plugin.approval.resolve` 涵盖插件定义的审批流程。 - - 自动化：`wake` 调度立即或下一次心跳时的唤醒文本注入；`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` 管理计划工作。 + - 自动化：`wake` 安排立即或下一次心跳时注入唤醒文本；`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` 管理计划工作。 - Skills 和工具：`commands.list`、`skills.*`、`tools.catalog`、`tools.effective`。 @@ -406,11 +406,12 @@ Gateway 网关将这些视为**声明**，并强制执行服务端允许列表 ### 常见事件系列 -- `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅转录的聊天事件。 +- `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅转录的聊天 + 事件。 - `session.message` 和 `session.tool`：已订阅会话的转录/事件流更新。 -- `sessions.changed`：会话索引或元数据已变更。 -- `presence`：系统在线状态快照更新。 -- `tick`：周期性 keepalive / 活跃性事件。 +- `sessions.changed`：会话索引或元数据已更改。 +- `presence`：系统存在状态快照更新。 +- `tick`：周期性 keepalive / 存活事件。 - `health`：Gateway 网关健康快照更新。 - `heartbeat`：心跳事件流更新。 - `cron`：cron 运行/作业变更事件。 @@ -418,73 +419,86 @@ Gateway 网关将这些视为**声明**，并强制执行服务端允许列表 - `node.pair.requested` / `node.pair.resolved`：节点配对生命周期。 - `node.invoke.request`：节点调用请求广播。 - `device.pair.requested` / `device.pair.resolved`：配对设备生命周期。 -- `voicewake.changed`：唤醒词触发器配置已变更。 -- `exec.approval.requested` / `exec.approval.resolved`：exec 审批生命周期。 -- `plugin.approval.requested` / `plugin.approval.resolved`：插件审批生命周期。 +- `voicewake.changed`：唤醒词触发器配置已更改。 +- `exec.approval.requested` / `exec.approval.resolved`：exec 审批 + 生命周期。 +- `plugin.approval.requested` / `plugin.approval.resolved`：插件审批 + 生命周期。 ### 节点辅助方法 -- 节点可以调用 `skills.bins` 来获取当前技能可执行文件列表，用于自动允许检查。 +- 节点可以调用 `skills.bins` 以获取当前技能可执行文件列表， + 用于自动允许检查。 ### 操作员辅助方法 -- 操作员可以调用 `commands.list`（`operator.read`）来获取智能体的运行时命令清单。 +- 操作员可以调用 `commands.list`（`operator.read`）以获取智能体的运行时 + 命令清单。 - `agentId` 是可选的；省略它可读取默认智能体工作区。 - `scope` 控制主 `name` 面向哪个表面： - `text` 返回不带前导 `/` 的主文本命令令牌 - - `native` 和默认 `both` 路径会在可用时返回提供商感知的原生命名 + - `native` 和默认的 `both` 路径会在可用时返回提供商感知的原生命名 - `textAliases` 携带精确的斜杠别名，例如 `/model` 和 `/m`。 - `nativeName` 在存在时携带提供商感知的原生命令名称。 - - `provider` 是可选的，并且仅影响原生命名和原生插件命令可用性。 - - `includeArgs=false` 会从响应中省略序列化参数元数据。 -- 操作员可以调用 `tools.catalog`（`operator.read`）来获取智能体的运行时工具目录。响应包括分组工具和来源元数据： + - `provider` 是可选的，并且仅影响原生命名以及原生插件命令可用性。 + - `includeArgs=false` 从响应中省略序列化的参数元数据。 +- 操作员可以调用 `tools.catalog`（`operator.read`）以获取智能体的运行时工具目录。响应包括分组工具和来源元数据： - `source`：`core` 或 `plugin` - `pluginId`：当 `source="plugin"` 时的插件所有者 - `optional`：插件工具是否为可选 -- 操作员可以调用 `tools.effective`（`operator.read`）来获取会话的运行时生效工具清单。 +- 操作员可以调用 `tools.effective`（`operator.read`）以获取会话的运行时有效工具 + 清单。 - `sessionKey` 是必需的。 - - Gateway 网关会从服务器端会话派生受信任的运行时上下文，而不是接受调用方提供的认证或投递上下文。 - - 响应限定于会话范围，并反映活动对话现在可以使用的内容，包括核心、插件和渠道工具。 -- 操作员可以调用 `skills.status`（`operator.read`）来获取智能体的可见技能清单。 + - Gateway 网关会从服务器端会话派生受信任的运行时上下文，而不是接受 + 调用方提供的认证或投递上下文。 + - 响应限定于会话作用域，并反映活动对话当前可以使用的内容， + 包括核心、插件和渠道工具。 +- 操作员可以调用 `skills.status`（`operator.read`）以获取智能体的可见 + 技能清单。 - `agentId` 是可选的；省略它可读取默认智能体工作区。 - - 响应包括资格、缺失要求、配置检查，以及不暴露原始密钥值的已清理安装选项。 -- 操作员可以调用 `skills.search` 和 `skills.detail`（`operator.read`）来获取 ClawHub 发现元数据。 -- 操作员可以通过两种模式调用 `skills.install`（`operator.admin`）： - - ClawHub 模式：`{ source: "clawhub", slug, version?, force? }` 会将技能文件夹安装到默认智能体工作区的 `skills/` 目录。 - - Gateway 网关安装器模式：`{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` 会在 Gateway 网关主机上运行声明的 `metadata.openclaw.install` 操作。 -- 操作员可以通过两种模式调用 `skills.update`（`operator.admin`）： - - ClawHub 模式会更新默认智能体工作区中的一个已跟踪 slug，或所有已跟踪的 ClawHub 安装。 - - 配置模式会修补 `skills.entries.` 值，例如 `enabled`、`apiKey` 和 `env`。 + - 响应包括资格、缺失要求、配置检查，以及 + 不暴露原始密钥值的已净化安装选项。 +- 操作员可以调用 `skills.search` 和 `skills.detail`（`operator.read`）以获取 + ClawHub 发现元数据。 +- 操作员可以用两种模式调用 `skills.install`（`operator.admin`）： + - ClawHub 模式：`{ source: "clawhub", slug, version?, force? }` 将一个 + 技能文件夹安装到默认智能体工作区的 `skills/` 目录。 + - Gateway 网关安装器模式：`{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` + 在 Gateway 网关主机上运行声明的 `metadata.openclaw.install` 动作。 +- 操作员可以用两种模式调用 `skills.update`（`operator.admin`）： + - ClawHub 模式会更新默认智能体工作区中一个已跟踪的 slug，或所有已跟踪的 ClawHub 安装。 + - 配置模式会修补 `skills.entries.` 值，例如 `enabled`、 + `apiKey` 和 `env`。 ### `models.list` 视图 `models.list` 接受可选的 `view` 参数： -- 省略或 `"default"`：当前运行时行为。如果配置了 `agents.defaults.models`，响应就是允许的目录；否则响应就是完整 Gateway 网关目录。 -- `"configured"`：适合选择器的行为。如果配置了 `agents.defaults.models`，它仍然优先。否则响应使用显式的 `models.providers.*.models` 条目，仅在不存在已配置模型行时才回退到完整目录。 -- `"all"`：完整 Gateway 网关目录，绕过 `agents.defaults.models`。将其用于诊断和设备发现 UI，而不是普通模型选择器。 +- 省略或 `"default"`：当前运行时行为。如果已配置 `agents.defaults.models`，响应为允许的目录；否则响应为完整的 Gateway 网关目录。 +- `"configured"`：适合选择器大小的行为。如果已配置 `agents.defaults.models`，它仍然优先。否则响应使用显式的 `models.providers.*.models` 条目，仅在不存在已配置模型行时才回退到完整目录。 +- `"all"`：完整的 Gateway 网关目录，绕过 `agents.defaults.models`。将其用于诊断和发现 UI，而不是常规模型选择器。 ## Exec 审批 - 当 exec 请求需要审批时，Gateway 网关会广播 `exec.approval.requested`。 -- 操作员客户端通过调用 `exec.approval.resolve` 来解析（需要 `operator.approvals` 作用域）。 +- 操作员客户端通过调用 `exec.approval.resolve` 来处理（需要 `operator.approvals` 作用域）。 - 对于 `host=node`，`exec.approval.request` 必须包含 `systemRunPlan`（规范的 `argv`/`cwd`/`rawCommand`/会话元数据）。缺少 `systemRunPlan` 的请求会被拒绝。 - 审批后，转发的 `node.invoke system.run` 调用会复用该规范 `systemRunPlan`，作为权威的命令/cwd/会话上下文。 -- 如果调用方在准备和最终已审批的 `system.run` 转发之间更改了 `command`、`rawCommand`、`cwd`、`agentId` 或 - `sessionKey`，Gateway 网关会拒绝运行，而不是信任被更改的载荷。 +- 如果调用方在准备阶段和最终已审批的 `system.run` 转发之间修改了 `command`、`rawCommand`、`cwd`、`agentId` 或 + `sessionKey`，Gateway 网关会拒绝本次运行，而不是信任被修改的载荷。 ## 智能体投递回退 - `agent` 请求可以包含 `deliver=true` 来请求出站投递。 -- `bestEffortDeliver=false` 保持严格行为：无法解析或仅内部的投递目标会返回 `INVALID_REQUEST`。 -- `bestEffortDeliver=true` 允许在无法解析外部可投递路由时回退到仅会话执行（例如内部/webchat 会话或含糊的多渠道配置）。 +- `bestEffortDeliver=false` 保持严格行为：无法解析或仅限内部的投递目标会返回 `INVALID_REQUEST`。 +- `bestEffortDeliver=true` 允许在无法解析外部可投递路由时回退到仅会话执行（例如内部/webchat 会话，或存在歧义的多渠道配置）。 ## 版本控制 - `PROTOCOL_VERSION` 位于 `src/gateway/protocol/schema/protocol-schemas.ts`。 -- 客户端发送 `minProtocol` + `maxProtocol`；服务器会拒绝不匹配项。 -- Schema + 模型由 TypeBox 定义生成： +- 客户端发送 `minProtocol` + `maxProtocol`；服务器会拒绝不匹配的情况。 +- schema + 模型从 TypeBox 定义生成： - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` @@ -496,79 +510,80 @@ Gateway 网关将这些视为**声明**，并强制执行服务端允许列表 | 常量 | 默认值 | 来源 | | ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | | `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | -| 请求超时（每个 RPC） | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | -| 预认证 / 连接质询超时 | `10_000` ms | `src/gateway/handshake-timeouts.ts`（限制为 `250`–`10_000`） | -| 初始重连退避 | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | -| 最大重连退避 | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | -| 设备令牌关闭后的快速重试限制 | `250` ms | `src/gateway/client.ts` | -| `terminate()` 前的强制停止宽限期 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | +| 请求超时（每个 RPC） | `30_000` ms | `src/gateway/client.ts`（`requestTimeoutMs`） | +| 预认证 / 连接挑战超时 | `15_000` ms | `src/gateway/handshake-timeouts.ts`（钳制 `250`–`15_000`） | +| 初始重连退避 | `1_000` ms | `src/gateway/client.ts`（`backoffMs`） | +| 最大重连退避 | `30_000` ms | `src/gateway/client.ts`（`scheduleReconnect`） | +| 设备令牌关闭后的快速重试钳制 | `250` ms | `src/gateway/client.ts` | +| `terminate()` 前的强制停止宽限 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | | `stopAndWait()` 默认超时 | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | | 默认 tick 间隔（`hello-ok` 前） | `30_000` ms | `src/gateway/client.ts` | -| Tick 超时关闭 | 静默超过 `tickIntervalMs * 2` 时使用代码 `4000` | `src/gateway/client.ts` | +| Tick 超时关闭 | 当静默超过 `tickIntervalMs * 2` 时使用代码 `4000` | `src/gateway/client.ts` | | `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024`（25 MB） | `src/gateway/server-constants.ts` | -服务器会在 `hello-ok` 中公告有效的 `policy.tickIntervalMs`、`policy.maxPayload` -和 `policy.maxBufferedBytes`；客户端应遵循这些值，而不是握手前默认值。 +服务器会在 `hello-ok` 中公布有效的 `policy.tickIntervalMs`、`policy.maxPayload` +和 `policy.maxBufferedBytes`；客户端应遵循这些值，而不是握手前的默认值。 ## 认证 - 共享密钥 Gateway 网关认证使用 `connect.params.auth.token` 或 `connect.params.auth.password`，具体取决于配置的认证模式。 -- 带身份的模式，例如 Tailscale Serve - (`gateway.auth.allowTailscale: true`) 或非 loopback 的 - `gateway.auth.mode: "trusted-proxy"`，会从请求头而不是 `connect.params.auth.*` 满足连接认证检查。 -- 私有入口 `gateway.auth.mode: "none"` 会完全跳过共享密钥连接认证；不要在公开/不可信入口上暴露该模式。 -- 配对后，Gateway 网关会签发一个限定为连接角色 + 作用域的**设备令牌**。它会在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化以供后续连接使用。 -- 客户端应在任何成功连接后持久化主 `hello-ok.auth.deviceToken`。 -- 使用该**已存储**设备令牌重连时，也应复用为该令牌存储的已批准作用域集合。这会保留已授予的读取/探测/Status 访问权限，并避免将重连静默压缩到更窄的隐式仅管理员作用域。 -- 客户端连接认证组装（`src/gateway/client.ts` 中的 `selectConnectAuth`）： - - `auth.password` 是正交的，设置后始终转发。 - - `auth.token` 按优先级填充：先使用显式共享令牌，然后是显式 `deviceToken`，再然后是已存储的按设备令牌（按 `deviceId` + `role` 建键）。 - - 仅当上述都没有解析出 `auth.token` 时才发送 `auth.bootstrapToken`。共享令牌或任何已解析设备令牌都会抑制它。 - - 在一次性 `AUTH_TOKEN_MISMATCH` 重试中自动提升已存储设备令牌，仅限于**可信端点**： - loopback，或带固定 `tlsFingerprint` 的 `wss://`。未固定的公共 `wss://` 不符合条件。 -- 额外的 `hello-ok.auth.deviceTokens` 条目是引导交接令牌。仅当连接在可信传输上使用引导认证时才持久化它们，例如 `wss://` 或 loopback/local 配对。 -- 如果客户端提供了**显式** `deviceToken` 或显式 `scopes`，调用方请求的作用域集合仍然是权威来源；仅当客户端复用已存储的按设备令牌时，才复用缓存作用域。 +- 带身份的模式（例如 Tailscale Serve + （`gateway.auth.allowTailscale: true`）或非 loopback 的 + `gateway.auth.mode: "trusted-proxy"`）会从请求头满足连接认证检查，而不是使用 `connect.params.auth.*`。 +- 私有入口 `gateway.auth.mode: "none"` 会完全跳过共享密钥连接认证；不要在公共/不受信任入口上暴露该模式。 +- 配对后，Gateway 网关会签发一个作用域限定为连接角色 + 作用域的**设备令牌**。它在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化以供将来连接使用。 +- 客户端应在任何成功连接后持久化主要的 `hello-ok.auth.deviceToken`。 +- 使用该**已存储**设备令牌重新连接时，还应复用该令牌已存储的已批准作用域集。这样会保留已授予的读取/探测/Status 访问权限，并避免将重连静默压缩到更窄的隐式仅管理员作用域。 +- 客户端侧连接认证组装（`src/gateway/client.ts` 中的 `selectConnectAuth`）： + - `auth.password` 是正交的，设置时始终会被转发。 + - `auth.token` 按优先级填充：先使用显式共享令牌，然后是显式 `deviceToken`，再然后是已存储的每设备令牌（按 `deviceId` + `role` 键控）。 + - 只有当上述任何项都没有解析出 `auth.token` 时，才会发送 `auth.bootstrapToken`。共享令牌或任何已解析的设备令牌都会抑制它。 + - 在一次性 `AUTH_TOKEN_MISMATCH` 重试中自动提升已存储设备令牌，仅限**受信任端点**： + loopback，或带有已固定 `tlsFingerprint` 的 `wss://`。没有固定的公共 `wss://` + 不符合条件。 +- 额外的 `hello-ok.auth.deviceTokens` 条目是 bootstrap 交接令牌。仅当连接在受信任传输（例如 `wss://` 或 loopback/local 配对）上使用 bootstrap 认证时才持久化它们。 +- 如果客户端提供**显式** `deviceToken` 或显式 `scopes`，该调用方请求的作用域集仍为权威；仅当客户端复用已存储的每设备令牌时，才会复用缓存的作用域。 - 设备令牌可以通过 `device.token.rotate` 和 `device.token.revoke` 轮换/撤销（需要 `operator.pairing` 作用域）。 -- `device.token.rotate` 返回轮换元数据。只有在同设备调用且该调用已用该设备令牌认证时，它才会回显替换用 bearer 令牌，因此仅令牌客户端可以在重连前持久化替换令牌。共享/管理员轮换不会回显 bearer 令牌。 -- 令牌签发、轮换和撤销保持限定在该设备配对条目中记录的已批准角色集合内；令牌变更无法扩展到配对审批从未授予的设备角色，也无法以其为目标。 -- 对于已配对设备令牌会话，除非调用方还拥有 `operator.admin`，否则设备管理是自限定的：非管理员调用方只能移除/撤销/轮换其**自己的**设备条目。 -- `device.token.rotate` 和 `device.token.revoke` 还会用调用方当前会话作用域检查目标操作员令牌作用域集合。非管理员调用方不能轮换或撤销比自己已持有范围更广的操作员令牌。 +- `device.token.rotate` 返回轮换元数据。它仅针对已经使用该设备令牌完成认证的同设备调用回显替换 bearer 令牌，因此仅令牌客户端可以在重连前持久化其替换令牌。共享/管理员轮换不会回显 bearer 令牌。 +- 令牌签发、轮换和撤销始终受限于该设备配对条目中记录的已批准角色集；令牌变更无法扩展或指向配对审批从未授予的设备角色。 +- 对于配对设备令牌会话，除非调用方还拥有 `operator.admin`，设备管理都是自作用域的：非管理员调用方只能移除/撤销/轮换其**自己的**设备条目。 +- `device.token.rotate` 和 `device.token.revoke` 还会检查目标操作员令牌作用域集是否匹配调用方当前会话作用域。非管理员调用方无法轮换或撤销比其当前持有范围更宽的操作员令牌。 - 认证失败包含 `error.details.code` 以及恢复提示： - `error.details.canRetryWithDeviceToken`（布尔值） - `error.details.recommendedNextStep`（`retry_with_device_token`、`update_auth_configuration`、`update_auth_credentials`、`wait_then_retry`、`review_auth_configuration`） -- `AUTH_TOKEN_MISMATCH` 的客户端行为： - - 可信客户端可以尝试一次有界重试，使用缓存的按设备令牌。 - - 如果该重试失败，客户端应停止自动重连循环，并呈现操作员操作指引。 +- 客户端对 `AUTH_TOKEN_MISMATCH` 的行为： + - 受信任客户端可以尝试使用缓存的每设备令牌进行一次有界重试。 + - 如果该重试失败，客户端应停止自动重连循环，并显示需要操作员处理的指导。 ## 设备身份 + 配对 - 节点应包含从密钥对指纹派生的稳定设备身份（`device.id`）。 - Gateway 网关按设备 + 角色签发令牌。 -- 新设备 ID 需要配对审批，除非启用了本地自动审批。 +- 除非启用了本地自动审批，否则新设备 ID 需要配对审批。 - 配对自动审批以直接 local loopback 连接为中心。 -- OpenClaw 还提供一条狭窄的后端/容器本地自连接路径，用于可信共享密钥辅助流程。 -- 同主机 tailnet 或 LAN 连接仍会按远程连接处理以进行配对，并且需要审批。 -- WS 客户端通常在 `connect` 期间包含 `device` 身份（操作员 + - 节点）。唯一不带设备的操作员例外是显式信任路径： - - `gateway.controlUi.allowInsecureAuth=true`，用于仅限 localhost 的不安全 HTTP 兼容性。 +- OpenClaw 还为受信任的共享密钥辅助流程提供一个很窄的后端/容器本地自连接路径。 +- 同主机 tailnet 或 LAN 连接仍会被视为远程配对，并且需要审批。 +- WS 客户端通常会在 `connect` 期间包含 `device` 身份（操作员 + + 节点）。唯一无设备操作员例外是显式信任路径： + - `gateway.controlUi.allowInsecureAuth=true`，用于仅 localhost 的不安全 HTTP 兼容性。 - 成功的 `gateway.auth.mode: "trusted-proxy"` 操作员 Control UI 认证。 - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（应急开关，严重降低安全性）。 - - 使用共享 Gateway 网关令牌/密码认证的 direct-loopback `gateway-client` 后端 RPC。 -- 所有连接都必须签署服务器提供的 `connect.challenge` nonce。 + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（紧急破窗，严重降低安全性）。 + - 使用共享 Gateway 网关令牌/密码认证的直连 loopback `gateway-client` 后端 RPC。 +- 所有连接都必须签名服务器提供的 `connect.challenge` nonce。 ### 设备认证迁移诊断 -对于仍使用质询前签名行为的旧版客户端，`connect` 现在会在 `error.details.code` 下返回 +对于仍使用挑战前签名行为的旧版客户端，`connect` 现在会在 `error.details.code` 下返回 `DEVICE_AUTH_*` 详情代码，并带有稳定的 `error.details.reason`。 常见迁移失败： | 消息 | details.code | details.reason | 含义 | | --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | 客户端省略了 `device.nonce`（或发送了空值）。 | -| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | 客户端使用过期/错误的 nonce 签名。 | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | 客户端省略了 `device.nonce`（或发送为空）。 | +| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | 客户端使用过期/错误 nonce 进行签名。 | | `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 签名载荷与 v2 载荷不匹配。 | | `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 已签名时间戳超出允许偏差。 | | `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` 与公钥指纹不匹配。 | @@ -577,24 +592,24 @@ Gateway 网关将这些视为**声明**，并强制执行服务端允许列表 迁移目标： - 始终等待 `connect.challenge`。 -- 签署包含服务器 nonce 的 v2 载荷。 -- 在 `connect.params.device.nonce` 中发送相同 nonce。 -- 首选签名载荷是 `v3`，它除了设备/客户端/角色/作用域/令牌/nonce 字段外，还绑定了 `platform` 和 `deviceFamily`。 -- 为了兼容性，旧版 `v2` 签名仍会被接受，但已配对设备元数据固定仍会控制重连时的命令策略。 +- 签名包含服务器 nonce 的 v2 载荷。 +- 在 `connect.params.device.nonce` 中发送相同的 nonce。 +- 首选签名载荷为 `v3`，除设备/客户端/角色/作用域/令牌/nonce 字段外，还绑定 `platform` 和 `deviceFamily`。 +- 旧版 `v2` 签名仍会出于兼容性被接受，但配对设备元数据固定仍会在重连时控制命令策略。 ## TLS + 固定 -- TLS 支持用于 WS 连接。 -- 客户端可以选择固定 Gateway 网关证书指纹（见 `gateway.tls` - 配置以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。 +- WS 连接支持 TLS。 +- 客户端可以选择固定 Gateway 网关证书指纹（参见 `gateway.tls` + 配置，以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。 ## 作用域 -此协议暴露**完整 Gateway 网关 API**（Status、渠道、Models、聊天、 +此协议公开**完整 Gateway 网关 API**（Status、渠道、模型、聊天、 智能体、会话、节点、审批等）。确切表面由 `src/gateway/protocol/schema.ts` 中的 TypeBox schema 定义。 -## 相关内容 +## 相关 - [桥接协议](/zh-CN/gateway/bridge-protocol) - [Gateway 网关运行手册](/zh-CN/gateway) diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index 925da1d0b..2408c8668 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -1,84 +1,84 @@ --- read_when: - 你看到 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 警告 - - 你会看到 OPENCLAW_EXTENSION_API_DEPRECATED 警告 - - 你在 OpenClaw 2026.4.25 之前使用了 api.registerEmbeddedExtensionFactory + - 你看到了 OPENCLAW_EXTENSION_API_DEPRECATED 警告 + - 你在 OpenClaw 2026.4.25 之前使用过 api.registerEmbeddedExtensionFactory - 你正在将插件更新到现代插件架构 - 你维护一个外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-28T11:59:31Z" + generated_at: "2026-04-28T20:08:50Z" model: gpt-5.5 provider: openai - source_hash: 3f102c3632f6b51fcc007a53a3e3c4d47dbbee8e86a8d49b758cff38925fbbf1 + source_hash: efaf0f397e7b06a67fd324f1710ac62529dd2c039d483b381a8df5495716cd51 source_path: plugins/sdk-migration.md workflow: 16 --- -OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，使用聚焦且有文档说明的导入。如果你的插件是在新架构之前构建的，本指南可帮助你迁移。 +OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，使用聚焦且有文档说明的导入。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 ## 正在变化的内容 -旧插件系统提供了两个完全开放的接口，让插件可以从单个入口点导入所需的任何内容： +旧插件系统提供了两个开放范围很大的表面，允许插件从单一入口点导入所需的任何内容： -- **`openclaw/plugin-sdk/compat`** — 单个导入，重新导出了数十个辅助函数。它的引入是为了在新插件架构构建期间，让较早的基于钩子的插件继续工作。 -- **`openclaw/plugin-sdk/infra-runtime`** — 宽泛的运行时辅助 barrel，混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助函数、文件辅助函数、审批类型和不相关的实用工具。 -- **`openclaw/plugin-sdk/config-runtime`** — 宽泛的配置兼容性 barrel，在迁移窗口期间仍携带已弃用的直接加载/写入辅助函数。 -- **`openclaw/extension-api`** — 一个桥接层，让插件能够直接访问宿主侧辅助函数，例如嵌入式 agent runner。 -- **`api.registerEmbeddedExtensionFactory(...)`** — 已移除的仅 Pi 内置扩展钩子，可观察嵌入式 runner 事件，例如 `tool_result`。 +- **`openclaw/plugin-sdk/compat`** — 一个会重新导出数十个辅助函数的单一导入。它的引入是为了在新的插件架构构建期间，保持较旧的基于钩子的插件可用。 +- **`openclaw/plugin-sdk/infra-runtime`** — 一个宽泛的运行时辅助 barrel，混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助函数、文件辅助函数、审批类型和无关工具。 +- **`openclaw/plugin-sdk/config-runtime`** — 一个宽泛的配置兼容性 barrel，在迁移窗口期间仍携带已弃用的直接加载/写入辅助函数。 +- **`openclaw/extension-api`** — 一个桥接层，让插件可以直接访问主机侧辅助函数，例如嵌入式智能体 runner。 +- **`api.registerEmbeddedExtensionFactory(...)`** — 一个已移除的仅限 Pi 的内置扩展钩子，可观察嵌入式 runner 事件，例如 `tool_result`。 -这些宽泛的导入接口现在已**弃用**。它们在运行时仍然可用，但新插件不得使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。仅 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。 +这些宽泛的导入表面现在已**弃用**。它们在运行时仍可工作，但新插件不得使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已移除；请改用工具结果中间件。 -OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已有文档说明的插件行为。破坏性合约变更必须先经过兼容性适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、manifest 字段、设置 API、钩子和运行时注册行为。 +OpenClaw 不会在引入替代方案的同一变更中移除或重新解释有文档说明的插件行为。破坏性契约变更必须先经过兼容性适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、manifest 字段、设置 API、钩子和运行时注册行为。 - 向后兼容层将在未来的主版本中移除。届时仍从这些接口导入的插件将会中断。仅 Pi 的嵌入式扩展工厂注册现在已经不再加载。 + 向后兼容层将在未来的主要版本中移除。届时仍从这些表面导入的插件将会中断。仅限 Pi 的嵌入式扩展工厂注册现在已经不再加载。 -## 为什么会有这个变更 +## 为什么做出此变更 -旧方式带来了问题： +旧方法带来了问题： - **启动缓慢** — 导入一个辅助函数会加载数十个无关模块 -- **循环依赖** — 宽泛的重新导出很容易造成导入循环 -- **API 接口不清晰** — 无法判断哪些导出是稳定的，哪些是内部的 +- **循环依赖** — 宽泛的重新导出很容易造成导入环 +- **API 表面不清晰** — 无法判断哪些导出是稳定的，哪些是内部的 -现代插件 SDK 修复了这一点：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有明确用途和有文档说明的合约。 +现代插件 SDK 修复了这一点：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含模块，具有明确用途和有文档说明的契约。 -面向内置渠道的旧版 provider 便利 seam 也已移除。带渠道品牌的辅助 seam 是私有单仓库快捷方式，不是稳定的插件合约。请改用窄范围的通用 SDK 子路径。在内置插件工作区内，将 provider 自有的辅助函数保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 +内置渠道的旧提供商便利接缝也已移除。带渠道品牌的辅助接缝是私有 mono-repo 快捷方式，不是稳定的插件契约。请改用狭窄的通用 SDK 子路径。在内置插件工作区内，将提供商拥有的辅助函数保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 -当前的内置 provider 示例： +当前内置提供商示例： -- Anthropic 将 Claude 专用流式辅助函数保留在自己的 `api.ts` / `contract-api.ts` seam 中 -- OpenAI 将 provider builder、默认模型辅助函数和实时 provider builder 保留在自己的 `api.ts` 中 -- OpenRouter 将 provider builder 以及 onboarding/config 辅助函数保留在自己的 `api.ts` 中 +- Anthropic 将 Claude 专用流辅助函数保留在自己的 `api.ts` / `contract-api.ts` 接缝中 +- OpenAI 将提供商 builder、默认模型辅助函数和实时提供商 builder 保留在自己的 `api.ts` 中 +- OpenRouter 将提供商 builder 和新手引导/配置辅助函数保留在自己的 `api.ts` 中 ## 兼容性策略 对于外部插件，兼容性工作遵循以下顺序： -1. 添加新合约 -2. 保留通过兼容性适配器连接的旧行为 -3. 发出诊断或警告，指出旧路径和替代项 -4. 在测试中覆盖两条路径 +1. 添加新契约 +2. 通过兼容性适配器保持旧行为连通 +3. 发出诊断或警告，指明旧路径和替代方案 +4. 在测试中覆盖两个路径 5. 记录弃用和迁移路径 -6. 仅在已公告的迁移窗口之后移除，通常是在主版本中 +6. 仅在已公告的迁移窗口之后移除，通常是在主要版本中 -维护者可以使用 `pnpm plugins:boundary-report` 审计当前迁移队列。使用 `pnpm plugins:boundary-report:summary` 查看紧凑计数，使用 `--owner ` 查看单个插件或兼容性所有者，并在 CI gate 需要因到期兼容性记录、跨所有者保留 SDK 导入或未使用的保留 SDK 子路径而失败时使用 `pnpm plugins:boundary-report:ci`。该报告会按移除日期对已弃用的兼容性记录分组，统计本地代码/文档引用，暴露跨所有者保留 SDK 导入，并汇总私有 memory-host SDK bridge，让兼容性清理保持明确，而不是依赖临时搜索。保留 SDK 子路径必须有跟踪的所有者使用情况；未使用的保留辅助导出应从公开 SDK 中移除。 +维护者可以使用 `pnpm plugins:boundary-report` 审计当前迁移队列。使用 `pnpm plugins:boundary-report:summary` 获取紧凑计数，使用 `--owner ` 查看单个插件或兼容性 owner，并在 CI gate 应因到期兼容性记录、跨 owner 保留 SDK 导入或未使用的保留 SDK 子路径而失败时使用 `pnpm plugins:boundary-report:ci`。该报告会按移除日期对已弃用的兼容性记录分组，统计本地代码/文档引用，显示跨 owner 保留 SDK 导入，并汇总私有 memory-host SDK 桥接，使兼容性清理保持显式，而不是依赖临时搜索。保留 SDK 子路径必须有已跟踪的 owner 使用；未使用的保留辅助导出应从公共 SDK 中移除。 -如果某个 manifest 字段仍被接受，插件作者可以继续使用它，直到文档和诊断另有说明。新代码应优先使用有文档说明的替代项，但现有插件不应在普通次版本发布期间中断。 +如果某个 manifest 字段仍被接受，插件作者可以继续使用它，直到文档和诊断另有说明。新代码应优先使用有文档说明的替代方案，但现有插件不应在普通次要版本发布期间中断。 ## 如何迁移 - + 内置插件应停止直接调用 `api.runtime.config.loadConfig()` 和 - `api.runtime.config.writeConfigFile(...)`。优先使用已传入活动调用路径的配置。需要当前进程快照的长生命周期处理程序可以使用 `api.runtime.config.current()`。长生命周期 agent 工具应在 `execute` 内使用工具上下文的 `ctx.getRuntimeConfig()`，这样在配置写入前创建的工具仍能看到刷新的运行时配置。 + `api.runtime.config.writeConfigFile(...)`。优先使用已传入当前活动调用路径的配置。需要当前进程快照的长生命周期处理器可以使用 `api.runtime.config.current()`。长生命周期智能体工具应在 `execute` 内使用工具上下文的 `ctx.getRuntimeConfig()`，这样在配置写入前创建的工具仍能看到刷新的运行时配置。 - 配置写入必须经过事务性辅助函数，并选择写入后策略： + 配置写入必须通过事务辅助函数，并选择写入后策略： ```typescript await api.runtime.config.mutateConfigFile({ @@ -89,13 +89,16 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 }); ``` - 当调用方知道该变更需要干净重启 Gateway 网关时，使用 `afterWrite: { mode: "restart", reason: "..." }`；仅当调用方拥有后续处理并有意抑制 reload planner 时，才使用 `afterWrite: { mode: "none", reason: "..." }`。Mutation 结果包含类型化的 `followUp` 摘要，用于测试和日志；Gateway 网关仍负责应用或安排重启。`loadConfig` 和 `writeConfigFile` 在迁移窗口期间仍作为面向外部插件的已弃用兼容性辅助函数保留，并会以 `runtime-config-load-write` 兼容性代码警告一次。内置插件和仓库运行时代码受 `pnpm check:deprecated-internal-config-api` 和 `pnpm check:no-runtime-action-load-config` 中的扫描器护栏保护：新的生产插件用法会直接失败，直接配置写入会失败，Gateway 网关 server 方法必须使用请求运行时快照，运行时渠道 send/action/client 辅助函数必须从其边界接收配置，并且长生命周期运行时模块允许的环境 `loadConfig()` 调用数量为零。 + 当调用方知道变更需要一次干净的 Gateway 网关重启时，使用 `afterWrite: { mode: "restart", reason: "..." }`；只有当调用方拥有后续处理并有意抑制 reload planner 时，才使用 `afterWrite: { mode: "none", reason: "..." }`。变更结果包含一个带类型的 `followUp` 摘要，用于测试和日志；Gateway 网关仍负责应用或调度重启。`loadConfig` 和 `writeConfigFile` 在迁移窗口期间仍作为外部插件的已弃用兼容性辅助函数保留，并会以 `runtime-config-load-write` 兼容性代码警告一次。内置插件和仓库运行时代码受到 + `pnpm check:deprecated-internal-config-api` 和 + `pnpm check:no-runtime-action-load-config` 中扫描器 guardrail 的保护：新的生产插件用法会直接失败，直接配置写入会失败，Gateway 网关服务器方法必须使用请求运行时快照，运行时渠道发送/action/client 辅助函数必须从其边界接收配置，并且长生命周期运行时模块允许的环境级 `loadConfig()` 调用数为零。 - 新插件代码也应避免导入宽泛的 `openclaw/plugin-sdk/config-runtime` 兼容性 barrel。请使用与任务匹配的窄范围 SDK 子路径： + 新插件代码还应避免导入宽泛的 + `openclaw/plugin-sdk/config-runtime` 兼容性 barrel。请使用与任务匹配的狭窄 SDK 子路径： | 需求 | 导入 | | --- | --- | - | Config 类型，例如 `OpenClawConfig` | `openclaw/plugin-sdk/config-types` | + | `OpenClawConfig` 等配置类型 | `openclaw/plugin-sdk/config-types` | | 已加载配置断言和插件入口配置查找 | `openclaw/plugin-sdk/plugin-config-runtime` | | 当前运行时快照读取 | `openclaw/plugin-sdk/runtime-config-snapshot` | | 配置写入 | `openclaw/plugin-sdk/config-mutation` | @@ -105,13 +108,13 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 | Secret 输入解析 | `openclaw/plugin-sdk/secret-input-runtime` | | 模型/会话覆盖 | `openclaw/plugin-sdk/model-session-runtime` | - 内置插件及其测试受扫描器保护，不得使用宽泛的 barrel，因此导入和 mock 会保持在它们需要的行为本地。宽泛的 barrel 仍为外部兼容性存在，但新代码不应依赖它。 + 内置插件及其测试会通过扫描器防护避免使用宽泛 barrel，确保导入和 mock 保持在所需行为的本地范围内。宽泛 barrel 仍为外部兼容性存在，但新代码不应依赖它。 - - 内置插件必须将仅 Pi 的 - `api.registerEmbeddedExtensionFactory(...)` 工具结果处理程序替换为运行时中立的中间件。 + + 内置插件必须将仅限 Pi 的 + `api.registerEmbeddedExtensionFactory(...)` 工具结果处理器替换为运行时中立的中间件。 ```typescript // Pi and Codex runtime dynamic tools @@ -132,29 +135,31 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 } ``` - 外部插件无法注册工具结果中间件，因为它可以在模型看到高信任工具输出之前重写该输出。 + 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前重写它。 - + 支持审批的渠道插件现在通过 `approvalCapability.nativeRuntime` 加共享运行时上下文注册表来暴露原生审批行为。 关键变更： - - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 `approvalCapability.nativeRuntime` - - 将审批专用 auth/delivery 从旧版 `plugin.auth` / `plugin.approvals` 连接迁移到 `approvalCapability` - - `ChannelPlugin.approvals` 已从公开渠道插件合约中移除；将 delivery/native/render 字段迁移到 `approvalCapability` - - `plugin.auth` 仅保留用于渠道登录/登出流程；核心不再读取其中的审批 auth 钩子 - - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有运行时对象，例如 clients、tokens 或 Bolt apps - - 不要从原生审批处理程序发送插件自有的 reroute 通知；core 现在根据实际投递结果拥有 routed-elsewhere 通知 - - 将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 会被拒绝。 + - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 + `approvalCapability.nativeRuntime` + - 将审批专用 auth/delivery 从旧版 `plugin.auth` / + `plugin.approvals` 接线迁移到 `approvalCapability` + - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；将 delivery/native/render 字段迁移到 `approvalCapability` + - `plugin.auth` 仅保留用于渠道登录/登出流程；core 不再读取其中的审批 auth 钩子 + - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道拥有的运行时对象，例如 client、token 或 Bolt app + - 不要从原生审批处理器发送插件拥有的 reroute 通知；core 现在根据实际投递结果拥有 routed-elsewhere 通知 + - 将 `channelRuntime` 传入 `createChannelManager(...)` 时，提供真实的 `createPluginRuntime().channel` 表面。部分 stub 会被拒绝。 请参阅 `/plugins/sdk-channel-plugins` 了解当前审批能力布局。 - - 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，未解析的 Windows `.cmd`/`.bat` wrapper 现在会失败关闭，除非你显式传入 `allowShellFallback: true`。 + + 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，未解析的 Windows `.cmd`/`.bat` wrapper 现在会 fail closed，除非你显式传入 `allowShellFallback: true`。 ```typescript // Before @@ -169,12 +174,12 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 }); ``` - 如果你的调用方并非有意依赖 shell fallback，请不要设置 `allowShellFallback`，而是处理抛出的错误。 + 如果你的调用方并非有意依赖 shell fallback，不要设置 `allowShellFallback`，而应处理抛出的错误。 - - 在你的插件中搜索来自任一已弃用接口的导入： + + 在你的插件中搜索来自任一已弃用表面的导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -185,8 +190,8 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 - - 旧接口中的每个导出都映射到特定的现代导入路径： + + 旧表面中的每个导出都映射到一个特定的现代导入路径： ```typescript // Before (deprecated backwards-compatibility layer) @@ -202,7 +207,7 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - 对于宿主侧辅助函数，请使用注入的插件运行时，而不是直接导入： + 对于主机侧辅助函数，请使用注入的插件运行时，而不是直接导入： ```typescript // Before (deprecated extension-api bridge) @@ -213,7 +218,7 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - 同样的模式也适用于其他旧版桥接 helper： + 同一模式也适用于其他旧版桥接辅助函数： | 旧导入 | 现代等价项 | | --- | --- | @@ -223,47 +228,42 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | 会话存储 helper | `api.runtime.agent.session.*` | + | 会话存储辅助函数 | `api.runtime.agent.session.*` | - `openclaw/plugin-sdk/infra-runtime` 仍然为外部兼容性保留， - 但新代码应导入它实际需要的聚焦 helper 表面： + `openclaw/plugin-sdk/infra-runtime` 仍为外部兼容性而存在，但新代码应导入它实际需要的聚焦辅助接口： | 需求 | 导入 | | --- | --- | - | 系统事件队列 helper | `openclaw/plugin-sdk/system-event-runtime` | - | 心跳事件和可见性 helper | `openclaw/plugin-sdk/heartbeat-runtime` | + | 系统事件队列辅助函数 | `openclaw/plugin-sdk/system-event-runtime` | + | 心跳事件和可见性辅助函数 | `openclaw/plugin-sdk/heartbeat-runtime` | | 待处理投递队列排空 | `openclaw/plugin-sdk/delivery-queue-runtime` | | 渠道活动遥测 | `openclaw/plugin-sdk/channel-activity-runtime` | - | 内存去重缓存 | `openclaw/plugin-sdk/dedupe-runtime` | - | 安全的本地文件/媒体路径 helper | `openclaw/plugin-sdk/file-access-runtime` | + | 内存中去重缓存 | `openclaw/plugin-sdk/dedupe-runtime` | + | 安全的本地文件/媒体路径辅助函数 | `openclaw/plugin-sdk/file-access-runtime` | | 感知调度器的 fetch | `openclaw/plugin-sdk/runtime-fetch` | - | 代理和受保护的 fetch helper | `openclaw/plugin-sdk/fetch-runtime` | + | 代理和受保护的 fetch 辅助函数 | `openclaw/plugin-sdk/fetch-runtime` | | SSRF 调度器策略类型 | `openclaw/plugin-sdk/ssrf-dispatcher` | - | 审批请求/解决类型 | `openclaw/plugin-sdk/approval-runtime` | - | 审批回复载荷和命令 helper | `openclaw/plugin-sdk/approval-reply-runtime` | - | 错误格式化 helper | `openclaw/plugin-sdk/error-runtime` | + | 审批请求/解析类型 | `openclaw/plugin-sdk/approval-runtime` | + | 审批回复载荷和命令辅助函数 | `openclaw/plugin-sdk/approval-reply-runtime` | + | 错误格式化辅助函数 | `openclaw/plugin-sdk/error-runtime` | | 传输就绪等待 | `openclaw/plugin-sdk/transport-ready-runtime` | - | 安全 token helper | `openclaw/plugin-sdk/secure-random-runtime` | + | 安全令牌辅助函数 | `openclaw/plugin-sdk/secure-random-runtime` | | 有界异步任务并发 | `openclaw/plugin-sdk/concurrency-runtime` | | 数值强制转换 | `openclaw/plugin-sdk/number-runtime` | | 进程本地异步锁 | `openclaw/plugin-sdk/async-lock-runtime` | | 文件锁 | `openclaw/plugin-sdk/file-lock` | - 内置插件通过扫描器防止使用 `infra-runtime`，因此仓库代码 - 不能退回到宽泛的 barrel。 + 内置插件会通过扫描器防止使用 `infra-runtime`，因此仓库代码无法退回到宽泛的 barrel。 - - 新的渠道路由代码应使用 `openclaw/plugin-sdk/channel-route`。 - 旧的 route-key 和 comparable-target 名称在迁移窗口期间仍作为兼容性 - 别名保留，但新插件应使用能直接描述行为的 route - 名称： + + 新的渠道路由代码应使用 `openclaw/plugin-sdk/channel-route`。较旧的 route-key 和 comparable-target 名称在迁移窗口期间仍作为兼容性别名保留，但新插件应使用直接描述行为的路由名称： - | 旧 helper | 现代 helper | + | 旧辅助函数 | 现代辅助函数 | | --- | --- | | `channelRouteIdentityKey(...)` | `channelRouteDedupeKey(...)` | | `channelRouteKey(...)` | `channelRouteCompactKey(...)` | @@ -273,10 +273,7 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 | `comparableChannelTargetsMatch(...)` | `channelRouteTargetsMatchExact(...)` | | `comparableChannelTargetsShareRoute(...)` | `channelRouteTargetsShareConversation(...)` | - 现代 route helper 会在原生审批、回复抑制、入站去重、 - cron 投递和会话路由中一致地规范化 `{ channel, to, accountId, threadId }`。 - 如果你的插件拥有自定义目标语法，请使用 `resolveChannelRouteTargetWithParser(...)` - 将该解析器适配到同一个 route target 契约中。 + 现代路由辅助函数会在原生审批、回复抑制、入站去重、cron 投递和会话路由中一致地规范化 `{ channel, to, accountId, threadId }`。如果你的插件拥有自定义目标语法，请使用 `resolveChannelRouteTargetWithParser(...)` 将该解析器适配到相同的路由目标契约。 @@ -290,206 +287,208 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 ## 导入路径参考 - + | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | 规范插件入口助手 | `definePluginEntry` | - | `plugin-sdk/core` | 用于渠道入口定义/构建器的旧版汇总再导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | 根配置架构导出 | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | 单一提供商入口助手 | `defineSingleProviderPluginEntry` | + | `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` | + | `plugin-sdk/core` | 旧版统括式重新导出，用于渠道入口定义/构建器 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | 单提供商入口辅助工具 | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导助手 | 允许列表提示词、设置 Status 构建器 | - | `plugin-sdk/setup-runtime` | 设置时运行时助手 | 导入安全的设置补丁适配器、查找说明助手、`promptResolvedAllowFrom`、`splitSetupEntries`、委托式设置代理 | - | `plugin-sdk/setup-adapter-runtime` | 设置适配器助手 | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | 设置工具助手 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账号助手 | 账号列表/配置/操作门控助手 | - | `plugin-sdk/account-id` | 账号 ID 助手 | `DEFAULT_ACCOUNT_ID`、账号 ID 规范化 | - | `plugin-sdk/account-resolution` | 账号查找助手 | 账号查找 + 默认回退助手 | - | `plugin-sdk/account-helpers` | 窄范围账号助手 | 账号列表/账号操作助手 | - | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、`createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | + | `plugin-sdk/setup` | 共享设置向导辅助工具 | 允许列表提示、设置状态构建器 | + | `plugin-sdk/setup-runtime` | 设置期间运行时辅助工具 | 导入安全的设置补丁适配器、查找备注辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托式设置代理 | + | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | 多账号辅助工具 | 账号列表/配置/操作门控辅助工具 | + | `plugin-sdk/account-id` | 账号 ID 辅助工具 | `DEFAULT_ACCOUNT_ID`、账号 ID 规范化 | + | `plugin-sdk/account-resolution` | 账号查找辅助工具 | 账号查找 + 默认回退辅助工具 | + | `plugin-sdk/account-helpers` | 窄范围账号辅助工具 | 账号列表/账号操作辅助工具 | + | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | 回复前缀、正在输入和源交付接线 | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` | + | `plugin-sdk/channel-reply-pipeline` | 回复前缀、输入中状态和来源投递接线 | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` | | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | 配置架构构建器 | 共享渠道配置架构原语和仅通用构建器 | - | `plugin-sdk/bundled-channel-config-schema` | 内置配置架构 | 仅限 OpenClaw 维护的内置插件；新插件必须定义插件本地架构 | - | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置架构 | 仅兼容性别名；对维护中的内置插件使用 `plugin-sdk/bundled-channel-config-schema` | - | `plugin-sdk/telegram-command-config` | Telegram 命令配置助手 | 命令名规范化、描述裁剪、重复/冲突校验 | + | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 仅共享渠道配置 schema 原语和通用构建器 | + | `plugin-sdk/bundled-channel-config-schema` | 内置配置 schema | 仅限 OpenClaw 维护的内置插件；新插件必须定义插件本地 schema | + | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置 schema | 仅兼容性别名；对维护中的内置插件使用 `plugin-sdk/bundled-channel-config-schema` | + | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名称规范化、描述裁剪、重复/冲突验证 | | `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | 账号 Status 和草稿流生命周期助手 | `createAccountStatusSink`、草稿预览终结助手 | - | `plugin-sdk/inbound-envelope` | 入站信封助手 | 共享路由 + 信封构建器助手 | - | `plugin-sdk/inbound-reply-dispatch` | 入站回复助手 | 共享记录并分发助手 | - | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配助手 | - | `plugin-sdk/outbound-media` | 出站媒体助手 | 共享出站媒体加载 | - | `plugin-sdk/outbound-send-deps` | 出站发送依赖助手 | 无需导入完整出站运行时的轻量级 `resolveOutboundSendDep` 查找 | - | `plugin-sdk/outbound-runtime` | 出站运行时助手 | 出站交付、身份/发送委托、会话、格式化和载荷规划助手 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定助手 | 线程绑定生命周期和适配器助手 | - | `plugin-sdk/agent-media-payload` | 旧版媒体载荷助手 | 用于旧版字段布局的智能体媒体载荷构建器 | - | `plugin-sdk/channel-runtime` | 已弃用的兼容性垫片 | 仅旧版渠道运行时工具 | + | `plugin-sdk/channel-lifecycle` | 账号状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览终结辅助工具 | + | `plugin-sdk/inbound-envelope` | 入站信封辅助工具 | 共享路由 + 信封构建器辅助工具 | + | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并分发辅助工具 | + | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 | + | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 | + | `plugin-sdk/outbound-send-deps` | 出站发送依赖辅助工具 | 无需导入完整出站运行时的轻量级 `resolveOutboundSendDep` 查找 | + | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、身份/发送委托、会话、格式化和载荷规划辅助工具 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | + | `plugin-sdk/agent-media-payload` | 旧版媒体载荷辅助工具 | 适用于旧版字段布局的 Agent 媒体载荷构建器 | + | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时实用工具 | | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 | | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | 宽范围运行时助手 | 运行时/日志/备份/插件安装助手 | - | `plugin-sdk/runtime-env` | 窄范围运行时环境助手 | 日志记录器/运行时环境、超时、重试和退避助手 | - | `plugin-sdk/plugin-runtime` | 共享插件运行时助手 | 插件命令/钩子/http/交互式助手 | - | `plugin-sdk/hook-runtime` | 钩子流水线助手 | 共享 webhook/内部钩子流水线助手 | - | `plugin-sdk/lazy-runtime` | 懒加载运行时助手 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程助手 | 共享 exec 助手 | - | `plugin-sdk/cli-runtime` | CLI 运行时助手 | 命令格式化、等待、版本助手 | - | `plugin-sdk/gateway-runtime` | Gateway 网关助手 | Gateway 网关客户端和渠道 Status 补丁助手 | - | `plugin-sdk/config-runtime` | 已弃用的配置兼容性垫片 | 优先使用 `config-types`、`plugin-config-runtime`、`runtime-config-snapshot` 和 `config-mutation` | - | `plugin-sdk/telegram-command-config` | Telegram 命令助手 | 当内置 Telegram 合同表面不可用时提供回退稳定的 Telegram 命令校验助手 | - | `plugin-sdk/approval-runtime` | 审批提示助手 | Exec/插件审批载荷、审批能力/配置文件助手、原生审批路由/运行时助手，以及结构化审批显示路径格式化 | - | `plugin-sdk/approval-auth-runtime` | 审批认证助手 | 审批人解析、同一聊天操作认证 | - | `plugin-sdk/approval-client-runtime` | 审批客户端助手 | 原生 exec 审批配置文件/过滤器助手 | - | `plugin-sdk/approval-delivery-runtime` | 审批交付助手 | 原生审批能力/交付适配器 | - | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关助手 | 共享审批 Gateway 网关解析助手 | - | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器助手 | 面向热渠道入口点的轻量级原生审批适配器加载助手 | - | `plugin-sdk/approval-handler-runtime` | 审批处理器助手 | 更宽范围的审批处理器运行时助手；当更窄的适配器/Gateway 网关衔接足够时优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 审批目标助手 | 原生审批目标/账号绑定助手 | - | `plugin-sdk/approval-reply-runtime` | 审批回复助手 | Exec/插件审批回复载荷助手 | - | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文助手 | 通用渠道运行时上下文注册/get/watch 助手 | - | `plugin-sdk/security-runtime` | 安全助手 | 共享信任、私信门控、外部内容和密钥收集助手 | - | `plugin-sdk/ssrf-policy` | SSRF 策略助手 | 主机允许列表和私有网络策略助手 | - | `plugin-sdk/ssrf-runtime` | SSRF 运行时助手 | 固定调度器、受保护的 fetch、SSRF 策略助手 | - | `plugin-sdk/system-event-runtime` | 系统事件助手 | `enqueueSystemEvent`, `peekSystemEventEntries` | - | `plugin-sdk/heartbeat-runtime` | 心跳助手 | 心跳事件和可见性助手 | - | `plugin-sdk/delivery-queue-runtime` | 交付队列助手 | `drainPendingDeliveries` | - | `plugin-sdk/channel-activity-runtime` | 渠道活动助手 | `recordChannelActivity` | - | `plugin-sdk/dedupe-runtime` | 去重助手 | 内存去重缓存 | - | `plugin-sdk/file-access-runtime` | 文件访问助手 | 安全本地文件/媒体路径助手 | - | `plugin-sdk/transport-ready-runtime` | 传输就绪助手 | `waitForTransportReady` | - | `plugin-sdk/collection-runtime` | 有界缓存助手 | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | 诊断门控助手 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | 错误格式化助手 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图助手 | - | `plugin-sdk/fetch-runtime` | 封装的 fetch/代理助手 | `resolveFetch`、代理助手 | - | `plugin-sdk/host-runtime` | 主机规范化助手 | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | 重试助手 | `RetryConfig`, `retryAsync`、策略运行器 | + | `plugin-sdk/runtime` | 广范围运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | 日志记录器/运行时环境、超时、重试和退避辅助工具 | + | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/钩子/http/交互式辅助工具 | + | `plugin-sdk/hook-runtime` | 钩子流水线辅助工具 | 共享 webhook/内部钩子流水线辅助工具 | + | `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 | + | `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 | + | `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 | + | `plugin-sdk/config-runtime` | 已弃用的配置兼容性 shim | 优先使用 `config-types`, `plugin-config-runtime`, `runtime-config-snapshot` 和 `config-mutation` | + | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 合同表面不可用时，提供回退稳定的 Telegram 命令验证辅助工具 | + | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批载荷、审批能力/配置文件辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示路径格式化 | + | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批者解析、同一聊天操作认证 | + | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件/过滤器辅助工具 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力/投递适配器 | + | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 | + | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 面向热门渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 审批处理程序辅助工具 | 更广范围的审批处理程序运行时辅助工具；当更窄的适配器/Gateway 网关衔接已足够时，优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/账号绑定辅助工具 | + | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复载荷辅助工具 | + | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文注册/获取/监听辅助工具 | + | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和密钥收集辅助工具 | + | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机允许列表和专用网络策略辅助工具 | + | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | 固定 dispatcher、受保护 fetch、SSRF 策略辅助工具 | + | `plugin-sdk/system-event-runtime` | 系统事件辅助工具 | `enqueueSystemEvent`, `peekSystemEventEntries` | + | `plugin-sdk/heartbeat-runtime` | 心跳辅助工具 | 心跳事件和可见性辅助工具 | + | `plugin-sdk/delivery-queue-runtime` | 投递队列辅助工具 | `drainPendingDeliveries` | + | `plugin-sdk/channel-activity-runtime` | 渠道活动辅助工具 | `recordChannelActivity` | + | `plugin-sdk/dedupe-runtime` | 去重辅助工具 | 内存中去重缓存 | + | `plugin-sdk/file-access-runtime` | 文件访问辅助工具 | 安全本地文件/媒体路径辅助工具 | + | `plugin-sdk/transport-ready-runtime` | 传输就绪辅助工具 | `waitForTransportReady` | + | `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 | + | `plugin-sdk/fetch-runtime` | 包装 fetch/代理辅助工具 | `resolveFetch`、代理辅助工具 | + | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 | | `plugin-sdk/allow-from` | 允许列表格式化 | `formatAllowFromLowercase` | | `plugin-sdk/allowlist-resolution` | 允许列表输入映射 | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | 命令门控和命令表面助手 | `resolveControlCommandGate`、发送方授权助手、命令注册表助手（包括动态参数菜单格式化） | - | `plugin-sdk/command-status` | 命令 Status/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入助手 | - | `plugin-sdk/webhook-ingress` | Webhook 请求助手 | Webhook 目标工具 | - | `plugin-sdk/webhook-request-guards` | Webhook 正文保护助手 | 请求正文读取/限制助手 | + | `plugin-sdk/command-auth` | 命令门控和命令表面辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具，包括动态参数菜单格式化 | + | `plugin-sdk/command-status` | 命令状态/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助工具 | + | `plugin-sdk/webhook-ingress` | Webhook 请求辅助工具 | Webhook 目标实用工具 | + | `plugin-sdk/webhook-request-guards` | Webhook 正文保护辅助工具 | 请求正文读取/限制辅助工具 | | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发助手 | 终结、提供商分发和会话标签助手 | - | `plugin-sdk/reply-history` | 回复历史助手 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | 终结、提供商分发和对话标签辅助工具 | + | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 回复分块助手 | 文本/Markdown 分块助手 | - | `plugin-sdk/session-store-runtime` | 会话存储助手 | 存储路径 + updated-at 助手 | - | `plugin-sdk/state-paths` | 状态路径助手 | 状态和 OAuth 目录助手 | - | `plugin-sdk/routing` | 路由/会话键助手 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化助手 | - | `plugin-sdk/status-helpers` | 渠道 Status 助手 | 渠道/账号 Status 摘要构建器、运行时状态默认值、问题元数据助手 | - | `plugin-sdk/target-resolver-runtime` | 目标解析器助手 | 共享目标解析器助手 | - | `plugin-sdk/string-normalization-runtime` | 字符串规范化助手 | Slug/字符串规范化助手 | - | `plugin-sdk/request-url` | 请求 URL 助手 | 从类请求输入中提取字符串 URL | - | `plugin-sdk/run-command` | 定时命令助手 | 带规范化 stdout/stderr 的定时命令运行器 | + | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本/markdown 分块辅助工具 | + | `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + 更新时间辅助工具 | + | `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 | + | `plugin-sdk/routing` | 路由/会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 | + | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道/账号状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | + | `plugin-sdk/target-resolver-runtime` | 目标解析器辅助工具 | 共享目标解析器辅助工具 | + | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug/字符串规范化辅助工具 | + | `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类似请求的输入中提取字符串 URL | + | `plugin-sdk/run-command` | 定时命令辅助工具 | 带规范化 stdout/stderr 的定时命令运行器 | | `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 | | `plugin-sdk/tool-payload` | 工具载荷提取 | 从工具结果对象中提取规范化载荷 | | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 | - | `plugin-sdk/temp-path` | 临时路径助手 | 共享临时下载路径助手 | - | `plugin-sdk/logging-core` | 日志助手 | 子系统日志记录器和脱敏助手 | - | `plugin-sdk/markdown-table-runtime` | Markdown 表格助手 | Markdown 表格模式助手 | + | `plugin-sdk/temp-path` | 临时路径辅助函数 | 共享临时下载路径辅助函数 | + | `plugin-sdk/logging-core` | 日志记录辅助函数 | 子系统日志记录器和修订辅助函数 | + | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助函数 | Markdown 表格模式辅助函数 | | `plugin-sdk/reply-payload` | 消息回复类型 | 回复载荷类型 | - | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置助手 | 自托管提供商设备发现/配置助手 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容的自托管提供商设置助手 | 相同的自托管提供商设备发现/配置助手 | - | `plugin-sdk/provider-auth-runtime` | 提供商运行时凭证助手 | 运行时 API 密钥解析助手 | - | `plugin-sdk/provider-auth-api-key` | 提供商 API 密钥设置助手 | API 密钥新手引导/配置文件写入助手 | - | `plugin-sdk/provider-auth-result` | 提供商凭证结果助手 | 标准 OAuth 凭证结果构建器 | - | `plugin-sdk/provider-auth-login` | 提供商交互式登录助手 | 共享交互式登录助手 | - | `plugin-sdk/provider-selection-runtime` | 提供商选择助手 | 已配置或自动提供商选择与原始提供商配置合并 | - | `plugin-sdk/provider-env-vars` | 提供商环境变量助手 | 提供商凭证环境变量查找助手 | - | `plugin-sdk/provider-model-shared` | 共享提供商模型/重放助手 | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享重放策略构建器、提供商端点助手和模型 ID 规范化助手 | - | `plugin-sdk/provider-catalog-shared` | 共享提供商目录助手 | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`buildManifestModelProviderConfig`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置助手 | - | `plugin-sdk/provider-http` | 提供商 HTTP 助手 | 通用提供商 HTTP/端点能力助手，包括音频转录 multipart 表单助手 | - | `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 助手 | Web-fetch 提供商注册/缓存助手 | - | `plugin-sdk/provider-web-search-config-contract` | 提供商 Web 搜索配置助手 | 面向不需要插件启用接线的提供商的窄 Web 搜索配置/凭据助手 | - | `plugin-sdk/provider-web-search-contract` | 提供商 Web 搜索契约助手 | 窄 Web 搜索配置/凭据契约助手，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及限定作用域的凭据 setter/getter | - | `plugin-sdk/provider-web-search` | 提供商 Web 搜索助手 | Web 搜索提供商注册/缓存/运行时助手 | - | `plugin-sdk/provider-tools` | 提供商工具/schema 兼容助手 | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容助手，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | 提供商用量助手 | `fetchClaudeUsage`、`fetchGeminiUsage`、`fetchGithubCopilotUsage` 和其他提供商用量助手 | - | `plugin-sdk/provider-stream` | 提供商流包装器助手 | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器助手 | - | `plugin-sdk/provider-transport-runtime` | 提供商传输助手 | 原生提供商传输助手，例如带保护的 fetch、传输消息转换和可写传输事件流 | + | `plugin-sdk/provider-setup` | 精选本地/自托管提供商设置辅助函数 | 自托管提供商发现/配置辅助函数 | + | `plugin-sdk/self-hosted-provider-setup` | 专注于 OpenAI 兼容自托管提供商的设置辅助函数 | 相同的自托管提供商发现/配置辅助函数 | + | `plugin-sdk/provider-auth-runtime` | 提供商运行时认证辅助函数 | 运行时 API 密钥解析辅助函数 | + | `plugin-sdk/provider-auth-api-key` | 提供商 API 密钥设置辅助函数 | API 密钥新手引导/配置文件写入辅助函数 | + | `plugin-sdk/provider-auth-result` | 提供商认证结果辅助函数 | 标准 OAuth 认证结果构建器 | + | `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助函数 | 共享交互式登录辅助函数 | + | `plugin-sdk/provider-selection-runtime` | 提供商选择辅助函数 | 已配置或自动提供商选择以及原始提供商配置合并 | + | `plugin-sdk/provider-env-vars` | 提供商环境变量辅助函数 | 提供商认证环境变量查找辅助函数 | + | `plugin-sdk/provider-model-shared` | 共享提供商模型/重放辅助函数 | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享重放策略构建器、提供商端点辅助函数以及模型 ID 规范化辅助函数 | + | `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助函数 | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`buildManifestModelProviderConfig`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置辅助函数 | + | `plugin-sdk/provider-http` | 提供商 HTTP 辅助函数 | 通用提供商 HTTP/端点能力辅助函数，包括音频转录 multipart 表单辅助函数 | + | `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助函数 | Web-fetch 提供商注册/缓存辅助函数 | + | `plugin-sdk/provider-web-search-config-contract` | 提供商 Web 搜索配置辅助函数 | 面向不需要插件启用接线的提供商的窄 Web 搜索配置/凭证辅助函数 | + | `plugin-sdk/provider-web-search-contract` | 提供商 Web 搜索契约辅助函数 | 窄 Web 搜索配置/凭证契约辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化凭证设置器/获取器 | + | `plugin-sdk/provider-web-search` | 提供商 Web 搜索辅助函数 | Web 搜索提供商注册/缓存/运行时辅助函数 | + | `plugin-sdk/provider-tools` | 提供商工具/架构兼容辅助函数 | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini 架构清理 + 诊断，以及 xAI 兼容辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | 提供商用量辅助函数 | `fetchClaudeUsage`、`fetchGeminiUsage`、`fetchGithubCopilotUsage` 以及其他提供商用量辅助函数 | + | `plugin-sdk/provider-stream` | 提供商流包装器辅助函数 | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助函数 | + | `plugin-sdk/provider-transport-runtime` | 提供商传输辅助函数 | 原生提供商传输辅助函数，例如受保护的 fetch、传输消息转换以及可写传输事件流 | | `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | 共享媒体助手 | 媒体获取/转换/存储助手，以及媒体载荷构建器 | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成助手 | 图像/视频/音乐生成的共享故障转移助手、候选选择和缺失模型消息 | - | `plugin-sdk/media-understanding` | 媒体理解助手 | 媒体理解提供商类型，以及面向提供商的图像/音频助手导出 | - | `plugin-sdk/text-runtime` | 共享文本助手 | 面向 Assistant 的可见文本剥离、Markdown 渲染/分块/表格助手、脱敏助手、指令标签助手、安全文本实用工具，以及相关文本/日志助手 | - | `plugin-sdk/text-chunking` | 文本分块助手 | 出站文本分块助手 | - | `plugin-sdk/speech` | 语音助手 | 语音提供商类型，以及面向提供商的指令、注册表、验证助手和 OpenAI 兼容的 TTS 构建器 | + | `plugin-sdk/media-runtime` | 共享媒体辅助函数 | 媒体获取/转换/存储辅助函数以及媒体载荷构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助函数 | 用于图像/视频/音乐生成的共享故障转移辅助函数、候选选择以及缺失模型消息 | + | `plugin-sdk/media-understanding` | 媒体理解辅助函数 | 媒体理解提供商类型以及面向提供商的图像/音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享文本辅助函数 | 助手可见文本剥离、Markdown 渲染/分块/表格辅助函数、修订辅助函数、指令标签辅助函数、安全文本实用工具以及相关文本/日志记录辅助函数 | + | `plugin-sdk/text-chunking` | 文本分块辅助函数 | 出站文本分块辅助函数 | + | `plugin-sdk/speech` | 语音辅助函数 | 语音提供商类型以及面向提供商的指令、注册表、验证辅助函数和 OpenAI 兼容 TTS 构建器 | | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、指令、规范化 | - | `plugin-sdk/realtime-transcription` | 实时转录助手 | 提供商类型、注册表助手和共享 WebSocket 会话助手 | - | `plugin-sdk/realtime-voice` | 实时语音助手 | 提供商类型、注册表/解析助手和桥接会话助手 | - | `plugin-sdk/image-generation` | 图像生成助手 | 图像生成提供商类型，以及图像资产/data URL 助手和 OpenAI 兼容的图像提供商构建器 | - | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、凭证和注册表助手 | - | `plugin-sdk/music-generation` | 音乐生成助手 | 音乐生成提供商/请求/结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移助手、提供商查找和模型引用解析 | - | `plugin-sdk/video-generation` | 视频生成助手 | 视频生成提供商/请求/结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移助手、提供商查找和模型引用解析 | - | `plugin-sdk/interactive-runtime` | 交互式回复助手 | 交互式回复载荷规范化/归约 | - | `plugin-sdk/channel-config-primitives` | 渠道配置基元 | 窄渠道配置 schema 基元 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入助手 | 渠道配置写入授权助手 | - | `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导导出 | - | `plugin-sdk/channel-status` | 渠道 Status 助手 | 共享渠道 Status 快照/摘要助手 | - | `plugin-sdk/allowlist-config-edit` | 允许列表配置助手 | 允许列表配置编辑/读取助手 | - | `plugin-sdk/group-access` | 群组访问助手 | 共享群组访问决策助手 | - | `plugin-sdk/direct-dm` | 直接私信助手 | 共享直接私信凭证/保护助手 | - | `plugin-sdk/extension-shared` | 共享扩展助手 | 被动渠道/Status 和环境代理助手基元 | - | `plugin-sdk/webhook-targets` | Webhook 目标助手 | Webhook 目标注册表和路由安装助手 | - | `plugin-sdk/webhook-path` | Webhook 路径助手 | Webhook 路径规范化助手 | - | `plugin-sdk/web-media` | 共享 Web 媒体助手 | 远程/本地媒体加载助手 | - | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用方重新导出的 `zod` | - | `plugin-sdk/memory-core` | 内置 memory-core 助手 | 内存管理器/配置/文件/CLI 助手表面 | + | `plugin-sdk/realtime-transcription` | 实时转录辅助函数 | 提供商类型、注册表辅助函数以及共享 WebSocket 会话辅助函数 | + | `plugin-sdk/realtime-voice` | 实时语音辅助函数 | 提供商类型、注册表/解析辅助函数以及桥接会话辅助函数 | + | `plugin-sdk/image-generation` | 图像生成辅助函数 | 图像生成提供商类型以及图像资产/数据 URL 辅助函数和 OpenAI 兼容图像提供商构建器 | + | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助函数 | + | `plugin-sdk/music-generation` | 音乐生成辅助函数 | 音乐生成提供商/请求/结果类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助函数、提供商查找以及模型引用解析 | + | `plugin-sdk/video-generation` | 视频生成辅助函数 | 视频生成提供商/请求/结果类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助函数、提供商查找以及模型引用解析 | + | `plugin-sdk/interactive-runtime` | 交互式回复辅助函数 | 交互式回复载荷规范化/缩减 | + | `plugin-sdk/channel-config-primitives` | 渠道配置基元 | 窄渠道配置架构基元 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入辅助函数 | 渠道配置写入授权辅助函数 | + | `plugin-sdk/channel-plugin-common` | 共享渠道前奏 | 共享渠道插件前奏导出 | + | `plugin-sdk/channel-status` | 渠道 Status 辅助函数 | 共享渠道 Status 快照/摘要辅助函数 | + | `plugin-sdk/allowlist-config-edit` | 允许列表配置辅助函数 | 允许列表配置编辑/读取辅助函数 | + | `plugin-sdk/group-access` | 群组访问辅助函数 | 共享群组访问决策辅助函数 | + | `plugin-sdk/direct-dm` | 直接私信辅助函数 | 共享直接私信认证/防护辅助函数 | + | `plugin-sdk/extension-shared` | 共享扩展辅助函数 | 被动渠道/Status 和环境代理辅助基元 | + | `plugin-sdk/webhook-targets` | Webhook 目标辅助函数 | Webhook 目标注册表和路由安装辅助函数 | + | `plugin-sdk/webhook-path` | Webhook 路径辅助函数 | Webhook 路径规范化辅助函数 | + | `plugin-sdk/web-media` | 共享 Web 媒体辅助函数 | 远程/本地媒体加载辅助函数 | + | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 消费者重新导出的 `zod` | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助函数 | 内存管理器/配置/文件/CLI 辅助表面 | | `plugin-sdk/memory-core-engine-runtime` | 内存引擎运行时门面 | 内存索引/搜索运行时门面 | - | `plugin-sdk/memory-core-host-engine-foundation` | 内存主机 foundation 引擎 | 内存主机 foundation 引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | 内存主机嵌入引擎 | 内存嵌入契约、注册表访问、本地提供商，以及通用批量/远程助手；具体远程提供商位于其归属插件中 | + | `plugin-sdk/memory-core-host-engine-foundation` | 内存主机基础引擎 | 内存主机基础引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | 内存主机嵌入引擎 | 内存嵌入契约、注册表访问、本地提供商以及通用批处理/远程辅助函数；具体远程提供商位于其所属插件中 | | `plugin-sdk/memory-core-host-engine-qmd` | 内存主机 QMD 引擎 | 内存主机 QMD 引擎导出 | | `plugin-sdk/memory-core-host-engine-storage` | 内存主机存储引擎 | 内存主机存储引擎导出 | - | `plugin-sdk/memory-core-host-multimodal` | 内存主机多模态助手 | 内存主机多模态助手 | - | `plugin-sdk/memory-core-host-query` | 内存主机查询助手 | 内存主机查询助手 | - | `plugin-sdk/memory-core-host-secret` | 内存主机密钥助手 | 内存主机密钥助手 | - | `plugin-sdk/memory-core-host-events` | 内存主机事件日志助手 | 内存主机事件日志助手 | - | `plugin-sdk/memory-core-host-status` | 内存主机 Status 助手 | 内存主机 Status 助手 | - | `plugin-sdk/memory-core-host-runtime-cli` | 内存主机 CLI 运行时 | 内存主机 CLI 运行时助手 | - | `plugin-sdk/memory-core-host-runtime-core` | 内存主机核心运行时 | 内存主机核心运行时助手 | - | `plugin-sdk/memory-core-host-runtime-files` | 内存主机文件/运行时助手 | 内存主机文件/运行时助手 | - | `plugin-sdk/memory-host-core` | 内存主机核心运行时别名 | 内存主机核心运行时助手的供应商中立别名 | - | `plugin-sdk/memory-host-events` | 内存主机事件日志别名 | 内存主机事件日志助手的供应商中立别名 | - | `plugin-sdk/memory-host-files` | 内存主机文件/运行时别名 | 内存主机文件/运行时助手的供应商中立别名 | - | `plugin-sdk/memory-host-markdown` | 托管 Markdown 助手 | 面向内存相邻插件的共享托管 Markdown 助手 | - | `plugin-sdk/memory-host-search` | 活跃内存搜索门面 | 懒加载的活跃内存搜索管理器运行时门面 | - | `plugin-sdk/memory-host-status` | 内存主机 Status 别名 | 内存主机 Status 助手的供应商中立别名 | - | `plugin-sdk/testing` | 测试实用工具 | 旧版宽兼容性桶；优先使用聚焦的测试子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/channel-target-testing`、`plugin-sdk/test-env` 和 `plugin-sdk/test-fixtures` | + | `plugin-sdk/memory-core-host-multimodal` | 内存主机多模态辅助函数 | 内存主机多模态辅助函数 | + | `plugin-sdk/memory-core-host-query` | 内存主机查询辅助函数 | 内存主机查询辅助函数 | + | `plugin-sdk/memory-core-host-secret` | 内存主机密钥辅助函数 | 内存主机密钥辅助函数 | + | `plugin-sdk/memory-core-host-events` | 内存主机事件日志辅助函数 | 内存主机事件日志辅助函数 | + | `plugin-sdk/memory-core-host-status` | 内存主机 Status 辅助函数 | 内存主机 Status 辅助函数 | + | `plugin-sdk/memory-core-host-runtime-cli` | 内存主机 CLI 运行时 | 内存主机 CLI 运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-core` | 内存主机核心运行时 | 内存主机核心运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-files` | 内存主机文件/运行时辅助函数 | 内存主机文件/运行时辅助函数 | + | `plugin-sdk/memory-host-core` | 内存主机核心运行时别名 | 内存主机核心运行时辅助函数的供应商中立别名 | + | `plugin-sdk/memory-host-events` | 内存主机事件日志别名 | 内存主机事件日志辅助函数的供应商中立别名 | + | `plugin-sdk/memory-host-files` | 内存主机文件/运行时别名 | 内存主机文件/运行时辅助函数的供应商中立别名 | + | `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助函数 | 面向内存相关插件的共享托管 Markdown 辅助函数 | + | `plugin-sdk/memory-host-search` | 活跃内存搜索门面 | 延迟活跃内存搜索管理器运行时门面 | + | `plugin-sdk/memory-host-status` | 内存主机 Status 别名 | 内存主机 Status 辅助函数的供应商中立别名 | + | `plugin-sdk/testing` | 测试实用工具 | 旧版宽泛兼容 barrel；优先使用聚焦的测试子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/channel-target-testing`、`plugin-sdk/test-env` 和 `plugin-sdk/test-fixtures` | -这张表有意只列出常见迁移子集，而不是完整的 SDK -表面。200+ 个入口点的完整列表位于 +此表有意只列出常见迁移子集，而不是完整的 SDK +表面。200 多个入口点的完整列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 -保留的内置插件辅助接缝已从公开 SDK -导出映射中移除。特定所有者的辅助工具位于所属插件包内部；共享的 -主机行为应通过通用 SDK 契约迁移，例如 -`plugin-sdk/gateway-runtime`、`plugin-sdk/security-runtime` 和 -`plugin-sdk/plugin-config-runtime`。 +预留的内置插件 helper 接缝已从公共 SDK +导出映射中退役，但明确记录的兼容 facade 除外，例如为已发布的 +`@openclaw/discord@2026.3.13` 包保留的已弃用 +`plugin-sdk/discord` shim。特定所有者的 helper 位于所属的 +插件包内；共享的宿主行为应通过通用 SDK +契约迁移，例如 `plugin-sdk/gateway-runtime`、`plugin-sdk/security-runtime` +和 `plugin-sdk/plugin-config-runtime`。 -使用与任务匹配的最窄导入。如果找不到导出，请检查 -`src/plugin-sdk/` 中的源码，或询问维护者该由哪个通用契约 +使用与任务匹配的最窄导入。如果找不到导出， +请检查 `src/plugin-sdk/` 中的源代码，或询问维护者应由哪个通用契约 拥有它。 -## 当前弃用项 +## 活跃弃用项 -这些更窄的弃用项适用于插件 SDK、提供商契约、 -运行时表面和清单。每一项目前仍可使用，但会在未来的主版本中移除。 -每个条目下方都会把旧 API 映射到它的规范替代项。 +适用于插件 SDK、提供商契约、运行时表面和清单的更窄弃用项。 +每一项今天仍可使用，但会在未来的主版本中移除。每个条目下方 +都会把旧 API 映射到其规范替代项。 - **旧（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`, + **旧 (`openclaw/plugin-sdk/command-auth`)**：`buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage`。 - **新（`openclaw/plugin-sdk/command-status`）**：相同签名、相同 + **新 (`openclaw/plugin-sdk/command-status`)**：相同签名、相同 导出，只是从更窄的子路径导入。`command-auth` - 会将它们作为兼容性桩重新导出。 + 会将它们重新导出为兼容 stub。 ```typescript // Before @@ -501,7 +500,7 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 - + **旧**：来自 `openclaw/plugin-sdk/channel-inbound` 或 `openclaw/plugin-sdk/channel-mention-gating` 的 @@ -509,52 +508,53 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 `shouldDropInboundForMention(...)`。 **新**：`resolveInboundMentionDecision({ facts, policy })`，返回单个 - 决策对象，而不是两个拆分调用。 + decision 对象，而不是两次拆分调用。 - 下游渠道插件（Slack、Discord、Matrix、MS Teams）已经 - 切换完成。 + 下游渠道插件（Slack、Discord、Matrix、MS Teams）已经切换。 - - `openclaw/plugin-sdk/channel-runtime` 是面向旧版 - 渠道插件的兼容性垫片。新代码不要导入它；使用 + + `openclaw/plugin-sdk/channel-runtime` 是面向较旧 + 渠道插件的兼容 shim。新代码不要从它导入；请使用 `openclaw/plugin-sdk/channel-runtime-context` 来注册运行时 对象。 - `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` - 辅助工具与原始 “actions” 渠道导出一起弃用。请改为通过语义化 - `presentation` 表面暴露能力，也就是让渠道插件声明它们渲染什么 - （卡片、按钮、选择器），而不是它们接受哪些原始动作名称。 + `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` helper + 已随原始 “actions” 渠道导出一起弃用。请改为通过语义化 + `presentation` 表面暴露能力，即渠道插件声明它们渲染什么 + （卡片、按钮、选择器），而不是它们接受哪些原始 action 名称。 - - **旧**：来自 `openclaw/plugin-sdk/provider-web-search` 的 `tool()` - 工厂。 + + **旧**：来自 `openclaw/plugin-sdk/provider-web-search` 的 `tool()` 工厂。 **新**：直接在提供商插件上实现 `createTool(...)`。 - OpenClaw 不再需要 SDK 辅助工具来注册工具包装器。 + OpenClaw 不再需要 SDK helper 来注册工具 wrapper。 - - **旧**：`formatInboundEnvelope(...)`（以及 - `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建 - 扁平纯文本提示信封。 + + **旧**：使用 `formatInboundEnvelope(...)`（以及 + `ChannelMessageForAgent.channelEnvelope`）从入站渠道消息构建扁平明文提示 + 信封。 - **新**：`BodyForAgent` 加结构化用户上下文块。渠道插件将路由元数据 - （线程、主题、回复目标、回应）作为类型化字段附加，而不是把它们 - 拼接到提示字符串中。`formatAgentEnvelope(...)` 辅助工具仍支持 - 合成的面向助手信封，但入站纯文本信封正在退出。 + **新**：`BodyForAgent` 加结构化用户上下文块。渠道 + 插件将路由元数据（线程、主题、回复目标、反应）作为 + 类型化字段附加，而不是把它们拼接进提示字符串。 + `formatAgentEnvelope(...)` helper 仍支持用于合成 + 面向 assistant 的信封，但入站明文信封正在 + 退出。 - 受影响区域：`inbound_claim`、`message_received`，以及任何 - 对 `channelEnvelope` 文本进行后处理的自定义渠道插件。 + 受影响区域：`inbound_claim`、`message_received`，以及任何对 + `channelEnvelope` 文本进行后处理的自定义 + 渠道插件。 - 四个发现类型别名现在是目录时代类型的薄包装： + 四个发现类型别名现在只是目录时代类型的薄 wrapper： | 旧别名 | 新类型 | | ------------------------- | ------------------------- | @@ -563,33 +563,34 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 | `ProviderDiscoveryResult` | `ProviderCatalogResult` | | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - 以及旧版 `ProviderCapabilities` 静态包。提供商插件应通过 - 提供商运行时契约附加能力事实，而不是使用静态对象。 + 另外还有旧版 `ProviderCapabilities` 静态包。提供商插件 + 应通过提供商运行时契约附加能力 facts， + 而不是使用静态对象。 - + **旧**（`ProviderThinkingPolicy` 上的三个独立钩子）： `isBinaryThinking(ctx)`、`supportsXHighThinking(ctx)` 和 `resolveDefaultThinkingLevel(ctx)`。 - **新**：单个 `resolveThinkingProfile(ctx)`，返回一个 - `ProviderThinkingProfile`，其中包含规范 `id`、可选 `label` 和 - 按等级排序的级别列表。OpenClaw 会按档案等级自动降级过期的 - 已存储值。 + **新**：单个 `resolveThinkingProfile(ctx)`，它返回包含规范 `id`、 + 可选 `label` 和排序 level 列表的 + `ProviderThinkingProfile`。OpenClaw 会自动按 profile + rank 降级过时的已存储值。 - 实现一个钩子即可，不再实现三个。旧钩子在弃用窗口期间仍会继续 - 工作，但不会与档案结果组合。 + 实现一个钩子，而不是三个。旧版钩子在弃用窗口期间仍可工作， + 但不会与 profile 结果组合。 - - **旧**：实现 `resolveExternalOAuthProfiles(...)`，但没有在 + + **旧**：实现 `resolveExternalOAuthProfiles(...)`，但未在 插件清单中声明提供商。 **新**：在插件清单中声明 `contracts.externalAuthProviders` **并且**实现 `resolveExternalAuthProfiles(...)`。旧的 “auth - fallback” 路径会在运行时发出警告，并将在之后移除。 + fallback” 路径会在运行时发出警告，并会被移除。 ```json { @@ -601,35 +602,35 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 - + **旧**清单字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。 - **新**：将相同的环境变量查找镜像到清单上的 - `setup.providers[].envVars`。这会把设置/Status 环境元数据合并到 - 一个位置，并避免仅为了回答环境变量查找而启动插件运行时。 + **新**：把相同的环境变量查找镜像到清单上的 `setup.providers[].envVars`。 + 这会把设置/Status 环境元数据整合到一个 + 位置，并避免仅为响应环境变量查找而启动插件运行时。 - `providerAuthEnvVars` 会通过兼容性适配器保持支持，直到弃用窗口 - 关闭。 + 在弃用窗口关闭前，`providerAuthEnvVars` 会继续通过兼容适配器 + 受支持。 **旧**：三个独立调用： - `api.registerMemoryPromptSection(...)`, - `api.registerMemoryFlushPlan(...)`, + `api.registerMemoryPromptSection(...)`、 + `api.registerMemoryFlushPlan(...)`、 `api.registerMemoryRuntime(...)`。 - **新**：memory-state API 上的一个调用： + **新**：memory-state API 上的一次调用： `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`。 - 相同槽位，单次注册调用。增量 Memory 辅助工具 + 相同槽位，单次注册调用。增量 Memory helper （`registerMemoryPromptSupplement`、`registerMemoryCorpusSupplement`、 `registerMemoryEmbeddingProvider`）不受影响。 - - 两个仍从 `src/plugins/runtime/types.ts` 导出的旧版类型别名： + + 仍从 `src/plugins/runtime/types.ts` 导出的两个旧版类型别名： | 旧 | 新 | | ----------------------------- | ------------------------------- | @@ -637,16 +638,17 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | 运行时方法 `readSession` 已弃用，请改用 - `getSessionMessages`。签名相同；旧方法会转调到新方法。 + `getSessionMessages`。签名相同；旧方法会转调到 + 新方法。 - **旧**：`runtime.tasks.flow`（单数）返回实时任务流访问器。 + **旧**：`runtime.tasks.flow`（单数）返回实时 task-flow 访问器。 - **新**：`runtime.tasks.managedFlows` 为需要从流中创建、更新、取消 - 或运行子任务的插件保留托管 TaskFlow 变更运行时。当插件只需要 - 基于 DTO 的读取时，请使用 `runtime.tasks.flows`。 + **新**：`runtime.tasks.managedFlows` 为需要从 flow 创建、更新、取消或运行 + 子任务的插件保留托管 TaskFlow 变更 + 运行时。当插件只需要基于 DTO 的读取时，请使用 `runtime.tasks.flows`。 ```typescript // Before @@ -657,18 +659,18 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 - - 上文 “如何迁移 → 将 Pi 工具结果扩展迁移到中间件” 中已有说明。 - 为完整性在此列出：已移除的仅 Pi + + 已在上方“如何迁移 → 将 Pi 工具结果插件迁移到 + 中间件”中涵盖。为完整性在此列出：已移除的仅 Pi `api.registerEmbeddedExtensionFactory(...)` 路径由 - `api.registerAgentToolResultMiddleware(...)` 替代，并在 + `api.registerAgentToolResultMiddleware(...)` 取代，并在 `contracts.agentToolResultMiddleware` 中提供显式运行时 列表。 从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` 现在是 - `OpenClawConfig` 的单行别名。请优先使用规范名称。 + `OpenClawConfig` 的单行别名。优先使用规范名称。 ```typescript // Before @@ -681,24 +683,25 @@ OpenClaw 不会在引入替代方案的同一变更中移除或重新解释已 -扩展级别弃用项（位于 `extensions/` 下的内置渠道/提供商插件内部） -会在它们自己的 `api.ts` 和 `runtime-api.ts` barrel 中跟踪。 -它们不会影响第三方插件契约，因此不在此列出。如果你直接使用内置 -插件的本地 barrel，请在升级前阅读该 barrel 中的弃用注释。 +插件级弃用项（位于 `extensions/` 下的内置渠道/提供商插件内） +在它们自己的 `api.ts` 和 `runtime-api.ts` +barrel 中跟踪。它们不影响第三方插件契约，也不会在此列出。 +如果你直接使用内置插件的本地 barrel，请在升级前阅读该 +barrel 中的弃用注释。 ## 移除时间线 -| 时间 | 会发生什么 | +| 时间 | 会发生什么 | | ---------------------- | ----------------------------------------------------------------------- | -| **现在** | 已弃用表面会发出运行时警告 | -| **下一个主版本** | 已弃用表面将被移除；仍在使用它们的插件会失败 | +| **现在** | 已弃用表面会发出运行时警告 | +| **下一个主版本** | 已弃用表面将被移除；仍在使用它们的插件会失败 | 所有核心插件都已迁移。外部插件应在下一个主版本发布前迁移。 ## 临时抑制警告 -迁移期间设置这些环境变量： +在迁移期间设置这些环境变量： ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run @@ -714,4 +717,4 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 - [插件内部机制](/zh-CN/plugins/architecture) — 架构深入解析 -- [插件清单](/zh-CN/plugins/manifest) — 清单架构参考 +- [插件清单](/zh-CN/plugins/manifest) — 清单 schema 参考 diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index 987f64aef..b14b53e91 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -1,65 +1,67 @@ --- read_when: - 你需要知道应从哪个 SDK 子路径导入 - - 你需要一份 OpenClawPluginApi 所有注册方法的参考资料 + - 你想要一份 OpenClawPluginApi 上所有注册方法的参考。 - 你正在查找某个特定的 SDK 导出 sidebarTitle: SDK overview summary: 导入映射、注册 API 参考和 SDK 架构 title: 插件 SDK 概览 x-i18n: - generated_at: "2026-04-28T11:59:37Z" + generated_at: "2026-04-28T20:08:39Z" model: gpt-5.5 provider: openai - source_hash: 0c3bd7ae2ca2fbf351442bfd073450b72368e1ab833dbbdccfbe569db5346ce9 + source_hash: 83f554cf3653cdae5027eac2048280a9200828c5ed256d975cd745a77ba1e796 source_path: plugins/sdk-overview.md workflow: 16 --- -插件 SDK 是插件与核心之间的类型化契约。本页是关于**应导入什么**以及**可以注册什么**的参考。 +插件 SDK 是插件与核心之间的类型化契约。本页是关于**要导入什么**以及**可以注册什么**的参考。 -想找操作指南？从 [构建插件](/zh-CN/plugins/building-plugins) 开始；渠道插件请使用 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)，提供商插件请使用 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)，工具或生命周期钩子插件请使用 [插件钩子](/zh-CN/plugins/hooks)。 +想找操作指南？从[构建插件](/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` 保留给更广泛的总括表面以及 `buildChannelConfigSchema` 等共享辅助工具。 +每个子路径都是一个小型、自包含的模块。这样可以保持启动快速，并防止循环依赖问题。对于渠道特定的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 留给更广泛的总括表面以及共享辅助工具，例如 `buildChannelConfigSchema`。 -对于渠道配置，请通过 `openclaw.plugin.json#channelConfigs` 发布渠道拥有的 JSON Schema。`plugin-sdk/channel-config-schema` 子路径用于共享 schema 基元和通用构建器。OpenClaw 的内置插件使用 `plugin-sdk/bundled-channel-config-schema` 来保留内置渠道 schema。已弃用的兼容性导出保留在 `plugin-sdk/channel-config-schema-legacy`；这两个内置 schema 子路径都不是新插件应遵循的模式。 +对于渠道配置，请通过 `openclaw.plugin.json#channelConfigs` 发布由渠道拥有的 JSON Schema。`plugin-sdk/channel-config-schema` 子路径用于共享 schema 原语和通用构建器。OpenClaw 的内置插件使用 `plugin-sdk/bundled-channel-config-schema` 来保留内置渠道 schema。已弃用的兼容性导出仍保留在 `plugin-sdk/channel-config-schema-legacy`；这两个内置 schema 子路径都不是新插件应采用的模式。 - 不要导入带有提供商或渠道品牌的便利接缝（例如 + 不要导入带有提供商或渠道品牌的便捷接缝（例如 `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。 - 内置插件会在自己的 `api.ts` / + 内置插件会在其自身的 `api.ts` / `runtime-api.ts` barrel 中组合通用 SDK 子路径；核心消费者应使用这些插件本地 - barrel，或在需求确实跨渠道时添加一个狭窄的通用 SDK 契约。 + barrel，或在确实存在跨渠道需求时添加一个窄的通用 SDK 契约。 -当少量内置插件辅助接缝有可追踪的所有者使用时，它们仍会出现在生成的导出映射中。它们仅用于内置插件维护，不推荐作为新第三方插件的导入路径。 +当一小组内置插件辅助接缝存在已跟踪的所有者使用时，它们仍会出现在生成的导出映射中。它们仅用于内置插件维护，不推荐作为新的第三方插件导入路径。 + +`openclaw/plugin-sdk/discord` 也作为已发布的 `@openclaw/discord@2026.3.13` 包的已弃用兼容性门面保留。不要将该导入路径复制到新插件中；请改用通用渠道 SDK 子路径。 ## 子路径参考 -插件 SDK 以一组按领域分组的狭窄子路径暴露（插件入口、渠道、提供商、凭证、运行时、能力、记忆，以及保留的内置插件辅助工具）。完整目录（已分组并带链接）请参见 [插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。 +插件 SDK 以一组按领域分组的窄子路径公开（插件入口、渠道、提供商、认证、运行时、能力、内存，以及保留的内置插件辅助工具）。完整目录按组列出并带有链接，请参阅[插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。 生成的 200+ 个子路径列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 ## 注册 API -`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，其中包含这些方法： +`register(api)` 回调接收一个 `OpenClawPluginApi` 对象，其中包含这些方法： ### 能力注册 -| 方法 | 它注册的内容 | +| 方法 | 注册内容 | | ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | 文本推理（LLM） | -| `api.registerAgentHarness(...)` | 实验性低层智能体执行器 | +| `api.registerProvider(...)` | 文本推理 (LLM) | +| `api.registerAgentHarness(...)` | 实验性低级智能体执行器 | | `api.registerCliBackend(...)` | 本地 CLI 推理后端 | | `api.registerChannel(...)` | 消息渠道 | | `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | @@ -74,76 +76,76 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ### 工具和命令 -| 方法 | 它注册的内容 | +| 方法 | 注册内容 | | ------------------------------- | --------------------------------------------- | | `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） | | `api.registerCommand(def)` | 自定义命令（绕过 LLM） | -当智能体需要一个简短的、由命令拥有的路由提示时，插件命令可以设置 `agentPromptGuidance`。请让该文本仅涉及命令本身；不要向核心提示词构建器添加提供商或插件特定策略。 +当智能体需要一条简短的、由命令拥有的路由提示时，插件命令可以设置 `agentPromptGuidance`。该文本应只说明命令本身；不要向核心提示构建器添加特定于提供商或插件的策略。 ### 基础设施 -| 方法 | 它注册的内容 | -| ---------------------------------------------- | ------------------------------------ | -| `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.registerAgentToolResultMiddleware(...)` | 运行时工具结果中间件 | -| `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.registerAgentToolResultMiddleware(...)` | 运行时工具结果中间件 | +| `api.registerMemoryPromptSupplement(builder)` | 增量的内存相邻提示部分 | +| `api.registerMemoryCorpusSupplement(adapter)` | 增量的内存搜索/读取语料库 | ### 工作流插件的宿主钩子 -宿主钩子是面向需要参与宿主生命周期的插件的 SDK 接缝，而不仅仅是添加提供商、渠道或工具。它们是通用契约；Plan Mode 可以使用它们，审批工作流、工作区策略门禁、后台监控器、设置向导和 UI 配套插件也可以使用。 +宿主钩子是 SDK 接缝，供需要参与宿主生命周期的插件使用，而不只是添加提供商、渠道或工具。它们是通用契约；Plan Mode 可以使用它们，审批工作流、工作区策略闸门、后台监视器、设置向导和 UI 配套插件也可以使用它们。 | 方法 | 它拥有的契约 | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -| `api.registerSessionExtension(...)` | 插件拥有的、JSON 兼容的会话状态，通过 Gateway 网关会话投射 | -| `api.enqueueNextTurnInjection(...)` | 持久且恰好一次的上下文，注入到某个会话的下一次智能体轮次中 | -| `api.registerTrustedToolPolicy(...)` | 内置/可信的前置插件工具策略，可阻止或重写工具参数 | -| `api.registerToolMetadata(...)` | 工具目录显示元数据，不改变工具实现 | +| `api.registerSessionExtension(...)` | 插件拥有的、JSON 兼容的会话状态，通过 Gateway 网关会话投射 | +| `api.enqueueNextTurnInjection(...)` | 持久的恰好一次上下文，注入某个会话的下一次智能体轮次 | +| `api.registerTrustedToolPolicy(...)` | 内置/受信任的插件前工具策略，可阻止或重写工具参数 | +| `api.registerToolMetadata(...)` | 工具目录显示元数据，不更改工具实现 | | `api.registerCommand(...)` | 作用域限定的插件命令；命令结果可以设置 `continueAgent: true` | | `api.registerControlUiDescriptor(...)` | 面向会话、工具、运行或设置表面的 Control UI 贡献描述符 | -| `api.registerRuntimeLifecycle(...)` | 在重置/删除/重载路径上清理插件拥有的运行时资源的回调 | -| `api.registerAgentEventSubscription(...)` | 用于工作流状态和监控器的已净化事件订阅 | -| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | 每次运行的插件暂存状态，会在终止运行生命周期时清除 | +| `api.registerRuntimeLifecycle(...)` | 在 reset/delete/reload 路径上清理插件拥有的运行时资源的回调 | +| `api.registerAgentEventSubscription(...)` | 面向工作流状态和监视器的已清理事件订阅 | +| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | 每次运行的插件暂存状态，在终止运行生命周期时清除 | | `api.registerSessionSchedulerJob(...)` | 插件拥有的会话调度器作业记录，具备确定性清理 | 这些契约有意拆分权限： - 外部插件可以拥有会话扩展、UI 描述符、命令、工具元数据、下一轮注入和普通钩子。 -- 可信工具策略在普通 `before_tool_call` 钩子之前运行，并且仅限内置插件，因为它们参与宿主安全策略。 +- 受信任工具策略会在普通 `before_tool_call` 钩子之前运行，并且仅限内置插件，因为它们参与宿主安全策略。 - 保留命令所有权仅限内置插件。外部插件应使用自己的命令名称或别名。 -- `allowPromptInjection=false` 会禁用会修改提示词的钩子，包括 `agent_turn_prepare`、`before_prompt_build`、`heartbeat_prompt_contribution`、旧版 `before_agent_start` 中的提示词字段，以及 `enqueueNextTurnInjection`。 +- `allowPromptInjection=false` 会禁用会改变提示的钩子，包括 `agent_turn_prepare`、`before_prompt_build`、`heartbeat_prompt_contribution`、旧版 `before_agent_start` 中的提示字段，以及 `enqueueNextTurnInjection`。 非 Plan 消费者示例： -| 插件原型 | 使用的钩子 | +| 插件原型 | 使用的钩子 | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | 审批工作流 | 会话扩展、命令延续、下一轮注入、UI 描述符 | -| 预算/工作区策略门禁 | 可信工具策略、工具元数据、会话投射 | -| 后台生命周期监控器 | 运行时生命周期清理、智能体事件订阅、会话调度器所有权/清理、心跳提示词贡献、UI 描述符 | -| 设置或新手引导向导 | 会话扩展、作用域限定命令、Control UI 描述符 | +| 预算/工作区策略闸门 | 受信任工具策略、工具元数据、会话投射 | +| 后台生命周期监视器 | 运行时生命周期清理、智能体事件订阅、会话调度器所有权/清理、心跳提示贡献、UI 描述符 | +| 设置或新手引导向导 | 会话扩展、作用域限定的命令、Control UI 描述符 | - 保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、 - `update.*`）始终保持为 `operator.admin`，即使插件尝试分配更狭窄的 - Gateway 网关方法作用域也是如此。插件拥有的方法应优先使用插件专用前缀。 + 保留的核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、 + `update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 + Gateway 网关方法作用域也是如此。插件拥有的方法应优先使用插件特定前缀。 - 当内置插件需要在执行后、运行时把结果回传给模型之前重写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。这是面向 tokenjuice 等异步输出归约器的可信且运行时中立的接缝。 + 当内置插件需要在工具执行后、运行时将结果反馈给模型之前重写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。这是用于 tokenjuice 等异步输出 reducer 的、受信任且运行时中立的接缝。 -内置插件必须为每个目标运行时声明 `contracts.agentToolResultMiddleware`，例如 `["pi", "codex"]`。外部插件不能注册此中间件；不需要模型前工具结果时序的工作应继续使用普通 OpenClaw 插件钩子。旧的仅 Pi 嵌入式扩展工厂注册路径已移除。 +内置插件必须为每个目标运行时声明 `contracts.agentToolResultMiddleware`，例如 `["pi", "codex"]`。外部插件不能注册此中间件；对于不需要模型前工具结果时序的工作，请继续使用普通 OpenClaw 插件钩子。旧的仅 Pi 嵌入式扩展工厂注册路径已被移除。 ### 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({ @@ -159,16 +161,18 @@ api.registerGatewayDiscoveryService({ }); ``` -Gateway 网关发现插件不得将公告的 TXT 值视为机密或凭证。设备发现只是路由提示；Gateway 网关凭证和 TLS 固定仍然负责信任。 +Gateway 网关发现插件不得将公告的 TXT 值视为秘密或认证。设备发现只是路由提示；Gateway 网关认证和 TLS 固定仍然负责信任。 ### CLI 注册元数据 -`api.registerCli(registrar, opts?)` 接受两类顶层元数据： +`api.registerCli(registrar, opts?)` 接受两类顶级元数据： -- `commands`：注册器拥有的显式命令根 -- `descriptors`：解析时命令描述符，用于根 CLI 帮助、路由和惰性插件 CLI 注册 +- `commands`：由注册器拥有的显式命令根 +- `descriptors`：解析时命令描述符，用于根 CLI 帮助、 + 路由和延迟插件 CLI 注册 -如果你希望插件命令在正常根 CLI 路径中保持延迟加载，请提供覆盖该注册器暴露的每个顶层命令根的 `descriptors`。 +如果你希望插件命令在普通根 CLI 路径中保持延迟加载， +请提供覆盖该注册器暴露的每个顶层命令根的 `descriptors`。 ```typescript api.registerCli( @@ -188,83 +192,95 @@ api.registerCli( ); ``` -只有在不需要延迟根 CLI 注册时，才单独使用 `commands`。该急切兼容路径仍然受支持，但它不会安装由描述符支持的占位符来进行解析时延迟加载。 +仅在不需要延迟根 CLI 注册时，才单独使用 `commands`。 +该急切兼容路径仍受支持，但它不会安装由描述符支持的占位符， +用于解析时延迟加载。 ### CLI 后端注册 -`api.registerCliBackend(...)` 让插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。 +`api.registerCliBackend(...)` 允许插件拥有本地 +AI CLI 后端（例如 `codex-cli`）的默认配置。 -- 后端 `id` 会成为 `codex-cli/gpt-5` 这类模型引用中的提供商前缀。 -- 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的形状。 -- 用户配置仍然优先。OpenClaw 会先将 `agents.defaults.cliBackends.` 合并到插件默认值之上，然后再运行 CLI。 -- 当后端需要在合并后进行兼容性重写时，请使用 `normalizeConfig`（例如规范化旧的标志形状）。 +- 后端 `id` 会成为 `codex-cli/gpt-5` 等模型引用中的提供商前缀。 +- 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的结构。 +- 用户配置仍然优先。OpenClaw 会先将 `agents.defaults.cliBackends.` 合并到 + 插件默认值上，然后再运行 CLI。 +- 当后端需要在合并后执行兼容性重写时，请使用 `normalizeConfig` + （例如规范化旧的标志结构）。 ### 独占槽位 -| 方法 | 注册内容 | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只能有一个处于活动状态）。`assemble()` 回调会收到 `availableTools` 和 `citationsMode`，以便引擎定制提示词附加内容。 | -| `api.registerMemoryCapability(capability)` | 统一内存能力 | -| `api.registerMemoryPromptSection(builder)` | 内存提示词段构建器 | -| `api.registerMemoryFlushPlan(resolver)` | 内存刷新计划解析器 | -| `api.registerMemoryRuntime(runtime)` | 内存运行时适配器 | +| 方法 | 注册内容 | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只能有一个处于活动状态）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎可以定制提示词补充内容。 | +| `api.registerMemoryCapability(capability)` | 统一内存能力 | +| `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` 使用导出的内存工件，而不是访问某个特定内存插件的私有布局。 -- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占内存插件 API。 -- `MemoryFlushPlan.model` 可以将刷新轮次固定到精确的 `provider/model` 引用，例如 `ollama/qwen3:8b`，而不会继承活动的回退链。 -- `registerMemoryEmbeddingProvider` 让活动内存插件注册一个或多个嵌入适配器 ID（例如 `openai`、`gemini`，或插件自定义 ID）。 -- `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback` 这类用户配置会根据这些已注册的适配器 ID 解析。 +- `registerMemoryCapability` 还可以暴露 `publicArtifacts.listArtifacts(...)`， + 让配套插件通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的内存工件， + 而不是进入某个特定内存插件的私有布局。 +- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 + `registerMemoryRuntime` 是兼容旧版的独占内存插件 API。 +- `MemoryFlushPlan.model` 可以将刷新轮次固定到精确的 `provider/model` + 引用，例如 `ollama/qwen3:8b`，而不继承活动回退链。 +- `registerMemoryEmbeddingProvider` 允许活动内存插件注册一个或多个 + 嵌入适配器 ID（例如 `openai`、`gemini`，或自定义的插件定义 ID）。 +- `agents.defaults.memorySearch.provider` 和 + `agents.defaults.memorySearch.fallback` 等用户配置会根据这些已注册的 + 适配器 ID 解析。 ### 事件和生命周期 -| 方法 | 作用 | -| -------------------------------------------- | -------------------- | -| `api.on(hookName, handler, opts?)` | 类型化生命周期钩子 | -| `api.onConversationBindingResolved(handler)` | 对话绑定回调 | +| 方法 | 作用 | +| -------------------------------------------- | ---------------- | +| `api.on(hookName, handler, opts?)` | 类型化生命周期钩子 | +| `api.onConversationBindingResolved(handler)` | 对话绑定回调 | -参见 [插件钩子](/zh-CN/plugins/hooks)，了解示例、常见钩子名称和守卫语义。 +有关示例、常见钩子名称和保护语义，请参阅 [插件钩子](/zh-CN/plugins/hooks)。 ### 钩子决策语义 -- `before_tool_call`：返回 `{ block: true }` 是终止性决策。一旦任何处理程序设置它，就会跳过优先级较低的处理程序。 +- `before_tool_call`：返回 `{ block: true }` 是终止性决策。一旦任何处理器设置它，就会跳过较低优先级的处理器。 - `before_tool_call`：返回 `{ block: false }` 会被视为没有决策（与省略 `block` 相同），而不是覆盖。 -- `before_install`：返回 `{ block: true }` 是终止性决策。一旦任何处理程序设置它，就会跳过优先级较低的处理程序。 +- `before_install`：返回 `{ block: true }` 是终止性决策。一旦任何处理器设置它，就会跳过较低优先级的处理器。 - `before_install`：返回 `{ block: false }` 会被视为没有决策（与省略 `block` 相同），而不是覆盖。 -- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性决策。一旦任何处理程序声明已分发，就会跳过优先级较低的处理程序和默认模型分发路径。 -- `message_sending`：返回 `{ cancel: true }` 是终止性决策。一旦任何处理程序设置它，就会跳过优先级较低的处理程序。 +- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性决策。一旦任何处理器声明已处理派发，就会跳过较低优先级的处理器和默认模型派发路径。 +- `message_sending`：返回 `{ cancel: true }` 是终止性决策。一旦任何处理器设置它，就会跳过较低优先级的处理器。 - `message_sending`：返回 `{ cancel: false }` 会被视为没有决策（与省略 `cancel` 相同），而不是覆盖。 -- `message_received`：当你需要入站话题/线程路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的额外信息。 +- `message_received`：当你需要入站线程/主题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的附加信息。 - `message_sending`：先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到渠道特定的 `metadata`。 - `gateway_start`：使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 获取 Gateway 网关拥有的启动状态，而不是依赖内部 `gateway:startup` 钩子。 -- `cron_changed`：观察 Gateway 网关拥有的 cron 生命周期变化。在同步外部唤醒调度器时使用 `event.job?.state?.nextRunAtMs` 和 `ctx.getCron?.()`，并让 OpenClaw 作为到期检查和执行的事实来源。 +- `cron_changed`：观察 Gateway 网关拥有的 cron 生命周期变化。在同步外部唤醒调度器时使用 `event.job?.state?.nextRunAtMs` 和 `ctx.getCron?.()`，并保持 OpenClaw 作为到期检查和执行的事实来源。 ### 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.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.resolvePath(input)` | `(string) => string` | 解析相对于插件根的路径 | ## 内部模块约定 -在你的插件内，使用本地桶文件进行内部导入： +在你的插件中，使用本地 barrel 文件进行内部导入： ``` my-plugin/ @@ -275,22 +291,32 @@ my-plugin/ ``` - 永远不要在生产代码中通过 `openclaw/plugin-sdk/` 导入你自己的插件。请通过 `./api.ts` 或 `./runtime-api.ts` 路由内部导入。SDK 路径仅是外部契约。 + 切勿在生产代码中通过 `openclaw/plugin-sdk/` + 导入你自己的插件。内部导入应通过 `./api.ts` 或 + `./runtime-api.ts` 路由。SDK 路径仅是外部契约。 -通过外观加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）在 OpenClaw 已运行时，优先使用活动运行时配置快照。如果尚不存在运行时快照，它们会回退到磁盘上已解析的配置文件。打包后的内置插件外观应通过 OpenClaw SDK 外观加载器加载；直接从 `dist/extensions/...` 导入会绕过打包安装用于插件自有依赖项的分阶段运行时依赖镜像。 +通过 facade 加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、 +`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）会在 OpenClaw 已运行时 +优先使用活动运行时配置快照。如果尚不存在运行时快照，它们会回退到磁盘上已解析的配置文件。 +打包的内置插件 facade 应通过 OpenClaw SDK facade 加载器加载；直接从 +`dist/extensions/...` 导入会绕过打包安装用于插件自有依赖的分阶段运行时依赖镜像。 -当辅助工具有意限定于某个提供商，并且尚不属于通用 SDK 子路径时，提供商插件可以暴露一个窄范围的插件本地契约桶文件。内置示例： +当某个辅助工具有意为提供商特定，且尚不属于通用 SDK 子路径时， +提供商插件可以暴露一个窄范围的插件本地契约 barrel。内置示例： -- **Anthropic**：面向 Claude beta 标头和 `service_tier` 流辅助工具的公共 `api.ts` / `contract-api.ts` 接缝。 +- **Anthropic**：面向 Claude beta-header 和 `service_tier` 流辅助工具的公共 `api.ts` / `contract-api.ts` 接缝。 - **`@openclaw/openai-provider`**：`api.ts` 导出提供商构建器、默认模型辅助工具和实时提供商构建器。 - **`@openclaw/openrouter-provider`**：`api.ts` 导出提供商构建器以及新手引导/配置辅助工具。 - 插件生产代码也应避免导入 `openclaw/plugin-sdk/`。如果某个辅助工具确实是共享的，请将其提升到中立的 SDK 子路径，例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他面向能力的表面，而不是把两个插件耦合在一起。 + 插件生产代码也应避免导入 `openclaw/plugin-sdk/`。 + 如果某个辅助工具确实共享，请将其提升到中立的 SDK 子路径， + 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他 + 面向能力的表面，而不是将两个插件耦合在一起。 -## 相关 +## 相关内容 @@ -300,15 +326,15 @@ my-plugin/ 完整的 `api.runtime` 命名空间参考。 - 打包、清单和配置架构。 + 打包、清单和配置 schema。 - 测试实用工具和 lint 规则。 + 测试工具和 lint 规则。 从已弃用表面迁移。 - 深层架构和能力模型。 + 深入架构和能力模型。 diff --git a/docs/zh-CN/plugins/sdk-subpaths.md b/docs/zh-CN/plugins/sdk-subpaths.md index fbc357c4d..0e53cbbe0 100644 --- a/docs/zh-CN/plugins/sdk-subpaths.md +++ b/docs/zh-CN/plugins/sdk-subpaths.md @@ -1,323 +1,326 @@ --- read_when: - 为插件导入选择正确的 plugin-sdk 子路径 - - 审计内置插件的子路径和辅助接口 -summary: 插件 SDK 子路径目录：各导入项位于何处，按领域分组 + - 审计内置插件子路径和辅助接口 +summary: 插件 SDK 子路径目录：哪些导入项位于何处，按领域分组 title: 插件 SDK 子路径 x-i18n: - generated_at: "2026-04-28T12:00:38Z" + generated_at: "2026-04-28T20:08:25Z" model: gpt-5.5 provider: openai - source_hash: 8f9939a84decc6d5ff34662044af97b8c9da838b0d2791b2cd0cfa15d181fdd7 + source_hash: f66fa1c9f9398ae2124dc4b92d3b11a07800616f452409d12e851a6fb0bcd675 source_path: plugins/sdk-subpaths.md workflow: 16 --- - 插件 SDK 以 `openclaw/plugin-sdk/` 下的一组窄子路径形式暴露。 - 本页按用途分组列出常用子路径。生成的 200+ 个子路径完整列表位于 `scripts/lib/plugin-sdk-entrypoints.json`； - 保留的内置插件辅助子路径也会出现在那里，但除非文档页明确提升它们，否则它们属于实现细节。维护者可以用 `pnpm plugins:boundary-report:summary` 审计活跃的 - 保留辅助子路径；未使用的保留辅助导出会让 CI 报告失败，而不是作为休眠的兼容性债务留在公共 SDK 中。 + 插件 SDK 以 `openclaw/plugin-sdk/` 下的一组窄子路径形式公开。 + 本页按用途分组列出常用子路径。生成的 200 多个子路径完整列表位于 `scripts/lib/plugin-sdk-entrypoints.json`； + 保留的内置插件辅助子路径也会出现在其中，但除非文档页面明确提升它们，否则它们属于实现细节。维护者可以使用 `pnpm plugins:boundary-report:summary` 审计当前使用中的保留辅助子路径；未使用的保留辅助导出会让 CI 报告失败，而不是作为休眠的兼容性债务留在公共 SDK 中。 - 插件编写指南见[插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 + 关于插件创作指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 ## 插件入口 - | 子路径 | 主要导出 | + | 子路径 | 关键导出 | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | | `plugin-sdk/config-schema` | `OpenClawSchema` | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/testing` | 面向旧版插件测试的宽兼容性聚合入口；新的插件测试应优先使用更聚焦的测试子路径 | - | `plugin-sdk/plugin-test-api` | 用于直接插件注册单元测试的最小 `OpenClawPluginApi` 模拟构建器 | - | `plugin-sdk/agent-runtime-test-contracts` | 用于凭证配置文件、投递抑制、回退分类、工具钩子、提示词叠加层、schema 和转录修复的原生智能体运行时适配器契约 fixture | - | `plugin-sdk/channel-test-helpers` | 渠道账号生命周期、目录、发送配置、运行时模拟、钩子、内置渠道入口、信封时间戳、配对回复和通用渠道契约测试辅助工具 | + | `plugin-sdk/testing` | 面向旧版插件测试的宽兼容性桶；新的扩展测试应优先使用聚焦的测试子路径 | + | `plugin-sdk/plugin-test-api` | 用于直接插件注册单元测试的最小 `OpenClawPluginApi` mock 构建器 | + | `plugin-sdk/agent-runtime-test-contracts` | 原生 agent-runtime 适配器契约夹具，用于凭证配置文件、投递抑制、回退分类、工具钩子、提示词叠加、schema 和 transcript 修复 | + | `plugin-sdk/channel-test-helpers` | 渠道账户生命周期、目录、发送配置、运行时 mock、钩子、内置渠道入口、信封时间戳、配对回复，以及通用渠道契约测试辅助工具 | | `plugin-sdk/channel-target-testing` | 共享的渠道目标解析错误场景测试套件 | - | `plugin-sdk/plugin-test-contracts` | 插件注册、包清单、公共产物、运行时 API、导入副作用和直接导入契约辅助工具 | - | `plugin-sdk/plugin-test-runtime` | 用于测试的插件运行时、注册表、提供商注册、设置向导和运行时任务流 fixture | - | `plugin-sdk/provider-test-contracts` | 提供商运行时、凭证、设备发现、新手引导、目录、媒体能力、重放策略、实时 STT 现场音频、网页搜索/获取和向导契约辅助工具 | - | `plugin-sdk/provider-http-test-mocks` | 供执行 `plugin-sdk/provider-http` 的提供商测试选择启用的 Vitest HTTP/凭证模拟 | - | `plugin-sdk/test-env` | 测试环境、fetch/网络、一次性 HTTP 服务器、传入请求、现场测试、临时文件系统和时间控制 fixture | - | `plugin-sdk/test-fixtures` | 通用 CLI、沙箱、skill、智能体消息、系统事件、模块重载、内置插件路径、终端、分块、凭证令牌和类型化用例测试 fixture | - | `plugin-sdk/test-node-mocks` | 用于 Vitest `vi.mock("node:*")` 工厂内部的聚焦 Node 内置模拟辅助工具 | - | `plugin-sdk/migration` | 迁移提供商条目辅助工具，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助工具和 `summarizeMigrationItems` | + | `plugin-sdk/plugin-test-contracts` | 插件注册、包 manifest、公共产物、运行时 API、导入副作用，以及直接导入契约辅助工具 | + | `plugin-sdk/plugin-test-runtime` | 用于测试的插件运行时、注册表、提供商注册、设置向导，以及运行时任务流夹具 | + | `plugin-sdk/provider-test-contracts` | 提供商运行时、凭证、设备发现、新手引导、目录、媒体能力、重放策略、实时 STT 实时音频、Web 搜索/获取，以及向导契约辅助工具 | + | `plugin-sdk/provider-http-test-mocks` | 面向测试 `plugin-sdk/provider-http` 的提供商测试的可选 Vitest HTTP/凭证 mock | + | `plugin-sdk/test-env` | 测试环境、fetch/网络、一次性 HTTP 服务器、传入请求、实时测试、临时文件系统，以及时间控制夹具 | + | `plugin-sdk/test-fixtures` | 通用 CLI、沙箱、skill、agent-message、system-event、模块重载、内置插件路径、终端、分块、凭证 token，以及 typed-case 测试夹具 | + | `plugin-sdk/test-node-mocks` | 用于 Vitest `vi.mock("node:*")` 工厂内的聚焦 Node 内置 mock 辅助工具 | + | `plugin-sdk/migration` | 迁移提供商项目辅助工具，例如 `createMigrationItem`、原因常量、项目状态标记、脱敏辅助工具，以及 `summarizeMigrationItems` | | `plugin-sdk/migration-runtime` | 运行时迁移辅助工具，例如 `copyMigrationFileItem` 和 `writeMigrationReport` | - | 子路径 | 主要导出 | + | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | 共享的设置向导辅助工具、allowlist 提示、设置 Status 构建器 | + | `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账号配置/操作门控辅助工具、默认账号回退辅助工具 | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、账号 ID 规范化辅助工具 | - | `plugin-sdk/account-resolution` | 账号查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄账号列表/账号操作辅助工具 | + | `plugin-sdk/account-core` | 多账户配置/action-gate 辅助工具、默认账户回退辅助工具 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化辅助工具 | + | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 | + | `plugin-sdk/account-helpers` | 窄账户列表/账户操作辅助工具 | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 共享渠道配置 schema 原语和通用构建器 | | `plugin-sdk/bundled-channel-config-schema` | 仅供维护的内置插件使用的内置 OpenClaw 渠道配置 schema | | `plugin-sdk/channel-config-schema-legacy` | 内置渠道配置 schema 的已弃用兼容性别名 | - | `plugin-sdk/telegram-command-config` | 带内置契约回退的 Telegram 自定义命令规范化/验证辅助工具 | - | `plugin-sdk/command-gating` | 窄命令授权门控辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，带内置契约回退 | + | `plugin-sdk/command-gating` | 窄命令授权 gate 辅助工具 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/最终化辅助工具 | | `plugin-sdk/inbound-envelope` | 共享传入路由 + 信封构建器辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 共享传入记录和分发辅助工具 | + | `plugin-sdk/inbound-reply-dispatch` | 共享传入记录与分发辅助工具 | | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 | | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 | | `plugin-sdk/outbound-send-deps` | 面向渠道适配器的轻量出站发送依赖查找 | - | `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化和载荷规划辅助工具 | + | `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化，以及载荷规划辅助工具 | | `plugin-sdk/poll-runtime` | 窄投票规范化辅助工具 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 | | `plugin-sdk/agent-media-payload` | 旧版智能体媒体载荷构建器 | - | `plugin-sdk/conversation-runtime` | 对话/线程绑定、配对和已配置绑定辅助工具 | + | `plugin-sdk/conversation-runtime` | 对话/线程绑定、配对，以及已配置绑定辅助工具 | | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 | | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 | | `plugin-sdk/channel-status` | 共享渠道 Status 快照/摘要辅助工具 | | `plugin-sdk/channel-config-primitives` | 窄渠道配置 schema 原语 | | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 | - | `plugin-sdk/channel-plugin-common` | 共享渠道插件前置导出 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助工具 | + | `plugin-sdk/channel-plugin-common` | 共享渠道插件 prelude 导出 | + | `plugin-sdk/allowlist-config-edit` | Allowlist 配置编辑/读取辅助工具 | | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 共享直接私信凭证/守卫辅助工具 | - | `plugin-sdk/interactive-runtime` | 语义消息呈现、投递和旧版交互式回复辅助工具。见[消息呈现](/zh-CN/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | 传入防抖、提及匹配、提及策略辅助工具和信封辅助工具的兼容性聚合入口 | + | `plugin-sdk/direct-dm` | 共享直接私信凭证/防护辅助工具 | + | `plugin-sdk/discord` | 面向已发布 `@openclaw/discord@2026.3.13` 的已弃用 Discord 兼容性 facade；新插件应使用通用渠道 SDK 子路径 | + | `plugin-sdk/interactive-runtime` | 语义消息呈现、投递，以及旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | 面向传入防抖、提及匹配、提及策略辅助工具，以及信封辅助工具的兼容性桶 | | `plugin-sdk/channel-inbound-debounce` | 窄传入防抖辅助工具 | - | `plugin-sdk/channel-mention-gating` | 不带更宽传入运行时表面的窄提及策略、提及标记和提及文本辅助工具 | + | `plugin-sdk/channel-mention-gating` | 不包含更宽传入运行时表面的窄提及策略、提及标记和提及文本辅助工具 | | `plugin-sdk/channel-envelope` | 窄传入信封格式化辅助工具 | | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 | - | `plugin-sdk/channel-logging` | 用于传入丢弃和输入/确认失败的渠道日志辅助工具 | + | `plugin-sdk/channel-logging` | 用于传入丢弃和 typing/ack 失败的渠道日志辅助工具 | | `plugin-sdk/channel-send-result` | 回复结果类型 | | `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 | - | `plugin-sdk/channel-route` | 共享路由规范化、解析器驱动的目标解析、线程 ID 字符串化、路由键去重/压缩、已解析目标类型，以及路由/目标比较辅助工具 | + | `plugin-sdk/channel-route` | 共享路由规范化、解析器驱动的目标解析、thread-id 字符串化、去重/紧凑路由键、已解析目标类型，以及路由/目标比较辅助工具 | | `plugin-sdk/channel-targets` | 目标解析辅助工具；路由比较调用方应使用 `plugin-sdk/channel-route` | | `plugin-sdk/channel-contract` | 渠道契约类型 | - | `plugin-sdk/channel-feedback` | 反馈/反应接线 | - | `plugin-sdk/channel-secret-runtime` | 窄密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 | + | `plugin-sdk/channel-feedback` | 反馈/reaction wiring | + | `plugin-sdk/channel-secret-runtime` | 窄 secret-contract 辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment`，以及 secret 目标类型 | - | 子路径 | 关键导出 | + | 子路径 | 主要导出 | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | 支持的 LM Studio 提供商门面，用于设置、目录发现和运行时模型准备 | - | `plugin-sdk/lmstudio-runtime` | 支持的 LM Studio 运行时门面，用于本地服务器默认值、模型发现、请求标头和已加载模型辅助工具 | + | `plugin-sdk/lmstudio` | 用于设置、目录发现和运行时模型准备的受支持 LM Studio 提供商门面 | + | `plugin-sdk/lmstudio-runtime` | 用于本地服务器默认值、模型发现、请求头和已加载模型辅助工具的受支持 LM Studio 运行时门面 | | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 专注的 OpenAI 兼容自托管提供商设置辅助工具 | + | `plugin-sdk/self-hosted-provider-setup` | 专注于 OpenAI 兼容自托管提供商的设置辅助工具 | | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API 密钥解析辅助工具 | + | `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API 密钥解析辅助工具 | | `plugin-sdk/provider-auth-api-key` | API 密钥新手引导/配置文件写入辅助工具，例如 `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | 标准 OAuth 凭证结果构建器 | - | `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助工具 | - | `plugin-sdk/provider-env-vars` | 提供商凭证环境变量查找辅助工具 | + | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | + | `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助工具 | + | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, 共享重放策略构建器、提供商端点辅助工具，以及模型 ID 规范化辅助工具，例如 `normalizeNativeXaiModelId` | - | `plugin-sdk/provider-catalog-runtime` | 提供商目录扩充运行时钩子和用于契约测试的插件提供商注册表接缝 | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、提供商端点辅助工具，以及模型 ID 规范化辅助工具，例如 `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-catalog-runtime` | 提供商目录增强运行时钩子，以及用于契约测试的插件提供商注册表接缝 | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `buildManifestModelProviderConfig`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具、提供商 HTTP 错误，以及音频转录 multipart 表单辅助工具 | - | `plugin-sdk/provider-web-fetch-contract` | 狭窄的 Web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册/缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的狭窄 Web-search 配置/凭据辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 狭窄的 Web-search 配置/凭据契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及带作用域的凭据 setter/getter | - | `plugin-sdk/provider-web-search` | Web-search 提供商注册/缓存/运行时辅助工具 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似工具 | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, 流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 | - | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受防护的 fetch、传输消息转换和可写传输事件流 | + | `plugin-sdk/provider-web-fetch-contract` | 狭窄的 Web 抓取配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Web 抓取提供商注册/缓存辅助工具 | + | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的狭窄 Web 搜索配置/凭证辅助工具 | + | `plugin-sdk/provider-web-search-contract` | 狭窄的 Web 搜索配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及带作用域的凭证设置器/获取器 | + | `plugin-sdk/provider-web-search` | Web 搜索提供商注册/缓存/运行时辅助工具 | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 和类似工具 | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 | + | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受防护的 fetch、传输消息转换，以及可写传输事件流 | | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 | | `plugin-sdk/global-singleton` | 进程本地单例/map/缓存辅助工具 | | `plugin-sdk/group-activation` | 狭窄的群组激活模式和命令解析辅助工具 | - - | 子路径 | 关键导出 | + + | 子路径 | 主要导出 | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`，命令注册表辅助工具，包括动态参数菜单格式化、发送者授权辅助工具 | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具，包括动态参数菜单格式化、发送者授权辅助工具 | | `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天操作凭证辅助工具 | + | `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天操作认证辅助工具 | | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤器辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/交付适配器 | + | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 | | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 面向热渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；当更狭窄的适配器/Gateway 网关接缝足够时，优先使用它们 | + | `plugin-sdk/approval-handler-adapter-runtime` | 用于热渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 更宽泛的审批处理器运行时辅助工具；当更狭窄的适配器/Gateway 网关接缝足够时，优先使用它们 | | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | | `plugin-sdk/approval-reply-runtime` | Exec/插件审批回复载荷辅助工具 | | `plugin-sdk/approval-runtime` | Exec/插件审批载荷辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示辅助工具，例如 `formatApprovalDisplayPath` | | `plugin-sdk/reply-dedupe` | 狭窄的入站回复去重重置辅助工具 | - | `plugin-sdk/channel-contract-testing` | 不依赖宽泛测试 barrel 的狭窄渠道契约测试辅助工具 | - | `plugin-sdk/command-auth-native` | 原生命令凭证、动态参数菜单格式化，以及原生会话目标辅助工具 | + | `plugin-sdk/channel-contract-testing` | 不包含宽泛测试 barrel 的狭窄渠道契约测试辅助工具 | + | `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化，以及原生会话目标辅助工具 | | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | | `plugin-sdk/command-primitives-runtime` | 面向热渠道路径的轻量级命令文本谓词 | - | `plugin-sdk/command-surface` | 命令正文规范化和命令表面辅助工具 | + | `plugin-sdk/command-surface` | 命令正文规范化和命令界面辅助工具 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 面向渠道/插件密钥表面的狭窄密钥契约收集辅助工具 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道/插件密钥界面的狭窄密钥契约收集辅助工具 | | `plugin-sdk/secret-ref-runtime` | 用于密钥契约/配置解析的狭窄 `coerceSecretRef` 和 SecretRef 类型辅助工具 | - | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、敏感文本脱敏、常量时间密钥比较，以及密钥收集辅助工具 | - | `plugin-sdk/ssrf-policy` | 主机允许列表和专用网络 SSRF 策略辅助工具 | - | `plugin-sdk/ssrf-dispatcher` | 不包含宽泛 infra 运行时表面的狭窄固定 dispatcher 辅助工具 | - | `plugin-sdk/ssrf-runtime` | 固定 dispatcher、SSRF 防护 fetch、SSRF 错误和 SSRF 策略辅助工具 | + | `plugin-sdk/security-runtime` | 共享信任、私信 gating、外部内容、敏感文本脱敏、常量时间密钥比较，以及密钥收集辅助工具 | + | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 | + | `plugin-sdk/ssrf-dispatcher` | 不包含宽泛基础设施运行时界面的狭窄固定 dispatcher 辅助工具 | + | `plugin-sdk/ssrf-runtime` | 固定 dispatcher、受 SSRF 防护的 fetch、SSRF 错误，以及 SSRF 策略辅助工具 | | `plugin-sdk/secret-input` | 密钥输入解析辅助工具 | - | `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具和原始 websocket/body 强制转换 | + | `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具，以及原始 websocket/正文强制转换 | | `plugin-sdk/webhook-request-guards` | 请求正文大小/超时辅助工具 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 宽泛的运行时、日志、备份和插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 窄范围的运行时环境、日志记录器、超时、重试和退避辅助工具 | - | `plugin-sdk/browser-config` | 受支持的浏览器配置门面，用于规范化配置文件/默认值、CDP URL 解析和浏览器控制凭证辅助工具 | - | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 | + | `plugin-sdk/runtime` | 广泛的运行时/日志记录/备份/插件安装辅助函数 | + | `plugin-sdk/runtime-env` | 精简的运行时环境、日志记录器、超时、重试和退避辅助函数 | + | `plugin-sdk/browser-config` | 支持的浏览器配置门面，用于规范化配置文件/默认值、CDP URL 解析和浏览器控制鉴权辅助函数 | + | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助函数 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | 共享插件命令、钩子、HTTP 和交互式辅助工具 | - | `plugin-sdk/hook-runtime` | 共享 webhook/内部钩子流水线辅助工具 | - | `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程执行辅助工具 | - | `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用和惰性命令组辅助工具 | - | `plugin-sdk/gateway-runtime` | Gateway 网关客户端、Gateway 网关 CLI RPC、Gateway 网关协议错误和渠道 Status 补丁辅助工具 | - | `plugin-sdk/config-types` | 仅类型配置表面，用于插件配置形态，例如 `OpenClawConfig` 和渠道/提供商配置类型 | - | `plugin-sdk/plugin-config-runtime` | 运行时插件配置查找辅助工具，例如 `requireRuntimeConfig`、`resolvePluginConfigObject` 和 `resolveLivePluginConfigObject` | - | `plugin-sdk/config-mutation` | 事务式配置变更辅助工具，例如 `mutateConfigFile`、`replaceConfigFile` 和 `logConfigUpdated` | - | `plugin-sdk/runtime-config-snapshot` | 当前进程配置快照辅助工具，例如 `getRuntimeConfig`、`getRuntimeConfigSnapshot` 和测试快照设置器 | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约表面不可用也适用 | - | `plugin-sdk/text-autolink-runtime` | 文件引用自动链接检测，不依赖宽泛的文本运行时桶 | - | `plugin-sdk/approval-runtime` | 执行/插件审批辅助工具、审批能力构建器、凭证/配置文件辅助工具、原生路由/运行时辅助工具，以及结构化审批显示路径格式化 | - | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、心跳、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发/完成和对话标签辅助工具 | - | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助工具和标记，例如 `buildHistoryContext`、`HISTORY_CONTEXT_MARKER`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | 共享的插件命令/钩子/http/交互式辅助函数 | + | `plugin-sdk/hook-runtime` | 共享的 webhook/内部钩子管线辅助函数 | + | `plugin-sdk/lazy-runtime` | 懒运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程执行辅助函数 | + | `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用和懒命令组辅助函数 | + | `plugin-sdk/gateway-runtime` | Gateway 网关客户端、Gateway 网关 CLI RPC、Gateway 网关协议错误和渠道状态补丁辅助函数 | + | `plugin-sdk/config-types` | 仅类型的配置表面，用于插件配置形状，例如 `OpenClawConfig` 以及渠道/提供商配置类型 | + | `plugin-sdk/plugin-config-runtime` | 运行时插件配置查找辅助函数，例如 `requireRuntimeConfig`、`resolvePluginConfigObject` 和 `resolveLivePluginConfigObject` | + | `plugin-sdk/config-mutation` | 事务性配置变更辅助函数，例如 `mutateConfigFile`、`replaceConfigFile` 和 `logConfigUpdated` | + | `plugin-sdk/runtime-config-snapshot` | 当前进程配置快照辅助函数，例如 `getRuntimeConfig`、`getRuntimeConfigSnapshot` 和测试快照设置器 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化和重复/冲突检查，即使内置的 Telegram 契约表面不可用也可使用 | + | `plugin-sdk/text-autolink-runtime` | 不依赖广泛的文本运行时桶的文件引用自动链接检测 | + | `plugin-sdk/approval-runtime` | 执行/插件批准辅助函数、批准能力构建器、鉴权/配置文件辅助函数、原生路由/运行时辅助函数，以及结构化批准显示路径格式化 | + | `plugin-sdk/reply-runtime` | 共享的入站/回复运行时辅助函数、分块、分发、心跳、回复规划器 | + | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发/完成和会话标签辅助函数 | + | `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助函数和标记，例如 `buildHistoryContext`、`HISTORY_CONTEXT_MARKER`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 窄范围文本/Markdown 分块辅助工具 | - | `plugin-sdk/session-store-runtime` | 会话存储路径、会话键、更新时间和存储变更辅助工具 | - | `plugin-sdk/cron-store-runtime` | Cron 存储路径/加载/保存辅助工具 | - | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 | - | `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享渠道/账户 Status 摘要辅助工具、运行时状态默认值和问题元数据辅助工具 | - | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助工具 | - | `plugin-sdk/string-normalization-runtime` | Slug/字符串规范化辅助工具 | - | `plugin-sdk/request-url` | 从类似 fetch/request 的输入中提取字符串 URL | - | `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout/stderr 结果 | - | `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 | + | `plugin-sdk/reply-chunking` | 精简的文本/Markdown 分块辅助函数 | + | `plugin-sdk/session-store-runtime` | 会话存储路径、会话键、更新时间和存储变更辅助函数 | + | `plugin-sdk/cron-store-runtime` | Cron 存储路径/加载/保存辅助函数 | + | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助函数 | + | `plugin-sdk/routing` | 路由/会话键/账号绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | 共享的渠道/账号状态摘要辅助函数、运行时状态默认值和问题元数据辅助函数 | + | `plugin-sdk/target-resolver-runtime` | 共享的目标解析器辅助函数 | + | `plugin-sdk/string-normalization-runtime` | Slug/字符串规范化辅助函数 | + | `plugin-sdk/request-url` | 从 fetch/类似 request 的输入中提取字符串 URL | + | `plugin-sdk/run-command` | 带有规范化 stdout/stderr 结果的限时命令运行器 | + | `plugin-sdk/param-readers` | 常用工具/CLI 参数读取器 | | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化载荷 | | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 | - | `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 | - | `plugin-sdk/logging-core` | 子系统日志记录器和遮蔽辅助工具 | - | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助工具 | - | `plugin-sdk/model-session-runtime` | 模型/会话覆盖辅助工具，例如 `applyModelOverrideToSessionEntry` 和 `resolveAgentMaxConcurrent` | - | `plugin-sdk/talk-config-runtime` | Talk 提供商配置解析辅助工具 | - | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 | - | `plugin-sdk/file-lock` | 可重入文件锁辅助工具 | - | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 | - | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 | - | `plugin-sdk/acp-runtime-backend` | 用于启动时加载插件的轻量级 ACP 后端注册和回复分发辅助工具 | - | `plugin-sdk/acp-binding-resolve-runtime` | 只读 ACP 绑定解析，不导入生命周期启动内容 | - | `plugin-sdk/agent-config-primitives` | 窄范围智能体运行时配置模式原语 | + | `plugin-sdk/temp-path` | 共享的临时下载路径辅助函数 | + | `plugin-sdk/logging-core` | 子系统日志记录器和脱敏辅助函数 | + | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助函数 | + | `plugin-sdk/model-session-runtime` | 模型/会话覆盖辅助函数，例如 `applyModelOverrideToSessionEntry` 和 `resolveAgentMaxConcurrent` | + | `plugin-sdk/talk-config-runtime` | 对话提供商配置解析辅助函数 | + | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助函数 | + | `plugin-sdk/file-lock` | 可重入文件锁辅助函数 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 | + | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助函数 | + | `plugin-sdk/acp-runtime-backend` | 用于启动时加载插件的轻量级 ACP 后端注册和回复分发辅助函数 | + | `plugin-sdk/acp-binding-resolve-runtime` | 不导入生命周期启动项的只读 ACP 绑定解析 | + | `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置架构基元 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | - | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 | - | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 | - | `plugin-sdk/extension-shared` | 共享被动渠道、Status 和环境代理辅助原语 | - | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 | - | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 | - | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 | - | `plugin-sdk/agent-harness` | 面向低级 Agent harness 的实验性受信插件表面：harness 类型、活动运行引导/中止辅助工具、OpenClaw 工具桥接辅助工具、运行时计划工具策略辅助工具、终端结果分类、工具进度格式化/详情辅助工具，以及尝试结果实用工具 | - | `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 | - | `plugin-sdk/async-lock-runtime` | 用于小型运行时状态文件的进程本地异步锁辅助工具 | - | `plugin-sdk/channel-activity-runtime` | 渠道活动遥测辅助工具 | - | `plugin-sdk/concurrency-runtime` | 有界异步任务并发辅助工具 | - | `plugin-sdk/dedupe-runtime` | 内存中去重缓存辅助工具 | - | `plugin-sdk/delivery-queue-runtime` | 出站待处理投递排空辅助工具 | - | `plugin-sdk/file-access-runtime` | 安全本地文件和媒体源路径辅助工具 | - | `plugin-sdk/heartbeat-runtime` | 心跳事件和可见性辅助工具 | - | `plugin-sdk/number-runtime` | 数值强制转换辅助工具 | - | `plugin-sdk/secure-random-runtime` | 安全令牌/UUID 辅助工具 | - | `plugin-sdk/system-event-runtime` | 系统事件队列辅助工具 | - | `plugin-sdk/transport-ready-runtime` | 传输就绪等待辅助工具 | - | `plugin-sdk/infra-runtime` | 已弃用的兼容性垫片；请使用上方聚焦的运行时子路径 | - | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 | - | `plugin-sdk/diagnostic-runtime` | 诊断标志、事件和跟踪上下文辅助工具 | - | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和固定查找辅助工具 | - | `plugin-sdk/runtime-fetch` | 感知调度器的运行时 fetch，不导入代理/受保护 fetch | - | `plugin-sdk/response-limit-runtime` | 有界响应体读取器，不依赖宽泛的媒体运行时表面 | - | `plugin-sdk/session-binding-runtime` | 当前对话绑定状态，不依赖配置的绑定路由或配对存储 | - | `plugin-sdk/session-store-runtime` | 会话存储辅助工具，不导入宽泛的配置写入/维护内容 | - | `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不导入宽泛的配置/安全内容 | - | `plugin-sdk/string-coerce-runtime` | 窄范围原始记录/字符串强制转换和规范化辅助工具，不导入 Markdown/日志内容 | - | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | - | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 | - | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 | + | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 | + | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 | + | `plugin-sdk/extension-shared` | 共享的被动渠道、状态和环境代理辅助基元 | + | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助函数 | + | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助函数 | + | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助函数 | + | `plugin-sdk/agent-harness` | 面向低层智能体 harness 的实验性受信插件表面：harness 类型、活动运行引导/中止辅助函数、OpenClaw 工具桥接辅助函数、运行时计划工具策略辅助函数、终端结果分类、工具进度格式化/详情辅助函数，以及尝试结果实用工具 | + | `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助函数 | + | `plugin-sdk/async-lock-runtime` | 用于小型运行时状态文件的进程本地异步锁辅助函数 | + | `plugin-sdk/channel-activity-runtime` | 渠道活动遥测辅助函数 | + | `plugin-sdk/concurrency-runtime` | 有界异步任务并发辅助函数 | + | `plugin-sdk/dedupe-runtime` | 内存中去重缓存辅助函数 | + | `plugin-sdk/delivery-queue-runtime` | 出站待处理投递排空辅助函数 | + | `plugin-sdk/file-access-runtime` | 安全本地文件和媒体源路径辅助函数 | + | `plugin-sdk/heartbeat-runtime` | 心跳事件和可见性辅助函数 | + | `plugin-sdk/number-runtime` | 数值强制转换辅助函数 | + | `plugin-sdk/secure-random-runtime` | 安全令牌/UUID 辅助函数 | + | `plugin-sdk/system-event-runtime` | 系统事件队列辅助函数 | + | `plugin-sdk/transport-ready-runtime` | 传输就绪等待辅助函数 | + | `plugin-sdk/infra-runtime` | 已弃用的兼容性垫片；请使用上面聚焦的运行时子路径 | + | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 | + | `plugin-sdk/diagnostic-runtime` | 诊断标志、事件和跟踪上下文辅助函数 | + | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和固定查找辅助函数 | + | `plugin-sdk/runtime-fetch` | 不导入代理/受保护 fetch 的调度器感知运行时 fetch | + | `plugin-sdk/response-limit-runtime` | 不依赖广泛媒体运行时表面的有界响应体读取器 | + | `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置的绑定路由或配对存储 | + | `plugin-sdk/session-store-runtime` | 会话存储辅助函数，不包含广泛的配置写入/维护导入 | + | `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不包含广泛的配置/安全导入 | + | `plugin-sdk/string-coerce-runtime` | 精简的基元记录/字符串强制转换和规范化辅助函数，不包含 Markdown/日志导入 | + | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 | + | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 | + | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助函数 | | `plugin-sdk/directory-runtime` | 配置支持的目录查询/去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - + | 子路径 | 主要导出 | | --- | --- | - | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具，以及媒体负载构建器 | - | `plugin-sdk/media-store` | 窄范围媒体存储辅助工具，例如 `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型消息 | + | `plugin-sdk/media-runtime` | 共享媒体获取、转换、存储辅助工具，以及媒体载荷构建器 | + | `plugin-sdk/media-store` | 精简的媒体存储辅助工具，例如 `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择，以及缺失模型消息 | | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如剥离智能体可见文本、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具和安全文本工具 | + | `plugin-sdk/text-runtime` | 共享文本、Markdown 和日志辅助工具，例如剥离智能体可见文本、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具，以及安全文本实用工具 | | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 | | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的指令、注册表、验证、OpenAI 兼容 TTS 构建器和语音辅助导出 | - | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、指令、规范化和语音辅助导出 | - | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | + | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、指令、规范化，以及语音辅助导出 | + | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助工具，以及共享 WebSocket 会话辅助工具 | | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 | - | `plugin-sdk/image-generation` | 图像生成提供商类型，以及图像资产/数据 URL 辅助工具和 OpenAI 兼容图像提供商构建器 | - | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、凭证和注册表辅助工具 | + | `plugin-sdk/image-generation` | 图像生成提供商类型，以及图像资源/数据 URL 辅助工具和 OpenAI 兼容图像提供商构建器 | + | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助工具 | | `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找和模型引用解析 | + | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找，以及模型引用解析 | | `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助工具、提供商查找和模型引用解析 | + | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助工具、提供商查找，以及模型引用解析 | | `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助工具 | | `plugin-sdk/webhook-path` | Webhook 路径规范化辅助工具 | | `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助工具 | | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/testing` | 面向旧版插件测试的宽泛兼容性桶形导出。新的扩展测试应改为导入聚焦的 SDK 子路径，例如 `plugin-sdk/agent-runtime-test-contracts`、`plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/test-env` 或 `plugin-sdk/test-fixtures` | - | `plugin-sdk/plugin-test-api` | 最小的 `createTestPluginApi` 辅助工具，用于不导入仓库测试辅助桥接的直接插件注册单元测试 | - | `plugin-sdk/agent-runtime-test-contracts` | 原生 Agent Runtimes 适配器契约夹具，用于凭证、交付、回退、工具钩子、提示词叠加、架构和转录投影测试 | - | `plugin-sdk/channel-test-helpers` | 面向渠道的测试辅助工具，用于通用操作/设置/Status 契约、目录断言、账号启动生命周期、发送配置线程化、运行时模拟、Status 问题、出站交付和钩子注册 | - | `plugin-sdk/channel-target-testing` | 渠道测试的共享目标解析错误用例套件 | + | `plugin-sdk/testing` | 用于旧版插件测试的宽兼容 barrel。新的插件测试应改为导入聚焦的 SDK 子路径，例如 `plugin-sdk/agent-runtime-test-contracts`、`plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/test-env` 或 `plugin-sdk/test-fixtures` | + | `plugin-sdk/plugin-test-api` | 最小化的 `createTestPluginApi` 辅助工具，用于直接插件注册单元测试，无需导入仓库测试辅助桥接 | + | `plugin-sdk/agent-runtime-test-contracts` | 原生智能体运行时适配器契约 fixture，用于认证、投递、回退、工具钩子、提示词叠加、schema 和 transcript 投影测试 | + | `plugin-sdk/channel-test-helpers` | 面向渠道的测试辅助工具，用于通用操作/设置/Status 契约、目录断言、账号启动生命周期、发送配置线程、运行时 mock、Status 问题、出站投递，以及钩子注册 | + | `plugin-sdk/channel-target-testing` | 供渠道测试使用的共享目标解析错误用例套件 | | `plugin-sdk/plugin-test-contracts` | 插件包、注册、公共工件、直接导入、运行时 API 和导入副作用契约辅助工具 | - | `plugin-sdk/provider-test-contracts` | 提供商运行时、凭证、设备发现、新手引导、目录、向导、媒体能力、重放策略、实时 STT 实况音频、Web 搜索/获取和流式传输契约辅助工具 | - | `plugin-sdk/provider-http-test-mocks` | 可选启用的 Vitest HTTP/凭证模拟，用于测试 `plugin-sdk/provider-http` 的提供商测试 | - | `plugin-sdk/test-fixtures` | 通用 CLI 运行时捕获、沙箱上下文、skill 写入器、智能体消息、系统事件、模块重新加载、内置插件路径、终端文本、分块、凭证令牌和类型化用例夹具 | - | `plugin-sdk/test-node-mocks` | 聚焦的 Node 内置模拟辅助工具，用于 Vitest `vi.mock("node:*")` 工厂内部 | + | `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、设备发现、新手引导、目录、向导、媒体能力、重放策略、实时 STT 实况音频、Web 搜索/获取，以及流式契约辅助工具 | + | `plugin-sdk/provider-http-test-mocks` | 可选启用的 Vitest HTTP/认证 mock，用于测试 `plugin-sdk/provider-http` 的提供商测试 | + | `plugin-sdk/test-fixtures` | 通用 CLI 运行时捕获、沙箱上下文、Skills 写入器、智能体消息、系统事件、模块重载、内置插件路径、终端文本、分块、认证令牌和类型化用例 fixture | + | `plugin-sdk/test-node-mocks` | 聚焦的 Node 内置 mock 辅助工具，用于 Vitest `vi.mock("node:*")` 工厂内部 | - + | 子路径 | 主要导出 | | --- | --- | - | `plugin-sdk/memory-core` | 面向管理器/配置/文件/CLI 辅助工具的内置 memory-core 辅助表面 | - | `plugin-sdk/memory-core-engine-runtime` | 内存索引/搜索运行时外观 | - | `plugin-sdk/memory-core-host-engine-foundation` | 内存主机基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | 内存主机嵌入契约、注册表访问、本地提供商和通用批处理/远程辅助工具 | - | `plugin-sdk/memory-core-host-engine-qmd` | 内存主机 QMD 引擎导出 | - | `plugin-sdk/memory-core-host-engine-storage` | 内存主机存储引擎导出 | - | `plugin-sdk/memory-core-host-multimodal` | 内存主机多模态辅助工具 | - | `plugin-sdk/memory-core-host-query` | 内存主机查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | 内存主机密钥辅助工具 | - | `plugin-sdk/memory-core-host-events` | 内存主机事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | 内存主机 Status 辅助工具 | - | `plugin-sdk/memory-core-host-runtime-cli` | 内存主机 CLI 运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-core` | 内存主机核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | 内存主机文件/运行时辅助工具 | - | `plugin-sdk/memory-host-core` | 内存主机核心运行时辅助工具的供应商中立别名 | - | `plugin-sdk/memory-host-events` | 内存主机事件日志辅助工具的供应商中立别名 | - | `plugin-sdk/memory-host-files` | 内存主机文件/运行时辅助工具的供应商中立别名 | - | `plugin-sdk/memory-host-markdown` | 面向内存相邻插件的共享受管 Markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 用于搜索管理器访问的活动内存运行时外观 | - | `plugin-sdk/memory-host-status` | 内存主机 Status 辅助工具的供应商中立别名 | + | `plugin-sdk/memory-core` | 用于管理器/配置/文件/CLI 辅助工具的内置 memory-core 辅助表面 | + | `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时门面 | + | `plugin-sdk/memory-core-host-engine-foundation` | Memory 主机基础引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机嵌入契约、注册表访问、本地提供商，以及通用批处理/远程辅助工具 | + | `plugin-sdk/memory-core-host-engine-qmd` | Memory 主机 QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | Memory 主机存储引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | Memory 主机多模态辅助工具 | + | `plugin-sdk/memory-core-host-query` | Memory 主机查询辅助工具 | + | `plugin-sdk/memory-core-host-secret` | Memory 主机 secret 辅助工具 | + | `plugin-sdk/memory-core-host-events` | Memory 主机事件日志辅助工具 | + | `plugin-sdk/memory-core-host-status` | Memory 主机 Status 辅助工具 | + | `plugin-sdk/memory-core-host-runtime-cli` | Memory 主机 CLI 运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-core` | Memory 主机核心运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-files` | Memory 主机文件/运行时辅助工具 | + | `plugin-sdk/memory-host-core` | Memory 主机核心运行时辅助工具的厂商中立别名 | + | `plugin-sdk/memory-host-events` | Memory 主机事件日志辅助工具的厂商中立别名 | + | `plugin-sdk/memory-host-files` | Memory 主机文件/运行时辅助工具的厂商中立别名 | + | `plugin-sdk/memory-host-markdown` | 面向 Memory 相邻插件的共享托管 Markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活跃 Memory 运行时门面 | + | `plugin-sdk/memory-host-status` | Memory 主机 Status 辅助工具的厂商中立别名 | - - 目前没有预留的内置辅助 SDK 子路径。所有者专用辅助工具位于所属插件包内，而可复用的主机契约使用通用 SDK 子路径，例如 `plugin-sdk/gateway-runtime`、`plugin-sdk/security-runtime` 和 `plugin-sdk/plugin-config-runtime`。 + + 目前没有保留的内置辅助工具 SDK 子路径。特定所有者的 + 辅助工具位于所属插件包内部，而可复用的主机契约 + 使用通用 SDK 子路径，例如 `plugin-sdk/gateway-runtime`、 + `plugin-sdk/security-runtime` 和 `plugin-sdk/plugin-config-runtime`。 diff --git a/docs/zh-CN/tools/acp-agents.md b/docs/zh-CN/tools/acp-agents.md index b8a314b2f..248f95a1d 100644 --- a/docs/zh-CN/tools/acp-agents.md +++ b/docs/zh-CN/tools/acp-agents.md @@ -1,109 +1,119 @@ --- read_when: - 通过 ACP 运行编码执行框架 - - 在消息渠道上设置对话绑定的 ACP 会话 + - 在消息渠道上设置绑定到对话的 ACP 会话 - 将消息渠道对话绑定到持久 ACP 会话 - - ACP 后端、插件接入或补全结果递送故障排除 - - 在聊天中操作 /acp 命令 + - ACP 后端、插件接入或完成结果交付的故障排除 + - 从聊天中操作 /acp 命令 sidebarTitle: ACP agents summary: 通过 ACP 后端运行外部编码执行框架（Claude Code、Cursor、Gemini CLI、显式 Codex ACP、OpenClaw ACP、OpenCode） title: ACP 智能体 x-i18n: - generated_at: "2026-04-28T19:52:00Z" + generated_at: "2026-04-28T20:08:49Z" model: gpt-5.5 provider: openai - source_hash: 754aea24b6e050894b8e954350c148bf84f399b445a85ff4a66a2d5b3453157f + source_hash: f7e9100cc825f77ce0972e26ecc26be1526922174c727d2024965d62fa86cd70 source_path: tools/acp-agents.md workflow: 16 --- [Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话 -让 OpenClaw 通过 ACP 后端插件运行外部编码运行框架（例如 Pi、Claude Code、 +让 OpenClaw 通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、 Cursor、Copilot、Droid、OpenClaw ACP、OpenCode、Gemini CLI，以及其他 -受支持的 ACPX 运行框架）。 +受支持的 ACPX harness）。 -每次 ACP 会话生成都会作为[后台任务](/zh-CN/automation/tasks)跟踪。 +每次 ACP 会话生成都会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 -**ACP 是外部运行框架路径，不是默认 Codex 路径。** 原生 Codex app-server 插件拥有 `/codex ...` 控制和 -`agentRuntime.id: "codex"` 嵌入式运行时；ACP 拥有 +**ACP 是外部 harness 路径，不是默认的 Codex 路径。** 原生 +Codex 应用服务器插件负责 `/codex ...` 控制和 +`agentRuntime.id: "codex"` 嵌入式运行时；ACP 负责 `/acp ...` 控制和 `sessions_spawn({ runtime: "acp" })` 会话。 -如果你想让 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有 OpenClaw 渠道会话，请使用 -[`openclaw mcp serve`](/zh-CN/cli/mcp)，而不是 ACP。 +如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的 +OpenClaw 渠道对话，请使用 [`openclaw mcp serve`](/zh-CN/cli/mcp)，而不是 ACP。 -## 我该看哪个页面？ +## 我应该看哪个页面？ -| 你想要… | 使用 | 备注 | +| 你想要… | 使用 | 说明 | | ----------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 在当前会话中绑定或控制 Codex | `/codex bind`, `/codex threads` | 启用 `codex` 插件时的原生 Codex app-server 路径；包括绑定的聊天回复、图片转发、模型/快速/权限、停止和引导控制。ACP 是显式后备方案 | -| 通过 OpenClaw 运行 Claude Code、Gemini CLI、显式 Codex ACP 或其他外部运行框架 | 本页面 | 绑定到聊天的会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 | -| 将 OpenClaw Gateway 网关会话作为 ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端通过 stdio/WebSocket 与 OpenClaw 进行 ACP 通信 | -| 复用本地 AI CLI 作为纯文本后备模型 | [CLI 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、没有运行框架运行时 | +| 在当前对话中绑定或控制 Codex | `/codex bind`, `/codex threads` | 启用 `codex` 插件时使用原生 Codex 应用服务器路径；包括绑定聊天回复、图片转发、模型/快速/权限、停止和引导控制。ACP 是显式回退方案 | +| 通过 OpenClaw 运行 Claude Code、Gemini CLI、显式 Codex ACP，或其他外部 harness | 本页 | 绑定聊天的会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 | +| 将 OpenClaw Gateway 网关会话作为 ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端通过 stdio/WebSocket 与 OpenClaw 进行 ACP 通信 | +| 复用本地 AI CLI 作为纯文本回退模型 | [CLI 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具，没有 ACP 控制，也没有 harness 运行时 | -## 这个开箱即用吗？ +## 这能开箱即用吗？ -通常可以。全新安装默认会启用内置的 `acpx` 运行时插件，并附带一个插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自修复它。运行 `/acp doctor` 进行就绪检查。 +通常可以。全新安装默认会启用内置的 `acpx` 运行时插件， +并附带插件本地固定版本的 `acpx` 二进制文件；OpenClaw 会在启动时探测它 +并进行自修复。运行 `/acp doctor` 进行就绪检查。 -OpenClaw 只会在 ACP **真正可用**时才教智能体使用 ACP 生成会话：ACP 必须已启用，分发不得被禁用，当前会话不得被沙箱阻止，并且必须已加载运行时后端。如果这些条件不满足，ACP 插件 Skills 和 `sessions_spawn` ACP 指引会保持隐藏，这样智能体就不会建议一个不可用的后端。 +只有当 ACP **真正可用**时，OpenClaw 才会教智能体如何生成 ACP： +必须启用 ACP，分发不能被禁用，当前会话不能被沙箱阻止，并且必须加载 +运行时后端。如果不满足这些条件，ACP 插件 Skills 和 +`sessions_spawn` ACP 指引会保持隐藏，以免智能体建议不可用的后端。 - - 如果设置了 `plugins.allow`，它就是一个限制性的插件清单，并且**必须**包含 `acpx`；否则内置默认项会被有意阻止，`/acp doctor` 会报告缺失的允许列表条目。 - - 内置 Codex ACP 适配器会随 `acpx` 插件预置，并在可行时本地启动。 - - 其他目标运行框架适配器在首次使用时可能仍会按需通过 `npx` 获取。 - - 该运行框架的厂商凭证仍必须存在于主机上。 - - 如果主机没有 npm 或网络访问权限，首次运行的适配器获取会失败，直到缓存被预热，或适配器通过其他方式安装。 + - 如果设置了 `plugins.allow`，它就是一个限制性的插件清单，并且**必须**包含 `acpx`；否则内置默认插件会被有意阻止，`/acp doctor` 会报告缺少 allowlist 条目。 + - 内置 Codex ACP 适配器随 `acpx` 插件一起暂存，并在可能时本地启动。 + - 其他目标 harness 适配器在你首次使用时仍可能按需通过 `npx` 获取。 + - 该 harness 的供应商凭证仍必须存在于主机上。 + - 如果主机没有 npm 或网络访问，首次运行的适配器获取会失败，直到缓存已预热或通过其他方式安装了适配器。 - - ACP 会启动一个真实的外部运行框架进程。OpenClaw 负责路由、 - 后台任务状态、交付、绑定和策略；运行框架负责其提供商登录、 + + ACP 会启动一个真实的外部 harness 进程。OpenClaw 负责路由、 + 后台任务状态、投递、绑定和策略；harness 负责其提供商登录、 模型目录、文件系统行为和原生工具。 在归因于 OpenClaw 之前，请确认： - `/acp doctor` 报告一个已启用且健康的后端。 - - 设置 `acp.allowedAgents` 允许列表时，目标 id 被该允许列表允许。 - - 运行框架命令可以在 Gateway 网关主机上启动。 - - 该运行框架的提供商凭证已存在（`claude`、`codex`、`gemini`、`opencode`、`droid` 等）。 - - 所选模型存在于该运行框架中 —— 模型 id 不能跨运行框架移植。 - - 请求的 `cwd` 存在且可访问，或者省略 `cwd` 并让后端使用其默认值。 - - 权限模式与工作相匹配。非交互式会话无法点击原生权限提示，因此写入/执行密集型的编码运行通常需要一个可以无头继续执行的 ACPX 权限配置文件。 + - 设置了 `acp.allowedAgents` allowlist 时，目标 id 被允许。 + - harness 命令可以在 Gateway 网关主机上启动。 + - 该 harness 的提供商凭证已存在（`claude`、`codex`、`gemini`、`opencode`、`droid` 等）。 + - 所选模型存在于该 harness 中 — 模型 id 不能跨 harness 通用。 + - 请求的 `cwd` 存在且可访问；或者省略 `cwd`，让后端使用其默认值。 + - 权限模式与工作匹配。非交互式会话无法点击原生权限提示，因此写入/执行密集型编码运行通常需要一个可以无头继续执行的 ACPX 权限配置文件。 -默认情况下，OpenClaw 插件工具和内置 OpenClaw 工具**不会**暴露给 ACP 运行框架。仅当运行框架应直接调用这些工具时，才在 +默认情况下，OpenClaw 插件工具和内置 OpenClaw 工具**不会**暴露给 +ACP harness。只有当 harness 应直接调用这些工具时，才在 [ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)中启用显式 MCP 桥接。 -## 支持的运行框架目标 +## 支持的 harness 目标 -使用内置 `acpx` 后端时，将这些运行框架 id 用作 `/acp spawn ` 或 `sessions_spawn({ runtime: "acp", agentId: "" })` 目标： +使用内置 `acpx` 后端时，将这些 harness id 用作 `/acp spawn ` +或 `sessions_spawn({ runtime: "acp", agentId: "" })` 目标： -| 运行框架 id | 典型后端 | 备注 | +| Harness id | 典型后端 | 说明 | | ---------- | ---------------------------------------------- | ----------------------------------------------------------------------------------- | -| `claude` | Claude Code ACP 适配器 | 需要主机上的 Claude Code 凭证。 | -| `codex` | Codex ACP 适配器 | 仅在原生 `/codex` 不可用或请求 ACP 时作为显式 ACP 后备。 | +| `claude` | Claude Code ACP 适配器 | 需要主机上有 Claude Code 凭证。 | +| `codex` | Codex ACP 适配器 | 仅在原生 `/codex` 不可用或请求 ACP 时，作为显式 ACP 回退方案。 | | `copilot` | GitHub Copilot ACP 适配器 | 需要 Copilot CLI/运行时凭证。 | | `cursor` | Cursor CLI ACP (`cursor-agent acp`) | 如果本地安装暴露了不同的 ACP 入口点，请覆盖 acpx 命令。 | -| `droid` | Factory Droid CLI | 需要 Factory/Droid 凭证，或运行框架环境中的 `FACTORY_API_KEY`。 | -| `gemini` | Gemini CLI ACP 适配器 | 需要 Gemini CLI 凭证或 API key 设置。 | +| `droid` | Factory Droid CLI | 需要 Factory/Droid 凭证，或 harness 环境中的 `FACTORY_API_KEY`。 | +| `gemini` | Gemini CLI ACP 适配器 | 需要 Gemini CLI 凭证或 API key 设置。 | | `iflow` | iFlow CLI | 适配器可用性和模型控制取决于已安装的 CLI。 | | `kilocode` | Kilo Code CLI | 适配器可用性和模型控制取决于已安装的 CLI。 | -| `kimi` | Kimi/Moonshot CLI | 需要主机上的 Kimi/Moonshot 凭证。 | +| `kimi` | Kimi/Moonshot CLI | 需要主机上有 Kimi/Moonshot 凭证。 | | `kiro` | Kiro CLI | 适配器可用性和模型控制取决于已安装的 CLI。 | -| `opencode` | OpenCode ACP 适配器 | 需要 OpenCode CLI/提供商凭证。 | -| `openclaw` | 通过 `openclaw acp` 的 OpenClaw Gateway 网关桥接 | 让支持 ACP 的运行框架回连到 OpenClaw Gateway 网关会话。 | -| `pi` | Pi/嵌入式 OpenClaw 运行时 | 用于 OpenClaw 原生运行框架实验。 | -| `qwen` | Qwen Code / Qwen CLI | 需要主机上的 Qwen 兼容凭证。 | +| `opencode` | OpenCode ACP 适配器 | 需要 OpenCode CLI/提供商凭证。 | +| `openclaw` | 通过 `openclaw acp` 的 OpenClaw Gateway 网关桥接 | 让支持 ACP 的 harness 回连到 OpenClaw Gateway 网关会话。 | +| `pi` | Pi/嵌入式 OpenClaw 运行时 | 用于 OpenClaw 原生 harness 实验。 | +| `qwen` | Qwen Code / Qwen CLI | 需要主机上有 Qwen 兼容凭证。 | -可以在 acpx 本身中配置自定义 acpx 智能体别名，但 OpenClaw 策略在分发前仍会检查 `acp.allowedAgents` 和任何 `agents.list[].runtime.acp.agent` 映射。 +自定义 acpx 智能体别名可以在 acpx 自身中配置，但 OpenClaw +策略在分发前仍会检查 `acp.allowedAgents` 和任何 +`agents.list[].runtime.acp.agent` 映射。 ## 操作员运行手册 -从聊天开始的快速 `/acp` 流程： +从聊天发起的快速 `/acp` 流程： @@ -112,8 +122,7 @@ OpenClaw 只会在 ACP **真正可用**时才教智能体使用 ACP 生成会话 `/acp spawn codex --bind here`。 - 在绑定的会话或线程中继续（或显式指定会话 - key）。 + 在绑定的对话或线程中继续（或显式指定会话键）。 `/acp status` @@ -133,117 +142,121 @@ OpenClaw 只会在 ACP **真正可用**时才教智能体使用 ACP 生成会话 - - 生成会创建或恢复一个 ACP 运行时会话，在 OpenClaw 会话存储中记录 ACP 元数据，并且当运行由父级拥有时可能会创建一个后台任务。 - - 父级拥有的 ACP 会话会被视为后台工作，即使运行时会话是持久的；完成和跨界面交付会通过父任务通知器完成，而不是像普通面向用户的聊天会话一样处理。 - - 绑定的后续消息会直接发送到 ACP 会话，直到绑定被关闭、失焦、重置或过期。 - - Gateway 网关命令保持本地处理。`/acp ...`、`/status` 和 `/unfocus` 永远不会作为普通提示文本发送给绑定的 ACP 运行框架。 - - 当后端支持取消时，`cancel` 会中止活动轮次；它不会删除绑定或会话元数据。 - - 从 OpenClaw 的角度看，`close` 会结束 ACP 会话并移除绑定。如果运行框架支持恢复，它可能仍会保留自己的上游历史。 - - 空闲运行时 worker 在 `acp.runtime.ttlMinutes` 后可被清理；存储的会话元数据仍可用于 `/acp sessions`。 + - 生成会创建或恢复 ACP 运行时会话，在 OpenClaw 会话存储中记录 ACP 元数据，并且当运行由父级拥有时，可能会创建后台任务。 + - 父级拥有的 ACP 会话会被视为后台工作，即使运行时会话是持久的；完成和跨界面投递会通过父任务通知器，而不是像普通面向用户的聊天会话那样处理。 + - 任务维护会关闭终止状态的父级拥有的一次性 ACP 会话。只要仍存在活跃的对话绑定，持久 ACP 会话就会被保留；没有活跃绑定的过期持久会话会被关闭，以免在拥有任务完成后被静默恢复。 + - 绑定的后续消息会直接发送到 ACP 会话，直到绑定被关闭、取消聚焦、重置或过期。 + - Gateway 网关命令保持本地执行。`/acp ...`、`/status` 和 `/unfocus` 永远不会作为普通提示文本发送给绑定的 ACP harness。 + - 当后端支持取消时，`cancel` 会中止当前轮次；它不会删除绑定或会话元数据。 + - `close` 会从 OpenClaw 视角结束 ACP 会话并移除绑定。如果 harness 支持恢复，它仍可能保留自己的上游历史。 + - 空闲运行时 worker 在 `acp.runtime.ttlMinutes` 之后可被清理；存储的会话元数据仍可用于 `/acp sessions`。 - 应该在启用时路由到**原生 Codex - 插件**的自然语言触发语： + 当**原生 Codex 插件**已启用时，以下自然语言触发应路由到它： - “将这个 Discord 渠道绑定到 Codex。” - “将这个聊天附加到 Codex 线程 ``。” - - “显示 Codex 线程，然后绑定这个。” + - “显示 Codex 线程，然后绑定这个线程。” - 原生 Codex 会话绑定是默认聊天控制路径。 + 原生 Codex 对话绑定是默认聊天控制路径。 OpenClaw 动态工具仍通过 OpenClaw 执行，而 - shell/apply-patch 等 Codex 原生工具在 Codex 内部执行。 - 对于 Codex 原生工具事件，OpenClaw 会注入每轮原生 - 钩子中继，让插件钩子可以阻止 `before_tool_call`、观察 - `after_tool_call`，并通过 OpenClaw 审批路由 Codex `PermissionRequest` 事件。Codex `Stop` 钩子会被中继到 - OpenClaw `before_agent_finalize`，插件可在此请求再进行一次 - 模型轮次，然后 Codex 再最终确定其回答。该中继刻意保持保守：它不会修改 Codex 原生工具参数，也不会重写 Codex 线程记录。仅当你想要 ACP 运行时/会话模型时，才使用显式 ACP。嵌入式 Codex 支持边界记录在 + Codex 原生工具（如 shell/apply-patch）在 Codex 内执行。 + 对于 Codex 原生工具事件，OpenClaw 会注入一个按轮次的原生 + hook 中继，使插件钩子可以阻止 `before_tool_call`、观察 + `after_tool_call`，并通过 OpenClaw 审批路由 Codex `PermissionRequest` 事件。 + Codex `Stop` 钩子会中继到 OpenClaw `before_agent_finalize`， + 插件可在其中请求再进行一次模型调用，然后 Codex 才最终确定回答。 + 该中继保持刻意保守：它不会修改 Codex 原生工具参数，也不会重写 + Codex 线程记录。只有当你需要 ACP 运行时/会话模型时，才使用显式 ACP。 + 嵌入式 Codex 支持边界记录在 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)中。 - `openai-codex/*` — PI Codex OAuth/订阅路由。 - - `openai/*` 加 `agentRuntime.id: "codex"` — 原生 Codex app-server 嵌入式运行时。 - - `/codex ...` — 原生 Codex 会话控制。 + - `openai/*` 加 `agentRuntime.id: "codex"` — 原生 Codex 应用服务器嵌入式运行时。 + - `/codex ...` — 原生 Codex 对话控制。 - `/acp ...` 或 `runtime: "acp"` — 显式 ACP/acpx 控制。 - - 应该路由到 ACP 运行时的触发语： + + 应路由到 ACP 运行时的触发条件： - - “以一次性 Claude Code ACP 会话运行此任务，并总结结果。” - - “在一个线程中用 Gemini CLI 完成此任务，然后将后续跟进保留在同一线程中。” - - “通过 ACP 在后台线程中运行 Codex。” + - "Run this as a one-shot Claude Code ACP session and summarize the result." + - "Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread." + - "Run Codex through ACP in a background thread." OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`， - 在支持时绑定到当前对话或线程，并将后续跟进路由到该会话， - 直到会话关闭或过期。只有在明确指定 ACP/acpx，或原生 Codex - 插件不可用于所请求操作时，Codex 才会走这条路径。 + 在受支持时绑定到当前对话或话题串，并将后续消息路由到该会话，直到关闭或过期。Codex 仅在显式指定 ACP/acpx，或所请求操作无法使用原生 Codex + 插件时，才会采用此路径。 - 对于 `sessions_spawn`，只有在 ACP 已启用、请求方未被沙箱隔离， - 且已加载 ACP 运行时后端时，才会公布 `runtime: "acp"`。 - `acp.dispatch.enabled=false` 会暂停自动 ACP 线程分派，但不会隐藏或阻止显式的 + 对于 `sessions_spawn`，只有在 ACP 已启用、请求方未处于沙箱隔离、 + 且已加载 ACP 运行时后端时，才会宣告 `runtime: "acp"`。 + `acp.dispatch.enabled=false` 会暂停自动 ACP 话题串分发， + 但不会隐藏或阻止显式的 `sessions_spawn({ runtime: "acp" })` 调用。它面向 `codex`、 - `claude`、`droid`、`gemini` 或 `opencode` 等 ACP harness ID。 - 除非某个普通 OpenClaw 配置智能体 ID 来自 `agents_list` 的条目 - 已明确配置为 `agents.list[].runtime.type="acp"`，否则不要传入该 ID； - 请改用默认子智能体运行时。当某个 OpenClaw 智能体配置了 - `runtime.type="acp"` 时，OpenClaw 会使用 - `runtime.acp.agent` 作为底层 harness ID。 + `claude`、`droid`、`gemini` 或 `opencode` 等 ACP harness id。不要传入来自 `agents_list` 的普通 + OpenClaw 配置智能体 id，除非该条目已显式配置为 + `agents.list[].runtime.type="acp"`； + 否则请使用默认子智能体运行时。当 OpenClaw 智能体 + 配置了 `runtime.type="acp"` 时，OpenClaw 会使用 + `runtime.acp.agent` 作为底层 harness id。 -## ACP 与子智能体 +## ACP 与子智能体对比 -如果你需要外部 harness 运行时，请使用 ACP。如果启用了 `codex` -插件，并且你需要 Codex 对话绑定/控制，请使用**原生 Codex -app-server**。如果你需要 OpenClaw 原生委派运行，请使用**子智能体**。 +当你需要外部 harness 运行时时，使用 ACP。当 `codex` +插件已启用且你需要 Codex 对话绑定/控制时，使用 **原生 Codex +应用服务器**。当你需要 OpenClaw 原生的委派运行时，使用 **子智能体**。 -| 领域 | ACP 会话 | 子智能体运行 | +| 领域 | ACP 会话 | 子智能体运行 | | ------------- | ------------------------------------- | ---------------------------------- | -| 运行时 | ACP 后端插件（例如 acpx） | OpenClaw 原生子智能体运行时 | -| 会话键 | `agent::acp:` | `agent::subagent:` | -| 主要命令 | `/acp ...` | `/subagents ...` | -| 生成工具 | 带 `runtime:"acp"` 的 `sessions_spawn` | `sessions_spawn`（默认运行时） | +| 运行时 | ACP 后端插件（例如 acpx） | OpenClaw 原生子智能体运行时 | +| 会话键名 | `agent::acp:` | `agent::subagent:` | +| 主要命令 | `/acp ...` | `/subagents ...` | +| 启动工具 | 带 `runtime:"acp"` 的 `sessions_spawn` | `sessions_spawn`（默认运行时） | -另请参阅[子智能体](/zh-CN/tools/subagents)。 +另请参阅 [子智能体](/zh-CN/tools/subagents)。 ## ACP 如何运行 Claude Code -对于通过 ACP 使用 Claude Code，堆栈为： +通过 ACP 运行 Claude Code 时，栈如下： 1. OpenClaw ACP 会话控制平面。 -2. 内置的 `acpx` 运行时插件。 +2. 内置 `acpx` 运行时插件。 3. Claude ACP 适配器。 4. Claude 侧运行时/会话机制。 -ACP Claude 是一个**harness 会话**，具备 ACP 控制、会话恢复、 -后台任务跟踪，以及可选的对话/线程绑定。 +ACP Claude 是一个 **harness 会话**，具备 ACP 控制、会话恢复、 +后台任务跟踪，以及可选的对话/话题串绑定。 -CLI 后端是独立的纯文本本地后备运行时，参见 +CLI 后端是独立的纯文本本地回退运行时 —— 请参阅 [CLI 后端](/zh-CN/gateway/cli-backends)。 -对操作员来说，实用规则是： +对运维人员而言，实用规则是： - **需要 `/acp spawn`、可绑定会话、运行时控制或持久 harness 工作？** 使用 ACP。 -- **只需要通过原始 CLI 进行简单本地文本后备？** 使用 CLI 后端。 +- **需要通过原始 CLI 进行简单的本地文本回退？** 使用 CLI 后端。 ## 绑定会话 ### 心智模型 -- **聊天表面** — 人们持续对话的位置（Discord 渠道、Telegram 主题、iMessage 聊天）。 +- **聊天界面** — 人们持续对话的位置（Discord 频道、Telegram 话题、iMessage 聊天）。 - **ACP 会话** — OpenClaw 路由到的持久 Codex/Claude/Gemini 运行时状态。 -- **子线程/主题** — 仅由 `--thread ...` 创建的可选额外消息表面。 -- **运行时工作区** — harness 运行的文件系统位置（`cwd`、仓库 checkout、后端工作区）。它独立于聊天表面。 +- **子话题串/话题** — 仅由 `--thread ...` 创建的可选额外消息界面。 +- **运行时工作区** — harness 运行所在的文件系统位置（`cwd`、仓库 checkout、后端工作区）。它独立于聊天界面。 ### 当前对话绑定 -`/acp spawn --bind here` 会将当前对话固定到生成的 -ACP 会话，没有子线程，仍使用同一聊天表面。OpenClaw 继续负责 -传输、鉴权、安全和投递。该对话中的后续消息会路由到同一会话； -`/new` 和 `/reset` 会就地重置该会话；`/acp close` 会移除绑定。 +`/acp spawn --bind here` 会将当前对话固定到 +新启动的 ACP 会话 —— 没有子话题串，仍使用同一聊天界面。OpenClaw 继续 +负责传输、认证、安全和投递。该对话中的后续消息会路由到 +同一会话；`/new` 和 `/reset` 会在原位置重置 +该会话；`/acp close` 会移除绑定。 示例： @@ -257,38 +270,39 @@ ACP 会话，没有子线程，仍使用同一聊天表面。OpenClaw 继续负 ``` - + - `--bind here` 和 `--thread ...` 互斥。 - - `--bind here` 只适用于声明支持当前对话绑定的渠道；否则 OpenClaw 会返回清晰的不支持消息。绑定会在 Gateway 网关重启后保留。 - - 在 Discord 上，只有当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions`；`--bind here` 不需要。 - - 如果你生成到另一个 ACP 智能体且未指定 `--cwd`，OpenClaw 默认继承**目标智能体的**工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为生成错误暴露。 - - Gateway 网关管理命令在绑定对话中保持本地处理：即使普通后续文本路由到绑定的 ACP 会话，`/acp ...` 命令也由 OpenClaw 处理；只要该表面启用了命令处理，`/status` 和 `/unfocus` 也会保持本地处理。 + - `--bind here` 仅适用于宣告支持当前对话绑定的渠道；否则 OpenClaw 会返回清晰的不支持消息。绑定会在 Gateway 网关重启后保持。 + - 在 Discord 上，只有当 OpenClaw 需要为 `--thread auto|here` 创建子话题串时，才需要 `spawnAcpSessions`，而 `--bind here` 不需要。 + - 如果你启动到另一个 ACP 智能体且未指定 `--cwd`，OpenClaw 默认继承**目标智能体的**工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误暴露。 + - Gateway 网关管理命令在绑定对话中仍保持本地处理 —— 即使普通后续文本会路由到绑定的 ACP 会话，`/acp ...` 命令也由 OpenClaw 处理；只要该界面启用了命令处理，`/status` 和 `/unfocus` 也会保持本地处理。 - - 当渠道适配器启用线程绑定时： + + 当渠道适配器启用话题串绑定时： - - OpenClaw 会将线程绑定到目标 ACP 会话。 - - 该线程中的后续消息会路由到绑定的 ACP 会话。 - - ACP 输出会投递回同一线程。 - - 取消聚焦/关闭/归档/空闲超时或最大存活期过期会移除绑定。 + - OpenClaw 会将话题串绑定到目标 ACP 会话。 + - 该话题串中的后续消息会路由到绑定的 ACP 会话。 + - ACP 输出会投递回同一话题串。 + - 取消聚焦/关闭/归档/空闲超时或最大年龄过期会移除绑定。 - `/acp close`、`/acp cancel`、`/acp status`、`/status` 和 `/unfocus` 是 Gateway 网关命令，不是发送给 ACP harness 的提示词。 - 线程绑定 ACP 所需的功能标志： + 话题串绑定 ACP 所需的功能开关： - `acp.enabled=true` - - `acp.dispatch.enabled` 默认开启（设置为 `false` 可暂停自动 ACP 线程分派；显式的 `sessions_spawn({ runtime: "acp" })` 调用仍然可用）。 - - 已启用渠道适配器 ACP 线程生成标志（适配器特定）： + - `acp.dispatch.enabled` 默认开启（设置为 `false` 可暂停自动 ACP 话题串分发；显式 `sessions_spawn({ runtime: "acp" })` 调用仍可工作）。 + - 启用渠道适配器 ACP 话题串启动开关（适配器特定）： - Discord：`channels.discord.threadBindings.spawnAcpSessions=true` - Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true` - 线程绑定支持因适配器而异。如果活动渠道适配器不支持线程绑定， - OpenClaw 会返回清晰的不支持/不可用消息。 + 话题串绑定支持取决于适配器。如果当前活动的渠道 + 适配器不支持话题串绑定，OpenClaw 会返回清晰的 + 不支持/不可用消息。 - - - 任何暴露会话/线程绑定能力的渠道适配器。 - - 当前内置支持：**Discord** 线程/渠道，**Telegram** 主题（群组/超级群组中的论坛主题，以及私信主题）。 + + - 任何公开会话/话题串绑定能力的渠道适配器。 + - 当前内置支持：**Discord** 话题串/频道、**Telegram** 话题（群组/超级群组中的论坛话题和私信话题）。 - 插件渠道可以通过同一绑定接口添加支持。 @@ -306,26 +320,26 @@ ACP 会话，没有子线程，仍使用同一聊天表面。OpenClaw 继续负 标识目标对话。各渠道形状如下： -- **Discord 渠道/线程：** `match.channel="discord"` + `match.peer.id=""` -- **Telegram 论坛主题：** `match.channel="telegram"` + `match.peer.id=":topic:"` -- **BlueBubbles 私信/群组：** `match.channel="bluebubbles"` + `match.peer.id=""`。稳定的群组绑定优先使用 `chat_id:*` 或 `chat_identifier:*`。 -- **iMessage 私信/群组：** `match.channel="imessage"` + `match.peer.id=""`。稳定的群组绑定优先使用 `chat_id:*`。 +- **Discord 频道/话题串：** `match.channel="discord"` + `match.peer.id=""` +- **Telegram 论坛话题：** `match.channel="telegram"` + `match.peer.id=":topic:"` +- **BlueBubbles 私信/群组：** `match.channel="bluebubbles"` + `match.peer.id=""`。对于稳定的群组绑定，优先使用 `chat_id:*` 或 `chat_identifier:*`。 +- **iMessage 私信/群组：** `match.channel="imessage"` + `match.peer.id=""`。对于稳定的群组绑定，优先使用 `chat_id:*`。 - 拥有该绑定的 OpenClaw 智能体 ID。 + 所属 OpenClaw 智能体 id。 - 可选的 ACP 覆盖项。 + 可选 ACP 覆盖项。 - 可选的面向操作员标签。 + 可选的面向运维人员标签。 - 可选的运行时工作目录。 + 可选运行时工作目录。 - 可选的后端覆盖项。 + 可选后端覆盖项。 ### 每个智能体的运行时默认值 @@ -333,7 +347,7 @@ ACP 会话，没有子线程，仍使用同一聊天表面。OpenClaw 继续负 使用 `agents.list[].runtime` 为每个智能体定义一次 ACP 默认值： - `agents.list[].runtime.type="acp"` -- `agents.list[].runtime.acp.agent`（harness ID，例如 `codex` 或 `claude`） +- `agents.list[].runtime.acp.agent`（harness id，例如 `codex` 或 `claude`） - `agents.list[].runtime.acp.backend` - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` @@ -426,20 +440,21 @@ ACP 会话，没有子线程，仍使用同一聊天表面。OpenClaw 继续负 ### 行为 -- OpenClaw 会确保配置的 ACP 会话在使用前存在。 -- 该渠道或主题中的消息会路由到配置的 ACP 会话。 -- 在绑定对话中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话键。 -- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍然适用。 -- 对于未显式指定 `cwd` 的跨智能体 ACP 生成，OpenClaw 会从智能体配置继承目标智能体工作区。 -- 缺失的继承工作区路径会回退到后端默认 cwd；非缺失的访问失败会作为生成错误暴露。 +- OpenClaw 会在使用前确保配置的 ACP 会话存在。 +- 该频道或话题中的消息会路由到配置的 ACP 会话。 +- 在绑定对话中，`/new` 和 `/reset` 会在原位置重置同一个 ACP 会话键。 +- 临时运行时绑定（例如由话题串聚焦流程创建的绑定）在存在时仍会生效。 +- 对于未显式指定 `cwd` 的跨智能体 ACP 启动，OpenClaw 会从智能体配置继承目标智能体工作区。 +- 缺失的继承工作区路径会回退到后端默认 cwd；非缺失的访问失败会作为启动错误暴露。 ## 启动 ACP 会话 启动 ACP 会话有两种方式： - - 使用 `runtime: "acp"` 从智能体回合或工具调用启动 ACP 会话。 + + 使用 `runtime: "acp"` 从智能体回合或 + 工具调用启动 ACP 会话。 ```json { @@ -452,14 +467,14 @@ ACP 会话，没有子线程，仍使用同一聊天表面。OpenClaw 继续负 ``` - `runtime` 默认为 `subagent`，因此请为 ACP 会话显式设置 + `runtime` 默认是 `subagent`，因此对于 ACP 会话，请显式设置 `runtime: "acp"`。如果省略 `agentId`，OpenClaw 会在已配置时使用 - `acp.defaultAgent`。`mode: "session"` 要求 - `thread: true`，以保留持久绑定对话。 + `acp.defaultAgent`。`mode: "session"` 需要 `thread: true` + 才能保留持久绑定会话。 - + 使用 `/acp spawn` 从聊天中进行显式操作员控制。 ```text @@ -477,7 +492,7 @@ ACP 会话，没有子线程，仍使用同一聊天表面。OpenClaw 继续负 - `--cwd ` - `--label ` - 请参阅 [斜杠命令](/zh-CN/tools/slash-commands)。 + 参见 [Slash commands](/zh-CN/tools/slash-commands)。 @@ -485,13 +500,13 @@ ACP 会话，没有子线程，仍使用同一聊天表面。OpenClaw 继续负 ### `sessions_spawn` 参数 - 发送给 ACP 会话的初始提示词。 + 发送到 ACP 会话的初始提示。 - 对于 ACP 会话，必须为 `"acp"`。 + 对于 ACP 会话，必须是 `"acp"`。 - ACP 目标执行框架 ID。如果已设置，则回退到 `acp.defaultAgent`。 + ACP 目标 harness ID。如果已设置，则回退到 `acp.defaultAgent`。 在支持的位置请求线程绑定流程。 @@ -502,58 +517,63 @@ ACP 会话，没有子线程，仍使用同一聊天表面。OpenClaw 继续负 `mode: "session"` 需要 `thread: true`。 - 请求的运行时工作目录（由后端/运行时策略验证）。如果省略，ACP 生成会在已配置时继承目标 Agent 工作区；缺失的继承路径会回退到后端默认值，而真实访问错误会返回。 + 请求的运行时工作目录（由后端/运行时策略验证）。如果省略，ACP spawn 会在已配置时继承目标 Agent 工作区；缺失的继承路径会回退到后端默认值，而真实访问错误会被返回。 - 用于会话/横幅文本的面向操作员的标签。 + 用于会话/banner 文本的面向操作员标签。 - 恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load` 重放其对话历史。需要 `runtime: "acp"`。 + 恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load` + 重放其会话历史。需要 `runtime: "acp"`。 - `"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式传回请求方会话。接受的响应包括 `streamLogPath`，它指向会话范围的 JSONL 日志（`.acp-stream.jsonl`），你可以跟踪它以查看完整中继历史。 + `"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式传回请求方会话。接受的响应包括 + `streamLogPath`，它指向会话作用域的 JSONL 日志 + (`.acp-stream.jsonl`)，你可以 tail 它来查看完整中继历史。 - N 秒后中止 ACP 子轮次。`0` 会让该轮次走 Gateway 网关的无超时路径。同一值会应用到 Gateway 网关运行和 ACP 运行时，避免停滞或配额耗尽的执行框架无限期占用父智能体通道。 + N 秒后中止 ACP 子轮次。`0` 会让该轮次走 gateway 的无超时路径。同一个值会应用到 Gateway 网关运行和 ACP 运行时，因此卡住或配额耗尽的 harness 不会无限期占用父智能体通道。 - ACP 子会话的显式模型覆盖。Codex ACP 生成会在 `session/new` 之前，将 OpenClaw Codex 引用（例如 `openai-codex/gpt-5.4`）规范化为 Codex ACP 启动配置；斜杠形式（例如 `openai-codex/gpt-5.4/high`）也会设置 Codex ACP 推理强度。其他执行框架必须声明 ACP `models` 并支持 `session/set_model`；否则 OpenClaw/acpx 会清晰失败，而不是静默回退到目标智能体默认值。 + ACP 子会话的显式模型覆盖。Codex ACP spawn 会在 `session/new` 之前，将 OpenClaw Codex 引用（例如 `openai-codex/gpt-5.4`）规范化为 Codex ACP 启动配置；类似 + `openai-codex/gpt-5.4/high` 的斜杠形式也会设置 Codex ACP 推理强度。其他 harness 必须声明 ACP `models` 并支持 + `session/set_model`；否则 OpenClaw/acpx 会清晰失败，而不是静默回退到目标智能体默认值。 - 显式思考/推理强度。对于 Codex ACP，`minimal` 映射到低强度，`low`/`medium`/`high`/`xhigh` 直接映射，`off` 会省略推理强度启动覆盖。 + 显式 thinking/推理强度。对于 Codex ACP，`minimal` 映射到低强度，`low`/`medium`/`high`/`xhigh` 直接映射，`off` 会省略推理强度启动覆盖。 -## 生成绑定和线程模式 +## Spawn 绑定和线程模式 | 模式 | 行为 | | ------ | ---------------------------------------------------------------------- | - | `here` | 就地绑定当前活动对话；如果没有活动对话则失败。 | - | `off` | 不创建当前对话绑定。 | + | `here` | 就地绑定当前活跃会话；如果没有活跃会话则失败。 | + | `off` | 不创建当前会话绑定。 | 注意： - - `--bind here` 是“让这个渠道或聊天由 Codex 支持”的最简单操作员路径。 + - `--bind here` 是“让这个渠道或聊天由 Codex 支撑”的最简单操作员路径。 - `--bind here` 不会创建子线程。 - - `--bind here` 仅适用于暴露当前对话绑定支持的渠道。 + - `--bind here` 仅适用于公开当前会话绑定支持的渠道。 - `--bind` 和 `--thread` 不能在同一个 `/acp spawn` 调用中组合使用。 | 模式 | 行为 | | ------ | --------------------------------------------------------------------------------------------------- | - | `auto` | 在活动线程中：绑定该线程。在线程外：在支持时创建/绑定子线程。 | - | `here` | 要求当前存在活动线程；如果不在线程中则失败。 | + | `auto` | 在活跃线程中：绑定该线程。在线程外：在支持时创建/绑定子线程。 | + | `here` | 要求当前活跃线程；如果不在线程中则失败。 | | `off` | 不绑定。会话以未绑定状态启动。 | 注意： - - 在非线程绑定表面上，默认行为实际上是 `off`。 - - 线程绑定生成需要渠道策略支持： + - 在非线程绑定界面上，默认行为实际上是 `off`。 + - 线程绑定 spawn 需要渠道策略支持： - Discord：`channels.discord.threadBindings.spawnAcpSessions=true` - Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true` - - 当你想固定当前对话而不创建子线程时，请使用 `--bind here`。 + - 当你想固定当前会话且不创建子线程时，请使用 `--bind here`。 @@ -563,50 +583,53 @@ ACP 会话，没有子线程，仍使用同一聊天表面。OpenClaw 继续负 ACP 会话可以是交互式工作区，也可以是父级拥有的后台工作。交付路径取决于这种形态。 - - 交互式会话用于在可见聊天表面上持续对话： + + 交互式会话旨在持续在可见聊天界面上对话： - - `/acp spawn ... --bind here` 将当前对话绑定到 ACP 会话。 + - `/acp spawn ... --bind here` 将当前会话绑定到 ACP 会话。 - `/acp spawn ... --thread ...` 将渠道线程/主题绑定到 ACP 会话。 - - 持久配置的 `bindings[].type="acp"` 会将匹配的对话路由到同一个 ACP 会话。 + - 持久配置的 `bindings[].type="acp"` 会将匹配的会话路由到同一个 ACP 会话。 - 绑定对话中的后续消息会直接路由到 ACP 会话，ACP 输出也会交付回同一个渠道/线程/主题。 + 绑定会话中的后续消息会直接路由到 ACP 会话，ACP 输出也会交付回同一渠道/线程/主题。 - OpenClaw 发送给执行框架的内容： + OpenClaw 发送给 harness 的内容： - - 普通绑定后续消息会作为提示词文本发送，只有在执行框架/后端支持时才附带附件。 - - `/acp` 管理命令和本地 Gateway 网关命令会在 ACP 分发之前被拦截。 - - 运行时生成的完成事件会按目标物化。OpenClaw 智能体会获得 OpenClaw 的内部运行时上下文信封；外部 ACP 执行框架会获得带有子结果和指令的普通提示词。原始 `<<>>` 信封不应发送给外部执行框架，也不应作为 ACP 用户转录文本持久化。 - - ACP 转录条目使用用户可见的触发文本或普通完成提示词。在可能的情况下，内部事件元数据在 OpenClaw 中保持结构化，并且不会被视为用户撰写的聊天内容。 + - 普通绑定后续消息会作为提示文本发送，且仅在 harness/后端支持时附带附件。 + - `/acp` 管理命令和本地 Gateway 网关命令会在 ACP 派发前被拦截。 + - 运行时生成的完成事件会按目标实体化。OpenClaw 智能体会收到 OpenClaw 的内部运行时上下文信封；外部 ACP harness 会收到包含子结果和指令的普通提示。原始 `<<>>` 信封绝不应发送到外部 harness，也不应作为 ACP 用户转录文本持久化。 + - ACP 转录条目使用用户可见的触发文本或普通完成提示。内部事件元数据会尽可能在 OpenClaw 中保持结构化，并且不会被视为用户撰写的聊天内容。 - - 由另一个智能体运行生成的一次性 ACP 会话是后台子项，类似于子智能体： + + 由另一个智能体运行 spawn 出来的一次性 ACP 会话是后台子会话，类似于子智能体： - - 父级使用 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。 - - 子项在自己的 ACP 执行框架会话中运行。 - - 子轮次会运行在原生子智能体生成所用的同一后台通道上，因此缓慢的 ACP 执行框架不会阻塞无关的主会话工作。 - - 完成结果会通过任务完成公告路径回报。OpenClaw 会在发送给外部执行框架之前，将内部完成元数据转换为普通 ACP 提示词，因此执行框架不会看到仅限 OpenClaw 的运行时上下文标记。 - - 当面向用户的回复有用时，父级会用正常助手口吻重写子项结果。 + - 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。 + - 子级在自己的 ACP harness 会话中运行。 + - 子轮次运行在原生子智能体 spawn 使用的同一个后台通道上，因此缓慢的 ACP harness 不会阻塞无关的主会话工作。 + - 完成通过任务完成公告路径回报。OpenClaw 会在发送给外部 harness 前，将内部完成元数据转换为普通 ACP 提示，因此 harness 不会看到 OpenClaw 专用的运行时上下文标记。 + - 当用户可见回复有用时，父级会用正常助手语气重写子结果。 - **不要**将此路径视为父级和子项之间的点对点聊天。子项已经有一个返回父级的完成渠道。 + **不要**将此路径视为父级和子级之间的点对点聊天。子级已经有一条返回父级的完成渠道。 - - `sessions_send` 可以在生成后定位另一个会话。对于普通对等会话，OpenClaw 会在注入消息后使用智能体到智能体（A2A）后续路径： + + `sessions_send` 可以在 spawn 后以另一个会话为目标。对于普通对等会话，OpenClaw 会在注入消息后使用智能体到智能体（A2A）的后续路径： - 等待目标会话的回复。 - - 可选地允许请求方和目标交换有限数量的后续轮次。 + - 可选地允许请求方和目标交换有界数量的后续轮次。 - 要求目标生成一条公告消息。 - 将该公告交付到可见渠道或线程。 - 该 A2A 路径是对等发送的回退方案，用于发送方需要可见后续回复的情况。当无关会话可以看到并向 ACP 目标发消息时，它仍会启用，例如在宽泛的 `tools.sessions.visibility` 设置下。 + 该 A2A 路径是对等发送的回退方案，适用于发送方需要可见后续回复的场景。当无关会话可以看到 ACP 目标并向其发送消息时，例如在宽泛的 + `tools.sessions.visibility` 设置下，它会保持启用。 - 只有当请求方是自己父级拥有的一次性 ACP 子项的父级时，OpenClaw 才会跳过 A2A 后续。在这种情况下，在任务完成之上运行 A2A 可能会用子项结果唤醒父级，将父级回复转发回子项，并创建父级/子项回声循环。对于这种拥有的子项情况，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为完成路径已经负责处理结果。 + 只有当请求方是其自己父级拥有的一次性 ACP 子级的父级时，OpenClaw 才会跳过 A2A 后续路径。在这种情况下，在任务完成之上运行 A2A 可能会用子级结果唤醒父级，将父级的回复转发回子级，并创建父/子回声循环。对于这种被拥有的子级情况，`sessions_send` 结果会报告 + `delivery.status="skipped"`，因为完成路径已经负责返回结果。 - - 使用 `resumeSessionId` 继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其对话历史，因此会带着之前的完整上下文继续。 + + 使用 `resumeSessionId` 继续之前的 ACP 会话，而不是重新开始。智能体会通过 + `session/load` 重放其会话历史，因此会带着之前内容的完整上下文继续。 ```json { @@ -619,68 +642,70 @@ ACP 会话可以是交互式工作区，也可以是父级拥有的后台工作 常见用例： - - 将 Codex 会话从你的笔记本电脑交接到手机，让你的智能体从你离开的地方继续。 - - 继续你之前在 CLI 中交互式启动的编码会话，现在通过你的智能体无头运行。 - - 接续因 Gateway 网关重启或空闲超时而中断的工作。 + - 将 Codex 会话从你的笔记本电脑交接到你的手机：告诉你的智能体从你离开的地方继续。 + - 继续你在 CLI 中交互式启动的编码会话，现在通过你的智能体以无头方式进行。 + - 接手因 gateway 重启或空闲超时而中断的工作。 注意： - - `resumeSessionId` 仅在 `runtime: "acp"` 时适用；默认子智能体运行时会忽略这个仅限 ACP 的字段。 - - `streamTo` 仅在 `runtime: "acp"` 时适用；默认子智能体运行时会忽略这个仅限 ACP 的字段。 - - `resumeSessionId` 是主机本地 ACP/执行框架恢复 ID，而不是 OpenClaw 渠道会话键；OpenClaw 在分发前仍会检查 ACP 生成策略和目标智能体策略，而 ACP 后端或执行框架负责加载该上游 ID 的授权。 - - `resumeSessionId` 会恢复上游 ACP 对话历史；`thread` 和 `mode` 仍会正常应用到你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍需要 `thread: true`。 + - `resumeSessionId` 仅在 `runtime: "acp"` 时适用；默认子智能体运行时会忽略这个仅 ACP 字段。 + - `streamTo` 仅在 `runtime: "acp"` 时适用；默认子智能体运行时会忽略这个仅 ACP 字段。 + - `resumeSessionId` 是主机本地 ACP/harness 恢复 ID，不是 OpenClaw 渠道会话键；OpenClaw 在派发前仍会检查 ACP spawn 策略和目标智能体策略，而 ACP 后端或 harness 负责加载该上游 ID 的授权。 + - `resumeSessionId` 会恢复上游 ACP 会话历史；`thread` 和 `mode` 仍然会正常应用到你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然需要 `thread: true`。 - 目标智能体必须支持 `session/load`（Codex 和 Claude Code 支持）。 - - 如果找不到会话 ID，生成会以清晰错误失败，不会静默回退到新会话。 + - 如果找不到会话 ID，spawn 会以清晰错误失败，不会静默回退到新会话。 - - Gateway 网关部署后，请运行实时端到端检查，而不是仅信任单元测试： + + gateway 部署后，运行一次真实端到端检查，而不是信任单元测试： - 1. 验证目标主机上的已部署 Gateway 网关版本和提交。 - 2. 打开一个临时 ACPX 桥接会话连接到实时智能体。 + 1. 验证目标主机上的已部署 gateway 版本和提交。 + 2. 打开一个到真实智能体的临时 ACPX bridge 会话。 3. 要求该智能体调用 `sessions_spawn`，并使用 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，以及任务 `Reply with exactly LIVE-ACP-SPAWN-OK`。 - 4. 验证 `accepted=yes`、真实的 `childSessionKey`，且没有验证器错误。 - 5. 清理临时桥接会话。 + 4. 验证 `accepted=yes`、真实的 `childSessionKey`，并且没有验证器错误。 + 5. 清理临时 bridge 会话。 - 将门禁保持在 `mode: "run"`，并跳过 `streamTo: "parent"`，线程绑定的 `mode: "session"` 和流中继路径是独立的、更丰富的集成检查。 + 将 gate 保持在 `mode: "run"`，并跳过 `streamTo: "parent"`，因为线程绑定的 + `mode: "session"` 和流中继路径是单独的、更丰富的集成检查。 ## 沙箱兼容性 -ACP 会话目前运行在主机运行时上，**不**在 OpenClaw 沙箱内运行。 +ACP 会话当前运行在主机运行时上，**不**在 OpenClaw 沙箱内运行。 **安全边界：** -- 外部执行框架可以按照自己的 CLI 权限和所选 `cwd` 读写。 -- OpenClaw 的沙箱策略**不会**包装 ACP 执行框架执行。 -- OpenClaw 仍会强制执行 ACP 功能门禁、允许的智能体、会话所有权、渠道绑定和 Gateway 网关交付策略。 -- 对于由沙箱强制执行的 OpenClaw 原生工作，请使用 `runtime: "subagent"`。 +- 外部执行框架可以根据其自身 CLI 权限和所选 `cwd` 进行读写。 +- OpenClaw 的沙箱策略**不会**包裹 ACP 执行框架的执行。 +- OpenClaw 仍会强制执行 ACP 功能门控、允许的智能体、会话所有权、渠道绑定和 Gateway 网关投递策略。 +- 对需要强制沙箱的 OpenClaw 原生工作，请使用 `runtime: "subagent"`。 当前限制： -- 如果请求方会话处于沙箱隔离状态，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 生成都会被阻止。 -- 使用 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。 +- 如果请求方会话是沙箱隔离的，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 派生都会被阻止。 +- 带有 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。 ## 会话目标解析 -大多数 `/acp` 操作接受可选会话目标（`session-key`、`session-id` 或 `session-label`）。 +大多数 `/acp` 操作都接受可选的会话目标（`session-key`、 +`session-id` 或 `session-label`）。 **解析顺序：** -1. 显式目标参数（或用于 `/acp steer` 的 `--session`） - - 先尝试键名 - - 再尝试 UUID 形式的会话 ID - - 再尝试标签 -2. 当前线程绑定（如果此对话/线程绑定到 ACP 会话）。 -3. 当前请求者会话回退。 +1. 显式目标参数（或 `/acp steer` 的 `--session`） + - 尝试键 + - 然后尝试 UUID 形状的会话 ID + - 然后尝试标签 +2. 当前线程绑定（如果此对话/线程已绑定到 ACP 会话）。 +3. 当前请求方会话回退。 -当前对话绑定和线程绑定都会参与 -步骤 2。 +当前对话绑定和线程绑定都参与 +第 2 步。 如果没有解析出目标，OpenClaw 会返回清晰的错误 （`Unable to resolve session target: ...`）。 @@ -691,78 +716,77 @@ ACP 会话目前运行在主机运行时上，**不**在 OpenClaw 沙箱内运 | -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- | | `/acp spawn` | 创建 ACP 会话；可选当前绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` | | `/acp cancel` | 取消目标会话中正在进行的轮次。 | `/acp cancel agent:codex:acp:` | -| `/acp steer` | 向正在运行的会话发送引导指令。 | `/acp steer --session support inbox prioritize failing tests` | +| `/acp steer` | 向运行中的会话发送引导指令。 | `/acp steer --session support inbox prioritize failing tests` | | `/acp close` | 关闭会话并解除线程目标绑定。 | `/acp close` | | `/acp status` | 显示后端、模式、状态、运行时选项和能力。 | `/acp status` | -| `/acp set-mode` | 为目标会话设置运行时模式。 | `/acp set-mode plan` | +| `/acp set-mode` | 设置目标会话的运行时模式。 | `/acp set-mode plan` | | `/acp set` | 写入通用运行时配置选项。 | `/acp set model openai/gpt-5.4` | -| `/acp cwd` | 设置运行时工作目录覆盖。 | `/acp cwd /Users/user/Projects/repo` | +| `/acp cwd` | 设置运行时工作目录覆盖值。 | `/acp cwd /Users/user/Projects/repo` | | `/acp permissions` | 设置审批策略配置文件。 | `/acp permissions strict` | | `/acp timeout` | 设置运行时超时（秒）。 | `/acp timeout 120` | -| `/acp model` | 设置运行时模型覆盖。 | `/acp model anthropic/claude-opus-4-6` | -| `/acp reset-options` | 移除会话运行时选项覆盖。 | `/acp reset-options` | +| `/acp model` | 设置运行时模型覆盖值。 | `/acp model anthropic/claude-opus-4-6` | +| `/acp reset-options` | 移除会话运行时选项覆盖值。 | `/acp reset-options` | | `/acp sessions` | 从存储中列出最近的 ACP 会话。 | `/acp sessions` | -| `/acp doctor` | 后端健康状态、能力和可执行修复建议。 | `/acp doctor` | +| `/acp doctor` | 后端健康状况、能力和可操作修复。 | `/acp doctor` | | `/acp install` | 打印确定性的安装和启用步骤。 | `/acp install` | -`/acp status` 显示有效的运行时选项，以及运行时级别和 -后端级别的会话标识符。当后端缺少某项能力时，不支持的控制错误会 -清晰呈现。`/acp sessions` 会读取当前绑定会话或请求者会话的 -存储；目标令牌 -（`session-key`、`session-id` 或 `session-label`）会通过 -Gateway 网关会话发现进行解析，包括自定义的按智能体 `session.store` +`/acp status` 会显示有效的运行时选项，以及运行时级别和 +后端级别的会话标识符。当某个后端缺少能力时，不受支持的控制错误会 +清晰显示。`/acp sessions` 会读取当前绑定会话或请求方会话的 +存储；目标令牌（`session-key`、`session-id` 或 `session-label`）会通过 +Gateway 网关会话发现进行解析，包括每个智能体自定义的 `session.store` 根目录。 ### 运行时选项映射 -`/acp` 提供便捷命令和通用设置器。等价 +`/acp` 提供便捷命令和通用设置器。等效 操作： -| 命令 | 映射到 | 备注 | -| ---------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/acp model ` | 运行时配置键 `model` | 对于 Codex ACP，OpenClaw 会将 `openai-codex/` 规范化为适配器模型 ID，并将诸如 `openai-codex/gpt-5.4/high` 的斜杠 reasoning 后缀映射到 `reasoning_effort`。 | -| `/acp set thinking ` | 运行时配置键 `thinking` | 对于 Codex ACP，OpenClaw 会在适配器支持时发送对应的 `reasoning_effort`。 | -| `/acp permissions ` | 运行时配置键 `approval_policy` | — | -| `/acp timeout ` | 运行时配置键 `timeout` | — | -| `/acp cwd ` | 运行时 cwd 覆盖 | 直接更新。 | -| `/acp set ` | 通用 | `key=cwd` 使用 cwd 覆盖路径。 | -| `/acp reset-options` | 清除所有运行时覆盖 | — | +| 命令 | 映射到 | 备注 | +| ---------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/acp model ` | 运行时配置键 `model` | 对于 Codex ACP，OpenClaw 会将 `openai-codex/` 规范化为适配器模型 ID，并将斜杠推理后缀（如 `openai-codex/gpt-5.4/high`）映射到 `reasoning_effort`。 | +| `/acp set thinking ` | 运行时配置键 `thinking` | 对于 Codex ACP，在适配器支持时，OpenClaw 会发送对应的 `reasoning_effort`。 | +| `/acp permissions ` | 运行时配置键 `approval_policy` | — | +| `/acp timeout ` | 运行时配置键 `timeout` | — | +| `/acp cwd ` | 运行时 cwd 覆盖值 | 直接更新。 | +| `/acp set ` | 通用 | `key=cwd` 使用 cwd 覆盖路径。 | +| `/acp reset-options` | 清除所有运行时覆盖值 | — | -## acpx harness、插件设置和权限 +## acpx 执行框架、插件设置和权限 -有关 acpx harness 配置（Claude Code / Codex / Gemini CLI -别名）、plugin-tools 和 OpenClaw-tools MCP bridge，以及 ACP +关于 acpx 执行框架配置（Claude Code / Codex / Gemini CLI +别名）、plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP 权限模式，请参阅 -[ACP agents — 设置](/zh-CN/tools/acp-agents-setup)。 +[ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)。 ## 故障排除 -| 症状 | 可能原因 | 修复 | +| 现象 | 可能原因 | 解决方法 | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ACP runtime backend is not configured` | 后端插件缺失、已禁用，或被 `plugins.allow` 阻止。 | 安装并启用后端插件；当设置了该允许列表时，在 `plugins.allow` 中包含 `acpx`，然后运行 `/acp doctor`。 | -| `ACP is disabled by policy (acp.enabled=false)` | ACP 已全局禁用。 | 设置 `acp.enabled=true`。 | -| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 已禁用从普通线程消息自动调度。 | 设置 `acp.dispatch.enabled=true` 以恢复自动线程路由；显式的 `sessions_spawn({ runtime: "acp" })` 调用仍然可用。 | -| `ACP agent "" is not allowed by policy` | 智能体不在允许列表中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 | -| `/acp doctor` reports backend not ready right after startup | 插件依赖探测或自修复仍在运行。 | 稍等片刻后重新运行 `/acp doctor`；如果仍不健康，请检查后端安装错误以及插件允许/拒绝策略。 | -| Harness command not found | 适配器 CLI 未安装、暂存的插件依赖缺失，或非 Codex 适配器的首次运行 `npx` 拉取失败。 | 运行 `/acp doctor`，修复插件依赖，在 Gateway 网关主机上安装/预热适配器，或显式配置 acpx 智能体命令。 | -| Model-not-found from the harness | 模型 ID 对另一个提供商/harness 有效，但对此 ACP 目标无效。 | 使用该 harness 列出的模型，在 harness 中配置模型，或省略覆盖项。 | -| Vendor auth error from the harness | OpenClaw 状态正常，但目标 CLI/提供商未登录。 | 在 Gateway 网关主机环境中登录，或提供所需的提供商密钥。 | -| `Unable to resolve session target: ...` | 键/ID/标签令牌错误。 | 运行 `/acp sessions`，复制准确的键/标签，然后重试。 | -| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动可绑定对话的情况下使用了 `--bind here`。 | 移动到目标聊天/渠道后重试，或使用未绑定的生成。 | -| `Conversation bindings are unavailable for .` | 适配器缺少当前对话 ACP 绑定能力。 | 在受支持的位置使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或移动到受支持的渠道。 | -| `--thread here requires running /acp spawn inside an active ... thread` | 在非线程上下文中使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 | -| `Only can rebind this channel/conversation/thread.` | 另一个用户拥有活动绑定目标。 | 以所有者身份重新绑定，或使用其他对话或线程。 | -| `Thread bindings are unavailable for .` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或移动到受支持的适配器/渠道。 | -| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于主机侧；请求方会话已沙箱隔离。 | 从沙箱隔离会话使用 `runtime="subagent"`，或从非沙箱隔离会话运行 ACP 生成。 | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对必需的沙箱隔离使用 `runtime="subagent"`，或从非沙箱隔离会话使用带 `sandbox="inherit"` 的 ACP。 | -| `Cannot apply --model ... did not advertise model support` | 目标 harness 未暴露通用 ACP 模型切换。 | 使用声明 ACP `models`/`session/set_model` 的 harness，使用 Codex ACP 模型引用，或如果该 harness 有自己的启动标志，则直接在其中配置模型。 | -| Missing ACP metadata for bound session | ACP 会话元数据已过期/已删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 | -| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 阻止非交互式 ACP 会话中的写入/执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。请参阅[权限配置](/zh-CN/tools/acp-agents-setup#permission-configuration)。 | -| ACP session fails early with little output | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。对于完整权限，设置 `permissionMode=approve-all`；对于优雅降级，设置 `nonInteractivePermissions=deny`。 | -| ACP session stalls indefinitely after completing work | Harness 进程已完成，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动终止过期进程。 | -| Harness sees `<<>>` | 内部事件信封泄漏跨过了 ACP 边界。 | 更新 OpenClaw 并重新运行完成流程；外部 harness 应只接收纯完成提示。 | +| `ACP runtime backend is not configured` | 后端插件缺失、已禁用，或被 `plugins.allow` 阻止。 | 安装并启用后端插件；设置该允许列表时，在 `plugins.allow` 中包含 `acpx`，然后运行 `/acp doctor`。 | +| `ACP is disabled by policy (acp.enabled=false)` | ACP 已全局禁用。 | 设置 `acp.enabled=true`。 | +| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 来自普通线程消息的自动分发已禁用。 | 设置 `acp.dispatch.enabled=true` 以恢复自动线程路由；显式 `sessions_spawn({ runtime: "acp" })` 调用仍可工作。 | +| `ACP agent "" is not allowed by policy` | 智能体不在允许列表中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 | +| `/acp doctor` reports backend not ready right after startup | 插件依赖探测或自我修复仍在运行。 | 稍等片刻并重新运行 `/acp doctor`；如果仍不健康，请检查后端安装错误和插件允许/拒绝策略。 | +| Harness 命令未找到 | 适配器 CLI 未安装、暂存的插件依赖缺失，或非 Codex 适配器的首次运行 `npx` 拉取失败。 | 运行 `/acp doctor`，修复插件依赖，在 Gateway 网关主机上安装/预热适配器，或显式配置 acpx 智能体命令。 | +| Harness 返回模型未找到 | 模型 ID 对另一个提供商/harness 有效，但对此 ACP 目标无效。 | 使用该 harness 列出的模型，在 harness 中配置模型，或省略覆盖项。 | +| Harness 返回厂商认证错误 | OpenClaw 运行正常，但目标 CLI/提供商未登录。 | 在 Gateway 网关主机环境中登录或提供所需的提供商密钥。 | +| `Unable to resolve session target: ...` | 错误的键/ID/标签令牌。 | 运行 `/acp sessions`，复制精确的键/标签，然后重试。 | +| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动的可绑定对话时使用了 `--bind here`。 | 移动到目标聊天/渠道并重试，或使用未绑定的生成。 | +| `Conversation bindings are unavailable for .` | 适配器缺少当前对话 ACP 绑定能力。 | 在支持的情况下使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或移动到受支持的渠道。 | +| `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文之外使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 | +| `Only can rebind this channel/conversation/thread.` | 另一个用户拥有活动绑定目标。 | 以所有者身份重新绑定，或使用其他对话或线程。 | +| `Thread bindings are unavailable for .` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或移动到受支持的适配器/渠道。 | +| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于主机端；请求方会话处于沙箱隔离。 | 从沙箱隔离会话使用 `runtime="subagent"`，或从非沙箱隔离会话运行 ACP 生成。 | +| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对需要的沙箱隔离使用 `runtime="subagent"`，或从非沙箱隔离会话使用带 `sandbox="inherit"` 的 ACP。 | +| `Cannot apply --model ... did not advertise model support` | 目标 harness 未公开通用 ACP 模型切换。 | 使用公告 ACP `models`/`session/set_model` 的 harness，使用 Codex ACP 模型引用，或在该 harness 有自己的启动标志时直接在其中配置模型。 | +| 绑定会话缺少 ACP 元数据 | 过期/已删除的 ACP 会话元数据。 | 使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。 | +| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互式 ACP 会话中阻止写入/执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all`，并重启 Gateway 网关。参见[权限配置](/zh-CN/tools/acp-agents-setup#permission-configuration)。 | +| ACP 会话过早失败且输出很少 | 权限提示被 `permissionMode`/`nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。如需完整权限，设置 `permissionMode=approve-all`；如需优雅降级，设置 `nonInteractivePermissions=deny`。 | +| ACP 会话完成工作后无限期停滞 | Harness 进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动终止过期进程。 | +| Harness 看到 `<<>>` | 内部事件封套泄漏到了 ACP 边界之外。 | 更新 OpenClaw 并重新运行完成流程；外部 harness 应该只接收普通的完成提示。 | -## 相关内容 +## 相关 - [ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup) - [智能体发送](/zh-CN/tools/agent-send)