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

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-29 03:47:00 +00:00
parent 4467c25334
commit 7a3e829ae8
4 changed files with 804 additions and 830 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,49 +1,49 @@
---
read_when:
- 查看正在进行或最近完成的后台工作
- 调试分离式智能体运行的投递失败
- 检查正在进行或最近完成的后台工作
- 调试分离式智能体运行的交付失败
- 了解后台运行与会话、cron 和心跳的关系
sidebarTitle: Background tasks
summary: 用于 ACP 运行、子智能体、隔离的 cron 作业和 CLI 操作的后台任务跟踪
summary: 用于跟踪 ACP 运行、子智能体、隔离的 cron 作业和 CLI 操作的后台任务
title: 后台任务
x-i18n:
generated_at: "2026-04-28T20:08:43Z"
generated_at: "2026-04-29T03:44:27Z"
model: gpt-5.5
provider: openai
source_hash: ff4f22f98148b01c1b044a5213a5946eac8c5d763f0d22c992e6a4a2297bc308
source_hash: 4bbf74f3aeea532738b56b83cd2e1a0a3734bfd453da6636b8be985a28ccc027
source_path: automation/tasks.md
workflow: 16
---
<Note>
在查找调度功能？请参阅 [自动化和任务](/zh-CN/automation) 以选择合适的机制。本页是后台工作的活动台账，而不是调度器。
正在寻找调度功能？请参见 [自动化和任务](/zh-CN/automation) 以选择合适机制。本页是后台工作的活动台账，不是调度器。
</Note>
后台任务跟踪**主对话会话之外**运行的工作：ACP 运行、子智能体生成、隔离的 cron 作业执行，以及 CLI 发起的操作。
后台任务跟踪在**主对话会话之外**运行的工作：ACP 运行、子智能体派生、隔离的 cron 作业执行，以及由 CLI 发起的操作。
任务**不会**取代会话、cron 作业或心跳；它们是记录分离工作发生了什么、何时发生以及是否成功的**活动台账**。
任务**不会**取代会话、cron 作业或心跳，它们是记录脱离式工作发生了什么、何时发生以及是否成功的**活动台账**。
<Note>
并非每次智能体运行都会创建任务。心跳轮次和普通交互式聊天不会。所有 cron 执行、ACP 生成、子智能体生成和 CLI 智能体命令都会创建任务。
并非每次智能体运行都会创建任务。心跳轮次和普通交互式聊天不会创建任务。所有 cron 执行、ACP 派生、子智能体派生和 CLI 智能体命令都会创建任务。
</Note>
## 摘要
## 要点速览
- 任务是**记录**，不是调度器；cron 和心跳决定工作在_何时_运行，任务跟踪_发生了什么_。
- 任务是**记录**，不是调度器；cron 和心跳决定工作_何时_运行，任务跟踪_发生了什么_。
- ACP、子智能体、所有 cron 作业和 CLI 操作都会创建任务。心跳轮次不会。
- 每个任务都会经历 `queued → running → terminal`（succeeded、failed、timed_out、cancelled 或 lost）。
- 只要 cron 运行时仍然拥有该作业，cron 任务就会保持活动；如果内存中的运行时状态已消失，任务维护会先检查持久化 cron 运行历史，然后才将任务标记为 lost。
- 完成由推送驱动：分离工作完成时可以直接通知，或唤醒请求方会话/心跳，因此状态轮询循环通常不是合适的形态。
- 隔离的 cron 运行和子智能体完成会尽力为其子会话清理已跟踪的浏览器标签页/进程，然后再进行最终清理记账。
- 当后代子智能体工作仍在排空时，隔离的 cron 送达会抑制过时的中间父级回复，并且如果最终后代输出在送达前到达，则优先使用该输出。
- 完成通知会直接送达到渠道，或排队等待下一次心跳。
- `openclaw tasks list` 显示所有任务；`openclaw tasks audit` 暴露问题。
- 每个任务都会经过 `queued → running → terminal`（succeeded、failed、timed_out、cancelled 或 lost）。
- 当 cron 运行时仍拥有作业时，cron 任务会保持活动状态；如果内存中的运行时状态已消失，任务维护会先检查持久化的 cron 运行历史，再将任务标记为 lost。
- 完成由推送驱动：脱离式工作完成时可以直接通知，或唤醒请求方会话/心跳，因此状态轮询循环通常不是合适的形态。
- 隔离的 cron 运行和子智能体完成会尽力清理其子会话中受跟踪的浏览器标签页/进程，然后再进行最终清理记账。
- 当后代子智能体工作仍在收尾时，隔离的 cron 投递会抑制过时的中间父级回复；如果最终后代输出在投递前到达，它会优先使用该输出。
- 完成通知会直接投递到渠道，或排队等待下一次心跳。
- `openclaw tasks list` 显示所有任务；`openclaw tasks audit` 会暴露问题。
- 终态记录会保留 7 天，然后自动清理。
## 快速开始
<Tabs>
<Tab title="列出和筛选">
<Tab title="列出和过滤">
```bash
# List all tasks (newest first)
openclaw tasks list
@ -81,7 +81,7 @@ x-i18n:
```
</Tab>
<Tab title="任务流程">
<Tab title="任务流">
```bash
# Inspect TaskFlow state
openclaw tasks flow list
@ -93,26 +93,26 @@ 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` |
<AccordionGroup>
<Accordion title="cron 和媒体的默认通知设置">
主会话 cron 任务默认使用 `silent` 通知策略：它们会创建记录用于跟踪，但不会生成通知。隔离的 cron 任务也默认使用 `silent`，但因为它们在自己的会话中运行，所以更容易看到。
<Accordion title="cron 和媒体的默认通知">
主会话 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` 完成会先尝试直接投递到渠道，然后再回退到请求方会话唤醒路径。
</Accordion>
<Accordion title="并发 video_generate 保护机制">
当由会话支撑的 `video_generate` 任务仍处于活动状态时，该工具也会作为保护机制：同一会话中重复的 `video_generate` 调用会返回活动任务状态，而不是启动第二个并发生成。需要从智能体侧显式查询进度/状态时，请使用 `action: "status"`。
<Accordion title="并发 video_generate 护栏">
当基于会话的 `video_generate` 任务仍处于活动状态时，该工具也会充当护栏：同一会话中重复的 `video_generate` 调用会返回活动任务状态，而不是启动第二个并发生成。需要从智能体侧显式查询进度/状态时，请使用 `action: "status"`。
</Accordion>
<Accordion title="哪些不会创建任务">
- 心跳轮次：主会话；参见 [心跳](/zh-CN/gateway/heartbeat)
<Accordion title="什么不会创建任务">
- 心跳轮次；主会话；参见 [心跳](/zh-CN/gateway/heartbeat)
- 普通交互式聊天轮次
- 直接 `/command` 响应
@ -133,52 +133,52 @@ stateDiagram-v2
running --> lost : session gone > 5 min
```
| Status | 含义 |
| 状态 | 含义 |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | 已创建，正在等待智能体启动 |
| `running` | 智能体轮次正在主动执行 |
| `succeeded` | 已成功完成 |
| `failed` | 已完成但出现错误 |
| `timed_out` | 超过配置的超时时间 |
| `cancelled` | 操作员通过 `openclaw tasks cancel` 停止 |
| `failed` | 已完成但发生错误 |
| `timed_out` | 超出配置的超时时间 |
| `cancelled` | 操作者通过 `openclaw tasks cancel` 停止 |
| `lost` | 运行时在 5 分钟宽限期后丢失了权威支撑状态 |
转换会自动发生；当关联的智能体运行结束时，任务状态会更新为匹配的状态。
状态转换会自动发生；当关联的智能体运行结束时，任务状态会更新为匹配的状态。
智能体运行完成是活动任务记录的权威依据。成功的分离运行会最终记为 `succeeded`，普通运行错误会最终记为 `failed`，超时或中止结果会最终记为 `timed_out`。如果操作员已经取消该任务，或者运行时已经记录了更强的终态，例如 `failed`、`timed_out` 或 `lost`，后续的成功信号不会降级该终态。
对于活动任务记录，智能体运行完成结果具有权威性。成功的脱离式运行会最终确定为 `succeeded`，普通运行错误会最终确定为 `failed`，超时或中止结果会最终确定为 `timed_out`。如果操作者已经取消任务，或者运行时已经记录了更强的终态（例如 `failed`、`timed_out` 或 `lost`），之后到达的成功信号不会下调该终态状态。
`lost` 具有运行时感知能力：
- ACP 任务：支撑的 ACP 子会话元数据已消失。
- 子智能体任务：支撑的子会话已从目标智能体存储中消失。
- Cron 任务：cron 运行时不再将该作业跟踪为活动状态，并且持久化 cron 运行历史未显示该运行的终态结果。离线 CLI 审计不会将其自身空的进程内 cron 运行时状态视为权威依据。
- CLI 任务：隔离的子会话任务使用子会话；由聊天支撑的 CLI 任务改用实时运行上下文，因此残留的渠道/群组/私信会话行不会让它们保持活动。由 Gateway 网关支撑的 `openclaw agent` 运行也会根据其运行结果最终确定状态，因此已完成的运行不会一直保持活动，直到清理器将它们标记为 `lost`。
- 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` / 账号。
**会话排队送达**：如果直接送达失败或未设置来源，更新会作为系统事件排队到请求方会话中，并在下一次心跳时浮现。
**会话排队投递**：如果直接投递失败或未设置来源，更新会作为系统事件排入请求方会话，并在下一次心跳中呈现。
<Tip>
任务完成会触发一次即时心跳唤醒，因此你能快速看到结果；无需等待下一次计划的心跳节拍。
任务完成会触发一次即时心跳唤醒，让你快速看到结果；你不必等待下一次计划的心跳 tick。
</Tip>
这意味着常规工作流是推送式的：启动一次分离工作，然后让运行时在完成时唤醒或通知你。只有在需要调试、干预或显式审计时，才轮询任务状态。
这意味着常见工作流是基于推送的：启动一次脱离式工作，然后让运行时在完成时唤醒或通知你。只有在需要调试、干预或显式审计时，才轮询任务状态。
### 通知策略
控制你收到每个任务多少信息：
控制每个任务的通知详细程度：
| 策略 | 送达内容 |
| 策略 | 投递内容 |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only`（默认） | 仅终态（succeeded、failed 等）；**这是默认值** |
| `state_changes` | 每次状态转换和进度更新 |
| `silent` | 完全不送达 |
| `silent` | 完全不通知 |
在任务运行时更改策略：
任务运行期间可更改策略：
```bash
openclaw tasks notify <lookup> state_changes
@ -192,7 +192,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
输出列：任务 ID、类别、Status、送达、运行 ID、子会话、摘要。
输出列：任务 ID、种类、状态、投递、运行 ID、子会话、摘要。
</Accordion>
<Accordion title="tasks show">
@ -200,7 +200,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks show <lookup>
```
查询标记接受任务 ID、运行 ID 或会话键。显示完整记录，包括时序、送达状态、错误和终态摘要。
查找令牌接受任务 ID、运行 ID 或会话键。显示完整记录，包括计时、投递状态、错误和终态摘要。
</Accordion>
<Accordion title="tasks cancel">
@ -208,7 +208,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
对于 ACP 和子智能体任务，这会终止子会话。对于由 CLI 跟踪的任务，取消操作会记录在任务注册表中（没有单独的子运行时句柄）。Status 会转换为 `cancelled`，并在适用时发送送达通知。
对于 ACP 和子智能体任务，这会杀掉子会话。对于由 CLI 跟踪的任务，取消操作会记录在任务注册表中（没有单独的子运行时句柄）。状态转换为 `cancelled`，并在适用时发送投递通知。
</Accordion>
<Accordion title="tasks notify">
@ -221,139 +221,139 @@ openclaw tasks notify <lookup> 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` |
| `missing_cleanup` | warn | 终止任务没有清理时间戳 |
| `inconsistent_timestamps` | warn | 时间线违规（例如结束早于开始） |
| `stale_queued` | 警告 | 排队超过 10 分钟 |
| `stale_running` | 错误 | 运行超过 30 分钟 |
| `lost` | 警告/错误 | 运行时支持的任务所有权消失；保留的丢失任务在 `cleanupAfter` 之前发出警告，之后变为错误 |
| `delivery_failed` | 警告 | 交付失败且通知策略不是 `silent` |
| `missing_cleanup` | 警告 | 终止任务没有清理时间戳 |
| `inconsistent_timestamps` | 警告 | 时间线违规（例如结束时间早于开始时间） |
</Accordion>
<Accordion title="任务维护">
<Accordion title="tasks maintenance">
```bash
openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
使用此命令可预览或应用针对任务和任务流状态的协调、清理标记和修剪。
用它来预览或应用任务和 Task Flow 状态的对账、清理标记和修剪。
协调会感知运行时：
对账会感知运行时：
- ACP/子智能体任务会检查其背后的子会话。
- Cron 任务会检查 cron 运行时是否仍拥有该作业，然后先从持久化的 cron 运行日志/作业状态恢复终止状态，再回退到 `lost`。只有 Gateway 网关进程对内存中的 cron 活动作业集合具有权威性；离线 CLI 审计会使用持久历史记录，但不会仅因为该本地 Set 为空就将 cron 任务标记为丢失。
- 由聊天支持的 CLI 任务会检查所属的实时运行上下文，而不只是聊天会话行。
- ACP/subagent 任务会检查其背后的子会话。
- Cron 任务会检查 cron 运行时是否仍拥有该作业，然后先从持久化的 cron 运行日志/作业状态恢复终止状态，再回退到 `lost`。只有 Gateway 网关进程对内存中的 cron 活动作业集具有权威性；离线 CLI 审计会使用持久化历史，但不会仅因为该本地 Set 为空就把 cron 任务标记为丢失。
- 聊天支持的 CLI 任务会检查所属的实时运行上下文，而不只是聊天会话行。
完成清理也会感知运行时：
- 子智能体完成后，会尽力在公告清理继续之前关闭为子会话跟踪的浏览器标签页/进程。
- 隔离 cron 完成后，会尽力在运行完全拆除前关闭为 cron 会话跟踪的浏览器标签页/进程。
- 隔离 cron 投递会在需要时等待后代子智能体的后续操作，并抑制过期的父级确认文本，而不是公告它。
- 子智能体完成投递优先使用最新可见的助手文本；如果为空，则回退到经过清理的最新工具/toolResult 文本；仅超时的工具调用运行可以折叠为简短的部分进度摘要。终止失败的运行会公告失败状态，而不会重放捕获的回复文本。
- Subagent 完成时会尽力关闭为子会话跟踪的浏览器标签页/进程，然后继续执行公告清理。
- 隔离的 cron 完成时会尽力关闭为 cron 会话跟踪的浏览器标签页/进程，然后运行才会完全拆除。
- 隔离的 cron 交付会在需要时等待后代 subagent 后续操作，并抑制陈旧的父级确认文本，而不是公告它。
- Subagent 完成交付优先使用最新可见的助手文本；如果为空，则回退到已清理的最新 tool/toolResult 文本，并且仅超时的工具调用运行可以折叠成简短的部分进度摘要。终止失败的运行会公告失败状态，而不会重放捕获到的回复文本。
- 清理失败不会掩盖真实的任务结果。
</Accordion>
<Accordion title="任务流列表 | 显示 | 取消">
<Accordion title="tasks flow list | show | cancel">
```bash
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
当你关心的是编排任务流，而不是某一条单独的后台任务记录时，请使用这些命令。
当你关注的是编排中的 Task Flow，而不是某一条后台任务记录时，请使用这些命令。
</Accordion>
</AccordionGroup>
## 聊天任务看板（`/tasks`）
在任意聊天会话中使用 `/tasks` 查看链接到该会话的后台任务。看板会显示活动任务和最近完成的任务，以及运行时、Status、计时、进度或错误详情。
在任何聊天会话中使用 `/tasks` 查看链接到该会话的后台任务。该看板会显示活跃任务和最近完成的任务，以及运行时、状态、时间信息、进度或错误详情。
当当前会话没有可见的链接任务时，`/tasks` 会回退到智能体本地任务计数，这样你仍能获得概览，而不会泄露其他会话的详情。
当当前会话没有可见的已链接任务时，`/tasks` 会回退到智能体本地任务计数，因此你仍能获得概览，同时不会泄露其他会话的详情。
要查看完整的操作员账本，请使用 CLI：`openclaw tasks list`。
如需完整的操作员账本，请使用 CLI：`openclaw tasks list`。
## Status 集成（任务压力）
`openclaw status` 包含一眼可见的任务摘要：
`openclaw status` 包含一目了然的任务摘要：
```
Tasks: 3 queued · 2 running · 1 issues
```
摘要报告：
该摘要会报告：
- **active** — `queued` + `running` 的数量
- **failures** — `failed` + `timed_out` + `lost` 的数量
- **byRuntime** — 按 `acp`、`subagent`、`cron`、`cli` 的明细
- **活跃** — `queued` + `running` 的数量
- **失败** — `failed` + `timed_out` + `lost` 的数量
- **按运行时** — 按 `acp`、`subagent`、`cron`、`cli` 分解
`/status` 和 `session_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 秒** 运行一次，处理四件事：
<Steps>
<Step title="协调">
检查活动任务是否仍有权威运行时支持。ACP/子智能体任务使用子会话状态，cron 任务使用活动作业所有权，由聊天支持的 CLI 任务使用所属运行上下文。如果该支持状态消失超过 5 分钟，任务会被标记为 `lost`。
<Step title="Reconciliation">
检查活跃任务是否仍有权威的运行时支持。ACP/subagent 任务使用子会话状态，cron 任务使用活动作业所有权，聊天支持的 CLI 任务使用所属的运行上下文。如果该支持状态消失超过 5 分钟，任务会被标记为 `lost`。
</Step>
<Step title="ACP 会话修复">
关闭终止的父级拥有的一次性 ACP 会话，并且仅在没有剩余活动对话绑定时关闭过期的终止持久 ACP 会话。
<Step title="ACP session repair">
关闭终止的或孤立的父级所有的一次性 ACP 会话，并且仅在没有剩余活跃对话绑定时，才关闭陈旧的终止或孤立持久 ACP 会话。
</Step>
<Step title="清理标记">
为终止任务设置 `cleanupAfter` 时间戳（endedAt + 7 天）。在保留期内，丢失任务仍会在审计中显示为警告；在 `cleanupAfter` 过期后，或当清理元数据缺失时，它们会变为错误。
<Step title="Cleanup stamping">
在终止任务上设置 `cleanupAfter` 时间戳（endedAt + 7 天）。在保留期内，丢失任务仍会在审计中显示为警告；`cleanupAfter` 过期后，或清理元数据缺失时，它们会成为错误。
</Step>
<Step title="修剪">
<Step title="Pruning">
删除超过其 `cleanupAfter` 日期的记录。
</Step>
</Steps>
<Note>
**保留：** 终止任务记录会保留 **7 天**，然后自动修剪。无需配置。
**保留期：** 终止任务记录会保留 **7 天**，然后自动修剪。无需配置。
</Note>
## 任务与其他系统的关系
<AccordionGroup>
<Accordion title="任务和任务流">
[任务流](/zh-CN/automation/taskflow) 是后台任务之上的流程编排层。单个流程可能在其生命周期内使用托管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单条任务记录，使用 `openclaw tasks flow` 检查编排流程。
<Accordion title="Tasks and Task Flow">
[Task Flow](/zh-CN/automation/taskflow) 是后台任务之上的流程编排层。单个流程可以在其生命周期内使用托管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单个任务记录，使用 `openclaw tasks flow` 检查编排中的流程。
了解详情请参阅[任务流](/zh-CN/automation/taskflow)。
详情参见 [Task Flow](/zh-CN/automation/taskflow)。
</Accordion>
<Accordion title="任务和 cron">
cron 作业**定义**位于 `~/.openclaw/cron/jobs.json`；运行时执行状态位于旁边的 `~/.openclaw/cron/jobs-state.json`。**每次** cron 执行都会创建一条任务记录，包括主会话和隔离会话。主会话 cron 任务默认使用 `silent` 通知策略，因此它们只跟踪而不生成通知。
<Accordion title="Tasks and cron">
cron 作业**定义**位于 `~/.openclaw/cron/jobs.json`；运行时执行状态位于旁边的 `~/.openclaw/cron/jobs-state.json`。**每次** cron 执行都会创建一条任务记录，包括主会话和隔离会话。主会话 cron 任务默认使用 `silent` 通知策略，因此它们会被跟踪，但不会生成通知。
请参阅 [Cron 作业](/zh-CN/automation/cron-jobs)。
参见 [Cron 作业](/zh-CN/automation/cron-jobs)。
</Accordion>
<Accordion title="任务和心跳">
心跳运行属于主会话轮次，不会创建任务记录。任务完成时，它可以触发一次心跳唤醒，让你及时看到结果。
<Accordion title="Tasks and heartbeat">
Heartbeat 运行是主会话轮次，它们不会创建任务记录。任务完成时，可以触发一次 heartbeat 唤醒，让你及时看到结果。
请参阅[心跳](/zh-CN/gateway/heartbeat)。
参见 [Heartbeat](/zh-CN/gateway/heartbeat)。
</Accordion>
<Accordion title="任务和会话">
<Accordion title="Tasks and sessions">
任务可以引用 `childSessionKey`（工作运行的位置）和 `requesterSessionKey`（启动它的人）。会话是对话上下文；任务是在其之上的活动跟踪。
</Accordion>
<Accordion title="任务和智能体运行">
任务的 `runId` 会链接到执行工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务 Status，你不需要手动管理生命周期。
<Accordion title="Tasks and agent runs">
任务的 `runId` 会链接到执行工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务状态，你不需要手动管理生命周期。
</Accordion>
</AccordionGroup>
@ -361,6 +361,6 @@ Gateway 网关通过 SQLite 的默认自动检查点阈值，以及周期性和
- [自动化与任务](/zh-CN/automation) — 所有自动化机制一览
- [CLI：任务](/zh-CN/cli/tasks) — CLI 命令参考
- [心跳](/zh-CN/gateway/heartbeat) — 周期性主会话轮次
- [计划任务](/zh-CN/automation/cron-jobs) — 调度后台工作
- [任务流](/zh-CN/automation/taskflow) — 任务之上的流程编排
- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性主会话轮次
- [定时任务](/zh-CN/automation/cron-jobs) — 调度后台工作
- [Task Flow](/zh-CN/automation/taskflow) — 任务之上的流程编排

558
docs/zh-CN/plugins/architecture-internals.md
View File

