chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
0749b4cca3
commit
bd2e09378a
@ -3,30 +3,30 @@ read_when:
|
||||
- 你想安装或管理 Gateway 网关插件或兼容包
|
||||
- 你想调试插件加载失败
|
||||
sidebarTitle: Plugins
|
||||
summary: CLI 参考：`openclaw plugins`（list、install、marketplace、uninstall、enable/disable、doctor）
|
||||
summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）'
|
||||
title: 插件
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:48:36Z"
|
||||
generated_at: "2026-04-28T17:10:20Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: b458b67b905941f8f1424db7127640a3ae033dde5092daafd9926567d1bfc6cb
|
||||
source_hash: 99b34b992248eec8830471d795d1827af208f739325fa02b01d58922a969d3b2
|
||||
source_path: cli/plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
管理 Gateway 网关插件、钩子包和兼容包。
|
||||
管理 Gateway 网关插件、钩子包和兼容 bundle。
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Plugin system" href="/zh-CN/tools/plugin">
|
||||
面向最终用户的插件安装、启用和故障排除指南。
|
||||
<Card title="插件系统" href="/zh-CN/tools/plugin">
|
||||
面向最终用户的指南，介绍如何安装、启用插件并排查插件问题。
|
||||
</Card>
|
||||
<Card title="Plugin bundles" href="/zh-CN/plugins/bundles">
|
||||
包兼容性模型。
|
||||
<Card title="插件 bundle" href="/zh-CN/plugins/bundles">
|
||||
Bundle 兼容性模型。
|
||||
</Card>
|
||||
<Card title="Plugin manifest" href="/zh-CN/plugins/manifest">
|
||||
清单字段和配置模式。
|
||||
<Card title="插件清单" href="/zh-CN/plugins/manifest">
|
||||
清单字段和配置 schema。
|
||||
</Card>
|
||||
<Card title="Security" href="/zh-CN/gateway/security">
|
||||
<Card title="安全" href="/zh-CN/gateway/security">
|
||||
插件安装的安全加固。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@ -55,12 +55,14 @@ openclaw plugins marketplace list <marketplace>
|
||||
openclaw plugins marketplace list <marketplace> --json
|
||||
```
|
||||
|
||||
如果要调查安装、inspect、卸载或 registry 刷新较慢的问题，请使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行命令。该 trace 会将阶段耗时写入 stderr，并保持 JSON 输出可解析。请参阅 [调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。
|
||||
|
||||
<Note>
|
||||
内置插件随 OpenClaw 一起提供。有些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；其他插件需要使用 `plugins enable`。
|
||||
内置插件随 OpenClaw 一起发布。有些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；其他插件需要 `plugins enable`。
|
||||
|
||||
原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空）。兼容包改用自己的包清单。
|
||||
原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空）。兼容 bundle 改用它们自己的 bundle 清单。
|
||||
|
||||
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表/info 输出还会显示包子类型（`codex`、`claude` 或 `cursor`）以及检测到的包能力。
|
||||
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细 list/info 输出还会显示 bundle 子类型（`codex`、`claude` 或 `cursor`）以及检测到的 bundle 能力。
|
||||
</Note>
|
||||
|
||||
### 安装
|
||||
@ -79,73 +81,73 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
|
||||
```
|
||||
|
||||
<Warning>
|
||||
裸包名会先在 ClawHub 中检查，然后再检查 npm。请像运行代码一样对待插件安装。优先使用固定版本。
|
||||
裸包名会先对照 ClawHub 检查，然后再检查 npm。请像运行代码一样对待插件安装。优先使用固定版本。
|
||||
</Warning>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Config includes and invalid-config recovery">
|
||||
如果你的 `plugins` 部分由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该被包含的文件，并保持 `openclaw.json` 不变。根包含、包含数组，以及带同级覆盖的包含会关闭失败，而不是展平。支持的形态见 [配置包含](/zh-CN/gateway/configuration)。
|
||||
<Accordion title="配置 include 和无效配置恢复">
|
||||
如果你的 `plugins` section 由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该 include 文件，并让 `openclaw.json` 保持不变。根 include、include 数组以及带有同级 override 的 include 会失败关闭，而不是被展平。有关支持的形态，请参阅 [配置 include](/zh-CN/gateway/configuration)。
|
||||
|
||||
如果安装期间配置无效，`plugins install` 通常会关闭失败，并提示你先运行 `openclaw doctor --fix`。Gateway 网关启动期间，某个插件的无效配置会被隔离到该插件，因此其他渠道和插件可以继续运行；`openclaw doctor --fix` 可以隔离无效的插件条目。唯一有文档说明的安装时例外，是面向显式选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件的窄范围内置插件恢复路径。
|
||||
如果安装期间配置无效，`plugins install` 通常会失败关闭，并提示你先运行 `openclaw doctor --fix`。在 Gateway 网关启动期间，某个插件的无效配置会被隔离到该插件，因此其他渠道和插件可以继续运行；`openclaw doctor --fix` 可以隔离该无效插件条目。唯一有文档说明的安装期例外，是面向显式选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件的窄内置插件恢复路径。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--force and reinstall vs update">
|
||||
`--force` 会复用现有安装目标，并就地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 工件重新安装相同 id 时使用它。对于已跟踪 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
|
||||
<Accordion title="--force 与重新安装相对 update">
|
||||
`--force` 会复用现有安装目标，并在原地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm artifact 重新安装相同 id 时使用它。对于已跟踪的 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
|
||||
|
||||
如果你为已安装的插件 id 运行 `plugins install`，OpenClaw 会停止，并指向 `plugins update <id-or-npm-spec>` 用于常规升级，或者在你确实想从不同来源覆盖当前安装时，指向 `plugins install <package> --force`。
|
||||
如果你对已安装的插件 id 运行 `plugins install`，OpenClaw 会停止，并指向 `plugins update <id-or-npm-spec>` 以执行正常升级；如果你确实想从不同来源覆盖当前安装，则指向 `plugins install <package> --force`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--pin scope">
|
||||
`--pin` 仅适用于 npm 安装。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm 规范。
|
||||
<Accordion title="--pin 作用域">
|
||||
`--pin` 只适用于 npm 安装。不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm spec。
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install">
|
||||
`--dangerously-force-unsafe-install` 是内置危险代码扫描器出现误报时的应急选项。即使内置扫描器报告 `critical` 发现，它也允许安装继续，但它**不会**绕过插件 `before_install` 钩子策略阻止，也**不会**绕过扫描失败。
|
||||
`--dangerously-force-unsafe-install` 是内置危险代码扫描器出现误报时的应急选项。即使内置扫描器报告 `critical` 发现，它也允许安装继续，但它**不会**绕过插件 `before_install` 钩子的策略拦截，也**不会**绕过扫描失败。
|
||||
|
||||
此 CLI 标志适用于插件安装/update 流程。由 Gateway 网关支持的 skill 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是单独的 ClawHub skill 下载/安装流程。
|
||||
此 CLI 标志适用于插件安装/update 流程。由 Gateway 网关支持的 skill 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求 override，而 `openclaw skills install` 仍然是单独的 ClawHub skill 下载/安装流程。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Hook packs and npm specs">
|
||||
`plugins install` 也是安装钩子包的入口，这些钩子包会在 `package.json` 中暴露 `openclaw.hooks`。使用 `openclaw hooks` 查看经过筛选的钩子可见性和逐钩子启用，不要用于包安装。
|
||||
<Accordion title="钩子包和 npm specs">
|
||||
`plugins install` 也是安装暴露 `openclaw.hooks` 的钩子包的界面，位置在 `package.json` 中。使用 `openclaw hooks` 查看经过筛选的钩子可见性和单个钩子启用状态，而不是用于包安装。
|
||||
|
||||
Npm 规范**仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file 规范和 semver 范围会被拒绝。为安全起见，依赖安装会以项目本地方式运行并使用 `--ignore-scripts`，即使你的 shell 中有全局 npm 安装设置也是如此。
|
||||
Npm specs **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file specs 和 semver ranges 会被拒绝。为了安全，即使你的 shell 有全局 npm install 设置，依赖安装也会以项目本地方式并带 `--ignore-scripts` 运行。
|
||||
|
||||
当你想跳过 ClawHub 查找并直接从 npm 安装时，使用 `npm:<package>`。裸包规范仍优先使用 ClawHub，并且只有在 ClawHub 没有该包或版本时才回退到 npm。
|
||||
当你想跳过 ClawHub lookup 并直接从 npm 安装时，使用 `npm:<package>`。裸包 specs 仍优先使用 ClawHub，只有当 ClawHub 没有该包或版本时才回退到 npm。
|
||||
|
||||
裸规范和 `@latest` 会停留在稳定轨道。如果 npm 将其中任一项解析为预发布版本，OpenClaw 会停止并要求你使用预发布标签（例如 `@beta`/`@rc`）或精确的预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。
|
||||
裸 specs 和 `@latest` 会留在 stable 轨道。如果 npm 将其中任一项解析为 prerelease，OpenClaw 会停止，并要求你通过 prerelease tag（例如 `@beta`/`@rc`）或精确 prerelease 版本（例如 `@1.2.3-beta.4`）显式选择加入。
|
||||
|
||||
如果裸安装规范匹配内置插件 id（例如 `diffs`），OpenClaw 会直接安装内置插件。若要安装同名 npm 包，请使用显式作用域规范（例如 `@scope/diffs`）。
|
||||
如果裸 install spec 匹配内置插件 id（例如 `diffs`），OpenClaw 会直接安装该内置插件。若要安装同名 npm 包，请使用显式 scoped spec（例如 `@scope/diffs`）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Archives">
|
||||
支持的归档：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw 插件归档必须在解压后的插件根目录中包含有效的 `openclaw.plugin.json`；仅包含 `package.json` 的归档会在 OpenClaw 写入安装记录前被拒绝。
|
||||
<Accordion title="归档">
|
||||
支持的归档：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw 插件归档必须在解压后的插件根目录包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的归档会在 OpenClaw 写入安装记录之前被拒绝。
|
||||
|
||||
也支持 Claude marketplace 安装。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
ClawHub 安装使用显式 `clawhub:<package>` 定位符：
|
||||
ClawHub 安装使用显式的 `clawhub:<package>` locator：
|
||||
|
||||
```bash
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
|
||||
```
|
||||
|
||||
OpenClaw 现在也会优先将 ClawHub 用于裸 npm 安全插件规范。只有在 ClawHub 没有该包或版本时，它才会回退到 npm：
|
||||
OpenClaw 现在还会优先为裸 npm-safe 插件 specs 使用 ClawHub。只有当 ClawHub 没有该包或版本时，才会回退到 npm：
|
||||
|
||||
```bash
|
||||
openclaw plugins install openclaw-codex-app-server
|
||||
```
|
||||
|
||||
使用 `npm:` 强制仅使用 npm 解析，例如当 ClawHub 无法访问，或你知道该包只存在于 npm 上时：
|
||||
使用 `npm:` 可强制仅通过 npm 解析，例如当 ClawHub 无法访问，或你知道该包只存在于 npm 上时：
|
||||
|
||||
```bash
|
||||
openclaw plugins install npm:openclaw-codex-app-server
|
||||
openclaw plugins install npm:@scope/plugin-name@1.0.1
|
||||
```
|
||||
|
||||
OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低 Gateway 网关兼容性，然后通过普通归档路径安装它。记录的安装会保留其 ClawHub 源元数据，以供后续更新使用。
|
||||
未指定版本的 ClawHub 安装会保留未指定版本的记录规范，因此 `openclaw plugins update` 可以跟随后续较新的 ClawHub 发布；显式版本或标签选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）会保持固定到该选择器。
|
||||
OpenClaw 会从 ClawHub 下载包归档，检查声明的插件 API / 最低 gateway 兼容性，然后通过常规归档路径安装它。记录的安装会保留其 ClawHub 源元数据，以供后续 update 使用。
|
||||
未指定版本的 ClawHub 安装会保留未指定版本的记录 spec，因此 `openclaw plugins update` 可以跟随后续较新的 ClawHub release；显式版本或 tag 选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍固定到该选择器。
|
||||
|
||||
#### Marketplace 简写
|
||||
|
||||
@ -166,31 +168,31 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Marketplace sources">
|
||||
- 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称
|
||||
<Tab title="Marketplace 源">
|
||||
- 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude known-marketplace 名称
|
||||
- 本地 marketplace 根目录或 `marketplace.json` 路径
|
||||
- GitHub 仓库简写，例如 `owner/repo`
|
||||
- GitHub 仓库 URL，例如 `https://github.com/owner/repo`
|
||||
- GitHub repo 简写，例如 `owner/repo`
|
||||
- GitHub repo URL，例如 `https://github.com/owner/repo`
|
||||
- git URL
|
||||
|
||||
</Tab>
|
||||
<Tab title="Remote marketplace rules">
|
||||
对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内。OpenClaw 接受来自该仓库的相对路径源，并拒绝来自远程清单的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件源。
|
||||
<Tab title="远程 marketplace 规则">
|
||||
对于从 GitHub 或 git 加载的远程 marketplaces，插件条目必须保持在克隆的 marketplace repo 内。OpenClaw 接受来自该 repo 的相对路径源，并拒绝来自远程清单的 HTTP(S)、绝对路径、git、GitHub 和其他非路径插件源。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
对于本地路径和归档，OpenClaw 会自动检测：
|
||||
|
||||
- 原生 OpenClaw 插件（`openclaw.plugin.json`）
|
||||
- Codex 兼容包（`.codex-plugin/plugin.json`）
|
||||
- Claude 兼容包（`.claude-plugin/plugin.json` 或默认 Claude 组件布局）
|
||||
- Cursor 兼容包（`.cursor-plugin/plugin.json`）
|
||||
- Codex-compatible bundles（`.codex-plugin/plugin.json`）
|
||||
- Claude-compatible bundles（`.claude-plugin/plugin.json` 或默认 Claude 组件布局）
|
||||
- Cursor-compatible bundles（`.cursor-plugin/plugin.json`）
|
||||
|
||||
<Note>
|
||||
兼容包会安装到普通插件根目录，并参与同一套 list/info/enable/disable 流程。目前支持包 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex 钩子目录；其他检测到的包能力会显示在诊断/info 中，但尚未接入运行时执行。
|
||||
兼容 bundle 会安装到正常插件根目录，并参与相同的 list/info/enable/disable 流程。目前支持 bundle skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex 钩子目录；其他检测到的 bundle 能力会显示在 diagnostics/info 中，但尚未接入运行时执行。
|
||||
</Note>
|
||||
|
||||
### 列出
|
||||
### 列表
|
||||
|
||||
```bash
|
||||
openclaw plugins list
|
||||
@ -203,27 +205,23 @@ openclaw plugins list --json
|
||||
仅显示已启用的插件。
|
||||
</ParamField>
|
||||
<ParamField path="--verbose" type="boolean">
|
||||
从表格视图切换到逐插件详细行，包含 source/origin/version/activation 元数据。
|
||||
从表格视图切换为每个插件的详情行，包含 source/origin/version/activation 元数据。
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
机器可读的清单，以及 registry 诊断。
|
||||
机器可读 inventory 加 registry diagnostics。
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
`plugins list` 会先读取持久化的本地插件 registry；如果 registry 缺失或无效，则使用仅由清单派生的回退结果。它适合检查插件是否已安装、已启用，并且对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，请重启服务该渠道的 Gateway 网关，再期待新的 `register(api)` 代码或钩子运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不只是包装进程。
|
||||
`plugins list` 会先读取持久化的本地插件 registry；当 registry 缺失或无效时，使用仅基于清单派生的 fallback。它适合检查插件是否已安装、启用并对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，请先重启服务该渠道的 Gateway 网关，再期待新的 `register(api)` 代码或钩子运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不只是 wrapper 进程。
|
||||
</Note>
|
||||
|
||||
对于打包 Docker 镜像内的内置插件工作，请将插件
|
||||
源目录绑定挂载到匹配的打包源路径上，例如
|
||||
`/app/extensions/synology-chat`。OpenClaw 会先发现该挂载的源
|
||||
覆盖层，再发现 `/app/dist/extensions/synology-chat`；普通复制的源
|
||||
目录仍不会生效，因此常规打包安装仍会使用编译后的 dist。
|
||||
对于 packaged Docker image 内的内置插件工作，请将插件源目录 bind-mount 到匹配的 packaged source path 上，例如 `/app/extensions/synology-chat`。OpenClaw 会先发现该挂载的 source overlay，再发现 `/app/dist/extensions/synology-chat`；普通复制的源目录仍不会生效，因此正常 packaged installs 仍使用 compiled dist。
|
||||
|
||||
对于运行时钩子调试：
|
||||
|
||||
- `openclaw plugins inspect <id> --json` 显示模块加载检查过程中注册的钩子和诊断信息。
|
||||
- `openclaw gateway status --deep --require-rpc` 确认可访问的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态。
|
||||
- 非内置对话钩子（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
|
||||
- `openclaw plugins inspect <id> --json` 会显示一次模块加载检查过程中注册的钩子和诊断信息。
|
||||
- `openclaw gateway status --deep --require-rpc` 会确认可访问的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态。
|
||||
- 非内置会话钩子（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
|
||||
|
||||
使用 `--link` 避免复制本地目录（会添加到 `plugins.load.paths`）：
|
||||
|
||||
@ -232,16 +230,16 @@ openclaw plugins install -l ./my-plugin
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制到托管安装目标上。
|
||||
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是覆盖复制到托管安装目标。
|
||||
|
||||
在 npm 安装中使用 `--pin`，可将解析后的精确规格（`name@version`）保存到托管插件索引中，同时保持默认行为为不固定版本。
|
||||
在 npm 安装中使用 `--pin`，可将解析后的精确规格（`name@version`）保存到托管插件索引，同时保持默认行为不固定版本。
|
||||
</Note>
|
||||
|
||||
### 插件索引
|
||||
|
||||
插件安装元数据是机器管理的状态，不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组是从清单派生的冷注册表缓存。该文件包含请勿编辑警告，并由 `openclaw plugins update`、卸载、诊断和冷插件注册表使用。
|
||||
插件安装元数据是由机器管理的状态，不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件 manifest 的记录。`plugins` 数组是从 manifest 派生的冷注册表缓存。该文件包含请勿编辑警告，并由 `openclaw plugins update`、卸载、诊断和冷插件注册表使用。
|
||||
|
||||
当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，会将它们移动到插件索引中并移除该配置键；如果任一写入失败，会保留配置记录，避免安装元数据丢失。
|
||||
当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，会将它们移动到插件索引并移除该配置键；如果任一写入失败，配置记录会保留，避免安装元数据丢失。
|
||||
|
||||
### 卸载
|
||||
|
||||
@ -251,10 +249,10 @@ openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` 会从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目以及适用时链接的 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，卸载还会移除跟踪的托管安装目录，前提是它位于 OpenClaw 的插件扩展根目录内。对于活动的内存插件，内存槽会重置为 `memory-core`。
|
||||
`uninstall` 会从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及适用时链接的 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，否则卸载还会在托管安装目录位于 OpenClaw 插件扩展根目录内时移除该受跟踪的托管安装目录。对于活动内存插件，内存槽会重置为 `memory-core`。
|
||||
|
||||
<Note>
|
||||
`--keep-config` 作为 `--keep-files` 的已弃用别名受支持。
|
||||
`--keep-config` 作为 `--keep-files` 的已弃用别名仍受支持。
|
||||
</Note>
|
||||
|
||||
### 更新
|
||||
@ -267,25 +265,25 @@ openclaw plugins update @openclaw/voice-call@beta
|
||||
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
|
||||
```
|
||||
|
||||
更新适用于托管插件索引中跟踪的插件安装，以及 `hooks.internal.installs` 中跟踪的钩子包安装。
|
||||
更新会应用于托管插件索引中受跟踪的插件安装，以及 `hooks.internal.installs` 中受跟踪的钩子包安装。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Resolving plugin id vs npm spec">
|
||||
当你传入插件 id 时，OpenClaw 会复用该插件记录的安装规格。这意味着先前存储的 dist-tag（例如 `@beta`）和精确固定版本会在之后的 `update <id>` 运行中继续使用。
|
||||
<Accordion title="解析插件 id 与 npm 规格">
|
||||
当你传入插件 id 时，OpenClaw 会复用为该插件记录的安装规格。这意味着之前存储的 dist-tag（例如 `@beta`）和精确固定版本，会在后续 `update <id>` 运行中继续使用。
|
||||
|
||||
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包规格。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格以供未来基于 id 的更新使用。
|
||||
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包规格。OpenClaw 会将该包名解析回受跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格供将来基于 id 的更新使用。
|
||||
|
||||
传入不带版本或标签的 npm 包名，也会解析回被跟踪的插件记录。当某个插件被固定到精确版本，而你想将其移回注册表默认发布线时使用此方式。
|
||||
传入不带版本或标签的 npm 包名也会解析回受跟踪的插件记录。当某个插件被固定到精确版本，而你想将其移回注册表默认发布线时，请使用这种方式。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Version checks and integrity drift">
|
||||
在实时 npm 更新之前，OpenClaw 会对照 npm 注册表元数据检查已安装包版本。如果已安装版本和记录的构件身份已与解析后的目标匹配，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。
|
||||
<Accordion title="版本检查和完整性漂移">
|
||||
在执行实时 npm 更新前，OpenClaw 会根据 npm 注册表元数据检查已安装包版本。如果已安装版本和记录的产物身份已经与解析目标匹配，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。
|
||||
|
||||
当存在已存储的完整性哈希且获取到的构件哈希发生变化时，OpenClaw 会将其视为 npm 构件漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助工具会默认关闭失败，除非调用方提供显式继续策略。
|
||||
当存在已存储的完整性哈希且获取到的产物哈希发生变化时，OpenClaw 会将其视为 npm 产物漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助程序会默认关闭失败，除非调用方提供显式继续策略。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install on update">
|
||||
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的应急覆盖。它仍然不会绕过插件 `before_install` 策略阻止或扫描失败阻止，并且只适用于插件更新，不适用于钩子包更新。
|
||||
<Accordion title="更新时使用 --dangerously-force-unsafe-install">
|
||||
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的破窗覆盖。它仍不会绕过插件 `before_install` 策略阻断或扫描失败阻断，并且仅适用于插件更新，不适用于钩子包更新。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -296,9 +294,9 @@ openclaw plugins inspect <id>
|
||||
openclaw plugins inspect <id> --json
|
||||
```
|
||||
|
||||
对单个插件进行深度自省。显示身份、加载状态、来源、已注册能力、钩子、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、诊断信息、安装元数据、包能力，以及检测到的任何 MCP 或 LSP 服务器支持。
|
||||
对单个插件进行深度内省。显示身份、加载状态、来源、已注册能力、钩子、工具、命令、服务、Gateway 网关方法、HTTP 路由、策略标志、诊断信息、安装元数据、包能力，以及检测到的任何 MCP 或 LSP 服务器支持。
|
||||
|
||||
每个插件会按其在运行时实际注册的内容分类：
|
||||
每个插件都会按其在运行时实际注册的内容分类：
|
||||
|
||||
- **plain-capability** — 一种能力类型（例如仅提供商插件）
|
||||
- **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像）
|
||||
@ -308,7 +306,7 @@ openclaw plugins inspect <id> --json
|
||||
有关能力模型的更多信息，请参阅 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
|
||||
|
||||
<Note>
|
||||
`--json` 标志会输出适合脚本和审计的机器可读报告。`inspect --all` 会渲染一张全局表格，包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。
|
||||
`--json` 标志会输出适合脚本和审计使用的机器可读报告。`inspect --all` 会呈现全量表格，包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。
|
||||
</Note>
|
||||
|
||||
### Doctor
|
||||
@ -317,9 +315,9 @@ openclaw plugins inspect <id> --json
|
||||
openclaw plugins doctor
|
||||
```
|
||||
|
||||
`doctor` 报告插件加载错误、清单/设备发现诊断信息和兼容性通知。当一切正常时，会打印 `No plugin issues detected.`
|
||||
`doctor` 会报告插件加载错误、manifest/设备发现诊断信息，以及兼容性通知。当一切正常时，它会打印 `No plugin issues detected.`
|
||||
|
||||
对于模块形态失败，例如缺少 `register`/`activate` 导出，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。
|
||||
对于缺少 `register`/`activate` 导出等模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。
|
||||
|
||||
### 注册表
|
||||
|
||||
@ -329,12 +327,12 @@ openclaw plugins registry --refresh
|
||||
openclaw plugins registry --json
|
||||
```
|
||||
|
||||
本地插件注册表是 OpenClaw 的持久化冷读取模型，用于已安装插件的身份、启用状态、来源元数据和贡献归属。正常启动、提供商所有者查找、渠道设置分类和插件清单都可以在不导入插件运行时模块的情况下读取它。
|
||||
本地插件注册表是 OpenClaw 为已安装插件身份、启用状态、来源元数据和贡献归属持久化的冷读取模型。正常启动、提供商所有者查找、渠道设置分类和插件清单都可以读取它，而无需导入插件运行时模块。
|
||||
|
||||
使用 `plugins registry` 检查持久化注册表是否存在、是否为当前版本或是否已过期。使用 `--refresh` 可根据持久化插件索引、配置策略和清单/包元数据重建它。这是修复路径，不是运行时激活路径。
|
||||
使用 `plugins registry` 检查持久化注册表是否存在、是否当前有效或是否过期。使用 `--refresh` 可根据持久化插件索引、配置策略和 manifest/包元数据重建它。这是修复路径，不是运行时激活路径。
|
||||
|
||||
<Warning>
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的应急兼容性开关，用于注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；环境变量回退仅用于迁移推出期间的紧急启动恢复。
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是用于注册表读取失败的已弃用破窗兼容开关。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；该环境变量回退仅用于迁移推出期间的紧急启动恢复。
|
||||
</Warning>
|
||||
|
||||
### 市场
|
||||
@ -344,7 +342,7 @@ openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
```
|
||||
|
||||
市场列表接受本地市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的来源标签，以及解析出的市场清单和插件条目。
|
||||
市场列表接受本地市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印解析后的来源标签，以及解析后的市场 manifest 和插件条目。
|
||||
|
||||
## 相关
|
||||
|
||||
|
||||
@ -1,26 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要检查原始模型输出中的推理泄漏问题
|
||||
- 你想在迭代时以监视模式运行 Gateway 网关
|
||||
- 你需要一套可重复的调试工作流
|
||||
summary: 调试工具：监视模式、原始模型流以及推理泄漏追踪
|
||||
- 你需要检查原始模型输出是否泄露推理内容
|
||||
- 你想在迭代过程中以监视模式运行 Gateway 网关
|
||||
- 你需要一个可重复的调试工作流
|
||||
summary: 调试工具：监视模式、原始模型流和推理泄漏追踪
|
||||
title: 调试
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T06:04:45Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-28T17:10:23Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 374af10312e07d4c4e45d07416fa2d0920dd300e739ebb7a3b72b1e327f21cc1
|
||||
source_hash: 13a49773e39041c77d4562aadcf03669bb5e66801be9908954e971a27f924cd4
|
||||
source_path: help/debugging.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
用于调试流式输出的辅助工具，尤其适用于提供商将推理内容混入普通文本时的情况。
|
||||
流式输出的调试辅助工具，尤其适用于提供商将推理内容混入普通文本的情况。
|
||||
|
||||
## 运行时调试覆盖
|
||||
|
||||
在聊天中使用 `/debug` 可设置**仅运行时**的配置覆盖（存储在内存中，不写入磁盘）。
|
||||
`/debug` 默认禁用；通过 `commands.debug: true` 启用。
|
||||
当你需要切换一些冷门设置而不想编辑 `openclaw.json` 时，这很方便。
|
||||
在聊天中使用 `/debug` 设置**仅运行时**配置覆盖（保存在内存中，不写入磁盘）。
|
||||
`/debug` 默认禁用；使用 `commands.debug: true` 启用。
|
||||
当你需要切换晦涩设置但不想编辑 `openclaw.json` 时，这很方便。
|
||||
|
||||
示例：
|
||||
|
||||
@ -33,10 +33,9 @@ x-i18n:
|
||||
|
||||
`/debug reset` 会清除所有覆盖，并恢复为磁盘上的配置。
|
||||
|
||||
## 会话 trace 输出
|
||||
## 会话跟踪输出
|
||||
|
||||
当你希望只在某个会话中查看插件拥有的 trace/debug 行，
|
||||
而不启用完整 verbose 模式时，请使用 `/trace`。
|
||||
当你想在一个会话中查看插件拥有的跟踪/调试行，但不想开启完整详细模式时，使用 `/trace`。
|
||||
|
||||
示例：
|
||||
|
||||
@ -47,23 +46,39 @@ x-i18n:
|
||||
```
|
||||
|
||||
将 `/trace` 用于插件诊断，例如 Active Memory 调试摘要。
|
||||
普通 verbose 状态/工具输出仍使用 `/verbose`，而运行时专用配置覆盖仍使用
|
||||
`/debug`。
|
||||
继续使用 `/verbose` 查看常规的详细 Status/工具输出，并继续使用 `/debug` 进行仅运行时配置覆盖。
|
||||
|
||||
## 插件生命周期跟踪
|
||||
|
||||
当插件生命周期命令感觉很慢，并且你需要内置的阶段拆解来查看插件元数据、设备发现、注册表、运行时镜像、配置变更和刷新工作时，使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`。该跟踪是选择性启用的，并写入 stderr，因此 JSON 命令输出仍保持可解析。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
|
||||
```
|
||||
|
||||
示例输出：
|
||||
|
||||
```text
|
||||
[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
|
||||
[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"
|
||||
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"
|
||||
```
|
||||
|
||||
在使用 CPU 分析器之前，先用它调查插件生命周期。
|
||||
如果命令从源码检出目录运行，建议在 `pnpm build` 后用 `node dist/entry.js ...` 测量构建后的运行时；`pnpm openclaw ...` 也会把源码运行器开销计入测量。
|
||||
|
||||
## 临时 CLI 调试计时
|
||||
|
||||
OpenClaw 保留 `src/cli/debug-timing.ts` 作为一个用于本地排查的小型辅助工具。
|
||||
它有意默认不接入 CLI 启动流程、命令路由或任何命令。仅在调试慢命令时使用，
|
||||
然后在提交行为变更前移除相应的 import 和 span。
|
||||
OpenClaw 保留 `src/cli/debug-timing.ts` 作为本地调查的小型辅助工具。
|
||||
它有意默认不接入 CLI 启动、命令路由或任何命令。只在调试慢命令时使用它，然后在落地行为变更前移除 import 和 span。
|
||||
|
||||
当某条命令很慢，而你需要先快速拆解各阶段耗时，
|
||||
再决定是使用 CPU profiler 还是修复某个特定子系统时，可使用它。
|
||||
当某个命令很慢，而你需要快速查看阶段拆解，再决定是使用 CPU 分析器还是修复特定子系统时，使用它。
|
||||
|
||||
### 添加临时 span
|
||||
|
||||
将辅助工具添加到你正在排查的代码附近。例如，在调试
|
||||
`openclaw models list` 时，可在
|
||||
`src/commands/models/list.list-command.ts` 中临时加入如下补丁：
|
||||
在你正在调查的代码附近添加该辅助工具。例如，在调试 `openclaw models list` 时，`src/commands/models/list.list-command.ts` 中的临时补丁可能如下所示：
|
||||
|
||||
```ts
|
||||
// Temporary debugging only. Remove before landing.
|
||||
@ -83,15 +98,15 @@ const loaded = await timing.timeAsync(
|
||||
);
|
||||
```
|
||||
|
||||
指南：
|
||||
准则：
|
||||
|
||||
- 临时阶段名称请使用 `debug:` 前缀。
|
||||
- 只在怀疑较慢的代码段周围添加少量 span。
|
||||
- 优先使用宽泛阶段名称，如 `registry`、`auth_store` 或 `rows`，而不是辅助函数名。
|
||||
- 对同步工作使用 `time()`，对 Promise 使用 `timeAsync()`。
|
||||
- 保持 stdout 干净。该辅助工具会写入 stderr，因此命令的 JSON 输出仍可解析。
|
||||
- 在提交最终修复 PR 前移除临时 import 和 span。
|
||||
- 在 issue 或 PR 中附上计时输出或简短摘要，以说明优化依据。
|
||||
- 用 `debug:` 作为临时阶段名称的前缀。
|
||||
- 只在疑似慢的区段周围添加少量 span。
|
||||
- 相比辅助函数名称，优先使用 `registry`、`auth_store` 或 `rows` 这类宽泛阶段。
|
||||
- 对同步工作使用 `time()`，对 promise 使用 `timeAsync()`。
|
||||
- 保持 stdout 干净。该辅助工具写入 stderr，因此命令 JSON 输出保持可解析。
|
||||
- 在打开最终修复 PR 前移除临时 import 和 span。
|
||||
- 在 issue 或 PR 中包含计时输出或简短摘要，以说明优化依据。
|
||||
|
||||
### 使用可读输出运行
|
||||
|
||||
@ -101,7 +116,7 @@ const loaded = await timing.timeAsync(
|
||||
OPENCLAW_DEBUG_TIMING=1 pnpm openclaw models list --all --provider moonshot
|
||||
```
|
||||
|
||||
来自一次临时 `models list` 排查的示例输出：
|
||||
临时 `models list` 调查的示例输出：
|
||||
|
||||
```text
|
||||
OpenClaw CLI debug timing: models list
|
||||
@ -130,30 +145,29 @@ moonshot/kimi-k2.6 text+image 256k no no
|
||||
36.9s +0ms complete rows=5
|
||||
```
|
||||
|
||||
从这份输出可得出的结论：
|
||||
从该输出得出的发现：
|
||||
|
||||
| Phase | Time | 含义 |
|
||||
| ----- | ---: | ---- |
|
||||
| `debug:models:list:auth_store` | 20.3s | auth-profile store 加载是最大的成本，应优先排查。 |
|
||||
| `debug:models:list:ensure_models_json` | 5.0s | 同步 `models.json` 的开销足够大，值得检查缓存或跳过条件。 |
|
||||
| `debug:models:list:load_model_registry` | 5.9s | 注册表构建和 provider 可用性检查也有明显成本。 |
|
||||
| `debug:models:list:read_registry_models` | 2.4s | 读取全部注册表模型并非没有成本，对 `--all` 可能很重要。 |
|
||||
| 行追加阶段 | 总计 3.2s | 即使只构建 5 行显示结果，也用了数秒，因此应进一步查看过滤路径。 |
|
||||
| `debug:models:list:print_model_table` | 0ms | 渲染不是瓶颈。 |
|
||||
| 阶段 | 时间 | 含义 |
|
||||
| ---------------------------------------- | ---------: | ------------------------------------------------------------------------------------------------------- |
|
||||
| `debug:models:list:auth_store` | 20.3s | auth-profile 存储加载是最大成本，应优先调查。 |
|
||||
| `debug:models:list:ensure_models_json` | 5.0s | 同步 `models.json` 的开销已经值得检查是否可缓存或跳过。 |
|
||||
| `debug:models:list:load_model_registry` | 5.9s | 注册表构建和提供商可用性工作也是有意义的成本。 |
|
||||
| `debug:models:list:read_registry_models` | 2.4s | 读取所有注册表模型并非免费，对 `--all` 可能有影响。 |
|
||||
| 行追加阶段 | 总计 3.2s | 构建五个显示行仍需数秒，因此过滤路径值得进一步查看。 |
|
||||
| `debug:models:list:print_model_table` | 0ms | 渲染不是瓶颈。 |
|
||||
|
||||
这些结论已经足以指导下一次补丁，而无需将计时代码保留在
|
||||
生产路径中。
|
||||
这些发现足以指导下一次补丁，而无需在生产路径中保留计时代码。
|
||||
|
||||
### 使用 JSON 输出运行
|
||||
|
||||
当你想保存或比较计时数据时，请使用 JSON 模式：
|
||||
当你想保存或比较计时数据时，使用 JSON 模式：
|
||||
|
||||
```bash
|
||||
OPENCLAW_DEBUG_TIMING=json pnpm openclaw models list --all --provider moonshot \
|
||||
2> .artifacts/models-list-timing.jsonl
|
||||
```
|
||||
|
||||
stderr 的每一行都是一个 JSON 对象：
|
||||
每一行 stderr 都是一个 JSON 对象：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -167,9 +181,9 @@ stderr 的每一行都是一个 JSON 对象：
|
||||
}
|
||||
```
|
||||
|
||||
### 提交前清理
|
||||
### 落地前清理
|
||||
|
||||
在打开最终 PR 之前：
|
||||
打开最终 PR 前：
|
||||
|
||||
```bash
|
||||
rg 'createCliDebugTiming|debug:[a-z0-9_-]+:' src/commands src/cli \
|
||||
@ -177,47 +191,36 @@ rg 'createCliDebugTiming|debug:[a-z0-9_-]+:' src/commands src/cli \
|
||||
--glob '!*.test.ts'
|
||||
```
|
||||
|
||||
除非该 PR 明确是在添加永久性的诊断能力，否则该命令不应返回任何临时埋点调用点。
|
||||
对于普通性能修复，只保留行为变更、测试以及包含计时证据的简短说明。
|
||||
除非该 PR 明确是在添加永久诊断界面，否则该命令不应返回任何临时插桩调用点。对于常规性能修复，只保留行为变更、测试，以及包含计时证据的简短说明。
|
||||
|
||||
对于更深层的 CPU 热点，请使用 Node profiling（`--cpu-prof`）或外部
|
||||
profiler，而不是继续添加更多计时包装。
|
||||
对于更深层的 CPU 热点，请使用 Node 分析（`--cpu-prof`）或外部分析器，而不是添加更多计时包装器。
|
||||
|
||||
## Gateway 网关监视模式
|
||||
## Gateway 网关 watch 模式
|
||||
|
||||
为了快速迭代，可在文件监视器下运行 Gateway 网关：
|
||||
为了快速迭代，在文件 watcher 下运行 Gateway 网关：
|
||||
|
||||
```bash
|
||||
pnpm gateway:watch
|
||||
```
|
||||
|
||||
它映射到：
|
||||
这会映射到：
|
||||
|
||||
```bash
|
||||
node scripts/watch-node.mjs gateway --force
|
||||
```
|
||||
|
||||
当 `src/` 下的构建相关文件、扩展源码文件、
|
||||
扩展 `package.json` 和 `openclaw.plugin.json` 元数据、`tsconfig.json`、
|
||||
`package.json` 以及 `tsdown.config.ts` 发生变化时，监视器会重启
|
||||
gateway。扩展元数据变更会重启 gateway，但不会强制执行 `tsdown` 重建；
|
||||
源码和配置变更仍会先重建 `dist`。
|
||||
该 watcher 会在 `src/` 下与构建相关的文件、插件源文件、插件 `package.json` 和 `openclaw.plugin.json` 元数据、`tsconfig.json`、`package.json` 以及 `tsdown.config.ts` 发生变化时重启。插件元数据变更会重启 Gateway 网关，但不会强制执行 `tsdown` 重新构建；源码和配置变更仍会先重新构建 `dist`。
|
||||
|
||||
在 `gateway:watch` 后追加任何 gateway CLI 标志，
|
||||
这些标志都会在每次重启时透传。现在，对同一仓库/同一标志集重复运行相同的监视命令
|
||||
会替换旧的 watcher，而不是留下重复的 watcher 父进程。
|
||||
在 `gateway:watch` 后添加任何 Gateway 网关 CLI 标志，它们都会在每次重启时透传。现在，对同一仓库/标志组合重新运行相同的 watch 命令时，会替换旧 watcher，而不会留下重复的 watcher 父进程。
|
||||
|
||||
## Dev profile + dev gateway（`--dev`）
|
||||
## 开发配置文件 + 开发 Gateway 网关（--dev）
|
||||
|
||||
使用 dev profile 可以隔离状态，并为调试启动一个安全、可丢弃的环境。
|
||||
这里有**两个** `--dev` 标志：
|
||||
使用开发配置文件来隔离状态，并启动一个安全、可丢弃的设置用于调试。这里有**两个** `--dev` 标志：
|
||||
|
||||
- **全局 `--dev`（profile）**：将状态隔离到 `~/.openclaw-dev` 下，
|
||||
并默认将 gateway 端口设为 `19001`（派生端口也会随之变动）。
|
||||
- **`gateway --dev`**：告诉 Gateway 网关在配置和工作区缺失时自动创建默认配置 +
|
||||
workspace（并跳过 `BOOTSTRAP.md`）。
|
||||
- **全局 `--dev`（profile）：** 将状态隔离到 `~/.openclaw-dev` 下，并将 Gateway 网关端口默认为 `19001`（派生端口随之偏移）。
|
||||
- **`gateway --dev`：告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区**（并跳过 BOOTSTRAP.md）。
|
||||
|
||||
推荐流程（dev profile + dev bootstrap）：
|
||||
推荐流程（开发配置文件 + 开发引导）：
|
||||
|
||||
```bash
|
||||
pnpm gateway:dev
|
||||
@ -226,22 +229,22 @@ OPENCLAW_PROFILE=dev openclaw tui
|
||||
|
||||
如果你还没有全局安装，请通过 `pnpm openclaw ...` 运行 CLI。
|
||||
|
||||
其作用如下：
|
||||
这会执行以下操作：
|
||||
|
||||
1. **Profile 隔离**（全局 `--dev`）
|
||||
1. **配置文件隔离**（全局 `--dev`）
|
||||
- `OPENCLAW_PROFILE=dev`
|
||||
- `OPENCLAW_STATE_DIR=~/.openclaw-dev`
|
||||
- `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
|
||||
- `OPENCLAW_GATEWAY_PORT=19001`（browser/canvas 端口也会相应偏移）
|
||||
- `OPENCLAW_GATEWAY_PORT=19001`（browser/canvas 会相应偏移）
|
||||
|
||||
2. **Dev bootstrap**（`gateway --dev`）
|
||||
- 若配置缺失则写入一个最小配置（`gateway.mode=local`，绑定 loopback）。
|
||||
- 将 `agent.workspace` 设置为 dev workspace。
|
||||
- 设置 `agent.skipBootstrap=true`（不使用 `BOOTSTRAP.md`）。
|
||||
- 若工作区文件缺失则写入初始文件：
|
||||
2. **开发引导**（`gateway --dev`）
|
||||
- 如果缺失，写入最小配置（`gateway.mode=local`，绑定 local loopback）。
|
||||
- 将 `agent.workspace` 设置为开发工作区。
|
||||
- 设置 `agent.skipBootstrap=true`（无 BOOTSTRAP.md）。
|
||||
- 如果缺失，则播种工作区文件：
|
||||
`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`。
|
||||
- 默认身份：**C3‑PO**（protocol droid）。
|
||||
- 在 dev 模式下跳过渠道 provider（`OPENCLAW_SKIP_CHANNELS=1`）。
|
||||
- 默认身份：**C3‑PO**（礼仪机器人）。
|
||||
- 在开发模式中跳过渠道提供商（`OPENCLAW_SKIP_CHANNELS=1`）。
|
||||
|
||||
重置流程（全新开始）：
|
||||
|
||||
@ -250,7 +253,7 @@ pnpm gateway:dev:reset
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--dev` 是一个**全局** profile 标志，会被某些运行器吞掉。如果你需要显式写出它，请使用环境变量形式：
|
||||
`--dev` 是一个**全局**配置文件标志，会被某些运行器吞掉。如果你需要明确写出它，请使用环境变量形式：
|
||||
|
||||
```bash
|
||||
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
|
||||
@ -258,11 +261,10 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
|
||||
|
||||
</Note>
|
||||
|
||||
`--reset` 会清除配置、凭证、会话以及 dev workspace（使用
|
||||
`trash`，而不是 `rm`），然后重新创建默认的 dev 设置。
|
||||
`--reset` 会清除配置、凭证、会话和开发工作区（使用 `trash`，而不是 `rm`），然后重新创建默认开发设置。
|
||||
|
||||
<Tip>
|
||||
如果已有非 dev 的 gateway 正在运行（launchd 或 systemd），请先停止它：
|
||||
如果非开发 Gateway 网关已经在运行（launchd 或 systemd），请先停止它：
|
||||
|
||||
```bash
|
||||
openclaw gateway stop
|
||||
@ -272,9 +274,8 @@ openclaw gateway stop
|
||||
|
||||
## 原始流日志（OpenClaw）
|
||||
|
||||
OpenClaw 可以记录**原始助手流**，即在任何过滤/格式化之前的内容。
|
||||
这是查看推理内容是否以普通文本 delta
|
||||
（或作为独立 thinking block）到达的最佳方式。
|
||||
OpenClaw 可以在任何过滤/格式化之前记录**原始 assistant 流**。
|
||||
这是查看推理是作为纯文本增量到达，还是作为独立 thinking block 到达的最佳方式。
|
||||
|
||||
通过 CLI 启用：
|
||||
|
||||
@ -299,10 +300,9 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
|
||||
|
||||
`~/.openclaw/logs/raw-stream.jsonl`
|
||||
|
||||
## 原始分块日志（pi-mono）
|
||||
## 原始 chunk 日志（pi-mono）
|
||||
|
||||
若要在分块被解析成 block 之前捕获**原始 OpenAI 兼容分块**，
|
||||
pi-mono 提供了单独的记录器：
|
||||
为了在原始 OpenAI 兼容 chunk 被解析为 block 之前捕获它们，pi-mono 提供了单独的日志记录器：
|
||||
|
||||
```bash
|
||||
PI_RAW_STREAM=1
|
||||
@ -318,16 +318,16 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
|
||||
|
||||
`~/.pi-mono/logs/raw-openai-completions.jsonl`
|
||||
|
||||
> 注意：这只会由使用 pi-mono
|
||||
> `openai-completions` provider 的进程输出。
|
||||
> 注意：这只由使用 pi-mono 的
|
||||
> `openai-completions` 提供商的进程发出。
|
||||
|
||||
## 安全说明
|
||||
|
||||
- 原始流日志可能包含完整提示词、工具输出和用户数据。
|
||||
- 请将日志保留在本地，并在调试后删除。
|
||||
- 如果你要共享日志，请先清理密钥和个人敏感信息。
|
||||
- 将日志保留在本地，并在调试后删除它们。
|
||||
- 如果你共享日志，请先清理密钥和 PII。
|
||||
|
||||
## 相关内容
|
||||
## 相关
|
||||
|
||||
- [故障排除](/zh-CN/help/troubleshooting)
|
||||
- [常见问题](/zh-CN/help/faq)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user