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-05-02 13:57:44 +00:00
parent 6d8530ef30
commit 2d6ef795f3
3 changed files with 209 additions and 234 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
docs/zh-CN/plugins/building-plugins.md
View File

@ -1,39 +1,31 @@
---
read_when:
- 你想创建一个新的 OpenClaw 插件
- 你需要一份插件开发快速开始指南
- 你需要一份用于插件开发的快速开始指南
- 你正在向 OpenClaw 添加新的渠道、提供商、工具或其他能力
sidebarTitle: Getting Started
summary: 只需几分钟即可创建你的第一个 OpenClaw 插件
summary: 几分钟内创建你的第一个 OpenClaw 插件
title: 构建插件
x-i18n:
generated_at: "2026-05-02T05:25:40Z"
generated_at: "2026-05-02T13:56:38Z"
model: gpt-5.5
provider: openai
source_hash: 2cf85c1c1c1f6ae6752f7fb8d842a420bffac6ebaf4d64803fb8bb8ab9f6f83c
source_hash: f4f810d831db26d1e4efecf691590980b3ba1d958c4b4af3cc6a7ca9ea155a36
source_path: plugins/building-plugins.md
workflow: 16
---
插件通过新增能力扩展 OpenClaw：渠道、模型提供商、
语音、实时转写、实时语音、媒体理解、图像
生成、视频生成、Web 抓取、Web 搜索、智能体工具，或任意
组合。
插件用新能力扩展 OpenClaw：渠道、模型提供商、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、Web 获取、Web 搜索、智能体工具，或它们的任意组合。
你无需将插件添加到 OpenClaw 仓库。发布到
[ClawHub](/zh-CN/tools/clawhub)，用户使用
`openclaw plugins install <package-name>` 安装。OpenClaw 会先尝试 ClawHub，
并针对仍使用 npm 分发的包自动回退到 npm。
你不需要把插件添加到 OpenClaw 仓库。发布到 [ClawHub](/zh-CN/tools/clawhub)，用户用 `openclaw plugins install <package-name>` 安装。OpenClaw 会先尝试 ClawHub，并对仍使用 npm 分发的软件包自动回退到 npm。
## 前提条件
- Node >= 22 和一个包管理器（npm 或 pnpm）
- 熟悉 TypeScript（ESM）
- 对于仓库内插件：已克隆仓库并完成 `pnpm install`。源码
checkout 插件开发仅支持 pnpm，因为 OpenClaw 会从 `extensions/*` 工作区包加载内置
插件。
- 对于仓库内插件：已克隆仓库并完成 `pnpm install`。源代码检出方式的插件开发仅支持 pnpm，因为 OpenClaw 会从 `extensions/*` 工作区软件包加载内置插件。
## 哪种插件？
## 什么类型的插件？
<CardGroup cols={3}>
<Card title="渠道插件" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
@ -47,18 +39,14 @@ x-i18n:
</Card>
</CardGroup>
对于在新手引导/设置运行时不能保证已安装的渠道插件，请使用
`openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。
它会生成一个设置适配器 + 向导组合，用于说明安装要求，并且在插件安装前，
对真实配置写入采取失败关闭策略。
对于不能保证在新手引导/设置运行时已安装的渠道插件，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装前对真实配置写入保持失败关闭状态。
## 快速开始：工具插件
本演练会创建一个注册智能体工具的最小插件。渠道
和提供商插件有上方链接的专门指南。
本演练会创建一个注册智能体工具的最小插件。渠道和提供商插件有上方链接的专门指南。
<Steps>
<Step title="创建包和清单">
<Step title="创建软件包和清单">
<CodeGroup>
```json package.json
{
@ -98,12 +86,7 @@ x-i18n:
```
</CodeGroup>
每个插件都需要清单，即使没有配置也是如此。运行时注册的工具
必须列在 `contracts.tools` 中，这样 OpenClaw 才能在不加载每个插件运行时的情况下发现所属
插件。插件也应有意声明
`activation.onStartup`。本示例将其设置为 `true`。完整 schema 请参阅
[清单](/zh-CN/plugins/manifest)。规范的 ClawHub
发布片段位于 `docs/snippets/plugin-publish/`。
每个插件都需要一个清单，即使没有配置也是如此。运行时注册的工具必须列在 `contracts.tools` 中，这样 OpenClaw 才能在不加载每个插件运行时的情况下发现拥有该工具的插件。插件还应有意声明 `activation.onStartup`。此示例将其设置为 `true`。完整 schema 请参阅 [Manifest](/zh-CN/plugins/manifest)。规范的 ClawHub 发布片段位于 `docs/snippets/plugin-publish/`。
</Step>
@ -131,15 +114,13 @@ x-i18n:
});
```
`definePluginEntry` 用于非渠道插件。对于渠道，请使用
`defineChannelPluginEntry` — 参阅[渠道插件](/zh-CN/plugins/sdk-channel-plugins)。
完整入口点选项请参阅[入口点](/zh-CN/plugins/sdk-entrypoints)。
`definePluginEntry` 用于非渠道插件。对于渠道，请使用 `defineChannelPluginEntry` — 参阅 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。完整入口点选项请参阅 [入口点](/zh-CN/plugins/sdk-entrypoints)。
</Step>
<Step title="测试并发布">
**外部插件：** 使用 ClawHub 验证并发布，然后安装：
**外部插件：**使用 ClawHub 验证并发布，然后安装：
```bash
clawhub package publish your-org/your-plugin --dry-run
@ -147,11 +128,9 @@ x-i18n:
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
```
对于像 `@myorg/openclaw-my-plugin` 这样的裸包规格，
OpenClaw 也会先检查 ClawHub，再检查 npm；对于尚未
迁移到 ClawHub 的包，npm 仍作为回退。
对于像 `@myorg/openclaw-my-plugin` 这样的裸包规格，OpenClaw 也会先检查 ClawHub，再检查 npm；对于尚未迁移到 ClawHub 的软件包，npm 仍作为回退。
**仓库内插件：** 放在内置插件工作区树下 — 会被自动发现。
**仓库内插件：**放在内置插件工作区树下 — 会被自动发现。
```bash
pnpm test -- <bundled-plugin-root>/my-plugin/
@ -168,15 +147,15 @@ x-i18n:
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| 文本推理（LLM） | `api.registerProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins) |
| CLI 推理后端 | `api.registerCliBackend(...)` | [CLI 后端](/zh-CN/gateway/cli-backends) |
| 渠道 / 消息 | `api.registerChannel(...)` | [渠道插件](/zh-CN/plugins/sdk-channel-plugins) |
| 渠道 / 消息传递 | `api.registerChannel(...)` | [渠道插件](/zh-CN/plugins/sdk-channel-plugins) |
| 语音（TTS/STT） | `api.registerSpeechProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 实时转写 | `api.registerRealtimeTranscriptionProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 图像生成 | `api.registerImageGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 音乐生成 | `api.registerMusicGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 视频生成 | `api.registerVideoGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Web 抓取 | `api.registerWebFetchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Web 获取 | `api.registerWebFetchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Web 搜索 | `api.registerWebSearchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 工具结果中间件 | `api.registerAgentToolResultMiddleware(...)` | [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api) |
| 智能体工具 | `api.registerTool(...)` | 下文 |
@ -188,42 +167,31 @@ x-i18n:
完整注册 API 请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。
当内置插件需要在模型看到输出前异步重写工具结果时，可以使用
`api.registerAgentToolResultMiddleware(...)`。请在
`contracts.agentToolResultMiddleware` 中声明目标运行时，例如
`["pi", "codex"]`。这是一个受信任的内置插件接口；外部
插件应优先使用常规 OpenClaw 插件钩子，除非 OpenClaw 为此能力发展出
明确的信任策略。
内置插件在需要在模型看到输出前异步改写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。请在 `contracts.agentToolResultMiddleware` 中声明目标运行时，例如 `["pi", "codex"]`。这是一个受信任的内置插件接缝；外部插件应优先使用常规 OpenClaw 插件钩子，除非 OpenClaw 为此能力增加明确的信任策略。
如果你的插件注册自定义 Gateway 网关 RPC 方法，请将它们保持在
插件专属前缀下。核心管理员命名空间（`config.*`、
`exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并始终解析为
`operator.admin`，即使插件请求更窄的 scope 也是如此。
如果你的插件注册自定义 Gateway 网关 RPC 方法，请将它们放在插件专属前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并且始终解析为 `operator.admin`，即使插件请求更窄的作用域也是如此。
需要牢记的钩子防护语义：
需要记住的钩子守卫语义：
- `before_tool_call`：`{ block: true }` 是终止性的，并会停止较低优先级处理器。
- `before_tool_call`：`{ block: false }` 被视为没有决定。
- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec approval 叠层、Telegram 按钮、Discord 交互或任意渠道上的 `/approve` 命令提示用户审批。
- `before_install`：`{ block: true }` 是终止性的，并会停止较低优先级处理器。
- `before_install`：`{ block: false }` 被视为没有决定。
- `message_sending`：`{ cancel: true }` 是终止性的，并会停止较低优先级处理器。
- `message_sending`：`{ cancel: false }` 被视为没有决定。
- `message_received`：需要入站线程/话题路由时，优先使用带类型的 `threadId` 字段。将 `metadata` 保留给渠道特定的额外信息。
- `message_sending`：优先使用带类型的 `replyToId` / `threadId` 路由字段，而不是渠道特定的 metadata 键。
- `before_tool_call`：`{ block: true }` 是终止性的，并会停止较低优先级的处理程序。
- `before_tool_call`：`{ block: false }` 被视为未做决定。
- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 批准浮层、Telegram 按钮、Discord 交互，或任意渠道上的 `/approve` 命令提示用户批准。
- `before_install`：`{ block: true }` 是终止性的，并会停止较低优先级的处理程序。
- `before_install`：`{ block: false }` 被视为未做决定。
- `message_sending`：`{ cancel: true }` 是终止性的，并会停止较低优先级的处理程序。
- `message_sending`：`{ cancel: false }` 被视为未做决定。
- `message_received`：当你需要入站线程/话题路由时，优先使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的额外信息。
- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，而不是渠道特定的元数据键。
`/approve` 命令通过有界回退同时处理 exec 和插件审批：当找不到 exec approval id 时，OpenClaw 会通过插件审批重试同一个 id。插件审批转发可通过配置中的 `approvals.plugin` 独立配置。
`/approve` 命令会用有界回退处理 exec 和插件批准：找不到 exec 批准 ID 时，OpenClaw 会用同一个 ID 重试插件批准。插件批准转发可以通过配置中的 `approvals.plugin` 独立配置。
如果自定义审批管线需要检测同一个有界回退场景，
请优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，
而不是手动匹配审批过期字符串。
如果自定义批准管线需要检测同一个有界回退情况，请优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不是手动匹配批准过期字符串。
示例和钩子参考请参阅[插件钩子](/zh-CN/plugins/hooks)。
示例和钩子参考请参阅 [插件钩子](/zh-CN/plugins/hooks)。
## 注册智能体工具
工具是 LLM 可以调用的带类型函数。它们可以是必需的（始终
可用）或可选的（用户选择启用）：
工具是 LLM 可以调用的类型化函数。它们可以是必需的（始终可用）或可选的（用户选择启用）：
```typescript
register(api) {
@ -252,8 +220,7 @@ register(api) {
}
```
每个通过 `api.registerTool(...)` 注册的工具也必须在
插件清单中声明：
每个通过 `api.registerTool(...)` 注册的工具也必须在插件清单中声明：
```json
{
@ -263,6 +230,8 @@ register(api) {
}
```
OpenClaw 会从已注册工具捕获并缓存经过验证的描述符，因此插件不需要在清单中重复 `description` 或 schema 数据。清单契约只声明所有权和发现；执行仍会调用实时注册的工具实现。
用户在配置中启用可选工具：
```json5
@ -272,13 +241,14 @@ register(api) {
```
- 工具名称不得与核心工具冲突（冲突项会被跳过）
- 注册对象格式错误的工具（包括缺少 `parameters`）会被跳过，并在插件诊断中报告，而不会中断智能体运行
- 对有副作用或额外二进制要求的工具使用 `optional: true`
- 用户可以通过将插件 id 添加到 `tools.allow` 来启用某个插件的所有工具
- 注册对象格式错误的工具（包括缺少 `parameters`）会被跳过并在插件诊断中报告，而不是中断智能体运行
- 对有副作用或需要额外二进制文件的工具使用 `optional: true`
- 用户可以通过将插件 id 添加到 `tools.allow` 来启用插件中的所有工具
## 注册 CLI 命令
插件可以通过 `api.registerCli` 添加根级 `openclaw` 命令组。为每个顶级命令根提供 `descriptors`，这样 OpenClaw 就能显示和路由命令，而不必急切加载每个插件运行时。
插件可以通过 `api.registerCli` 添加根级 `openclaw` 命令组。为每个顶层命令根提供
`descriptors`，这样 OpenClaw 就可以展示并路由该命令，而无需急切加载每个插件运行时。
```typescript
register(api) {
@ -308,7 +278,7 @@ register(api) {
}
```
安装后，验证运行时注册并执行该命令：
安装后，验证运行时注册并执行命令：
```bash
openclaw plugins inspect demo-plugin --runtime --json
@ -329,21 +299,21 @@ import { ... } from "openclaw/plugin-sdk";
完整子路径参考见 [SDK 概览](/zh-CN/plugins/sdk-overview)。
在你的插件内部，使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行内部导入，不要通过其 SDK 路径导入你自己的插件。
在你的插件中，对内部导入使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）——绝不要通过其 SDK 路径导入你自己的插件。
对于提供商插件，除非该接缝确实是通用的，否则请将提供商特定的辅助函数保留在这些 package-root barrel 中。当前内置示例：
对于提供商插件，请将提供商专用辅助函数保留在这些 package 根级 barrel 中，除非该接缝确实是通用的。当前内置示例：
- Anthropic：Claude 流包装器和 `service_tier` / beta 辅助函数
- Anthropic：Claude 流包装器以及 `service_tier` / beta 辅助函数
- OpenAI：提供商构建器、默认模型辅助函数、实时提供商
- OpenRouter：提供商构建器以及新手引导/配置辅助函数
如果某个辅助函数只在一个内置提供商包内部有用，请将其保留在该 package-root 接缝上，而不是提升到 `openclaw/plugin-sdk/*`。
如果某个辅助函数只在一个内置提供商包内部有用，请将它保留在该 package 根级接缝上，而不是提升到 `openclaw/plugin-sdk/*` 中。
一些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助接缝仍然存在，用于有已跟踪所有者使用情况的内置插件维护。请将这些视为保留接口，而不是新第三方插件的默认模式。
一些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助接缝仍然存在，用于在存在已跟踪 owner 用法时维护内置插件。将这些视为保留表面，而不是新第三方插件的默认模式。
## 提交前检查清单
<Check>**package.json** 包含正确的 `openclaw` 元数据</Check>
<Check>**package.json** 具有正确的 `openclaw` 元数据</Check>
<Check>**openclaw.plugin.json** 清单存在且有效</Check>
<Check>入口点使用 `defineChannelPluginEntry` 或 `definePluginEntry`</Check>
<Check>所有导入都使用聚焦的 `plugin-sdk/<subpath>` 路径</Check>
@ -351,14 +321,14 @@ import { ... } from "openclaw/plugin-sdk";
<Check>测试通过（`pnpm test -- <bundled-plugin-root>/my-plugin/`）</Check>
<Check>`pnpm check` 通过（仓库内插件）</Check>
## Beta 发布测试
## Beta 版本发布测试
1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签类似 `v2026.3.N-beta.1`。你也可以为官方 OpenClaw X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以接收发布公告。
2. Beta 标签一出现，就针对它测试你的插件。稳定版发布前的窗口通常只有几个小时。
3. 测试后，在 `plugin-forum` Discord 渠道中你的插件线程里发布 `all good` 或说明损坏了什么。如果你还没有线程，请创建一个。
4. 如果出现问题，请创建或更新标题为 `Beta blocker: <plugin-name> - <summary>` 的 issue，并应用 `beta-blocker` 标签。把 issue 链接放到你的线程中。
5. 向 `main` 打开一个标题为 `fix(<plugin-id>): beta blocker - <summary>` 的 PR，并在 PR 和你的 Discord 线程中都链接该 issue。贡献者无法给 PR 加标签，因此标题是给维护者和自动化使用的 PR 侧信号。带 PR 的阻塞问题会被合并；没有 PR 的阻塞问题可能仍会随版本发布。维护者会在 beta 测试期间关注这些线程。
6. 沉默就代表绿色通过。如果你错过窗口，你的修复很可能会进入下一个周期。
1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签形如 `v2026.3.N-beta.1`。你也可以为官方 OpenClaw X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以接收发布公告。
2. Beta 标签一出现，就针对该 beta 标签测试你的插件。稳定版发布前的窗口通常只有几个小时。
3. 测试后，在 `plugin-forum` Discord 渠道中你的插件线程里发布 `all good` 或说明损坏内容。如果你还没有线程，请创建一个。
4. 如果有内容损坏，请打开或更新标题为 `Beta blocker: <plugin-name> - <summary>` 的 issue，并应用 `beta-blocker` 标签。将 issue 链接放入你的线程。
5. 向 `main` 打开一个标题为 `fix(<plugin-id>): beta blocker - <summary>` 的 PR，并在 PR 和你的 Discord 线程中链接该 issue。贡献者无法给 PR 打标签，因此标题是给维护者和自动化系统的 PR 侧信号。有 PR 的阻断问题会被合并；没有 PR 的阻断问题仍可能随版本发布。维护者会在 beta 测试期间关注这些线程。
6. 沉默即表示通过。如果你错过窗口，你的修复很可能会进入下一个周期。
## 后续步骤
@ -376,7 +346,7 @@ import { ... } from "openclaw/plugin-sdk";
通过 api.runtime 使用 TTS、搜索、子智能体
</Card>
<Card title="Testing" icon="test-tubes" href="/zh-CN/plugins/sdk-testing">
测试工具和模式
测试实用工具和模式
</Card>
<Card title="Plugin Manifest" icon="file-json" href="/zh-CN/plugins/manifest">
完整清单 schema 参考
@ -385,7 +355,7 @@ import { ... } from "openclaw/plugin-sdk";
## 相关内容
- [插件架构](/zh-CN/plugins/architecture) — 内部架构深入解析
- [插件架构](/zh-CN/plugins/architecture) — 内部架构深度解析
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考
- [清单](/zh-CN/plugins/manifest) — 插件清单格式
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件

103
docs/zh-CN/plugins/sdk-runtime.md
View File

@ -1,28 +1,28 @@
---
read_when:
- 你需要从插件调用核心辅助函数（TTS、STT、image gen、web search、subagent、nodes）
- 你需要从插件调用核心辅助函数（TTS、STT、图像生成、Web 搜索、子智能体、节点）
- 你想了解 api.runtime 公开了什么
- 你正在从插件代码访问配置、智能体或媒体辅助函数
- 你正在从插件代码访问配置、智能体或媒体辅助工具
sidebarTitle: Runtime helpers
summary: api.runtime -- 可供插件使用的注入式运行时辅助程序
title: 插件运行时辅助工具
summary: api.runtime -- 可供插件使用的注入式运行时辅助工具
title: 插件运行时辅助函数
x-i18n:
generated_at: "2026-05-02T12:15:35Z"
generated_at: "2026-05-02T13:56:43Z"
model: gpt-5.5
provider: openai
source_hash: 02c0dc6522e80d4a02b1d3c248fa5ac934888035d435df8b1967861f9dcceb6a
source_hash: 26df37a2ad0dcd29648e382eb579b6892068af4dea1c47460cfd379458a8081c
source_path: plugins/sdk-runtime.md
workflow: 16
---
Reference for the `api.runtime` object injected into every plugin during registration. Use these helpers instead of importing host internals directly.
`api.runtime` 对象的参考文档，该对象会在注册期间注入到每个插件中。使用这些辅助函数，而不是直接导入主机内部实现。
<CardGroup cols={2}>
<Card title="Channel plugins" href="/zh-CN/plugins/sdk-channel-plugins">
在渠道插件上下文中使用这些助手的分步指南。
渠道插件的分步指南，会在上下文中使用这些辅助函数。
</Card>
<Card title="Provider plugins" href="/zh-CN/plugins/sdk-provider-plugins">
在提供商插件上下文中使用这些助手的分步指南。
提供商插件的分步指南，会在上下文中使用这些辅助函数。
</Card>
</CardGroup>
@ -32,33 +32,33 @@ register(api) {
}
```
## 配置加载与写入
## 配置加载和写入
优先使用已经传入当前调用路径的配置，例如注册期间的 `api.config`，或渠道/提供商回调中的 `cfg` 参数。这样可以让同一个进程快照贯穿整个工作流程，而不是在热路径上重新解析配置。
优先使用已经传入当前活跃调用路径的配置，例如注册期间的 `api.config`，或渠道/提供商回调中的 `cfg` 参数。这样可以让同一个进程快照贯穿整个工作流，而不是在热路径上重新解析配置。
仅当长生命周期处理程序需要当前进程快照，且没有配置传入该函数时，才使用 `api.runtime.config.current()`。返回值为只读；编辑前请克隆，或使用变更助手。
仅当长生命周期处理程序需要当前进程快照，且没有配置传入该函数时，才使用 `api.runtime.config.current()`。返回值是只读的；编辑前请克隆，或使用变更辅助函数。
工具工厂会收到 `ctx.runtimeConfig` 和 `ctx.getRuntimeConfig()`。当工具定义创建后配置可能发生变化时，请在长生命周期工具的 `execute` 回调中使用该 getter。
使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 持久化变更。每次写入都必须选择显式的 `afterWrite` 策略：
使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 持久化更改。每次写入都必须选择一个显式的 `afterWrite` 策略：
- `afterWrite: { mode: "auto" }` 让 Gateway 网关重载规划器决定。
- `afterWrite: { mode: "restart", reason: "..." }` 会在写入方知道热重载不安全时强制干净重启。
- `afterWrite: { mode: "none", reason: "..." }` 仅当调用方负责后续处理时，才抑制自动重载/重启。
- `afterWrite: { mode: "none", reason: "..." }` 仅在调用方拥有后续处理时，才抑制自动重载/重启。
变更助手会返回 `afterWrite` 以及类型化的 `followUp` 摘要，这样调用方可以记录或测试自己是否请求了重启。Gateway 网关仍然负责决定该重启实际何时发生。
变更辅助函数会返回 `afterWrite` 以及一个类型化的 `followUp` 摘要，因此调用方可以记录或测试自己是否请求了重启。Gateway 网关仍然负责决定实际何时重启。
`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是 `runtime-config-load-write` 下已弃用的兼容性助手。它们会在运行时警告一次，并在迁移窗口期间继续供旧版外部插件使用。内置插件不得使用它们；如果插件代码调用它们，或从插件 SDK 子路径导入这些助手，配置边界守卫会失败。
`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是 `runtime-config-load-write` 下已弃用的兼容辅助函数。它们会在运行时警告一次，并在迁移窗口期间继续供旧的外部插件使用。内置插件不得使用它们；如果插件代码调用这些辅助函数，或从插件 SDK 子路径导入这些辅助函数，配置边界守卫会失败。
对于直接 SDK 导入，请使用聚焦的配置子路径，而不是宽泛的
`openclaw/plugin-sdk/config-runtime` 兼容性 barrel：`config-types` 用于
`openclaw/plugin-sdk/config-runtime` 兼容 barrel：`config-types` 用于
类型，`plugin-config-runtime` 用于已加载配置断言和插件
入口查询，`runtime-config-snapshot` 用于当前进程快照，`config-mutation` 用于写入。内置插件测试应直接模拟这些聚焦的
子路径，而不是模拟宽泛的兼容性 barrel。
入口查找，`runtime-config-snapshot` 用于当前进程快照，`config-mutation` 用于写入。内置插件测试应直接 mock 这些聚焦的
子路径，而不是 mock 宽泛的兼容 barrel。
内部 OpenClaw 运行时代码也遵循同样方向：在 CLI、Gateway 网关或进程边界加载一次配置，然后传递该值。成功的变更写入会刷新进程运行时快照并推进其内部修订版本；长生命周期缓存应基于运行时拥有的缓存键，而不是在本地序列化配置。长生命周期运行时模块对环境中的 `loadConfig()` 调用采用零容忍扫描器；请使用传入的 `cfg`、请求的 `context.getRuntimeConfig()`，或在显式进程边界使用 `getRuntimeConfig()`。
OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关或进程边界加载一次配置，然后将该值继续传递下去。成功的变更写入会刷新进程运行时快照并推进其内部修订版本；长生命周期缓存应基于运行时拥有的缓存键，而不是在本地序列化配置。长生命周期运行时模块对环境中的 `loadConfig()` 调用实行零容忍扫描；请使用传入的 `cfg`、请求的 `context.getRuntimeConfig()`，或在显式进程边界使用 `getRuntimeConfig()`。
提供商和渠道执行路径必须使用活动的运行时配置快照，而不是为配置回读或编辑返回的文件快照。文件快照会保留源值，例如供 UI 和写入使用的 SecretRef 标记；提供商回调需要解析后的运行时视图。当助手可能收到活动源快照或活动运行时快照时，请在读取凭证前通过 `selectApplicableRuntimeConfig()` 路由。
提供商和渠道执行路径必须使用活跃的运行时配置快照，而不是用于配置读回或编辑的文件快照。文件快照会保留源值，例如供 UI 和写入使用的 SecretRef 标记；提供商回调需要的是已解析的运行时视图。当某个辅助函数可能收到活跃源快照或活跃运行时快照时，请先通过 `selectApplicableRuntimeConfig()` 再读取凭证。
## 运行时命名空间
@ -108,15 +108,15 @@ register(api) {
});
```
`runEmbeddedAgent(...)` 是从插件代码启动普通 OpenClaw 智能体轮次的中立助手。它使用与渠道触发回复相同的提供商/模型解析和 agent-harness 选择。
`runEmbeddedAgent(...)` 是从插件代码启动普通 OpenClaw 智能体轮次的中立辅助函数。它使用与渠道触发回复相同的提供商/模型解析和 agent harness 选择。
`runEmbeddedPiAgent(...)` 会继续作为兼容性别名保留。
`runEmbeddedPiAgent(...)` 保留为兼容别名。
`resolveThinkingPolicy(...)` 返回提供商/模型支持的思考级别和可选默认值。提供商插件通过其思考钩子拥有模型特定配置文件，因此工具插件应调用此运行时助手，而不是导入或复制提供商列表。
`resolveThinkingPolicy(...)` 返回提供商/模型支持的思考等级和可选默认值。提供商插件通过其思考钩子拥有模型特定的配置文件，因此工具插件应调用此运行时辅助函数，而不是导入或重复维护提供商列表。
`normalizeThinkingLevel(...)` 会将用户文本（例如 `on`、`x-high` 或 `extra high`）转换为规范存储级别，然后再对照解析出的策略进行检查。
`normalizeThinkingLevel(...)` 会将 `on`、`x-high` 或 `extra high` 等用户文本转换为规范存储等级，然后再与解析出的策略比对。
**会话存储助手** 位于 `api.runtime.agent.session` 下：
**会话存储辅助函数** 位于 `api.runtime.agent.session` 下：
```typescript
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
@ -128,7 +128,7 @@ register(api) {
const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId);
```
对运行时写入，优先使用 `updateSessionStore(...)` 或 `updateSessionStoreEntry(...)`。它们会通过 Gateway 网关拥有的会话存储写入器路由，保留并发更新，并复用热缓存。`saveSessionStore(...)` 会继续用于兼容性和离线维护式重写。
对运行时写入，优先使用 `updateSessionStore(...)` 或 `updateSessionStoreEntry(...)`。它们会通过 Gateway 网关拥有的会话存储写入器执行，保留并发更新，并复用热缓存。`saveSessionStore(...)` 会继续作为兼容和离线维护式重写用途提供。
</Accordion>
<Accordion title="api.runtime.agent.defaults">
@ -141,7 +141,7 @@ register(api) {
</Accordion>
<Accordion title="api.runtime.subagent">
启动和管理后台 subagent 运行。
启动和管理后台子智能体运行。
```typescript
// Start a subagent run
@ -169,14 +169,14 @@ register(api) {
```
<Warning>
模型覆盖（`provider`/`model`）需要操作员通过配置中的 `plugins.entries.<id>.subagent.allowModelOverride: true` 选择启用。不受信任的插件仍可运行 subagent，但覆盖请求会被拒绝。
模型覆盖（`provider`/`model`）需要操作者在配置中通过 `plugins.entries.<id>.subagent.allowModelOverride: true` 选择启用。不受信任的插件仍然可以运行子智能体，但覆盖请求会被拒绝。
</Warning>
`deleteSession(...)` 可以删除同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作员会话仍需要管理员范围的 Gateway 网关请求。
`deleteSession(...)` 可以删除同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作者会话仍然需要管理员范围的 Gateway 网关请求。
</Accordion>
<Accordion title="api.runtime.nodes">
列出已连接节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令调用节点主机命令。当插件拥有配对设备上的本地工作时使用此功能，例如另一台 Mac 上的浏览器或音频桥接器。
列出已连接节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令调用节点宿主命令。当插件拥有配对设备上的本地工作时使用它，例如另一台 Mac 上的浏览器或音频桥接。
```typescript
const { nodes } = await api.runtime.nodes.list({ connected: true });
@ -189,13 +189,13 @@ register(api) {
});
```
在 Gateway 网关内部，此运行时在进程内执行。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此 `openclaw googlemeet recover-tab` 等命令可以从终端检查配对节点。节点命令仍会经过正常的 Gateway 网关节点配对、命令 allowlist、插件 node-invoke 策略以及节点本地命令处理。
在 Gateway 网关内部，此运行时位于进程内。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此 `openclaw googlemeet recover-tab` 等命令可以从终端检查配对节点。节点命令仍然会经过正常的 Gateway 网关节点配对、命令 allowlist、插件节点调用策略和节点本地命令处理。
暴露危险节点主机命令的插件应使用 `api.registerNodeInvokePolicy(...)` 注册 node-invoke 策略。该策略会在 Gateway 网关中运行，在命令 allowlist 检查之后、命令转发到节点之前执行，因此直接 `node.invoke` 调用和更高级的插件工具会共享同一执行路径。
暴露危险节点宿主命令的插件应使用 `api.registerNodeInvokePolicy(...)` 注册节点调用策略。该策略会在 Gateway 网关中运行，位于命令 allowlist 检查之后、命令转发到节点之前，因此直接 `node.invoke` 调用和更高层级的插件工具会共享同一执行控制路径。
</Accordion>
<Accordion title="api.runtime.tasks.managedFlows">
将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具上下文，然后无需在每次调用时传递 owner 即可创建和管理 Task Flow。
将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具上下文，然后无需在每次调用时传入所有者即可创建和管理 Task Flow。
```typescript
const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
@ -282,7 +282,7 @@ register(api) {
});
```
未生成输出时（例如跳过的输入），返回 `{ text: undefined }`。
未产生输出时返回 `{ text: undefined }`（例如跳过的输入）。
<Info>
`api.runtime.stt.transcribeAudioFile(...)` 仍作为 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容性别名保留。
@ -316,7 +316,7 @@ register(api) {
</Accordion>
<Accordion title="api.runtime.media">
底层媒体实用工具。
底层媒体工具。
```typescript
const webMedia = await api.runtime.media.loadWebMedia(url);
@ -341,7 +341,7 @@ register(api) {
</Accordion>
<Accordion title="api.runtime.config">
当前运行时配置快照和事务式配置写入。优先使用已经传入活动调用路径的配置；仅在处理程序需要直接获取进程快照时才使用 `current()`。
当前运行时配置快照，以及事务式配置写入。优先使用已传入当前活动调用路径的配置；只有当处理程序需要直接访问进程快照时，才使用 `current()`。
```typescript
const cfg = api.runtime.config.current();
@ -353,15 +353,22 @@ register(api) {
});
```
`mutateConfigFile(...)` 和 `replaceConfigFile(...)` 会返回一个 `followUp` 值，例如 `{ mode: "restart", requiresRestart: true, reason }`，它会记录写入方意图，而不会从 Gateway 网关手中接管重启控制。
`mutateConfigFile(...)` 和 `replaceConfigFile(...)` 会返回一个 `followUp`
值，例如 `{ mode: "restart", requiresRestart: true, reason }`，
它会记录写入方的意图，同时不会从 Gateway 网关手中接管重启控制。
</Accordion>
<Accordion title="api.runtime.system">
系统级实用工具。
系统级工具。
```typescript
await api.runtime.system.enqueueSystemEvent(event);
api.runtime.system.requestHeartbeatNow();
api.runtime.system.requestHeartbeat({
source: "other",
intent: "event",
reason: "plugin-event",
});
api.runtime.system.requestHeartbeatNow({ reason: "plugin-event" }); // Deprecated compatibility alias.
const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);
const hint = api.runtime.system.formatNativeDependencyHint(pkg);
```
@ -390,7 +397,7 @@ register(api) {
</Accordion>
<Accordion title="api.runtime.modelAuth">
模型和提供商鉴权解析。
模型和提供商凭证解析。
```typescript
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
@ -402,7 +409,7 @@ register(api) {
</Accordion>
<Accordion title="api.runtime.state">
状态目录解析和基于 SQLite 的键控存储。
状态目录解析，以及基于 SQLite 的键值存储。
```typescript
const stateDir = api.runtime.state.resolveStateDir(process.env);
@ -418,7 +425,7 @@ register(api) {
await store.clear();
```
键控存储会在重启后保留，并按运行时绑定的插件 id 隔离。限制：每个命名空间 `maxEntries`、每个插件 1,000 行活动记录、低于 64KB 的 JSON 值，以及可选的 TTL 过期。
键值存储会在重启后保留，并按运行时绑定的插件 id 隔离。限制：每个命名空间 `maxEntries`、每个插件 1,000 个存活行、JSON 值小于 64KB，以及可选的 TTL 过期。
<Warning>
此版本仅限内置插件。
@ -436,9 +443,9 @@ register(api) {
</Accordion>
<Accordion title="api.runtime.channel">
渠道专用运行时辅助工具（在加载渠道插件时可用）。
渠道专用运行时辅助工具（加载渠道插件时可用）。
`api.runtime.channel.mentions` 是供使用运行时注入的内置渠道插件使用的共享入站提及策略表面：
`api.runtime.channel.mentions` 是使用运行时注入的内置渠道插件共享的入站提及策略表面：
```typescript
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
@ -473,7 +480,7 @@ register(api) {
- `implicitMentionKindWhen`
- `resolveInboundMentionDecision`
`api.runtime.channel.mentions` 有意不暴露较旧的 `resolveMentionGating*` 兼容性辅助工具。优先使用规范化的 `{ facts, policy }` 路径。
`api.runtime.channel.mentions` 有意不暴露旧的 `resolveMentionGating*` 兼容性辅助工具。优先使用规范化的 `{ facts, policy }` 路径。
</Accordion>
</AccordionGroup>
@ -521,7 +528,7 @@ register(api) {
</Steps>
<Note>
运行时存储身份优先使用 `pluginId`。较低层级的 `key` 形式适用于少见场景，即一个插件有意需要多个运行时槽位。
运行时存储身份优先使用 `pluginId`。较低层级的 `key` 形式适用于少见情况，即一个插件有意需要多个运行时槽位。
</Note>
## 其他顶层 `api` 字段
@ -535,7 +542,7 @@ register(api) {
插件显示名称。
</ParamField>
<ParamField path="api.config" type="OpenClawConfig">
当前配置快照（可用时为活动的内存运行时快照）。
当前配置快照（可用时为活动的内存中运行时快照）。
</ParamField>
<ParamField path="api.pluginConfig" type="Record<string, unknown>">
来自 `plugins.entries.<id>.config` 的插件专用配置。

192
docs/zh-CN/tools/index.md
View File

@ -1,55 +1,55 @@
---
read_when:
- 你想了解 OpenClaw 提供了哪些工具
- 你想了解 OpenClaw 提供哪些工具
- 你需要配置、允许或拒绝工具
- 你正在选择使用内置工具、Skills 还是插件
summary: OpenClaw 工具和插件概览：智能体可以做什么以及如何扩展它
- 你正在内置工具、Skills 和插件之间做选择
summary: OpenClaw 工具和插件概览：智能体能做什么以及如何扩展它
title: 工具和插件
x-i18n:
generated_at: "2026-04-30T12:51:57Z"
generated_at: "2026-05-02T13:56:38Z"
model: gpt-5.5
provider: openai
source_hash: 7acfac11669b6f9696a368c08afada8d33e30ac2f452d507f5d1bc36bae367eb
source_hash: 892eb520c14c13e4f55c80aa17ccd2578cc803796844c15cd71674cb2a0a8adf
source_path: tools/index.md
workflow: 16
---
智能体在生成文本之外所做的一切都通过 **工具** 完成。
工具是智能体读取文件、运行命令、浏览 Web、发送
消息以及与设备交互的方式。
智能体在生成文本之外所做的一切都通过**工具**完成。
工具让智能体能够读取文件、运行命令、浏览网页、发送
消息，并与设备交互。
## 工具、Skills 和插件
## 工具、技能和插件
OpenClaw 有三层协同工作：
OpenClaw 有三个协同工作的层：
<Steps>
<Step title="工具是智能体调用的对象">
工具是智能体可以调用的类型化函数（例如 `exec`、`browser`、
`web_search`、`message`）。OpenClaw 随附一组 **内置工具**，
插件可以注册其他工具。
<Step title="Tools are what the agent calls">
工具是智能体可以调用的带类型函数（例如 `exec`、`browser`、
`web_search`、`message`）。OpenClaw 随附一组**内置工具**，
插件可以注册额外的工具。
智能体会看到作为结构化函数定义发送给模型 API 的工具。
智能体看到的工具是发送给模型 API 的结构化函数定义。
</Step>
<Step title="Skills 教智能体何时以及如何使用">
Skill 是一个注入系统提示词的 Markdown 文件（`SKILL.md`）。
Skills 为智能体提供上下文、约束和分步指导，
以便高效使用工具。Skills 存放在你的工作区、共享文件夹中，
<Step title="Skills teach the agent when and how">
技能是注入到系统提示词中的 markdown 文件（`SKILL.md`）。
技能为智能体提供上下文、约束和分步指导，
帮助它有效使用工具。技能存在于你的工作区、共享文件夹中，
或随插件一起提供。
[Skills 参考](/zh-CN/tools/skills) | [创建 Skills](/zh-CN/tools/creating-skills)
[Skills 参考](/zh-CN/tools/skills) | [创建技能](/zh-CN/tools/creating-skills)
</Step>
<Step title="插件将所有内容打包在一起">
插件是一个包，可以注册任意组合的能力：
渠道、模型提供商、工具、Skills、语音、实时转录、
<Step title="Plugins package everything together">
插件是可以注册任意能力组合的包：
渠道、模型提供商、工具、技能、语音、实时转录、
实时语音、媒体理解、图像生成、视频生成、
Web 抓取、Web 搜索等。有些插件是 **核心**（随
OpenClaw 提供），其他插件是 **外部**（由社区发布到 npm）。
web 获取、web 搜索等。有些插件是**核心**插件（随
OpenClaw 提供），另一些是**外部**插件（由社区发布到 npm）。
[安装并配置插件](/zh-CN/tools/plugin) | [构建你自己的插件](/zh-CN/plugins/building-plugins)
[安装和配置插件](/zh-CN/tools/plugin) | [构建你自己的插件](/zh-CN/plugins/building-plugins)
</Step>
</Steps>
@ -58,66 +58,72 @@ OpenClaw 有三层协同工作：
这些工具随 OpenClaw 提供，无需安装任何插件即可使用：
| 工具 | 作用 | 页面 |
| 工具 | 功能 | 页面 |
| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ |
| `exec` / `process` | 运行 shell 命令，管理后台进程 | [Exec](/zh-CN/tools/exec), [Exec 批准](/zh-CN/tools/exec-approvals) |
| `code_execution` | 运行沙箱隔离的远程 Python 分析 | [代码执行](/zh-CN/tools/code-execution) |
| `browser` | 控制 Chromium 浏览器（导航、点击、截图） | [浏览器](/zh-CN/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | 搜索 Web、搜索 X 帖子、抓取页面内容 | [Web](/zh-CN/tools/web), [Web 抓取](/zh-CN/tools/web-fetch) |
| `read` / `write` / `edit` | 工作区中的文件 I/O | |
| `apply_patch` | 多 hunk 文件补丁 | [Apply Patch](/zh-CN/tools/apply-patch) |
| `message` | 跨所有渠道发送消息 | [智能体发送](/zh-CN/tools/agent-send) |
| `canvas` | 驱动 node Canvas（呈现、求值、快照） | |
| `nodes` | 发现并定位已配对设备 | |
| `cron` / `gateway` | 管理定时任务；检查、修补、重启或更新 Gateway 网关 | |
| `image` / `image_generate` | 分析或生成图像 | [图像生成](/zh-CN/tools/image-generation) |
| `music_generate` | 生成音乐曲目 | [音乐生成](/zh-CN/tools/music-generation) |
| `video_generate` | 生成视频 | [视频生成](/zh-CN/tools/video-generation) |
| `tts` | 一次性文本转语音转换 | [TTS](/zh-CN/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | 会话管理、Status 和子智能体编排 | [子智能体](/zh-CN/tools/subagents) |
| `session_status` | 轻量级 `/status` 风格回读和会话模型覆盖 | [会话工具](/zh-CN/concepts/session-tool) |
| `exec` / `process` | 运行 shell 命令，管理后台进程 | [Exec](/zh-CN/tools/exec), [Exec Approvals](/zh-CN/tools/exec-approvals) |
| `code_execution` | 运行沙箱隔离的远程 Python 分析 | [代码执行](/zh-CN/tools/code-execution) |
| `browser` | 控制 Chromium 浏览器（导航、点击、截图） | [浏览器](/zh-CN/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | 搜索 web、搜索 X 帖文、获取页面内容 | [Web](/zh-CN/tools/web), [Web 获取](/zh-CN/tools/web-fetch) |
| `read` / `write` / `edit` | 在工作区中进行文件 I/O | |
| `apply_patch` | 多区块文件补丁 | [应用补丁](/zh-CN/tools/apply-patch) |
| `message` | 跨所有渠道发送消息 | [智能体发送](/zh-CN/tools/agent-send) |
| `canvas` | 驱动 node Canvas（present、eval、snapshot） | |
| `nodes` | 发现并定位已配对设备 | |
| `cron` / `gateway` | 管理定时任务；检查、修补、重启或更新 Gateway 网关 | |
| `image` / `image_generate` | 分析或生成图像 | [图像生成](/zh-CN/tools/image-generation) |
| `music_generate` | 生成音乐曲目 | [音乐生成](/zh-CN/tools/music-generation) |
| `video_generate` | 生成视频 | [视频生成](/zh-CN/tools/video-generation) |
| `tts` | 一次性文本转语音转换 | [TTS](/zh-CN/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | 会话管理、Status 和子智能体编排 | [子智能体](/zh-CN/tools/subagents) |
| `session_status` | 轻量级 `/status` 风格回读和会话模型覆盖 | [会话工具](/zh-CN/concepts/session-tool) |
对于图像工作，请使用 `image` 进行分析，使用 `image_generate` 进行生成或编辑。如果目标是 `openai/*`、`google/*`、`fal/*` 或其他非默认图像提供商，请先配置该提供商的认证/API key。
对于图像工作，使用 `image` 进行分析，使用 `image_generate` 进行生成或编辑。如果你以 `openai/*`、`google/*`、`fal/*` 或其他非默认图像提供商为目标，请先配置该提供商的身份验证/API key。
对于音乐工作，请使用 `music_generate`。如果目标是 `google/*`、`minimax/*` 或其他非默认音乐提供商，请先配置该提供商的认证/API key。
对于音乐工作，使用 `music_generate`。如果你以 `google/*`、`minimax/*` 或其他非默认音乐提供商为目标，请先配置该提供商的身份验证/API key。
对于视频工作，请使用 `video_generate`。如果目标是 `qwen/*` 或其他非默认视频提供商，请先配置该提供商的认证/API key。
对于视频工作，使用 `video_generate`。如果你以 `qwen/*` 或其他非默认视频提供商为目标，请先配置该提供商的身份验证/API key。
对于工作流驱动的音频生成，当 ComfyUI 等插件注册了
`music_generate` 时，请使用它。这与用于文本转语音的 `tts` 分开。
对于由工作流驱动的音频生成，当 ComfyUI 等插件注册了 `music_generate` 时，
使用 `music_generate`。这不同于 `tts`，后者是文本转语音。
`session_status` 是会话组中的轻量级 Status/回读工具。
它回答关于当前会话的 `/status` 风格问题，并且可以
选择性地设置按会话生效的模型覆盖；`model=default` 会清除该
覆盖。与 `/status` 一样，它可以从最新转录用量条目回填稀疏的 token/缓存计数器以及
活动运行时模型标签。
它会回答关于当前会话的 `/status` 风格问题，并且可以
选择性设置按会话生效的模型覆盖；`model=default` 会清除该
覆盖。与 `/status` 一样，它可以从最新的转录使用记录中回填稀疏的 token/cache 计数器和
当前运行时模型标签。
`gateway` 是用于 Gateway 网关操作的仅所有者运行时工具：
`gateway` 是仅所有者可用的 Gateway 网关操作运行时工具：
- `config.schema.lookup`：编辑前查看一个按路径限定的配置子树
- `config.get`：获取当前配置快照 + hash
- `config.patch`：带重启的部分配置更新
- `config.apply`：仅用于完整配置替换
- `update.run`：用于显式自我更新 + 重启
- `config.schema.lookup` 用于在编辑前查询一个按路径限定的配置子树
- `config.get` 用于获取当前配置快照 + 哈希
- `config.patch` 用于带重启的部分配置更新
- `config.apply` 仅用于完整配置替换
- `update.run` 用于显式自更新 + 重启
对于部分更改，优先使用 `config.schema.lookup`，然后使用 `config.patch`。只有在有意替换整个配置时才使用
对于部分更改，优先使用 `config.schema.lookup`，然后使用 `config.patch`。只有在你有意替换整个配置时才使用
`config.apply`。
如需更广泛的配置文档，请阅读 [配置](/zh-CN/gateway/configuration) 和
如需更广泛的配置文档，请阅读[配置](/zh-CN/gateway/configuration)和
[配置参考](/zh-CN/gateway/configuration-reference)。
该工具还会拒绝更改 `tools.exec.ask` 或 `tools.exec.security`；
旧版 `tools.bash.*` 别名会规范化为相同的受保护 exec 路径。
旧版 `tools.bash.*` 别名会规范化到同一组受保护的 exec 路径。
### 插件提供的工具
插件可以注册其他工具。一些示例：
插件可以注册额外工具。一些示例：
- [Diffs](/zh-CN/tools/diffs) — diff 查看器和渲染器
- [LLM 任务](/zh-CN/tools/llm-task) — 用于结构化输出的仅 JSON LLM 步骤
- [Lobster](/zh-CN/tools/lobster) — 带可恢复批准的类型化工作流运行时
- [音乐生成](/zh-CN/tools/music-generation) — 带工作流后端提供商的共享 `music_generate` 工具
- [OpenProse](/zh-CN/prose) — Markdown 优先的工作流编排
- [音乐生成](/zh-CN/tools/music-generation) — 带工作流支持提供商的共享 `music_generate` 工具
- [OpenProse](/zh-CN/prose) — markdown 优先的工作流编排
- [Tokenjuice](/zh-CN/tools/tokenjuice) — 压缩嘈杂的 `exec` 和 `bash` 工具结果
插件工具仍然通过 `api.registerTool(...)` 编写，并在
插件清单的 `contracts.tools` 列表中声明。OpenClaw 在设备发现期间捕获已验证的
工具描述符，并按插件来源和合约缓存它，因此
后续工具规划可以跳过插件运行时加载。工具执行仍会加载
拥有该工具的插件，并调用实时注册的实现。
## 工具配置
### 允许和拒绝列表
@ -134,48 +140,49 @@ OpenClaw 有三层协同工作：
}
```
当显式允许列表解析不到可调用工具时，OpenClaw 会失败关闭。
例如，只有在已加载插件实际注册了 `query_db` 时，`tools.allow: ["query_db"]` 才有效。
如果没有任何内置工具、插件或内置 MCP 工具匹配
允许列表，运行会在模型调用前停止，而不是作为可能幻觉工具结果的
纯文本运行继续。
当显式允许列表解析不到任何可调用工具时，OpenClaw 会默认失败关闭。
例如，`tools.allow: ["query_db"]` 只有在已加载插件实际
注册了 `query_db` 时才有效。如果没有内置工具、插件或内置 MCP 工具匹配该
允许列表，运行会在模型调用之前停止，而不是继续作为
纯文本运行并可能幻觉出工具结果。
### 工具配置文件
`tools.profile` 会在应用 `allow`/`deny` 之前设置基础允许列表。
按智能体覆盖：`agents.list[].tools.profile`。
| 配置文件 | 包含内容 |
| 配置文件 | 包含内容 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `full` | 用于更广泛命令/控制访问的不受限制基线；与不设置 `tools.profile` 相同 |
| `full` | 用于更广泛命令/控制访问的不受限制基线；等同于未设置 `tools.profile` |
| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`music_generate`、`video_generate` |
| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` |
| `minimal` | 仅 `session_status` |
| `minimal` | 仅 `session_status` |
<Note>
`tools.profile: "messaging"` 特意为以渠道为中心的
智能体保持较窄范围。它不包含文件系统、运行时、
`tools.profile: "messaging"` 针对以渠道为中心的
智能体有意保持范围较窄。它排除了文件系统、运行时、
浏览器、canvas、nodes、cron 和 Gateway 网关控制等更广泛的命令/控制工具。使用 `tools.profile: "full"`
作为更广泛命令/控制访问的不受限制基线，然后在需要时用
`tools.allow` / `tools.deny` 收窄访问。
作为更广泛命令/控制访问的不受限制基线，然后在需要时使用
`tools.allow` / `tools.deny` 收窄
访问权限。
</Note>
`coding` 包含轻量级 Web 工具（`web_search`、`web_fetch`、`x_search`），
但不包含完整浏览器控制工具。浏览器自动化可以驱动真实
会话和已登录资料，因此请用
`tools.alsoAllow: ["browser"]` 或按智能体的
但不包含完整的浏览器控制工具。浏览器自动化可以驱动真实
会话和已登录的配置文件，因此请使用
`tools.alsoAllow: ["browser"]` 或按智能体设置的
`agents.list[].tools.alsoAllow: ["browser"]` 显式添加它。
<Note>
在限制性配置文件（`messaging`、`minimal`）下配置 `tools.exec` 或 `tools.fs` 不会隐式扩大该配置文件的允许列表。当你希望限制性配置文件使用这些已配置部分时，请添加显式 `tools.alsoAllow` 条目（例如 exec 使用 `["exec", "process"]`，fs 使用 `["read", "write", "edit"]`）。当存在配置部分但没有匹配的 `alsoAllow` 授权时，OpenClaw 会记录启动警告。
在限制性配置文件（`messaging`、`minimal`）下配置 `tools.exec` 或 `tools.fs`，不会隐式扩大该配置文件的允许列表。当你希望限制性配置文件使用这些已配置的部分时，请添加显式 `tools.alsoAllow` 条目（例如 exec 使用 `["exec", "process"]`，fs 使用 `["read", "write", "edit"]`）。当存在某个配置部分但没有匹配的 `alsoAllow` 授权时，OpenClaw 会记录启动警告。
</Note>
`coding` 和 `messaging` 配置文件还允许在插件键 `bundle-mcp` 下配置的内置 MCP 工具。
当你希望某个配置文件保留正常内置工具但隐藏所有已配置 MCP 工具时，
`coding` 和 `messaging` 配置文件还允许在插件键 `bundle-mcp` 下配置的 bundle MCP 工具。
当你希望某个配置文件保留其正常内置工具但隐藏所有已配置的 MCP 工具时，
添加 `tools.deny: ["bundle-mcp"]`。
`minimal` 配置文件不包含内置 MCP 工具。
`minimal` 配置文件不包含 bundle MCP 工具。
示例（默认使用最广的工具表面）：
示例（默认使用最广的工具范围）：
```json5
{
@ -191,7 +198,7 @@ OpenClaw 有三层协同工作：
| 组 | 工具 |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `group:runtime` | exec, process, code_execution（`bash` 可作为 `exec` 的别名） |
| `group:runtime` | exec, process, code_execution（`bash` 可作为 `exec` 的别名使用） |
| `group:fs` | read, write, edit, apply_patch |
| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status |
| `group:memory` | memory_search, memory_get |
@ -202,22 +209,13 @@ OpenClaw 有三层协同工作：
| `group:nodes` | nodes |
| `group:agents` | agents_list |
| `group:media` | image, image_generate, music_generate, video_generate, tts |
| `group:openclaw` | 所有内置 OpenClaw 工具（不包括插件工具） |
| `group:openclaw` | 所有内置 OpenClaw 工具（不包括插件工具） |
`sessions_history` 返回一个有界、经过安全过滤的召回视图。它会从助手文本中移除
thinking 标签、`<relevant-memories>` 脚手架、纯文本工具调用 XML
载荷（包括 `<tool_call>...</tool_call>`、
`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、
`<function_calls>...</function_calls>`，以及被截断的工具调用块）、
降级后的工具调用脚手架、泄露的 ASCII/全角模型控制
令牌，以及格式不正确的 MiniMax 工具调用 XML，然后应用
脱敏/截断，并在可能的超大行位置使用占位符，而不是作为
原始记录转储。
`sessions_history` 返回一个有边界且经过安全过滤的回忆视图。它会从 assistant 文本中剥离思考标签、`<relevant-memories>` 结构、纯文本工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块）、降级后的工具调用结构、泄露的 ASCII/全角模型控制令牌，以及格式错误的 MiniMax 工具调用 XML，然后应用脱敏/截断，并可能使用超大行占位符，而不是作为原始转录转储。
### 提供商特定限制
使用 `tools.byProvider` 为特定提供商限制工具，而不
更改全局默认值：
使用 `tools.byProvider` 可针对特定提供商限制工具，而不更改全局默认值：
```json5
{