@ -3,25 +3,25 @@ read_when:
- 实现提供商运行时钩子、渠道生命周期或包集合
- 调试插件加载顺序或注册表状态
- 添加新的插件能力或上下文引擎插件
summary: 插件架构内部机制：加载管线、注册表、运行时钩子、HTTP 路由和参考表
summary: 插件架构内部机制：加载流水线、注册表、运行时钩子、HTTP 路由和参考表
title: 插件架构内部机制
x-i18n:
generated_at: "2026-04-29T03:28:37Z"
generated_at: "2026-04-29T03:44:32Z"
model: gpt-5.5
provider: openai
source_hash: 24f6b5d20bbd7f0f33e8e6bcbd9b0769e7e7c335530e19c4b85f60cb3b5b070e
source_hash: a598de14ca67d4ef08093a4e6ce65ade18e1c427fca9b3edfce218f847915850
source_path: plugins/architecture-internals.md
workflow: 16
---
有关公共能力模型、插件形态以及所有权/执行契约，请参阅[插件架构](/zh-CN/plugins/architecture)。本页是内部机制的参考：加载流水线、注册表、运行时钩子、Gateway 网关 HTTP 路由、导入路径和 schema 表。
对于公开的能力模型、插件形态和所有权/执行契约，请参阅[插件架构](/zh-CN/plugins/architecture)。本页是内部机制的参考：加载管线、注册表、运行时钩子、Gateway 网关 HTTP 路由、导入路径和 schema 表。
## 加载流水线
## 加载管线
启动时，OpenClaw 大致会执行以下操作：
1. 发现候选插件根目录
2. 读取原生或兼容 bundle manifest 以及 package 元数据
2. 读取原生或兼容 bundle 清单和 package 元数据
3. 拒绝不安全的候选项
4. 规范化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、
`slots`、`load.paths`）
@ -29,71 +29,71 @@ x-i18n:
6. 加载已启用的原生模块：已构建的内置模块使用原生加载器；
未构建的原生插件使用 jiti
7. 调用原生 `register(api)` 钩子，并将注册项收集到插件注册表中
8. 将注册表暴露给命令/运行时界面
8. 将注册表暴露给命令/运行时表面
<Note>
`activate` 是 `register` 的旧版别名 — 加载器会解析存在的那个（`def.register ?? def.activate`），并在同一时点调用它。所有内置插件都使用 `register`；新插件请优先使用 `register`。
`activate` 是 `register` 的旧版别名 — 加载器会解析存在的那个（`def.register ?? def.activate`），并在同一位置调用它。所有内置插件都使用 `register`；新插件请优先使用 `register`。
</Note>
安全门控发生在运行时执行**之前**。当入口逃逸出插件根目录、路径可被全局写入，或非内置插件的路径所有权看起来可疑时，候选项会被阻止。
安全门禁发生在运行时执行**之前**。当入口逃逸出插件根目录、路径对所有用户可写，或非内置插件的路径所有权看起来可疑时，候选项会被阻止。
### Manifest 优先行为
### 清单优先行为
Manifest 是控制平面的事实来源。OpenClaw 使用它来：
清单是控制平面的事实来源。OpenClaw 使用它来：
- 识别插件
- 发现已声明的渠道/Skills/配置 schema 或 bundle 能力
- 发现声明的渠道/Skills/配置 schema 或 bundle 能力
- 验证 `plugins.entries.<id>.config`
- 补充 Control UI 标签/占位符
- 增强 Control UI 标签/占位符
- 显示安装/目录元数据
- 在不加载插件运行时的情况下保留轻量激活和设置描述符
- 在不加载插件运行时的情况下，保留低成本的激活和设置描述符
对于原生插件，运行时模块是数据平面部分。它注册实际行为，例如钩子、工具、命令或提供商流程。
对于原生插件，运行时模块是数据平面部分。它注册钩子、工具、命令或提供商流程等实际行为。
可选的 manifest `activation` 和 `setup` 块保留在控制平面上。它们是仅含元数据的描述符，用于激活规划和设置发现；它们不会取代运行时注册、`register(...)` 或 `setupEntry`。首批实时激活消费者现在使用 manifest 命令、渠道和提供商提示，在更广泛的注册表物化之前缩小插件加载范围：
可选的清单 `activation` 和 `setup` 块保留在控制平面上。它们是用于激活规划和设置发现的纯元数据描述符；它们不会替代运行时注册、`register(...)` 或 `setupEntry`。首批实时激活使用者现在会使用清单命令、渠道和提供商提示，在更广泛的注册表物化之前缩小插件加载范围：
- CLI 加载会缩小到拥有所请求主命令的插件
- 渠道设置/插件解析会缩小到拥有所请求渠道 id 的插件
- 显式提供商设置/运行时解析会缩小到拥有所请求提供商 id 的插件
- Gateway 网关启动规划会使用 `activation.onStartup` 处理显式启动导入和启动选择退出；随着 OpenClaw 摆脱隐式启动导入，每个插件都应声明它，而没有静态能力元数据且没有 `activation.onStartup` 的插件仍会使用已弃用的隐式启动 sidecar 回退以保持兼容
- 渠道设置/插件解析会缩小到拥有所请求渠道 ID 的插件
- 显式提供商设置/运行时解析会缩小到拥有所请求提供商 ID 的插件
- Gateway 网关启动规划使用 `activation.onStartup` 处理显式启动导入和启动退出；随着 OpenClaw 从隐式启动导入迁移，每个插件都应声明它，而没有静态能力元数据且没有 `activation.onStartup` 的插件，仍会为了兼容性使用已弃用的隐式启动辅助回退
激活规划器既为现有调用方暴露仅包含 id 的 API，也为新的诊断暴露计划 API。计划条目会报告插件被选中的原因，将显式 `activation.*` 规划器提示与 manifest 所有权回退区分开来，例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和钩子。这个原因拆分就是兼容边界：现有插件元数据会继续工作，而新代码可以检测宽泛提示或回退行为，而无需改变运行时加载语义。
激活规划器同时为现有调用方暴露仅含 ID 的 API，并为新的诊断暴露规划 API。规划条目会报告插件被选中的原因，将显式 `activation.*` 规划器提示与清单所有权回退（例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和钩子）分开。该原因拆分是兼容性边界：现有插件元数据继续工作，而新代码可以在不改变运行时加载语义的情况下检测宽泛提示或回退行为。
设置发现现在优先使用描述符拥有的 id，例如 `setup.providers` 和 `setup.cliBackends`，在回退到 `setup-api` 之前缩小候选插件范围，供那些仍需要设置时运行时钩子的插件使用。提供商设置列表会使用 manifest `providerAuthChoices`、描述符派生的设置选项和安装目录元数据，而不加载提供商运行时。显式 `setup.requiresRuntime: false` 是仅描述符的截止点；省略 `requiresRuntime` 会保留旧版 setup-api 回退以保持兼容。如果多个发现到的插件声明了同一个规范化后的设置提供商或 CLI 后端 id，设置查找会拒绝这个模糊所有者，而不是依赖发现顺序。当设置运行时确实执行时，注册表诊断会报告 `setup.providers` / `setup.cliBackends` 与 setup-api 注册的提供商或 CLI 后端之间的漂移，但不会阻止旧版插件。
设置发现现在优先使用描述符拥有的 ID（例如 `setup.providers` 和 `setup.cliBackends`）来缩小候选插件范围，然后才回退到面向仍需要设置时运行时钩子的插件的 `setup-api`。提供商设置列表会使用清单 `providerAuthChoices`、从描述符派生的设置选项，以及安装目录元数据，而无需加载提供商运行时。显式的 `setup.requiresRuntime: false` 是仅描述符的截止条件；省略 `requiresRuntime` 会保留旧版 `setup-api` 回退以保持兼容。如果多个已发现插件声明同一个规范化后的设置提供商或 CLI 后端 ID，设置查找会拒绝这个有歧义的所有者，而不是依赖发现顺序。当设置运行时确实执行时，注册表诊断会报告 `setup.providers` / `setup.cliBackends` 与由 setup-api 注册的提供商或 CLI 后端之间的偏差，但不会阻止旧版插件。
### 插件缓存边界
OpenClaw 不会在基于挂钟时间的窗口后面缓存插件发现结果或直接 manifest 注册表数据。安装、manifest 编辑和加载路径更改必须在下一次显式元数据读取或快照重建时可见。
OpenClaw 不会在基于墙钟时间的窗口后面缓存插件发现结果或直接清单注册表数据。安装、清单编辑和加载路径变更必须在下一次显式元数据读取或快照重建时可见。清单文件解析器可以保留一个有界的文件签名缓存，以打开的清单路径、inode、大小和时间戳为键；该缓存只用于避免重新解析未变化的字节，不得缓存发现、注册表、所有者或策略答案。
安全的元数据快速路径是显式对象所有权，而不是隐藏缓存。Gateway 网关启动热路径应通过调用链传递当前的 `PluginMetadataSnapshot`、派生的 `PluginLookUpTable` 或显式 manifest 注册表。配置验证、启动自动启用、插件引导和提供商选择可以复用这些对象，只要它们代表当前配置和插件清单。设置查找仍会按需重建 manifest 元数据，除非特定设置路径收到显式 manifest 注册表；请将其保留为冷路径回退，而不是添加隐藏查找缓存。当输入发生变化时，重建并替换快照，而不是修改它或保留历史副本。
活动插件注册表上的视图和内置渠道引导辅助函数应从当前注册表/根目录重新计算。短生命周期 map 可以在单次调用内用于去重工作或防止重入；它们不得变成进程元数据缓存。
安全的元数据快速路径是显式对象所有权，而不是隐藏缓存。Gateway 网关启动热路径应通过调用链传递当前的 `PluginMetadataSnapshot`、派生的 `PluginLookUpTable`，或显式清单注册表。配置验证、启动自动启用、插件引导和提供商选择可以复用这些对象，只要它们代表当前配置和插件清单。设置查找仍会按需重建清单元数据，除非特定设置路径接收到显式清单注册表；应将其保留为冷路径回退，而不是添加隐藏查找缓存。当输入发生变化时，应重建并替换快照，而不是修改它或保留历史副本。
应从当前注册表/根目录重新计算活动插件注册表上的视图和内置渠道引导助手。短生命周期的 map 可以在单次调用中用于去重工作或防止重入；它们不得变成进程元数据缓存。
对于插件加载，持久缓存层是运行时加载。当代码或已安装工件确实被加载时，它可以复用加载器状态，例如：
对于插件加载，持久缓存层是运行时加载。它可以在代码或已安装 artifact 实际加载时复用加载器状态，例如：
- `PluginLoaderCacheState` 和兼容的活动运行时注册表
- jiti/module 缓存和公共界面加载器缓存，用于避免重复导入同一个运行时界面
- 已安装插件工件的运行时依赖镜像和文件系统缓存
- 用于避免重复导入同一运行时表面的 jiti/模块缓存和公共表面加载器缓存
- 已安装插件 artifact 的运行时依赖镜像和文件系统缓存
- 用于路径规范化或重复解析的短生命周期按调用 map
这些缓存是数据平面实现细节。它们不得回答诸如“哪个插件拥有这个提供商？”之类的控制平面问题，除非调用方有意请求了运行时加载。
这些缓存是数据平面实现细节。除非调用方有意请求运行时加载，否则它们不得回答控制平面问题，例如“哪个插件拥有此提供商？”。
不要为以下内容添加持久缓存或挂钟时间缓存：
不要为以下内容添加持久缓存或基于墙钟时间的缓存：
- 发现结果
- 直接 manifest 注册表
- 从已安装插件索引重建的 manifest 注册表
- 提供商所有者查找、模型抑制、提供商策略或公共工件元数据
- 任何其他 manifest 派生答案，其中已更改的 manifest、已安装索引或加载路径应在下一次元数据读取时可见
- 直接清单注册表
- 从已安装插件索引重建的清单注册表
- 提供商所有者查找、模型抑制、提供商策略或公共 artifact 元数据
- 任何其他从清单派生的答案，其中变更后的清单、已安装索引或加载路径应在下一次元数据读取时可见
从持久化的已安装插件索引重建 manifest 元数据的调用方会按需重建该注册表。已安装索引是持久的源平面状态；它不是隐藏的进程内元数据缓存。
从持久化的已安装插件索引重建清单元数据的调用方，会按需重建该注册表。已安装索引是持久的来源平面状态；它不是隐藏的进程内元数据缓存。
## 注册表模型
已加载的插件不会直接修改任意核心全局变量。它们会注册到中央插件注册表中。
已加载的插件不会直接修改随机的核心全局变量。它们会注册到一个中央插件注册表中。
注册表会跟踪：
- 插件记录（身份、来源、原点、Status、诊断）
- 插件记录（身份、来源、源头、Status、诊断）
- 工具
- 旧版钩子和类型化钩子
- 渠道
@ -104,18 +104,18 @@ OpenClaw 不会在基于挂钟时间的窗口后面缓存插件发现结果或
- 后台服务
- 插件拥有的命令
然后，核心功能会从该注册表读取，而不是直接与插件模块通信。这让加载保持单向：
随后，核心功能会从该注册表读取，而不是直接与插件模块交互。这让加载保持单向：
- 插件模块 -> 注册表注册
- 核心运行时 -> 注册表消费
这种分离对可维护性很重要。这意味着大多数核心界面只需要一个集成点：“读取注册表”，而不是“为每个插件模块做特殊处理”。
这种分离对可维护性很重要。它意味着大多数核心表面只需要一个集成点：“读取注册表”，而不是“为每个插件模块做特殊处理”。
## 对话绑定回调
绑定对话的插件可以在审批被解析时作出响应。
绑定对话的插件可以在批准完成解析时做出反应。
使用 `api.onConversationBindingResolved(...)` 在绑定请求被批准或拒绝后接收回调：
使用 `api.onConversationBindingResolved(...)` 可在绑定请求被批准或拒绝后接收回调：
```ts
export default {
@ -140,86 +140,84 @@ export default {
- `status`：`"approved"` 或 `"denied"`
- `decision`：`"allow-once"`、`"allow-always"` 或 `"deny"`
- `binding`：已批准请求的已解析绑定
- `request`：原始请求摘要、分离提示、发送方 id 和对话元数据
- `request`：原始请求摘要、分离提示、发送方 ID 和对话元数据
此回调仅用于通知。它不会改变谁被允许绑定对话，并且会在核心审批处理完成后运行。
此回调仅用于通知。它不会更改谁被允许绑定对话，并且会在核心批准处理完成后运行。
## 提供商运行时钩子
提供商插件有三层：
- **Manifest 元数据**，用于轻量的运行时前查找：
- **清单元数据**，用于低成本的运行时前查找：
`setup.providers[].envVars`、已弃用的兼容性 `providerAuthEnvVars`、
`providerAuthAliases`、`providerAuthChoices` 和 `channelEnvVars`。
- **配置时钩子**：`catalog`（旧版 `discovery`）加上
- **配置时钩子**：`catalog`（旧版 `discovery`）以及
`applyConfigDefaults`。
- **运行时钩子**：40 多个可选钩子，覆盖凭证、模型解析、
流包装、思考等级、重放策略和用量端点。请参阅
[钩子顺序和用法](#hook-order-and-usage)下的完整列表。
- **运行时钩子**：40 多个可选钩子，涵盖认证、模型解析、流包装、思考等级、重放策略和用量端点。完整列表见[钩子顺序和用法](#hook-order-and-usage)。
OpenClaw 仍拥有通用 Agent loop、故障转移、转录处理和工具策略。这些钩子是提供商特定行为的扩展界面，不需要完整的自定义推理传输。
OpenClaw 仍然拥有通用 Agent loop、故障转移、转录处理和工具策略。这些钩子是用于提供商特定行为的扩展表面，无需完整的自定义推理传输。
当提供商具有基于环境变量的凭证，并且通用凭证/Status/模型选择器路径应在不加载插件运行时的情况下看到这些凭证时，请使用 manifest `setup.providers[].envVars`。已弃用的 `providerAuthEnvVars` 在弃用窗口期间仍会由兼容性适配器读取，使用它的非内置插件会收到 manifest 诊断。当一个提供商 id 应复用另一个提供商 id 的环境变量、凭证配置文件、配置支持的凭证和 API 密钥新手引导选项时，请使用 manifest `providerAuthAliases`。当新手引导/凭证选择 CLI 界面应在不加载提供商运行时的情况下了解提供商的选项 id、分组标签和简单的单标志凭证接线时，请使用 manifest `providerAuthChoices`。将提供商运行时 `envVars` 保留给面向操作者的提示，例如新手引导标签或 OAuth client-id/client-secret 设置变量。
当提供商拥有基于环境的凭证，并且通用认证/Status/模型选择器路径应在不加载插件运行时的情况下看到这些凭证时，请使用清单 `setup.providers[].envVars`。已弃用的 `providerAuthEnvVars` 在弃用窗口期间仍会由兼容性适配器读取，使用它的非内置插件会收到清单诊断。当一个提供商 ID 应复用另一个提供商 ID 的环境变量、认证配置、配置支持的认证和 API 密钥新手引导选项时，请使用清单 `providerAuthAliases`。当新手引导/认证选择 CLI 表面应在不加载提供商运行时的情况下知道提供商的选择 ID、分组标签和简单的单标志认证接线时，请使用清单 `providerAuthChoices`。将提供商运行时 `envVars` 保留给面向操作员的提示，例如新手引导标签或 OAuth 客户端 ID/客户端密钥设置变量。
当渠道具有由环境变量驱动的凭证或设置，并且通用 shell 环境回退、配置/Status 检查或设置提示应在不加载渠道运行时的情况下看到它们时，请使用 manifest `channelEnvVars`。
当渠道具有由环境驱动的认证或设置，并且通用 shell 环境回退、配置/Status 检查或设置提示应在不加载渠道运行时的情况下看到它时，请使用清单 `channelEnvVars`。
### 钩子顺序和用法
对于模型/提供商插件，OpenClaw 会按大致如下顺序调用钩子。
对于模型/提供商插件，OpenClaw 会按以下大致顺序调用钩子。
“When to use” 列是快速决策指南。
| # | 钩子 | 作用 | 何时使用 |
| # | 钩子 | 作用 | 何时使用 |
| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | `catalog` | 在生成 `models.json` 期间将提供商配置发布到 `models.providers` | 提供商拥有目录或基础 URL 默认值 |
| 2 | `applyConfigDefaults` | 在配置物化期间应用提供商自有的全局配置默认值 | 默认值取决于认证模式、环境或提供商模型族语义 |
| -- | _(内置模型查找)_ | OpenClaw 会先尝试正常的注册表/目录路径 | _(不是插件钩子)_ |
| 3 | `normalizeModelId` | 在查找前规范化旧版或预览版模型 ID 别名 | 提供商在规范模型解析前负责清理别名 |
| 4 | `normalizeTransport` | 在通用模型组装前规范化提供商族的 `api` / `baseUrl` | 提供商负责清理同一传输族中自定义提供商 ID 的传输设置 |
| 5 | `normalizeConfig` | 在运行时/提供商解析前规范化 `models.providers.<id>` | 提供商需要与插件同处的配置清理；内置 Google 族助手也会兜底支持的 Google 配置条目 |
| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式用量兼容重写 | 提供商需要由端点驱动的原生流式用量元数据修复 |
| 7 | `resolveConfigApiKey` | 在运行时认证加载前为配置提供商解析环境标记认证 | 提供商拥有自有的环境标记 API-key 解析；`amazon-bedrock` 也在这里有一个内置的 AWS 环境标记解析器 |
| 8 | `resolveSyntheticAuth` | 暴露本地/自托管或配置支持的认证，且不持久化明文 | 提供商可以使用合成/本地凭证标记运行 |
| 9 | `resolveExternalAuthProfiles` | 叠加提供商自有的外部认证配置文件；CLI/应用自有凭证的默认 `persistence` 为 `runtime-only` | 提供商复用外部认证凭证，而不持久化复制的刷新令牌；在 manifest 中声明 `contracts.externalAuthProviders` |
| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的合成配置文件占位符降级到环境/配置支持的认证之后 | 提供商存储了不应优先胜出的合成占位符配置文件 |
| 11 | `resolveDynamicModel` | 为尚未进入本地注册表的提供商自有模型 ID 同步兜底 | 提供商接受任意上游模型 ID |
| 12 | `prepareDynamicModel` | 异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 ID 前需要网络元数据 |
| 13 | `normalizeResolvedModel` | 嵌入式运行器使用已解析模型前的最终重写 | 提供商需要传输重写，但仍使用核心传输 |
| 14 | `contributeResolvedModelCompat` | 为位于另一种兼容传输之后的厂商模型贡献兼容标志 | 提供商能在代理传输上识别自己的模型，而不接管该提供商 |
| 15 | `capabilities` | 共享核心逻辑使用的提供商自有转录/工具元数据 | 提供商需要转录/提供商族特性 |
| 16 | `normalizeToolSchemas` | 在嵌入式运行器看到工具 schema 前对其规范化 | 提供商需要传输族 schema 清理 |
| 17 | `inspectToolSchemas` | 在规范化后暴露提供商自有的 schema 诊断 | 提供商希望发出关键字警告，而不让核心学习提供商特定规则 |
| 18 | `resolveReasoningOutputMode` | 选择原生与带标签的推理输出契约 | 提供商需要带标签的推理/最终输出，而不是原生字段 |
| 19 | `prepareExtraParams` | 在通用流选项包装器前规范化请求参数 | 提供商需要默认请求参数或按提供商清理参数 |
| 20 | `createStreamFn` | 用自定义传输完全替换正常流路径 | 提供商需要自定义线协议，而不只是包装器 |
| 21 | `wrapStreamFn` | 应用通用包装器后的流包装器 | 提供商需要请求 header/body/模型兼容包装器，而不需要自定义传输 |
| 22 | `resolveTransportTurnState` | 附加原生的逐轮传输 header 或元数据 | 提供商希望通用传输发送提供商原生的轮次身份 |
| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket header 或会话冷却策略 | 提供商希望通用 WS 传输调整会话 header 或兜底策略 |
| 24 | `formatApiKey` | 认证配置文件格式化器：已存储配置文件会变成运行时 `apiKey` 字符串 | 提供商存储额外认证元数据，并需要自定义运行时令牌形态 |
| 25 | `refreshOAuth` | 用于自定义刷新端点或刷新失败策略的 OAuth 刷新覆盖 | 提供商不适配共享的 `pi-ai` 刷新器 |
| 26 | `buildAuthDoctorHint` | OAuth 刷新失败时追加的修复提示 | 提供商在刷新失败后需要提供商自有的认证修复指引 |
| 27 | `matchesContextOverflowError` | 提供商自有的上下文窗口溢出匹配器 | 提供商存在通用启发式会漏掉的原始溢出错误 |
| 28 | `classifyFailoverReason` | 提供商自有的故障转移原因分类 | 提供商可以将原始 API/传输错误映射为限速/过载等 |
| 29 | `isCacheTtlEligible` | 代理/回程提供商的提示缓存策略 | 提供商需要特定于代理的缓存 TTL 门控 |
| 30 | `buildMissingAuthMessage` | 替换通用的缺失认证恢复消息 | 提供商需要特定于提供商的缺失认证恢复提示 |
| 31 | `suppressBuiltInModel` | 已弃用。运行时钩子不再被调用；请使用 manifest `modelCatalog.suppressions` | 用于隐藏过期上游行的历史钩子；新的抑制数据应保留在插件 manifest 中 |
| 32 | `augmentModelCatalog` | 在设备发现后追加的合成/最终目录行 | 提供商需要在 `models list` 和选择器中提供合成的前向兼容行 |
| 33 | `resolveThinkingProfile` | 特定模型的 `/think` 等级集、显示标签和默认值 | 提供商为选定模型暴露自定义 thinking 阶梯或二元标签 |
| 34 | `isBinaryThinking` | 开/关推理切换兼容钩子 | 提供商只暴露二元 thinking 开/关 |
| 35 | `supportsXHighThinking` | `xhigh` 推理支持兼容钩子 | 提供商只希望部分模型支持 `xhigh` |
| 36 | `resolveDefaultThinkingLevel` | 默认 `/think` 等级兼容钩子 | 提供商拥有某个模型族的默认 `/think` 策略 |
| 37 | `isModernModelRef` | 用于实时配置文件筛选器和冒烟测试选择的现代模型匹配器 | 由提供商负责实时/冒烟测试首选模型匹配 |
| 38 | `prepareRuntimeAuth` | 在推理前，将已配置凭证交换为实际运行时令牌/密钥 | 提供商需要令牌交换或短期请求凭证 |
| 39 | `resolveUsageAuth` | 为 `/usage` 和相关 Status 表面解析使用量/计费凭证 | 提供商需要自定义使用量/配额令牌解析，或不同的使用量凭证 |
| 40 | `fetchUsageSnapshot` | 在凭证解析完成后，获取并规范化特定于提供商的使用量/配额快照 | 提供商需要特定于提供商的使用量端点或载荷解析器 |
| 41 | `createEmbeddingProvider` | 为记忆/搜索构建由提供商负责的嵌入适配器 | 记忆嵌入行为归属提供商插件 |
| 42 | `buildReplayPolicy` | 返回控制提供商转录处理的重放策略 | 提供商需要自定义转录策略（例如，移除思考块） |
| 43 | `sanitizeReplayHistory` | 在通用转录清理后重写重放历史 | 提供商需要超出共享压缩辅助函数的特定于提供商的重放重写 |
| 44 | `validateReplayTurns` | 在嵌入式运行器之前进行最终重放轮次验证或重塑 | 提供商传输协议需要在通用净化后进行更严格的轮次验证 |
| 45 | `onModelSelected` | 运行由提供商负责的选择后副作用 | 当模型变为活动状态时，提供商需要遥测或由提供商负责的状态 |
| 1 | `catalog` | 在生成 `models.json` 期间，将提供商配置发布到 `models.providers` | 提供商拥有目录或基准 URL 默认值 |
| 2 | `applyConfigDefaults` | 在配置物化期间应用提供商自有的全局配置默认值 | 默认值取决于凭证模式、环境或提供商模型系列语义 |
| -- | _(内置模型查找)_ | OpenClaw 会先尝试正常的注册表/目录路径 | _(不是插件钩子)_ |
| 3 | `normalizeModelId` | 在查找前规范化旧版或预览版模型 ID 别名 | 提供商在规范模型解析前负责别名清理 |
| 4 | `normalizeTransport` | 在通用模型组装前规范化提供商系列的 `api` / `baseUrl` | 提供商负责同一传输系列中自定义提供商 ID 的传输清理 |
| 5 | `normalizeConfig` | 在运行时/提供商解析前规范化 `models.providers.<id>` | 提供商需要应与插件共存的配置清理；内置 Google 系列帮助程序也会兜底支持的 Google 配置项 |
| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式用量兼容性重写 | 提供商需要由端点驱动的原生流式用量元数据修复 |
| 7 | `resolveConfigApiKey` | 在加载运行时凭证前，为配置提供商解析环境变量标记凭证 | 提供商有提供商自有的环境变量标记 API 密钥解析；`amazon-bedrock` 也在这里有内置 AWS 环境变量标记解析器 |
| 8 | `resolveSyntheticAuth` | 暴露本地/自托管或配置支持的凭证，而不持久化明文 | 提供商可以使用合成/本地凭证标记运行 |
| 9 | `resolveExternalAuthProfiles` | 叠加提供商自有的外部凭证配置；CLI/应用自有凭据的默认 `persistence` 是 `runtime-only` | 提供商复用外部凭证凭据，而不持久化复制的刷新令牌；在清单中声明 `contracts.externalAuthProviders` |
| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的合成配置占位符置于环境变量/配置支持的凭证之后 | 提供商存储不应赢得优先级的合成占位符配置 |
| 11 | `resolveDynamicModel` | 为尚未进入本地注册表的提供商自有模型 ID 提供同步回退 | 提供商接受任意上游模型 ID |
| 12 | `prepareDynamicModel` | 异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 ID 前需要网络元数据 |
| 13 | `normalizeResolvedModel` | 在嵌入式运行器使用已解析模型前进行最终重写 | 提供商需要传输重写，但仍使用核心传输 |
| 14 | `contributeResolvedModelCompat` | 为位于另一种兼容传输之后的供应商模型贡献兼容性标志 | 提供商能识别代理传输上的自有模型，而不接管提供商 |
| 15 | `capabilities` | 共享核心逻辑使用的提供商自有 transcript/工具元数据 | 提供商需要 transcript/提供商系列特殊处理 |
| 16 | `normalizeToolSchemas` | 在嵌入式运行器看到工具 schema 前对其进行规范化 | 提供商需要传输系列 schema 清理 |
| 17 | `inspectToolSchemas` | 在规范化后暴露提供商自有的 schema 诊断 | 提供商想要关键字警告，而不把提供商特定规则教给核心 |
| 18 | `resolveReasoningOutputMode` | 选择原生或标记式 reasoning 输出契约 | 提供商需要标记式 reasoning/最终输出，而不是原生字段 |
| 19 | `prepareExtraParams` | 在通用流式选项包装器前规范化请求参数 | 提供商需要默认请求参数或按提供商进行参数清理 |
| 20 | `createStreamFn` | 用自定义传输完全替换正常流式路径 | 提供商需要自定义 wire protocol，而不仅仅是包装器 |
| 21 | `wrapStreamFn` | 应用通用包装器之后的流式包装器 | 提供商需要请求标头/正文/模型兼容包装器，而不需要自定义传输 |
| 22 | `resolveTransportTurnState` | 附加原生每轮传输标头或元数据 | 提供商希望通用传输发送提供商原生的轮次身份 |
| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 标头或会话冷却策略 | 提供商希望通用 WS 传输调整会话标头或回退策略 |
| 24 | `formatApiKey` | 凭证配置格式化器：已存储配置会变成运行时 `apiKey` 字符串 | 提供商存储额外凭证元数据，并需要自定义运行时令牌形态 |
| 25 | `refreshOAuth` | 针对自定义刷新端点或刷新失败策略的 OAuth 刷新覆盖 | 提供商不适合共享的 `pi-ai` 刷新器 |
| 26 | `buildAuthDoctorHint` | OAuth 刷新失败时附加的修复提示 | 提供商在刷新失败后需要提供商自有的凭证修复指导 |
| 27 | `matchesContextOverflowError` | 提供商自有的上下文窗口溢出匹配器 | 提供商存在通用启发式规则会漏掉的原始溢出错误 |
| 28 | `classifyFailoverReason` | 提供商自有的故障转移原因分类 | 提供商可以将原始 API/传输错误映射到速率限制/过载等 |
| 29 | `isCacheTtlEligible` | 针对代理/回程提供商的提示缓存策略 | 提供商需要代理特定的缓存 TTL 门控 |
| 30 | `buildMissingAuthMessage` | 替换通用缺失凭证恢复消息 | 提供商需要提供商特定的缺失凭证恢复提示 |
| 31 | `suppressBuiltInModel` | 已弃用。运行时钩子不再被调用；请使用清单 `modelCatalog.suppressions` | 用于隐藏陈旧上游行的历史钩子；将新的抑制数据保留在插件清单中 |
| 32 | `augmentModelCatalog` | 在设备发现后追加的合成/最终目录行 | 提供商需要 `models list` 和选择器中的合成前向兼容行 |
| 33 | `resolveThinkingProfile` | 特定模型的 `/think` 级别集合、显示标签和默认值 | 提供商为所选模型暴露自定义思考阶梯或二元标签 |
| 34 | `isBinaryThinking` | 开/关 reasoning 切换兼容性钩子 | 提供商只暴露二元思考开关 |
| 35 | `supportsXHighThinking` | `xhigh` reasoning 支持兼容性钩子 | 提供商只想对部分模型启用 `xhigh` |
| 36 | `resolveDefaultThinkingLevel` | 默认 `/think` 级别兼容性钩子 | 提供商拥有某个模型系列的默认 `/think` 策略 |
| 37 | `isModernModelRef` | 用于实时配置文件过滤器和冒烟选择的现代模型匹配器 | 提供商负责实时/冒烟首选模型匹配 |
| 38 | `prepareRuntimeAuth` | 在推理前，将已配置的凭证交换为实际运行时令牌/密钥 | 提供商需要令牌交换或短期请求凭证 |
| 39 | `resolveUsageAuth` | 为 `/usage` 和相关 Status 界面解析用量/计费凭证 | 提供商需要自定义用量/配额令牌解析，或不同的用量凭证 |
| 40 | `fetchUsageSnapshot` | 在认证解析完成后，获取并规范化提供商特定的用量/配额快照 | 提供商需要提供商特定的用量端点或载荷解析器 |
| 41 | `createEmbeddingProvider` | 为记忆/搜索构建提供商拥有的嵌入适配器 | 记忆嵌入行为属于提供商插件 |
| 42 | `buildReplayPolicy` | 返回用于控制该提供商转录处理的重放策略 | 提供商需要自定义转录策略（例如，剥离思考块） |
| 43 | `sanitizeReplayHistory` | 在通用转录清理后重写重放历史 | 提供商需要超出共享压缩辅助函数之外的提供商特定重放重写 |
| 44 | `validateReplayTurns` | 在嵌入式运行器之前进行最终的重放轮次验证或重塑 | 提供商传输协议在通用清理后需要更严格的轮次验证 |
| 45 | `onModelSelected` | 运行提供商拥有的选择后副作用 | 当模型变为活动状态时，提供商需要遥测或提供商拥有的状态 |
`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配的提供商插件，然后继续遍历其他支持钩子的提供商插件，直到某个插件实际改写了模型 ID 或传输/配置。这样可以保持别名/兼容提供商 shim 正常工作，而不要求调用方知道哪个内置插件负责改写。如果没有提供商钩子改写受支持的 Google 系列配置项，内置的 Google 配置规范化器仍会应用该兼容性清理。
`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配的提供商插件，然后继续遍历其他具备钩子能力的提供商插件，直到某个钩子实际更改模型 ID 或传输/配置。这样可以让别名/兼容性提供商垫片继续工作，而不要求调用方知道哪个内置插件拥有这次重写。如果没有提供商钩子重写受支持的 Google 系列配置条目，内置的 Google 配置规范化器仍会应用该兼容性清理。
如果提供商需要完全自定义的线协议或自定义请求执行器，那属于另一类扩展。这些钩子用于仍运行在 OpenClaw 常规推理循环上的提供商行为。
如果提供商需要完全自定义的传输协议或自定义请求执行器，那属于另一类扩展。这些钩子适用于仍运行在 OpenClaw 正常推理循环上的提供商行为。
### 提供商示例
@ -277,33 +275,31 @@ api.registerProvider({
### 内置示例
内置提供商插件会组合上面的钩子，以适配每个供应商的目录、认证、思考、回放和用量需求。权威的钩子集合随每个插件位于 `extensions/` 下；本页展示的是这些形态，而不是镜像完整列表。
内置提供商插件会组合上面的钩子，以适配各个厂商的目录、鉴权、思考、重放和用量需求。权威钩子集合位于 `extensions/` 下的各个插件中；本页说明这些形态，而不是镜像该列表。
<AccordionGroup>
<Accordion title="透传目录提供商">
OpenRouter、Kilocode、Z.AI、xAI 注册 `catalog` 以及
`resolveDynamicModel` / `prepareDynamicModel`，这样它们就能在 OpenClaw 的静态目录之前呈现上游模型 ID。
`resolveDynamicModel` / `prepareDynamicModel`，这样它们可以在 OpenClaw 的静态目录之前暴露上游模型 ID。
</Accordion>
<Accordion title="OAuth 和用量端点提供商">
GitHub Copilot、Gemini CLI、ChatGPT Codex、MiniMax、Xiaomi、z.ai 将
`prepareRuntimeAuth` 或 `formatApiKey` 与 `resolveUsageAuth` +
`fetchUsageSnapshot` 配对，以拥有令牌交换和 `/usage` 集成。
`fetchUsageSnapshot` 搭配使用，以自行负责令牌交换和 `/usage` 集成。
</Accordion>
<Accordion title="回放和对话记录清理族">
共享的命名族（`google-gemini`、`passthrough-gemini`、
`anthropic-by-model`、`hybrid-anthropic-openai`）让提供商可以通过
`buildReplayPolicy` 选择加入对话记录策略，而无需每个插件重新实现清理逻辑。
<Accordion title="重放和转录清理系列">
共享的命名系列（`google-gemini`、`passthrough-gemini`、
`anthropic-by-model`、`hybrid-anthropic-openai`）让提供商可以通过 `buildReplayPolicy` 选择加入转录策略，而不需要每个插件重新实现清理。
</Accordion>
<Accordion title="仅目录提供商">
`byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi-coding`、`nvidia`、
`qianfan`、`synthetic`、`together`、`venice`、`vercel-ai-gateway` 和
`volcengine` 只注册 `catalog`，并使用共享推理循环。
</Accordion>
<Accordion title="Anthropic 专用流辅助工具">
Beta 头、`/fast` / `serviceTier` 和 `context1m` 位于
Anthropic 插件的公共 `api.ts` / `contract-api.ts` 接缝内
<Accordion title="Anthropic 专用流式辅助工具">
Beta 标头、`/fast` / `serviceTier` 和 `context1m` 位于 Anthropic 插件的公共 `api.ts` / `contract-api.ts` 边界中
（`wrapAnthropicProviderStream`、`resolveAnthropicBetas`、
`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`），而不是通用 SDK 中。
`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`），而不是位于通用 SDK 中。
</Accordion>
</AccordionGroup>
@ -328,16 +324,16 @@ const voices = await api.runtime.tts.listVoices({
});
```
说明：
注意：
- `textToSpeech` 返回用于文件/语音便笺表面的常规核心 TTS 输出载荷。
- `textToSpeech` 会返回用于文件/语音备注界面的常规核心 TTS 输出载荷。
- 使用核心 `messages.tts` 配置和提供商选择。
- 返回 PCM 音频缓冲区 + 采样率。插件必须为提供商重新采样/编码。
- `listVoices` 对每个提供商都是可选的。将它用于供应商拥有的语音选择器或设置流程。
- 语音列表可以包含更丰富的元数据，例如区域设置、性别和人格标签，用于感知提供商的选择器。
- 返回 PCM 音频缓冲区 + 采样率。插件必须为提供商重采样/编码。
- `listVoices` 对每个提供商都是可选的。将它用于厂商自有的语音选择器或设置流程。
- 语音列表可以包含更丰富的元数据，例如区域设置、性别和个性标签，供提供商感知的选择器使用。
- OpenAI 和 ElevenLabs 目前支持电话音频。Microsoft 不支持。
插件还可以通过 `api.registerSpeechProvider(...)` 注册语音提供商。
插件也可以通过 `api.registerSpeechProvider(...)` 注册语音提供商。
```ts
api.registerSpeechProvider({
@ -355,14 +351,14 @@ api.registerSpeechProvider({
});
```
说明：
注意：
- 将 TTS 策略、回退和回复交付保留在核心中。
- 将语音提供商用于供应商拥有的合成行为。
- 将 TTS 策略、回退和回复投递保留在核心中。
- 将语音提供商用于厂商自有的合成行为。
- 旧版 Microsoft `edge` 输入会规范化为 `microsoft` 提供商 ID。
- 首选的所有权模型以公司为导向：随着 OpenClaw 添加这些能力合约，一个供应商插件可以拥有文本、语音、图像和未来媒体提供商。
- 首选的所有权模型以公司为导向：随着 OpenClaw 添加这些能力契约，一个厂商插件可以拥有文本、语音、图像和未来的媒体提供商。
对于图像/音频/视频理解，插件注册一个类型化的媒体理解提供商，而不是通用键/值包：
对于图像/音频/视频理解，插件注册一个有类型的媒体理解提供商，而不是通用键/值包：
```ts
api.registerMediaUnderstandingProvider({
@ -374,14 +370,14 @@ api.registerMediaUnderstandingProvider({
});
```
说明：
注意：
- 将编排、回退、配置和渠道接线保留在核心中。
- 将供应商行为保留在提供商插件中。
- 将厂商行为保留在提供商插件中。
- 增量扩展应保持类型化：新的可选方法、新的可选结果字段、新的可选能力。
- 视频生成已经遵循相同模式：
- 核心拥有能力合约和运行时辅助工具
- 供应商插件注册 `api.registerVideoGenerationProvider(...)`
- 核心拥有能力契约和运行时辅助工具
- 厂商插件注册 `api.registerVideoGenerationProvider(...)`
- 功能/渠道插件使用 `api.runtime.videoGeneration.*`
对于媒体理解运行时辅助工具，插件可以调用：
@ -399,7 +395,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({
});
```
对于音频转录，插件可以使用媒体理解运行时或较旧的 STT 别名：
对于音频转录，插件可以使用媒体理解运行时，也可以使用较旧的 STT 别名：
```ts
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
@ -410,11 +406,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
});
```
说明：
注意：
- `api.runtime.mediaUnderstanding.*` 是图像/音频/视频理解的首选共享表面。
- `api.runtime.mediaUnderstanding.*` 是图像/音频/视频理解的首选共享界面。
- 使用核心媒体理解音频配置（`tools.media.audio`）和提供商回退顺序。
- 当没有生成转录输出时返回 `{ text: undefined }`（例如跳过/不支持的输入）。
- 当没有产生转录输出时（例如跳过/不支持的输入），返回 `{ text: undefined }`。
- `api.runtime.stt.transcribeAudioFile(...)` 仍作为兼容性别名保留。
插件还可以通过 `api.runtime.subagent` 启动后台子智能体运行：
@ -429,16 +425,16 @@ const result = await api.runtime.subagent.run({
});
```
说明：
注意：
- `provider` 和 `model` 是每次运行的可选覆盖项，不是持久会话变更。
- OpenClaw 仅为受信任调用方采用这些覆盖字段。
- 对于插件拥有的回退运行，操作员必须通过 `plugins.entries.<id>.subagent.allowModelOverride: true` 选择加入。
- 使用 `plugins.entries.<id>.subagent.allowedModels` 将受信任插件限制到特定规范 `provider/model` 目标，或使用 `"*"` 明确允许任意目标。
- 不受信任的插件子智能体运行仍会工作，但覆盖请求会被拒绝，而不是静默回退。
- 插件创建的子智能体会话会带有创建插件 ID 标签。回退 `api.runtime.subagent.deleteSession(...)` 只能删除这些归属会话；任意会话删除仍需要管理员范围的 Gateway 网关请求。
- `provider` 和 `model` 是每次运行的可选覆盖项，不是持久会话更改。
- OpenClaw 只会为可信调用方遵循这些覆盖字段。
- 对于插件拥有的回退运行，运营者必须使用 `plugins.entries.<id>.subagent.allowModelOverride: true` 选择启用。
- 使用 `plugins.entries.<id>.subagent.allowedModels` 将可信插件限制为特定的规范 `provider/model` 目标，或使用 `"*"` 明确允许任何目标。
- 不可信插件的子智能体运行仍可工作，但覆盖请求会被拒绝，而不是静默回退。
- 插件创建的子智能体会话会标记创建它的插件 ID。回退 `api.runtime.subagent.deleteSession(...)` 只能删除这些归属会话；任意会话删除仍需要管理员范围的 Gateway 网关请求。
对于 Web 搜索，插件可以使用共享运行时辅助工具，而不是伸入智能体工具接线：
对于网页搜索，插件可以使用共享运行时辅助工具，而不是深入智能体工具接线：
```ts
const providers = api.runtime.webSearch.listProviders({
@ -454,13 +450,14 @@ const result = await api.runtime.webSearch.search({
});
```
插件还可以通过 `api.registerWebSearchProvider(...)` 注册 Web 搜索提供商。
插件也可以通过
`api.registerWebSearchProvider(...)` 注册网页搜索提供商。
说明：
注意：
- 将提供商选择、凭证解析和共享请求语义保留在核心中。
- 将 Web 搜索提供商用于供应商特定的搜索传输。
- `api.runtime.webSearch.*` 是需要搜索行为、但不依赖智能体工具包装器的功能/渠道插件的首选共享表面。
- 将网页搜索提供商用于厂商专用搜索传输。
- `api.runtime.webSearch.*` 是需要搜索行为但不依赖智能体工具包装器的功能/渠道插件的首选共享界面。
### `api.runtime.imageGeneration`
@ -475,12 +472,12 @@ const providers = api.runtime.imageGeneration.listProviders({
});
```
- `generate(...)`：使用配置的图像生成提供商链生成图像。
- `generate(...)`：使用已配置的图像生成提供商链生成图像。
- `listProviders(...)`：列出可用的图像生成提供商及其能力。
## Gateway 网关 HTTP 路由
插件可以使用 `api.registerHttpRoute(...)` 暴露 HTTP 端点。
插件可以通过 `api.registerHttpRoute(...)` 暴露 HTTP 端点。
```ts
api.registerHttpRoute({
@ -498,119 +495,141 @@ api.registerHttpRoute({
路由字段：
- `path`：Gateway 网关 HTTP 服务器下的路由路径。
- `auth`：必填。使用 `"gateway"` 要求常规 Gateway 网关认证，或使用 `"plugin"` 进行插件管理的认证/webhook 验证。
- `auth`：必填。使用 `"gateway"` 要求常规 Gateway 网关鉴权，或使用 `"plugin"` 进行插件管理的鉴权/webhook 验证。
- `match`：可选。`"exact"`（默认）或 `"prefix"`。
- `replaceExisting`：可选。允许同一插件替换其自己的现有路由注册。
- `handler`：当路由已处理请求时返回 `true`。
- `replaceExisting`：可选。允许同一个插件替换它自己现有的路由注册。
- `handler`：当该路由处理了请求时返回 `true`。
说明：
注意：
- `api.registerHttpHandler(...)` 已移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。
- 插件路由必须显式声明 `auth`。
- 精确的 `path + match` 冲突会被拒绝，除非设置 `replaceExisting: true`，并且一个插件不能替换另一个插件的路由。
- 不同 `auth` 级别的重叠路由会被拒绝。仅在相同身份验证级别上保留 `exact`/`prefix` 回退链。
- `auth: "plugin"` 路由**不会**自动接收操作员运行时作用域。它们用于插件管理的 webhook/签名验证，而不是特权 Gateway 网关辅助调用。
- 除非设置 `replaceExisting: true`，否则精确的 `path + match` 冲突会被拒绝，并且一个插件不能替换另一个插件的路由。
- 具有不同 `auth` 级别的重叠路由会被拒绝。只在同一认证级别上保留 `exact`/`prefix` 回退链。
- `auth: "plugin"` 路由**不会**自动获得操作者运行时作用域。它们用于插件管理的 webhook/签名验证，而不是有特权的 Gateway 网关辅助调用。
- `auth: "gateway"` 路由在 Gateway 网关请求运行时作用域内运行，但该作用域有意保持保守：
- 共享密钥 bearer 身份验证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes`
- 带可信身份的 HTTP 模式（例如私有入口上的 `trusted-proxy` 或 `gateway.auth.mode = "none"`）仅在显式提供 `x-openclaw-scopes` 标头时才会采用它
- 如果这些带身份的插件路由请求中缺少 `x-openclaw-scopes`，运行时作用域会回退到 `operator.write`
- 实用规则：不要假设经过 Gateway 网关身份验证的插件路由就是隐式管理员接口。如果你的路由需要仅限管理员的行为，请要求使用带身份的身份验证模式，并记录显式 `x-openclaw-scopes` 标头契约。
- 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes`
- 受信任且携带身份的 HTTP 模式（例如 `trusted-proxy`，或私有入口上的 `gateway.auth.mode = "none"`）仅在显式提供该标头时才遵循 `x-openclaw-scopes`
- 如果这些携带身份的插件路由请求中缺少 `x-openclaw-scopes`，运行时作用域会回退到 `operator.write`
- 实用规则：不要假设通过 Gateway 网关认证的插件路由是隐式管理员表面。如果你的路由需要仅限管理员的行为，请要求携带身份的认证模式，并记录显式 `x-openclaw-scopes` 标头约定。
## 插件 SDK 导入路径
编写新插件时，使用较窄的 SDK 子路径，而不是单体式 `openclaw/plugin-sdk` 根 barrel。核心子路径：
编写新插件时，请使用窄范围的 SDK 子路径，而不是单体的 `openclaw/plugin-sdk` 根
barrel。核心子路径：
| 子路径 | 用途 |
| ----------------------------------- | -------------------------------------------------- |
| `openclaw/plugin-sdk/plugin-entry` | 插件注册原语 |
| `openclaw/plugin-sdk/channel-core` | 渠道入口/构建辅助工具 |
| `openclaw/plugin-sdk/core` | 通用共享辅助工具和总括契约 |
| `openclaw/plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema（`OpenClawSchema`） |
| `openclaw/plugin-sdk/core` | 通用共享辅助工具和伞形契约 |
| `openclaw/plugin-sdk/config-schema` | 根 `openclaw.json` Zod 模式（`OpenClawSchema`） |
渠道插件可从一组较窄的边界中选择：`channel-setup`、`setup-runtime`、`setup-adapter-runtime`、`setup-tools`、`channel-pairing`、`channel-contract`、`channel-feedback`、`channel-inbound`、`channel-lifecycle`、`channel-reply-pipeline`、`command-auth`、`secret-input`、`webhook-ingress`、`channel-targets` 和 `channel-actions`。审批行为应整合到一个 `approvalCapability` 契约上，而不是混用无关的插件字段。请参阅[渠道插件](/zh-CN/plugins/sdk-channel-plugins)。
渠道插件可从一组窄范围接缝中选择：`channel-setup`、
`setup-runtime`、`setup-adapter-runtime`、`setup-tools`、`channel-pairing`、
`channel-contract`、`channel-feedback`、`channel-inbound`、`channel-lifecycle`、
`channel-reply-pipeline`、`command-auth`、`secret-input`、`webhook-ingress`、
`channel-targets` 和 `channel-actions`。审批行为应统一到一个
`approvalCapability` 契约上，而不是混用无关的插件字段。参见[渠道插件](/zh-CN/plugins/sdk-channel-plugins)。
运行时和配置辅助工具位于匹配的聚焦 `*-runtime` 子路径下（`approval-runtime`、`agent-runtime`、`lazy-runtime`、`directory-runtime`、`text-runtime`、`runtime-store`、`system-event-runtime`、`heartbeat-runtime`、`channel-activity-runtime` 等）。优先使用 `config-types`、`plugin-config-runtime`、`runtime-config-snapshot` 和 `config-mutation`，而不是宽泛的 `config-runtime` 兼容 barrel。
运行时和配置辅助工具位于匹配的聚焦 `*-runtime` 子路径下
（`approval-runtime`、`agent-runtime`、`lazy-runtime`、`directory-runtime`、
`text-runtime`、`runtime-store`、`system-event-runtime`、`heartbeat-runtime`、
`channel-activity-runtime` 等）。优先使用 `config-types`、
`plugin-config-runtime`、`runtime-config-snapshot` 和 `config-mutation`，
而不是宽泛的 `config-runtime` 兼容 barrel。
<Info>
`openclaw/plugin-sdk/channel-runtime`、`openclaw/plugin-sdk/config-runtime` 和 `openclaw/plugin-sdk/infra-runtime` 是面向旧插件的已弃用兼容 shim。新代码应改为导入更窄的通用原语。
`openclaw/plugin-sdk/channel-runtime`、`openclaw/plugin-sdk/config-runtime`
和 `openclaw/plugin-sdk/infra-runtime` 是面向旧插件的已弃用兼容 shim。
新代码应改为导入更窄的通用原语。
</Info>
仓库内部入口点（按每个内置插件包根目录）：
仓库内部入口点（按内置插件包根目录）：
- `index.js` — 内置插件入口
- `api.js` — 辅助工具/类型 barrel
- `runtime-api.js` — 仅运行时 barrel
- `setup-entry.js` — 设置插件入口
外部插件应仅导入 `openclaw/plugin-sdk/*` 子路径。绝不要从 core 或另一个插件导入另一个插件包的 `src/*`。由 facade 加载的入口点在存在活动运行时配置快照时优先使用该快照，然后回退到磁盘上的已解析配置文件。
外部插件应只导入 `openclaw/plugin-sdk/*` 子路径。切勿从核心或另一个插件中
导入另一个插件包的 `src/*`。通过 facade 加载的入口点会在存在活动运行时配置快照时优先使用它，
然后回退到磁盘上解析出的配置文件。
`image-generation`、`media-understanding` 和 `speech` 等能力专用子路径存在，是因为内置插件目前使用它们。它们不会自动成为长期冻结的外部契约；依赖它们时请查看相关 SDK 参考页面。
`image-generation`、`media-understanding` 和 `speech` 等特定能力子路径存在，
是因为内置插件当前正在使用它们。它们不会自动成为长期冻结的外部契约；依赖它们时请查看相关 SDK 参考页面。
## 消息工具 schema
## 消息工具模式
插件应拥有渠道特定的 `describeMessageTool(...)` schema 贡献，用于 reaction、read 和 poll 等非消息原语。共享发送呈现应使用通用 `MessagePresentation` 契约，而不是 provider 原生按钮、组件、块或卡片字段。请参阅 [Message Presentation](/zh-CN/plugins/message-presentation) 了解契约、回退规则、provider 映射和插件作者检查清单。
插件应拥有针对非消息原语（如反应、已读和投票）的渠道特定
`describeMessageTool(...)` 模式贡献。共享发送呈现应使用通用
`MessagePresentation` 契约，而不是提供商原生的按钮、组件、块或卡片字段。
有关契约、回退规则、提供商映射和插件作者检查清单，请参见[消息呈现](/zh-CN/plugins/message-presentation)。
具备发送能力的插件通过消息能力声明它们可以渲染的内容：
- `presentation` 用于语义呈现块（`text`、`context`、`divider`、`buttons`、`select`）
- `delivery-pin` 用于固定投递请求
Core 决定是原生渲染该呈现，还是将其降级为文本。不要从通用消息工具暴露 provider 原生 UI 逃生口。旧版原生 schema 的已弃用 SDK 辅助工具仍会为现有第三方插件导出，但新插件不应使用它们。
核心决定是以原生方式渲染呈现，还是将其降级为文本。不要从通用消息工具中暴露提供商原生 UI 逃生口。
面向旧版原生模式的已弃用 SDK 辅助工具仍会为现有第三方插件导出，但新插件不应使用它们。
## 渠道目标解析
渠道插件应拥有渠道特定的目标语义。保持共享出站主机的通用性，并使用消息适配器接口处理 provider 规则：
渠道插件应拥有渠道特定的目标语义。保持共享出站宿主通用，并使用消息适配器表面处理提供商规则：
- `messaging.inferTargetChatType({ to })` 在目录查找之前，决定规范化目标应被视为 `direct`、`group` 还是 `channel`。
- `messaging.targetResolver.looksLikeId(raw, normalized)` 告诉 core 某个输入是否应跳过目录搜索，直接进入类似 id 的解析。
- `messaging.targetResolver.resolveTarget(...)` 是插件回退路径，用于 core 在规范化后或目录未命中后需要最终由 provider 拥有的解析。
- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后，负责构造 provider 特定的会话路由。
- `messaging.inferTargetChatType({ to })` 在目录查找前决定归一化目标应被视为 `direct`、`group` 还是 `channel`。
- `messaging.targetResolver.looksLikeId(raw, normalized)` 告诉核心，某个输入是否应直接跳到类似 ID 的解析，而不是进行目录搜索。
- `messaging.targetResolver.resolveTarget(...)` 是核心在归一化后或目录未命中后需要最终由提供商拥有的解析时使用的插件回退。
- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后拥有提供商特定的会话路由构建。
推荐拆分：
- 使用 `inferTargetChatType` 处理应在搜索 peer/group 之前发生的类别决策。
- 使用 `looksLikeId` 进行“将此视为显式/原生目标 id”的检查。
- 使用 `resolveTarget` 作为 provider 特定的规范化回退，而不是用于宽泛的目录搜索。
- 将 chat id、thread id、JID、handle 和 room id 等 provider 原生 id 保留在 `target` 值或 provider 特定参数中，不要放入通用 SDK 字段。
- 使用 `inferTargetChatType` 处理应在搜索对等方/群组前发生的类别决策。
- 使用 `looksLikeId` 进行“将此视为显式/原生目标 ID”的检查。
- 使用 `resolveTarget` 处理提供商特定的归一化回退，而不是用于宽泛的目录搜索。
- 将聊天 ID、线程 ID、JID、handle 和房间 ID 等提供商原生 ID 保留在 `target` 值或提供商特定参数中，而不是放在通用 SDK 字段中。
## 配置支撑的目录
## 配置驱动的目录
从配置派生目录条目的插件应将该逻辑保留在插件中，并复用 `openclaw/plugin-sdk/directory-runtime` 中的共享辅助工具。
从配置派生目录条目的插件应将该逻辑保留在插件中，并复用
`openclaw/plugin-sdk/directory-runtime` 中的共享辅助工具。
当渠道需要由配置支撑的 peer/group 时使用它，例如：
当渠道需要由配置驱动的对等方/群组时使用此方式，例如：
- allowlist 驱动的私信 peer
- 已配置的渠道/group 映射
- allowlist 驱动的私信对等方
- 已配置的渠道/群组映射
- 账号作用域的静态目录回退
`directory-runtime` 中的共享辅助工具仅处理通用操作：
`directory-runtime` 中的共享辅助工具只处理通用操作：
- 查询过滤
- limit 应用
- 去重/规范化辅助工具
- 限制应用
- 去重/归一化辅助工具
- 构建 `ChannelDirectoryEntry[]`
渠道特定的账号检查和 id 规范化应留在插件实现中。
渠道特定的账号检查和 ID 归一化应保留在插件实现中。
## Provider 目录
## 提供商目录
Provider 插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })` 为推理定义模型目录。
提供商插件可以使用 `registerProvider({ catalog: { run(...) { ... } } })`
定义用于推理的模型目录。
`catalog.run(...)` 返回与 OpenClaw 写入 `models.providers` 相同的形状：
`catalog.run(...)` 返回的形状与 OpenClaw 写入 `models.providers` 的形状相同：
- `{ provider }` 表示一个 provider 条目
- `{ providers }` 表示多个 provider 条目
- `{ provider }` 表示一个提供商条目
- `{ providers }` 表示多个提供商条目
当插件拥有 provider 特定的模型 id、base URL 默认值或受身份验证保护的模型元数据时，请使用 `catalog`。
当插件拥有提供商特定的模型 ID、基础 URL 默认值，或需要认证控制的模型元数据时，请使用 `catalog`。
`catalog.order` 控制插件目录相对于 OpenClaw 内置隐式 provider 的合并时机：
`catalog.order` 控制插件目录相对于 OpenClaw 内置隐式提供商的合并时机：
- `simple`：普通 API key 或环境驱动的 provider
- `profile`：当身份验证 profile 存在时出现的 provider
- `paired`：合成多个相关 provider 条目的 provider
- `late`：最后一轮，在其他隐式 provider 之后
- `simple`：普通 API key 或环境驱动的提供商
- `profile`：存在认证配置文件时出现的提供商
- `paired`：合成多个相关提供商条目的提供商
- `late`：最后一轮，在其他隐式提供商之后
发生键冲突时，较晚的 provider 胜出，因此插件可以有意使用相同 provider id 覆盖内置 provider 条目。
后面的提供商会在键冲突时胜出，因此插件可以有意使用相同的提供商 ID 覆盖内置提供商条目。
兼容性：
@ -619,28 +638,29 @@ Provider 插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })
## 只读渠道检查
如果你的插件注册了渠道，优先在 `resolveAccount(...)` 旁实现 `plugin.config.inspectAccount(cfg, accountId)`。
如果你的插件注册了渠道，请优先在 `resolveAccount(...)` 旁实现
`plugin.config.inspectAccount(cfg, accountId)`。
原因：
- `resolveAccount(...)` 是运行时路径。它允许假设凭证已完全物化，并且可以在缺少必需 secret 时快速失败。
- `openclaw status`、`openclaw status --all`、`openclaw channels status`、`openclaw channels resolve` 以及 doctor/config 修复流程等只读命令路径，不应仅为了描述配置就需要物化运行时凭证。
- `resolveAccount(...)` 是运行时路径。它可以假设凭证已完全具体化，并且在缺少必要密钥时快速失败。
- `openclaw status`、`openclaw status --all`、`openclaw channels status`、`openclaw channels resolve` 以及 Doctor/配置修复流程等只读命令路径，不应仅为了描述配置而需要具体化运行时凭证。
推荐的 `inspectAccount(...)` 行为：
- 仅返回描述性账号状态。
- 只返回描述性的账号状态。
- 保留 `enabled` 和 `configured`。
- 在相关时包含凭证来源/状态字段，例如：
- `tokenSource`、`tokenStatus`
- `botTokenSource`、`botTokenStatus`
- `appTokenSource`、`appTokenStatus`
- `signingSecretSource`、`signingSecretStatus`
- 你无需为了报告只读可用性而返回原始 token 值。返回 `tokenStatus: "available"`（以及匹配的 source 字段）就足以满足 status 风格的命令。
- 当凭证通过 SecretRef 配置但在当前命令路径中不可用时，使用 `configured_unavailable`。
- 你不需要仅为了报告只读可用性而返回原始令牌值。返回 `tokenStatus: "available"`（以及匹配的来源字段）就足以支持状态类命令。
- 当凭证通过 SecretRef 配置，但在当前命令路径中不可用时，使用 `configured_unavailable`。
这让只读命令可以报告“已配置，但在此命令路径中不可用”，而不是崩溃或误报账号未配置。
这使只读命令能够报告“已配置但在此命令路径中不可用”，而不是崩溃或误报账号未配置。
## 包组合
## 包集合
插件目录可以包含带有 `openclaw.extensions` 的 `package.json`：
@ -654,37 +674,49 @@ Provider 插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })
}
```
每个条目都会成为一个插件。如果包列出了多个插件，插件 id 会变为 `name/<fileBase>`。
每个条目都会成为一个插件。如果包列出了多个扩展，插件 ID
会变成 `name/<fileBase>`。
如果你的插件导入 npm 依赖，请在该目录中安装它们，以便 `node_modules` 可用（`npm install` / `pnpm install`）。
如果你的插件导入 npm 依赖，请在该目录中安装它们，以便
`node_modules` 可用（`npm install` / `pnpm install`）。
安全护栏：每个 `openclaw.extensions` 条目在 symlink 解析后都必须留在插件目录内。逃出包目录的条目会被拒绝。
安全护栏：符号链接解析后，每个 `openclaw.extensions` 条目都必须保留在插件
目录内。逃逸出包目录的条目会被拒绝。
安全说明：`openclaw plugins install` 会使用项目本地的 `npm install --omit=dev --ignore-scripts` 安装插件依赖（没有生命周期脚本，运行时没有 dev 依赖），并忽略继承的全局 npm install 设置。保持插件依赖树为“纯 JS/TS”，并避免需要 `postinstall` 构建的包。
安全说明：`openclaw plugins install` 会使用项目本地的 `npm install --omit=dev --ignore-scripts`
安装插件依赖（没有生命周期脚本，运行时没有 dev 依赖），并忽略继承的全局 npm 安装设置。
请保持插件依赖树为“纯 JS/TS”，并避免需要 `postinstall` 构建的包。
可选：`openclaw.setupEntry` 可以指向一个轻量的仅设置模块。当 OpenClaw 需要为已禁用的渠道插件提供设置接口，或渠道插件已启用但仍未配置时，它会加载 `setupEntry`，而不是完整插件入口。当你的主插件入口还会连接工具、钩子或其他仅运行时代码时，这会让启动和设置更轻量。
可选：`openclaw.setupEntry` 可以指向轻量的仅设置模块。当 OpenClaw 需要为已禁用的渠道插件提供设置表面，
或当渠道插件已启用但仍未配置时，它会加载 `setupEntry`
而不是完整插件入口。当你的主插件入口还会连接工具、钩子或其他仅运行时代码时，
这能让启动和设置更轻量。
可选：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` 可以让渠道插件在 Gateway 网关预监听启动阶段选择使用相同的 `setupEntry` 路径，即使该渠道已经配置完成。
可选：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
可以让渠道插件在 Gateway 网关预监听启动阶段选择同一个 `setupEntry` 路径，即使该渠道已经配置完成。
仅当 `setupEntry` 完全覆盖 Gateway 网关开始监听前必须存在的启动接口时，才使用此项。实践中，这意味着设置入口必须注册启动所依赖的每个渠道自有能力，例如：
仅当 `setupEntry` 完全覆盖 Gateway 网关开始监听前必须存在的启动表面时才使用此选项。实践中，这意味着设置入口
必须注册启动所依赖的每个渠道拥有的能力，例如：
- 渠道注册本身
- 任何必须在 Gateway 网关开始监听前可用的 HTTP 路由
- 任何必须在同一时间窗口中存在的 gateway 方法、工具或服务
- Gateway 网关开始监听前必须可用的任何 HTTP 路由
- 在同一时间窗口内必须存在的任何 Gateway 网关方法、工具或服务
如果你的完整入口仍拥有任何必需的启动能力，请不要启用此标志。保持插件使用默认行为，并让 OpenClaw 在启动期间加载完整入口。
如果你的完整入口仍拥有任何必需的启动能力，请不要启用此标志。保持插件使用默认行为，并让 OpenClaw 在启动期间加载
完整入口。
内置渠道还可以发布仅设置的契约接口辅助工具，供 core 在完整渠道运行时加载前查询。当前设置提升接口是：
内置渠道也可以发布仅设置的契约表面辅助工具，供核心在完整渠道运行时加载前查询。当前的设置
提升表面是：
- `singleAccountKeysToMove`
- `namedAccountPromotionKeys`
- `resolveSingleAccountPromotionTarget(...)`
当 Core 需要在不加载完整插件入口的情况下，将旧版单账号渠道配置提升到 `channels.<id>.accounts.*` 时，会使用这个表面。Matrix 是当前的内置示例：当命名账号已经存在时，它只会把身份验证/引导键移动到一个命名的已提升账号中，并且可以保留已配置的非规范默认账号键，而不是总是创建 `accounts.default`。
当核心需要在不加载完整插件入口的情况下，将旧版单账户渠道配置提升到 `channels.<id>.accounts.*` 时，会使用这个接口。Matrix 是当前内置示例：当命名账户已存在时，它只会把认证/引导键移入命名提升账户，并且可以保留已配置的非规范默认账户键，而不是总是创建 `accounts.default`。
这些设置补丁适配器会让内置合同表面的发现保持惰性。导入时间保持轻量；提升表面只会在首次使用时加载，而不是在模块导入时重新进入内置渠道启动流程。
这些设置补丁适配器会让内置契约接口发现保持惰性。导入时间保持轻量；提升接口只会在首次使用时加载，而不是在模块导入时重新进入内置渠道启动流程。
当这些启动表面包含 Gateway 网关 RPC 方法时，请把它们放在插件专用前缀下。Core 管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍然是保留命名空间，并且始终解析为 `operator.admin`，即使某个插件请求了更窄的作用域。
当这些启动接口包含 Gateway 网关 RPC 方法时，请把它们放在插件专属前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并且始终解析为 `operator.admin`，即使某个插件请求更窄的作用域也是如此。
示例：
@ -703,7 +735,7 @@ Provider 插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })
### 渠道目录元数据
渠道插件可以通过 `openclaw.channel` 声明设置/设备发现元数据，并通过 `openclaw.install` 声明安装提示。这可以让 Core 目录不包含数据。
渠道插件可以通过 `openclaw.channel` 公布设置/设备发现元数据，并通过 `openclaw.install` 公布安装提示。这让核心目录不包含数据。
示例：
@ -731,38 +763,38 @@ Provider 插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })
}
```
除了最小示例之外，常用的 `openclaw.channel` 字段：
除了最小示例以外，常用的 `openclaw.channel` 字段：
- `detailLabel`：用于更丰富的目录/Status 表面的次级标签
- `detailLabel`：用于更丰富目录/Status 接口的次级标签
- `docsLabel`：覆盖文档链接的链接文本
- `preferOver`：此目录条目应优先于的低优先级插件/渠道 ID
- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择表面的文案控制
- `markdownCapable`：将该渠道标记为支持 markdown，用于出站格式化决策
- `exposure.configured`：设置为 `false` 时，在已配置渠道列表表面隐藏该渠道
- `exposure.setup`：设置为 `false` 时，在交互式设置/配置选择器中隐藏该渠道
- `exposure.docs`：在文档导航表面将该渠道标记为内部/私有
- `showConfigured` / `showInSetup`：为了兼容仍然接受的旧版别名；优先使用 `exposure`
- `preferOver`：此目录条目应优先于的较低优先级插件/渠道 ID
- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择界面文案控制
- `markdownCapable`：将渠道标记为支持 markdown，用于出站格式化决策
- `exposure.configured`：设为 `false` 时，在已配置渠道列表界面中隐藏该渠道
- `exposure.setup`：设为 `false` 时，在交互式设置/配置选择器中隐藏该渠道
- `exposure.docs`：将渠道标记为文档导航界面的内部/私有渠道
- `showConfigured` / `showInSetup`：出于兼容性仍接受的旧别名；优先使用 `exposure`
- `quickstartAllowFrom`：让该渠道加入标准快速开始 `allowFrom` 流程
- `forceAccountBinding`：即使只存在一个账号，也要求显式账号绑定
- `forceAccountBinding`：即使只有一个账户，也要求显式账户绑定
- `preferSessionLookupForAnnounceTarget`：解析公告目标时优先使用会话查找
OpenClaw 也可以合并**外部渠道目录**（例如 MPM 注册表导出）。将 JSON 文件放在以下任一位置：
OpenClaw 也可以合并**外部渠道目录**（例如 MPM 注册表导出）。把 JSON 文件放在以下任一位置：
- `~/.openclaw/mpm/plugins.json`
- `~/.openclaw/mpm/catalog.json`
- `~/.openclaw/plugins/catalog.json`
或者让 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（以逗号/分号/`PATH` 分隔）。每个文件都应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器还接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧版别名。
或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（逗号/分号/`PATH` 分隔）。每个文件应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧别名。
生成的渠道目录条目和提供商安装目录条目会在原始 `openclaw.install` 块旁边暴露规范化的安装源事实。规范化事实会标识 npm spec 是精确版本还是浮动选择器、是否存在预期完整性元数据，以及本地源路径是否也可用。当目录/包身份已知时，如果解析出的 npm 包名偏离该身份，规范化事实会发出警告。它们还会在 `defaultChoice` 无效或指向不可用源时发出警告，并在存在 npm 完整性元数据但没有有效 npm 源时发出警告。消费者应将 `installSource` 视为一个附加的可选字段，这样手写条目和目录垫片就不必合成它。这让新手引导和诊断可以解释源平面状态，而无需导入插件运行时。
生成的渠道目录条目和提供商安装目录条目会在原始 `openclaw.install` 块旁边公开规范化的安装源事实。规范化事实会标识 npm 规格是精确版本还是浮动选择器、是否存在预期完整性元数据，以及本地源路径是否也可用。当目录/包身份已知时，如果解析出的 npm 包名偏离该身份，规范化事实会发出警告。当 `defaultChoice` 无效或指向不可用的源，以及存在 npm 完整性元数据但没有有效 npm 源时，它们也会发出警告。消费者应将 `installSource` 视为一个增量可选字段，这样手工构建的条目和目录兼容层不必合成它。这让新手引导和诊断能够解释源平面状态，而无需导入插件运行时。
官方外部 npm 条目应优先使用精确的 `npmSpec` 加 `expectedIntegrity`。裸包名和 dist-tag 仍可用于兼容，但它们会显示源平面警告，以便目录可以逐步转向固定版本、带完整性检查的安装，而不会破坏现有插件。当新手引导从本地目录路径安装时，它会记录一个托管插件的插件索引条目，其中包含 `source: "path"`，并在可能时包含工作区相对的 `sourcePath`。绝对运行加载路径仍保留在 `plugins.load.paths` 中；安装记录会避免把本地工作站路径重复写入长期配置。这让本地开发安装对源平面诊断可见，同时不增加第二个原始文件系统路径披露表面。持久化的 `plugins/installs.json` 插件索引是安装事实来源，并且可以在不加载插件运行时模块的情况下刷新。即使插件清单缺失或无效，它的 `installRecords` map 也会持久保留；它的 `plugins` 数组是可重建的清单视图。
官方外部 npm 条目应优先使用精确的 `npmSpec` 加 `expectedIntegrity`。裸包名和 dist-tag 出于兼容性仍可使用，但它们会显示源平面警告，以便目录可以逐步转向固定版本、带完整性校验的安装，而不破坏现有插件。当新手引导从本地目录路径安装时，它会记录一个托管插件索引条目，其中 `source: "path"`，并在可能时使用工作区相对的 `sourcePath`。绝对操作加载路径仍保存在 `plugins.load.paths`；安装记录会避免把本地工作站路径重复写入长期配置。这让本地开发安装对源平面诊断保持可见，同时不会增加第二个原始文件系统路径披露界面。持久化的 `plugins/installs.json` 插件索引是安装信息的事实来源，并且可以在不加载插件运行时模块的情况下刷新。即使插件清单缺失或无效，它的 `installRecords` 映射也是持久的；它的 `plugins` 数组是可重建的清单视图。
## 上下文引擎插件
上下文引擎插件拥有用于摄取、组装和压缩的会话上下文编排。使用 `api.registerContextEngine(id, factory)` 从你的插件注册它们，然后用 `plugins.slots.contextEngine` 选择活动引擎。
上下文引擎插件拥有用于摄取、组装和压缩的会话上下文编排。从你的插件中使用 `api.registerContextEngine(id, factory)` 注册它们，然后用 `plugins.slots.contextEngine` 选择活跃引擎。
当你的插件需要替换或扩展默认上下文管线，而不只是添加记忆搜索或钩子时，请使用这个能力。
当你的插件需要替换或扩展默认上下文流水线，而不是只添加记忆搜索或钩子时，请使用它。
```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
@ -790,9 +822,9 @@ export default function (api) {
}
```
工厂的 `ctx` 会暴露可选的 `config`、`agentDir` 和 `workspaceDir` 值，用于构造时初始化。
工厂的 `ctx` 会公开可选的 `config`、`agentDir` 和 `workspaceDir` 值，用于构造时初始化。
如果你的引擎**不**拥有压缩算法，请保留 `compact()` 实现并显式委托它：
如果你的引擎**不**拥有压缩算法，请保留 `compact()` 实现并显式委托：
```ts
import {
@ -833,33 +865,33 @@ export default function (api) {
推荐顺序：
1. 定义 Core 合同
决定 Core 应该拥有哪些共享行为：策略、回退、配置合并、生命周期、面向渠道的语义，以及运行时 helper 形状。
2. 添加类型化插件注册/运行时表面
用最小可用的类型化能力表面扩展 `OpenClawPluginApi` 和/或 `api.runtime`。
3. 连接 Core + 渠道/功能消费者
渠道和功能插件应通过 Core 消费新能力，而不是直接导入某个供应商实现。
1. 定义核心契约
决定核心应拥有哪些共享行为：策略、回退、配置合并、生命周期、面向渠道的语义，以及运行时辅助工具形态。
2. 添加类型化插件注册/运行时接口
使用最小可用的类型化能力接口扩展 `OpenClawPluginApi` 和/或 `api.runtime`。
3. 连接核心 + 渠道/功能消费者
渠道和功能插件应通过核心使用新能力，而不是直接导入某个供应商实现。
4. 注册供应商实现
然后供应商插件将它们的后端注册到该能力。
5. 添加合同覆盖
添加测试，让所有权和注册形状随着时间保持显式。
然后供应商插件针对该能力注册其后端。
5. 添加契约覆盖
添加测试，让所有权和注册形态长期保持明确。
这就是 OpenClaw 保持有主张但又不硬编码到某一个提供商世界观的方式。请参阅[能力扩展手册](/zh-CN/plugins/architecture)，了解具体文件清单和完整示例。
这就是 OpenClaw 在保持有主见的同时，不会硬编码到某个提供商世界观的方式。请参阅[能力扩展手册](/zh-CN/plugins/architecture)，了解具体文件检查清单和完整示例。
### 能力检查清单
添加新能力时，实现通常应同时触及这些表面：
添加新能力时，通常应同时触及这些接口：
- `src/<capability>/types.ts` 中的 Core 合同类型
- `src/<capability>/runtime.ts` 中的 Core runner/运行时 helper
- `src/plugins/types.ts` 中的插件 API 注册表面
- `src/plugins/registry.ts` 中的插件注册表连接
- 当功能/渠道插件需要消费它时，`src/plugins/runtime/*` 中的插件运行时暴露
- `src/test-utils/plugin-registration.ts` 中的捕获/测试 helper
- `src/plugins/contracts/registry.ts` 中的所有权/合同断言
- `src/<capability>/types.ts` 中的核心契约类型
- `src/<capability>/runtime.ts` 中的核心运行器/运行时辅助工具
- `src/plugins/types.ts` 中的插件 API 注册接口
- `src/plugins/registry.ts` 中的插件注册表接线
- 当功能/渠道插件需要使用它时，`src/plugins/runtime/*` 中的插件运行时暴露
- `src/test-utils/plugin-registration.ts` 中的捕获/测试辅助工具
- `src/plugins/contracts/registry.ts` 中的所有权/契约断言
- `docs/` 中的操作员/插件文档
如果缺少其中某个表面，通常说明该能力尚未完全集成。
如果缺少其中某个接口，通常说明该能力尚未完全集成。
### 能力模板
@ -889,7 +921,7 @@ const clip = await api.runtime.videoGeneration.generate({
});
```
合同测试模式：
契约测试模式：
```ts
expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
@ -897,14 +929,14 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
这让规则保持简单：
- Core 拥有能力合同 + 编排
- 核心拥有能力契约 + 编排
- 供应商插件拥有供应商实现
- 功能/渠道插件消费运行时 helper
- 合同测试让所有权保持显式
- 功能/渠道插件使用运行时辅助工具
- 契约测试让所有权保持明确
## 相关内容
## 相关
- [插件架构](/zh-CN/plugins/architecture) — 公共能力模型和形状
- [插件架构](/zh-CN/plugins/architecture) — 公共能力模型和形态
- [插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)
- [插件 SDK 设置](/zh-CN/plugins/sdk-setup)
- [构建插件](/zh-CN/plugins/building-plugins)

305
docs/zh-CN/providers/ollama.md
View File

@ -6,41 +6,41 @@ read_when:
summary: 使用 Ollama 运行 OpenClaw（云端和本地模型）
title: Ollama
x-i18n:
generated_at: "2026-04-28T17:56:08Z"
generated_at: "2026-04-29T03:44:25Z"
model: gpt-5.5
provider: openai
source_hash: fd2e2a7ceba03f60cb43c0e9407603a7b661791cd03d55a805a9598ee089ac48
source_hash: 6eeaebc0ba72f72a0dee842f7d983a552c86cfa23271322d4740641124f57cfb
source_path: providers/ollama.md
workflow: 16
---
OpenClaw 通过 Ollama 原生 API（`/api/chat`）集成托管云模型和本地/自托管 Ollama 服务器。你可以在三种模式下使用 Ollama：通过可访问的 Ollama 主机使用 `Cloud + Local`，针对 `https://ollama.com` 使用 `Cloud only`，或针对可访问的 Ollama 主机使用 `Local only`。
OpenClaw 与 Ollama 的原生 API（`/api/chat`）集成，可用于托管云模型以及本地/自托管 Ollama 服务器。你可以通过三种模式使用 Ollama：通过可访问的 Ollama 主机使用 `Cloud + Local`，针对 `https://ollama.com` 使用 `Cloud only`，或针对可访问的 Ollama 主机使用 `Local only`。
<Warning>
**远程 Ollama 用户**：不要在 OpenClaw 中使用 `/v1` OpenAI 兼容 URL（`http://host:11434/v1`）。这会破坏工具调用，模型可能会把原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL：`baseUrl: "http://host:11434"`（没有 `/v1`）。
**远程 Ollama 用户**：不要在 OpenClaw 中使用 `/v1` OpenAI 兼容 URL（`http://host:11434/v1`）。这会破坏工具调用，模型可能会把原始工具 JSON 当作纯文本输出。请改用原生 Ollama API URL：`baseUrl: "http://host:11434"`（不带 `/v1`）。
</Warning>
Ollama 提供商配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 `baseURL`，以兼容 OpenAI SDK 风格的示例，但新配置应优先使用 `baseUrl`。
Ollama provider 配置使用 `baseUrl` 作为规范键名。为兼容 OpenAI SDK 风格的示例，OpenClaw 也接受 `baseURL`，但新配置应优先使用 `baseUrl`。
## 凭证规则
<AccordionGroup>
<Accordion title="本地和局域网主机">
本地和局域网 Ollama 主机不需要真实 bearer token。OpenClaw 只会针对 loopback、私有网络、`.local` 和裸主机名 Ollama base URL 使用本地 `ollama-local` 标记。
<Accordion title="本地和 LAN 主机">
本地和 LAN Ollama 主机不需要真实的 bearer token。OpenClaw 仅对 loopback、私有网络、`.local` 和裸主机名 Ollama base URL 使用本地 `ollama-local` 标记。
</Accordion>
<Accordion title="远程和 Ollama Cloud 主机">
远程公共主机和 Ollama Cloud（`https://ollama.com`）需要通过 `OLLAMA_API_KEY`、凭证配置文件或提供商的 `apiKey` 提供真实凭证。
远程公共主机和 Ollama Cloud（`https://ollama.com`）需要通过 `OLLAMA_API_KEY`、凭证配置档或 provider 的 `apiKey` 提供真实凭证。
</Accordion>
<Accordion title="自定义提供商 id">
设置了 `api: "ollama"` 的自定义提供商 id 遵循相同规则。例如，指向私有局域网 Ollama 主机的 `ollama-remote` 提供商可以使用 `apiKey: "ollama-local"`，子智能体会通过 Ollama 提供商钩子解析该标记，而不是把它当作缺失凭证处理。Memory 搜索也可以把 `agents.defaults.memorySearch.provider` 设为该自定义提供商 id，让嵌入使用匹配的 Ollama 端点。
<Accordion title="自定义 provider id">
设置了 `api: "ollama"` 的自定义 provider id 遵循相同规则。例如，指向私有 LAN Ollama 主机的 `ollama-remote` provider 可以使用 `apiKey: "ollama-local"`，子智能体会通过 Ollama provider 钩子解析该标记，而不是将其视为缺失凭证。记忆搜索也可以将 `agents.defaults.memorySearch.provider` 设置为该自定义 provider id，以便嵌入使用匹配的 Ollama 端点。
</Accordion>
<Accordion title="凭证配置文件">
`auth-profiles.json` 存储提供商 id 的凭证。请将端点设置（`baseUrl`、`api`、模型 id、headers、timeouts）放在 `models.providers.<id>` 中。较旧的扁平凭证配置文件，例如 `{ "ollama-windows": { "apiKey": "ollama-local" } }`，不是运行时格式；运行 `openclaw doctor --fix` 可将其重写为规范的 `ollama-windows:default` API-key 配置文件，并生成备份。该文件中的 `baseUrl` 是兼容性噪声，应移至提供商配置。
<Accordion title="凭证配置档">
`auth-profiles.json` 存储 provider id 的凭证。将端点设置（`baseUrl`、`api`、model id、headers、timeouts）放在 `models.providers.<id>` 中。较旧的扁平凭证配置档文件，例如 `{ "ollama-windows": { "apiKey": "ollama-local" } }`，不是运行时格式；运行 `openclaw doctor --fix` 可将其重写为规范的 `ollama-windows:default` API-key 配置档并创建备份。该文件中的 `baseUrl` 是兼容性噪音，应移到 provider 配置中。
</Accordion>
<Accordion title="Memory 嵌入范围">
当 Ollama 用于 Memory 嵌入时，bearer 凭证的作用域限定在声明它的主机：
<Accordion title="记忆嵌入范围">
当 Ollama 用于记忆嵌入时，bearer 身份验证的作用域限定为声明它的主机：
- 提供商级别的 key 只会发送到该提供商的 Ollama 主机。
- provider 级密钥只会发送到该 provider 的 Ollama 主机。
- `agents.*.memorySearch.remote.apiKey` 只会发送到其远程嵌入主机。
- 纯 `OLLAMA_API_KEY` 环境变量值会被视为 Ollama Cloud 约定，默认不会发送到本地或自托管主机。
@ -61,16 +61,16 @@ Ollama 提供商配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 `
openclaw onboard
```
从提供商列表中选择 **Ollama**。
从 provider 列表中选择 **Ollama**。
</Step>
<Step title="选择你的模式">
- **Cloud + Local** — 本地 Ollama 主机，加上通过该主机路由的云模型
- **Cloud + Local** — 本地 Ollama 主机加上通过该主机路由的云模型
- **Cloud only** — 通过 `https://ollama.com` 使用托管 Ollama 模型
- **Local only** — 仅本地模型
- **Local only** — 仅使用本地模型
</Step>
<Step title="选择模型">
`Cloud only` 会提示输入 `OLLAMA_API_KEY`，并建议托管云端默认值。`Cloud + Local` 和 `Local only` 会要求提供 Ollama base URL，发现可用模型，并在选定的本地模型尚不可用时自动拉取该模型。当 Ollama 报告已安装的 `:latest` 标签（例如 `gemma4:latest`）时，设置只显示该已安装模型一次，而不是同时显示 `gemma4` 和 `gemma4:latest`，也不会再次拉取裸别名。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以获得云端访问权限。
`Cloud only` 会提示输入 `OLLAMA_API_KEY` 并建议托管云端默认值。`Cloud + Local` 和 `Local only` 会要求提供 Ollama base URL，发现可用模型，并在所选本地模型尚不可用时自动拉取。若 Ollama 报告了已安装的 `:latest` 标签，例如 `gemma4:latest`，设置过程只会显示该已安装模型一次，而不会同时显示 `gemma4` 和 `gemma4:latest`，也不会再次拉取裸别名。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以获取云端访问权限。
</Step>
<Step title="验证模型可用">
```bash
@ -87,7 +87,7 @@ Ollama 提供商配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 `
--accept-risk
```
可选地指定自定义 base URL 或模型：
也可以指定自定义 base URL 或模型：
```bash
openclaw onboard --non-interactive \
@ -119,7 +119,7 @@ Ollama 提供商配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 `
```
</Step>
<Step title="为 OpenClaw 启用 Ollama">
对于 `Cloud only`，使用你的真实 `OLLAMA_API_KEY`。对于由主机支撑的设置，任何占位值都可以：
对于 `Cloud only`，使用你的真实 `OLLAMA_API_KEY`。对于由主机支持的设置，任何占位符值都可用：
```bash
# Cloud
@ -161,43 +161,48 @@ Ollama 提供商配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 `
<Tab title="Cloud + Local">
`Cloud + Local` 使用可访问的 Ollama 主机作为本地模型和云模型的控制点。这是 Ollama 偏好的混合流程。
在设置期间使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama base URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以获得云端访问权限。当主机已登录时，OpenClaw 还会建议托管云端默认值，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。
在设置期间使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama base URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以获取云端访问权限。当主机已登录时，OpenClaw 还会建议托管云端默认值，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。
如果主机尚未登录，OpenClaw 会保持设置为仅本地，直到你运行 `ollama signin`。
如果主机尚未登录，OpenClaw 会让设置保持为仅本地，直到你运行 `ollama signin`。
</Tab>
<Tab title="Cloud only">
`Cloud only` 针对 Ollama 在 `https://ollama.com` 的托管 API 运行。
`Cloud only` 针对 Ollama 托管 API `https://ollama.com` 运行。
在设置期间使用 **Cloud only**。OpenClaw 会提示输入 `OLLAMA_API_KEY`，设置 `baseUrl: "https://ollama.com"`，并填充托管云模型列表。此路径**不**需要本地 Ollama 服务器或 `ollama signin`。
`openclaw onboard` 期间显示的云模型列表会从 `https://ollama.com/api/tags` 实时填充，上限为 500 条，因此选择器反映的是当前托管目录，而不是静态种子。如果设置时无法访问 `ollama.com` 或它未返回任何模型，OpenClaw 会回退到之前的硬编码建议，确保新手引导仍可完成。
`openclaw onboard` 期间显示的云模型列表会从 `https://ollama.com/api/tags` 实时填充，上限为 500 条，因此选择器反映的是当前托管目录，而不是静态种子。如果 `ollama.com` 在设置时无法访问或未返回模型，OpenClaw 会回退到之前的硬编码建议，确保新手引导仍能完成。
</Tab>
<Tab title="Local only">
在仅本地模式下，OpenClaw 会从已配置的 Ollama 实例发现模型。此路径适用于本地或自托管 Ollama 服务器。
OpenClaw 当前建议使用 `gemma4` 作为本地默认值。
OpenClaw 当前建议 `gemma4` 作为本地默认值。
</Tab>
</Tabs>
## 模型发现（隐式提供商）
## 模型发现（隐式 provider）
当你设置 `OLLAMA_API_KEY`（或凭证配置文件）并且**没有**定义 `models.providers.ollama` 或其他带有 `api: "ollama"` 的自定义远程提供商时，OpenClaw 会从位于 `http://127.0.0.1:11434` 的本地 Ollama 实例发现模型。
当你设置 `OLLAMA_API_KEY`（或凭证配置档）并且**没有**定义 `models.providers.ollama` 或另一个带有 `api: "ollama"` 的自定义远程 provider 时，OpenClaw 会从 `http://127.0.0.1:11434` 的本地 Ollama 实例发现模型。
| 行为 | 详情 |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 目录查询 | 查询 `/api/tags` |
| 能力检测 | 使用 best-effort `/api/show` 查找读取 `contextWindow`、展开的 `num_ctx` Modelfile 参数，以及包括视觉/工具在内的能力 |
| 视觉模型 | `/api/show` 报告具有 `vision` 能力的模型会标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图像注入提示词 |
| 推理检测 | 可用时使用 `/api/show` 能力，包括 `thinking`；当 Ollama 省略能力时，回退到模型名称启发式规则（`r1`、`reasoning`、`think`） |
| Token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama max-token 上限 |
| 成本 | 将所有成本设置为 `0` |
| 能力检测 | 尽力使用 `/api/show` 查询来读取 `contextWindow`、展开后的 `num_ctx` Modelfile 参数，以及包括视觉/工具在内的能力 |
| 视觉模型 | `/api/show` 报告具有 `vision` 能力的模型会被标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图像注入到提示词中 |
| 推理检测 | 可用时使用 `/api/show` 能力，包括 `thinking`；当 Ollama 省略能力时，回退到模型名称启发式规则（`r1`、`reasoning`、`think`） |
| Token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 |
| 成本 | 将所有成本设置为 `0` |
这避免了手动模型条目，同时让目录与本地 Ollama 实例保持一致。你可以在本地 `infer model run` 中使用完整引用，例如 `ollama/<pulled-model>:latest`；OpenClaw 会从 Ollama 的实时目录解析该已安装模型，而不需要手写 `models.json` 条目。
这样可以避免手动模型条目，同时让目录与本地 Ollama 实例保持一致。你可以在本地 `infer model run` 中使用完整引用，例如 `ollama/<pulled-model>:latest`；OpenClaw 会从 Ollama 的实时目录解析该已安装模型，而无需手写 `models.json` 条目。
对于已登录的 Ollama 主机，一些 `:cloud` 模型可能在出现在 `/api/tags` 之前，就已经可以通过 `/api/chat`
和 `/api/show` 使用。当你显式选择完整的 `ollama/<model>:cloud` 引用时，OpenClaw 会用
`/api/show` 验证该精确缺失模型，并且只有在 Ollama 确认模型
元数据时，才将其加入运行时目录。拼写错误仍会作为未知模型失败，而不会被自动创建。
```bash
# See what models are available
@ -206,7 +211,7 @@ openclaw models list
```
对于避开完整智能体工具表面的窄文本生成冒烟测试，
请使用带完整 Ollama 模型引用的本地 `infer model run`：
请使用带有完整 Ollama 模型引用的本地 `infer model run`：
```bash
OLLAMA_API_KEY=ollama-local \
@ -217,14 +222,14 @@ OLLAMA_API_KEY=ollama-local \
--json
```
该路径仍然使用 OpenClaw 已配置的提供商、凭证和原生 Ollama
该路径仍使用 OpenClaw 已配置的 provider、凭证和原生 Ollama
传输协议，但不会启动聊天智能体轮次，也不会加载 MCP/工具上下文。如果
此路径成功而普通智能体回复失败，请接着排查模型的智能体
此路径成功而普通智能体回复失败，接下来请排查该模型的智能体
提示词/工具容量。
对于同一精简路径上的窄视觉模型冒烟测试，请向 `infer model run` 添加一个或多个
图像文件。这会将提示词和图像直接发送到
所选 Ollama 视觉模型，而不会加载聊天工具、Memory 或先前的
对于同一精简路径上的窄视觉模型冒烟测试，请向
`infer model run` 添加一个或多个图像文件。这会将提示词和图像直接发送到
所选 Ollama 视觉模型，而不会加载聊天工具、记忆或先前
会话上下文：
```bash
@ -238,22 +243,17 @@ OLLAMA_API_KEY=ollama-local \
```
`model run --file` 接受检测为 `image/*` 的文件，包括常见 PNG、
JPEG 和 WebP 输入。非图像文件会在调用 Ollama 前被拒绝。
JPEG 和 WebP 输入。非图像文件会在调用 Ollama 之前被拒绝。
对于语音识别，请改用 `openclaw infer audio transcribe`。
当你使用 `/model ollama/<model>` 切换会话时，OpenClaw 会将
其视为精确的用户选择。如果已配置的 Ollama `baseUrl`
无法访问，下一次回复会失败并返回提供商错误，而不是静默地
不可访问，下一条回复会因 provider 错误而失败，而不是静默
从另一个已配置的回退模型回答。
隔离的 cron 作业在启动智能体轮次前会额外执行一次本地安全检查。
如果所选模型解析到本地、私有网络或 `.local`
Ollama 提供商，而 `/api/tags` 无法访问，OpenClaw 会将该 cron 运行
记录为 `skipped`，并在错误文本中包含所选的 `ollama/<model>`。端点
预检会缓存 5 分钟，因此指向同一个已停止 Ollama daemon 的多个 cron 作业
不会全部发起失败的模型请求。
隔离的 cron 作业在启动智能体轮次前会额外执行一次本地安全检查。如果选定的模型解析到 local、私有网络或 `.local` Ollama 提供商，并且 `/api/tags` 无法访问，OpenClaw 会将该 cron 运行记录为 `skipped`，并在错误文本中包含选定的 `ollama/<model>`。端点预检会缓存 5 分钟，因此指向同一个已停止 Ollama 守护进程的多个 cron 作业不会全部发起失败的模型请求。
使用以下命令针对本地 Ollama 实时验证本地文本路径、原生流式传输路径和嵌入：
使用以下命令针对本地 Ollama 实时验证本地文本路径、原生流路径和嵌入：
```bash
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
@ -266,24 +266,24 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
ollama pull mistral
```
新模型会被自动发现，并可供使用。
新模型会被自动发现并可供使用。
<Note>
如果你显式设置 `models.providers.ollama`，或配置自定义远程提供商，例如带有 `api: "ollama"` 的 `models.providers.ollama-cloud`，则会跳过自动发现，并且你必须手动定义模型。像 `http://127.0.0.2:11434` 这样的 loopback 自定义提供商仍会被视为本地提供商。请参阅下面的显式配置部分。
如果你显式设置 `models.providers.ollama`，或配置自定义远程提供商，例如带有 `api: "ollama"` 的 `models.providers.ollama-cloud`，则会跳过自动发现，你必须手动定义模型。像 `http://127.0.0.2:11434` 这样的回环自定义提供商仍会被视为本地。请参阅下面的显式配置部分。
</Note>
## 视觉和图像描述
内置的 Ollama 插件会将 Ollama 注册为支持图像的媒体理解提供商。这样，OpenClaw 就可以将显式图像描述请求以及已配置的图像模型默认值路由到本地或托管的 Ollama 视觉模型。
内置的 Ollama 插件会将 Ollama 注册为支持图像的媒体理解提供商。这让 OpenClaw 可以通过本地或托管的 Ollama 视觉模型来路由显式图像描述请求和已配置的图像模型默认值。
对于本地视觉，请拉取支持图像的模型：
对于本地视觉，请拉取一个支持图像的模型：
```bash
ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"
```
然后用 infer CLI 验证：
然后使用 infer CLI 验证：
```bash
openclaw infer image describe \
@ -292,9 +292,9 @@ openclaw infer image describe \
--json
```
`--model` 必须是完整的 `<provider/model>` 引用。设置后，`openclaw infer image describe` 会直接运行该模型，而不会因为模型支持原生视觉而跳过描述。
`--model` 必须是完整的 `<provider/model>` 引用。设置后，`openclaw infer image describe` 会直接运行该模型，而不是因为模型支持原生视觉而跳过描述。
当你想使用 OpenClaw 的图像理解提供商流程、已配置的 `agents.defaults.imageModel` 以及图像描述输出结构时，请使用 `infer image describe`。当你想用自定义提示词和一张或多张图像进行原始多模态模型探测时，请使用 `infer model run --file`。
当你需要 OpenClaw 的图像理解提供商流程、已配置的 `agents.defaults.imageModel` 以及图像描述输出形状时，请使用 `infer image describe`。当你需要使用自定义提示词和一张或多张图像来原始探测多模态模型时，请使用 `infer model run --file`。
要让 Ollama 成为入站媒体的默认图像理解模型，请配置 `agents.defaults.imageModel`：
@ -310,9 +310,9 @@ openclaw infer image describe \
}
```
优先使用完整的 `ollama/<model>` 引用。如果同一模型列在 `models.providers.ollama.models` 下，带有 `input: ["text", "image"]`，并且没有其他已配置的图像提供商暴露该裸模型 ID，OpenClaw 也会将像 `qwen2.5vl:7b` 这样的裸 `imageModel` 引用规范化为 `ollama/qwen2.5vl:7b`。如果多个已配置的图像提供商拥有相同的裸 ID，请显式使用提供商前缀。
优先使用完整的 `ollama/<model>` 引用。如果同一模型列在 `models.providers.ollama.models` 下，且带有 `input: ["text", "image"]`，并且没有其他已配置的图像提供商暴露相同的裸模型 ID，OpenClaw 也会把像 `qwen2.5vl:7b` 这样的裸 `imageModel` 引用规范化为 `ollama/qwen2.5vl:7b`。如果多个已配置的图像提供商拥有相同的裸 ID，请显式使用提供商前缀。
较慢的本地视觉模型可能需要比云端模型更长的图像理解超时时间。当 Ollama 试图在受限硬件上分配完整声明的视觉上下文时，它们也可能崩溃或停止。设置能力超时，并在你只需要一次普通图像描述轮次时，在模型条目上限制 `num_ctx`：
慢速本地视觉模型可能需要比云模型更长的图像理解超时时间。当 Ollama 尝试在受限硬件上分配完整声明的视觉上下文时，它们也可能崩溃或停止。设置能力超时，并在你只需要普通图像描述轮次时，在模型条目上限制 `num_ctx`：
```json5
{
@ -341,16 +341,16 @@ openclaw infer image describe \
}
```
此超时适用于入站图像理解，也适用于智能体在轮次中可以调用的显式 `image` 工具。提供商级别的 `models.providers.ollama.timeoutSeconds` 仍会控制普通模型调用底层 Ollama HTTP 请求的保护超时。
此超时适用于入站图像理解，也适用于智能体在轮次中可调用的显式 `image` 工具。提供商级别的 `models.providers.ollama.timeoutSeconds` 仍控制普通模型调用底层 Ollama HTTP 请求的保护超时。
使用以下命令对本地 Ollama 实时验证显式图像工具：
使用以下命令针对本地 Ollama 实时验证显式图像工具：
```bash
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.ts
```
如果你手动定义 `models.providers.ollama.models`，请用图像输入支持标记视觉模型：
如果你手动定义 `models.providers.ollama.models`，请将视觉模型标记为支持图像输入：
```json5
{
@ -362,12 +362,12 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
}
```
OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使用隐式发现时，当 `/api/show` 报告视觉能力时，OpenClaw 会从 Ollama 读取这一点。
OpenClaw 会拒绝未标记为支持图像能力的模型的图像描述请求。使用隐式发现时，当 `/api/show` 报告视觉能力时，OpenClaw 会从 Ollama 读取此信息。
## 配置
<Tabs>
<Tab title="基础（隐式发现）">
<Tab title="Basic (implicit discovery)">
最简单的仅本地启用路径是通过环境变量：
```bash
@ -380,8 +380,8 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
</Tab>
<Tab title="显式（手动模型）">
当你想要托管云端设置、Ollama 运行在另一台主机或端口上、想强制指定特定上下文窗口或模型列表，或想完全手动定义模型时，请使用显式配置。
<Tab title="Explicit (manual models)">
当你需要托管云设置、Ollama 运行在另一台主机或端口上、想强制指定特定上下文窗口或模型列表，或想完全手动定义模型时，请使用显式配置。
```json5
{
@ -410,8 +410,8 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
</Tab>
<Tab title="自定义基础 URL">
如果 Ollama 运行在不同的主机或端口上（显式配置会禁用自动发现，因此请手动定义模型）：
<Tab title="Custom base URL">
如果 Ollama 在不同主机或端口上运行（显式配置会禁用自动发现，因此需要手动定义模型）：
```json5
{
@ -419,15 +419,15 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
providers: {
ollama: {
apiKey: "ollama-local",
baseUrl: "http://ollama-host:11434", // 无 /v1 - 使用原生 Ollama API URL
api: "ollama", // 显式设置以保证原生工具调用行为
timeoutSeconds: 300, // 可选：给冷启动本地模型更长时间来连接和流式传输
baseUrl: "http://ollama-host:11434", // No /v1 - use native Ollama API URL
api: "ollama", // Set explicitly to guarantee native tool-calling behavior
timeoutSeconds: 300, // Optional: give cold local models longer to connect and stream
models: [
{
id: "qwen3:32b",
name: "qwen3:32b",
params: {
keep_alive: "15m", // 可选：在轮次之间保持模型加载
keep_alive: "15m", // Optional: keep the model loaded between turns
},
},
],
@ -438,7 +438,7 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
```
<Warning>
不要向 URL 添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用不可靠。请使用没有路径后缀的 Ollama 基础 URL。
不要向 URL 添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用不可靠。请使用不带路径后缀的基础 Ollama URL。
</Warning>
</Tab>
@ -446,11 +446,11 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
## 常见配方
将这些用作起点，并用 `ollama list` 或 `openclaw models list --provider ollama` 中的确切名称替换模型 ID。
将这些作为起点，并将模型 ID 替换为 `ollama list` 或 `openclaw models list --provider ollama` 中的准确名称。
<AccordionGroup>
<Accordion title="带自动发现的本地模型">
当 Ollama 与 Gateway 网关运行在同一台机器上，并且你希望 OpenClaw 自动发现已安装模型时，请使用此配置。
<Accordion title="Local model with auto-discovery">
当 Ollama 与 Gateway 网关运行在同一台机器上，并且你希望 OpenClaw 自动发现已安装的模型时，请使用此配置。
```bash
ollama serve
@ -460,12 +460,12 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
openclaw models set ollama/gemma4
```
此路径让配置保持最小化。除非你想手动定义模型，否则不要添加 `models.providers.ollama` 块。
此路径会让配置保持最小化。除非你想手动定义模型，否则不要添加 `models.providers.ollama` 块。
</Accordion>
<Accordion title="带手动模型的 LAN Ollama 主机">
对 LAN 主机使用原生 Ollama URL。不要添加 `/v1`。
<Accordion title="LAN Ollama host with manual models">
对于 LAN 主机，请使用原生 Ollama URL。不要添加 `/v1`。
```json5
{
@ -502,12 +502,12 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
}
```
`contextWindow` 是 OpenClaw 侧的上下文预算。`params.num_ctx` 会随请求发送给 Ollama。当你的硬件无法运行该模型完整声明的上下文时，请保持它们一致。
`contextWindow` 是 OpenClaw 侧的上下文预算。`params.num_ctx` 会随请求发送给 Ollama。当你的硬件无法运行模型完整声明的上下文时，请保持二者一致。
</Accordion>
<Accordion title="仅 Ollama Cloud">
当你不运行本地守护进程，并想直接使用托管 Ollama 模型时，请使用此配置。
<Accordion title="Ollama Cloud only">
当你不运行本地守护进程并希望直接使用托管的 Ollama 模型时，请使用此配置。
```bash
export OLLAMA_API_KEY="your-ollama-api-key"
@ -544,8 +544,8 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
</Accordion>
<Accordion title="通过已登录守护进程同时使用云端和本地">
当本地或 LAN Ollama 守护进程已通过 `ollama signin` 登录，并且应同时提供本地模型和 `:cloud` 模型时，请使用此配置。
<Accordion title="Cloud plus local through a signed-in daemon">
当本地或 LAN Ollama 守护进程已通过 `ollama signin` 登录，并且应同时服务本地模型和 `:cloud` 模型时，请使用此配置。
```bash
ollama signin
@ -581,7 +581,7 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
</Accordion>
<Accordion title="多个 Ollama 主机">
<Accordion title="Multiple Ollama hosts">
当你有多个 Ollama 服务器时，请使用自定义提供商 ID。每个提供商都有自己的主机、模型、认证、超时和模型引用。
```json5
@ -617,12 +617,12 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
}
```
当 OpenClaw 发送请求时，会剥离活动提供商前缀，因此 `ollama-large/qwen3.5:27b` 会以 `qwen3.5:27b` 的形式到达 Ollama。
当 OpenClaw 发送请求时，会剥离活动提供商前缀，因此 `ollama-large/qwen3.5:27b` 会以 `qwen3.5:27b` 到达 Ollama。
</Accordion>
<Accordion title="精简本地模型配置">
一些本地模型可以回答简单提示词，但难以处理完整的智能体工具表面。先限制工具和上下文，再考虑更改全局运行时设置。
<Accordion title="Lean local model profile">
有些本地模型可以回答简单提示词，但难以处理完整的智能体工具表面。请先限制工具和上下文，再更改全局运行时设置。
```json5
{
@ -656,7 +656,7 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
}
```
只有当模型或服务器在工具 schema 上稳定失败时，才使用 `compat.supportsTools: false`。这会用智能体能力换取稳定性。
仅当模型或服务器在工具 schema 上会可靠失败时，才使用 `compat.supportsTools: false`。它会用智能体能力换取稳定性。
`localModelLean` 会从智能体表面移除浏览器、cron 和消息工具，但它不会改变 Ollama 的运行时上下文或思考模式。对于会循环或把响应预算花在隐藏推理上的小型 Qwen 风格思考模型，请将它与显式的 `params.num_ctx` 和 `params.thinking: false` 搭配使用。
</Accordion>
@ -679,9 +679,9 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
}
```
也支持自定义 Ollama 提供商 ID。当模型引用使用当前激活的提供商前缀时，例如 `ollama-spark/qwen3:32b`，OpenClaw 在调用 Ollama 前只会剥离该前缀，因此服务器会收到 `qwen3:32b`。
也支持自定义 Ollama 提供商 ID。当模型引用使用活动提供商前缀时，例如 `ollama-spark/qwen3:32b`，OpenClaw 只会在调用 Ollama 前剥离该前缀，因此服务器会收到 `qwen3:32b`。
对于较慢的本地模型，优先使用按提供商作用域的请求调优，再考虑提高整个智能体运行时超时：
对于较慢的本地模型，优先使用提供商范围的请求调优，然后再提高整个智能体运行时超时时间：
```json5
{
@ -702,7 +702,7 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。使
}
```
`timeoutSeconds` 适用于模型 HTTP 请求，包括连接建立、headers、正文流式传输以及整个受保护 fetch 的中止控制。`params.keep_alive` 会在原生 `/api/chat` 请求中作为顶层 `keep_alive` 转发给 Ollama；当首轮加载时间是瓶颈时，请按模型设置它。
`timeoutSeconds` 适用于模型 HTTP 请求，包括连接建立、标头、正文流式传输，以及受保护抓取的总中止时间。`params.keep_alive` 会在原生 `/api/chat` 请求中作为顶层 `keep_alive` 转发给 Ollama；当首轮加载时间是瓶颈时，请按模型设置它。
### 快速验证
@ -720,7 +720,7 @@ openclaw infer model run \
--prompt "Reply with exactly: ok"
```
对于远程主机，请将 `127.0.0.1` 替换为 `baseUrl` 中使用的主机。如果 `curl` 可用但 OpenClaw 不可用，请检查 Gateway 网关是否运行在另一台机器、容器或服务账号下。
对于远程主机，将 `127.0.0.1` 替换为 `baseUrl` 中使用的主机。如果 `curl` 正常但 OpenClaw 不正常，请检查 Gateway 网关是否运行在另一台机器、容器或服务账号下。
## Ollama Web 搜索
@ -728,11 +728,11 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
| 属性 | 详情 |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 主机 | 使用你配置的 Ollama 主机（设置后使用 `models.providers.ollama.baseUrl`，否则使用 `http://127.0.0.1:11434`）；`https://ollama.com` 会直接使用托管 API |
| 凭证 | 已登录的本地 Ollama 主机无需密钥；直接通过 `https://ollama.com` 搜索或使用受凭证保护的主机时，使用 `OLLAMA_API_KEY` 或已配置的提供商凭证 |
| 主机 | 使用你配置的 Ollama 主机（设置了 `models.providers.ollama.baseUrl` 时使用它，否则使用 `http://127.0.0.1:11434`）；`https://ollama.com` 会直接使用托管 API |
| 凭证 | 对已登录的本地 Ollama 主机无需密钥；对直接 `https://ollama.com` 搜索或受凭证保护的主机，使用 `OLLAMA_API_KEY` 或已配置的提供商凭证 |
| 要求 | 本地/自托管主机必须正在运行并已通过 `ollama signin` 登录；直接托管搜索需要 `baseUrl: "https://ollama.com"` 加真实的 Ollama API 密钥 |
在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 **Ollama Web 搜索**，或者设置：
在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 **Ollama Web 搜索**，或设置：
```json5
{
@ -746,7 +746,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
}
```
如需通过 Ollama Cloud 直接托管搜索：
要通过 Ollama Cloud 进行直接托管搜索：
```json5
{
@ -768,7 +768,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
}
```
对于已登录的本地 daemon，OpenClaw 使用该 daemon 的 `/api/experimental/web_search` 代理。对于 `https://ollama.com`，它会直接调用托管的 `/api/web_search` 端点。
对于已登录的本地守护进程，OpenClaw 会使用该守护进程的 `/api/experimental/web_search` 代理。对于 `https://ollama.com`，它会直接调用托管的 `/api/web_search` 端点。
<Note>
有关完整设置和行为详情，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。
@ -777,12 +777,12 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
## 高级配置
<AccordionGroup>
<Accordion title="Legacy OpenAI-compatible mode">
<Accordion title="旧版 OpenAI 兼容模式">
<Warning>
**在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为代理使用 OpenAI 格式且不依赖原生工具调用行为时，才使用此模式。
**在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为代理使用 OpenAI 格式，且不依赖原生工具调用行为时，才使用此模式。
</Warning>
如果你需要改用 OpenAI 兼容端点（例如位于只支持 OpenAI 格式的代理之后），请显式设置 `api: "openai-completions"`：
如果你需要改用 OpenAI 兼容端点（例如在只支持 OpenAI 格式的代理后面），请显式设置 `api: "openai-completions"`：
```json5
{
@ -800,9 +800,9 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
}
```
此模式可能不支持同时使用流式传输和工具调用。你可能需要在模型配置中通过 `params: { streaming: false }` 禁用流式传输。
此模式可能无法同时支持流式传输和工具调用。你可能需要在模型配置中用 `params: { streaming: false }` 禁用流式传输。
当 `api: "openai-completions"` 与 Ollama 一起使用时，OpenClaw 默认会注入 `options.num_ctx`，这样 Ollama 就不会静默回退到 4096 上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段，请禁用此行为：
当 Ollama 使用 `api: "openai-completions"` 时，OpenClaw 默认会注入 `options.num_ctx`，这样 Ollama 就不会静默回退到 4096 上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段，请禁用此行为：
```json5
{
@ -822,12 +822,12 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
</Accordion>
<Accordion title="Context windows">
对于自动发现的模型，只要 Ollama 报告了上下文窗口，OpenClaw 就会使用该值，包括来自自定义 Modelfile 的更大 `PARAMETER num_ctx` 值。否则，它会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。
<Accordion title="上下文窗口">
对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，包括来自自定义 Modelfile 的更大 `PARAMETER num_ctx` 值。否则，它会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。
你可以为该 Ollama 提供商下的每个模型设置提供商级别的 `contextWindow`、`contextTokens` 和 `maxTokens` 默认值，然后在需要时按模型覆盖它们。`contextWindow` 是 OpenClaw 的提示词和压缩预算。原生 Ollama 请求会保持 `options.num_ctx` 未设置，除非你显式配置 `params.num_ctx`，这样 Ollama 就可以应用它自己的模型、`OLLAMA_CONTEXT_LENGTH` 或基于 VRAM 的默认值。要在不重新构建 Modelfile 的情况下限制或强制 Ollama 的每请求运行时上下文，请设置 `params.num_ctx`；无效、零、负数和非有限值会被忽略。OpenAI 兼容的 Ollama 适配器仍然默认从已配置的 `params.num_ctx` 或 `contextWindow` 注入 `options.num_ctx`；如果你的上游拒绝 `options`，请使用 `injectNumCtxForOpenAICompat: false` 禁用该行为。
你可以为该 Ollama 提供商下的每个模型设置提供商级别的 `contextWindow`、`contextTokens` 和 `maxTokens` 默认值，然后在需要时按模型覆盖它们。`contextWindow` 是 OpenClaw 的提示词和压缩预算。原生 Ollama 请求会保持 `options.num_ctx` 未设置，除非你显式配置 `params.num_ctx`，因此 Ollama 可以应用自己的模型、`OLLAMA_CONTEXT_LENGTH` 或基于 VRAM 的默认值。要在不重建 Modelfile 的情况下限制或强制 Ollama 的每请求运行时上下文，请设置 `params.num_ctx`；无效、零、负数和非有限值会被忽略。OpenAI 兼容的 Ollama 适配器仍会默认根据已配置的 `params.num_ctx` 或 `contextWindow` 注入 `options.num_ctx`；如果你的上游拒绝 `options`，请用 `injectNumCtxForOpenAICompat: false` 禁用它。
原生 Ollama 模型条目也接受 `params` 下的常见 Ollama 运行时选项，包括 `temperature`、`top_p`、`top_k`、`min_p`、`num_predict`、`stop`、`repeat_penalty`、`num_batch`、`num_thread` 和 `use_mmap`。OpenClaw 只转发 Ollama 请求键，因此 `streaming` 等 OpenClaw 运行时参数不会泄漏给 Ollama。使用 `params.think` 或 `params.thinking` 发送顶层 Ollama `think`；`false` 会为 Qwen 风格思考模型禁用 API 级思考。
原生 Ollama 模型条目还接受 `params` 下的常见 Ollama 运行时选项，包括 `temperature`、`top_p`、`top_k`、`min_p`、`num_predict`、`stop`、`repeat_penalty`、`num_batch`、`num_thread` 和 `use_mmap`。OpenClaw 只转发 Ollama 请求键，因此不会把 OpenClaw 运行时参数（如 `streaming`）泄漏给 Ollama。使用 `params.think` 或 `params.thinking` 发送顶层 Ollama `think`；`false` 会为 Qwen 风格的思考模型禁用 API 级别思考。
```json5
{
@ -854,12 +854,12 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
}
```
按模型设置的 `agents.defaults.models["ollama/<model>"].params.num_ctx` 也可用。如果两者都已配置，显式的提供商模型条目会优先于智能体默认值。
按模型设置的 `agents.defaults.models["ollama/<model>"].params.num_ctx` 也可用。如果两者都已配置，显式提供商模型条目优先于智能体默认值。
</Accordion>
<Accordion title="Thinking control">
对于原生 Ollama 模型，OpenClaw 会按 Ollama 预期的方式转发思考控制：使用顶层 `think`，而不是 `options.think`。如果自动发现模型的 `/api/show` 响应包含 `thinking` 能力，则会公开 `/think low`、`/think medium`、`/think high` 和 `/think max`；非思考模型只公开 `/think off`。
<Accordion title="思考控制">
对于原生 Ollama 模型，OpenClaw 会按 Ollama 期望的方式转发思考控制：顶层 `think`，而不是 `options.think`。如果自动发现模型的 `/api/show` 响应包含 `thinking` 能力，则会暴露 `/think low`、`/think medium`、`/think high` 和 `/think max`；非思考模型只会暴露 `/think off`。
```bash
openclaw agent --model ollama/gemma4 --thinking off
@ -882,12 +882,12 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
}
```
按模型设置的 `params.think` 或 `params.thinking` 可以为特定已配置模型禁用或强制 Ollama API 思考。当当前运行只有隐式默认值 `off` 时，OpenClaw 会保留这些显式模型参数；`/think medium` 等非 off 运行时命令仍会覆盖当前运行。
按模型设置的 `params.think` 或 `params.thinking` 可以为特定已配置模型禁用或强制 Ollama API 思考。当活动运行只有隐式默认 `off` 时，OpenClaw 会保留这些显式模型参数；非 off 运行时命令（如 `/think medium`）仍会覆盖活动运行。
</Accordion>
<Accordion title="Reasoning models">
OpenClaw 默认将名称包含 `deepseek-r1`、`reasoning` 或 `think` 等内容的模型视为具备推理能力。
<Accordion title="推理模型">
OpenClaw 默认会将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 等内容的模型视为具备推理能力。
```bash
ollama pull deepseek-r1:32b
@ -897,24 +897,21 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
</Accordion>
<Accordion title="Model costs">
<Accordion title="模型成本">
Ollama 免费并在本地运行，因此所有模型成本都设置为 $0。这同时适用于自动发现和手动定义的模型。
</Accordion>
<Accordion title="Memory embeddings">
内置 Ollama 插件会为
[memory search](/zh-CN/concepts/memory) 注册一个 memory embedding 提供商。它使用已配置的 Ollama base URL
和 API 密钥，调用 Ollama 当前的 `/api/embed` 端点，并在可能时将
多个 memory chunk 批处理进一个 `input` 请求。
<Accordion title="记忆嵌入">
内置 Ollama 插件会为 [memory search](/zh-CN/concepts/memory) 注册一个记忆嵌入提供商。它使用已配置的 Ollama 基础 URL 和 API 密钥，调用 Ollama 当前的 `/api/embed` 端点，并在可能时将多个记忆块批处理到一个 `input` 请求中。
| 属性 | 值 |
| ------------- | ------------------- |
| 默认模型 | `nomic-embed-text` |
| 自动拉取 | 是 — 如果本地不存在，则会自动拉取 embedding 模型 |
| 默认模型 | `nomic-embed-text` |
| 自动拉取 | 是 — 如果本地不存在该嵌入模型，会自动拉取 |
查询时 embedding 会为需要或推荐使用检索前缀的模型使用这些前缀，包括 `nomic-embed-text`、`qwen3-embedding` 和 `mxbai-embed-large`。Memory 文档批次保持原始格式，因此现有索引不需要格式迁移。
查询时嵌入会为需要或推荐检索前缀的模型使用检索前缀，包括 `nomic-embed-text`、`qwen3-embedding` 和 `mxbai-embed-large`。记忆文档批次保持原始格式，因此现有索引不需要格式迁移。
要选择 Ollama 作为 memory search embedding 提供商：
要选择 Ollama 作为记忆搜索嵌入提供商：
```json5
{
@ -932,7 +929,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
}
```
对于远程 embedding 主机，请将凭证限定到该主机：
对于远程嵌入主机，请将凭证限定在该主机范围内：
```json5
{
@ -955,12 +952,12 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
</Accordion>
<Accordion title="流式传输配置">
OpenClaw 的 Ollama 集成默认使用 **原生 Ollama API**（`/api/chat`），它完全支持同时进行流式传输和工具调用。不需要特殊配置。
OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），它完全支持同时进行流式传输和工具调用。不需要特殊配置。
对于原生 `/api/chat` 请求，OpenClaw 还会将思考控制直接转发给 Ollama：`/think off` 和 `openclaw agent --thinking off` 会发送顶层 `think: false`，除非已配置显式的模型 `params.think`/`params.thinking` 值；而 `/think low|medium|high` 会发送匹配的顶层 `think` effort 字符串。`/think max` 会映射到 Ollama 的最高原生 effort，即 `think: "high"`。
对于原生 `/api/chat` 请求，OpenClaw 还会将思考控制直接转发给 Ollama：`/think off` 和 `openclaw agent --thinking off` 会发送顶层 `think: false`，除非配置了显式的模型 `params.think`/`params.thinking` 值；而 `/think low|medium|high` 会发送匹配的顶层 `think` 强度字符串。`/think max` 会映射到 Ollama 的最高原生强度，即 `think: "high"`。
<Tip>
如果你需要使用兼容 OpenAI 的端点，请参阅上面的“旧版兼容 OpenAI 模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。
如果你需要使用 OpenAI 兼容端点，请参见上面的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。
</Tip>
</Accordion>
@ -970,42 +967,42 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
<AccordionGroup>
<Accordion title="WSL2 崩溃循环（反复重启）">
在带有 NVIDIA/CUDA 的 WSL2 上，官方 Ollama Linux 安装器会创建一个带有 `Restart=always` 的 `ollama.service` systemd 单元。如果该服务自动启动，并在 WSL2 启动期间加载由 GPU 支持的模型，Ollama 可能会在模型加载时占用主机内存。Hyper-V 内存回收并不总是能回收这些被固定的页面，因此 Windows 可能会终止 WSL2 VM，systemd 再次启动 Ollama，循环便会重复。
在带有 NVIDIA/CUDA 的 WSL2 上，官方 Ollama Linux 安装程序会创建一个带有 `Restart=always` 的 `ollama.service` systemd 单元。如果该服务自动启动，并在 WSL2 启动期间加载由 GPU 支持的模型，Ollama 可能会在模型加载时固定主机内存。Hyper-V 内存回收并不总是能回收这些固定页面，因此 Windows 可能会终止 WSL2 VM，systemd 又会再次启动 Ollama，循环随之重复。
常见证据：
- 从 Windows 侧看到 WSL2 反复重启或终止
- WSL2 启动后不久，`app.slice` 或 `ollama.service` 中 CPU 占用很高
- Windows 侧反复出现 WSL2 重启或终止
- WSL2 启动后不久，`app.slice` 或 `ollama.service` 中 CPU 占用较高
- 来自 systemd 的 SIGTERM，而不是 Linux OOM-killer 事件
当 OpenClaw 检测到 WSL2、启用了带有 `Restart=always` 的 `ollama.service`，并且存在可见的 CUDA 标记时，会记录一条启动警告。
当 OpenClaw 检测到 WSL2、启用了带有 `Restart=always` 的 `ollama.service`，并且可见 CUDA 标记时，会记录启动警告。
缓解方法：
缓解措施：
```bash
sudo systemctl disable ollama
```
将以下内容添加到 Windows 侧的 `%USERPROFILE%\.wslconfig`，然后运行 `wsl --shutdown`：
在 Windows 侧将以下内容添加到 `%USERPROFILE%\.wslconfig`，然后运行 `wsl --shutdown`：
```ini
[experimental]
autoMemoryReclaim=disabled
```
在 Ollama 服务环境中设置更短的保活时间，或者只在需要时手动启动 Ollama：
在 Ollama 服务环境中设置更短的 keep-alive，或者只在需要时手动启动 Ollama：
```bash
export OLLAMA_KEEP_ALIVE=5m
ollama serve
```
请参阅 [ollama/ollama#11317](https://github.com/ollama/ollama/issues/11317)。
参见 [ollama/ollama#11317](https://github.com/ollama/ollama/issues/11317)。
</Accordion>
<Accordion title="未检测到 Ollama">
确保 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或凭证配置文件），同时你**没有**定义显式的 `models.providers.ollama` 条目：
确保 Ollama 正在运行，并且你设置了 `OLLAMA_API_KEY`（或凭证配置文件），且**没有**定义显式的 `models.providers.ollama` 条目：
```bash
ollama serve
@ -1023,29 +1020,29 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
如果你的模型未列出，请在本地拉取该模型，或在 `models.providers.ollama` 中显式定义它。
```bash
ollama list # See what's installed
ollama list # 查看已安装内容
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3 # Or another model
ollama pull llama3.3 # 或另一个模型
```
</Accordion>
<Accordion title="连接被拒绝">
检查 Ollama 是否在正确的端口上运行：
检查 Ollama 是否在正确端口上运行：
```bash
# Check if Ollama is running
# 检查 Ollama 是否正在运行
ps aux | grep ollama
# Or restart Ollama
# 或重启 Ollama
ollama serve
```
</Accordion>
<Accordion title="远程主机可用 curl 访问，但 OpenClaw 不可用">
从运行 Gateway 网关的同一台机器和运行时验证：
<Accordion title="远程主机可通过 curl 使用，但 OpenClaw 不行">
从运行 Gateway 网关的同一台机器和运行时进行验证：
```bash
openclaw gateway status --deep
@ -1055,14 +1052,14 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
常见原因：
- `baseUrl` 指向 `localhost`，但 Gateway 网关在 Docker 中或另一台主机上运行。
- URL 使用 `/v1`，这会选择兼容 OpenAI 的行为，而不是原生 Ollama。
- URL 使用 `/v1`，这会选择 OpenAI 兼容行为，而不是原生 Ollama。
- 远程主机需要在 Ollama 侧更改防火墙或 LAN 绑定。
- 该模型存在于你笔记本电脑的 daemon 上，但不存在于远程 daemon 上。
- 模型存在于你的笔记本电脑守护进程上，但不在远程守护进程上。
</Accordion>
<Accordion title="模型将工具 JSON 输出为文本">
这通常意味着提供商正在使用兼容 OpenAI 的模式，或者模型无法处理工具 schema。
这通常意味着提供商正在使用 OpenAI 兼容模式，或者模型无法处理工具架构。
优先使用原生 Ollama 模式：
@ -1079,14 +1076,14 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
}
```
如果某个小型本地模型仍然在工具 schema 上失败，请在该模型条目上设置 `compat.supportsTools: false` 并重新测试。
如果小型本地模型在工具架构上仍然失败，请在该模型条目上设置 `compat.supportsTools: false`，然后重新测试。
</Accordion>
<Accordion title="Kimi 或 GLM 返回乱码符号">
托管的 Kimi/GLM 响应如果是很长的非语言符号串，会被视为失败的提供商输出，而不是成功的助手回答。这会让正常的重试、回退或错误处理接管，而不会把损坏的文本持久化到会话中。
Hosted Kimi/GLM 响应如果是很长的非语言符号串，会被视为失败的提供商输出，而不是成功的助手回答。这样正常的重试、回退或错误处理就能接管，而不会把损坏文本持久化到会话中。
如果反复发生，请捕获原始模型名称、当前会话文件，以及该次运行是使用 `Cloud + Local` 还是 `Cloud only`，然后尝试新的会话和回退模型：
如果反复发生，请捕获原始模型名称、当前会话文件，以及本次运行使用的是 `Cloud + Local` 还是 `Cloud only`，然后尝试一个新的会话和一个回退模型：
```bash
openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --json
@ -1096,7 +1093,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
</Accordion>
<Accordion title="冷启动本地模型超时">
大型本地模型可能需要很长的首次加载时间，之后才会开始流式传输。将超时范围限定在 Ollama 提供商，并可选择让 Ollama 在多轮之间保持模型加载：
大型本地模型在流式传输开始前可能需要很长的首次加载时间。将超时范围限定到 Ollama 提供商，并且可以选择让 Ollama 在轮次之间保持模型已加载：
```json5
{
@ -1117,12 +1114,12 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
}
```
如果主机本身接受连接很慢，`timeoutSeconds` 也会为此提供商延长受保护的 Undici 连接超时。
如果主机本身接受连接很慢，`timeoutSeconds` 也会延长此提供商受保护的 Undici 连接超时。
</Accordion>
<Accordion title="大上下文模型太慢或耗尽内存">
许多 Ollama 模型宣称的上下文大于你的硬件能舒适运行的范围。原生 Ollama 会使用 Ollama 自己的运行时上下文默认值，除非你设置 `params.num_ctx`。当你想要可预测的首个 token 延迟时，请同时限制 OpenClaw 的预算和 Ollama 的请求上下文：
<Accordion title="大上下文模型太慢或内存不足">
许多 Ollama 模型声明的上下文大于你的硬件可以舒适运行的范围。原生 Ollama 会使用 Ollama 自身的运行时上下文默认值，除非你设置 `params.num_ctx`。当你想要可预测的首个 token 延迟时，请同时限制 OpenClaw 的预算和 Ollama 的请求上下文：
```json5
{
@ -1144,7 +1141,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
}
```
如果 OpenClaw 发送了过多 prompt，请先降低 `contextWindow`。如果 Ollama 正在加载的运行时上下文对机器来说过大，请降低 `params.num_ctx`。如果生成运行时间过长，请降低 `maxTokens`。
如果 OpenClaw 发送了过多提示词，请先降低 `contextWindow`。如果 Ollama 正在加载对这台机器来说过大的运行时上下文，请降低 `params.num_ctx`。如果生成运行时间过长，请降低 `maxTokens`。
</Accordion>
</AccordionGroup>
@ -1157,7 +1154,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` 提供商。
<CardGroup cols={2}>
<Card title="模型提供商" href="/zh-CN/concepts/model-providers" icon="layers">
所有提供商、模型引用和故障转移行为概览。
所有提供商、模型引用和故障转移行为的概览。
</Card>
<Card title="模型选择" href="/zh-CN/concepts/models" icon="brain">
如何选择和配置模型。

549
docs/zh-CN/tools/acp-agents.md
View File

@ -3,117 +3,98 @@ read_when:
- 通过 ACP 运行编码执行框架
- 在消息渠道上设置绑定到对话的 ACP 会话
- 将消息渠道对话绑定到持久 ACP 会话
- ACP 后端、插件接入或完成结果交付的故障排除
- 从聊天中操作 /acp 命令
- ACP 后端、插件连接或补全交付的故障排除
- 在聊天中操作 /acp 命令
sidebarTitle: ACP agents
summary: 通过 ACP 后端运行外部编码执行框架（Claude Code、Cursor、Gemini CLI、显式 Codex ACP、OpenClaw ACP、OpenCode）
summary: 通过 ACP 后端运行外部编码框架（Claude Code、Cursor、Gemini CLI、显式 Codex ACP、OpenClaw ACP、OpenCode）
title: ACP 智能体
x-i18n:
generated_at: "2026-04-28T20:08:49Z"
generated_at: "2026-04-29T03:44:42Z"
model: gpt-5.5
provider: openai
source_hash: f7e9100cc825f77ce0972e26ecc26be1526922174c727d2024965d62fa86cd70
source_hash: c8257bdba22b613093da1a06761fdc5034cae4bca249ae91a531ec3fccabb954
source_path: tools/acp-agents.md
workflow: 16
---
[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话
让 OpenClaw 通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、
Cursor、Copilot、Droid、OpenClaw ACP、OpenCode、Gemini CLI，以及其他
受支持的 ACPX harness）。
[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话让 OpenClaw 可以通过 ACP 后端插件运行外部编码运行框架（例如 Pi、Claude Code、Cursor、Copilot、Droid、OpenClaw ACP、OpenCode、Gemini CLI 以及其他受支持的 ACPX 运行框架）。
每次 ACP 会话生成都会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。
<Note>
**ACP 是外部 harness 路径，不是默认的 Codex 路径。** 原生
Codex 应用服务器插件负责 `/codex ...` 控制和
`agentRuntime.id: "codex"` 嵌入式运行时；ACP 负责
`/acp ...` 控制和 `sessions_spawn({ runtime: "acp" })` 会话。
**ACP 是外部运行框架路径，不是默认 Codex 路径。** 原生 Codex app-server 插件拥有 `/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。
</Note>
## 我应该看哪个页面？
| 你想要… | 使用 | 说明 |
| ----------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 在当前对话中绑定或控制 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 运行时 |
| 你想要… | 使用 | 备注 |
| ----------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 在当前对话中绑定或控制 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 控制，没有运行框架运行时 |
## 这能开箱即用吗？
通常可以。全新安装默认会启用内置的 `acpx` 运行时插件，
并附带插件本地固定版本的 `acpx` 二进制文件；OpenClaw 会在启动时探测它
并进行自修复。运行 `/acp doctor` 进行就绪检查。
通常可以。全新安装默认启用内置的 `acpx` 运行时插件，并附带插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自修复。运行 `/acp doctor` 执行就绪检查。
只有当 ACP **真正可用**时，OpenClaw 才会教智能体如何生成 ACP：
必须启用 ACP，分发不能被禁用，当前会话不能被沙箱阻止，并且必须加载
运行时后端。如果不满足这些条件，ACP 插件 Skills 和
`sessions_spawn` ACP 指引会保持隐藏，以免智能体建议不可用的后端。
OpenClaw 只会在 ACP **确实可用**时教智能体使用 ACP 生成：ACP 必须已启用，分发不得被禁用，当前会话不得被沙箱阻止，并且必须已加载运行时后端。如果不满足这些条件，ACP 插件 Skills 和 `sessions_spawn` ACP 指引会保持隐藏，以免智能体建议不可用的后端。
<AccordionGroup>
<Accordion title="首次运行注意事项">
- 如果设置了 `plugins.allow`，它就是一个限制性的插件清单，并且**必须**包含 `acpx`；否则内置默认插件会被有意阻止，`/acp doctor` 会报告缺少 allowlist 条目。
- 内置 Codex ACP 适配器随 `acpx` 插件一起暂存，并在可能时本地启动。
- 其他目标 harness 适配器在你首次使用时仍可能按需通过 `npx` 获取。
- 该 harness 的供应商凭证仍必须存在于主机上。
- 如果主机没有 npm 或网络访问，首次运行的适配器获取会失败，直到缓存已预热或通过其他方式安装了适配器。
- 如果设置了 `plugins.allow`，它就是限制性的插件清单，并且**必须**包含 `acpx`；否则内置默认插件会被有意阻止，`/acp doctor` 会报告缺少允许列表条目。
- 内置 Codex ACP 适配器随 `acpx` 插件一起暂存，并在可行时本地启动。
- 其他目标运行框架适配器可能仍会在你首次使用时通过 `npx` 按需获取。
- 该运行框架的供应商凭证仍必须存在于主机上。
- 如果主机没有 npm 或网络访问权限，首次运行的适配器获取会失败，直到缓存预热或通过其他方式安装适配器。
</Accordion>
<Accordion title="运行时前提条件">
ACP 会启动一个真实的外部 harness 进程。OpenClaw 负责路由、
后台任务状态、投递、绑定和策略；harness 负责其提供商登录、
模型目录、文件系统行为和原生工具。
<Accordion title="运行时先决条件">
ACP 会启动一个真实的外部运行框架进程。OpenClaw 负责路由、后台任务状态、投递、绑定和策略；运行框架负责自己的提供商登录、模型目录、文件系统行为和原生工具。
在归因于 OpenClaw 之前，请确认：
在归因于 OpenClaw 之前，请验证：
- `/acp doctor` 报告一个已启用且健康的后端。
- 设置了 `acp.allowedAgents` allowlist 时，目标 id 被允许。
- harness 命令可以在 Gateway 网关主机上启动。
- 该 harness 的提供商凭证已存在（`claude`、`codex`、`gemini`、`opencode`、`droid` 等）。
- 所选模型存在于该 harness 中 — 模型 id 不能跨 harness 通用。
- 请求的 `cwd` 存在且可访问；或者省略 `cwd`，让后端使用其默认值。
- 权限模式与工作匹配。非交互式会话无法点击原生权限提示，因此写入/执行密集型编码运行通常需要一个可以无头继续执行的 ACPX 权限配置文件。
- `/acp doctor` 报告后端已启用且健康。
- 设置 `acp.allowedAgents` 允许列表时，目标 ID 被该允许列表允许。
- 运行框架命令可以在 Gateway 网关主机上启动。
- 该运行框架存在提供商凭证（`claude`、`codex`、`gemini`、`opencode`、`droid` 等）。
- 所选模型存在于该运行框架中 —— 模型 ID 不能跨运行框架移植。
- 请求的 `cwd` 存在且可访问，或者省略 `cwd` 并让后端使用其默认值。
- 权限模式与工作匹配。非交互式会话无法点击原生权限提示，因此写入/执行密集的编码运行通常需要能无界面继续执行的 ACPX 权限配置文件。
</Accordion>
</AccordionGroup>
默认情况下，OpenClaw 插件工具和内置 OpenClaw 工具**不会**暴露给
ACP harness。只有当 harness 应直接调用这些工具时，才在
[ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)中启用显式 MCP 桥接。
OpenClaw 插件工具和内置 OpenClaw 工具默认**不会**暴露给 ACP 运行框架。仅当运行框架应直接调用这些工具时，才在 [ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)中启用显式 MCP 桥接。
## 支持的 harness 目标
## 支持的运行框架目标
使用内置 `acpx` 后端时，将这些 harness id 用作 `/acp spawn <id>`
或 `sessions_spawn({ runtime: "acp", agentId: "<id>" })` 目标：
使用内置 `acpx` 后端时，请将这些运行框架 ID 作为 `/acp spawn <id>` 或 `sessions_spawn({ runtime: "acp", agentId: "<id>" })` 目标：
| Harness id | 典型后端 | 说明 |
| 运行框架 ID | 典型后端 | 备注 |
| ---------- | ---------------------------------------------- | ----------------------------------------------------------------------------------- |
| `claude` | Claude Code ACP 适配器 | 需要主机上有 Claude Code 凭证。 |
| `codex` | Codex ACP 适配器 | 仅在原生 `/codex` 不可用或请求 ACP 时，作为显式 ACP 回退方案。 |
| `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 凭证，或 harness 环境中的 `FACTORY_API_KEY`。 |
| `gemini` | Gemini CLI ACP 适配器 | 需要 Gemini CLI 凭证或 API key 设置。 |
| `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 密钥设置。 |
| `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 的 harness 回连到 OpenClaw Gateway 网关会话。 |
| `pi` | Pi/嵌入式 OpenClaw 运行时 | 用于 OpenClaw 原生 harness 实验。 |
| `qwen` | Qwen Code / Qwen CLI | 需要主机上有 Qwen 兼容凭证。 |
| `opencode` | OpenCode ACP 适配器 | 需要 OpenCode CLI/提供商凭证。 |
| `openclaw` | 通过 `openclaw acp` 的 OpenClaw Gateway 网关桥接 | 让支持 ACP 的运行框架回连到 OpenClaw Gateway 网关会话。 |
| `pi` | Pi/嵌入式 OpenClaw 运行时 | 用于 OpenClaw 原生运行框架实验。 |
| `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` 的流程：
<Steps>
<Step title="生成">
@ -142,121 +123,110 @@ ACP harness。只有当 harness 应直接调用这些工具时，才在
<AccordionGroup>
<Accordion title="生命周期详情">
- 生成会创建或恢复 ACP 运行时会话，在 OpenClaw 会话存储中记录 ACP 元数据，并且当运行由父级拥有时，可能会创建后台任务。
- 生成会创建或恢复 ACP 运行时会话，在 OpenClaw 会话存储中记录 ACP 元数据，并且当运行由父级拥有时可能会创建后台任务。
- 父级拥有的 ACP 会话会被视为后台工作，即使运行时会话是持久的；完成和跨界面投递会通过父任务通知器，而不是像普通面向用户的聊天会话那样处理。
- 任务维护会关闭终止状态的父级拥有的一次性 ACP 会话。只要仍存在活跃的对话绑定，持久 ACP 会话就会被保留；没有活跃绑定的过期持久会话会被关闭，以免在拥有任务完成后被静默恢复。
- 任务维护会关闭终态或孤立的父级拥有一次性 ACP 会话。持久 ACP 会话会在仍有活动对话绑定时保留；没有活动绑定的陈旧持久会话会被关闭，以免在拥有任务完成或其任务记录消失后被静默恢复。
- 绑定的后续消息会直接发送到 ACP 会话，直到绑定被关闭、取消聚焦、重置或过期。
- Gateway 网关命令保持本地执行。`/acp ...`、`/status` 和 `/unfocus` 永远不会作为普通提示文本发送给绑定的 ACP harness。
- Gateway 网关命令保持本地执行。`/acp ...`、`/status` 和 `/unfocus` 永远不会作为普通提示文本发送给绑定的 ACP 运行框架。
- 当后端支持取消时，`cancel` 会中止当前轮次；它不会删除绑定或会话元数据。
- `close` 会从 OpenClaw 视角结束 ACP 会话并移除绑定。如果 harness 支持恢复，它仍可能保留自己的上游历史。
- 空闲运行时 worker 在 `acp.runtime.ttlMinutes` 之后可被清理；存储的会话元数据仍可用于 `/acp sessions`。
- 从 OpenClaw 视角看，`close` 会结束 ACP 会话并移除绑定。如果运行框架支持恢复，它可能仍会保留自己的上游历史。
- 空闲运行时工作进程可在 `acp.runtime.ttlMinutes` 之后被清理；已存储的会话元数据仍可用于 `/acp sessions`。
</Accordion>
<Accordion title="原生 Codex 路由规则">
当**原生 Codex 插件**已启用时，以下自然语言触发应路由到它：
当**原生 Codex 插件**启用时，应路由到它的自然语言触发：
- “将这个 Discord 渠道绑定到 Codex。”
- “将这个聊天附加到 Codex 线程 `<id>`。”
- “显示 Codex 线程，然后绑定这个线程。”
原生 Codex 对话绑定是默认聊天控制路径。
OpenClaw 动态工具仍通过 OpenClaw 执行，而
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)中。
原生 Codex 对话绑定是默认聊天控制路径。OpenClaw 动态工具仍通过 OpenClaw 执行，而 Codex 原生工具（例如 shell/apply-patch）在 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 运行框架 v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)中。
</Accordion>
<Accordion title="模型 / 提供商 / 运行时选择速查表">
- `openai-codex/*` — PI Codex OAuth/订阅路由。
- `openai/*` 加 `agentRuntime.id: "codex"` — 原生 Codex 应用服务器嵌入式运行时。
- `openai/*` 加 `agentRuntime.id: "codex"` — 原生 Codex app-server 嵌入式运行时。
- `/codex ...` — 原生 Codex 对话控制。
- `/acp ...` 或 `runtime: "acp"` — 显式 ACP/acpx 控制。
</Accordion>
<Accordion title="ACP 路由的自然语言触发条件">
应路由到 ACP 运行时的触发条件：
<Accordion title="ACP 路由自然语言触发器">
应路由到 ACP 运行时的触发器：
- "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."
- “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`，
在受支持时绑定到当前对话或话题串，并将后续消息路由到该会话，直到关闭或过期。Codex 仅在显式指定 ACP/acpx，或所请求操作无法使用原生 Codex
插件时，才会采用此路径。
在支持时绑定到当前对话或话题，
并将后续消息路由到该会话，直到关闭/过期。只有当 ACP/acpx 明确指定，
或原生 Codex 插件不适用于请求的操作时，Codex 才会走这条路径。
对于 `sessions_spawn`，只有在 ACP 已启用、请求方未处于沙箱隔离、
且已加载 ACP 运行时后端时，才会宣告 `runtime: "acp"`。
`acp.dispatch.enabled=false` 会暂停自动 ACP 话题串分发，
但不会隐藏或阻止显式的
`sessions_spawn({ runtime: "acp" })` 调用。它面向 `codex`、
`claude`、`droid`、`gemini` 或 `opencode` 等 ACP harness id。不要传入来自 `agents_list` 的普通
OpenClaw 配置智能体 id，除非该条目已显式配置为
对于 `sessions_spawn`，只有在 ACP 已启用、请求者未被沙箱隔离、
且已加载 ACP 运行时后端时，才会声明 `runtime: "acp"`。`acp.dispatch.enabled=false` 会暂停自动
ACP 话题分发，但不会隐藏或阻止显式
`sessions_spawn({ runtime: "acp" })` 调用。它面向 ACP harness ID，例如 `codex`、
`claude`、`droid`、`gemini` 或 `opencode`。不要传入来自 `agents_list` 的普通
OpenClaw 配置智能体 ID，除非该条目已显式配置为
`agents.list[].runtime.type="acp"`；
否则请使用默认子智能体运行时。当 OpenClaw 智能体
否则使用默认子智能体运行时。当 OpenClaw 智能体
配置了 `runtime.type="acp"` 时，OpenClaw 会使用
`runtime.acp.agent` 作为底层 harness id。
`runtime.acp.agent` 作为底层 harness ID。
</Accordion>
</AccordionGroup>
## ACP 与子智能体对比
## ACP 与子智能体
当你需要外部 harness 运行时时，使用 ACP。当 `codex`
插件已启用且你需要 Codex 对话绑定/控制时，使用 **原生 Codex
应用服务器**。当你需要 OpenClaw 原生的委派运行时，使用 **子智能体**。
当你需要外部 harness 运行时时使用 ACP。当启用 `codex`
插件并需要 Codex 对话绑定/控制时，使用**原生 Codex
app-server**。当你需要 OpenClaw 原生委派运行时，使用**子智能体**。
| 领域 | ACP 会话 | 子智能体运行 |
| 范围 | ACP 会话 | 子智能体运行 |
| ------------- | ------------------------------------- | ---------------------------------- |
| 运行时 | ACP 后端插件（例如 acpx） | OpenClaw 原生子智能体运行时 |
| 会话键名 | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| 会话键 | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| 主要命令 | `/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` 运行时插件。
3. Claude ACP 适配器。
4. Claude 侧运行时/会话机制。
ACP Claude 是一个 **harness 会话**，具备 ACP 控制、会话恢复、
后台任务跟踪，以及可选的对话/话题串绑定。
ACP Claude 是一个带有 ACP 控制、会话恢复、后台任务跟踪，
以及可选对话/话题绑定的 **harness 会话**。
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`、仓库检出、后端工作区）。独立于聊天表面。
### 当前对话绑定
`/acp spawn <harness> --bind here` 会将当前对话固定到
新启动的 ACP 会话 —— 没有子话题串，仍使用同一聊天界面。OpenClaw 继续
负责传输、认证、安全和投递。该对话中的后续消息会路由到
同一会话；`/new` 和 `/reset` 会在原位置重置
该会话；`/acp close` 会移除绑定。
生成的 ACP 会话 — 不创建子话题，使用同一聊天表面。OpenClaw 继续
负责传输、凭证、安全和投递。该对话中的后续消息会路由到
同一会话；`/new` 和 `/reset` 会原地重置
会话；`/acp close` 会移除绑定。
示例：
@ -272,37 +242,37 @@ CLI 后端是独立的纯文本本地回退运行时 —— 请参阅
<AccordionGroup>
<Accordion title="绑定规则和排他性">
- `--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` 不需要。
- 如果你在没有 `--cwd` 的情况下生成到另一个 ACP 智能体，OpenClaw 默认会继承**目标智能体的**工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为生成错误显示。
- Gateway 网关管理命令在绑定对话中保持本地处理 — 即使普通后续文本会路由到绑定的 ACP 会话，`/acp ...` 命令也由 OpenClaw 处理；只要该表面启用了命令处理，`/status` 和 `/unfocus` 也会保持本地处理。
</Accordion>
<Accordion title="话题串绑定会话">
当渠道适配器启用话题串绑定时：
<Accordion title="话题绑定会话">
当渠道适配器启用话题绑定时：
- OpenClaw 会将话题串绑定到目标 ACP 会话。
- 该话题串中的后续消息会路由到绑定的 ACP 会话。
- ACP 输出会投递回同一话题串。
- 取消聚焦/关闭/归档/空闲超时或最大年龄过期会移除绑定。
- `/acp close`、`/acp cancel`、`/acp status`、`/status` 和 `/unfocus` 是 Gateway 网关命令，不是发送给 ACP harness 的提示词。
- 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 会返回明确的
不支持/不可用消息。
</Accordion>
<Accordion title="支持话题串的渠道">
- 任何公开会话/话题串绑定能力的渠道适配器。
- 当前内置支持：**Discord** 话题串/频道、**Telegram** 话题（群组/超级群组中的论坛话题和私信话题）。
<Accordion title="支持话题的渠道">
- 任何公开会话/话题绑定能力的渠道适配器。
- 当前内置支持：**Discord** 话题/渠道、**Telegram** 主题（群组/超级群组中的论坛主题和私信主题）。
- 插件渠道可以通过同一绑定接口添加支持。
</Accordion>
@ -310,36 +280,37 @@ CLI 后端是独立的纯文本本地回退运行时 —— 请参阅
## 持久渠道绑定
对于非临时工作流，请在顶层 `bindings[]` 条目中配置持久 ACP 绑定。
对于非临时工作流，请在顶层 `bindings[]` 条目中
配置持久 ACP 绑定。
### 绑定模型
<ParamField path="bindings[].type" type='"acp"'>
标记一个持久 ACP 对话绑定。
标记持久 ACP 对话绑定。
</ParamField>
<ParamField path="bindings[].match" type="object">
标识目标对话。各渠道形状如下：
标识目标对话。各渠道形态：
- **Discord 频道/话题串：** `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- **Telegram 论坛话题：** `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- **BlueBubbles 私信/群组：** `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`。对于稳定的群组绑定，优先使用 `chat_id:*` 或 `chat_identifier:*`。
- **iMessage 私信/群组：** `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`。对于稳定的群组绑定，优先使用 `chat_id:*`。
- **Discord 渠道/话题：** `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- **Telegram 论坛主题：** `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- **BlueBubbles 私信/群组：** `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`。稳定群组绑定首选 `chat_id:*` 或 `chat_identifier:*`。
- **iMessage 私信/群组：** `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`。稳定群组绑定首选 `chat_id:*`。
</ParamField>
<ParamField path="bindings[].agentId" type="string">
所属 OpenClaw 智能体 id。
所属 OpenClaw 智能体 ID。
</ParamField>
<ParamField path="bindings[].acp.mode" type='"persistent" | "oneshot"'>
可选 ACP 覆盖项。
可选 ACP 覆盖。
</ParamField>
<ParamField path="bindings[].acp.label" type="string">
可选的面向运维人员标签。
可选的面向操作者标签。
</ParamField>
<ParamField path="bindings[].acp.cwd" type="string">
可选运行时工作目录。
</ParamField>
<ParamField path="bindings[].acp.backend" type="string">
可选后端覆盖项。
可选后端覆盖。
</ParamField>
### 每个智能体的运行时默认值
@ -347,7 +318,7 @@ CLI 后端是独立的纯文本本地回退运行时 —— 请参阅
使用 `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`
@ -440,12 +411,12 @@ CLI 后端是独立的纯文本本地回退运行时 —— 请参阅
### 行为
- OpenClaw 会在使用前确保配置的 ACP 会话存在。
- 该频道或话题中的消息会路由到配置的 ACP 会话。
- 在绑定对话中，`/new` 和 `/reset` 会在原位置重置同一个 ACP 会话键。
- 临时运行时绑定（例如由话题串聚焦流程创建的绑定）在存在时仍会生效。
- 对于未显式指定 `cwd` 的跨智能体 ACP 启动，OpenClaw 会从智能体配置继承目标智能体工作区。
- 缺失的继承工作区路径会回退到后端默认 cwd；非缺失的访问失败会作为启动错误暴露。
- OpenClaw 会确保配置的 ACP 会话在使用前存在。
- 该渠道或主题中的消息会路由到配置的 ACP 会话。
- 在绑定对话中，`/new` 和 `/reset` 会原地重置同一个 ACP 会话键。
- 临时运行时绑定（例如由话题聚焦流程创建的绑定）在存在时仍会生效。
- 对于未显式指定 `cwd` 的跨智能体 ACP 生成，OpenClaw 会从智能体配置继承目标智能体工作区。
- 缺失的继承工作区路径会回退到后端默认 cwd；非缺失的访问失败会作为生成错误显示。
## 启动 ACP 会话
@ -467,14 +438,11 @@ CLI 后端是独立的纯文本本地回退运行时 —— 请参阅
```
<Note>
`runtime` 默认是 `subagent`，因此对于 ACP 会话，请显式设置
`runtime: "acp"`。如果省略 `agentId`，OpenClaw 会在已配置时使用
`acp.defaultAgent`。`mode: "session"` 需要 `thread: true`
才能保留持久绑定会话。
`runtime` 默认为 `subagent`，因此请为 ACP 会话显式设置 `runtime: "acp"`。如果省略 `agentId`，OpenClaw 会在已配置时使用 `acp.defaultAgent`。`mode: "session"` 需要 `thread: true`，以保持持久绑定的对话。
</Note>
</Tab>
<Tab title="From /acp command">
<Tab title="来自 /acp 命令">
使用 `/acp spawn` 从聊天中进行显式操作员控制。
```text
@ -492,7 +460,7 @@ CLI 后端是独立的纯文本本地回退运行时 —— 请参阅
- `--cwd <absolute-path>`
- `--label <name>`
参见 [Slash commands](/zh-CN/tools/slash-commands)。
请参阅 [Slash commands](/zh-CN/tools/slash-commands)。
</Tab>
</Tabs>
@ -509,38 +477,31 @@ CLI 后端是独立的纯文本本地回退运行时 —— 请参阅
ACP 目标 harness ID。如果已设置，则回退到 `acp.defaultAgent`。
</ParamField>
<ParamField path="thread" type="boolean" default="false">
在支持的位置请求线程绑定流程。
在支持的地方请求线程绑定流程。
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
`"run"` 是一次性运行；`"session"` 是持久会话。如果 `thread: true` 且
省略了 `mode`，OpenClaw 可能会根据运行时路径默认使用持久行为。
`mode: "session"` 需要 `thread: true`。
`"run"` 是一次性模式；`"session"` 是持久模式。如果 `thread: true` 且省略了 `mode`，OpenClaw 可能会根据运行时路径默认采用持久行为。`mode: "session"` 需要 `thread: true`。
</ParamField>
<ParamField path="cwd" type="string">
请求的运行时工作目录（由后端/运行时策略验证）。如果省略，ACP spawn 会在已配置时继承目标 Agent 工作区；缺失的继承路径会回退到后端默认值，而真实访问错误会被返回。
请求的运行时工作目录（由后端/运行时策略验证）。如果省略，ACP spawn 会在已配置时继承目标 Agent 工作区；缺失的继承路径会回退到后端默认值，而真实的访问错误会被返回。
</ParamField>
<ParamField path="label" type="string">
用于会话/banner 文本的面向操作员标签。
用于会话/横幅文本的面向操作员标签。
</ParamField>
<ParamField path="resumeSessionId" type="string">
恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load`
重放其会话历史。需要 `runtime: "acp"`。
恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load` 重放其对话历史。需要 `runtime: "acp"`。
</ParamField>
<ParamField path="streamTo" type='"parent"'>
`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式传回请求方会话。接受的响应包括
`streamLogPath`，它指向会话作用域的 JSONL 日志
(`<sessionId>.acp-stream.jsonl`)，你可以 tail 它来查看完整中继历史。
`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流式传回请求者会话。接受的响应包括 `streamLogPath`，指向会话作用域的 JSONL 日志（`<sessionId>.acp-stream.jsonl`），你可以 tail 它来查看完整中继历史。
</ParamField>
<ParamField path="runTimeoutSeconds" type="number">
N 秒后中止 ACP 子轮次。`0` 会让该轮次走 gateway 的无超时路径。同一个值会应用到 Gateway 网关运行和 ACP 运行时，因此卡住或配额耗尽的 harness 不会无限期占用父智能体通道。
在 N 秒后中止 ACP 子回合。`0` 会让该回合走 Gateway 网关的无超时路径。相同的值会应用到 Gateway 网关运行和 ACP 运行时，因此停滞或配额耗尽的 harness 不会无限期占用父智能体通道。
</ParamField>
<ParamField path="model" type="string">
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 会清晰失败，而不是静默回退到目标智能体默认值。
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 会明确失败，而不是静默回退到目标智能体默认值。
</ParamField>
<ParamField path="thinking" type="string">
显式 thinking/推理强度。对于 Codex ACP，`minimal` 映射到低强度，`low`/`medium`/`high`/`xhigh` 直接映射，`off` 会省略推理强度启动覆盖。
显式思考/推理强度。对于 Codex ACP，`minimal` 映射到低强度，`low`/`medium`/`high`/`xhigh` 直接映射，`off` 则省略推理强度启动覆盖。
</ParamField>
## Spawn 绑定和线程模式
@ -549,31 +510,31 @@ CLI 后端是独立的纯文本本地回退运行时 —— 请参阅
<Tab title="--bind here|off">
| 模式 | 行为 |
| ------ | ---------------------------------------------------------------------- |
| `here` | 就地绑定当前活跃会话；如果没有活跃会话则失败。 |
| `off` | 不创建当前会话绑定。 |
| `here` | 就地绑定当前活动对话；如果没有活动对话则失败。 |
| `off` | 不创建当前对话绑定。 |
注意：
- `--bind here` 是“让这个渠道或聊天由 Codex 支撑”的最简单操作员路径。
- `--bind here` 是“让此渠道或聊天由 Codex 支持”的最简单操作员路径。
- `--bind here` 不会创建子线程。
- `--bind here` 仅适用于公开当前会话绑定支持的渠道。
- `--bind here` 仅适用于公开当前对话绑定支持的渠道。
- `--bind` 和 `--thread` 不能在同一个 `/acp spawn` 调用中组合使用。
</Tab>
<Tab title="--thread auto|here|off">
| 模式 | 行为 |
| ------ | --------------------------------------------------------------------------------------------------- |
| `auto` | 在活跃线程中：绑定该线程。在线程外：在支持时创建/绑定子线程。 |
| `here` | 要求当前活跃线程；如果不在线程中则失败。 |
| `auto` | 在活动线程中：绑定该线程。在线程外：在支持时创建/绑定子线程。 |
| `here` | 要求当前活动线程；如果不在线程中则失败。 |
| `off` | 不绑定。会话以未绑定状态启动。 |
注意：
- 在非线程绑定界面上，默认行为实际上是 `off`。
- 线程绑定 spawn 需要渠道策略支持：
- 在非线程绑定表面上，默认行为实际上是 `off`。
- 线程绑定的 spawn 需要渠道策略支持：
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true`
- 当你想固定当前会话且不创建子线程时，请使用 `--bind here`。
- 当你想固定当前对话而不创建子线程时，请使用 `--bind here`。
</Tab>
</Tabs>
@ -583,53 +544,50 @@ CLI 后端是独立的纯文本本地回退运行时 —— 请参阅
ACP 会话可以是交互式工作区，也可以是父级拥有的后台工作。交付路径取决于这种形态。
<AccordionGroup>
<Accordion title="Interactive ACP sessions">
交互式会话旨在持续在可见聊天界面上对话：
<Accordion title="交互式 ACP 会话">
交互式会话旨在持续在可见聊天表面上对话：
- `/acp spawn ... --bind here` 将当前会话绑定到 ACP 会话。
- `/acp spawn ... --thread ...` 将渠道线程/主题绑定到 ACP 会话。
- 持久配置的 `bindings[].type="acp"` 会将匹配的会话路由到同一个 ACP 会话。
- `/acp spawn ... --bind here` 将当前对话绑定到 ACP 会话。
- `/acp spawn ... --thread ...` 将渠道线程/话题绑定到 ACP 会话。
- 持久配置的 `bindings[].type="acp"` 会将匹配的对话路由到同一个 ACP 会话。
绑定会话中的后续消息会直接路由到 ACP 会话，ACP 输出也会交付回同一渠道/线程/主题。
绑定对话中的后续消息会直接路由到 ACP 会话，ACP 输出也会交付回同一个渠道/线程/话题。
OpenClaw 发送给 harness 的内容：
- 普通绑定后续消息会作为提示文本发送，且仅在 harness/后端支持时附带附件。
- `/acp` 管理命令和本地 Gateway 网关命令会在 ACP 派发前被拦截。
- 运行时生成的完成事件会按目标实体化。OpenClaw 智能体会收到 OpenClaw 的内部运行时上下文信封；外部 ACP harness 会收到包含子结果和指令的普通提示。原始 `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` 信封绝不应发送到外部 harness，也不应作为 ACP 用户转录文本持久化。
- ACP 转录条目使用用户可见的触发文本或普通完成提示。内部事件元数据会尽可能在 OpenClaw 中保持结构化，并且不会被视为用户撰写的聊天内容。
- 正常的绑定后续消息会作为提示文本发送，只有在 harness/后端支持时才包含附件。
- `/acp` 管理命令和本地 Gateway 网关命令会在 ACP 分发前被拦截。
- 运行时生成的完成事件会按目标实体化。OpenClaw 智能体会收到 OpenClaw 的内部运行时上下文信封；外部 ACP harness 会收到包含子结果和指令的普通提示。原始 `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` 信封绝不应发送给外部 harness，也不应作为 ACP 用户转录文本持久化。
- ACP 转录条目使用用户可见的触发文本或普通完成提示。内部事件元数据会尽可能以结构化形式保留在 OpenClaw 中，并且不会被视为用户编写的聊天内容。
</Accordion>
<Accordion title="Parent-owned one-shot ACP sessions">
由另一个智能体运行 spawn 出来的一次性 ACP 会话是后台子会话，类似于子智能体：
<Accordion title="父级拥有的一次性 ACP 会话">
由另一个智能体运行 spawn 的一次性 ACP 会话是后台子会话，类似于子智能体：
- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。
- 父级使用 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。
- 子级在自己的 ACP harness 会话中运行。
- 子轮次运行在原生子智能体 spawn 使用的同一个后台通道上，因此缓慢的 ACP harness 不会阻塞无关的主会话工作。
- 完成通过任务完成公告路径回报。OpenClaw 会在发送给外部 harness 前，将内部完成元数据转换为普通 ACP 提示，因此 harness 不会看到 OpenClaw 专用的运行时上下文标记。
- 当用户可见回复有用时，父级会用正常助手语气重写子结果。
- 子回合运行在原生子智能体 spawn 使用的同一个后台通道上，因此缓慢的 ACP harness 不会阻塞无关的主会话工作。
- 完成结果会通过任务完成公告路径报告回来。OpenClaw 会先将内部完成元数据转换为普通 ACP 提示，再发送给外部 harness，因此 harness 不会看到仅限 OpenClaw 的运行时上下文标记。
- 当面向用户的回复有用时，父级会用普通助手语气重写子结果。
**不要**将此路径视为父级和子级之间的点对点聊天。子级已经有一条返回父级的完成渠道。
不要将此路径视为父级和子级之间的点对点聊天。子级已经有回到父级的完成渠道。
</Accordion>
<Accordion title="sessions_send and A2A delivery">
`sessions_send` 可以在 spawn 后以另一个会话为目标。对于普通对等会话，OpenClaw 会在注入消息后使用智能体到智能体（A2A）的后续路径：
<Accordion title="sessions_send 和 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"`，因为完成路径已经负责处理结果。
</Accordion>
<Accordion title="Resume an existing session">
使用 `resumeSessionId` 继续之前的 ACP 会话，而不是重新开始。智能体会通过
`session/load` 重放其会话历史，因此会带着之前内容的完整上下文继续。
<Accordion title="恢复现有会话">
使用 `resumeSessionId` 继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其对话历史，因此会带着之前内容的完整上下文继续。
```json
{
@ -642,151 +600,138 @@ ACP 会话可以是交互式工作区，也可以是父级拥有的后台工作
常见用例：
- 将 Codex 会话从你的笔记本电脑交接到你的手机：告诉你的智能体从你离开的地方继续。
- 继续你在 CLI 中交互式启动的编码会话，现在通过你的智能体以无头方式进行。
- 接手因 gateway 重启或空闲超时而中断的工作。
- 将 Codex 会话从你的笔记本电脑移交到你的手机，告诉你的智能体从你离开的地方继续。
- 继续你在 CLI 中交互式启动的编码会话，现在通过你的智能体以无头方式继续。
- 接手因 Gateway 网关重启或空闲超时而中断的工作。
注意：
- `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`。
- `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，spawn 会以清晰错误失败，不会静默回退到新会话。
- 如果找不到会话 ID，spawn 会明确失败，不会静默回退到新会话。
</Accordion>
<Accordion title="Post-deploy smoke test">
gateway 部署后，运行一次真实端到端检查，而不是信任单元测试：
<Accordion title="部署后冒烟测试">
Gateway 网关部署后，请运行实时端到端检查，而不是信任单元测试：
1. 验证目标主机上的已部署 gateway 版本和提交。
2. 打开一个到真实智能体的临时 ACPX bridge 会话。
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`，并且没有验证器错误。
4. 验证 `accepted=yes`、真实的 `childSessionKey`，且没有验证器错误。
5. 清理临时 bridge 会话。
将 gate 保持在 `mode: "run"`，并跳过 `streamTo: "parent"`，因为线程绑定的
`mode: "session"` 和流中继路径是单独的、更丰富的集成检查。
保持门禁使用 `mode: "run"`，并跳过 `streamTo: "parent"`，因为线程绑定的 `mode: "session"` 和流式中继路径是单独的、更丰富的集成轮次。
</Accordion>
</AccordionGroup>
## 沙箱兼容性
ACP 会话当前运行在主机运行时上，**不**在 OpenClaw 沙箱内运行。
ACP 会话目前在主机运行时上运行，**不是**在 OpenClaw 沙箱内运行。
<Warning>
**安全边界：**
- 外部执行框架可以根据其自身 CLI 权限和所选 `cwd` 进行读写。
- 外部执行框架可以根据其自身的 CLI 权限和选定的 `cwd` 进行读取/写入。
- OpenClaw 的沙箱策略**不会**包裹 ACP 执行框架的执行。
- OpenClaw 仍会强制执行 ACP 功能门控、允许的智能体、会话所有权、渠道绑定和 Gateway 网关投递策略。
- 对需要强制沙箱的 OpenClaw 原生工作，请使用 `runtime: "subagent"`。
- 对需要强制沙箱隔离的 OpenClaw 原生工作，使用 `runtime: "subagent"`。
</Warning>
当前限制：
- 如果请求方会话是沙箱隔离的，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 派生都会被阻止。
- 如果请求方会话处于沙箱隔离状态，则 `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
- 尝试 key
- 然后尝试 UUID 形态的会话 ID
- 然后尝试标签
2. 当前线程绑定（如果此对话/线程已绑定到 ACP 会话）。
2. 当前线程绑定（如果此对话/线程绑定到 ACP 会话）。
3. 当前请求方会话回退。
当前对话绑定和线程绑定都参与
第 2 步。
当前对话绑定和线程绑定都会参与第 2 步。
如果没有解析出目标，OpenClaw 会返回清晰的错误
（`Unable to resolve session target: ...`）。
如果没有解析出目标，OpenClaw 会返回明确错误（`Unable to resolve session target: ...`）。
## ACP 控制
## ACP 控制命令
| 命令 | 作用 | 示例 |
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
| `/acp spawn` | 创建 ACP 会话；可选当前绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | 取消目标会话中正在进行的轮次。 | `/acp cancel agent:codex:acp:<uuid>` |
| `/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` | 写入通用运行时配置选项。 | `/acp set model openai/gpt-5.4` |
| `/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 sessions` | 从存储中列出最近的 ACP 会话。 | `/acp sessions` |
| `/acp doctor` | 后端健康状况、能力和可操作修复。 | `/acp doctor` |
| `/acp install` | 打印确定性的安装和启用步骤。 | `/acp install` |
| `/acp spawn` | 创建 ACP 会话；可选当前绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | 取消目标会话正在进行的轮次。 | `/acp cancel agent:codex:acp:<uuid>` |
| `/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` | 写入通用运行时配置选项。 | `/acp set model openai/gpt-5.4` |
| `/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 sessions` | 从存储中列出最近的 ACP 会话。 | `/acp sessions` |
| `/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` 会读取当前已绑定会话或请求方会话的存储；目标 token（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括每个智能体自定义的 `session.store` 根目录。
### 运行时选项映射
`/acp` 提供便捷命令和通用设置器。等效
操作：
`/acp` 提供便捷命令和通用设置器。等效操作：
| 命令 | 映射到 | 备注 |
| ---------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/acp model <id>` | 运行时配置键 `model` | 对于 Codex ACP，OpenClaw 会将 `openai-codex/<model>` 规范化为适配器模型 ID，并将斜杠推理后缀（如 `openai-codex/gpt-5.4/high`）映射到 `reasoning_effort`。 |
| `/acp set thinking <level>` | 运行时配置键 `thinking` | 对于 Codex ACP，在适配器支持时，OpenClaw 会发送对应的 `reasoning_effort`。 |
| `/acp permissions <profile>` | 运行时配置键 `approval_policy` | — |
| `/acp timeout <seconds>` | 运行时配置键 `timeout` | — |
| `/acp cwd <path>` | 运行时 cwd 覆盖值 | 直接更新。 |
| `/acp set <key> <value>` | 通用 | `key=cwd` 使用 cwd 覆盖路径。 |
| `/acp reset-options` | 清除所有运行时覆盖值 | — |
| 命令 | 映射到 | 说明 |
| ---------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/acp model <id>` | 运行时配置键 `model` | 对于 Codex ACP，OpenClaw 会将 `openai-codex/<model>` 规范化为适配器模型 ID，并将斜杠推理后缀（例如 `openai-codex/gpt-5.4/high`）映射到 `reasoning_effort`。 |
| `/acp set thinking <level>` | 运行时配置键 `thinking` | 对于 Codex ACP，OpenClaw 会在适配器支持时发送对应的 `reasoning_effort`。 |
| `/acp permissions <profile>` | 运行时配置键 `approval_policy` | — |
| `/acp timeout <seconds>` | 运行时配置键 `timeout` | — |
| `/acp cwd <path>` | 运行时 cwd 覆盖 | 直接更新。 |
| `/acp set <key> <value>` | 通用 | `key=cwd` 使用 cwd 覆盖路径。 |
| `/acp reset-options` | 清除所有运行时覆盖 | — |
## acpx 执行框架、插件设置和权限
关于 acpx 执行框架配置（Claude Code / Codex / Gemini CLI
别名）、plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP
权限模式，请参阅
[ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)。
有关 acpx 执行框架配置（Claude Code / Codex / Gemini CLI 别名）、plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP 权限模式，请参阅 [ACP agents — 设置](/zh-CN/tools/acp-agents-setup)。
## 故障排除
| 现象 | 可能原因 | 解决方法 |
| 症状 | 可能原因 | 修复方法 |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ACP runtime backend is not configured` | 后端插件缺失、已禁用，或被 `plugins.allow` 阻止。 | 安装并启用后端插件；设置该允许列表时，在 `plugins.allow` 中包含 `acpx`，然后运行 `/acp doctor`。 |
| `ACP runtime backend is not configured` | 后端插件缺失、已禁用，或被 `plugins.allow` 阻止。 | 安装并启用后端插件；设置该允许列表时，将 `acpx` 加入 `plugins.allow`，然后运行 `/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 dispatch is disabled by policy (acp.dispatch.enabled=false)` | 已禁用普通线程消息的自动分发。 | 设置 `acp.dispatch.enabled=true` 以恢复自动线程路由；显式 `sessions_spawn({ runtime: "acp" })` 调用仍可工作。 |
| `ACP agent "<id>" 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 <channel>.` | 适配器缺少当前对话 ACP 绑定能力。 | 在支持的情况下使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或移动到受支持的渠道。 |
| `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文之外使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 |
| `Only <user-id> can rebind this channel/conversation/thread.` | 另一个用户拥有活动绑定目标。 | 以所有者身份重新绑定，或使用其他对话或线程。 |
| `Thread bindings are unavailable for <channel>.` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或移动到受支持的适配器/渠道。 |
| `/acp doctor` reports backend not ready right after startup | 插件依赖探测或自修复仍在运行。 | 稍等片刻并重新运行 `/acp doctor`；如果仍不健康，请检查后端安装错误以及插件允许/拒绝策略。 |
| 找不到运行框架命令 | 未安装适配器 CLI、暂存的插件依赖缺失，或非 Codex 适配器的首次运行 `npx` 拉取失败。 | 运行 `/acp doctor`，修复插件依赖，在 Gateway 网关主机上安装/预热适配器，或显式配置 acpx 智能体命令。 |
| 运行框架返回模型未找到 | 模型 ID 对另一个提供商/运行框架有效，但不适用于此 ACP 目标。 | 使用该运行框架列出的模型，在运行框架中配置模型，或省略覆盖项。 |
| 运行框架返回厂商凭证错误 | 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 <channel>.` | 适配器缺少当前对话 ACP 绑定能力。 | 在支持的情况下使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或移动到支持的渠道。 |
| `--thread here requires running /acp spawn inside an active ... thread` | 在非线程上下文中使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto`/`off`。 |
| `Only <user-id> can rebind this channel/conversation/thread.` | 另一个用户拥有活跃绑定目标。 | 以所有者身份重新绑定，或使用其他对话或线程。 |
| `Thread bindings are unavailable for <channel>.` | 适配器缺少线程绑定能力。 | 使用 `--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 看到 `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` | 内部事件封套泄漏到了 ACP 边界之外。 | 更新 OpenClaw 并重新运行完成流程；外部 harness 应该只接收普通的完成提示。 |
| `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` | 目标运行框架未公开通用 ACP 模型切换。 | 使用声明支持 ACP `models`/`session/set_model` 的运行框架，使用 Codex ACP 模型引用，或在运行框架拥有自己的启动标志时直接在其中配置模型。 |
| 已绑定会话缺少 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 会话完成工作后无限期卡住 | 运行框架进程已完成，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动终止过期进程。 |
| 运行框架看到 `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` | 内部事件信封泄漏到了 ACP 边界之外。 | 更新 OpenClaw 并重新运行完成流程；外部运行框架应只接收普通完成提示。 |
## 相关
## 相关内容
- [ACP 智能体 — 设置](/zh-CN/tools/acp-agents-setup)
- [智能体发送](/zh-CN/tools/agent-send)