chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
b15e26f368
commit
aead5dd55d
@ -2,20 +2,20 @@
|
||||
read_when:
|
||||
- 安装或配置插件
|
||||
- 了解插件发现和加载规则
|
||||
- 使用与 Codex/Claude 兼容的插件捆绑包
|
||||
- 使用与 Codex/Claude 兼容的插件包
|
||||
sidebarTitle: Install and Configure
|
||||
summary: 安装、配置和管理 OpenClaw 插件
|
||||
title: 插件
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T11:23:13Z"
|
||||
generated_at: "2026-05-02T13:23:27Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 97ec11a601445fa948d5639a6d461bcf3846a3c70d3eb304a66243a3d8ce810a
|
||||
source_hash: 6aa1819e086c66fd9cb035d17f0dea0ddc7fcd0c0d5490fac09c843fb1d74a39
|
||||
source_path: tools/plugin.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
插件通过新增能力扩展 OpenClaw：渠道、模型提供商、Agent harnesses、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、Web 抓取、Web 搜索等。一些插件是**核心**插件（随 OpenClaw 一起提供），另一些是**外部**插件。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。npm 仍然支持直接安装，也会在迁移完成前临时用于一组 OpenClaw 自有插件包。
|
||||
插件为 OpenClaw 扩展新能力：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、Web 获取、Web 搜索等。有些插件是 **核心** 插件（随 OpenClaw 一起发布），其他是 **外部** 插件。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。npm 仍支持直接安装，也支持一组临时的 OpenClaw 自有插件包，直到该迁移完成。
|
||||
|
||||
## 快速开始
|
||||
|
||||
@ -56,6 +56,14 @@ x-i18n:
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="聊天原生管理">
|
||||
在正在运行的 Gateway 网关中，仅限所有者使用的 `/plugins enable` 和 `/plugins disable`
|
||||
会触发 Gateway 网关配置重载器。Gateway 网关会在进程内重载插件运行时
|
||||
表面，新的智能体轮次会从刷新后的注册表重新构建它们的工具列表。`/plugins install` 会更改插件源代码，因此
|
||||
Gateway 网关会请求重启，而不是假装当前进程可以安全地重载已经导入的模块。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="验证插件">
|
||||
```bash
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
@ -64,12 +72,13 @@ x-i18n:
|
||||
openclaw <plugin-command> --help
|
||||
```
|
||||
|
||||
当你需要证明已注册的工具、服务、gateway 方法、钩子或插件自有 CLI 命令时，请使用 `--runtime`。普通 `inspect` 是冷态的清单/注册表检查，会有意避免导入插件运行时。
|
||||
当你需要证明已注册的工具、服务、gateway 方法、钩子或插件自有 CLI 命令时，使用 `--runtime`。普通的 `inspect` 是一次冷态
|
||||
清单/注册表检查，并且有意避免导入插件运行时。
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
如果你偏好聊天原生控制，请启用 `commands.plugins: true` 并使用：
|
||||
如果你更喜欢聊天原生控制，请启用 `commands.plugins: true` 并使用：
|
||||
|
||||
```text
|
||||
/plugin install clawhub:<package>
|
||||
@ -77,13 +86,40 @@ 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 的托管插件根目录下。npm 依赖可能会在 OpenClaw 托管的 npm 根目录内提升；安装/更新会先扫描该托管根目录再进行信任判断，卸载则会通过 npm 移除 npm 管理的包。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。请参阅[插件依赖解析](/zh-CN/plugins/dependency-resolution)了解安装时生命周期。
|
||||
插件依赖安装只会在显式安装/更新或
|
||||
doctor 修复流程中发生。Gateway 网关启动、配置重载和运行时检查
|
||||
不会运行包管理器或修复依赖树。本地插件必须已经
|
||||
安装了依赖，而 npm、git 和 ClawHub 插件会安装到 OpenClaw 的托管插件根目录下。npm 依赖可能会在 OpenClaw 的托管 npm 根目录内提升；安装/更新会先扫描该托管根目录，然后再信任；卸载会通过 npm 移除 npm 托管的包。外部插件
|
||||
和自定义加载路径仍必须通过 `openclaw plugins install` 安装。
|
||||
查看 [插件依赖解析](/zh-CN/plugins/dependency-resolution) 了解
|
||||
安装时生命周期。
|
||||
|
||||
源码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置插件，请运行 `pnpm install`；OpenClaw 随后会从 `extensions/<id>` 加载内置插件，因此编辑内容和包本地依赖会被直接使用。普通 npm 根目录安装用于打包版 OpenClaw，而不是源码检出开发。
|
||||
源码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置
|
||||
插件，请运行 `pnpm install`；随后 OpenClaw 会从
|
||||
`extensions/<id>` 加载内置插件，因此编辑内容和包本地依赖会被直接使用。
|
||||
普通 npm 根安装用于打包版 OpenClaw，不用于源码检出
|
||||
开发。
|
||||
|
||||
## 插件类型
|
||||
|
||||
@ -91,18 +127,27 @@ OpenClaw 识别两种插件格式：
|
||||
|
||||
| 格式 | 工作方式 | 示例 |
|
||||
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
|
||||
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
|
||||
| **Bundle** | Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
|
||||
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
|
||||
| **Bundle** | Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
|
||||
|
||||
两者都会显示在 `openclaw plugins list` 下。请参阅[插件 Bundle](/zh-CN/plugins/bundles)了解 Bundle 详情。
|
||||
两者都会显示在 `openclaw plugins list` 下。查看 [插件 Bundle](/zh-CN/plugins/bundles) 了解 bundle 详情。
|
||||
|
||||
如果你正在编写原生插件，请从[构建插件](/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`，请为其构建后的 JavaScript 对等文件使用 `openclaw.runtimeSetupEntry`；声明该文件时它是必需的。
|
||||
当发布的运行时文件不在与源条目相同的路径时，使用 `openclaw.runtimeExtensions`。
|
||||
存在时，`runtimeExtensions` 必须为每个 `extensions` 条目包含
|
||||
正好一个条目。列表不匹配会导致安装和
|
||||
插件发现失败，而不是静默回退到源路径。如果你还
|
||||
发布 `openclaw.setupEntry`，请为其内置
|
||||
JavaScript 对等文件使用 `openclaw.runtimeSetupEntry`；声明后该文件是必需的。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -116,11 +161,17 @@ OpenClaw 识别两种插件格式：
|
||||
|
||||
## 官方插件
|
||||
|
||||
### 迁移期间 OpenClaw 自有的 npm 包
|
||||
### 迁移期间的 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 包。
|
||||
|
||||
| 插件 | 包 | 文档 |
|
||||
| --------------- | -------------------------- | ------------------------------------------ |
|
||||
@ -138,7 +189,7 @@ ClawHub 是大多数插件的主要分发路径。当前打包版 OpenClaw 版
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |
|
||||
|
||||
### 核心（随 OpenClaw 一起提供）
|
||||
### 核心（随 OpenClaw 一起发布）
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="模型提供商（默认启用）">
|
||||
@ -150,10 +201,11 @@ ClawHub 是大多数插件的主要分发路径。当前打包版 OpenClaw 版
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="记忆插件">
|
||||
- `memory-core` — 内置记忆搜索（默认通过 `plugins.slots.memory` 使用）
|
||||
- `memory-lancedb` — 基于 LanceDB 的长期记忆，支持自动回忆/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
|
||||
- `memory-core` — 内置记忆搜索（默认通过 `plugins.slots.memory`）
|
||||
- `memory-lancedb` — 由 LanceDB 支持、具备自动召回/捕获能力的长期记忆（设置 `plugins.slots.memory = "memory-lancedb"`）
|
||||
|
||||
请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)，了解 OpenAI 兼容的 embedding 设置、Ollama 示例、回忆限制和故障排除。
|
||||
查看 [Memory LanceDB](/zh-CN/plugins/memory-lancedb) 了解 OpenAI 兼容的
|
||||
嵌入设置、Ollama 示例、召回限制和故障排除。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -162,13 +214,13 @@ ClawHub 是大多数插件的主要分发路径。当前打包版 OpenClaw 版
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="其他">
|
||||
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` gateway 方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用它）
|
||||
- `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` gateway 方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；在替换它之前请先禁用）
|
||||
- `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用）
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
在找第三方插件？请参阅[社区插件](/zh-CN/plugins/community)。
|
||||
在寻找第三方插件？查看 [社区插件](/zh-CN/plugins/community)。
|
||||
|
||||
## 配置
|
||||
|
||||
@ -192,71 +244,79 @@ ClawHub 是大多数插件的主要分发路径。当前打包版 OpenClaw 版
|
||||
| `allow` | 插件允许列表（可选） |
|
||||
| `deny` | 插件拒绝列表（可选；拒绝优先） |
|
||||
| `load.paths` | 额外插件文件/目录 |
|
||||
| `slots` | 独占 slot 选择器（例如 `memory`、`contextEngine`） |
|
||||
| `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(...)` 钩子、工具、服务或提供商/运行时钩子运行之前，请重启正在服务实时渠道的 Gateway 网关进程。
|
||||
通过 `/plugins enable` 或 `/plugins disable` 进行的配置更改会触发进程内 Gateway 网关插件重新加载。新的智能体轮次会从刷新的插件注册表重建其工具列表。安装、更新和卸载等会更改源码的操作仍会重启 Gateway 网关进程，因为已经导入的插件模块无法安全地就地替换。
|
||||
|
||||
`openclaw plugins list` 是本地插件注册表/配置快照。其中的 `enabled` 插件表示持久化注册表和当前配置允许该插件参与运行。它不能证明已经在运行的远程 Gateway 网关子进程已重启并加载了同一份插件代码。在带有包装进程的 VPS/容器设置中，请将重启信号发送给实际的 `openclaw gateway run` 进程，或者对正在运行的 Gateway 网关使用 `openclaw gateway restart`。
|
||||
`openclaw plugins list` 是本地插件注册表/配置快照。其中显示为 `enabled` 的插件表示持久化注册表和当前配置允许该插件参与运行。它不能证明已经运行的远程 Gateway 网关已经重新加载或重启到相同的插件代码。在带有包装进程的 VPS/容器设置中，请将重启或触发重新加载的写入发送到实际的 `openclaw gateway run` 进程，或者在重新加载报告失败时，对正在运行的 Gateway 网关使用 `openclaw gateway restart`。
|
||||
|
||||
<Accordion title="插件状态：已禁用 vs 缺失 vs 无效">
|
||||
<Accordion title="Plugin states: disabled vs missing vs invalid">
|
||||
- **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。
|
||||
- **缺失**：配置引用了设备发现未找到的插件 ID。
|
||||
- **无效**：插件存在，但其配置与声明的架构不匹配。Gateway 网关启动时只会跳过该插件；`openclaw doctor --fix` 可以通过禁用它并移除其配置载荷来隔离无效条目。
|
||||
- **无效**：插件存在，但其配置与声明的架构不匹配。Gateway 网关启动时只会跳过该插件；`openclaw doctor --fix` 可以通过禁用无效条目并移除其配置负载来隔离该条目。
|
||||
|
||||
</Accordion>
|
||||
|
||||
## 设备发现和优先级
|
||||
|
||||
OpenClaw 按以下顺序扫描插件（第一个匹配项胜出）：
|
||||
OpenClaw 按以下顺序扫描插件（先匹配者优先）：
|
||||
|
||||
<Steps>
|
||||
<Step title="配置路径">
|
||||
`plugins.load.paths` — 显式文件或目录路径。指回 OpenClaw 自身打包内置插件目录的路径会被忽略；运行 `openclaw doctor --fix` 可移除这些过时别名。
|
||||
<Step title="Config paths">
|
||||
`plugins.load.paths` — 显式文件或目录路径。指回 OpenClaw 自己打包的内置插件目录的路径会被忽略；
|
||||
运行 `openclaw doctor --fix` 可移除这些过时别名。
|
||||
</Step>
|
||||
|
||||
<Step title="工作区插件">
|
||||
<Step title="Workspace plugins">
|
||||
`\<workspace\>/.openclaw/<plugin-root>/*.ts` 和 `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`。
|
||||
</Step>
|
||||
|
||||
<Step title="全局插件">
|
||||
<Step title="Global plugins">
|
||||
`~/.openclaw/<plugin-root>/*.ts` 和 `~/.openclaw/<plugin-root>/*/index.ts`。
|
||||
</Step>
|
||||
|
||||
<Step title="内置插件">
|
||||
随 OpenClaw 一起发布。许多插件默认启用（模型提供商、语音）。其他插件需要显式启用。
|
||||
<Step title="Bundled plugins">
|
||||
随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。其他插件需要显式启用。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
打包安装和 Docker 镜像通常从编译后的 `dist/extensions` 树解析内置插件。如果一个内置插件源目录以绑定挂载覆盖匹配的打包源路径，例如 `/app/extensions/synology-chat`，OpenClaw 会将该挂载的源目录视为内置源码覆盖层，并在打包的 `/app/dist/extensions/synology-chat` bundle 之前发现它。这样可以让维护者容器循环继续工作，而不必把每个内置插件切回 TypeScript 源码。设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist bundle，即使存在源码覆盖层挂载也是如此。
|
||||
打包安装和 Docker 镜像通常会从已编译的 `dist/extensions` 树解析内置插件。如果某个内置插件源码目录被绑定挂载到匹配的打包源码路径上，例如 `/app/extensions/synology-chat`，OpenClaw 会将该挂载的源码目录视为内置源码覆盖层，并在打包的 `/app/dist/extensions/synology-chat` bundle 之前发现它。这样可以让维护者容器循环正常工作，而无需将每个内置插件都切回 TypeScript 源码。设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist bundle，即使存在源码覆盖挂载也是如此。
|
||||
|
||||
### 启用规则
|
||||
|
||||
- `plugins.enabled: false` 会禁用所有插件，并跳过插件设备发现/加载工作
|
||||
- `plugins.deny` 的优先级始终高于 allow
|
||||
- `plugins.enabled: false` 会禁用所有插件并跳过插件发现/加载工作
|
||||
- `plugins.deny` 始终优先于 allow
|
||||
- `plugins.entries.\<id\>.enabled: false` 会禁用该插件
|
||||
- 工作区来源的插件**默认禁用**（必须显式启用）
|
||||
- 内置插件遵循内建的默认启用集合，除非被覆盖
|
||||
- 独占 slot 可以强制启用为该 slot 选择的插件
|
||||
- 某些需要选择启用的内置插件会在配置命名插件拥有的表面时自动启用，例如提供商模型引用、渠道配置或 harness 运行时
|
||||
- 当 `plugins.enabled: false` 处于活动状态时，过时的插件配置会被保留；如果你想移除过时 ID，请先重新启用插件，再运行 Doctor 清理
|
||||
- OpenAI 系列 Codex 路由会保持独立的插件边界：`openai-codex/*` 属于 OpenAI 插件，而内置的 Codex 应用服务器插件由 `agentRuntime.id: "codex"` 或旧版 `codex/*` 模型引用选择
|
||||
- 内置插件遵循内建的默认开启集合，除非被覆盖
|
||||
- 独占槽位可以强制启用该槽位选中的插件
|
||||
- 当配置命名某个插件拥有的表面（例如提供商模型引用、渠道配置或 harness 运行时）时，一些内置的可选启用插件会自动启用
|
||||
- 当 `plugins.enabled: false` 处于活动状态时，过时插件配置会被保留；如果你希望移除过时 ID，请在运行 Doctor 清理之前重新启用插件
|
||||
- OpenAI 系列 Codex 路由保持独立的插件边界：
|
||||
`openai-codex/*` 属于 OpenAI 插件，而内置 Codex
|
||||
app-server 插件由 `agentRuntime.id: "codex"` 或旧版
|
||||
`codex/*` 模型引用选择
|
||||
|
||||
## 排查运行时钩子
|
||||
## 运行时钩子的故障排除
|
||||
|
||||
如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子没有在实时聊天流量中运行，请先检查以下事项：
|
||||
如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子没有在实时聊天流量中运行，请先检查以下内容：
|
||||
|
||||
- 运行 `openclaw gateway status --deep --require-rpc`，并确认活跃的 Gateway 网关 URL、profile、配置路径和进程就是你正在编辑的对象。
|
||||
- 在插件安装/配置/代码变更后重启实时 Gateway 网关。在包装容器中，PID 1 可能只是一个 supervisor；请重启或向子 `openclaw gateway run` 进程发送信号。
|
||||
- 使用 `openclaw plugins inspect <id> --runtime --json` 确认钩子注册和诊断。非内置对话钩子（例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
|
||||
- 运行 `openclaw gateway status --deep --require-rpc`，并确认活动的 Gateway 网关 URL、profile、配置路径和进程正是你正在编辑的对象。
|
||||
- 在插件安装/配置/代码更改后重启实时 Gateway 网关。在包装容器中，PID 1 可能只是 supervisor；请重启子 `openclaw gateway run` 进程或向其发送信号。
|
||||
- 使用 `openclaw plugins inspect <id> --runtime --json` 确认钩子注册和诊断信息。非内置会话钩子（如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
|
||||
- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 只会在一次模型尝试产生助手输出之后运行。
|
||||
- 要证明有效会话模型，请使用 `openclaw sessions` 或 Gateway 网关会话/Status 表面；调试提供商载荷时，请使用 `--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
|
||||
- 若要证明有效会话模型，请使用 `openclaw sessions` 或 Gateway 网关会话/Status 表面；调试提供商负载时，请用 `--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
|
||||
|
||||
### 插件工具设置缓慢
|
||||
|
||||
如果智能体轮次在准备工具时似乎停滞，请启用 trace 日志并检查插件工具工厂计时行：
|
||||
如果智能体轮次似乎在准备工具时停滞，请启用 trace 日志并检查插件工具 factory 的计时行：
|
||||
|
||||
```bash
|
||||
openclaw config set logging.level trace
|
||||
@ -269,9 +329,9 @@ openclaw logs --follow
|
||||
[trace:plugin-tools] factory timings ...
|
||||
```
|
||||
|
||||
摘要会列出总工厂时间和最慢的插件工具工厂，包括插件 ID、声明的工具名称、结果形状，以及该工具是否为可选工具。当单个工厂耗时至少 1 秒，或插件工具工厂准备总耗时至少 5 秒时，慢速行会提升为警告。
|
||||
摘要会列出总 factory 时间和最慢的插件工具 factory，包括插件 ID、声明的工具名称、结果形状以及该工具是否为可选。当单个 factory 至少耗时 1 秒或插件工具 factory 准备总耗时至少 5 秒时，慢速行会提升为警告。
|
||||
|
||||
OpenClaw 会为使用相同有效请求上下文的重复解析缓存成功的插件工具工厂结果。缓存键包含有效运行时配置、工作区、智能体/会话 ID、沙箱策略、浏览器设置、交付上下文、请求者身份和所有权状态，因此依赖这些可信字段的工厂会在上下文变化时重新运行。
|
||||
OpenClaw 会缓存成功的插件工具 factory 结果，以便在相同有效请求上下文的重复解析中复用。缓存键包含有效运行时配置、工作区、智能体/会话 ID、沙箱策略、浏览器设置、交付上下文、请求者身份和所有权状态，因此依赖这些可信字段的 factory 会在上下文变化时重新运行。
|
||||
|
||||
如果某个插件占用了主要耗时，请检查其运行时注册：
|
||||
|
||||
@ -279,7 +339,7 @@ OpenClaw 会为使用相同有效请求上下文的重复解析缓存成功的
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
```
|
||||
|
||||
然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移到工具执行路径之后，而不是在工具工厂内部执行。
|
||||
然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移到工具执行路径之后，而不是在工具 factory 中完成。
|
||||
|
||||
### 重复的渠道或工具所有权
|
||||
|
||||
@ -289,24 +349,24 @@ 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 registry --refresh`，使持久化元数据反映当前安装。
|
||||
- 在安装、注册表或配置变更后重启 Gateway 网关。
|
||||
- 对每个可疑插件运行 `openclaw plugins inspect <id> --runtime --json`，并比较 `channels`、`channelConfigs`、`tools` 和诊断信息。
|
||||
- 在安装或移除插件包后运行 `openclaw plugins registry --refresh`，以便持久化元数据反映当前安装。
|
||||
- 在安装、注册表或配置更改后重启 Gateway 网关。
|
||||
|
||||
修复选项：
|
||||
|
||||
- 如果一个插件有意替换另一个具有相同渠道 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` 禁用其中一方，或移除过时的插件安装。
|
||||
- 如果你显式启用了两个插件，OpenClaw 会保留该请求并报告冲突。请为该渠道选择一个所有者，或重命名插件拥有的工具，使运行时表面没有歧义。
|
||||
- 如果一个插件有意替换同一渠道 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` 禁用其中一方，或移除过时的插件安装。
|
||||
- 如果你显式启用了两个插件，OpenClaw 会保留该请求并报告冲突。请为该渠道选择一个所有者，或重命名插件拥有的工具，使运行时表面明确无歧义。
|
||||
|
||||
## 插件 slot（独占类别）
|
||||
## 插件槽位（独占类别）
|
||||
|
||||
某些类别是独占的（同一时间只能有一个处于活跃状态）：
|
||||
某些类别是独占的（同一时间只能有一个活动项）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -319,10 +379,10 @@ openclaw plugins inspect <plugin-id> --runtime --json
|
||||
}
|
||||
```
|
||||
|
||||
| Slot | 控制内容 | 默认值 |
|
||||
| --------------- | -------------- | ------------------ |
|
||||
| `memory` | 主动记忆插件 | `memory-core` |
|
||||
| `contextEngine` | 活跃上下文引擎 | `legacy`（内建） |
|
||||
| 槽位 | 控制内容 | 默认值 |
|
||||
| --------------- | --------------------- | ------------------- |
|
||||
| `memory` | 主动记忆插件 | `memory-core` |
|
||||
| `contextEngine` | 活动上下文引擎 | `legacy`（内置） |
|
||||
|
||||
## CLI 参考
|
||||
|
||||
@ -372,34 +432,34 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
内置插件随 OpenClaw 一起发布。许多插件默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）。其他内置插件仍然需要 `openclaw plugins enable <id>`。
|
||||
内置插件随 OpenClaw 一起发布。许多默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）。其他内置插件仍需要 `openclaw plugins enable <id>`。
|
||||
|
||||
`--force` 会就地覆盖现有已安装插件或钩子包。对于已跟踪 npm 插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到托管安装目标之上。
|
||||
`--force` 会就地覆盖现有已安装插件或钩子包。对于已跟踪 npm 插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。它不支持与 `--link` 一起使用，因为 `--link` 会复用源码路径，而不是复制到托管安装目标上。
|
||||
|
||||
当 `plugins.allow` 已设置时，`openclaw plugins install` 会先将已安装插件 ID 添加到该允许列表，然后再启用它。如果同一个插件 ID 存在于 `plugins.deny` 中，安装会移除该过时的 deny 条目，使显式安装在重启后立即可加载。
|
||||
当已经设置 `plugins.allow` 时，`openclaw plugins install` 会先将已安装插件 ID 添加到该允许列表，然后再启用它。如果同一个插件 ID 存在于 `plugins.deny` 中，安装会移除该过时的 deny 条目，使显式安装在重启后立即可加载。
|
||||
|
||||
OpenClaw 会保留一个持久化的本地插件注册表，作为插件清单、贡献归属和启动规划的冷读取模型。安装、更新、卸载、启用和禁用流程会在更改插件状态后刷新该注册表。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的 manifest 元数据。如果注册表缺失、过期或无效，`openclaw plugins registry --refresh` 会根据安装记录、配置策略以及 manifest/package 元数据重建其 manifest 视图，而不会加载插件运行时模块。
|
||||
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带有 dist-tag 或精确版本的 npm package spec 时，会将包名解析回已跟踪的插件记录，并记录新的 spec 以供后续更新使用。传入不带版本的包名时，会将精确固定的安装切回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析出的版本和记录的构件身份，OpenClaw 会跳过更新，不下载、不重新安装，也不重写配置。
|
||||
OpenClaw 会将本地插件注册表持久化，作为插件清单、贡献归属和启动规划的冷读取模型。安装、更新、卸载、启用和停用流程会在更改插件状态后刷新该注册表。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的清单元数据。如果注册表缺失、过期或无效，`openclaw plugins registry --refresh` 会从安装记录、配置策略以及清单/包元数据重建其清单视图，而不加载插件运行时模块。
|
||||
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包规格时，会将包名解析回已跟踪的插件记录，并记录新的规格供未来更新使用。传入不带版本的包名会将精确固定的安装移回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析到的版本和记录的制品身份，OpenClaw 会跳过更新，不下载、不重新安装，也不重写配置。
|
||||
|
||||
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
|
||||
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm 规格。
|
||||
|
||||
`--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 skill 下载/安装流程。
|
||||
|
||||
如果你发布到 ClawHub 的插件被扫描隐藏或阻止，请打开 ClawHub dashboard，或运行 `clawhub package rescan <name>` 请求 ClawHub 再次检查它。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被阻止的发布公开。
|
||||
如果你发布到 ClawHub 的插件被扫描隐藏或阻止，请打开 ClawHub 仪表板，或运行 `clawhub package rescan <name>` 请求 ClawHub 再次检查。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被阻止的发布公开。
|
||||
|
||||
兼容 bundle 会参与同一套插件列表/检查/启用/禁用流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和 manifest 声明的 `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>` 也会报告检测到的 bundle 能力，以及 bundle 支持的插件中受支持或不受支持的 MCP 和 LSP server 条目。
|
||||
`openclaw plugins inspect <id>` 还会报告检测到的 bundle 能力，以及由 bundle 支持的插件中受支持或不受支持的 MCP 和 LSP 服务器条目。
|
||||
|
||||
Marketplace 来源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub repo URL，或 git URL。对于远程 marketplaces，插件条目必须保留在克隆的 marketplace repo 内，并且只能使用相对路径来源。
|
||||
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)。
|
||||
了解详情，请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。
|
||||
|
||||
## 插件 API 概览
|
||||
|
||||
原生插件会导出一个暴露 `register(api)` 的入口对象。较旧的插件可能仍将 `activate(api)` 用作 legacy alias，但新插件应使用 `register`。
|
||||
原生插件会导出一个暴露 `register(api)` 的入口对象。旧版插件仍可使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
|
||||
|
||||
```typescript
|
||||
export default definePluginEntry({
|
||||
@ -419,21 +479,21 @@ 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` | 渠道设置加载，同时也需要运行时入口。 |
|
||||
| `setup-runtime` | 同时需要运行时入口的渠道设置加载。 |
|
||||
| `cli-metadata` | 仅收集 CLI 命令元数据。 |
|
||||
|
||||
会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 防护这些副作用。Discovery 加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。Discovery 是非激活式的，但并非无需 import：OpenClaw 可能会求值可信插件入口或渠道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到 full-runtime 路径之后。
|
||||
会打开 socket、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 防护这些副作用。发现加载会与激活加载分开缓存，且不会替换正在运行的 Gateway 网关注册表。发现是非激活的，但并非免导入：OpenClaw 可能会执行可信插件入口或渠道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。
|
||||
|
||||
常见注册方法：
|
||||
常用注册方法：
|
||||
|
||||
| 方法 | 注册内容 |
|
||||
| --------------------------------------- | --------------------------- |
|
||||
@ -448,23 +508,23 @@ OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`
|
||||
| `registerImageGenerationProvider` | 图像生成 |
|
||||
| `registerMusicGenerationProvider` | 音乐生成 |
|
||||
| `registerVideoGenerationProvider` | 视频生成 |
|
||||
| `registerWebFetchProvider` | Web fetch / scrape 提供商 |
|
||||
| `registerWebFetchProvider` | Web 获取 / 抓取提供商 |
|
||||
| `registerWebSearchProvider` | Web 搜索 |
|
||||
| `registerHttpRoute` | HTTP endpoint |
|
||||
| `registerHttpRoute` | HTTP 端点 |
|
||||
| `registerCommand` / `registerCli` | CLI 命令 |
|
||||
| `registerContextEngine` | 上下文引擎 |
|
||||
| `registerService` | 后台服务 |
|
||||
|
||||
类型化生命周期钩子的钩子防护行为：
|
||||
类型化生命周期钩子的防护行为：
|
||||
|
||||
- `before_tool_call`: `{ block: true }` 是终止性的；较低优先级的处理器会被跳过。
|
||||
- `before_tool_call`: `{ block: false }` 是 no-op，并且不会清除先前的 block。
|
||||
- `before_install`: `{ block: true }` 是终止性的；较低优先级的处理器会被跳过。
|
||||
- `before_install`: `{ block: false }` 是 no-op，并且不会清除先前的 block。
|
||||
- `message_sending`: `{ cancel: true }` 是终止性的；较低优先级的处理器会被跳过。
|
||||
- `message_sending`: `{ cancel: false }` 是 no-op，并且不会清除先前的 cancel。
|
||||
- `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 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)。
|
||||
原生 Codex app-server 运行会将 Codex-native 工具事件桥接回此钩子表面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该桥接目前还不会重写 Codex-native 工具参数。确切的 Codex 运行时支持边界位于 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。
|
||||
|
||||
完整的类型化钩子行为请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
|
||||
|
||||
@ -472,7 +532,7 @@ OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`
|
||||
|
||||
- [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件
|
||||
- [插件 bundle](/zh-CN/plugins/bundles) — Codex/Claude/Cursor bundle 兼容性
|
||||
- [插件 manifest](/zh-CN/plugins/manifest) — manifest schema
|
||||
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema
|
||||
- [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
|
||||
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线
|
||||
- [社区插件](/zh-CN/plugins/community) — 第三方列表
|
||||
|
||||
@ -6,17 +6,17 @@ sidebarTitle: Slash commands
|
||||
summary: 斜杠命令：文本式与原生式、配置和支持的命令
|
||||
title: 斜杠命令
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T09:29:29Z"
|
||||
generated_at: "2026-05-02T13:23:22Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: b469c4436dec92eb3712f71e5f54bf2c96b9b0b17d60a1533d8669c127caefee
|
||||
source_hash: c2829a33601eb53a63b914ad1a6c3bf51be4298fe3bd34faf6475f60a2d491d2
|
||||
source_path: tools/slash-commands.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是它的别名）。
|
||||
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 作为别名）。
|
||||
|
||||
当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP 执行框架。Gateway 网关管理命令仍保持本地处理：`/acp ...` 始终会到达 OpenClaw ACP 命令处理程序，并且只要该表面启用了命令处理，`/status` 和 `/unfocus` 也会保持本地处理。
|
||||
当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍然保持本地处理：`/acp ...` 始终到达 OpenClaw ACP 命令处理器，并且只要该表面启用了命令处理，`/status` 和 `/unfocus` 就会保持本地处理。
|
||||
|
||||
有两个相关系统：
|
||||
|
||||
@ -25,18 +25,18 @@ x-i18n:
|
||||
独立的 `/...` 消息。
|
||||
</Accordion>
|
||||
<Accordion title="指令">
|
||||
`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
|
||||
`/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`。
|
||||
|
||||
- 指令会在模型看到消息之前从消息中移除。
|
||||
- 在普通聊天消息中（不是仅指令消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。
|
||||
- 在仅指令消息中（消息只包含指令），它们会持久化到会话，并回复确认。
|
||||
- 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被视为普通文本。
|
||||
- 在普通聊天消息（非仅指令）中，它们被视为“行内提示”，并且**不会**持久化会话设置。
|
||||
- 在仅指令消息（消息只包含指令）中，它们会持久化到会话，并回复确认。
|
||||
- 指令仅适用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被当作纯文本处理。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="内联快捷命令">
|
||||
仅限允许列表中/已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
<Accordion title="行内快捷命令">
|
||||
仅限允许列表中/已授权的发送者：`/help`, `/commands`, `/status`, `/whoami` (`/id`)。
|
||||
|
||||
它们会立即运行，在模型看到消息之前被移除，剩余文本会继续按正常流程处理。
|
||||
它们会立即运行，在模型看到消息之前被移除，剩余文本继续走正常流程。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -69,17 +69,17 @@ x-i18n:
|
||||
```
|
||||
|
||||
<ParamField path="commands.text" type="boolean" default="true">
|
||||
启用聊天消息中的 `/...` 解析。在没有原生命令的表面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使将此项设为 `false`，文本命令仍然可用。
|
||||
启用在聊天消息中解析 `/...`。在没有原生命令的表面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将其设为 `false`，文本命令仍然可用。
|
||||
</ParamField>
|
||||
<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
|
||||
注册原生命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对没有原生支持的提供商会忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
|
||||
注册原生命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生命令的提供商忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上之前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
|
||||
</ParamField>
|
||||
在 Discord 上，原生命令规格可以包含 `descriptionLocalizations`，OpenClaw 会将其发布为 Discord `description_localizations`，并纳入协调比较。
|
||||
在 Discord 上，原生命令规格可以包含 `descriptionLocalizations`，OpenClaw 会将其发布为 Discord `description_localizations`，并纳入对账比较。
|
||||
<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
|
||||
在支持时以原生方式注册 **skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 要求为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
|
||||
在支持时原生注册 **skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
|
||||
</ParamField>
|
||||
<ParamField path="commands.bash" type="boolean" default="false">
|
||||
启用 `! <cmd>` 来运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
|
||||
启用 `! <cmd>` 以运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
|
||||
</ParamField>
|
||||
<ParamField path="commands.bashForegroundMs" type="number" default="2000">
|
||||
控制 bash 在切换到后台模式之前等待多久（`0` 表示立即转入后台）。
|
||||
@ -91,110 +91,110 @@ x-i18n:
|
||||
启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。
|
||||
</ParamField>
|
||||
<ParamField path="commands.plugins" type="boolean" default="false">
|
||||
启用 `/plugins`（插件发现/Status，以及安装 + 启用/禁用控件）。
|
||||
启用 `/plugins`（插件发现/状态，以及安装 + 启用/禁用控制）。
|
||||
</ParamField>
|
||||
<ParamField path="commands.debug" type="boolean" default="false">
|
||||
启用 `/debug`（仅运行时覆盖）。
|
||||
</ParamField>
|
||||
<ParamField path="commands.restart" type="boolean" default="true">
|
||||
启用 `/restart` 以及 Gateway 网关重启工具操作。
|
||||
启用 `/restart` 以及 Gateway 网关重启工具动作。
|
||||
</ParamField>
|
||||
<ParamField path="commands.ownerAllowFrom" type="string[]">
|
||||
为仅所有者命令/工具表面设置显式所有者允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom` 和私信配对访问。
|
||||
为仅所有者命令/工具表面设置显式所有者允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom`，也独立于私信配对访问。
|
||||
</ParamField>
|
||||
<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
|
||||
按渠道设置：让仅所有者命令在该表面上运行时要求**所有者身份**。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上拥有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**通过验证 —— 仅所有者命令会在该渠道上默认失败。如果你希望仅所有者命令只由 `ownerAllowFrom` 和标准命令允许列表控制，请保持关闭。
|
||||
按渠道设置：让仅所有者命令在该表面运行时必须具备**所有者身份**。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或在内部消息渠道上持有内部 `operator.admin` scope。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求：仅所有者命令会在该渠道上失败关闭。如果你希望仅所有者命令只由 `ownerAllowFrom` 和标准命令允许列表控制，请保持关闭。
|
||||
</ParamField>
|
||||
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
|
||||
控制所有者 ID 在系统提示中的显示方式。
|
||||
控制所有者 ID 在系统提示中如何显示。
|
||||
</ParamField>
|
||||
<ParamField path="commands.ownerDisplaySecret" type="string">
|
||||
可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
|
||||
可选设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC secret。
|
||||
</ParamField>
|
||||
<ParamField path="commands.allowFrom" type="object">
|
||||
用于命令授权的按提供商允许列表。配置后，它就是命令和指令的唯一授权来源（会忽略渠道允许列表/配对以及 `commands.useAccessGroups`）。使用 `"*"` 表示全局默认值；提供商专用键会覆盖它。
|
||||
用于命令授权的按提供商允许列表。配置后，它是命令和指令的唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。
|
||||
</ParamField>
|
||||
<ParamField path="commands.useAccessGroups" type="boolean" default="true">
|
||||
在未设置 `commands.allowFrom` 时，为命令强制执行允许列表/策略。
|
||||
当未设置 `commands.allowFrom` 时，为命令强制执行允许列表/策略。
|
||||
</ParamField>
|
||||
|
||||
## 命令列表
|
||||
|
||||
当前权威来源：
|
||||
当前事实来源：
|
||||
|
||||
- 核心内置项来自 `src/auto-reply/commands-registry.shared.ts`
|
||||
- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts`
|
||||
- 插件命令来自插件 `registerCommand()` 调用
|
||||
- Gateway 网关上的实际可用性仍取决于配置标志、渠道表面以及已安装/已启用的插件
|
||||
- 你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道表面，以及已安装/已启用的插件
|
||||
|
||||
### 核心内置命令
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="会话和运行">
|
||||
- `/new [model]` 启动新会话；`/reset` 是重置别名。
|
||||
- Control UI 会拦截输入的 `/new`，以创建并切换到新的仪表盘会话；输入的 `/reset` 仍会运行 Gateway 网关的原地重置。
|
||||
- `/reset soft [message]` 保留当前转录内容，丢弃复用的 CLI 后端会话 ID，并在原地重新运行启动/系统提示加载。
|
||||
- `/compact [instructions]` 压缩会话上下文。参见[压缩](/zh-CN/concepts/compaction)。
|
||||
- Control UI 会拦截输入的 `/new`，创建并切换到新的仪表板会话；输入的 `/reset` 仍会运行 Gateway 网关的原地重置。
|
||||
- `/reset soft [message]` 保留当前 transcript，丢弃复用的 CLI 后端会话 ID，并在原地重新运行启动/系统提示加载。
|
||||
- `/compact [instructions]` 压缩会话上下文。参见 [压缩](/zh-CN/concepts/compaction)。
|
||||
- `/stop` 中止当前运行。
|
||||
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期时间。
|
||||
- `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。
|
||||
- `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要某个 OpenClaw 会话的提示、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。
|
||||
- `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [trajectory bundle](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示、工具和 transcript 时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="模型和运行控件">
|
||||
- `/think <level>` 设置思考级别。选项来自当前模型的提供商配置文件；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，自定义级别（如 `xhigh`、`adaptive`、`max`）或二进制 `on` 仅在受支持时可用。别名：`/thinking`、`/t`。
|
||||
<Accordion title="模型和运行控制">
|
||||
- `/think <level>` 设置思考级别。选项来自活动模型的提供商 profile；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，而 `xhigh`、`adaptive`、`max` 等自定义级别或二进制 `on` 仅在支持的地方可用。别名：`/thinking`、`/t`。
|
||||
- `/verbose on|off|full` 切换详细输出。别名：`/v`。
|
||||
- `/trace on|off` 切换当前会话的插件跟踪输出。
|
||||
- `/trace on|off` 为当前会话切换插件 trace 输出。
|
||||
- `/fast [status|on|off]` 显示或设置快速模式。
|
||||
- `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。
|
||||
- `/reasoning [on|off|stream]` 切换 reasoning 可见性。别名：`/reason`。
|
||||
- `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 显示或设置 exec 默认值。
|
||||
- `/model [name|#|status]` 显示或设置模型。
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出已配置/可用认证的提供商，或列出某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。
|
||||
- `/queue <mode>` 管理队列行为（`steer`、旧版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见[命令队列](/zh-CN/concepts/queue)和[Steering queue](/zh-CN/concepts/queue-steering)。
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出已配置/可用认证的提供商，或某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。
|
||||
- `/queue <mode>` 管理队列行为（`steer`、旧版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 清除会话覆盖。参见 [命令队列](/zh-CN/concepts/queue) 和 [Steering queue](/zh-CN/concepts/queue-steering)。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="设备发现和 Status">
|
||||
<Accordion title="设备发现和状态">
|
||||
- `/help` 显示简短帮助摘要。
|
||||
- `/commands` 显示生成的命令目录。
|
||||
- `/tools [compact|verbose]` 显示当前智能体现在可以使用的内容。
|
||||
- `/status` 显示执行/运行时 Status，包括 `Execution`/`Runtime` 标签，以及可用时的提供商用量/配额。
|
||||
- `/diagnostics [note]` 是用于 Gateway 网关 bug 和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 前请求明确的 exec 批准；不要用允许全部规则批准诊断。批准后，它会发送一份可粘贴报告，其中包含本地包路径、清单摘要、隐私说明和相关会话 ID。在群聊中，批准提示和报告会私下发送给所有者。当当前会话使用 OpenAI Codex harness 时，同一次批准还会将相关 Codex 反馈发送到 OpenAI 服务器，并且完成回复会列出 OpenClaw 会话 ID、Codex 线程 ID 以及 `codex resume <thread-id>` 命令。参见[诊断导出](/zh-CN/gateway/diagnostics)。
|
||||
- `/tools [compact|verbose]` 显示当前智能体现在可使用的内容。
|
||||
- `/status` 显示执行/运行时状态，包括 `Execution`/`Runtime` 标签，以及可用时的提供商使用量/配额。
|
||||
- `/diagnostics [note]` 是面向 Gateway 网关 bug 和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 前请求显式 exec 批准；不要用 allow-all 规则批准 diagnostics。批准后，它会发送一份可粘贴的报告，包含本地 bundle 路径、manifest 摘要、隐私说明和相关会话 ID。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一次批准还会将相关 Codex 反馈发送到 OpenAI 服务器，完成后的回复会列出 OpenClaw 会话 ID、Codex thread ID，以及 `codex resume <thread-id>` 命令。参见 [Diagnostics Export](/zh-CN/gateway/diagnostics)。
|
||||
- `/crestodian <request>` 从所有者私信运行 Crestodian 设置和修复助手。
|
||||
- `/tasks` 列出当前会话的活跃/近期后台任务。
|
||||
- `/context [list|detail|json]` 说明上下文如何组装。
|
||||
- `/whoami` 显示你的发送者 ID。别名：`/id`。
|
||||
- `/usage off|tokens|full|cost` 控制每条回复的用量页脚，或打印本地成本摘要。
|
||||
- `/usage off|tokens|full|cost` 控制每次响应的用量页脚，或打印本地成本摘要。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Skills、允许列表、批准">
|
||||
- `/skill <name> [input]` 按名称运行一个 skill。
|
||||
- `/skill <name> [input]` 按名称运行 skill。
|
||||
- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。
|
||||
- `/approve <id> <decision>` 解决 exec 批准提示。
|
||||
- `/btw <question>` 提出一个旁支问题，不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。
|
||||
- `/approve <id> <decision>` 处理 exec 批准提示。
|
||||
- `/btw <question>` 提出一个旁支问题，而不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="子智能体和 ACP">
|
||||
- `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。
|
||||
- `/focus <target>` 将当前 Discord 话题串或 Telegram 主题/对话绑定到一个会话目标。
|
||||
- `/focus <target>` 将当前 Discord 线程或 Telegram 话题/对话绑定到一个会话目标。
|
||||
- `/unfocus` 移除当前绑定。
|
||||
- `/agents` 列出当前会话中绑定到话题串的智能体。
|
||||
- `/agents` 列出当前会话中绑定到线程的智能体。
|
||||
- `/kill <id|#|all>` 中止一个或所有正在运行的子智能体。
|
||||
- `/steer <id|#> <message>` 向正在运行的子智能体发送 Steering queue。别名：`/tell`。
|
||||
- `/steer <id|#> <message>` 向正在运行的子智能体发送 Steering。别名：`/tell`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="仅所有者可执行的写入和管理">
|
||||
<Accordion title="仅所有者可写和管理">
|
||||
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅所有者可用。需要 `commands.config: true`。
|
||||
- `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅所有者可用。需要 `commands.mcp: true`。
|
||||
- `/mcp show|get|set|unset` 读取或写入 OpenClaw 管理的 MCP 服务器配置，位于 `mcp.servers` 下。仅所有者可用。需要 `commands.mcp: true`。
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` 检查或更改插件状态。`/plugin` 是别名。写入仅所有者可用。需要 `commands.plugins: true`。
|
||||
- `/debug show|set|unset|reset` 管理仅运行时生效的配置覆盖。仅所有者可用。需要 `commands.debug: true`。
|
||||
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用。
|
||||
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用它。
|
||||
- `/send on|off|inherit` 设置发送策略。仅所有者可用。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="语音、TTS、渠道控制">
|
||||
- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。参见 [TTS](/zh-CN/tools/tts)。
|
||||
- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。请参阅 [TTS](/zh-CN/tools/tts)。
|
||||
- `/activation mention|always` 设置群组激活模式。
|
||||
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。
|
||||
- `!poll [sessionId]` 检查后台 bash 作业。
|
||||
@ -203,129 +203,129 @@ x-i18n:
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 生成的 dock 命令
|
||||
### 生成的停靠命令
|
||||
|
||||
Dock 命令会将当前会话的回复路由切换到另一个已链接的
|
||||
渠道。有关设置、示例和故障排除，请参见[渠道停靠](/zh-CN/concepts/channel-docking)。
|
||||
停靠命令会将当前会话的回复路由切换到另一个已链接的
|
||||
渠道。有关设置、示例和故障排除，请参阅 [渠道停靠](/zh-CN/concepts/channel-docking)。
|
||||
|
||||
Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
停靠命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
|
||||
- `/dock-discord`（别名：`/dock_discord`）
|
||||
- `/dock-mattermost`（别名：`/dock_mattermost`）
|
||||
- `/dock-slack`（别名：`/dock_slack`）
|
||||
- `/dock-telegram`（别名：`/dock_telegram`）
|
||||
|
||||
在直接聊天中使用 dock 命令，可将当前会话的回复路由切换到另一个已链接的渠道。智能体会保留相同的会话上下文，但该会话后续回复会投递到所选渠道对端。
|
||||
在直接聊天中使用停靠命令，可将当前会话的回复路由切换到另一个已链接的渠道。智能体会保留相同的会话上下文，但该会话之后的回复会发送到所选渠道对端。
|
||||
|
||||
Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须位于同一个身份组中，例如 `["telegram:123", "discord:456"]`。如果 id 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活跃会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未链接到 Discord 对端，该命令会回复设置提示，而不是回落到普通聊天。
|
||||
停靠命令需要 `session.identityLinks`。来源发送者和目标对端必须位于同一身份组，例如 `["telegram:123", "discord:456"]`。如果 ID 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未链接到 Discord 对端，该命令会回复设置提示，而不是回落到普通聊天。
|
||||
|
||||
停靠只会更改活跃会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，也不会将转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或其他生成的 dock 命令可再次切换路由。
|
||||
停靠只会更改活动会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，或将转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的停靠命令可再次切换路由。
|
||||
|
||||
### 内置插件命令
|
||||
|
||||
内置插件可以添加更多斜杠命令。此仓库中当前的内置命令：
|
||||
|
||||
- `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见[配对](/zh-CN/channels/pairing)。
|
||||
- `/dreaming [on|off|status|help]` 切换记忆 Dreaming。请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。请参阅 [配对](/zh-CN/channels/pairing)。
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时启用高风险手机节点命令。
|
||||
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。
|
||||
- `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。
|
||||
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 检查并控制内置 Codex 应用服务器 harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。
|
||||
- 仅 QQBot 的命令：
|
||||
- `/card ...` 发送 LINE 富卡片预设。请参阅 [LINE](/zh-CN/channels/line)。
|
||||
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 检查和控制内置 Codex 应用服务器 harness。请参阅 [Codex harness](/zh-CN/plugins/codex-harness)。
|
||||
- 仅 QQBot 可用的命令：
|
||||
- `/bot-ping`
|
||||
- `/bot-version`
|
||||
- `/bot-help`
|
||||
- `/bot-upgrade`
|
||||
- `/bot-logs`
|
||||
|
||||
### 动态 Skills 命令
|
||||
### 动态技能命令
|
||||
|
||||
用户可调用的 Skills 也会公开为斜杠命令：
|
||||
用户可调用的 Skills 也会作为斜杠命令暴露：
|
||||
|
||||
- `/skill <name> [input]` 始终可作为通用入口点使用。
|
||||
- 当 skill/插件注册时，Skills 也可能以 `/prose` 这样的直接命令出现。
|
||||
- 当 skill/插件注册时，Skills 也可能显示为类似 `/prose` 的直接命令。
|
||||
- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
|
||||
- 命令规格可以为支持本地化描述的原生界面提供 `descriptionLocalizations`，包括 Discord。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="参数和解析器说明">
|
||||
- 命令和参数之间可接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
|
||||
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。
|
||||
- 要查看完整的提供商使用量明细，请使用 `openclaw status --usage`。
|
||||
- 命令和参数之间可以接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
|
||||
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，文本会被视为消息正文。
|
||||
- 如需完整的提供商用量明细，请使用 `openclaw status --usage`。
|
||||
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。
|
||||
- 在多账号渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账号的 `configWrites`。
|
||||
- `/usage` 控制每条回复的用量页脚；`/usage cost` 从 OpenClaw 会话日志打印本地成本摘要。
|
||||
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用。
|
||||
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包、`git:<repo>` 或 `clawhub:<pkg>`。
|
||||
- `/plugins enable|disable` 会更新插件配置，并可能提示重启。
|
||||
- `/usage` 控制每条回复的用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地费用汇总。
|
||||
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。
|
||||
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包、`git:<repo>` 或 `clawhub:<pkg>`，然后请求重启 Gateway 网关，因为插件源模块已更改。
|
||||
- `/plugins enable|disable` 更新插件配置，并为新的智能体轮次触发 Gateway 网关插件重新加载。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="特定渠道行为">
|
||||
- 仅 Discord 的原生命令：`/vc join|leave|status` 控制语音频道（不能作为文本使用）。`join` 需要一个服务器和已选择的语音/舞台频道。需要 `channels.discord.voice` 和原生命令。
|
||||
- Discord 话题串绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效的话题串绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
|
||||
<Accordion title="渠道特定行为">
|
||||
- 仅 Discord 可用的原生命令：`/vc join|leave|status` 控制语音频道（不能作为文本使用）。`join` 需要一个服务器和所选语音/舞台频道。需要 `channels.discord.voice` 和原生命令。
|
||||
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
|
||||
- ACP 命令参考和运行时行为：[ACP 智能体](/zh-CN/tools/acp-agents)。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Verbose / trace / fast / reasoning 安全性">
|
||||
- `/verbose` 用于调试和提供额外可见性；正常使用时保持**关闭**。
|
||||
- `/trace` 比 `/verbose` 范围更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具噪声关闭。
|
||||
- `/fast on|off` 会持久化一个会话覆盖。使用会话 UI 的 `inherit` 选项可清除它并回退到配置默认值。
|
||||
- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公开 Anthropic 请求（包括发送到 `api.anthropic.com` 的 OAuth 认证流量）会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
|
||||
- 相关时仍会显示工具失败摘要，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。
|
||||
- `/reasoning`、`/verbose` 和 `/trace` 在群组环境中存在风险：它们可能暴露你不打算公开的内部推理、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。
|
||||
- `/trace` 比 `/verbose` 范围更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具杂音关闭。
|
||||
- `/fast on|off` 会持久化一个会话覆盖。使用会话 UI 的 `inherit` 选项可清除它，并回退到配置默认值。
|
||||
- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将它映射到 `service_tier=priority`，而直接公共 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会将它映射到 `service_tier=auto` 或 `standard_only`。请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
|
||||
- 工具失败摘要在相关时仍会显示，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。
|
||||
- `/reasoning`、`/verbose` 和 `/trace` 在群组环境中有风险：它们可能暴露你不打算公开的内部推理、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="模型切换">
|
||||
- `/model` 会立即持久化新的会话模型。
|
||||
- 如果智能体处于空闲状态，下一次运行会立即使用它。
|
||||
- 如果已有运行处于活跃状态，OpenClaw 会将实时切换标记为待处理，并只会在干净的重试点重启到新模型。
|
||||
- 如果工具活动或回复输出已经开始，待处理的切换可能会保持排队，直到后续重试机会或下一轮用户输入。
|
||||
- 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回 Crestodian。这与消息渠道救援模式分开，并且不会授予远程配置权限。
|
||||
- 如果智能体处于空闲状态，下一次运行会立刻使用它。
|
||||
- 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并仅在干净的重试点重启到新模型。
|
||||
- 如果工具活动或回复输出已经开始，待处理切换可能会保持排队，直到后续重试机会或下一次用户轮次。
|
||||
- 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回 Crestodian。这与消息渠道救援模式分离，并且不会授予远程配置权限。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="快速路径和行内快捷命令">
|
||||
- **快速路径：**来自允许列表发送者的纯命令消息会被立即处理（绕过队列 + 模型）。
|
||||
- **群组提及门控：**来自允许列表发送者的纯命令消息会绕过提及要求。
|
||||
- **行内快捷命令（仅允许列表发送者）：**某些命令嵌入普通消息时也会生效，并在模型看到剩余文本前被剥离。
|
||||
<Accordion title="快速路径和内联快捷方式">
|
||||
- **快速路径：** 来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。
|
||||
- **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。
|
||||
- **内联快捷方式（仅允许列表发送者）：** 某些命令嵌入在普通消息中时也会生效，并会在模型看到剩余文本之前被移除。
|
||||
- 示例：`hey /status` 会触发状态回复，剩余文本继续通过普通流程。
|
||||
- 当前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
- 未授权的纯命令消息会被静默忽略，行内 `/...` token 会被视为纯文本。
|
||||
- 当前包括：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
- 未授权的纯命令消息会被静默忽略，内联 `/...` token 会被视为纯文本。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Skill 命令和原生参数">
|
||||
- **Skill 命令：**`user-invocable` Skills 会公开为斜杠命令。名称会被清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。
|
||||
- `/skill <name> [input]` 按名称运行 skill（当原生命令限制阻止为每个 skill 提供命令时很有用）。
|
||||
- **Skill 命令：** `user-invocable` Skills 会作为斜杠命令暴露。名称会被清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。
|
||||
- `/skill <name> [input]` 按名称运行一个 skill（当原生命令限制阻止按 skill 创建命令时很有用）。
|
||||
- 默认情况下，skill 命令会作为普通请求转发给模型。
|
||||
- Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，无模型）。
|
||||
- 示例：`/prose`（OpenProse 插件）— 参见 [OpenProse](/zh-CN/prose)。
|
||||
- **原生命令参数：**Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。当命令支持选项且你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选项会根据目标会话模型解析，因此像 `/think` 级别这样的模型特定选项会遵循该会话的 `/model` 覆盖。
|
||||
- 示例：`/prose`（OpenProse 插件）— 请参阅 [OpenProse](/zh-CN/prose)。
|
||||
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。当命令支持选择且你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选择会针对目标会话模型解析，因此 `/think` 级别等模型特定选项会遵循该会话的 `/model` 覆盖。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## `/tools`
|
||||
|
||||
`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体现在在此对话中可以使用什么**。
|
||||
`/tools` 回答的是运行时问题，而不是配置问题：**此智能体现在在这个对话中可以使用什么**。
|
||||
|
||||
- 默认 `/tools` 紧凑，并针对快速浏览优化。
|
||||
- `/tools verbose` 添加简短描述。
|
||||
- 支持参数的原生命令界面会公开相同的模式切换：`compact|verbose`。
|
||||
- 结果按会话限定，因此更改智能体、渠道、话题串、发送者授权或模型都可能改变输出。
|
||||
- `/tools` 包含运行时实际可达的工具，包括核心工具、已连接的插件工具以及渠道拥有的工具。
|
||||
- 支持参数的原生命令界面会暴露同样的模式切换：`compact|verbose`。
|
||||
- 结果限定于会话范围，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。
|
||||
- `/tools` 包含运行时实际可访问的工具，包括核心工具、已连接插件工具以及渠道拥有的工具。
|
||||
|
||||
要编辑 profile 和覆盖，请使用 Control UI 工具面板或配置/目录界面，而不是将 `/tools` 当作静态目录。
|
||||
如需编辑 profile 和覆盖，请使用 Control UI Tools 面板或配置/catalog 界面，而不是把 `/tools` 当作静态目录。
|
||||
|
||||
## 使用量界面（什么显示在哪里）
|
||||
## 用量界面（哪里显示什么）
|
||||
|
||||
- **提供商用量/配额**（示例：“Claude 剩余 80%”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余 %”；对于 MiniMax，仅剩余百分比字段会在显示前反转，并且 `model_remains` 响应优先使用聊天模型条目以及带模型标记的计划标签。
|
||||
- **令牌/缓存行** 在 `/status` 中可在实时会话快照稀疏时回退到最新的转录用量条目。现有的非零实时值仍然优先，并且当已存储总数缺失或更小时，转录回退还可以恢复活动运行时模型标签以及更大的面向提示词的总量。
|
||||
- **执行与运行时：** `/status` 会为有效沙箱路径报告 `Execution`，并为实际运行会话的一方报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、一个 CLI 后端或一个 ACP 后端。
|
||||
- **每次响应的令牌/成本** 由 `/usage off|tokens|full` 控制（追加到普通回复中）。
|
||||
- `/model status` 关注的是 **模型/认证/端点**，不是用量。
|
||||
- **提供商用量/配额**（示例：“Claude 80% 剩余”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余百分比”；对于 MiniMax，仅剩余百分比字段会在显示前取反，并且 `model_remains` 响应会优先使用聊天模型条目加上带模型标记的计划标签。
|
||||
- **Token/缓存行** 在 `/status` 中可以在实时会话快照稀疏时回退到最新的转录用量条目。现有的非零实时值仍然优先，并且转录回退还可以在已存储总量缺失或更小时恢复活动运行时模型标签，以及一个更大的面向提示词的总量。
|
||||
- **执行与运行时：** `/status` 会为有效沙箱路径报告 `Execution`，并为实际运行会话的一方报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。
|
||||
- **每次响应的 token/成本** 由 `/usage off|tokens|full` 控制（附加到普通回复中）。
|
||||
- `/model status` 关注的是**模型/凭证/端点**，不是用量。
|
||||
|
||||
## 模型选择（`/model`）
|
||||
|
||||
`/model` 以指令形式实现。
|
||||
`/model` 实现为一条指令。
|
||||
|
||||
示例：
|
||||
|
||||
@ -343,11 +343,11 @@ Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须
|
||||
- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型系列 + 可用提供商）。
|
||||
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单以及提交步骤。
|
||||
- `/model <#>` 会从该选择器中选择（并在可能时优先使用当前提供商）。
|
||||
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和可用时的 API 模式（`api`）。
|
||||
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`）（如果可用）。
|
||||
|
||||
## 调试覆盖项
|
||||
## 调试覆盖
|
||||
|
||||
`/debug` 允许你设置**仅运行时**的配置覆盖项（内存中，而非磁盘）。仅限所有者。默认禁用；使用 `commands.debug: true` 启用。
|
||||
`/debug` 允许你设置**仅运行时**配置覆盖（内存中，而非磁盘）。仅限所有者。默认禁用；通过 `commands.debug: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -360,12 +360,12 @@ Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须
|
||||
```
|
||||
|
||||
<Note>
|
||||
覆盖项会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖项并返回磁盘上的配置。
|
||||
覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并返回磁盘上的配置。
|
||||
</Note>
|
||||
|
||||
## 插件跟踪输出
|
||||
|
||||
`/trace` 允许你切换**会话范围的插件跟踪/调试行**，无需开启完整的详细模式。
|
||||
`/trace` 允许你切换**会话范围的插件跟踪/调试行**，而无需开启完整详细模式。
|
||||
|
||||
示例：
|
||||
|
||||
@ -380,13 +380,13 @@ Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须
|
||||
- 不带参数的 `/trace` 会显示当前会话跟踪状态。
|
||||
- `/trace on` 会为当前会话启用插件跟踪行。
|
||||
- `/trace off` 会再次禁用它们。
|
||||
- 插件跟踪行可以出现在 `/status` 中，也可以在普通 assistant 回复后作为后续诊断消息出现。
|
||||
- `/trace` 不会取代 `/debug`；`/debug` 仍管理仅运行时的配置覆盖项。
|
||||
- `/trace` 不会取代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。
|
||||
- 插件跟踪行可以出现在 `/status` 中，也可以在普通助手回复后作为后续诊断消息出现。
|
||||
- `/trace` 不会替代 `/debug`；`/debug` 仍然管理仅运行时配置覆盖。
|
||||
- `/trace` 不会替代 `/verbose`；普通详细工具/状态输出仍属于 `/verbose`。
|
||||
|
||||
## 配置更新
|
||||
|
||||
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者。默认禁用；使用 `commands.config: true` 启用。
|
||||
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者。默认禁用；通过 `commands.config: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -404,7 +404,7 @@ Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须
|
||||
|
||||
## MCP 更新
|
||||
|
||||
`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者。默认禁用；使用 `commands.mcp: true` 启用。
|
||||
`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者。默认禁用；通过 `commands.mcp: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -421,7 +421,7 @@ Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须
|
||||
|
||||
## 插件更新
|
||||
|
||||
`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。
|
||||
`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；通过 `commands.plugins: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -434,28 +434,29 @@ Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须
|
||||
```
|
||||
|
||||
<Note>
|
||||
- `/plugins list` 和 `/plugins show` 会针对当前工作区以及磁盘上的配置执行真实的插件发现。
|
||||
- `/plugins enable|disable` 只会更新插件配置；它不会安装或卸载插件。
|
||||
- 启用/禁用更改后，重启 Gateway 网关以应用它们。
|
||||
- `/plugins list` 和 `/plugins show` 会针对当前工作区以及磁盘配置执行真实插件发现。
|
||||
- `/plugins install` 会从 ClawHub、npm、git、本地目录和归档安装。
|
||||
- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。
|
||||
- 启用和禁用更改会为新的智能体轮次热重载 Gateway 网关插件运行时接口；安装会请求重启 Gateway 网关，因为插件源模块已更改。
|
||||
|
||||
</Note>
|
||||
|
||||
## 界面说明
|
||||
## 表面说明
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="每个界面的会话">
|
||||
<Accordion title="每个表面的会话">
|
||||
- **文本命令** 在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。
|
||||
- **原生命令** 使用隔离会话：
|
||||
- Discord：`agent:<agentId>:discord:slash:<userId>`
|
||||
- Slack：`agent:<agentId>:slack:slash:<userId>`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）
|
||||
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 指向聊天会话）
|
||||
- **`/stop`** 指向活动聊天会话，因此它可以中止当前运行。
|
||||
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定位聊天会话）
|
||||
- **`/stop`** 会定位活动聊天会话，以便它可以中止当前运行。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Slack 细节">
|
||||
仍支持 `channels.slack.slashCommand` 用于单个 `/openclaw` 风格命令。如果启用 `commands.native`，必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单以临时 Block Kit 按钮形式交付。
|
||||
`channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格命令。如果你启用 `commands.native`，必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会作为临时 Block Kit 按钮发送。
|
||||
|
||||
Slack 原生例外：注册 `/agentstatus`（不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。
|
||||
Slack 原生例外：注册 `/agentstatus`（不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然有效。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -466,13 +467,13 @@ Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须
|
||||
|
||||
不同于普通聊天：
|
||||
|
||||
- 它将当前会话用作背景上下文，
|
||||
- 它使用当前会话作为背景上下文，
|
||||
- 它作为单独的**无工具**一次性调用运行，
|
||||
- 它不会更改未来的会话上下文，
|
||||
- 它不会改变未来的会话上下文，
|
||||
- 它不会写入转录历史，
|
||||
- 它作为实时旁路结果交付，而不是普通 assistant 消息。
|
||||
- 它会作为实时旁路结果发送，而不是普通助手消息。
|
||||
|
||||
这使得 `/btw` 在你希望主任务继续进行的同时获取临时澄清时很有用。
|
||||
这使得 `/btw` 适合在主任务继续进行时获取临时澄清。
|
||||
|
||||
示例：
|
||||
|
||||
@ -480,9 +481,9 @@ Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须
|
||||
/btw what are we doing right now?
|
||||
```
|
||||
|
||||
请参阅 [BTW 旁路问题](/zh-CN/tools/btw)，了解完整行为和客户端 UX 细节。
|
||||
完整行为和客户端 UX 细节请参阅 [BTW 旁路问题](/zh-CN/tools/btw)。
|
||||
|
||||
## 相关
|
||||
## 相关内容
|
||||
|
||||
- [创建 Skills](/zh-CN/tools/creating-skills)
|
||||
- [Skills](/zh-CN/tools/skills)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user