chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
1b95f27208
commit
03e5417382
@ -2,30 +2,30 @@
|
||||
read_when:
|
||||
- 你想创建一个新的 OpenClaw 插件
|
||||
- 你需要一份插件开发快速开始指南
|
||||
- 你正在向 OpenClaw 添加新的渠道、提供商、工具或其他能力
|
||||
- 你正在为 OpenClaw 添加新的渠道、提供商、工具或其他能力
|
||||
sidebarTitle: Getting Started
|
||||
summary: 几分钟内创建你的第一个 OpenClaw 插件
|
||||
title: 构建插件
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T10:03:21Z"
|
||||
generated_at: "2026-05-02T01:10:36Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5c80b831161c93b0a7f65baf1ccea705ccc27b8226180c0fd0ef15fbbefa3d83
|
||||
source_hash: e05c82cd810ed400a293cf0c336efeb6e5a6e081b144eb89150407754a98bc19
|
||||
source_path: plugins/building-plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
插件通过新功能扩展 OpenClaw：渠道、模型提供商、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或任意组合。
|
||||
插件为 OpenClaw 扩展新能力：渠道、模型提供商、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、Web 获取、Web 搜索、智能体工具，或这些能力的任意组合。
|
||||
|
||||
你无需将你的插件添加到 OpenClaw 仓库。发布到
|
||||
你无需把你的插件加入 OpenClaw 仓库。发布到
|
||||
[ClawHub](/zh-CN/tools/clawhub)，用户即可使用
|
||||
`openclaw plugins install <package-name>` 安装。OpenClaw 会先尝试 ClawHub，并会对仍使用 npm 分发的软件包自动回退到 npm。
|
||||
`openclaw plugins install <package-name>` 安装。OpenClaw 会先尝试 ClawHub，并自动回退到 npm，以支持仍在使用 npm 分发的软件包。
|
||||
|
||||
## 前提条件
|
||||
|
||||
- Node >= 22 和一个包管理器（npm 或 pnpm）
|
||||
- 熟悉 TypeScript（ESM）
|
||||
- 对于仓库内插件：已克隆仓库并完成 `pnpm install`
|
||||
- 对于仓库内插件：已克隆仓库并完成 `pnpm install`。源码检出方式的插件开发仅支持 pnpm，因为 OpenClaw 会从 `extensions/*` 工作区软件包加载内置插件。
|
||||
|
||||
## 哪种插件？
|
||||
|
||||
@ -37,17 +37,17 @@ x-i18n:
|
||||
添加模型提供商（LLM、代理或自定义端点）
|
||||
</Card>
|
||||
<Card title="工具 / 钩子插件" icon="wrench" href="/zh-CN/plugins/hooks">
|
||||
注册智能体工具、事件钩子或服务 — 继续阅读下文
|
||||
注册智能体工具、事件钩子或服务 — 请继续阅读
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
对于不能保证在新手引导/设置运行时已安装的渠道插件，请使用来自
|
||||
`openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface(...)`。它会生成一组设置适配器 + 向导，
|
||||
用于提示安装要求，并在插件安装前对真实配置写入采用失败关闭策略。
|
||||
`openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface(...)`。
|
||||
它会生成一组设置适配器 + 向导，用来提示安装要求，并且在插件安装前对真实配置写入采取失败关闭处理。
|
||||
|
||||
## 快速开始：工具插件
|
||||
|
||||
本演练会创建一个注册智能体工具的最小插件。渠道插件和提供商插件有上方链接的专门指南。
|
||||
本 walkthrough 会创建一个注册智能体工具的最小插件。渠道和提供商插件有上面链接的专门指南。
|
||||
|
||||
<Steps>
|
||||
<Step title="创建软件包和清单">
|
||||
@ -87,10 +87,9 @@ x-i18n:
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
每个插件都需要清单，即使没有配置也一样；每个插件也应有意声明
|
||||
`activation.onStartup`。运行时注册的工具需要启动时导入，因此本示例将它设为 `true`。请参阅
|
||||
[清单](/zh-CN/plugins/manifest) 了解完整 schema。规范的 ClawHub
|
||||
发布片段位于 `docs/snippets/plugin-publish/`。
|
||||
每个插件都需要清单，即使没有配置；并且每个插件都应该有意声明
|
||||
`activation.onStartup`。运行时注册的工具需要启动时导入，所以此示例将它设为 `true`。
|
||||
完整 schema 请参阅 [清单](/zh-CN/plugins/manifest)。规范的 ClawHub 发布片段位于 `docs/snippets/plugin-publish/`。
|
||||
|
||||
</Step>
|
||||
|
||||
@ -119,8 +118,8 @@ x-i18n:
|
||||
```
|
||||
|
||||
`definePluginEntry` 用于非渠道插件。对于渠道，请使用
|
||||
`defineChannelPluginEntry` — 参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。
|
||||
如需完整入口点选项，请参阅 [入口点](/zh-CN/plugins/sdk-entrypoints)。
|
||||
`defineChannelPluginEntry` — 参阅 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。
|
||||
完整入口点选项请参阅 [入口点](/zh-CN/plugins/sdk-entrypoints)。
|
||||
|
||||
</Step>
|
||||
|
||||
@ -134,7 +133,7 @@ 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；npm 仍作为尚未迁移到 ClawHub 的软件包的回退选项。
|
||||
|
||||
**仓库内插件：** 放在内置插件工作区树下 — 会自动发现。
|
||||
|
||||
@ -155,14 +154,14 @@ x-i18n:
|
||||
| CLI 推理后端 | `api.registerCliBackend(...)` | [CLI 后端](/zh-CN/gateway/cli-backends) |
|
||||
| 渠道 / 消息 | `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) |
|
||||
| 网页抓取 | `api.registerWebFetchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| 网页搜索 | `api.registerWebSearchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| 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(...)` | 下文 |
|
||||
| 自定义命令 | `api.registerCommand(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
|
||||
@ -171,36 +170,35 @@ x-i18n:
|
||||
| HTTP 路由 | `api.registerHttpRoute(...)` | [内部机制](/zh-CN/plugins/architecture-internals#gateway-http-routes) |
|
||||
| CLI 子命令 | `api.registerCli(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
|
||||
|
||||
如需完整注册 API，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。
|
||||
完整注册 API 请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。
|
||||
|
||||
内置插件在需要模型看到输出前进行异步工具结果重写时，可以使用 `api.registerAgentToolResultMiddleware(...)`。请在 `contracts.agentToolResultMiddleware` 中声明目标运行时，例如
|
||||
`["pi", "codex"]`。这是受信任的内置插件 seam；外部插件应优先使用常规 OpenClaw 插件钩子，除非 OpenClaw 为此能力发展出明确的信任策略。
|
||||
内置插件在需要于模型看到输出前异步重写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。
|
||||
请在 `contracts.agentToolResultMiddleware` 中声明目标运行时，例如
|
||||
`["pi", "codex"]`。这是一个受信任的内置插件接缝；外部插件应优先使用常规 OpenClaw 插件钩子，除非 OpenClaw 为此能力新增明确的信任策略。
|
||||
|
||||
如果你的插件注册自定义 Gateway 网关 RPC 方法，请将它们放在插件特定前缀下。核心管理命名空间（`config.*`、
|
||||
`exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并始终解析为
|
||||
`operator.admin`，即使插件请求更窄的范围也是如此。
|
||||
如果你的插件注册自定义 Gateway 网关 RPC 方法，请将它们放在插件专属前缀下。核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并且始终解析为 `operator.admin`，即使插件请求更窄的作用域也是如此。
|
||||
|
||||
需要牢记的钩子保护语义：
|
||||
需要记住的钩子守卫语义：
|
||||
|
||||
- `before_tool_call`：`{ block: true }` 是终止性决定，会停止较低优先级处理器。
|
||||
- `before_tool_call`：`{ block: false }` 会被视为无决定。
|
||||
- `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` 路由字段，而不是渠道特定的 metadata 键。
|
||||
- `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 键。
|
||||
|
||||
`/approve` 命令通过有界回退同时处理 exec 和插件审批：当找不到 exec 审批 id 时，OpenClaw 会用同一 id 通过插件审批重试。插件审批转发可在配置中通过 `approvals.plugin` 独立配置。
|
||||
`/approve` 命令会通过有界回退同时处理 exec 和插件审批：当找不到 exec 审批 ID 时，OpenClaw 会用同一个 ID 通过插件审批重试。可以通过配置中的 `approvals.plugin` 独立配置插件审批转发。
|
||||
|
||||
如果自定义审批 plumbing 需要检测同一个有界回退场景，请优先使用来自 `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) {
|
||||
@ -237,15 +235,15 @@ 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) {
|
||||
@ -294,23 +292,27 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import { ... } from "openclaw/plugin-sdk";
|
||||
```
|
||||
|
||||
完整的子路径参考见 [SDK 概览](/zh-CN/plugins/sdk-overview)。
|
||||
完整的子路径参考，请参见 [SDK 概览](/zh-CN/plugins/sdk-overview)。
|
||||
|
||||
在你的插件内，使用本地桶文件（`api.ts`、`runtime-api.ts`）进行内部导入，不要通过它的 SDK 路径导入你自己的插件。
|
||||
在你的插件中，使用本地桶文件（`api.ts`、`runtime-api.ts`）进行
|
||||
内部导入，不要通过插件自己的 SDK 路径导入自己的插件。
|
||||
|
||||
对于提供商插件，除非接口确实是通用的，否则应将提供商专用 helper 保留在这些包根桶文件中。当前内置示例：
|
||||
对于提供商插件，除非该接缝确实是通用的，否则请将提供商特定的辅助工具保留在这些包根
|
||||
桶文件中。当前内置示例：
|
||||
|
||||
- Anthropic：Claude 流包装器和 `service_tier` / beta helper
|
||||
- OpenAI：提供商构建器、默认模型 helper、实时提供商
|
||||
- OpenRouter：提供商构建器以及新手引导/配置 helper
|
||||
- Anthropic：Claude 流包装器和 `service_tier` / beta 辅助工具
|
||||
- OpenAI：提供商构建器、默认模型辅助工具、实时提供商
|
||||
- OpenRouter：提供商构建器以及新手引导/配置辅助工具
|
||||
|
||||
如果某个 helper 只在一个内置提供商包内部有用，请将它保留在该包根接口上，而不是提升到 `openclaw/plugin-sdk/*` 中。
|
||||
如果某个辅助工具只在一个内置提供商包内部有用，请将它保留在该
|
||||
包根接缝上，而不是提升到 `openclaw/plugin-sdk/*` 中。
|
||||
|
||||
一些生成的 `openclaw/plugin-sdk/<bundled-id>` helper 接口仍然存在，用于在有已跟踪的所有者使用时维护内置插件。请将这些视为保留表面，而不是新第三方插件的默认模式。
|
||||
一些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助接缝仍然存在，用于在有已跟踪所有者用法时
|
||||
维护内置插件。请将它们视为保留表面，而不是新第三方插件的默认模式。
|
||||
|
||||
## 提交前检查清单
|
||||
|
||||
<Check>**package.json** 有正确的 `openclaw` 元数据</Check>
|
||||
<Check>**package.json** 具有正确的 `openclaw` 元数据</Check>
|
||||
<Check>**openclaw.plugin.json** 清单存在且有效</Check>
|
||||
<Check>入口点使用 `defineChannelPluginEntry` 或 `definePluginEntry`</Check>
|
||||
<Check>所有导入都使用聚焦的 `plugin-sdk/<subpath>` 路径</Check>
|
||||
@ -318,20 +320,20 @@ 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) 的通知，以接收发布公告。
|
||||
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` 的 PR，标题为 `fix(<plugin-id>): beta blocker - <summary>`，并在 PR 和你的 Discord 主题帖中都链接该 issue。贡献者不能给 PR 加标签，因此标题是面向维护者和自动化的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题可能仍会随版本发布。维护者会在 Beta 测试期间关注这些主题帖。
|
||||
6. 沉默表示绿色。如果错过窗口，你的修复很可能会进入下一个周期。
|
||||
3. 测试后，在 `plugin-forum` Discord 渠道中你的插件帖子里发布 `all good` 或说明出了什么问题。如果你还没有帖子，请创建一个。
|
||||
4. 如果有内容损坏，请打开或更新标题为 `Beta blocker: <plugin-name> - <summary>` 的 issue，并应用 `beta-blocker` 标签。将 issue 链接放到你的帖子中。
|
||||
5. 打开一个指向 `main` 的 PR，标题为 `fix(<plugin-id>): beta blocker - <summary>`，并在 PR 和你的 Discord 帖子中都链接该 issue。贡献者不能给 PR 加标签，所以标题是给维护者和自动化使用的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题可能仍会随版本发布。维护者会在 Beta 测试期间关注这些帖子。
|
||||
6. 沉默即表示绿色。如果你错过窗口，你的修复很可能会在下一个周期落地。
|
||||
|
||||
## 后续步骤
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="渠道插件" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
|
||||
构建消息渠道插件
|
||||
构建消息传递渠道插件
|
||||
</Card>
|
||||
<Card title="提供商插件" icon="cpu" href="/zh-CN/plugins/sdk-provider-plugins">
|
||||
构建模型提供商插件
|
||||
@ -339,11 +341,11 @@ import { ... } from "openclaw/plugin-sdk";
|
||||
<Card title="SDK 概览" icon="book-open" href="/zh-CN/plugins/sdk-overview">
|
||||
导入映射和注册 API 参考
|
||||
</Card>
|
||||
<Card title="运行时 Helper" icon="settings" href="/zh-CN/plugins/sdk-runtime">
|
||||
TTS、搜索、通过 api.runtime 使用子智能体
|
||||
<Card title="运行时辅助工具" icon="settings" href="/zh-CN/plugins/sdk-runtime">
|
||||
通过 api.runtime 使用 TTS、搜索和子智能体
|
||||
</Card>
|
||||
<Card title="测试" icon="test-tubes" href="/zh-CN/plugins/sdk-testing">
|
||||
测试工具和模式
|
||||
测试实用工具和模式
|
||||
</Card>
|
||||
<Card title="插件清单" icon="file-json" href="/zh-CN/plugins/manifest">
|
||||
完整清单 schema 参考
|
||||
|
||||
@ -5,31 +5,28 @@ read_when:
|
||||
- 你正在维护打包的 OpenClaw 安装或内置插件清单
|
||||
sidebarTitle: Dependencies
|
||||
summary: OpenClaw 如何安装插件包并解析插件依赖项
|
||||
title: 插件依赖解析
|
||||
title: 插件依赖项解析
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T22:46:03Z"
|
||||
generated_at: "2026-05-02T01:10:40Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 093bbd7d3800ddfcc2546ce53e3ebb01e1897dad146bd10ab7f61efa20f24711
|
||||
source_hash: 6cb8b312dfee5be5f5333477c204eb3643b398a49017ea9ffe88b3c546cc0765
|
||||
source_path: plugins/dependency-resolution.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# 插件依赖解析
|
||||
|
||||
OpenClaw 将插件依赖处理保留在安装/更新时进行。运行时加载
|
||||
不会运行包管理器、修复依赖树，也不会改变 OpenClaw
|
||||
包目录。
|
||||
OpenClaw 将插件依赖工作保留在安装/更新时间。运行时加载不会运行包管理器、修复依赖树，也不会修改 OpenClaw 包目录。
|
||||
|
||||
## 责任划分
|
||||
|
||||
插件包负责自己的依赖图：
|
||||
插件包拥有自己的依赖图：
|
||||
|
||||
- 运行时依赖位于插件包的 `dependencies` 或
|
||||
`optionalDependencies`
|
||||
- SDK/核心导入是 peer，或由 OpenClaw 提供的导入
|
||||
- 运行时依赖位于插件包的 `dependencies` 或 `optionalDependencies`
|
||||
- SDK/核心导入是 peer 依赖，或由 OpenClaw 提供
|
||||
- 本地开发插件自带已安装的依赖
|
||||
- npm 和 git 插件安装到 OpenClaw 拥有的包根目录中
|
||||
- npm 和 git 插件会安装到 OpenClaw 拥有的包根目录中
|
||||
|
||||
OpenClaw 只负责插件生命周期：
|
||||
|
||||
@ -37,17 +34,17 @@ OpenClaw 只负责插件生命周期：
|
||||
- 在明确请求时安装或更新包
|
||||
- 记录安装元数据
|
||||
- 加载插件入口点
|
||||
- 依赖缺失时，给出可操作的错误并失败
|
||||
- 当依赖缺失时，给出可操作的错误并失败
|
||||
|
||||
## 安装根目录
|
||||
|
||||
OpenClaw 使用按来源稳定划分的根目录：
|
||||
OpenClaw 为每种来源使用稳定的根目录：
|
||||
|
||||
- npm 包安装在 `~/.openclaw/npm` 下
|
||||
- git 包克隆到 `~/.openclaw/git` 下
|
||||
- 本地/路径/归档安装会被复制或引用，不会修复依赖
|
||||
- git 包克隆在 `~/.openclaw/git` 下
|
||||
- 本地/路径/归档安装会被复制或引用，但不会修复依赖
|
||||
|
||||
npm 安装在 npm 根目录中运行：
|
||||
npm 安装会在 npm 根目录中运行：
|
||||
|
||||
```bash
|
||||
npm install --prefix ~/.openclaw/npm <spec> --omit=dev --ignore-scripts --no-audit --no-fund
|
||||
@ -59,25 +56,19 @@ git 安装会克隆或刷新仓库，然后运行：
|
||||
npm install --omit=dev --ignore-scripts --no-audit --no-fund
|
||||
```
|
||||
|
||||
随后，已安装的插件会从该包目录加载，因此包本地
|
||||
`node_modules` 解析的工作方式与普通 Node 包相同。
|
||||
随后，已安装的插件会从该包目录加载，因此包本地的 `node_modules` 解析方式与普通 Node 包相同。
|
||||
|
||||
## 本地插件
|
||||
|
||||
本地插件被视为由开发者控制的目录。OpenClaw 不会为它们
|
||||
运行 `npm install`、`pnpm install`，也不会修复依赖。如果本地
|
||||
插件有依赖，请先在该插件中安装它们，然后再加载插件。
|
||||
本地插件被视为开发者控制的目录。OpenClaw 不会为它们运行 `npm install`、`pnpm install` 或依赖修复。如果本地插件有依赖，请在加载它之前先在该插件中安装依赖。
|
||||
|
||||
第三方 TypeScript 本地插件可以使用应急 Jiti 路径。打包的
|
||||
JavaScript 插件和内置内部插件通过原生
|
||||
import/require 加载，而不是通过 Jiti。
|
||||
第三方 TypeScript 本地插件可以使用应急 Jiti 路径。打包的 JavaScript 插件和内置内部插件会通过原生 import/require 加载，而不是通过 Jiti。
|
||||
|
||||
## 启动与重新加载
|
||||
## 启动和重新加载
|
||||
|
||||
Gateway 网关启动和配置重新加载绝不会安装插件依赖。它们会读取
|
||||
插件安装记录、计算入口点，然后加载它。
|
||||
Gateway 网关启动和配置重新加载绝不会安装插件依赖。它们会读取插件安装记录、计算入口点并加载它。
|
||||
|
||||
如果运行时缺少依赖，插件会加载失败，并且错误应指向明确的修复方式：
|
||||
如果运行时缺少某个依赖，插件将加载失败，并且错误应将操作者指向明确的修复方式：
|
||||
|
||||
```bash
|
||||
openclaw plugins update <id>
|
||||
@ -85,24 +76,18 @@ openclaw plugins install <source>
|
||||
openclaw doctor --fix
|
||||
```
|
||||
|
||||
`doctor --fix` 可以清理旧版 OpenClaw 生成的依赖状态，并安装
|
||||
本地安装记录中缺失的已配置可下载插件。它不会修复已安装本地插件的依赖。
|
||||
`doctor --fix` 可以清理旧版 OpenClaw 生成的依赖状态，并安装已配置但本地安装记录缺失的可下载插件。它不会修复已安装本地插件的依赖。
|
||||
|
||||
## 内置插件
|
||||
|
||||
轻量级和核心关键的内置插件会作为 OpenClaw 的一部分发布。
|
||||
它们要么不应包含沉重的运行时依赖树，要么应移出为
|
||||
ClawHub/npm 上的可下载包。
|
||||
轻量级和核心关键的内置插件会作为 OpenClaw 的一部分发布。它们应当没有沉重的运行时依赖树，或者被移出为 ClawHub/npm 上的可下载包。
|
||||
|
||||
内置插件清单不得请求依赖预置。大型或可选的插件功能应作为普通插件
|
||||
打包，并通过与第三方插件相同的 npm/git/ClawHub 路径安装。
|
||||
内置插件清单不得请求依赖暂存。大型或可选的插件功能应作为普通插件打包，并通过与第三方插件相同的 npm/git/ClawHub 路径安装。
|
||||
|
||||
在源码检出中，OpenClaw 会将仓库视为 pnpm monorepo。运行 `pnpm install` 后，内置插件会从 `extensions/<id>` 加载，因此包本地 workspace 依赖可用，并且编辑会被直接拾取。源码检出开发仅支持 pnpm；在仓库根目录运行普通 `npm install` 不是准备内置插件依赖的受支持方式。
|
||||
|
||||
## 旧版清理
|
||||
|
||||
较早的 OpenClaw 版本会在启动时或 Doctor 修复期间生成内置插件
|
||||
依赖根目录。当前的 Doctor 清理会在使用 `--fix` 时移除这些过时的目录和
|
||||
符号链接，包括旧的 `plugin-runtime-deps` 根目录、
|
||||
`.openclaw-runtime-deps*` 清单、生成的插件 `node_modules`、安装
|
||||
暂存目录，以及包本地的 pnpm 存储。
|
||||
较旧的 OpenClaw 版本会在启动时或 Doctor 修复期间生成内置插件依赖根目录。当前的 Doctor 清理会在使用 `--fix` 时移除这些陈旧目录和符号链接，包括旧的 `plugin-runtime-deps` 根目录、`.openclaw-runtime-deps*` 清单、生成的插件 `node_modules`、安装暂存目录，以及包本地 pnpm store。
|
||||
|
||||
这些路径只是旧版残留。新的安装不应创建它们。
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 设置新机器
|
||||
- 你既想要“最新 + 最佳”，又不想破坏你的个人设置
|
||||
- 你想要“最新 + 最强”，同时不破坏你的个人设置
|
||||
summary: OpenClaw 的高级设置和开发工作流
|
||||
title: 设置
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T08:48:33Z"
|
||||
generated_at: "2026-05-02T01:10:30Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f96e5e8d46e694f0dfc67eeeb34f4c49498a56e384c3a2a6266c2214afdc0870
|
||||
source_hash: 101f7911d4a4cba139dd7a464b2ed82e2c80c630ba6ea58486309642c6690ee9
|
||||
source_path: start/setup.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -18,28 +18,28 @@ x-i18n:
|
||||
有关新手引导详情，请参阅[新手引导（CLI）](/zh-CN/start/wizard)。
|
||||
</Note>
|
||||
|
||||
## 简要概览
|
||||
## 太长不读
|
||||
|
||||
根据你想要更新的频率，以及是否想自己运行 Gateway 网关，选择一个设置流程：
|
||||
根据你希望更新的频率，以及是否想自己运行 Gateway 网关，选择一种设置工作流：
|
||||
|
||||
- **定制内容位于仓库之外：** 将你的配置和工作区保存在 `~/.openclaw/openclaw.json` 和 `~/.openclaw/workspace/` 中，这样仓库更新不会影响它们。
|
||||
- **稳定流程（推荐大多数人使用）：** 安装 macOS 应用，并让它运行内置的 Gateway 网关。
|
||||
- **前沿流程（开发）：** 通过 `pnpm gateway:watch` 自己运行 Gateway 网关，然后让 macOS 应用以 Local 模式连接。
|
||||
- **定制内容放在仓库外：**将你的配置和工作区保存在 `~/.openclaw/openclaw.json` 和 `~/.openclaw/workspace/`，这样仓库更新不会影响它们。
|
||||
- **稳定工作流（推荐给大多数人）：**安装 macOS 应用，并让它运行内置的 Gateway 网关。
|
||||
- **前沿工作流（开发）：**通过 `pnpm gateway:watch` 自己运行 Gateway 网关，然后让 macOS 应用以 Local 模式连接。
|
||||
|
||||
## 前置条件（从源码运行）
|
||||
|
||||
- 推荐 Node 24（Node 22 LTS，目前为 `22.14+`，仍受支持）
|
||||
- 首选 `pnpm`（如果你有意使用 [Bun 流程](/zh-CN/install/bun)，也可以使用 Bun）
|
||||
- Docker（可选；仅用于容器化设置/e2e，请参阅 [Docker](/zh-CN/install/docker)）
|
||||
- 推荐 Node 24（仍支持 Node 22 LTS，目前为 `22.14+`）
|
||||
- 源码检出需要 `pnpm`。OpenClaw 在开发模式下会从 `extensions/*` pnpm 工作区包加载内置插件，因此在根目录运行 `npm install` 不会准备完整源码树。
|
||||
- Docker（可选；仅用于容器化设置/e2e — 参见 [Docker](/zh-CN/install/docker)）
|
||||
|
||||
## 定制策略（避免更新造成影响）
|
||||
|
||||
如果你想要“100% 按我定制”_并且_轻松更新，请将你的自定义内容保存在：
|
||||
如果你想要“100% 按我定制”_并且_轻松更新，请将自定义内容保存在：
|
||||
|
||||
- **配置：** `~/.openclaw/openclaw.json`（JSON/类似 JSON5）
|
||||
- **工作区：** `~/.openclaw/workspace`（skills、prompts、memories；将其设为私有 git 仓库）
|
||||
- **配置：**`~/.openclaw/openclaw.json`（JSON/类似 JSON5）
|
||||
- **工作区：**`~/.openclaw/workspace`（Skills、提示词、记忆；建议做成私有 git 仓库）
|
||||
|
||||
只需引导一次：
|
||||
首次引导一次：
|
||||
|
||||
```bash
|
||||
openclaw setup
|
||||
@ -51,7 +51,7 @@ openclaw setup
|
||||
openclaw setup
|
||||
```
|
||||
|
||||
如果你还没有全局安装，请通过 `pnpm openclaw setup` 运行（如果你正在使用 Bun 流程，则使用 `bun run openclaw setup`）。
|
||||
如果你还没有全局安装，请通过 `pnpm openclaw setup` 运行。
|
||||
|
||||
## 从此仓库运行 Gateway 网关
|
||||
|
||||
@ -61,12 +61,12 @@ openclaw setup
|
||||
node openclaw.mjs gateway --port 18789 --verbose
|
||||
```
|
||||
|
||||
## 稳定流程（macOS 应用优先）
|
||||
## 稳定工作流（先使用 macOS 应用）
|
||||
|
||||
1. 安装并启动 **OpenClaw.app**（菜单栏）。
|
||||
2. 完成新手引导/权限检查清单（TCC 提示）。
|
||||
3. 确保 Gateway 网关为 **Local** 且正在运行（由应用管理）。
|
||||
4. 关联界面（示例：WhatsApp）：
|
||||
4. 关联渠道界面（示例：WhatsApp）：
|
||||
|
||||
```bash
|
||||
openclaw channels login
|
||||
@ -82,19 +82,19 @@ openclaw health
|
||||
|
||||
- 运行 `openclaw setup`，然后运行 `openclaw channels login`，再手动启动 Gateway 网关（`openclaw gateway`）。
|
||||
|
||||
## 前沿流程（在终端中运行 Gateway 网关）
|
||||
## 前沿工作流（在终端中运行 Gateway 网关）
|
||||
|
||||
目标：开发 TypeScript Gateway 网关，获得热重载，并保持 macOS 应用 UI 已连接。
|
||||
|
||||
### 0)（可选）也从源码运行 macOS 应用
|
||||
|
||||
如果你还想让 macOS 应用也使用前沿版本：
|
||||
如果你也想使用前沿版本的 macOS 应用：
|
||||
|
||||
```bash
|
||||
./scripts/restart-mac.sh
|
||||
```
|
||||
|
||||
### 1) 启动开发 Gateway 网关
|
||||
### 1) 启动开发版 Gateway 网关
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
@ -103,39 +103,30 @@ pnpm openclaw setup
|
||||
pnpm gateway:watch
|
||||
```
|
||||
|
||||
`gateway:watch` 会在一个具名 tmux 会话中启动或重启 Gateway 网关监听进程，并从交互式终端自动附加。非交互式 shell 会保持分离并打印 `tmux attach -t openclaw-gateway-watch-main`；使用 `OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch` 可让交互式运行保持分离，或使用 `pnpm gateway:watch:raw` 以前台监听模式运行。监听器会在相关源码、配置和内置插件元数据变更时重新加载。
|
||||
`pnpm openclaw setup` 是全新检出时一次性的本地配置/工作区初始化步骤。
|
||||
`gateway:watch` 会在具名 tmux 会话中启动或重启 Gateway 网关监视进程，并从交互式终端自动附加。非交互式 shell 会保持分离并打印 `tmux attach -t openclaw-gateway-watch-main`；使用 `OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch` 可让交互式运行保持分离，或使用 `pnpm gateway:watch:raw` 以前台监视模式运行。监视器会在相关源码、配置和内置插件元数据变更时重新加载。
|
||||
`pnpm openclaw setup` 是新检出仓库的一次性本地配置/工作区初始化步骤。
|
||||
`pnpm gateway:watch` 不会重新构建 `dist/control-ui`，因此在 `ui/` 变更后请重新运行 `pnpm ui:build`，或在开发 Control UI 时使用 `pnpm ui:dev`。
|
||||
|
||||
如果你有意使用 Bun 流程，等价命令如下：
|
||||
|
||||
```bash
|
||||
bun install
|
||||
# 仅首次运行（或重置本地 OpenClaw 配置/工作区后）
|
||||
bun run openclaw setup
|
||||
bun run gateway:watch
|
||||
```
|
||||
|
||||
### 2) 将 macOS 应用指向你正在运行的 Gateway 网关
|
||||
### 2) 将 macOS 应用指向正在运行的 Gateway 网关
|
||||
|
||||
在 **OpenClaw.app** 中：
|
||||
|
||||
- 连接模式：**Local**
|
||||
应用会连接到已配置端口上正在运行的 Gateway 网关。
|
||||
- Connection Mode：**Local**
|
||||
应用会连接到配置端口上正在运行的 gateway。
|
||||
|
||||
### 3) 验证
|
||||
|
||||
- 应用内 Gateway 网关状态应显示 **“正在使用现有 Gateway 网关 …”**
|
||||
- 应用内 Gateway 网关 Status 应显示 **“正在使用现有 gateway …”**
|
||||
- 或通过 CLI：
|
||||
|
||||
```bash
|
||||
openclaw health
|
||||
```
|
||||
|
||||
### 常见陷阱
|
||||
### 常见坑点
|
||||
|
||||
- **端口错误：** Gateway 网关 WS 默认值为 `ws://127.0.0.1:18789`；保持应用和 CLI 使用同一端口。
|
||||
- **状态存储位置：**
|
||||
- **端口错误：**Gateway 网关 WS 默认值为 `ws://127.0.0.1:18789`；保持应用和 CLI 使用同一端口。
|
||||
- **状态存放位置：**
|
||||
- 渠道/提供商状态：`~/.openclaw/credentials/`
|
||||
- 模型认证配置文件：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- 会话：`~/.openclaw/agents/<agentId>/sessions/`
|
||||
@ -143,39 +134,39 @@ openclaw health
|
||||
|
||||
## 凭证存储映射
|
||||
|
||||
在调试认证或决定备份内容时使用此映射：
|
||||
调试认证或决定备份内容时使用此表：
|
||||
|
||||
- **WhatsApp**：`~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
|
||||
- **Telegram 机器人令牌**：配置/环境变量或 `channels.telegram.tokenFile`（仅普通文件；拒绝符号链接）
|
||||
- **Discord 机器人令牌**：配置/环境变量或 SecretRef（env/file/exec 提供商）
|
||||
- **Slack 令牌**：配置/环境变量（`channels.slack.*`）
|
||||
- **Telegram bot token**：配置/环境变量或 `channels.telegram.tokenFile`（仅常规文件；拒绝符号链接）
|
||||
- **Discord bot token**：配置/环境变量或 SecretRef（环境变量/文件/exec 提供商）
|
||||
- **Slack token**：配置/环境变量（`channels.slack.*`）
|
||||
- **配对允许列表**：
|
||||
- `~/.openclaw/credentials/<channel>-allowFrom.json`（默认账户）
|
||||
- `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json`（非默认账户）
|
||||
- **模型认证配置文件**：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- **文件支持的 secrets 有效载荷（可选）**：`~/.openclaw/secrets.json`
|
||||
- **文件支持的密钥载荷（可选）**：`~/.openclaw/secrets.json`
|
||||
- **旧版 OAuth 导入**：`~/.openclaw/credentials/oauth.json`
|
||||
更多详情：[安全](/zh-CN/gateway/security#credential-storage-map)。
|
||||
|
||||
## 更新（不破坏你的设置）
|
||||
|
||||
- 将 `~/.openclaw/workspace` 和 `~/.openclaw/` 视为“你的内容”；不要把个人 prompts/配置放进 `openclaw` 仓库。
|
||||
- 更新源码：`git pull` + 你选择的包管理器安装步骤（默认 `pnpm install`；Bun 流程使用 `bun install`）+ 继续使用匹配的 `gateway:watch` 命令。
|
||||
- 将 `~/.openclaw/workspace` 和 `~/.openclaw/` 视为“你的东西”；不要把个人提示词/配置放进 `openclaw` 仓库。
|
||||
- 更新源码：`git pull` + `pnpm install` + 继续使用 `pnpm gateway:watch`。
|
||||
|
||||
## Linux（systemd 用户服务）
|
||||
|
||||
Linux 安装使用 systemd **用户**服务。默认情况下，systemd 会在注销/空闲时停止用户服务，这会终止 Gateway 网关。新手引导会尝试为你启用 linger（可能会提示输入 sudo）。如果仍未启用，请运行：
|
||||
Linux 安装使用 systemd **用户**服务。默认情况下，systemd 会在登出/空闲时停止用户服务，从而终止 Gateway 网关。新手引导会尝试为你启用 lingering（可能提示输入 sudo）。如果它仍未开启，请运行：
|
||||
|
||||
```bash
|
||||
sudo loginctl enable-linger $USER
|
||||
```
|
||||
|
||||
对于常驻或多用户服务器，请考虑使用 **system** 服务而不是用户服务（无需 linger）。systemd 说明请参阅 [Gateway 网关运行手册](/zh-CN/gateway)。
|
||||
对于始终在线或多用户服务器，请考虑使用**系统**服务而不是用户服务（无需 lingering）。有关 systemd 说明，请参阅 [Gateway 网关运行手册](/zh-CN/gateway)。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Gateway 网关运行手册](/zh-CN/gateway)（标志、监督、端口）
|
||||
- [Gateway 网关配置](/zh-CN/gateway/configuration)（配置架构 + 示例）
|
||||
- [Discord](/zh-CN/channels/discord) 和 [Telegram](/zh-CN/channels/telegram)（回复标签 + replyToMode 设置）
|
||||
- [OpenClaw 助手设置](/zh-CN/start/openclaw)
|
||||
- [macOS 应用](/zh-CN/platforms/macos)（Gateway 网关生命周期）
|
||||
- [Gateway 网关配置](/zh-CN/gateway/configuration)（配置 schema + 示例）
|
||||
- [Discord](/zh-CN/channels/discord) 和 [Telegram](/zh-CN/channels/telegram)（reply tags + replyToMode 设置）
|
||||
- [OpenClaw assistant 设置](/zh-CN/start/openclaw)
|
||||
- [macOS 应用](/zh-CN/platforms/macos)（gateway 生命周期）
|
||||
|
||||
@ -7,26 +7,26 @@ sidebarTitle: Install and Configure
|
||||
summary: 安装、配置和管理 OpenClaw 插件
|
||||
title: 插件
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T22:18:30Z"
|
||||
generated_at: "2026-05-02T01:10:39Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 45d4804c55d70000cf471d9d258204ef0028c30d5a731750c37f5d40991b72a0
|
||||
source_hash: dee1689b502a1ce60f4921d216f8d8a00fbb131bc993cfabb4e0295825c1fdb2
|
||||
source_path: tools/plugin.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
插件通过新能力扩展 OpenClaw：渠道、模型提供商、Agent harnesses、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、Web 搜索等。一些插件是 **core**（随 OpenClaw 提供），其他则是 **external**。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。Npm 仍支持直接安装，并在迁移完成前支持一组临时的 OpenClaw 自有插件包。
|
||||
插件通过新能力扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页获取、Web 搜索等。某些插件是**核心**插件（随 OpenClaw 一起提供），其他则是**外部**插件。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。Npm 仍支持直接安装，并在迁移完成前支持一组临时的 OpenClaw 自有插件包。
|
||||
|
||||
## 快速开始
|
||||
|
||||
<Steps>
|
||||
<Step title="See what is loaded">
|
||||
<Step title="查看已加载的内容">
|
||||
```bash
|
||||
openclaw plugins list
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Install a plugin">
|
||||
<Step title="安装插件">
|
||||
```bash
|
||||
# From npm
|
||||
openclaw plugins install npm:@acme/openclaw-plugin
|
||||
@ -41,16 +41,16 @@ x-i18n:
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Restart the Gateway">
|
||||
<Step title="重启 Gateway 网关">
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
然后在你的配置文件中的 `plugins.entries.\<id\>.config` 下配置。
|
||||
然后在配置文件的 `plugins.entries.\<id\>.config` 下进行配置。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Verify the plugin">
|
||||
<Step title="验证插件">
|
||||
```bash
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
|
||||
@ -58,7 +58,7 @@ x-i18n:
|
||||
openclaw <plugin-command> --help
|
||||
```
|
||||
|
||||
当你需要证明已注册的工具、服务、Gateway 网关方法、钩子或插件自有 CLI 命令时，请使用 `--runtime`。普通的 `inspect` 是冷态 manifest/registry 检查，会有意避免导入插件运行时。
|
||||
当你需要证明已注册的工具、服务、Gateway 网关方法、钩子或插件自有 CLI 命令时，请使用 `--runtime`。普通的 `inspect` 是冷态清单/注册表检查，并且会有意避免导入插件运行时。
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -71,15 +71,17 @@ x-i18n:
|
||||
/plugin enable <plugin-id>
|
||||
```
|
||||
|
||||
安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 `clawhub:<pkg>`、显式 `npm:<pkg>`、显式 `git:<repo>`，或裸包规范（先 ClawHub，再回退到 npm）。
|
||||
安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 `clawhub:<pkg>`、显式 `npm:<pkg>`、显式 `git:<repo>`，或裸包规范（先尝试 ClawHub，再回退到 npm）。
|
||||
|
||||
如果配置无效，安装通常会失败关闭，并指向 `openclaw doctor --fix`。唯一的恢复例外是一个狭窄的内置插件重装路径，用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。
|
||||
在 Gateway 网关启动期间，某个插件的无效配置会被隔离到该插件：启动会记录 `plugins.entries.<id>.config` 问题，在加载期间跳过该插件，并保持其他插件和渠道在线。运行 `openclaw doctor --fix` 可通过禁用该插件条目并移除其无效配置载荷来隔离错误插件配置；常规配置备份会保留之前的值。
|
||||
当渠道配置引用了一个不再可发现的插件，但同一个过时插件 ID 仍保留在插件配置或安装记录中时，Gateway 网关启动会记录警告并跳过该渠道，而不是阻塞所有其他渠道。运行 `openclaw doctor --fix` 可移除过时的渠道/插件条目；没有过时插件证据的未知渠道键仍会验证失败，这样拼写错误仍然可见。
|
||||
如果设置了 `plugins.enabled: false`，过时的插件引用会被视为惰性：Gateway 网关启动会跳过插件发现/加载工作，`openclaw doctor` 会保留已禁用的插件配置，而不是自动移除它。若你希望移除过时插件 ID，请先重新启用插件，再运行 Doctor 清理。
|
||||
如果配置无效，安装通常会失败关闭，并指引你运行 `openclaw doctor --fix`。唯一的恢复例外是一个狭窄的内置插件重装路径，适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。
|
||||
在 Gateway 网关启动期间，某个插件的无效配置会被隔离到该插件：启动日志会记录 `plugins.entries.<id>.config` 问题，在加载期间跳过该插件，并保持其他插件和渠道在线。运行 `openclaw doctor --fix` 可以通过禁用该插件条目并移除其无效配置载荷来隔离有问题的插件配置；常规配置备份会保留先前的值。
|
||||
当某个渠道配置引用了不再可发现的插件，但同一个过时插件 ID 仍保留在插件配置或安装记录中时，Gateway 网关启动会记录警告并跳过该渠道，而不是阻塞所有其他渠道。运行 `openclaw doctor --fix` 可以移除过时的渠道/插件条目；没有过时插件证据的未知渠道键名仍会验证失败，因此拼写错误仍然可见。
|
||||
如果设置了 `plugins.enabled: false`，过时插件引用会被视为惰性：Gateway 网关启动会跳过插件发现/加载工作，并且 `openclaw doctor` 会保留已禁用的插件配置，而不是自动移除它。若要移除过时插件 ID，请先重新启用插件，再运行 Doctor 清理。
|
||||
|
||||
插件依赖安装只会在显式安装/更新或 Doctor 修复流程期间发生。Gateway 网关启动、配置重载和运行时检查不会运行包管理器或修复依赖树。本地插件必须已安装好其依赖，而 npm、git 和 ClawHub 插件会安装到 OpenClaw 管理的插件根目录下，并使用包本地依赖。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。
|
||||
有关安装时生命周期，请参阅 [插件依赖解析](/zh-CN/plugins/dependency-resolution)。
|
||||
插件依赖安装只会在显式安装/更新或 Doctor 修复流程中发生。Gateway 网关启动、配置重载和运行时检查不会运行包管理器，也不会修复依赖树。本地插件必须已经安装其依赖，而 npm、git 和 ClawHub 插件会安装在 OpenClaw 托管的插件根目录下，并带有包本地依赖。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。
|
||||
有关安装时生命周期，请参阅[插件依赖解析](/zh-CN/plugins/dependency-resolution)。
|
||||
|
||||
源码检出是 pnpm 工作区。如果你克隆 OpenClaw 来开发内置插件，请运行 `pnpm install`；随后 OpenClaw 会从 `extensions/<id>` 加载内置插件，因此编辑内容和包本地依赖会被直接使用。普通 npm 根安装适用于打包版 OpenClaw，而不是源码检出开发。
|
||||
|
||||
## 插件类型
|
||||
|
||||
@ -90,15 +92,15 @@ OpenClaw 识别两种插件格式：
|
||||
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
|
||||
| **Bundle** | Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
|
||||
|
||||
两者都会显示在 `openclaw plugins list` 下。有关 bundle 详情，请参阅 [插件 Bundle](/zh-CN/plugins/bundles)。
|
||||
两者都会显示在 `openclaw plugins list` 下。有关 Bundle 详情，请参阅[插件 Bundle](/zh-CN/plugins/bundles)。
|
||||
|
||||
如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
|
||||
如果你正在编写原生插件，请从[构建插件](/zh-CN/plugins/building-plugins)和[插件 SDK 概览](/zh-CN/plugins/sdk-overview)开始。
|
||||
|
||||
## 包入口点
|
||||
|
||||
原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。每个条目都必须留在包目录内，并解析为可读的运行时文件，或解析为带有可推断构建后 JavaScript 对应文件的 TypeScript 源文件，例如 `src/index.ts` 对应 `dist/index.js`。
|
||||
原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。每个条目都必须位于包目录内，并解析到可读取的运行时文件，或者解析到 TypeScript 源文件，且该源文件具有可推断的已构建 JavaScript 对应文件，例如从 `src/index.ts` 到 `dist/index.js`。
|
||||
|
||||
当已发布的运行时文件与源条目不在相同路径时，请使用 `openclaw.runtimeExtensions`。如果存在，`runtimeExtensions` 必须为每个 `extensions` 条目包含且仅包含一个条目。列表不匹配会导致安装和插件发现失败，而不是静默回退到源路径。如果你还发布 `openclaw.setupEntry`，请使用 `openclaw.runtimeSetupEntry` 指向其构建后的 JavaScript 对应文件；声明后该文件即为必需。
|
||||
当已发布的运行时文件路径与源条目路径不相同时，请使用 `openclaw.runtimeExtensions`。存在时，`runtimeExtensions` 必须为每个 `extensions` 条目精确包含一个条目。列表不匹配会导致安装和插件发现失败，而不是静默回退到源路径。如果你还发布了 `openclaw.setupEntry`，请为其已构建的 JavaScript 对应文件使用 `openclaw.runtimeSetupEntry`；声明后该文件即为必需。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -114,9 +116,9 @@ OpenClaw 识别两种插件格式：
|
||||
|
||||
### 迁移期间的 OpenClaw 自有 npm 包
|
||||
|
||||
ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版本已经内置许多官方插件，因此在常规设置中无需单独 npm 安装。直到所有 OpenClaw 自有插件都迁移到 ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 `@openclaw/*` 插件包，用于较旧/自定义安装和直接 npm 工作流。
|
||||
ClawHub 是大多数插件的主要分发路径。当前打包版 OpenClaw 已经内置了许多官方插件，因此在普通设置中这些插件不需要单独通过 npm 安装。在所有 OpenClaw 自有插件迁移到 ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 `@openclaw/*` 插件包，用于旧版/自定义安装和直接 npm 工作流。
|
||||
|
||||
如果 npm 报告某个 `@openclaw/*` 插件包已弃用，该包版本来自较旧的外部包序列。请使用当前 OpenClaw 内置的插件或本地检出，直到发布更新的 npm 包。
|
||||
如果 npm 报告某个 `@openclaw/*` 插件包已弃用，则该包版本来自较旧的外部包发布线。请使用当前 OpenClaw 的内置插件或本地检出版本，直到发布更新的 npm 包。
|
||||
|
||||
| 插件 | 包 | 文档 |
|
||||
| --------------- | -------------------------- | ------------------------------------------ |
|
||||
@ -134,10 +136,10 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |
|
||||
|
||||
### Core（随 OpenClaw 提供）
|
||||
### 核心（随 OpenClaw 一起提供）
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Model providers (enabled by default)">
|
||||
<Accordion title="模型提供商（默认启用）">
|
||||
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
|
||||
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
|
||||
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
|
||||
@ -145,26 +147,26 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版
|
||||
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Memory plugins">
|
||||
<Accordion title="记忆插件">
|
||||
- `memory-core` — 内置记忆搜索（默认通过 `plugins.slots.memory`）
|
||||
- `memory-lancedb` — 基于 LanceDB 的长期记忆，支持自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
|
||||
- `memory-lancedb` — 由 LanceDB 支持的长期记忆，带自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
|
||||
|
||||
有关 OpenAI 兼容的 embedding 设置、Ollama 示例、召回限制和故障排除，请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)。
|
||||
有关 OpenAI 兼容嵌入设置、Ollama 示例、召回限制和故障排除，请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Speech providers (enabled by default)">
|
||||
<Accordion title="语音提供商（默认启用）">
|
||||
`elevenlabs`, `microsoft`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Other">
|
||||
<Accordion title="其他">
|
||||
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用）
|
||||
- `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用）
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
在找第三方插件？请参阅 [社区插件](/zh-CN/plugins/community)。
|
||||
在寻找第三方插件？请参阅[社区插件](/zh-CN/plugins/community)。
|
||||
|
||||
## 配置
|
||||
|
||||
@ -182,37 +184,37 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 描述 |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| `enabled` | 主开关（默认：`true`） |
|
||||
| `allow` | 插件允许列表（可选） |
|
||||
| `deny` | 插件拒绝列表（可选；拒绝优先） |
|
||||
| `load.paths` | 额外插件文件/目录 |
|
||||
| `slots` | 独占 slot 选择器（例如 `memory`、`contextEngine`） |
|
||||
| `entries.\<id\>` | 每插件开关 + 配置 |
|
||||
| 字段 | 描述 |
|
||||
| ---------------- | ------------------------------------------------------- |
|
||||
| `enabled` | 主开关（默认：`true`） |
|
||||
| `allow` | 插件允许列表（可选） |
|
||||
| `deny` | 插件拒绝列表（可选；拒绝优先） |
|
||||
| `load.paths` | 额外插件文件/目录 |
|
||||
| `slots` | 独占槽选择器（例如 `memory`、`contextEngine`） |
|
||||
| `entries.\<id\>` | 每个插件的开关 + 配置 |
|
||||
|
||||
`plugins.allow` 是排他的。当它非空时，只有列出的插件可以加载或暴露工具，即使 `tools.allow` 包含 `"*"` 或某个特定的插件自有工具名称。如果工具允许列表引用了插件工具，请将所属插件 ID 添加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对此形态发出警告。
|
||||
`plugins.allow` 是排他的。当它非空时，只有列出的插件可以加载或暴露工具，即使 `tools.allow` 包含 `"*"` 或某个具体的插件自有工具名称也是如此。如果工具允许列表引用了插件工具，请将所属插件 ID 添加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对此形态发出警告。
|
||||
|
||||
配置更改**需要重启 Gateway 网关**。如果 Gateway 网关运行时启用了配置监听 + 进程内重启（默认 `openclaw gateway` 路径），该重启通常会在配置写入落地后片刻自动执行。原生插件运行时代码或生命周期钩子没有受支持的热重载路径；在期望更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或 provider/运行时钩子运行前，请重启正在服务实时渠道的 Gateway 网关进程。
|
||||
配置变更**需要重启 Gateway 网关**。如果 Gateway 网关正在以启用配置监视 + 进程内重启的方式运行（默认的 `openclaw gateway` 路径），该重启通常会在配置写入落地后的片刻自动执行。原生插件运行时代码或生命周期钩子没有受支持的热重载路径；在期望更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或 provider/运行时钩子运行之前，请重启正在服务实时渠道的 Gateway 网关进程。
|
||||
|
||||
`openclaw plugins list` 是本地插件 registry/配置快照。那里显示为 `enabled` 的插件意味着持久化 registry 和当前配置允许该插件参与。它并不证明已经运行的远程 Gateway 网关子进程已重启到相同插件代码。在带有包装进程的 VPS/容器设置中，请将重启发送到实际的 `openclaw gateway run` 进程，或针对正在运行的 Gateway 网关使用 `openclaw gateway restart`。
|
||||
`openclaw plugins list` 是本地插件注册表/配置快照。其中显示为 `enabled` 的插件意味着持久化注册表和当前配置允许该插件参与。它并不能证明已经运行的远程 Gateway 网关子进程已重启并进入相同的插件代码。在使用包装进程的 VPS/容器设置中，请将重启发送到实际的 `openclaw gateway run` 进程，或针对正在运行的 Gateway 网关使用 `openclaw gateway restart`。
|
||||
|
||||
<Accordion title="Plugin states: disabled vs missing vs invalid">
|
||||
- **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。
|
||||
- **缺失**：配置引用了一个发现流程未找到的插件 ID。
|
||||
- **无效**：插件存在，但其配置与声明的 schema 不匹配。Gateway 网关启动只会跳过该插件；`openclaw doctor --fix` 可以通过禁用无效条目并移除其配置载荷来隔离该条目。
|
||||
<Accordion title="插件状态：已禁用 vs 缺失 vs 无效">
|
||||
- **已禁用**：插件存在，但启用规则将其关闭。配置会保留。
|
||||
- **缺失**：配置引用了设备发现未找到的插件 ID。
|
||||
- **无效**：插件存在，但它的配置与声明的 schema 不匹配。Gateway 网关启动只会跳过该插件；`openclaw doctor --fix` 可以通过禁用它并移除其配置载荷来隔离该无效条目。
|
||||
|
||||
</Accordion>
|
||||
|
||||
## 设备发现和优先级
|
||||
|
||||
OpenClaw 按以下顺序扫描插件（先匹配者优先）：
|
||||
OpenClaw 按以下顺序扫描插件（第一个匹配项胜出）：
|
||||
|
||||
<Steps>
|
||||
<Step title="配置路径">
|
||||
`plugins.load.paths` — 显式文件或目录路径。指向
|
||||
OpenClaw 自身打包内置插件目录的路径会被忽略；
|
||||
运行 `openclaw doctor --fix` 来移除这些过时别名。
|
||||
`plugins.load.paths` — 显式文件或目录路径。指回
|
||||
OpenClaw 自身打包的内置插件目录的路径会被忽略；
|
||||
运行 `openclaw doctor --fix` 可移除这些过时别名。
|
||||
</Step>
|
||||
|
||||
<Step title="工作区插件">
|
||||
@ -224,62 +226,64 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）：
|
||||
</Step>
|
||||
|
||||
<Step title="内置插件">
|
||||
随 OpenClaw 一起发布。许多插件默认启用（模型提供商、语音）。
|
||||
随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。
|
||||
其他插件需要显式启用。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
打包安装和 Docker 镜像通常会从已编译的 `dist/extensions` 树解析内置插件。如果一个内置插件源目录被
|
||||
绑定挂载到匹配的打包源路径上，例如
|
||||
打包安装和 Docker 镜像通常会从已编译的
|
||||
`dist/extensions` 树解析内置插件。如果某个内置插件源目录被
|
||||
bind-mounted 到匹配的打包源路径上，例如
|
||||
`/app/extensions/synology-chat`，OpenClaw 会将该挂载的源目录
|
||||
视为内置源覆盖层，并在打包的
|
||||
`/app/dist/extensions/synology-chat` 包之前发现它。这能让维护者容器
|
||||
循环保持可用，而不必把每个内置插件都切回 TypeScript 源码。
|
||||
设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist 包，
|
||||
即使存在源覆盖挂载也是如此。
|
||||
`/app/dist/extensions/synology-chat` bundle 之前发现它。这样可以让维护者容器
|
||||
循环继续工作，而无需把每个内置插件都切回 TypeScript 源码。
|
||||
设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist bundle，
|
||||
即使存在源覆盖层挂载也是如此。
|
||||
|
||||
### 启用规则
|
||||
|
||||
- `plugins.enabled: false` 会禁用所有插件，并跳过插件发现/加载工作
|
||||
- `plugins.deny` 始终优先于 allow
|
||||
- `plugins.deny` 总是优先于 allow
|
||||
- `plugins.entries.\<id\>.enabled: false` 会禁用该插件
|
||||
- 工作区来源的插件**默认禁用**（必须显式启用）
|
||||
- 内置插件遵循内置默认启用集合，除非被覆盖
|
||||
- 独占槽位可以强制启用该槽位选择的插件
|
||||
- 当配置命名了插件拥有的表面时，某些选择性启用的内置插件会自动启用，
|
||||
- 内置插件遵循内建的默认开启集合，除非被覆盖
|
||||
- 独占槽位可以强制启用为该槽位选择的插件
|
||||
- 当配置命名了插件拥有的表面时，一些内置的选择启用插件会自动启用，
|
||||
例如提供商模型引用、渠道配置或 harness 运行时
|
||||
- 当 `plugins.enabled: false` 处于活动状态时，过时插件配置会被保留；
|
||||
如果你想移除过时 id，请先重新启用插件再运行 Doctor 清理
|
||||
- OpenAI 系列 Codex 路由保持独立的插件边界：
|
||||
`openai-codex/*` 属于 OpenAI 插件，而内置 Codex
|
||||
如果你希望移除过时 ID，请先重新启用插件，再运行 Doctor 清理
|
||||
- OpenAI 系列 Codex 路由保持独立插件边界：
|
||||
`openai-codex/*` 属于 OpenAI 插件，而内置的 Codex
|
||||
app-server 插件由 `agentRuntime.id: "codex"` 或旧版
|
||||
`codex/*` 模型引用选择
|
||||
|
||||
## 运行时钩子故障排除
|
||||
|
||||
如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子
|
||||
没有在实时聊天流量中运行，请先检查这些项目：
|
||||
没有在实时聊天流量中运行，请先检查这些项：
|
||||
|
||||
- 运行 `openclaw gateway status --deep --require-rpc`，并确认活动的
|
||||
Gateway 网关 URL、配置文件、配置路径和进程就是你正在编辑的那些。
|
||||
- 在插件安装/配置/代码变更后重启实时 Gateway 网关。在包装容器中，
|
||||
PID 1 可能只是一个 supervisor；请重启或向子
|
||||
Gateway 网关 URL、profile、配置路径和进程就是你正在编辑的那些。
|
||||
- 在插件安装/配置/代码变更后重启实时 Gateway 网关。在 wrapper
|
||||
容器中，PID 1 可能只是 supervisor；请重启或向子
|
||||
`openclaw gateway run` 进程发送信号。
|
||||
- 使用 `openclaw plugins inspect <id> --runtime --json` 确认钩子注册和
|
||||
诊断。非内置会话钩子，例如 `llm_input`、
|
||||
`llm_output`、`before_agent_finalize` 和 `agent_end`，需要
|
||||
诊断。非内置会话钩子（如 `llm_input`、
|
||||
`llm_output`、`before_agent_finalize` 和 `agent_end`）需要
|
||||
`plugins.entries.<id>.hooks.allowConversationAccess=true`。
|
||||
- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型
|
||||
解析之前运行；`llm_output` 只会在一次模型尝试
|
||||
产生助手输出后运行。
|
||||
生成 assistant 输出之后运行。
|
||||
- 要证明有效会话模型，请使用 `openclaw sessions` 或
|
||||
Gateway 网关会话/Status 表面；调试提供商载荷时，使用
|
||||
`--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
|
||||
Gateway 网关会话/Status 表面；调试提供商载荷时，请使用
|
||||
`--raw-stream --raw-stream-path <path>` 启动
|
||||
Gateway 网关。
|
||||
|
||||
### 缓慢的插件工具设置
|
||||
|
||||
如果智能体轮次在准备工具时看起来停滞，请启用 trace 日志并
|
||||
检查插件工具工厂计时行：
|
||||
如果智能体轮次在准备工具时似乎停滞，请启用 trace 日志并
|
||||
检查插件工具工厂耗时行：
|
||||
|
||||
```bash
|
||||
openclaw config set logging.level trace
|
||||
@ -292,20 +296,20 @@ openclaw logs --follow
|
||||
[trace:plugin-tools] factory timings ...
|
||||
```
|
||||
|
||||
摘要会列出总工厂时间和最慢的插件工具工厂，
|
||||
包括插件 id、声明的工具名称、结果形状，以及该工具是否
|
||||
可选。当单个工厂至少耗时 1 秒，或插件工具工厂准备总耗时至少 5 秒时，
|
||||
慢行会提升为警告。
|
||||
摘要会列出总工厂耗时以及最慢的插件工具工厂，
|
||||
包括插件 ID、声明的工具名称、结果形状，以及该工具是否为
|
||||
可选项。当单个工厂耗时至少
|
||||
1 秒，或插件工具工厂准备总耗时至少 5 秒时，慢速行会提升为警告。
|
||||
|
||||
如果某个插件占用了大部分耗时，请检查其运行时注册：
|
||||
如果某个插件主导了耗时，请检查其运行时注册：
|
||||
|
||||
```bash
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
```
|
||||
|
||||
然后更新、重新安装或禁用该插件。插件作者应将
|
||||
昂贵的依赖加载移动到工具执行路径之后，而不是在
|
||||
工具工厂内部执行。
|
||||
昂贵的依赖加载移动到工具执行路径之后，而不是放在
|
||||
工具工厂内部。
|
||||
|
||||
### 重复的渠道或工具所有权
|
||||
|
||||
@ -315,35 +319,35 @@ openclaw plugins inspect <plugin-id> --runtime --json
|
||||
- `channel setup already registered: <channel-id> (<plugin-id>)`
|
||||
- `plugin tool name conflict (<plugin-id>): <tool-name>`
|
||||
|
||||
这些表示超过一个已启用插件正在尝试拥有同一个渠道、
|
||||
设置流程或工具名称。最常见的原因是外部渠道插件
|
||||
安装在一个现在已提供相同渠道 id 的内置插件旁边。
|
||||
这些表示有多个已启用插件正在尝试拥有同一个渠道、
|
||||
设置流程或工具名称。最常见的原因是一个外部渠道插件
|
||||
安装在某个内置插件旁边，而后者现在也提供相同的渠道 ID。
|
||||
|
||||
调试步骤：
|
||||
|
||||
- 运行 `openclaw plugins list --enabled --verbose` 查看每个已启用插件
|
||||
及其来源。
|
||||
- 对每个疑似插件运行 `openclaw plugins inspect <id> --runtime --json`，
|
||||
并比较 `channels`、`channelConfigs`、`tools` 和诊断。
|
||||
- 对每个可疑插件运行 `openclaw plugins inspect <id> --runtime --json`，并
|
||||
比较 `channels`、`channelConfigs`、`tools` 和诊断信息。
|
||||
- 安装或移除插件包后，运行 `openclaw plugins registry --refresh`，
|
||||
使持久化元数据反映当前安装。
|
||||
- 在安装、注册表或配置变更后重启 Gateway 网关。
|
||||
让持久化元数据反映当前安装。
|
||||
- 在安装、registry 或配置变更后重启 Gateway 网关。
|
||||
|
||||
修复选项：
|
||||
|
||||
- 如果某个插件有意替换另一个相同渠道 id 的插件，
|
||||
首选插件应声明 `channelConfigs.<channel-id>.preferOver`，并指定
|
||||
较低优先级的插件 id。参见 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。
|
||||
- 如果某个插件有意替换同一渠道 ID 的另一个插件，
|
||||
首选插件应声明 `channelConfigs.<channel-id>.preferOver`，并填入
|
||||
优先级较低的插件 ID。参见 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。
|
||||
- 如果重复是意外造成的，请使用
|
||||
`plugins.entries.<plugin-id>.enabled: false` 禁用其中一方，或移除过时的插件
|
||||
`plugins.entries.<plugin-id>.enabled: false` 禁用一侧，或移除过时的插件
|
||||
安装。
|
||||
- 如果你显式启用了两个插件，OpenClaw 会保留该请求并
|
||||
报告冲突。请为该渠道选择一个所有者，或重命名插件拥有的
|
||||
工具，使运行时表面保持明确。
|
||||
工具，使运行时表面明确无歧义。
|
||||
|
||||
## 插件槽位（独占类别）
|
||||
|
||||
某些类别是独占的（同一时间只能有一个处于活动状态）：
|
||||
某些类别是独占的（一次只能有一个处于活动状态）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -359,7 +363,7 @@ openclaw plugins inspect <plugin-id> --runtime --json
|
||||
| 槽位 | 控制内容 | 默认值 |
|
||||
| --------------- | --------------------- | ------------------- |
|
||||
| `memory` | 主动记忆插件 | `memory-core` |
|
||||
| `contextEngine` | 活动上下文引擎 | `legacy`（内置） |
|
||||
| `contextEngine` | 活动上下文引擎 | `legacy`（内置） |
|
||||
|
||||
## CLI 参考
|
||||
|
||||
@ -408,66 +412,57 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
内置插件随 OpenClaw 一起发布。许多插件默认启用（例如
|
||||
内置插件随 OpenClaw 一起发布。许多默认启用（例如
|
||||
内置模型提供商、内置语音提供商和内置浏览器
|
||||
插件）。其他内置插件仍需要 `openclaw plugins enable <id>`。
|
||||
|
||||
`--force` 会就地覆盖现有已安装插件或钩子包。对于已跟踪 npm
|
||||
`--force` 会原地覆盖现有已安装插件或钩子包。对于已跟踪 npm
|
||||
插件的常规升级，请使用
|
||||
`openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为后者会复用源路径，而不是
|
||||
复制到受管理的安装目标上。
|
||||
`openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，
|
||||
因为 `--link` 会复用源路径，而不是复制到受管理的安装目标上。
|
||||
|
||||
当 `plugins.allow` 已经设置时，`openclaw plugins install` 会在启用插件前
|
||||
将已安装插件 id 添加到该 allowlist。如果同一插件 id
|
||||
出现在 `plugins.deny` 中，安装会移除该过时 deny 条目，使显式安装
|
||||
在重启后立即可加载。
|
||||
当 `plugins.allow` 已设置时，`openclaw plugins install` 会在启用已安装插件之前，
|
||||
将已安装插件 ID 添加到该 allowlist。如果同一插件 ID
|
||||
存在于 `plugins.deny` 中，安装会移除该过时 deny 条目，
|
||||
以便显式安装在重启后立即可加载。
|
||||
|
||||
OpenClaw 保留一个持久化的本地插件注册表，作为插件库存、
|
||||
OpenClaw 保留一个持久化的本地插件 registry，作为插件清单、
|
||||
贡献所有权和启动规划的冷读取模型。安装、更新、
|
||||
卸载、启用和禁用流程会在更改插件状态后刷新该注册表。
|
||||
同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据，
|
||||
并在 `plugins` 中保存可重建的清单元数据。如果注册表缺失、过时或无效，
|
||||
卸载、启用和禁用流程会在改变插件状态后刷新该 registry。
|
||||
同一个 `plugins/installs.json` 文件会在顶层
|
||||
`installRecords` 中保留持久安装元数据，并在 `plugins` 中保留
|
||||
可重建的 manifest 元数据。如果 registry 缺失、过时或无效，
|
||||
`openclaw plugins registry
|
||||
--refresh` 会基于安装记录、配置策略以及
|
||||
清单/包元数据重建其清单视图，而无需加载插件运行时模块。
|
||||
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪安装。传入
|
||||
带 dist-tag 或确切版本的 npm 包 spec 时，会将包名解析回
|
||||
已跟踪插件记录，并记录新的 spec 供未来更新使用。
|
||||
传入不带版本的包名，会将精确固定的安装移回
|
||||
注册表的默认发布线。如果已安装的 npm 插件已经匹配
|
||||
解析后的版本和记录的工件身份，OpenClaw 会跳过更新，
|
||||
--refresh` 会从安装记录、配置策略以及
|
||||
manifest/package 元数据重建其 manifest 视图，而不会加载插件运行时模块。
|
||||
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪安装。传入带有
|
||||
dist-tag 或精确版本的 npm 包 spec 时，会将包名解析回
|
||||
已跟踪插件记录，并记录新的 spec 以供未来更新使用。
|
||||
传入不带版本的包名时，会将精确 pin 的安装移回
|
||||
registry 的默认发布线。如果已安装的 npm 插件已经匹配
|
||||
解析后的版本和记录的 artifact 身份，OpenClaw 会跳过更新，
|
||||
不会下载、重新安装或重写配置。
|
||||
|
||||
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为
|
||||
marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
|
||||
|
||||
`--dangerously-force-unsafe-install` 是内置危险代码扫描器误报时的应急覆盖。
|
||||
它允许插件安装
|
||||
和插件更新在内置 `critical` 发现之后继续，但仍然
|
||||
不会绕过插件 `before_install` 策略阻止或扫描失败阻止。
|
||||
安装扫描会忽略常见测试文件和目录，例如 `tests/`、
|
||||
`__tests__/`、`*.test.*` 和 `*.spec.*`，以避免阻止打包的测试 mock；
|
||||
声明的插件运行时入口点仍会被扫描，即使它们使用了这些
|
||||
名称之一。
|
||||
`--dangerously-force-unsafe-install` 是用于处理内置危险代码扫描器误报的紧急越权开关。它允许插件安装和插件更新在内置 `critical` 发现项之后继续执行，但仍不会绕过插件 `before_install` 策略阻断或扫描失败阻断。安装扫描会忽略常见测试文件和目录，例如 `tests/`、`__tests__/`、`*.test.*` 和 `*.spec.*`，以避免阻断已打包的测试 mock；声明的插件运行时入口点即使用了这些名称之一，仍会被扫描。
|
||||
|
||||
此 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 skill
|
||||
依赖安装会改用匹配的 `dangerouslyForceUnsafeInstall` 请求
|
||||
覆盖，而 `openclaw skills install` 仍是单独的 ClawHub
|
||||
skill 下载/安装流程。
|
||||
此 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装改用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是独立的 ClawHub Skills 下载/安装流程。
|
||||
|
||||
如果你在 ClawHub 上发布的插件被扫描隐藏或拦截，请打开 ClawHub 仪表板，或运行 `clawhub package rescan <name>` 请求 ClawHub 重新检查。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被拦截的发布公开。
|
||||
如果你发布到 ClawHub 的插件因扫描被隐藏或阻断，请打开 ClawHub dashboard，或运行 `clawhub package rescan <name>` 请求 ClawHub 重新检查。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描该插件，也不会让被阻断的发布变为公开。
|
||||
|
||||
兼容包会参与同一套插件 list/inspect/enable/disable 流程。当前运行时支持包括包内 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
|
||||
兼容 bundle 会参与同一套插件列表/检查/启用/禁用流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
|
||||
|
||||
`openclaw plugins inspect <id>` 还会报告检测到的包能力，以及由兼容包提供的插件中受支持或不受支持的 MCP 和 LSP 服务器条目。
|
||||
`openclaw plugins inspect <id>` 还会报告检测到的 bundle 能力，以及由 bundle 支持的插件中受支持或不受支持的 MCP 和 LSP 服务器条目。
|
||||
|
||||
Marketplace 源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保持在克隆下来的 marketplace 仓库内部，并且只能使用相对路径源。
|
||||
Marketplace 来源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内部，并且只能使用相对路径来源。
|
||||
|
||||
了解详情，请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。
|
||||
|
||||
## 插件 API 概览
|
||||
|
||||
原生插件会导出一个入口对象，该对象暴露 `register(api)`。较旧的插件可能仍使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
|
||||
原生插件会导出一个暴露 `register(api)` 的入口对象。较旧的插件仍可使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
|
||||
|
||||
```typescript
|
||||
export default definePluginEntry({
|
||||
@ -487,60 +482,60 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
|
||||
OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为较旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
|
||||
|
||||
`api.registrationMode` 会告诉插件其入口为何被加载：
|
||||
`api.registrationMode` 会告知插件其入口被加载的原因：
|
||||
|
||||
| 模式 | 含义 |
|
||||
| 模式 | 含义 |
|
||||
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `full` | 运行时激活。注册工具、钩子、服务、命令、路由，以及其他实时副作用。 |
|
||||
| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可以加载，但应跳过实时副作用。 |
|
||||
| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 |
|
||||
| `setup-runtime` | 还需要运行时入口的渠道设置加载。 |
|
||||
| `cli-metadata` | 仅收集 CLI 命令元数据。 |
|
||||
| `full` | 运行时激活。注册工具、钩子、服务、命令、路由和其他实时副作用。 |
|
||||
| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可以加载，但应跳过实时副作用。 |
|
||||
| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 |
|
||||
| `setup-runtime` | 还需要运行时入口的渠道设置加载。 |
|
||||
| `cli-metadata` | 仅收集 CLI 命令元数据。 |
|
||||
|
||||
会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活式的，但不是免导入的：OpenClaw 可能会求值可信插件入口或渠道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。
|
||||
会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活式的，但不是免 import 的：OpenClaw 可能会执行可信插件入口或渠道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。
|
||||
|
||||
常见注册方法：
|
||||
|
||||
| 方法 | 注册内容 |
|
||||
| 方法 | 注册内容 |
|
||||
| --------------------------------------- | --------------------------- |
|
||||
| `registerProvider` | 模型提供商（LLM） |
|
||||
| `registerChannel` | 聊天渠道 |
|
||||
| `registerTool` | 智能体工具 |
|
||||
| `registerHook` / `on(...)` | 生命周期钩子 |
|
||||
| `registerSpeechProvider` | 文本转语音 / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | 流式 STT |
|
||||
| `registerRealtimeVoiceProvider` | 双工实时语音 |
|
||||
| `registerMediaUnderstandingProvider` | 图像/音频分析 |
|
||||
| `registerImageGenerationProvider` | 图像生成 |
|
||||
| `registerMusicGenerationProvider` | 音乐生成 |
|
||||
| `registerVideoGenerationProvider` | 视频生成 |
|
||||
| `registerWebFetchProvider` | Web 获取 / 抓取提供商 |
|
||||
| `registerWebSearchProvider` | Web 搜索 |
|
||||
| `registerHttpRoute` | HTTP 端点 |
|
||||
| `registerCommand` / `registerCli` | CLI 命令 |
|
||||
| `registerContextEngine` | 上下文引擎 |
|
||||
| `registerService` | 后台服务 |
|
||||
| `registerProvider` | 模型提供商（LLM） |
|
||||
| `registerChannel` | 聊天渠道 |
|
||||
| `registerTool` | 智能体工具 |
|
||||
| `registerHook` / `on(...)` | 生命周期钩子 |
|
||||
| `registerSpeechProvider` | 文本转语音 / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | 流式 STT |
|
||||
| `registerRealtimeVoiceProvider` | 双工实时语音 |
|
||||
| `registerMediaUnderstandingProvider` | 图像/音频分析 |
|
||||
| `registerImageGenerationProvider` | 图像生成 |
|
||||
| `registerMusicGenerationProvider` | 音乐生成 |
|
||||
| `registerVideoGenerationProvider` | 视频生成 |
|
||||
| `registerWebFetchProvider` | Web 获取 / 抓取提供商 |
|
||||
| `registerWebSearchProvider` | Web 搜索 |
|
||||
| `registerHttpRoute` | HTTP 端点 |
|
||||
| `registerCommand` / `registerCli` | CLI 命令 |
|
||||
| `registerContextEngine` | 上下文引擎 |
|
||||
| `registerService` | 后台服务 |
|
||||
|
||||
类型化生命周期钩子的钩子保护行为：
|
||||
类型化生命周期钩子的守卫行为：
|
||||
|
||||
- `before_tool_call`：`{ block: true }` 是终止性的；较低优先级的处理程序会被跳过。
|
||||
- `before_tool_call`：`{ block: false }` 是无操作，不会清除更早的拦截。
|
||||
- `before_install`：`{ block: true }` 是终止性的；较低优先级的处理程序会被跳过。
|
||||
- `before_install`：`{ block: false }` 是无操作，不会清除更早的拦截。
|
||||
- `message_sending`：`{ cancel: true }` 是终止性的；较低优先级的处理程序会被跳过。
|
||||
- `message_sending`：`{ cancel: false }` 是无操作，不会清除更早的取消。
|
||||
- `before_tool_call`：`{ block: true }` 是终止性的；低优先级处理程序会被跳过。
|
||||
- `before_tool_call`：`{ block: false }` 是空操作，不会清除之前的阻断。
|
||||
- `before_install`：`{ block: true }` 是终止性的；低优先级处理程序会被跳过。
|
||||
- `before_install`：`{ block: false }` 是空操作，不会清除之前的阻断。
|
||||
- `message_sending`：`{ cancel: true }` 是终止性的；低优先级处理程序会被跳过。
|
||||
- `message_sending`：`{ cancel: false }` 是空操作，不会清除之前的取消。
|
||||
|
||||
原生 Codex 应用服务器会将 Codex 原生工具事件桥接回这个钩子表面。插件可以通过 `before_tool_call` 拦截原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该桥接目前还不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界位于 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。
|
||||
原生 Codex app-server 会把 Codex 原生工具事件桥接回这个钩子表面。插件可以通过 `before_tool_call` 阻断原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该桥接尚不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界见 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。
|
||||
|
||||
有关完整的类型化钩子行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
|
||||
完整的类型化钩子行为见 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件
|
||||
- [插件包](/zh-CN/plugins/bundles) — Codex/Claude/Cursor 兼容包
|
||||
- [插件清单](/zh-CN/plugins/manifest) — 清单架构
|
||||
- [插件 bundle](/zh-CN/plugins/bundles) — Codex/Claude/Cursor bundle 兼容性
|
||||
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema
|
||||
- [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
|
||||
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载管线
|
||||
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线
|
||||
- [社区插件](/zh-CN/plugins/community) — 第三方列表
|
||||
|
||||
Loading…
Reference in New Issue
Block a user