chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
af7a72b436
commit
e8da59a875
@ -2,23 +2,23 @@
|
||||
read_when:
|
||||
- 你想以非交互方式读取或编辑配置
|
||||
sidebarTitle: Config
|
||||
summary: 用于 `openclaw config` 的 CLI 参考（get/set/patch/unset/file/schema/validate）
|
||||
summary: '`openclaw config` 的 CLI 参考（get/set/patch/unset/file/schema/validate）'
|
||||
title: 配置
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T21:05:38Z"
|
||||
generated_at: "2026-05-03T17:10:53Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f1f55c4b932d469cb9112d9f55b66f0ff88dbe066250651df7a0a753060a223d
|
||||
source_hash: 7be6a2ff8474fe78deb1d32dd822a4cf8a2b420dfb45306be5d7c5a1d54f0b4d
|
||||
source_path: cli/config.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
配置辅助工具用于在 `openclaw.json` 中进行非交互式编辑：按路径 get/set/patch/unset/file/schema/validate 值，并打印当前活动的配置文件。不带子命令运行会打开配置向导（等同于 `openclaw configure`）。
|
||||
用于对 `openclaw.json` 进行非交互式编辑的配置辅助命令：按路径获取、设置、修补、取消设置、查看文件、查看 schema、验证值，并打印活动配置文件。不带子命令运行时会打开配置向导（等同于 `openclaw configure`）。
|
||||
|
||||
## 根选项
|
||||
|
||||
<ParamField path="--section <section>" type="string">
|
||||
当你不带子命令运行 `openclaw config` 时，可重复使用的引导式设置分区过滤器。
|
||||
当你不带子命令运行 `openclaw config` 时，可重复使用的引导式设置分区筛选器。
|
||||
</ParamField>
|
||||
|
||||
支持的引导式分区：`workspace`、`model`、`web`、`gateway`、`daemon`、`channels`、`plugins`、`skills`、`health`。
|
||||
@ -50,17 +50,17 @@ openclaw config validate --json
|
||||
将为 `openclaw.json` 生成的 JSON schema 以 JSON 形式打印到 stdout。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="What it includes">
|
||||
- 当前根配置 schema，加上用于编辑器工具的根 `$schema` 字符串字段。
|
||||
<Accordion title="包含内容">
|
||||
- 当前根配置 schema，并附带用于编辑器工具的根 `$schema` 字符串字段。
|
||||
- Control UI 使用的字段 `title` 和 `description` 文档元数据。
|
||||
- 当存在匹配的字段文档时，嵌套对象、通配符（`*`）和数组项（`[]`）节点会继承相同的 `title` / `description` 元数据。
|
||||
- 当存在匹配的字段文档时，`anyOf` / `oneOf` / `allOf` 分支也会继承相同的文档元数据。
|
||||
- 当可以加载运行时 manifest 时，尽力提供实时插件 + 渠道 schema 元数据。
|
||||
- 即使当前配置无效，也会提供干净的回退 schema。
|
||||
- 嵌套对象、通配符（`*`）和数组项（`[]`）节点在存在匹配字段文档时，会继承相同的 `title` / `description` 元数据。
|
||||
- `anyOf` / `oneOf` / `allOf` 分支在存在匹配字段文档时，也会继承相同的文档元数据。
|
||||
- 在能够加载运行时清单时，提供尽力而为的实时插件 + 渠道 schema 元数据。
|
||||
- 即使当前配置无效，也会提供一个干净的回退 schema。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Related runtime RPC">
|
||||
`config.schema.lookup` 返回一个规范化配置路径，包含一个浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据，以及直接子项摘要。可在 Control UI 或自定义客户端中用于按路径深入查看。
|
||||
<Accordion title="相关运行时 RPC">
|
||||
`config.schema.lookup` 返回一个规范化配置路径，并带有浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据，以及直接子项摘要。可将它用于 Control UI 或自定义客户端中的按路径钻取。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -68,7 +68,7 @@ openclaw config validate --json
|
||||
openclaw config schema
|
||||
```
|
||||
|
||||
当你想用其他工具检查或验证它时，可以通过管道写入文件：
|
||||
当你想用其他工具检查或验证它时，可以将其管道输出到文件：
|
||||
|
||||
```bash
|
||||
openclaw config schema > openclaw.schema.json
|
||||
@ -76,7 +76,7 @@ openclaw config schema > openclaw.schema.json
|
||||
|
||||
### 路径
|
||||
|
||||
路径使用点号或括号表示法：
|
||||
路径使用点号或方括号表示法：
|
||||
|
||||
```bash
|
||||
openclaw config get agents.defaults.workspace
|
||||
@ -92,7 +92,7 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
|
||||
|
||||
## 值
|
||||
|
||||
值会尽可能按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 要求必须按 JSON5 解析。`--json` 仍作为旧版别名受支持。
|
||||
值会在可能时按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 要求必须按 JSON5 解析。`--json` 仍作为旧版别名受到支持。
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.heartbeat.every "0m"
|
||||
@ -100,10 +100,10 @@ openclaw config set gateway.port 19001 --strict-json
|
||||
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
|
||||
```
|
||||
|
||||
`config get <path> --json` 会将原始值以 JSON 打印，而不是打印终端格式化文本。
|
||||
`config get <path> --json` 会以 JSON 打印原始值，而不是终端格式化文本。
|
||||
|
||||
<Note>
|
||||
默认情况下，对象赋值会替换目标路径。常用于保存用户新增条目的受保护 map/list 路径，例如 `agents.defaults.models`、`models.providers`、`models.providers.<id>.models`、`plugins.entries` 和 `auth.profiles`，会拒绝可能移除现有条目的替换，除非你传入 `--replace`。
|
||||
默认情况下，对象赋值会替换目标路径。常用于保存用户添加条目的受保护映射/列表路径，例如 `agents.defaults.models`、`models.providers`、`models.providers.<id>.models`、`plugins.entries` 和 `auth.profiles`，会拒绝移除现有条目的替换，除非你传入 `--replace`。
|
||||
</Note>
|
||||
|
||||
向这些映射添加条目时使用 `--merge`：
|
||||
@ -113,19 +113,19 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json
|
||||
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge
|
||||
```
|
||||
|
||||
只有当你明确希望提供的值成为完整目标值时，才使用 `--replace`。
|
||||
仅在你有意让提供的值成为完整目标值时，才使用 `--replace`。
|
||||
|
||||
## `config set` 模式
|
||||
|
||||
`openclaw config set` 支持四种赋值方式：
|
||||
`openclaw config set` 支持四种赋值样式：
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Value mode">
|
||||
<Tab title="值模式">
|
||||
```bash
|
||||
openclaw config set <path> <value>
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="SecretRef builder mode">
|
||||
<Tab title="SecretRef 构建器模式">
|
||||
```bash
|
||||
openclaw config set channels.discord.token \
|
||||
--ref-provider default \
|
||||
@ -133,7 +133,7 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll
|
||||
--ref-id DISCORD_BOT_TOKEN
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Provider builder mode">
|
||||
<Tab title="提供商构建器模式">
|
||||
提供商构建器模式仅面向 `secrets.providers.<alias>` 路径：
|
||||
|
||||
```bash
|
||||
@ -146,7 +146,7 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="Batch mode">
|
||||
<Tab title="批处理模式">
|
||||
```bash
|
||||
openclaw config set --batch-json '[
|
||||
{
|
||||
@ -168,28 +168,28 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll
|
||||
</Tabs>
|
||||
|
||||
<Warning>
|
||||
SecretRef 赋值会在不支持运行时可变的表面上被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook 令牌，以及 WhatsApp 凭证 JSON）。参见 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)。
|
||||
SecretRef 赋值会在不支持的运行时可变表面上被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook token，以及 WhatsApp 凭证 JSON）。请参阅 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)。
|
||||
</Warning>
|
||||
|
||||
批量解析始终使用批量载荷（`--batch-json`/`--batch-file`）作为事实来源。`--strict-json` / `--json` 不会改变批量解析行为。
|
||||
批处理解析始终以批处理载荷（`--batch-json`/`--batch-file`）为事实来源。`--strict-json` / `--json` 不会改变批处理解析行为。
|
||||
|
||||
## `config patch`
|
||||
|
||||
当你想粘贴或通过管道传入一个配置形状的补丁，而不是运行许多基于路径的 `config set` 命令时，使用 `config patch`。输入是一个 JSON5 对象。对象会递归合并，数组和标量值会替换目标值，`null` 会删除目标路径。
|
||||
当你想粘贴或管道传入配置形状的补丁，而不是运行许多基于路径的 `config set` 命令时，请使用 `config patch`。输入是一个 JSON5 对象。对象会递归合并，数组和标量值会替换目标值，而 `null` 会删除目标路径。
|
||||
|
||||
```bash
|
||||
openclaw config patch --file ./openclaw.patch.json5 --dry-run
|
||||
openclaw config patch --file ./openclaw.patch.json5
|
||||
```
|
||||
|
||||
你也可以通过 stdin 传入补丁，这对远程设置脚本很有用：
|
||||
你也可以通过 stdin 管道传入补丁，这对远程设置脚本很有用：
|
||||
|
||||
```bash
|
||||
ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
|
||||
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5
|
||||
```
|
||||
|
||||
示例补丁：
|
||||
补丁示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -221,15 +221,15 @@ ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5
|
||||
}
|
||||
```
|
||||
|
||||
当某个对象或数组必须精确变为提供的值，而不是被递归补丁处理时，使用 `--replace-path <path>`：
|
||||
当某个对象或数组必须精确变成提供的值，而不是被递归修补时，使用 `--replace-path <path>`：
|
||||
|
||||
```bash
|
||||
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'
|
||||
```
|
||||
|
||||
`--dry-run` 会在不写入的情况下运行 schema 和 SecretRef 可解析性检查。默认情况下，dry-run 期间会跳过基于 exec 的 SecretRefs；当你明确希望 dry-run 执行提供商命令时，添加 `--allow-exec`。
|
||||
`--dry-run` 会运行 schema 和 SecretRef 可解析性检查，而不写入。默认情况下，dry-run 期间会跳过 exec 支持的 SecretRef；当你有意让 dry-run 执行提供商命令时，添加 `--allow-exec`。
|
||||
|
||||
JSON 路径/值模式仍然同时支持 SecretRefs 和提供商：
|
||||
JSON 路径/值模式仍同时支持 SecretRef 和提供商：
|
||||
|
||||
```bash
|
||||
openclaw config set channels.discord.token \
|
||||
@ -246,24 +246,24 @@ openclaw config set secrets.providers.vaultfile \
|
||||
提供商构建器目标必须使用 `secrets.providers.<alias>` 作为路径。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Common flags">
|
||||
<Accordion title="通用标志">
|
||||
- `--provider-source <env|file|exec>`
|
||||
- `--provider-timeout-ms <ms>`（`file`、`exec`）
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Env provider (--provider-source env)">
|
||||
<Accordion title="Env 提供商（--provider-source env）">
|
||||
- `--provider-allowlist <ENV_VAR>`（可重复）
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="File provider (--provider-source file)">
|
||||
- `--provider-path <path>`（必需）
|
||||
<Accordion title="File 提供商（--provider-source file）">
|
||||
- `--provider-path <path>`（必填）
|
||||
- `--provider-mode <singleValue|json>`
|
||||
- `--provider-max-bytes <bytes>`
|
||||
- `--provider-allow-insecure-path`
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Exec provider (--provider-source exec)">
|
||||
- `--provider-command <path>`（必需）
|
||||
<Accordion title="Exec 提供商（--provider-source exec）">
|
||||
- `--provider-command <path>`（必填）
|
||||
- `--provider-arg <arg>`（可重复）
|
||||
- `--provider-no-output-timeout-ms <ms>`
|
||||
- `--provider-max-output-bytes <bytes>`
|
||||
@ -277,7 +277,7 @@ openclaw config set secrets.providers.vaultfile \
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
加固的 exec 提供商示例：
|
||||
加固后的 exec 提供商示例：
|
||||
|
||||
```bash
|
||||
openclaw config set secrets.providers.vault \
|
||||
@ -293,7 +293,7 @@ openclaw config set secrets.providers.vault \
|
||||
|
||||
## Dry run
|
||||
|
||||
使用 `--dry-run` 在不写入 `openclaw.json` 的情况下验证更改。
|
||||
使用 `--dry-run` 验证更改，而不写入 `openclaw.json`。
|
||||
|
||||
```bash
|
||||
openclaw config set channels.discord.token \
|
||||
@ -318,22 +318,22 @@ openclaw config set channels.discord.token \
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Dry-run behavior">
|
||||
- 构建器模式：对已更改的 refs/providers 运行 SecretRef 可解析性检查。
|
||||
- JSON 模式（`--strict-json`、`--json` 或批量模式）：运行 schema 验证以及 SecretRef 可解析性检查。
|
||||
<Accordion title="Dry-run 行为">
|
||||
- 构建器模式：对已更改的 ref/提供商运行 SecretRef 可解析性检查。
|
||||
- JSON 模式（`--strict-json`、`--json` 或批处理模式）：运行 schema 验证以及 SecretRef 可解析性检查。
|
||||
- 策略验证也会针对已知不支持的 SecretRef 目标表面运行。
|
||||
- 策略检查会评估完整的更改后配置，因此父对象写入（例如将 `hooks` 设置为对象）无法绕过不支持表面的验证。
|
||||
- dry-run 期间默认跳过 exec SecretRef 检查，以避免命令副作用。
|
||||
- 将 `--allow-exec` 与 `--dry-run` 一起使用可选择启用 exec SecretRef 检查（这可能会执行提供商命令）。
|
||||
- `--allow-exec` 仅用于 dry-run；如果不与 `--dry-run` 一起使用会报错。
|
||||
- 策略检查会评估完整的变更后配置，因此父对象写入（例如将 `hooks` 设置为对象）无法绕过不支持表面的验证。
|
||||
- 默认情况下，dry-run 期间会跳过 exec SecretRef 检查，以避免命令副作用。
|
||||
- 将 `--allow-exec` 与 `--dry-run` 搭配使用，以选择启用 exec SecretRef 检查（这可能会执行提供商命令）。
|
||||
- `--allow-exec` 仅适用于 dry-run；如果不带 `--dry-run` 使用会报错。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--dry-run --json fields">
|
||||
`--dry-run --json` 会打印机器可读报告：
|
||||
<Accordion title="--dry-run --json 字段">
|
||||
`--dry-run --json` 会打印一份机器可读报告：
|
||||
|
||||
- `ok`：dry-run 是否通过
|
||||
- `operations`：已评估的赋值数量
|
||||
- `checks`：是否运行了 schema/可解析性检查
|
||||
- `checks`：schema/可解析性检查是否已运行
|
||||
- `checks.resolvabilityComplete`：可解析性检查是否运行完成（跳过 exec refs 时为 false）
|
||||
- `refsChecked`：dry-run 期间实际解析的 refs 数量
|
||||
- `skippedExecRefs`：由于未设置 `--allow-exec` 而跳过的 exec refs 数量
|
||||
@ -413,11 +413,11 @@ openclaw config set channels.discord.token \
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="如果 dry-run 失败">
|
||||
- `config schema validation failed`：变更后的配置结构无效；修正路径/值或提供商/ref 对象结构。
|
||||
- `Config policy validation failed: unsupported SecretRef usage`：将该凭证移回明文/字符串输入，并仅在受支持的表面使用 SecretRefs。
|
||||
- `SecretRef assignment(s) could not be resolved`：当前无法解析引用的提供商/ref（缺少环境变量、文件指针无效、exec 提供商失败，或提供商/来源不匹配）。
|
||||
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`：dry-run 跳过了 exec 引用；如果你需要 exec 可解析性验证，请使用 `--allow-exec` 重新运行。
|
||||
- 对于批处理模式，请修复失败条目，并在写入前重新运行 `--dry-run`。
|
||||
- `config schema validation failed`：你的变更后配置形状无效；请修正路径/值或提供商/ref 对象形状。
|
||||
- `Config policy validation failed: unsupported SecretRef usage`：将该凭证移回明文/字符串输入，并只在受支持的表面使用 SecretRefs。
|
||||
- `SecretRef assignment(s) could not be resolved`：当前无法解析引用的提供商/ref（缺少环境变量、文件指针无效、exec 提供商失败，或提供商/source 不匹配）。
|
||||
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`：dry-run 跳过了 exec refs；如果你需要 exec 可解析性验证，请使用 `--allow-exec` 重新运行。
|
||||
- 对于批处理模式，请修正失败条目，并在写入前重新运行 `--dry-run`。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -430,7 +430,7 @@ openclaw config set channels.discord.token \
|
||||
活动配置路径必须是普通文件。写入不支持符号链接的 `openclaw.json` 布局；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
|
||||
</Warning>
|
||||
|
||||
小幅编辑优先使用 CLI 写入：
|
||||
小改动优先使用 CLI 写入：
|
||||
|
||||
```bash
|
||||
openclaw config set gateway.reload.mode hybrid --dry-run
|
||||
@ -438,7 +438,7 @@ openclaw config set gateway.reload.mode hybrid
|
||||
openclaw config validate
|
||||
```
|
||||
|
||||
如果写入被拒绝，请检查保存的载荷并修复完整配置结构：
|
||||
如果写入被拒绝，请检查保存的载荷并修正完整配置形状：
|
||||
|
||||
```bash
|
||||
CONFIG="$(openclaw config file)"
|
||||
@ -446,9 +446,9 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head
|
||||
openclaw config validate
|
||||
```
|
||||
|
||||
仍然允许直接用编辑器写入，但运行中的 Gateway 网关会在它们通过验证前将其视为不可信。无效的直接编辑可能会在启动或热重载期间从最后已知良好的备份恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
|
||||
仍然允许直接用编辑器写入，但运行中的 Gateway 网关会在它们通过验证之前将其视为不可信。无效的直接编辑会导致启动失败，或被热重载跳过；Gateway 网关不会重写 `openclaw.json`。运行 `openclaw doctor --fix` 来修复带前缀/被覆盖的配置，或恢复最后一次已知可用的副本。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-rejected-invalid-config)。
|
||||
|
||||
整文件恢复仅用于全局损坏的配置，例如解析错误、根级 schema 失败、旧版迁移失败，或插件与根配置同时失败。如果验证仅在 `plugins.entries.<id>...` 下失败，OpenClaw 会保留活动的 `openclaw.json`，并报告插件本地问题，而不是恢复 `.last-good`。这可以防止插件 schema 变更或 `minHostVersion` 偏差回滚无关的用户设置，例如模型、提供商、认证配置文件、渠道、Gateway 网关暴露、工具、内存、浏览器或 cron 配置。
|
||||
整文件恢复仅保留给 Doctor 修复。插件 schema 变更或 `minHostVersion` 偏差会保持显式报错，而不是回滚不相关的用户设置，例如模型、提供商、认证配置文件、渠道、Gateway 网关暴露、工具、记忆、浏览器或 cron 配置。
|
||||
|
||||
## 子命令
|
||||
|
||||
@ -458,14 +458,14 @@ openclaw config validate
|
||||
|
||||
## 验证
|
||||
|
||||
在不启动 Gateway 网关的情况下，根据活动 schema 验证当前配置。
|
||||
在不启动 Gateway 网关的情况下，针对活动 schema 验证当前配置。
|
||||
|
||||
```bash
|
||||
openclaw config validate
|
||||
openclaw config validate --json
|
||||
```
|
||||
|
||||
`openclaw config validate` 通过后，你可以使用本地 TUI，让嵌入式智能体在同一个终端中验证每项变更时，对照文档比较活动配置：
|
||||
`openclaw config validate` 通过后，你可以使用本地 TUI，让嵌入式智能体在你从同一个终端验证每项更改时，将活动配置与文档进行比较：
|
||||
|
||||
<Note>
|
||||
如果验证已经失败，请从 `openclaw configure` 或 `openclaw doctor --fix` 开始。`openclaw chat` 不会绕过无效配置保护。
|
||||
@ -475,7 +475,7 @@ openclaw config validate --json
|
||||
openclaw chat
|
||||
```
|
||||
|
||||
然后在 TUI 中：
|
||||
然后在 TUI 内：
|
||||
|
||||
```text
|
||||
!openclaw config file
|
||||
@ -494,10 +494,10 @@ openclaw chat
|
||||
使用 `openclaw config set` 或 `openclaw configure` 应用定向编辑。
|
||||
</Step>
|
||||
<Step title="重新验证">
|
||||
每次变更后重新运行 `openclaw config validate`。
|
||||
每次更改后重新运行 `openclaw config validate`。
|
||||
</Step>
|
||||
<Step title="针对运行时问题运行 Doctor">
|
||||
如果验证通过但运行时仍不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 获取迁移与修复帮助。
|
||||
<Step title="对运行时问题使用 Doctor">
|
||||
如果验证通过但运行时仍不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 获取迁移和修复帮助。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想安装或管理 Gateway 网关插件或兼容包
|
||||
- 你想调试插件加载失败
|
||||
- 你想安装或管理 Gateway 网关插件或兼容捆绑包
|
||||
- 你想调试插件加载失败问题
|
||||
sidebarTitle: Plugins
|
||||
summary: 适用于 `openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）
|
||||
summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）'
|
||||
title: 插件
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T21:57:47Z"
|
||||
generated_at: "2026-05-03T17:11:00Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 3b077ab0739e2453ccba434aa3b02b1d441bab792b7b131216221a8048d551cd
|
||||
source_hash: f6ae613e39535ea20f9cf3dd451f110ae1b14de4586bdbe3d55d06d8e7cfd2cf
|
||||
source_path: cli/plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
管理 Gateway 网关插件、钩子包和兼容包。
|
||||
管理 Gateway 网关插件、钩子包和兼容捆绑包。
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="插件系统" href="/zh-CN/tools/plugin">
|
||||
@ -23,13 +23,13 @@ x-i18n:
|
||||
<Card title="管理插件" href="/zh-CN/plugins/manage-plugins">
|
||||
安装、列出、更新、卸载和发布的快速示例。
|
||||
</Card>
|
||||
<Card title="插件包" href="/zh-CN/plugins/bundles">
|
||||
包兼容性模型。
|
||||
<Card title="插件捆绑包" href="/zh-CN/plugins/bundles">
|
||||
捆绑包兼容性模型。
|
||||
</Card>
|
||||
<Card title="插件清单" href="/zh-CN/plugins/manifest">
|
||||
清单字段和配置架构。
|
||||
</Card>
|
||||
<Card title="安全" href="/zh-CN/gateway/security">
|
||||
<Card title="安全性" href="/zh-CN/gateway/security">
|
||||
插件安装的安全加固。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@ -62,14 +62,16 @@ openclaw plugins marketplace list <marketplace>
|
||||
openclaw plugins marketplace list <marketplace> --json
|
||||
```
|
||||
|
||||
如需调查安装、检查、卸载或注册表刷新速度慢的问题，请使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行该命令。跟踪会将阶段耗时写入 stderr，并保持 JSON 输出可解析。参见 [调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。
|
||||
如果要排查安装、检查、卸载或注册表刷新缓慢的问题，请使用
|
||||
`OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行该命令。跟踪信息会将阶段耗时写入
|
||||
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`，即使为空）。兼容捆绑包则使用自己的捆绑包清单。
|
||||
|
||||
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表/info 输出还会显示包子类型（`codex`、`claude` 或 `cursor`）以及检测到的包能力。
|
||||
`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表/info 输出还会显示捆绑包子类型（`codex`、`claude` 或 `cursor`）以及检测到的捆绑包能力。
|
||||
</Note>
|
||||
|
||||
### 安装
|
||||
@ -91,100 +93,108 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
|
||||
```
|
||||
|
||||
<Warning>
|
||||
在发布切换期间，裸包名默认从 npm 安装。对 ClawHub 使用 `clawhub:<package>`。请像运行代码一样对待插件安装。优先使用固定版本。
|
||||
在发布切换期间，裸包名默认从 npm 安装。ClawHub 请使用 `clawhub:<package>`。请像运行代码一样对待插件安装。优先使用固定版本。
|
||||
</Warning>
|
||||
|
||||
`plugins search` 会查询 ClawHub 中可安装的插件包，并打印可直接安装的包名。它搜索代码插件和包插件包，而不是 Skills。使用 `openclaw skills search` 搜索 ClawHub Skills。
|
||||
`plugins search` 会查询 ClawHub 中可安装的插件包，并打印
|
||||
可直接用于安装的包名。它会搜索代码插件和捆绑包插件包，
|
||||
不搜索 Skills。对于 ClawHub Skills，请使用 `openclaw skills search`。
|
||||
|
||||
<Note>
|
||||
ClawHub 是大多数插件的主要分发和设备发现界面。Npm 仍是受支持的回退和直接安装路径。OpenClaw 拥有的 `@openclaw/*` 插件包已再次发布到 npm；请在 [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) 或 [插件清单](/zh-CN/plugins/plugin-inventory) 查看当前列表。稳定安装使用 `latest`。Beta 渠道安装和更新会优先使用 npm `beta` dist-tag（如果该标签可用），然后回退到 `latest`。
|
||||
ClawHub 是大多数插件的主要分发和发现入口。Npm
|
||||
仍然是受支持的回退和直接安装路径。OpenClaw 拥有的
|
||||
`@openclaw/*` 插件包已重新发布到 npm；请在
|
||||
[npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) 或
|
||||
[插件清单](/zh-CN/plugins/plugin-inventory)查看当前列表。稳定安装使用 `latest`。
|
||||
Beta 渠道安装和更新在 npm `beta` dist-tag 可用时会优先使用该标签，
|
||||
然后回退到 `latest`。
|
||||
</Note>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="配置 include 和无效配置恢复">
|
||||
如果你的 `plugins` 部分由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该包含文件，并保持 `openclaw.json` 不变。根 include、include 数组以及带有同级覆盖的 include 会失败关闭，而不是被扁平化。有关支持的形状，请参见 [配置 include](/zh-CN/gateway/configuration)。
|
||||
<Accordion title="配置 include 和无效配置修复">
|
||||
如果你的 `plugins` 部分由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该包含文件，并保持 `openclaw.json` 不变。根 include、include 数组以及带有同级覆盖项的 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 以及重新安装与更新">
|
||||
`--force` 会复用现有安装目标，并原地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 构件重新安装同一 id 时使用它。对于已跟踪 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
|
||||
<Accordion title="--force 和重新安装与更新">
|
||||
`--force` 会复用现有安装目标，并就地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 构件重新安装同一 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 范围">
|
||||
`--pin` 仅适用于 npm 安装。它不支持 `git:` 安装；当你想要固定来源时，请使用显式 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它不支持 `--marketplace`，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
|
||||
<Accordion title="--pin 作用域">
|
||||
`--pin` 仅适用于 npm 安装。它不支持 `git:` 安装；如果你想固定来源，请使用显式 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它不支持 `--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 标志适用于插件安装/更新流程。由 Gateway 网关支持的 skill 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是单独的 ClawHub skill 下载/安装流程。
|
||||
此 CLI 标志适用于插件安装/更新流程。由 Gateway 网关支持的 skill 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是单独的 ClawHub skill 下载/安装流程。
|
||||
|
||||
如果你发布到 ClawHub 的插件被注册表扫描阻止，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。
|
||||
如果你在 ClawHub 上发布的插件被注册表扫描阻止，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="钩子包和 npm specs">
|
||||
`plugins install` 也是安装在 `package.json` 中暴露 `openclaw.hooks` 的钩子包的入口。使用 `openclaw hooks` 查看筛选后的钩子可见性并启用单个钩子，而不是安装包。
|
||||
<Accordion title="钩子包和 npm spec">
|
||||
`plugins install` 也是安装钩子包的入口，这些钩子包会在 `package.json` 中暴露 `openclaw.hooks`。请使用 `openclaw hooks` 查看筛选后的钩子可见性并启用单个钩子，而不是用于包安装。
|
||||
|
||||
Npm specs **仅限注册表**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file specs 和 semver 范围会被拒绝。依赖安装以项目本地方式运行，并出于安全原因使用 `--ignore-scripts`，即使你的 shell 配有全局 npm 安装设置也是如此。
|
||||
Npm spec **仅限注册表**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为了安全，即使你的 shell 设置了全局 npm 安装设置，依赖安装也会在项目本地使用 `--ignore-scripts` 运行。
|
||||
|
||||
当你想明确使用 npm 解析时，请使用 `npm:<package>`。在发布切换期间，裸包 specs 也会直接从 npm 安装。
|
||||
当你想明确使用 npm 解析时，请使用 `npm:<package>`。在发布切换期间，裸包 spec 也会直接从 npm 安装。
|
||||
|
||||
裸 specs 和 `@latest` 会保持在稳定轨道上。如果 npm 将其中任一解析为预发布版，OpenClaw 会停止并要求你使用预发布标签（例如 `@beta`/`@rc`）或精确预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。
|
||||
裸 spec 和 `@latest` 会保持在稳定轨道。如果 npm 将其中任何一个解析为预发布版本，OpenClaw 会停止并要求你使用预发布标签（例如 `@beta`/`@rc`）或精确预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。
|
||||
|
||||
如果裸安装 spec 匹配官方插件 id（例如 `diffs`），OpenClaw 会直接安装目录条目。要安装同名 npm 包，请使用显式 scoped spec（例如 `@scope/diffs`）。
|
||||
如果裸安装 spec 匹配官方插件 id（例如 `diffs`），OpenClaw 会直接安装目录条目。若要安装同名 npm 包，请使用显式 scoped spec（例如 `@scope/diffs`）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Git 仓库">
|
||||
使用 `git:<repo>` 直接从 git 仓库安装。支持的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整 `https://`、`ssh://`、`git://`、`file://` 以及 `git@host:owner/repo.git` 克隆 URL。添加 `@<ref>` 或 `#<ref>` 可在安装前检出分支、标签或提交。
|
||||
使用 `git:<repo>` 可直接从 git 仓库安装。支持的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整的 `https://`、`ssh://`、`git://`、`file://` 以及 `git@host:owner/repo.git` 克隆 URL。添加 `@<ref>` 或 `#<ref>` 可在安装前检出分支、标签或提交。
|
||||
|
||||
Git 安装会克隆到临时目录，在存在请求的 ref 时检出它，然后使用正常的插件目录安装器。这意味着清单验证、危险代码扫描、包管理器安装工作和安装记录的行为都类似 npm 安装。记录的 git 安装会包含来源 URL/ref 以及解析后的提交，因此 `openclaw plugins update` 稍后可以重新解析来源。
|
||||
Git 安装会克隆到临时目录，在存在请求的 ref 时检出它，然后使用正常的插件目录安装器。这意味着清单验证、危险代码扫描、包管理器安装工作和安装记录的行为都与 npm 安装类似。记录的 git 安装包含来源 URL/ref 以及解析后的提交，因此 `openclaw plugins update` 以后可以重新解析该来源。
|
||||
|
||||
从 git 安装后，使用 `openclaw plugins inspect <id> --runtime --json` 验证运行时注册项，例如 gateway 方法和 CLI 命令。如果插件使用 `api.registerCli` 注册了 CLI 根命令，请直接通过 OpenClaw 根 CLI 执行该命令，例如 `openclaw demo-plugin ping`。
|
||||
从 git 安装后，请使用 `openclaw plugins inspect <id> --runtime --json` 验证运行时注册项，例如 gateway 方法和 CLI 命令。如果插件使用 `api.registerCli` 注册了 CLI 根命令，请直接通过 OpenClaw 根 CLI 执行该命令，例如 `openclaw demo-plugin ping`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="归档">
|
||||
支持的归档：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw 插件归档必须在解压后的插件根目录包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的归档会在 OpenClaw 写入安装记录前被拒绝。
|
||||
|
||||
Claude marketplace 安装也受支持。
|
||||
也支持 Claude marketplace 安装。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
ClawHub 安装使用显式 `clawhub:<package>` 定位器：
|
||||
ClawHub 安装使用显式 `clawhub:<package>` 定位符：
|
||||
|
||||
```bash
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
|
||||
```
|
||||
|
||||
在发布切换期间，裸 npm 安全插件 specs 默认从 npm 安装：
|
||||
在发布切换期间，裸 npm 安全插件 spec 默认从 npm 安装：
|
||||
|
||||
```bash
|
||||
openclaw plugins install openclaw-codex-app-server
|
||||
```
|
||||
|
||||
使用 `npm:` 明确仅使用 npm 解析：
|
||||
使用 `npm:` 以明确仅使用 npm 解析：
|
||||
|
||||
```bash
|
||||
openclaw plugins install npm:openclaw-codex-app-server
|
||||
openclaw plugins install npm:@scope/plugin-name@1.0.1
|
||||
```
|
||||
|
||||
OpenClaw 会在安装前检查宣告的插件 API / 最低 gateway 兼容性。当选定的 ClawHub 版本发布 ClawPack 构件时，OpenClaw 会下载带版本的 npm-pack `.tgz`，验证 ClawHub 摘要标头和构件摘要，然后通过正常归档路径安装。没有 ClawPack 元数据的较旧 ClawHub 版本仍会通过旧版包归档验证路径安装。记录的安装会保留其 ClawHub 来源元数据、构件类型、npm integrity、npm shasum、tarball 名称和 ClawPack 摘要信息，以便后续更新。
|
||||
未指定版本的 ClawHub 安装会保留未指定版本的记录 spec，因此 `openclaw plugins update` 可以跟随后续 ClawHub 版本；显式版本或标签选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍固定到该选择器。
|
||||
OpenClaw 会在安装前检查声明的插件 API / 最低 gateway 兼容性。当选定的 ClawHub 版本发布了 ClawPack 构件时，OpenClaw 会下载带版本的 npm-pack `.tgz`，验证 ClawHub 摘要标头和构件摘要，然后通过正常归档路径安装它。没有 ClawPack 元数据的旧版 ClawHub 版本仍会通过旧版包归档验证路径安装。记录的安装会保留其 ClawHub 来源元数据、构件类型、npm integrity、npm shasum、tarball 名称和 ClawPack 摘要事实，以供后续更新使用。
|
||||
未指定版本的 ClawHub 安装会保留未指定版本的记录 spec，以便 `openclaw plugins update` 可以跟随后续的 ClawHub 版本；显式版本或标签选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍会固定到该选择器。
|
||||
|
||||
#### Marketplace 简写
|
||||
|
||||
当 marketplace 名称存在于 Claude 位于 `~/.claude/plugins/known_marketplaces.json` 的本地注册表缓存中时，使用 `plugin@marketplace` 简写：
|
||||
当 Claude 的本地注册表缓存在 `~/.claude/plugins/known_marketplaces.json` 中存在 marketplace 名称时，使用 `plugin@marketplace` 简写：
|
||||
|
||||
```bash
|
||||
openclaw plugins marketplace list <marketplace-name>
|
||||
openclaw plugins install <plugin-name>@<marketplace-name>
|
||||
```
|
||||
|
||||
当你想显式传递 marketplace 来源时，使用 `--marketplace`：
|
||||
当你想显式传入 marketplace 来源时，请使用 `--marketplace`：
|
||||
|
||||
```bash
|
||||
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
|
||||
@ -194,31 +204,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 已知 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 加载的远程 marketplace，插件条目必须保留在克隆的 marketplace repo 内。OpenClaw 接受来自该 repo 的相对路径源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 和其他非路径插件源。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
对于本地路径和归档文件，OpenClaw 会自动检测：
|
||||
|
||||
- 原生 OpenClaw 插件（`openclaw.plugin.json`）
|
||||
- 兼容 Codex 的 bundle（`.codex-plugin/plugin.json`）
|
||||
- 兼容 Claude 的 bundle（`.claude-plugin/plugin.json` 或默认 Claude 组件布局）
|
||||
- 兼容 Cursor 的 bundle（`.cursor-plugin/plugin.json`）
|
||||
- Codex 兼容包（`.codex-plugin/plugin.json`）
|
||||
- Claude 兼容包（`.claude-plugin/plugin.json` 或默认 Claude 组件布局）
|
||||
- Cursor 兼容包（`.cursor-plugin/plugin.json`）
|
||||
|
||||
<Note>
|
||||
兼容 bundle 会安装到普通插件根目录，并参与相同的列表/信息/启用/禁用流程。目前支持 bundle Skills、Claude 命令 Skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor 命令 Skills，以及兼容的 Codex hook 目录；其他检测到的 bundle 能力会显示在诊断/信息中，但尚未接入运行时执行。
|
||||
兼容包会安装到常规插件根目录，并参与相同的列表/信息/启用/禁用流程。目前支持包 Skills、Claude 命令 Skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor 命令 Skills，以及兼容的 Codex 钩子目录；其他检测到的包能力会显示在诊断/信息中，但尚未接入运行时执行。
|
||||
</Note>
|
||||
|
||||
### 列出
|
||||
### 列表
|
||||
|
||||
```bash
|
||||
openclaw plugins list
|
||||
@ -234,46 +244,56 @@ openclaw plugins search <query> --json
|
||||
仅显示已启用的插件。
|
||||
</ParamField>
|
||||
<ParamField path="--verbose" type="boolean">
|
||||
从表格视图切换为按插件显示的详情行，包含来源/origin/版本/激活元数据。
|
||||
从表格视图切换为每个插件一行的详细信息，包含源/来源/版本/激活元数据。
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
机器可读的清单，以及注册表诊断和包依赖安装状态。
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
`plugins list` 会先读取持久化的本地插件注册表；当注册表缺失或无效时，会回退到仅从清单派生的结果。它适合用于检查插件是否已安装、已启用，并且对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、hook 策略或 `plugins.load.paths` 后，需要重启为该渠道提供服务的 Gateway 网关，之后新的 `register(api)` 代码或 hook 才会运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不仅是包装器进程。
|
||||
`plugins list` 会先读取持久化的本地插件注册表；当注册表缺失或无效时，会回退到仅由清单派生的结果。它适合用来检查某个插件是否已安装、已启用，并且对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。修改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，请重启服务于该渠道的 Gateway 网关，再预期新的 `register(api)` 代码或钩子会运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不只是包装器进程。
|
||||
|
||||
`plugins list --json` 包含每个插件来自 `package.json`
|
||||
`dependencies` 和 `optionalDependencies` 的 `dependencyStatus`。OpenClaw 会检查这些包名是否存在于插件正常的 Node `node_modules` 查找路径中；它不会导入插件运行时代码、运行包管理器，也不会修复缺失的依赖。
|
||||
`dependencies` 和 `optionalDependencies` 的 `dependencyStatus`。OpenClaw 会检查这些包
|
||||
名称是否存在于插件常规 Node `node_modules` 查找路径上；它
|
||||
不会导入插件运行时代码、运行包管理器，或修复缺失的
|
||||
依赖。
|
||||
</Note>
|
||||
|
||||
`plugins search` 是远程 ClawHub 目录查询。它不会检查本地状态、修改配置、安装包或加载插件运行时代码。搜索结果包含 ClawHub 包名、族、渠道、版本、摘要，以及类似 `openclaw plugins install clawhub:<package>` 的安装提示。
|
||||
`plugins search` 是远程 ClawHub 目录查询。它不会检查本地
|
||||
状态、修改配置、安装包，或加载插件运行时代码。搜索
|
||||
结果包含 ClawHub 包名、系列、渠道、版本、摘要，以及
|
||||
安装提示，例如 `openclaw plugins install clawhub:<package>`。
|
||||
|
||||
在打包的 Docker 镜像内处理内置插件时，将插件源码目录绑定挂载到匹配的打包源码路径上，例如 `/app/extensions/synology-chat`。OpenClaw 会先发现这个已挂载的源码覆盖层，再发现 `/app/dist/extensions/synology-chat`；单纯复制的源码目录保持不生效，因此普通打包安装仍会使用已编译的 dist。
|
||||
在打包 Docker 镜像内处理内置插件时，将插件
|
||||
源目录 bind-mount 到匹配的打包源路径上，例如
|
||||
`/app/extensions/synology-chat`。OpenClaw 会先于 `/app/dist/extensions/synology-chat` 发现该挂载的源
|
||||
覆盖层；普通复制的源
|
||||
目录仍然不会生效，因此常规打包安装仍会使用已编译的 dist。
|
||||
|
||||
对于运行时 hook 调试：
|
||||
用于运行时钩子调试：
|
||||
|
||||
- `openclaw plugins inspect <id> --runtime --json` 会显示一次已加载模块检查过程中注册的 hook 和诊断。运行时检查绝不会安装依赖；请使用 `openclaw doctor --fix` 清理旧版依赖状态，或安装缺失的已配置可下载插件。
|
||||
- `openclaw gateway status --deep --require-rpc` 会确认可达的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态。
|
||||
- 非内置会话 hook（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
|
||||
- `openclaw plugins inspect <id> --runtime --json` 会显示一次模块加载检查过程中注册的钩子和诊断。运行时检查绝不会安装依赖；使用 `openclaw doctor --fix` 清理旧版依赖状态，或安装缺失的已配置可下载插件。
|
||||
- `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`）：
|
||||
使用 `--link` 避免复制本地目录（会添加到 `plugins.load.paths`）：
|
||||
|
||||
```bash
|
||||
openclaw plugins install -l ./my-plugin
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源码路径，而不是覆盖托管安装目标。
|
||||
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制覆盖托管安装目标。
|
||||
|
||||
在 npm 安装中使用 `--pin`，可将解析后的精确 spec（`name@version`）保存到托管插件索引中，同时保持默认行为不固定版本。
|
||||
在 npm 安装中使用 `--pin`，可将解析后的精确规格（`name@version`）保存到托管插件索引中，同时默认行为仍保持不固定。
|
||||
</Note>
|
||||
|
||||
### 插件索引
|
||||
|
||||
插件安装元数据是机器管理的状态，而不是用户配置。安装和更新会把它写入活跃 OpenClaw 状态目录下的 `plugins/installs.json`。其顶层 `installRecords` 映射是安装元数据的持久来源，包括清单损坏或缺失的插件记录。`plugins` 数组是从清单派生的冷注册表缓存。该文件包含请勿编辑警告，并被 `openclaw plugins update`、卸载、诊断和冷插件注册表使用。
|
||||
插件安装元数据是机器管理的状态，不是用户配置。安装和更新会把它写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。它的顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组是由清单派生的冷注册表缓存。该文件包含“请勿编辑”警告，并由 `openclaw plugins update`、卸载、诊断和冷插件注册表使用。
|
||||
|
||||
当 OpenClaw 在配置中看到随版本交付的旧版 `plugins.installs` 记录时，会将它们迁移到插件索引并删除该配置键；如果任一写入失败，则会保留配置记录，以免安装元数据丢失。
|
||||
当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，会将其移动到插件索引并移除该配置键；如果任一写入失败，会保留配置记录，以免安装元数据丢失。
|
||||
|
||||
### 卸载
|
||||
|
||||
@ -283,10 +303,10 @@ openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` 会从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及适用时链接的 `plugins.load.paths` 条目中删除插件记录。除非设置了 `--keep-files`，否则卸载还会删除被跟踪的托管安装目录，前提是它位于 OpenClaw 的插件 extensions 根目录内。对于主动记忆插件，记忆槽位会重置为 `memory-core`。
|
||||
`uninstall` 会在适用时从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及已链接的 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，卸载还会移除被跟踪的托管安装目录，前提是它位于 OpenClaw 的插件扩展根目录内。对于主动记忆插件，记忆插槽会重置为 `memory-core`。
|
||||
|
||||
<Note>
|
||||
`--keep-config` 作为 `--keep-files` 的已弃用别名受支持。
|
||||
`--keep-config` 作为 `--keep-files` 的已弃用别名仍受支持。
|
||||
</Note>
|
||||
|
||||
### 更新
|
||||
@ -299,29 +319,29 @@ openclaw plugins update @openclaw/voice-call
|
||||
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
|
||||
```
|
||||
|
||||
更新会应用到托管插件索引中被跟踪的插件安装，以及 `hooks.internal.installs` 中被跟踪的 hook-pack 安装。
|
||||
更新适用于托管插件索引中被跟踪的插件安装，以及 `hooks.internal.installs` 中被跟踪的 hook-pack 安装。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Resolving plugin id vs npm spec">
|
||||
当你传入插件 ID 时，OpenClaw 会复用该插件记录的安装 spec。这意味着之前存储的 dist-tag（例如 `@beta`）和精确固定版本，会在后续 `update <id>` 运行中继续使用。
|
||||
<Accordion title="解析插件 id 与 npm 规格">
|
||||
当你传入插件 id 时，OpenClaw 会复用该插件记录的安装规格。这意味着先前存储的 dist-tag（例如 `@beta`）和精确固定版本，会在之后的 `update <id>` 运行中继续使用。
|
||||
|
||||
对于 npm 安装，你也可以传入带 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm spec 供未来基于 ID 的更新使用。
|
||||
对于 npm 安装，你也可以传入带 dist-tag 或精确版本的显式 npm 包规格。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格，供后续基于 id 的更新使用。
|
||||
|
||||
传入不带版本或 tag 的 npm 包名也会解析回被跟踪的插件记录。当某个插件固定到了精确版本，而你希望将其移回注册表的默认发布线时，请使用这种方式。
|
||||
传入不带版本或标签的 npm 包名也会解析回被跟踪的插件记录。当某个插件被固定到精确版本，而你想将其移回注册表默认发布线时，请使用这种方式。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Beta channel updates">
|
||||
除非你传入新的 spec，否则 `openclaw plugins update` 会复用被跟踪的插件 spec。`openclaw update` 还知道当前活跃的 OpenClaw 更新渠道：在 beta 渠道上，默认线 npm 和 ClawHub 插件记录会先尝试 `@beta`，如果不存在插件 beta 版本，再回退到记录的 default/latest spec。精确版本和显式 tag 会继续固定到该选择器。
|
||||
<Accordion title="Beta 渠道更新">
|
||||
`openclaw plugins update` 会复用被跟踪的插件规格，除非你传入新规格。`openclaw update` 还知道当前激活的 OpenClaw 更新渠道：在 beta 渠道上，默认线 npm 和 ClawHub 插件记录会先尝试 `@beta`，如果不存在插件 beta 版本，再回退到记录的默认/latest 规格。精确版本和显式标签会保持固定到该选择器。
|
||||
|
||||
</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` 策略阻断或扫描失败阻断，并且只适用于插件更新，不适用于 hook-pack 更新。
|
||||
<Accordion title="更新时使用 --dangerously-force-unsafe-install">
|
||||
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的紧急覆盖。它仍然不会绕过插件 `before_install` 策略阻断或扫描失败阻断，并且只适用于插件更新，不适用于 hook-pack 更新。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -333,21 +353,21 @@ openclaw plugins inspect <id> --runtime
|
||||
openclaw plugins inspect <id> --json
|
||||
```
|
||||
|
||||
默认情况下，Inspect 会显示身份、加载状态、来源、清单能力、策略标志、诊断、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持，而不导入插件运行时。添加 `--runtime` 会加载插件模块，并包含已注册的 hook、工具、命令、服务、gateway 方法和 HTTP 路由。运行时检查会直接报告缺失的插件依赖；安装和修复仍由 `openclaw plugins install`、`openclaw plugins update` 和 `openclaw doctor --fix` 处理。
|
||||
默认情况下，检查会在不导入插件运行时的情况下，显示身份、加载状态、来源、清单能力、策略标志、诊断、安装元数据、包能力，以及任何检测到的 MCP 或 LSP 服务器支持。添加 `--runtime` 会加载插件模块，并包含已注册的钩子、工具、命令、服务、gateway 方法和 HTTP 路由。运行时检查会直接报告缺失的插件依赖；安装和修复仍在 `openclaw plugins install`、`openclaw plugins update` 和 `openclaw doctor --fix` 中处理。
|
||||
|
||||
插件拥有的 CLI 命令会作为根 `openclaw` 命令组安装。`inspect --runtime` 在 `cliCommands` 下显示命令后，将其作为 `openclaw <command> ...` 运行；例如，注册了 `demo-git` 的插件可以用 `openclaw demo-git ping` 验证。
|
||||
插件自有 CLI 命令会作为根 `openclaw` 命令组安装。`inspect --runtime` 在 `cliCommands` 下显示命令后，请以 `openclaw <command> ...` 形式运行；例如，注册 `demo-git` 的插件可以用 `openclaw demo-git ping` 验证。
|
||||
|
||||
每个插件会根据其在运行时实际注册的内容分类：
|
||||
每个插件都会根据其在运行时实际注册的内容分类：
|
||||
|
||||
- **plain-capability** — 一种能力类型（例如仅提供商插件）
|
||||
- **plain-capability** — 一种能力类型（例如仅 provider 的插件）
|
||||
- **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像）
|
||||
- **hook-only** — 只有 hook，没有能力或表面
|
||||
- **hook-only** — 只有钩子，没有能力或 surface
|
||||
- **non-capability** — 有工具/命令/服务，但没有能力
|
||||
|
||||
关于能力模型的更多信息，请参阅 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
|
||||
有关能力模型的更多信息，请参见 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
|
||||
|
||||
<Note>
|
||||
`--json` 标志会输出适合脚本处理和审计的机器可读报告。`inspect --all` 会呈现全局表格，包含形态、能力种类、兼容性提示、bundle 能力和 hook 摘要列。`info` 是 `inspect` 的别名。
|
||||
`--json` 标志会输出适合脚本和审计的机器可读报告。`inspect --all` 会渲染一个全量表格，包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。
|
||||
</Note>
|
||||
|
||||
### Doctor
|
||||
@ -356,9 +376,9 @@ openclaw plugins inspect <id> --json
|
||||
openclaw plugins doctor
|
||||
```
|
||||
|
||||
`doctor` 会报告插件加载错误、清单/发现诊断和兼容性提示。当一切正常时，它会打印 `No plugin issues detected.`
|
||||
`doctor` 会报告插件加载错误、清单/发现诊断，以及兼容性通知。当一切正常时，它会打印 `No plugin issues detected.`
|
||||
|
||||
对于缺少 `register`/`activate` 导出等模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。
|
||||
对于缺失 `register`/`activate` 导出等模块形态失败，请用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以便在诊断输出中包含紧凑的导出形态摘要。
|
||||
|
||||
### 注册表
|
||||
|
||||
@ -368,22 +388,22 @@ openclaw plugins registry --refresh
|
||||
openclaw plugins registry --json
|
||||
```
|
||||
|
||||
本地插件注册表是 OpenClaw 对已安装插件身份、启用状态、来源元数据和贡献归属的持久化冷读模型。普通启动、提供商 owner 查找、渠道设置分类和插件清单可以读取它，而无需导入插件运行时模块。
|
||||
本地插件注册表是 OpenClaw 为已安装插件身份、启用状态、来源元数据和贡献归属持久化的冷读模型。常规启动、提供商所有者查找、渠道设置分类和插件清单都可以读取它，而无需导入插件运行时模块。
|
||||
|
||||
使用 `plugins registry` 检查持久化注册表是否存在、是否当前有效或是否陈旧。使用 `--refresh` 可基于持久化插件索引、配置策略和清单/包元数据重建它。这是修复路径，不是运行时激活路径。
|
||||
使用 `plugins registry` 检查持久化注册表是否存在、是否当前有效或是否过期。使用 `--refresh` 可根据持久化插件索引、配置策略和清单/包元数据重建它。这是修复路径，不是运行时激活路径。
|
||||
|
||||
<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>
|
||||
|
||||
### 市场
|
||||
### 插件市场
|
||||
|
||||
```bash
|
||||
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` 会打印解析后的来源标签，以及解析后的市场清单和插件条目。
|
||||
|
||||
## 相关内容
|
||||
|
||||
|
||||
@ -1,65 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- 针对 OpenClaw 缺陷构建或运行实时视觉 QA
|
||||
- 为 OpenClaw 缺陷构建或运行实时视觉质量检查
|
||||
- 为拉取请求添加前后验证
|
||||
- 添加 Discord、Slack、WhatsApp 或其他实时传输场景
|
||||
- 调试需要截图、浏览器自动化或 VNC 访问的 QA 运行
|
||||
summary: Mantis 是用于在实时传输协议上复现 OpenClaw 缺陷、捕获前后证据，并将工件附加到拉取请求的可视化端到端验证系统。
|
||||
summary: Mantis 是一个可视化端到端验证系统，用于在实时传输通道上复现 OpenClaw 缺陷、捕获修复前后的证据，并将工件附加到拉取请求中。
|
||||
title: Mantis
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T16:48:53Z"
|
||||
generated_at: "2026-05-03T17:11:15Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5b58934ec88a640745f7430c875c377e898f87f1b3d4a9ef03115395084664f5
|
||||
source_hash: 2a038872d2754b380a0983d81869de247d66c41b49746e1608dca215ab2096a7
|
||||
source_path: concepts/mantis.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Mantis 是 OpenClaw 的端到端验证系统，适用于需要真实运行时、真实传输协议和可见证明的缺陷。它会针对已知有问题的 ref 运行一个场景并捕获证据，再针对候选 ref 运行相同场景，然后将对比结果发布为构件，维护者可以从 PR 或本地命令中检查这些构件。
|
||||
Mantis 是 OpenClaw 端到端验证系统，用于需要真实运行时、真实传输协议和可见证据的 bug。它会在一个已知有问题的 ref 上运行场景，捕获证据，再在候选 ref 上运行同一场景，并将对比结果发布为构件，维护者可以从 PR 或本地命令中检查这些构件。
|
||||
|
||||
Mantis 从 Discord 开始，因为 Discord 为我们提供了一条高价值的首个通道：真实机器人凭证、真实公会渠道、回应、线程、原生命令，以及人类可以直观确认传输协议展示内容的浏览器 UI。
|
||||
Mantis 从 Discord 开始，因为 Discord 为我们提供了一条高价值的第一条验证通道：真实 bot 凭证、真实 guild 渠道、回应、线程、原生命令，以及一个浏览器 UI，便于人工直观看到传输协议展示的内容。
|
||||
|
||||
## 目标
|
||||
|
||||
- 使用用户看到的相同传输形态，从 GitHub 问题或 PR 中复现缺陷。
|
||||
- 在应用修复之前，在基线 ref 上捕获一个 **before** 构件。
|
||||
- 在应用修复之后，在候选 ref 上捕获一个 **after** 构件。
|
||||
- 尽可能使用确定性的判定器，例如 Discord REST 回应读取或渠道转录检查。
|
||||
- 当缺陷有可见 UI 表面时捕获截图。
|
||||
- 使用用户看到的同一种传输协议形态，从 GitHub issue 或 PR 中复现 bug。
|
||||
- 在应用修复前，在基线 ref 上捕获一个 **before** 构件。
|
||||
- 在应用修复后，在候选 ref 上捕获一个 **after** 构件。
|
||||
- 尽可能使用确定性的判定器，例如 Discord REST 反应读取或渠道转录检查。
|
||||
- 当 bug 有可见 UI 表面时捕获截图。
|
||||
- 从智能体控制的 CLI 在本地运行，并从 GitHub 远程运行。
|
||||
- 当登录、浏览器自动化或提供商凭证卡住时，保留足够的机器状态以便 VNC 救援。
|
||||
- 当运行被阻塞、需要手动 VNC 帮助或完成时，向操作员 Discord 渠道发布简洁状态。
|
||||
- 当登录、浏览器自动化或提供商凭证卡住时，保留足够的机器状态用于 VNC 救援。
|
||||
- 当运行被阻塞、需要手动 VNC 协助或完成时，向操作员 Discord 渠道发布简短状态。
|
||||
|
||||
## 非目标
|
||||
|
||||
- Mantis 不是单元测试的替代品。理解修复后，Mantis 运行通常应该转化为更小的回归测试。
|
||||
- Mantis 不是常规的快速 CI 门禁。它更慢、使用实时凭证，并且只保留给实时环境重要的缺陷。
|
||||
- Mantis 的正常运行不应该需要人类介入。手动 VNC 是救援路径，不是理想路径。
|
||||
- Mantis 不是单元测试的替代品。理解修复后，Mantis 运行通常应转化为更小的回归测试。
|
||||
- Mantis 不是常规的快速 CI 门禁。它更慢，使用实时凭证，并且只用于实时环境很重要的 bug。
|
||||
- Mantis 不应在正常运行中需要人工介入。手动 VNC 是救援路径，而不是理想路径。
|
||||
- Mantis 不会在构件、日志、截图、Markdown 报告或 PR 评论中存储原始密钥。
|
||||
|
||||
## 所有权
|
||||
## 归属
|
||||
|
||||
Mantis 位于 OpenClaw QA 栈中。
|
||||
|
||||
- OpenClaw 拥有场景运行时、传输协议适配器、证据 schema，以及 `pnpm openclaw qa mantis` 下的本地 CLI。
|
||||
- QA Lab 拥有实时传输协议 harness 组件、浏览器捕获辅助工具和构件写入器。
|
||||
- OpenClaw 拥有 `pnpm openclaw qa mantis` 下的场景运行时、传输协议适配器、证据 schema 和本地 CLI。
|
||||
- QA Lab 拥有实时传输协议 harness 组件、浏览器捕获助手和构件写入器。
|
||||
- 需要远程 VM 时，Crabbox 拥有预热的 Linux 机器。
|
||||
- GitHub Actions 拥有远程工作流入口点和构件保留。
|
||||
- ClawSweeper 拥有 GitHub 评论路由：解析维护者命令、调度工作流，以及发布最终 PR 评论。
|
||||
- ClawSweeper 拥有 GitHub 评论路由：解析维护者命令、分派工作流并发布最终 PR 评论。
|
||||
- 当场景需要智能体式设置、调试或卡住状态报告时，OpenClaw 智能体通过 Codex 驱动 Mantis。
|
||||
|
||||
这个边界将传输协议知识保留在 OpenClaw 中，将机器调度保留在 Crabbox 中，并将维护者工作流粘合逻辑保留在 ClawSweeper 中。
|
||||
这个边界将传输协议知识保留在 OpenClaw 中，将机器调度保留在 Crabbox 中，并将维护者工作流胶水保留在 ClawSweeper 中。
|
||||
|
||||
## 命令形态
|
||||
## 命令形式
|
||||
|
||||
第一个本地命令会验证 Discord 机器人、公会、渠道、消息发送、回应发送和构件路径：
|
||||
第一个本地命令会验证 Discord bot、guild、渠道、消息发送、反应发送和构件路径：
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis discord-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-smoke
|
||||
```
|
||||
|
||||
后续的前后对比运行器应该接受这种形态：
|
||||
后续 before 和 after 运行器应接受这种形式：
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis run \
|
||||
@ -70,12 +70,12 @@ pnpm openclaw qa mantis run \
|
||||
--output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions
|
||||
```
|
||||
|
||||
GitHub 冒烟工作流是 `Mantis Discord Smoke`。第一个真实场景的前后对比 GitHub 工作流是 `Mantis Discord Status Reactions`。它接受：
|
||||
GitHub smoke 工作流是 `Mantis Discord Smoke`。第一个真实场景的 before 和 after GitHub 工作流是 `Mantis Discord Status Reactions`。它接受：
|
||||
|
||||
- `baseline_ref`：预期会复现仅 queued 行为的 ref。
|
||||
- `candidate_ref`：预期会显示 `queued -> thinking -> done` 的 ref。
|
||||
|
||||
它会检出工作流 harness ref，构建独立的基线和候选 worktree，分别针对每个 worktree 运行 `discord-status-reactions-tool-only`，并将 `baseline/`、`candidate/`、`comparison.json` 和 `mantis-report.md` 作为 Actions 构件上传。
|
||||
它会检出工作流 harness ref，构建独立的基线和候选工作树，分别对每个工作树运行 `discord-status-reactions-tool-only`，并将 `baseline/`、`candidate/`、`comparison.json` 和 `mantis-report.md` 作为 Actions 构件上传。
|
||||
|
||||
ClawSweeper 命令示例：
|
||||
|
||||
@ -84,42 +84,42 @@ ClawSweeper 命令示例：
|
||||
@clawsweeper verify e2e discord
|
||||
```
|
||||
|
||||
第一个命令明确且聚焦于场景。第二个命令之后可以根据标签、变更文件和 ClawSweeper 审查发现，将 PR 或问题映射到推荐的 Mantis 场景。
|
||||
第一个命令是显式且聚焦场景的。第二个命令后续可以根据标签、变更文件和 ClawSweeper 评审发现，将 PR 或 issue 映射到推荐的 Mantis 场景。
|
||||
|
||||
## 运行生命周期
|
||||
|
||||
1. 获取凭证。
|
||||
2. 分配或复用 VM。
|
||||
3. 为基线 ref 准备一个干净检出。
|
||||
4. 安装依赖，并只构建场景需要的内容。
|
||||
5. 使用隔离的状态目录启动一个子 OpenClaw Gateway 网关。
|
||||
3. 为基线 ref 准备干净的检出。
|
||||
4. 安装依赖，并且只构建场景所需内容。
|
||||
5. 使用隔离状态目录启动子 OpenClaw Gateway 网关。
|
||||
6. 配置实时传输协议、提供商、模型和浏览器配置文件。
|
||||
7. 运行场景并捕获基线证据。
|
||||
8. 停止 Gateway 网关并保留日志。
|
||||
9. 在同一个 VM 中准备候选 ref。
|
||||
10. 运行相同场景并捕获候选证据。
|
||||
9. 在同一 VM 中准备候选 ref。
|
||||
10. 运行同一场景并捕获候选证据。
|
||||
11. 比较判定器结果和视觉证据。
|
||||
12. 写入 Markdown、JSON、日志、截图和可选 trace 构件。
|
||||
13. 上传 GitHub Actions 构件。
|
||||
14. 发布简洁的 PR 或 Discord 状态消息。
|
||||
14. 发布简短的 PR 或 Discord 状态消息。
|
||||
|
||||
场景应该能够以两种不同方式失败：
|
||||
场景应能以两种不同方式失败：
|
||||
|
||||
- **已复现缺陷**：基线以预期方式失败。
|
||||
- **Harness 失败**：环境设置、凭证、Discord API、浏览器或提供商在缺陷判定器有意义之前失败。
|
||||
- **已复现 bug**：基线以预期方式失败。
|
||||
- **Harness 失败**：环境设置、凭证、Discord API、浏览器或提供商在 bug 判定器有意义前失败。
|
||||
|
||||
最终报告必须区分这些情况，确保维护者不会把不稳定的环境与产品行为混淆。
|
||||
最终报告必须区分这些情况，这样维护者不会把不稳定环境与产品行为混淆。
|
||||
|
||||
## Discord MVP
|
||||
|
||||
第一个场景应该针对公会渠道中的 Discord 状态回应，其中源回复投递模式为 `message_tool_only`。
|
||||
第一个场景应针对 guild 渠道中的 Discord 状态反应，其中源回复投递模式为 `message_tool_only`。
|
||||
|
||||
它适合作为 Mantis 起点的原因：
|
||||
它是一个好的 Mantis 种子，原因如下：
|
||||
|
||||
- 它在 Discord 中表现为触发消息上的回应，具有可见性。
|
||||
- 它通过 Discord 消息回应状态提供强 REST 判定器。
|
||||
- 它会覆盖真实的 OpenClaw Gateway 网关、Discord 机器人凭证、消息分发、源回复投递模式、状态回应状态和模型轮次生命周期。
|
||||
- 它足够窄，可以让第一个实现保持诚实。
|
||||
- 它在 Discord 中以触发消息上的反应形式可见。
|
||||
- 它通过 Discord 消息反应状态提供强 REST 判定器。
|
||||
- 它会覆盖真实的 OpenClaw Gateway 网关、Discord bot 凭证、消息分派、源回复投递模式、状态反应状态和模型轮次生命周期。
|
||||
- 它足够窄，能让第一个实现保持可靠。
|
||||
|
||||
预期场景形态：
|
||||
|
||||
@ -152,9 +152,9 @@ evidence:
|
||||
screenshotMessageRow: true
|
||||
```
|
||||
|
||||
基线证据应该显示 queued 确认回应，但在仅工具模式下没有生命周期转换。候选证据应该显示当 `messages.statusReactions.enabled` 被显式设为 true 时，生命周期状态回应会运行。
|
||||
基线证据应显示 queued 确认反应，但在 tool-only 模式下没有生命周期转换。候选证据应显示当 `messages.statusReactions.enabled` 显式为 true 时，生命周期状态反应会运行。
|
||||
|
||||
可执行的第一个切片是选择启用的 Discord 实时 QA 场景：
|
||||
第一个可执行切片是可选启用的 Discord 实时 QA 场景：
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa discord \
|
||||
@ -166,20 +166,19 @@ pnpm openclaw qa discord \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate
|
||||
```
|
||||
|
||||
它会为 SUT 配置始终开启的公会处理、`visibleReplies:
|
||||
"message_tool"`、`ackReaction: "👀"` 和显式状态回应。判定器会轮询真实的 Discord 触发消息，并预期观察到序列 `👀 -> 🤔 -> 👍`。构件包括 `discord-qa-reaction-timelines.json`、`discord-status-reactions-tool-only-timeline.html` 和 `discord-status-reactions-tool-only-timeline.png`。
|
||||
它会为 SUT 配置始终开启的 guild 处理、`visibleReplies: "message_tool"`、`ackReaction: "👀"` 和显式状态反应。判定器会轮询真实的 Discord 触发消息，并预期观察到序列 `👀 -> 🤔 -> 👍`。构件包括 `discord-qa-reaction-timelines.json`、`discord-status-reactions-tool-only-timeline.html` 和 `discord-status-reactions-tool-only-timeline.png`。
|
||||
|
||||
## 现有 QA 组件
|
||||
|
||||
Mantis 应该构建在现有私有 QA 栈之上，而不是从零开始：
|
||||
Mantis 应基于现有的私有 QA 栈构建，而不是从零开始：
|
||||
|
||||
- `pnpm openclaw qa discord` 已经运行一条带 driver 和 SUT 机器人的实时 Discord 通道。
|
||||
- 实时传输协议运行器已经在 `.artifacts/qa-e2e/` 下写入报告和观测消息构件。
|
||||
- `pnpm openclaw qa discord` 已经运行带 driver 和 SUT bot 的实时 Discord 通道。
|
||||
- 实时传输协议运行器已经会在 `.artifacts/qa-e2e/` 下写入报告和已观察消息构件。
|
||||
- Convex 凭证租约已经提供对共享实时传输协议凭证的独占访问。
|
||||
- 浏览器控制服务已经支持截图、快照、无头托管配置文件和远程 CDP 配置文件。
|
||||
- QA Lab 已经拥有用于传输协议形态测试的调试器 UI 和总线。
|
||||
- QA Lab 已经有用于传输协议形态测试的调试器 UI 和总线。
|
||||
|
||||
第一个 Mantis 实现可以是在这些组件之上的一层很薄的前后对比运行器，再加上一层视觉证据。
|
||||
第一个 Mantis 实现可以是在这些组件之上构建的轻量 before/after 运行器，再加上一层视觉证据。
|
||||
|
||||
## 证据模型
|
||||
|
||||
@ -203,65 +202,65 @@ Mantis 应该构建在现有私有 QA 栈之上，而不是从零开始：
|
||||
run.log
|
||||
```
|
||||
|
||||
`mantis-summary.json` 应该是机器可读的事实来源。Markdown 报告用于 PR 评论和人工审查。
|
||||
`mantis-summary.json` 应是机器可读的事实来源。Markdown 报告用于 PR 评论和人工评审。
|
||||
|
||||
摘要必须包括：
|
||||
摘要必须包含：
|
||||
|
||||
- 测试的 ref 和 SHA
|
||||
- 传输协议和场景 ID
|
||||
- 机器提供商以及机器 ID 或租约 ID
|
||||
- 已测试的 refs 和 SHA
|
||||
- 传输协议和场景 id
|
||||
- 机器提供商以及机器 id 或租约 id
|
||||
- 不含密钥值的凭证来源
|
||||
- 基线结果
|
||||
- 候选结果
|
||||
- 缺陷是否在基线上复现
|
||||
- bug 是否在基线上复现
|
||||
- 候选是否修复了它
|
||||
- 构件路径
|
||||
- 已清理的设置或清理问题
|
||||
|
||||
截图是证据，不是密钥。它们仍然需要遵守脱敏纪律：私有渠道名称、用户名或消息内容可能会出现。对于公开 PR，在脱敏方案更成熟之前，优先使用 GitHub Actions 构件链接，而不是内联图片。
|
||||
截图是证据，不是密钥。它们仍然需要遵守脱敏纪律：私有渠道名称、用户名或消息内容可能会出现。对于公开 PR，在脱敏方案更完善之前，优先使用 GitHub Actions 构件链接，而不是内联图片。
|
||||
|
||||
## 浏览器和 VNC
|
||||
|
||||
浏览器通道有两种模式：
|
||||
|
||||
- **无头自动化**：CI 的默认模式。Chrome 启用 CDP 运行，Playwright 或 OpenClaw 浏览器控制会捕获截图。
|
||||
- **VNC 救援**：当登录、MFA、Discord 反自动化或视觉调试需要人类介入时，在同一个 VM 上启用。
|
||||
- **VNC 救援**：当登录、MFA、Discord 反自动化或视觉调试需要人工时，在同一 VM 上启用。
|
||||
|
||||
Discord 观察者浏览器配置文件应该足够持久，以避免每次运行都登录，但要与个人浏览器状态隔离。配置文件属于 Mantis 机器池，而不是开发者笔记本电脑。
|
||||
Discord 观察者浏览器配置文件应足够持久，避免每次运行都登录，但要与个人浏览器状态隔离。配置文件属于 Mantis 机器池，而不是开发者笔记本电脑。
|
||||
|
||||
当 Mantis 卡住时，它会发布一条 Discord 状态消息，其中包含：
|
||||
当 Mantis 卡住时，它会发布一条 Discord 状态消息，包含：
|
||||
|
||||
- 运行 ID
|
||||
- 场景 ID
|
||||
- 运行 id
|
||||
- 场景 id
|
||||
- 机器提供商
|
||||
- 构件目录
|
||||
- VNC 或 noVNC 连接说明（如果可用）
|
||||
- 简短阻塞原因文本
|
||||
- 简短阻塞说明
|
||||
|
||||
第一个私有部署可以将这些消息发布到现有操作员渠道，之后再迁移到专用 Mantis 渠道。
|
||||
|
||||
## 机器
|
||||
|
||||
第一个远程实现中，Mantis 应优先通过 Crabbox 使用 AWS。Crabbox 为我们提供预热机器、租约跟踪、环境补水、日志、结果和清理。如果 AWS 容量太慢或不可用，就在相同机器接口后添加 Hetzner 提供商。
|
||||
第一个远程实现中，Mantis 应优先通过 Crabbox 使用 AWS。Crabbox 提供预热机器、租约跟踪、hydration、日志、结果和清理。如果 AWS 容量太慢或不可用，则在同一机器接口后添加 Hetzner 提供商。
|
||||
|
||||
最低 VM 要求：
|
||||
|
||||
- Linux，安装了具备桌面能力的 Chrome 或 Chromium
|
||||
- Linux，安装可用于桌面的 Chrome 或 Chromium
|
||||
- 用于浏览器自动化的 CDP 访问
|
||||
- 用于救援的 VNC 或 noVNC
|
||||
- Node 22 和 pnpm
|
||||
- OpenClaw 检出和依赖缓存
|
||||
- 使用 Playwright 时的 Playwright Chromium 浏览器缓存
|
||||
- 足够运行一个 OpenClaw Gateway 网关、一个浏览器和一次模型运行的 CPU 与内存
|
||||
- 对 Discord、GitHub、模型提供商和凭证代理的出站访问
|
||||
- 对 Discord、GitHub、模型提供商和凭证 broker 的出站访问
|
||||
|
||||
VM 不应在预期凭证或浏览器配置文件存储之外保留长期存在的原始密钥。
|
||||
VM 不应在预期的凭证或浏览器配置文件存储之外保留长期存在的原始密钥。
|
||||
|
||||
## 密钥
|
||||
|
||||
远程运行的密钥位于 GitHub 组织或仓库密钥中，本地运行的密钥位于本地操作员控制的密钥文件中。
|
||||
远程运行的密钥存放在 GitHub 组织或仓库密钥中，本地运行的密钥存放在本地操作员控制的密钥文件中。
|
||||
|
||||
推荐的密钥名称：
|
||||
推荐密钥名称：
|
||||
|
||||
- `OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
|
||||
@ -269,30 +268,32 @@ VM 不应在预期凭证或浏览器配置文件存储之外保留长期存在
|
||||
- `OPENCLAW_QA_DISCORD_GUILD_ID`
|
||||
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`，用于公开 GitHub 构件上传
|
||||
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` 用于公开 GitHub 构件上传
|
||||
- `OPENCLAW_QA_CONVEX_SITE_URL`
|
||||
- `OPENCLAW_QA_CONVEX_SECRET_CI`
|
||||
|
||||
长期来看，Convex 凭证池应继续作为实时传输协议凭证的常规来源。GitHub 密钥用于引导代理和回退通道。
|
||||
长期来看，Convex 凭证池应继续作为实时传输协议凭证的常规来源。GitHub 密钥用于引导 broker 和后备通道。
|
||||
|
||||
Mantis 运行器绝不能打印：
|
||||
|
||||
- Discord 机器人 token
|
||||
- Discord bot token
|
||||
- 提供商 API key
|
||||
- 浏览器 cookie
|
||||
- 凭证配置文件内容
|
||||
- VNC 密码
|
||||
- 原始凭证载荷
|
||||
- 原始凭证 payload
|
||||
|
||||
公开构件上传还应脱敏 Discord 目标元数据，例如机器人、公会、渠道和消息 ID。GitHub 冒烟工作流因此启用了 `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`。
|
||||
公开构件上传还应脱敏 Discord 目标元数据，例如 bot、guild、渠道和消息 id。GitHub smoke 工作流因此启用了 `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`。
|
||||
|
||||
如果 token 被意外粘贴到问题、PR、聊天或日志中，请在新密钥存储后轮换它。
|
||||
如果 token 被意外粘贴到 issue、PR、聊天或日志中，请在存储新密钥后轮换它。
|
||||
|
||||
## GitHub 构件和 PR 评论
|
||||
|
||||
Mantis 工作流应将完整证据包作为短期 Actions 工件上传。当工作流针对错误报告或修复 PR 运行时，它还应将已脱敏的 PNG 截图发布到 `qa-artifacts` 分支，并在该错误或修复 PR 上插入或更新一条评论，内联展示修复前/修复后的截图。不要只把主要证明发布在通用 QA 自动化 PR 上。原始日志、观测到的消息和其他体量较大的证据保留在 Actions 工件中。
|
||||
Mantis 工作流应将完整证据包上传为短期 Actions 工件。当工作流针对错误报告或修复 PR 运行时，它还应将已脱敏的 PNG 截图发布到 `qa-artifacts` 分支，并在该错误或修复 PR 上更新或插入一条评论，内联展示修复前/后的截图。不要只把主要证明发布到通用 QA 自动化 PR 上。原始日志、观测到的消息以及其他体积较大的证据应保留在 Actions 工件中。
|
||||
|
||||
PR 评论应简短且偏视觉化：
|
||||
生产工作流应使用 Mantis GitHub App 发布这些评论，而不是使用 `github-actions[bot]`。将应用 id 和私钥存储为 `MANTIS_GITHUB_APP_ID` 和 `MANTIS_GITHUB_APP_PRIVATE_KEY` GitHub Actions 密钥。如果缺少这些密钥，工作流可以在本地启动阶段回退到 `github-actions[bot]`，但这不是期望的长期身份。
|
||||
|
||||
PR 评论应简短且以视觉为主：
|
||||
|
||||
```md
|
||||
Mantis Discord Status Reactions QA
|
||||
@ -312,60 +313,60 @@ candidate showed the expected queued -> thinking -> done sequence.
|
||||
| <inline screenshot> | <inline screenshot> |
|
||||
```
|
||||
|
||||
当运行失败是因为 harness 失败时，评论必须说明这一点，而不是暗示候选修复失败。
|
||||
当运行因 harness 失败而失败时，评论必须说明这一点，而不是暗示候选修复失败。
|
||||
|
||||
## 私有部署说明
|
||||
|
||||
私有部署可能已经有一个 Mantis Discord 应用。当该应用具备正确的机器人权限并且可以安全轮换时，复用该应用，而不是再创建一个应用。
|
||||
私有部署可能已经有一个 Mantis Discord 应用。如果该应用具备正确的 bot 权限并且可以安全轮换，请复用该应用，而不是再创建一个应用。
|
||||
|
||||
通过密钥或部署配置设置初始操作员通知渠道。它可以先指向现有的维护者或运维渠道，然后在专用 Mantis 渠道存在后再迁移过去。
|
||||
通过密钥或部署配置设置初始操作员通知渠道。它可以先指向现有维护者或运维渠道，等专用 Mantis 渠道存在后再迁移过去。
|
||||
|
||||
不要将服务器 ID、渠道 ID、机器人令牌、浏览器 Cookie 或 VNC 密码放入本文档。请将它们存储在 GitHub 密钥、凭证代理或操作员的本地密钥存储中。
|
||||
不要把 guild id、channel id、bot token、浏览器 cookie 或 VNC 密码放入本文档。将它们存储在 GitHub 密钥、凭证代理或操作员的本地密钥存储中。
|
||||
|
||||
## 添加场景
|
||||
|
||||
Mantis 场景应声明：
|
||||
|
||||
- ID 和标题
|
||||
- id 和标题
|
||||
- 传输协议
|
||||
- 所需凭证
|
||||
- 基线 ref 策略
|
||||
- 候选 ref 策略
|
||||
- OpenClaw 配置补丁
|
||||
- 设置步骤
|
||||
- 触发输入
|
||||
- 预期基线判定依据
|
||||
- 预期候选判定依据
|
||||
- 刺激
|
||||
- 预期基线判定器
|
||||
- 预期候选判定器
|
||||
- 视觉捕获目标
|
||||
- 超时预算
|
||||
- 清理步骤
|
||||
|
||||
场景应优先使用小型、类型化的判定依据：
|
||||
场景应优先使用小型、带类型的判定器：
|
||||
|
||||
- 用于回应错误的 Discord 回应状态
|
||||
- 用于话题串错误的 Discord 消息引用
|
||||
- 用于 Slack 错误的 Slack 线程 ts 和回应 API 状态
|
||||
- 用于邮件错误的电子邮件消息 ID 和标头
|
||||
- 当 UI 是唯一可靠的可观测对象时，使用浏览器截图
|
||||
- 用于表情回应错误的 Discord 表情回应状态
|
||||
- 用于串联错误的 Discord 消息引用
|
||||
- 用于 Slack 错误的 Slack thread ts 和表情回应 API 状态
|
||||
- 用于电子邮件错误的电子邮件消息 id 和标头
|
||||
- 当 UI 是唯一可靠可观测对象时使用浏览器截图
|
||||
|
||||
视觉检查应作为补充。如果平台 API 可以证明错误，就使用 API 作为通过/失败判定依据，并保留截图以增强人工信心。
|
||||
视觉检查应作为补充。如果平台 API 可以证明该错误，请使用 API 作为通过/失败判定器，并保留截图用于增强人工信心。
|
||||
|
||||
## 提供商扩展
|
||||
|
||||
在 Discord 之后，同一个 runner 可以添加：
|
||||
在 Discord 之后，同一个运行器可以添加：
|
||||
|
||||
- Slack：回应、线程、应用提及、模态框、文件上传。
|
||||
- 电子邮件：在连接器不足时，使用 `gog` 进行 Gmail 凭证和消息话题串处理。
|
||||
- WhatsApp：二维码登录、重新识别、消息送达、媒体、回应。
|
||||
- Telegram：群组提及门控、命令、可用时的回应。
|
||||
- Matrix：加密房间、线程或回复关系、重启后恢复。
|
||||
- Slack：表情回应、线程、应用提及、模态框、文件上传。
|
||||
- 电子邮件：在连接器不足时，使用 `gog` 进行 Gmail 认证和消息串联。
|
||||
- WhatsApp：二维码登录、重新识别、消息投递、媒体、表情回应。
|
||||
- Telegram：群组提及门控、命令、可用时的表情回应。
|
||||
- Matrix：加密房间、线程或回复关系、重启恢复。
|
||||
|
||||
每种传输协议都应有一个低成本冒烟场景，以及一个或多个错误类别场景。昂贵的视觉场景应保持为可选启用。
|
||||
每种传输协议都应有一个低成本 smoke 场景，以及一个或多个错误类别场景。昂贵的视觉场景应保持为选择性启用。
|
||||
|
||||
## 待解问题
|
||||
## 未决问题
|
||||
|
||||
- 当复用现有 Mantis 机器人时，哪个 Discord 机器人应作为驱动方，哪个应作为 SUT？
|
||||
- 第一阶段的观察者浏览器登录应使用真人 Discord 账号、测试账号，还是只使用机器人可读的 REST 证据？
|
||||
- 复用现有 Mantis bot 时，哪个 Discord bot 应作为驱动方，哪个应作为 SUT？
|
||||
- 第一阶段中，观察者浏览器登录应使用真人 Discord 账号、测试账号，还是只使用 bot 可读的 REST 证据？
|
||||
- GitHub 应为 PR 保留 Mantis 工件多长时间？
|
||||
- ClawSweeper 何时应自动推荐 Mantis，而不是等待维护者命令？
|
||||
- 公开 PR 上传前，截图是否应脱敏或裁剪？
|
||||
- ClawSweeper 应在什么时候自动推荐 Mantis，而不是等待维护者命令？
|
||||
- 面向公开 PR 上传前，截图是否应进行脱敏或裁剪？
|
||||
|
||||
@ -2,38 +2,38 @@
|
||||
read_when:
|
||||
- 首次设置 OpenClaw
|
||||
- 正在查找常见配置模式
|
||||
- 导航到特定配置章节
|
||||
summary: 配置概览：常见任务、快速设置，以及完整参考链接
|
||||
- 跳转到特定配置章节
|
||||
summary: 配置概览：常见任务、快速设置，以及完整参考的链接
|
||||
title: 配置
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T12:47:59Z"
|
||||
generated_at: "2026-05-03T17:11:02Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: b17a72368bb8d178174ccd3ff401657c67911096efd5960e5a1aa8cf0d303c81
|
||||
source_hash: e27ef442d6375d8c22715f20194fb9ce50130204377c9ba4652c2949de28967c
|
||||
source_path: gateway/configuration.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置。
|
||||
活动配置路径必须是普通文件。对于 OpenClaw 拥有的写入，不支持符号链接的 `openclaw.json`
|
||||
布局；原子写入可能会替换该路径，而不是保留符号链接。如果你将配置保存在
|
||||
默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
|
||||
活动配置路径必须是常规文件。符号链接的 `openclaw.json`
|
||||
布局不支持 OpenClaw 拥有的写入；原子写入可能会替换
|
||||
该路径，而不是保留符号链接。如果你将配置保存在默认状态目录
|
||||
之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
|
||||
|
||||
如果文件缺失，OpenClaw 会使用安全默认值。添加配置的常见原因：
|
||||
|
||||
- 连接渠道并控制谁可以给机器人发消息
|
||||
- 设置模型、工具、沙箱隔离或自动化（cron、hooks）
|
||||
- 连接渠道并控制谁可以给 bot 发送消息
|
||||
- 设置模型、工具、沙箱隔离或自动化（cron、钩子）
|
||||
- 调整会话、媒体、网络或 UI
|
||||
|
||||
查看[完整参考](/zh-CN/gateway/configuration-reference)，了解每个可用字段。
|
||||
查看[完整参考](/zh-CN/gateway/configuration-reference)了解每个可用字段。
|
||||
|
||||
智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 获取精确到字段级别的
|
||||
文档。将本页用于面向任务的指导，并将
|
||||
[配置参考](/zh-CN/gateway/configuration-reference)用于更完整的
|
||||
字段映射和默认值。
|
||||
智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 获取精确的字段级
|
||||
文档。此页面提供面向任务的指导；[配置参考](/zh-CN/gateway/configuration-reference)
|
||||
提供更完整的字段映射和默认值。
|
||||
|
||||
<Tip>
|
||||
**刚开始配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看 [Configuration Examples](/zh-CN/gateway/configuration-examples) 指南，获取完整的可复制粘贴配置。
|
||||
**刚开始使用配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看 [Configuration Examples](/zh-CN/gateway/configuration-examples) 指南获取完整的可复制粘贴配置。
|
||||
</Tip>
|
||||
|
||||
## 最小配置
|
||||
@ -64,53 +64,49 @@ OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 支
|
||||
</Tab>
|
||||
<Tab title="控制 UI">
|
||||
打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，并使用 **配置** 标签页。
|
||||
控制 UI 会根据实时配置架构渲染表单，包括字段
|
||||
`title` / `description` 文档元数据，以及可用时的插件和渠道架构，
|
||||
并提供 **Raw JSON** 编辑器作为逃生通道。对于下钻
|
||||
UI 和其他工具，Gateway 网关还暴露 `config.schema.lookup`，用于
|
||||
获取一个路径限定的架构节点及其直接子项摘要。
|
||||
控制 UI 会基于实时配置 schema 渲染表单，包括字段
|
||||
`title` / `description` 文档元数据，以及可用时的插件和渠道 schema，
|
||||
并提供 **原始 JSON** 编辑器作为逃生口。对于下钻
|
||||
UI 和其他工具，Gateway 网关还暴露 `config.schema.lookup`，
|
||||
用于获取一个路径作用域的 schema 节点及其直接子项摘要。
|
||||
</Tab>
|
||||
<Tab title="直接编辑">
|
||||
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
|
||||
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监听该文件并自动应用更改（见[热重载](#config-hot-reload)）。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 严格验证
|
||||
## 严格校验
|
||||
|
||||
<Warning>
|
||||
OpenClaw 只接受完全匹配架构的配置。未知键、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器可以附加 JSON Schema 元数据。
|
||||
OpenClaw 只接受完全匹配 schema 的配置。未知键、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器可以附加 JSON Schema 元数据。
|
||||
</Warning>
|
||||
|
||||
`openclaw config schema` 会打印控制 UI
|
||||
和验证使用的规范 JSON Schema。`config.schema.lookup` 会获取单个路径限定的节点及其
|
||||
子项摘要，供下钻工具使用。字段 `title`/`description` 文档元数据
|
||||
会贯穿嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/
|
||||
`oneOf`/`allOf` 分支。清单注册表加载后，会合并运行时插件和渠道架构。
|
||||
`openclaw config schema` 会打印控制 UI 和校验使用的规范 JSON Schema。
|
||||
`config.schema.lookup` 会获取单个路径作用域节点及其子项摘要，用于下钻工具。
|
||||
字段 `title`/`description` 文档元数据会贯穿嵌套对象、通配符（`*`）、
|
||||
数组项（`[]`）以及 `anyOf`/`oneOf`/`allOf` 分支。加载清单注册表后，
|
||||
运行时插件和渠道 schema 会合并进来。
|
||||
|
||||
验证失败时：
|
||||
校验失败时：
|
||||
|
||||
- Gateway 网关不会启动
|
||||
- 只有诊断命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`）
|
||||
- 运行 `openclaw doctor` 查看确切问题
|
||||
- 运行 `openclaw doctor` 查看精确问题
|
||||
- 运行 `openclaw doctor --fix`（或 `--yes`）应用修复
|
||||
|
||||
Gateway 网关会在每次成功启动后保留一份可信的最后已知良好副本。
|
||||
如果 `openclaw.json` 后续验证失败（或移除了 `gateway.mode`、大幅缩小，
|
||||
或前面被意外添加了一行日志），OpenClaw 会将损坏文件保留为
|
||||
`.clobbered.*`，恢复最后已知良好副本，并记录恢复
|
||||
原因。下一轮智能体交互还会收到一个系统事件警告，避免主
|
||||
智能体盲目重写已恢复的配置。当候选配置包含 `***` 等经过遮盖的密钥占位符时，
|
||||
会跳过将其提升为最后已知良好副本。
|
||||
当每个验证问题都限定在 `plugins.entries.<id>...` 范围内时，OpenClaw
|
||||
不会执行整文件恢复。它会保持当前配置活动，并
|
||||
浮现插件本地失败，这样插件架构或主机版本不匹配
|
||||
就不会回滚无关的用户设置。
|
||||
Gateway 网关在每次成功启动后都会保留一份可信的最近一次可用副本，
|
||||
但启动和热重载不会自动恢复它。如果 `openclaw.json`
|
||||
校验失败（包括插件本地校验），Gateway 网关启动会失败，或
|
||||
重载会被跳过，当前运行时保留最后一次被接受的配置。
|
||||
运行 `openclaw doctor --fix`（或 `--yes`）来修复带前缀/被覆盖的配置，或
|
||||
恢复最近一次可用副本。当候选配置包含已脱敏的密钥占位符（如 `***`）时，
|
||||
会跳过提升为最近一次可用副本。
|
||||
|
||||
## 常见任务
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="设置渠道（WhatsApp、Telegram、Discord 等）">
|
||||
每个渠道在 `channels.<provider>` 下都有自己的配置区段。查看专用渠道页面了解设置步骤：
|
||||
每个渠道在 `channels.<provider>` 下都有自己的配置段。设置步骤请查看对应的渠道页面：
|
||||
|
||||
- [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp`
|
||||
- [Telegram](/zh-CN/channels/telegram) — `channels.telegram`
|
||||
@ -141,7 +137,7 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="选择并配置模型">
|
||||
设置主模型和可选回退模型：
|
||||
设置主模型和可选回退项：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -160,31 +156,31 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
}
|
||||
```
|
||||
|
||||
- `agents.defaults.models` 定义模型目录，并作为 `/model` 的 allowlist。
|
||||
- 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加 allowlist 条目，而不会移除现有模型。除非传入 `--replace`，否则会移除条目的普通替换会被拒绝。
|
||||
- `agents.defaults.models` 定义模型目录，并作为 `/model` 的允许列表。
|
||||
- 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加允许列表条目，而不移除现有模型。除非传入 `--replace`，否则会移除条目的普通替换会被拒绝。
|
||||
- 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。
|
||||
- `agents.defaults.imageMaxDimensionPx` 控制 transcript/工具图像缩小（默认 `1200`）；较低的值通常会减少截图密集型运行中的视觉 token 用量。
|
||||
- 查看 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，并查看 [Model Failover](/zh-CN/concepts/model-failover) 了解认证轮换和回退行为。
|
||||
- `agents.defaults.imageMaxDimensionPx` 控制 transcript/工具图片缩小（默认 `1200`）；较低的值通常会在截图密集的运行中减少视觉 token 用量。
|
||||
- 参见 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，并参见 [Model Failover](/zh-CN/concepts/model-failover) 了解鉴权轮换和回退行为。
|
||||
- 对于自定义/自托管提供商，请参见参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="控制谁可以给机器人发消息">
|
||||
私信访问通过每个渠道的 `dmPolicy` 控制：
|
||||
<Accordion title="控制谁可以给 bot 发送消息">
|
||||
私信访问通过 `dmPolicy` 按渠道控制：
|
||||
|
||||
- `"pairing"`（默认）：未知发送者会获得一次性配对码用于批准
|
||||
- `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对的允许存储）
|
||||
- `"open"`：允许所有传入私信（需要 `allowFrom: ["*"]`）
|
||||
- `"pairing"`（默认）：未知发送者会收到一次性配对码以进行批准
|
||||
- `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者）
|
||||
- `"open"`：允许所有入站私信（需要 `allowFrom: ["*"]`）
|
||||
- `"disabled"`：忽略所有私信
|
||||
|
||||
对于群组，使用 `groupPolicy` + `groupAllowFrom` 或渠道特定的 allowlist。
|
||||
对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道专用允许列表。
|
||||
|
||||
查看[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)，了解每个渠道的详细信息。
|
||||
按渠道的详细信息请参见[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="设置群聊提及门控">
|
||||
群组消息默认**需要提及**。为每个智能体配置触发模式，并将可见房间回复保留在默认的消息工具路径上，除非你有意使用旧版自动最终回复：
|
||||
群组消息默认**需要提及**。按智能体配置触发模式，并将可见房间回复保持在默认的消息工具路径，除非你有意使用旧版自动最终回复：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -215,12 +211,12 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
- **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
|
||||
- **文本模式**：`mentionPatterns` 中的安全正则模式
|
||||
- **可见回复**：`messages.visibleReplies` 可以全局要求通过消息工具发送；`messages.groupChat.visibleReplies` 会为群组/渠道覆盖该设置。
|
||||
- 查看[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)，了解可见回复模式、每渠道覆盖以及自聊模式。
|
||||
- 查看[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)，了解可见回复模式、按渠道覆盖和自聊模式。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="按智能体限制 Skills">
|
||||
使用 `agents.defaults.skills` 作为共享基线，然后通过
|
||||
使用 `agents.defaults.skills` 作为共享基线，然后用
|
||||
`agents.list[].skills` 覆盖特定智能体：
|
||||
|
||||
```json5
|
||||
@ -238,16 +234,16 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
}
|
||||
```
|
||||
|
||||
- 省略 `agents.defaults.skills`，默认不限制 Skills。
|
||||
- 省略 `agents.list[].skills` 以继承默认值。
|
||||
- 设置 `agents.list[].skills: []` 表示没有 Skills。
|
||||
- 查看 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和
|
||||
- 省略 `agents.defaults.skills` 时，默认不限制 Skills。
|
||||
- 省略 `agents.list[].skills` 时继承默认值。
|
||||
- 将 `agents.list[].skills` 设为 `[]` 表示没有 Skills。
|
||||
- 参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及
|
||||
[配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="调整 Gateway 网关渠道健康监控">
|
||||
控制 Gateway 网关对看起来停滞的渠道进行重启的积极程度：
|
||||
控制 Gateway 网关对看起来停滞的渠道进行重启的激进程度：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -269,15 +265,15 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
}
|
||||
```
|
||||
|
||||
- 设置 `gateway.channelHealthCheckMinutes: 0` 可全局禁用健康监控重启。
|
||||
- 将 `gateway.channelHealthCheckMinutes: 0` 设为全局禁用健康监控重启。
|
||||
- `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。
|
||||
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled` 可为单个渠道或账号禁用自动重启，而不禁用全局监控器。
|
||||
- 查看 [Health Checks](/zh-CN/gateway/health) 了解运维调试，并查看[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。
|
||||
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled` 可为某个渠道或账号禁用自动重启，而不禁用全局监控。
|
||||
- 参见 [Health Checks](/zh-CN/gateway/health) 进行运维调试，并参见[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="调整 Gateway 网关 WebSocket 握手超时">
|
||||
在负载较高或性能较低的主机上，给本地客户端更多时间来完成认证前 WebSocket 握手：
|
||||
在负载较高或性能较低的主机上，给本地客户端更多时间完成鉴权前 WebSocket 握手：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -288,8 +284,8 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
```
|
||||
|
||||
- 默认值为 `15000` 毫秒。
|
||||
- 对于一次性的服务或 shell 覆盖，`OPENCLAW_HANDSHAKE_TIMEOUT_MS` 仍然优先。
|
||||
- 优先修复启动/事件循环停顿；这个旋钮适用于健康但在预热期间较慢的主机。
|
||||
- `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 对一次性服务或 shell 覆盖仍然优先。
|
||||
- 优先修复启动/事件循环停顿；此旋钮用于健康但预热期间较慢的主机。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -314,10 +310,10 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
}
|
||||
```
|
||||
|
||||
- `dmScope`: `main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer`
|
||||
- `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer`
|
||||
- `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。
|
||||
- 请参阅[会话管理](/zh-CN/concepts/session)，了解作用域、身份链接和发送策略。
|
||||
- 请参阅[完整参考](/zh-CN/gateway/config-agents#session)，了解所有字段。
|
||||
- 参见 [Session Management](/zh-CN/concepts/session) 了解作用域、身份链接和发送策略。
|
||||
- 参见[完整参考](/zh-CN/gateway/config-agents#session)了解所有字段。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -337,14 +333,14 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
}
|
||||
```
|
||||
|
||||
请先构建镜像——如果使用源码检出，运行 `scripts/sandbox-setup.sh`；如果使用 npm 安装，请参阅[沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)中的内联 `docker build` 命令。
|
||||
先构建镜像 — 如果是源码 checkout，请运行 `scripts/sandbox-setup.sh`；如果是 npm 安装，请参阅 [沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)中的内联 `docker build` 命令。
|
||||
|
||||
请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)获取完整指南，并参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。
|
||||
请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)了解完整指南，并参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="为官方 iOS 构建启用中继支持的推送">
|
||||
中继支持的推送在 `openclaw.json` 中配置。
|
||||
<Accordion title="为官方 iOS 构建启用 relay-backed push">
|
||||
relay-backed push 在 `openclaw.json` 中配置。
|
||||
|
||||
在 Gateway 网关配置中设置：
|
||||
|
||||
@ -364,7 +360,7 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
}
|
||||
```
|
||||
|
||||
等效的 CLI 命令：
|
||||
CLI 等效命令：
|
||||
|
||||
```bash
|
||||
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
|
||||
@ -373,34 +369,34 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
这会执行以下操作：
|
||||
|
||||
- 让 Gateway 网关通过外部中继发送 `push.test`、唤醒提示和重连唤醒。
|
||||
- 使用由已配对 iOS 应用转发的、注册作用域内的发送授权。Gateway 网关不需要部署范围的中继令牌。
|
||||
- 将每个中继支持的注册绑定到 iOS 应用配对的 Gateway 网关身份，因此另一个 Gateway 网关无法复用已存储的注册。
|
||||
- 让本地/手动 iOS 构建继续使用直连 APNs。中继支持的发送仅适用于通过中继注册的官方分发构建。
|
||||
- 必须与官方/TestFlight iOS 构建中内置的中继基础 URL 匹配，以便注册和发送流量到达同一个中继部署。
|
||||
- 使用由已配对 iOS 应用转发的、限定在注册范围内的发送授权。Gateway 网关不需要部署级中继 token。
|
||||
- 将每个 relay-backed 注册绑定到 iOS 应用配对的 Gateway 网关身份，因此其他 Gateway 网关无法复用已存储的注册。
|
||||
- 让本地/手动 iOS 构建继续使用直接 APNs。relay-backed 发送仅适用于通过中继注册的官方分发构建。
|
||||
- 必须匹配内置到官方/TestFlight iOS 构建中的中继基础 URL，以便注册和发送流量到达同一个中继部署。
|
||||
|
||||
端到端流程：
|
||||
|
||||
1. 安装使用相同中继基础 URL 编译的官方/TestFlight iOS 构建。
|
||||
2. 在 Gateway 网关上配置 `gateway.push.apns.relay.baseUrl`。
|
||||
3. 将 iOS 应用与 Gateway 网关配对，并让节点和操作员会话都完成连接。
|
||||
4. iOS 应用获取 Gateway 网关身份，使用 App Attest 和应用收据向中继注册，然后将中继支持的 `push.apns.register` 负载发布到已配对的 Gateway 网关。
|
||||
5. Gateway 网关存储中继句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。
|
||||
3. 将 iOS 应用与 Gateway 网关配对，并让节点会话和操作者会话都连接。
|
||||
4. iOS 应用获取 Gateway 网关身份，使用 App Attest 加应用收据向中继注册，然后将 relay-backed `push.apns.register` 载荷发布到已配对的 Gateway 网关。
|
||||
5. Gateway 网关存储中继 handle 和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。
|
||||
|
||||
运维说明：
|
||||
|
||||
- 如果你将 iOS 应用切换到不同的 Gateway 网关，请重新连接应用，以便它发布绑定到该 Gateway 网关的新中继注册。
|
||||
- 如果你发布了指向不同中继部署的新 iOS 构建，应用会刷新其缓存的中继注册，而不是复用旧的中继来源。
|
||||
- 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，使其能够发布绑定到该 Gateway 网关的新中继注册。
|
||||
- 如果你发布的新 iOS 构建指向不同的中继部署，应用会刷新其缓存的中继注册，而不是复用旧的中继来源。
|
||||
|
||||
兼容性说明：
|
||||
|
||||
- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖使用。
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限 loopback 的开发应急开关；不要在配置中持久化 HTTP 中继 URL。
|
||||
- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限 local loopback 的开发逃生口；不要在配置中持久保存 HTTP 中继 URL。
|
||||
|
||||
请参阅 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并参阅[认证和信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解中继安全模型。
|
||||
请参阅 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并参阅[身份验证和信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解中继安全模型。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="设置 Heartbeat（周期性报到）">
|
||||
<Accordion title="设置 Heartbeat（周期性签到）">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -414,10 +410,10 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
}
|
||||
```
|
||||
|
||||
- `every`：持续时间字符串（`30m`、`2h`）。设置为 `0m` 可禁用。
|
||||
- `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。
|
||||
- `target`：`last` | `none` | `<channel-id>`（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`）
|
||||
- `directPolicy`：对于私信风格的 Heartbeat 目标，使用 `allow`（默认）或 `block`
|
||||
- 请参阅 [Heartbeat](/zh-CN/gateway/heartbeat) 获取完整指南。
|
||||
- `directPolicy`：对于私信样式的 Heartbeat 目标，使用 `allow`（默认）或 `block`
|
||||
- 请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)了解完整指南。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -442,7 +438,7 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="设置 webhook（钩子）">
|
||||
<Accordion title="设置 webhook（hooks）">
|
||||
在 Gateway 网关上启用 HTTP webhook 端点：
|
||||
|
||||
```json5
|
||||
@ -467,15 +463,15 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
```
|
||||
|
||||
安全说明：
|
||||
- 将所有 hook/webhook 负载内容视为不受信任的输入。
|
||||
- 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关令牌。
|
||||
- Hook 认证仅支持标头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串令牌会被拒绝。
|
||||
- `hooks.path` 不能是 `/`；请将 webhook 入口保留在专用子路径上，例如 `/hooks`。
|
||||
- 除非进行严格限定范围的调试，否则请保持禁用不安全内容绕过标志（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。
|
||||
- 如果你启用 `hooks.allowRequestSessionKey`，也请设置 `hooks.allowedSessionKeyPrefixes` 来限制调用方选择的会话键。
|
||||
- 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息传递，并在可行时配合沙箱隔离）。
|
||||
- 将所有 hook/webhook 载荷内容视为不受信任的输入。
|
||||
- 使用专用的 `hooks.token`；不要复用共享 Gateway 网关 token。
|
||||
- Hook 认证仅支持 header（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串 token 会被拒绝。
|
||||
- `hooks.path` 不能是 `/`；将 webhook 入口保留在专用子路径上，例如 `/hooks`。
|
||||
- 除非进行严格限定范围的调试，否则保持不安全内容绕过标志禁用（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。
|
||||
- 如果启用 `hooks.allowRequestSessionKey`，也要设置 `hooks.allowedSessionKeyPrefixes`，以约束调用方选择的会话键。
|
||||
- 对于 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息传递，并尽可能使用沙箱隔离）。
|
||||
|
||||
请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)，了解所有映射选项和 Gmail 集成。
|
||||
请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)了解所有映射选项和 Gmail 集成。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -497,11 +493,11 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
}
|
||||
```
|
||||
|
||||
请参阅[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和按智能体划分的访问配置文件。
|
||||
请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和每智能体访问配置文件。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="将配置拆分为多个文件（$include）">
|
||||
<Accordion title="将配置拆分到多个文件中（$include）">
|
||||
使用 `$include` 组织大型配置：
|
||||
|
||||
```json5
|
||||
@ -517,35 +513,33 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好
|
||||
|
||||
- **单个文件**：替换包含它的对象
|
||||
- **文件数组**：按顺序深度合并（后者优先）
|
||||
- **同级键**：在 include 之后合并（覆盖被 include 的值）
|
||||
- **嵌套 include**：最多支持 10 层深度
|
||||
- **相对路径**：相对于执行 include 的文件解析
|
||||
- **OpenClaw 所有的写入**：当写入只更改一个由单文件 include 支持的顶层区段时，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该 include 的文件，并保持 `openclaw.json` 不变
|
||||
- **不支持的透传写入**：对于 OpenClaw 所有的写入，根 include、include 数组以及带同级覆盖的 include 会以失败关闭方式处理，而不是将配置扁平化
|
||||
- **限制范围**：`$include` 路径必须解析到包含 `openclaw.json` 的目录之下。要在机器或用户之间共享一棵目录树，请将 `OPENCLAW_INCLUDE_ROOTS` 设置为额外目录的路径列表（POSIX 上为 `:`，Windows 上为 `;`），include 可以引用这些目录。符号链接会被解析并重新检查，因此即使某个路径在词法上位于配置目录中，但其真实目标逃出了每个允许的根，也仍会被拒绝。
|
||||
- **错误处理**：针对缺失文件、解析错误和循环 include 提供清晰错误
|
||||
- **同级键**：在 include 之后合并（覆盖已 include 的值）
|
||||
- **嵌套 include**：支持最多 10 层深度
|
||||
- **相对路径**：相对于包含它的文件解析
|
||||
- **OpenClaw 所有的写入**：当一次写入只更改一个顶级 section，且该 section 由单文件 include 支持，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该被 include 的文件，并保持 `openclaw.json` 不变
|
||||
- **不支持的写穿透**：root include、include 数组，以及带有同级覆盖的 include，在 OpenClaw 所有的写入中会失败关闭，而不是展平配置
|
||||
- **限制范围**：`$include` 路径必须解析到保存 `openclaw.json` 的目录下。若要跨机器或用户共享一棵目录树，请将 `OPENCLAW_INCLUDE_ROOTS` 设置为路径列表（POSIX 上为 `:`，Windows 上为 `;`），其中包含 include 可引用的其他目录。符号链接会被解析并重新检查，因此即使某个路径在字面上位于配置目录中，但其真实目标逃逸出每个允许的 root，仍会被拒绝。
|
||||
- **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 配置热重载
|
||||
|
||||
Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——大多数设置无需手动重启。
|
||||
Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改 — 大多数设置无需手动重启。
|
||||
|
||||
直接文件编辑在通过验证前会被视为不受信任。监视器会等待编辑器的临时写入/重命名抖动稳定下来，读取最终文件，并通过恢复最后一次已知良好的配置来拒绝无效的外部编辑。OpenClaw 所有的配置写入在写入前使用同一个 schema 门禁；会拒绝破坏性覆盖，例如删除 `gateway.mode` 或将文件缩小超过一半，并保存为 `.rejected.*` 以供检查。
|
||||
直接文件编辑在通过验证前会被视为不受信任。监视器会等待编辑器临时写入/重命名抖动稳定，读取最终文件，并在不重写 `openclaw.json` 的情况下拒绝无效外部编辑。OpenClaw 所有的配置写入在写入前使用同一个 schema gate；破坏性覆盖（例如删除 `gateway.mode` 或将文件缩小超过一半）会被拒绝，并保存为 `.rejected.*` 以供检查。
|
||||
|
||||
插件本地验证失败是例外：如果所有问题都位于 `plugins.entries.<id>...` 下，重载会保留当前配置并报告插件问题，而不是恢复 `.last-good`。
|
||||
|
||||
如果你在日志中看到 `Config auto-restored from last-known-good` 或 `config reload restored last-known-good config`，请检查 `openclaw.json` 旁边匹配的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行 `openclaw config validate`。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)获取恢复检查清单。
|
||||
如果看到 `config reload skipped (invalid config)`，或启动时报出 `Invalid config`，请检查配置，运行 `openclaw config validate`，然后运行 `openclaw doctor --fix` 进行修复。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-rejected-invalid-config)查看检查清单。
|
||||
|
||||
### 重载模式
|
||||
|
||||
| 模式 | 行为 |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------- |
|
||||
| **`hybrid`**（默认） | 立即热应用安全更改。对关键更改自动重启。 |
|
||||
| **`hot`** | 仅热应用安全更改。当需要重启时记录警告——由你处理。 |
|
||||
| **`restart`** | 任何配置更改都会重启 Gateway 网关，无论是否安全。 |
|
||||
| **`off`** | 禁用文件监视。更改会在下一次手动重启时生效。 |
|
||||
| **`hot`** | 仅热应用安全更改。需要重启时记录警告 — 由你处理。 |
|
||||
| **`restart`** | 对任何配置更改都重启 Gateway 网关，无论是否安全。 |
|
||||
| **`off`** | 禁用文件监视。更改会在下次手动重启时生效。 |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -557,18 +551,18 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——
|
||||
|
||||
### 哪些会热应用，哪些需要重启
|
||||
|
||||
大多数字段都可以在不停机的情况下热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。
|
||||
大多数字段可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会被自动处理。
|
||||
|
||||
| 类别 | 字段 | 是否需要重启？ |
|
||||
| 类别 | 字段 | 需要重启？ |
|
||||
| ------------------- | ----------------------------------------------------------------- | --------------- |
|
||||
| 渠道 | `channels.*`, `web` (WhatsApp) — 所有内置和插件渠道 | 否 |
|
||||
| 智能体与模型 | `agent`, `agents`, `models`, `routing` | 否 |
|
||||
| 自动化 | `hooks`, `cron`, `agent.heartbeat` | 否 |
|
||||
| 会话与消息 | `session`, `messages` | 否 |
|
||||
| 工具与媒体 | `tools`, `browser`, `skills`, `mcp`, `audio`, `talk` | 否 |
|
||||
| UI 与其他 | `ui`, `logging`, `identity`, `bindings` | 否 |
|
||||
| 渠道 | `channels.*`、`web`（WhatsApp）— 所有内置和插件渠道 | 否 |
|
||||
| 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 |
|
||||
| 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 |
|
||||
| 会话和消息 | `session`、`messages` | 否 |
|
||||
| 工具和媒体 | `tools`、`browser`、`skills`、`mcp`、`audio`、`talk` | 否 |
|
||||
| UI 和其他 | `ui`、`logging`、`identity`、`bindings` | 否 |
|
||||
| Gateway 网关服务器 | `gateway.*`（端口、绑定、认证、tailscale、TLS、HTTP） | **是** |
|
||||
| 基础设施 | `discovery`, `canvasHost`, `plugins` | **是** |
|
||||
| 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** |
|
||||
|
||||
<Note>
|
||||
`gateway.reload` 和 `gateway.remote` 是例外 — 更改它们**不会**触发重启。
|
||||
@ -576,29 +570,23 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——
|
||||
|
||||
### 重载规划
|
||||
|
||||
当你编辑通过 `$include` 引用的源文件时，OpenClaw 会从源文件编写时的布局规划重载，而不是从扁平化的内存视图规划。
|
||||
这样即使单个顶级部分位于自己的包含文件中，例如
|
||||
`plugins: { $include: "./plugins.json5" }`，热重载决策（热应用或重启）也能保持可预测。
|
||||
如果源布局存在歧义，重载规划会保守失败。
|
||||
当你编辑通过 `$include` 引用的源文件时，OpenClaw 会从源作者编写的布局规划重新加载，而不是从扁平化的内存视图规划。这样即使单个顶层部分位于自己的 include 文件中，例如 `plugins: { $include: "./plugins.json5" }`，也能让热重载决策（热应用还是重启）保持可预测。如果源布局存在歧义，重新加载规划会以关闭方式失败。
|
||||
|
||||
## 配置 RPC（程序化更新）
|
||||
|
||||
对于通过 Gateway 网关 API 写入配置的工具，优先使用此流程：
|
||||
对于通过 Gateway 网关 API 写入配置的工具，建议使用以下流程：
|
||||
|
||||
- 使用 `config.schema.lookup` 检查一个子树（浅层 schema 节点 + 子级摘要）
|
||||
- 使用 `config.get` 获取当前快照以及 `hash`
|
||||
- 使用 `config.patch` 进行局部更新（JSON 合并补丁：对象会合并，`null` 会删除，数组会替换）
|
||||
- 仅在你打算替换整个配置时使用 `config.apply`
|
||||
- 使用 `update.run` 显式执行自更新并重启；如果重启后的会话应运行一次后续回合，请包含 `continuationMessage`
|
||||
- 使用 `update.status` 检查最新的更新重启哨兵，并在重启后验证正在运行的版本
|
||||
- `config.schema.lookup` 用于检查一个子树（浅层 schema 节点 + 子项摘要）
|
||||
- `config.get` 用于获取当前快照以及 `hash`
|
||||
- `config.patch` 用于局部更新（JSON merge patch：对象合并，`null` 删除，数组替换）
|
||||
- 仅当你打算替换整个配置时才使用 `config.apply`
|
||||
- `update.run` 用于显式自更新并重启；当重启后的会话应运行一个后续轮次时，请包含 `continuationMessage`
|
||||
- `update.status` 用于检查最新的更新重启哨兵，并在重启后验证正在运行的版本
|
||||
|
||||
智能体应将 `config.schema.lookup` 作为获取精确字段级文档和约束的第一站。
|
||||
当它们需要更宽泛的配置映射、默认值或指向专用子系统参考的链接时，请使用[配置参考](/zh-CN/gateway/configuration-reference)。
|
||||
智能体应将 `config.schema.lookup` 视为获取精确字段级文档和约束的第一站。当需要更广泛的配置映射、默认值或专用子系统参考链接时，请使用 [配置参考](/zh-CN/gateway/configuration-reference)。
|
||||
|
||||
<Note>
|
||||
控制平面写入（`config.apply`、`config.patch`、`update.run`）会按每个 `deviceId+clientIp` 每 60 秒 3 个请求进行限流。
|
||||
重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。
|
||||
`update.status` 是只读的，但限定为管理员作用域，因为重启哨兵可能包含更新步骤摘要和命令输出尾部。
|
||||
控制平面写入（`config.apply`、`config.patch`、`update.run`）按每个 `deviceId+clientIp` 每 60 秒 3 个请求进行速率限制。重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。`update.status` 是只读的，但属于管理员作用域，因为重启哨兵可能包含更新步骤摘要和命令输出尾部。
|
||||
</Note>
|
||||
|
||||
局部补丁示例：
|
||||
@ -611,17 +599,16 @@ openclaw gateway call config.patch --params '{
|
||||
}'
|
||||
```
|
||||
|
||||
`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。
|
||||
当配置已存在时，这两个方法都需要 `baseHash`。
|
||||
`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。当配置已经存在时，这两个方法都要求提供 `baseHash`。
|
||||
|
||||
## 环境变量
|
||||
|
||||
OpenClaw 会从父进程以及以下位置读取环境变量：
|
||||
OpenClaw 会从父进程读取环境变量，并额外读取：
|
||||
|
||||
- 当前工作目录中的 `.env`（如果存在）
|
||||
- `~/.openclaw/.env`（全局回退）
|
||||
|
||||
这两个文件都不会覆盖现有环境变量。你也可以在配置中设置内联环境变量：
|
||||
两个文件都不会覆盖现有环境变量。你也可以在配置中设置内联环境变量：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -632,8 +619,8 @@ OpenClaw 会从父进程以及以下位置读取环境变量：
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Shell env import (optional)">
|
||||
如果启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键：
|
||||
<Accordion title="Shell 环境导入（可选）">
|
||||
如果启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并只导入缺失的键：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -643,11 +630,11 @@ OpenClaw 会从父进程以及以下位置读取环境变量：
|
||||
}
|
||||
```
|
||||
|
||||
等效的环境变量：`OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
环境变量等价项：`OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Env var substitution in config values">
|
||||
使用 `${VAR_NAME}` 在任意配置字符串值中引用环境变量：
|
||||
<Accordion title="配置值中的环境变量替换">
|
||||
在任何配置字符串值中使用 `${VAR_NAME}` 引用环境变量：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -661,12 +648,12 @@ OpenClaw 会从父进程以及以下位置读取环境变量：
|
||||
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`
|
||||
- 缺失或为空的变量会在加载时抛出错误
|
||||
- 使用 `$${VAR}` 转义以输出字面量
|
||||
- 可在 `$include` 文件中使用
|
||||
- 可在 `$include` 文件内工作
|
||||
- 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Secret refs (env, file, exec)">
|
||||
<Accordion title="Secret refs（env、file、exec）">
|
||||
对于支持 SecretRef 对象的字段，你可以使用：
|
||||
|
||||
```json5
|
||||
@ -699,22 +686,21 @@ OpenClaw 会从父进程以及以下位置读取环境变量：
|
||||
}
|
||||
```
|
||||
|
||||
SecretRef 详情（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）位于[密钥管理](/zh-CN/gateway/secrets)。
|
||||
支持的凭据路径列在 [SecretRef 凭据表面](/zh-CN/reference/secretref-credential-surface)中。
|
||||
SecretRef 详情（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）见 [Secrets Management](/zh-CN/gateway/secrets)。支持的凭证路径列在 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) 中。
|
||||
</Accordion>
|
||||
|
||||
完整的优先级和来源见[环境](/zh-CN/help/environment)。
|
||||
完整优先级和来源请参阅 [Environment](/zh-CN/help/environment)。
|
||||
|
||||
## 完整参考
|
||||
|
||||
如需完整的逐字段参考，请参阅**[配置参考](/zh-CN/gateway/configuration-reference)**。
|
||||
如需完整的逐字段参考，请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。
|
||||
|
||||
---
|
||||
|
||||
_相关：[配置示例](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_
|
||||
_相关：[Configuration Examples](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_
|
||||
|
||||
## 相关
|
||||
|
||||
- [配置参考](/zh-CN/gateway/configuration-reference)
|
||||
- [配置示例](/zh-CN/gateway/configuration-examples)
|
||||
- [Configuration examples](/zh-CN/gateway/configuration-examples)
|
||||
- [Gateway 网关运行手册](/zh-CN/gateway)
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- 故障排除中心将你引导到这里，以便进行更深入的诊断
|
||||
- 你需要稳定的、基于症状的运行手册章节，并附上精确命令
|
||||
- 故障排除中心将你指引到这里，以便进行更深入的诊断
|
||||
- 你需要基于稳定症状、包含精确命令的运行手册章节
|
||||
sidebarTitle: Troubleshooting
|
||||
summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除操作手册
|
||||
summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除运行手册
|
||||
title: 故障排除
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T20:37:47Z"
|
||||
generated_at: "2026-05-03T17:11:05Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 815fbbca4d12b4b9c65b1172e07606d0eaf4c64df7fd6ca23a8f8d104b78c2a9
|
||||
source_hash: 19422615706ca09124b19dd3e21b2c13391d6daf2b1807e01b4ce2047d02e522
|
||||
source_path: gateway/troubleshooting.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
此页面是深入运行手册。如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。
|
||||
本页是深入运行手册。如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。
|
||||
|
||||
## 命令阶梯
|
||||
## 命令排查顺序
|
||||
|
||||
先按此顺序运行这些命令：
|
||||
请先按以下顺序运行这些命令：
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -31,14 +31,14 @@ openclaw channels status --probe
|
||||
预期的健康信号：
|
||||
|
||||
- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok`，以及一行 `Capability: ...`。
|
||||
- `openclaw doctor` 未报告阻塞性的配置/服务问题。
|
||||
- `openclaw channels status --probe` 显示每个账号的实时传输协议状态，并在支持的地方显示探测/审计结果，例如 `works` 或 `audit ok`。
|
||||
- `openclaw doctor` 报告没有阻塞性的配置/服务问题。
|
||||
- `openclaw channels status --probe` 显示逐账号的实时传输状态，并在支持的位置显示探测/审计结果，例如 `works` 或 `audit ok`。
|
||||
|
||||
## 安装分裂和新版配置保护
|
||||
## 脑裂安装与较新配置保护
|
||||
|
||||
当 Gateway 网关服务在更新后意外停止，或者日志显示某个 `openclaw` 二进制文件早于最后写入 `openclaw.json` 的版本时，使用此部分。
|
||||
当 Gateway 网关服务在更新后意外停止，或日志显示某个 `openclaw` 二进制文件早于最后写入 `openclaw.json` 的版本时，使用本节。
|
||||
|
||||
OpenClaw 会用 `meta.lastTouchedVersion` 标记配置写入。只读命令仍可检查由更新版 OpenClaw 写入的配置，但来自旧版二进制文件的进程和服务变更会拒绝继续。被阻止的操作包括 Gateway 网关服务启动、停止、重启、卸载、强制服务重装、服务模式 Gateway 网关启动，以及 `gateway --force` 端口清理。
|
||||
OpenClaw 会用 `meta.lastTouchedVersion` 标记配置写入。只读命令仍可检查由较新版 OpenClaw 写入的配置，但进程和服务变更操作会拒绝从较旧的二进制文件继续。被阻止的操作包括 Gateway 网关服务启动、停止、重启、卸载、强制服务重装、服务模式 Gateway 网关启动，以及 `gateway --force` 端口清理。
|
||||
|
||||
```bash
|
||||
which openclaw
|
||||
@ -52,7 +52,7 @@ openclaw config get meta.lastTouchedVersion
|
||||
修复 `PATH`，让 `openclaw` 解析到较新的安装，然后重新运行该操作。
|
||||
</Step>
|
||||
<Step title="重新安装 Gateway 网关服务">
|
||||
从较新的安装中重新安装预期的 Gateway 网关服务：
|
||||
从较新的安装重新安装目标 Gateway 网关服务：
|
||||
|
||||
```bash
|
||||
openclaw gateway install --force
|
||||
@ -60,18 +60,18 @@ openclaw config get meta.lastTouchedVersion
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="移除过时包装器">
|
||||
移除仍指向旧 `openclaw` 二进制文件的过时系统包或旧包装器条目。
|
||||
<Step title="移除过期包装器">
|
||||
移除仍指向旧 `openclaw` 二进制文件的过期系统包或旧包装器条目。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
仅在有意降级或紧急恢复时，为单个命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常操作时不要设置它。
|
||||
仅在有意降级或紧急恢复时，为单条命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常操作时保持未设置。
|
||||
</Warning>
|
||||
|
||||
## Anthropic 429 长上下文需要额外用量资格
|
||||
## Anthropic 429 长上下文需要额外用量
|
||||
|
||||
当日志/错误包含以下内容时使用：`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。
|
||||
当日志/错误包含以下内容时使用本节：`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。
|
||||
|
||||
```bash
|
||||
openclaw logs --follow
|
||||
@ -79,10 +79,10 @@ openclaw models status
|
||||
openclaw config get agents.defaults.models
|
||||
```
|
||||
|
||||
查看：
|
||||
检查以下情况：
|
||||
|
||||
- 选中的 Anthropic Opus/Sonnet 模型具有 `params.context1m: true`。
|
||||
- 当前 Anthropic 凭证不符合长上下文使用资格。
|
||||
- 所选的 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。
|
||||
- 当前 Anthropic 凭证不符合长上下文使用条件。
|
||||
- 请求只在需要 1M beta 路径的长会话/模型运行中失败。
|
||||
|
||||
修复选项：
|
||||
@ -91,26 +91,26 @@ openclaw config get agents.defaults.models
|
||||
<Step title="禁用 context1m">
|
||||
为该模型禁用 `context1m`，以回退到普通上下文窗口。
|
||||
</Step>
|
||||
<Step title="使用符合资格的凭证">
|
||||
使用符合长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API key。
|
||||
<Step title="使用符合条件的凭证">
|
||||
使用符合长上下文请求条件的 Anthropic 凭证，或切换到 Anthropic API 密钥。
|
||||
</Step>
|
||||
<Step title="配置回退模型">
|
||||
配置回退模型，让运行在 Anthropic 长上下文请求被拒绝时继续进行。
|
||||
配置回退模型，以便在 Anthropic 长上下文请求被拒绝时运行仍能继续。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
相关：
|
||||
|
||||
- [Anthropic](/zh-CN/providers/anthropic)
|
||||
- [令牌使用和成本](/zh-CN/reference/token-use)
|
||||
- [令牌使用量和成本](/zh-CN/reference/token-use)
|
||||
- [为什么我会看到来自 Anthropic 的 HTTP 429？](/zh-CN/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
|
||||
|
||||
## 本地 OpenAI 兼容后端通过直接探测，但智能体运行失败
|
||||
## 本地 OpenAI 兼容后端能通过直接探测，但智能体运行失败
|
||||
|
||||
在以下情况下使用：
|
||||
当出现以下情况时使用本节：
|
||||
|
||||
- `curl ... /v1/models` 正常工作
|
||||
- 很小的直接 `/v1/chat/completions` 调用正常工作
|
||||
- `curl ... /v1/models` 可用
|
||||
- 微型直接 `/v1/chat/completions` 调用可用
|
||||
- OpenClaw 模型运行只在普通智能体轮次中失败
|
||||
|
||||
```bash
|
||||
@ -122,29 +122,29 @@ openclaw infer model run --model <provider/model> --prompt "hi" --json
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
查看：
|
||||
检查以下情况：
|
||||
|
||||
- 直接的小请求成功，但 OpenClaw 运行只在较大提示词上失败
|
||||
- 出现 `model_not_found` 或 404 错误，即使直接 `/v1/chat/completions`
|
||||
可使用同一个裸模型 ID 正常工作
|
||||
- 关于 `messages[].content` 预期为字符串的后端错误
|
||||
- 直接微型调用成功，但 OpenClaw 运行只在较大的提示词上失败
|
||||
- 即使直接 `/v1/chat/completions`
|
||||
使用同一个裸模型 ID 可用，也出现 `model_not_found` 或 404 错误
|
||||
- 后端错误提示 `messages[].content` 期望字符串
|
||||
- 使用 OpenAI 兼容本地后端时，间歇出现 `incomplete turn detected ... stopReason=stop payloads=0` 警告
|
||||
- 只在较大的提示词令牌数或完整智能体运行时提示词下出现的后端崩溃
|
||||
- 只在更大的提示词令牌数量或完整智能体运行时提示词下出现的后端崩溃
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="常见特征">
|
||||
- 本地 MLX/vLLM 风格服务器出现 `model_not_found` → 验证 `baseUrl` 包含 `/v1`，对于 `/v1/chat/completions` 后端，`api` 是 `"openai-completions"`，并且 `models.providers.<provider>.models[].id` 是裸的提供商本地 ID。选择它时加一次提供商前缀，例如 `mlx/mlx-community/Qwen3-30B-A3B-6bit`；将目录条目保持为 `mlx-community/Qwen3-30B-A3B-6bit`。
|
||||
- 本地 MLX/vLLM 风格服务器出现 `model_not_found` → 验证 `baseUrl` 包含 `/v1`，对于 `/v1/chat/completions` 后端，`api` 是 `"openai-completions"`，并且 `models.providers.<provider>.models[].id` 是裸提供商本地 ID。选择时加一次提供商前缀，例如 `mlx/mlx-community/Qwen3-30B-A3B-6bit`；目录条目保持为 `mlx-community/Qwen3-30B-A3B-6bit`。
|
||||
- `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化 Chat Completions 内容部分。修复：设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
|
||||
- `incomplete turn detected ... stopReason=stop payloads=0` → 后端完成了 Chat Completions 请求，但未为该轮次返回用户可见的助手文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次；持续失败通常意味着后端正在发出空内容/非文本内容，或抑制最终回答文本。
|
||||
- 直接的小请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输协议很可能已经正确；后端在更大的智能体运行时提示词形态上失败。
|
||||
- 禁用工具后失败减少但未消失 → 工具 schema 是压力的一部分，但剩余问题仍是上游模型/服务器容量或后端 bug。
|
||||
- `incomplete turn detected ... stopReason=stop payloads=0` → 后端完成了 Chat Completions 请求，但没有为该轮次返回用户可见的助手文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次；持续失败通常意味着后端正在发出空内容/非文本内容，或抑制最终答案文本。
|
||||
- 直接微型请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输层很可能已经正确；失败发生在后端处理更大的智能体运行时提示词形状时。
|
||||
- 禁用工具后失败减少但没有消失 → 工具模式是压力来源的一部分，但剩余问题仍是上游模型/服务器容量或后端错误。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="修复选项">
|
||||
1. 对仅支持字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。
|
||||
2. 对无法可靠处理 OpenClaw 工具 schema 表面的模型/后端设置 `compat.supportsTools: false`。
|
||||
3. 尽可能降低提示词压力：更小的工作区启动内容、更短的会话历史、更轻量的本地模型，或具有更强长上下文支持的后端。
|
||||
4. 如果很小的直接请求持续通过，而 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并用已接受的 payload 形态向上游提交复现。
|
||||
1. 为仅支持字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。
|
||||
2. 对无法可靠处理 OpenClaw 工具模式接口面的模型/后端设置 `compat.supportsTools: false`。
|
||||
3. 在可行时降低提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或具备更强长上下文支持的后端。
|
||||
4. 如果微型直接请求持续通过，但 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并向该项目提交一个包含已接受载荷形状的复现。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -154,9 +154,9 @@ openclaw logs --follow
|
||||
- [本地模型](/zh-CN/gateway/local-models)
|
||||
- [OpenAI 兼容端点](/zh-CN/gateway/configuration-reference#openai-compatible-endpoints)
|
||||
|
||||
## 没有回复
|
||||
## 无回复
|
||||
|
||||
如果渠道已启动但没有任何响应，请先检查路由和策略，再重新连接任何内容。
|
||||
如果渠道已启动但没有任何回复，请先检查路由和策略，再重新连接任何内容。
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -166,17 +166,17 @@ openclaw config get channels
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
查看：
|
||||
检查以下情况：
|
||||
|
||||
- 私信发送者的配对待处理。
|
||||
- 私信发送者有待处理的配对。
|
||||
- 群组提及门控（`requireMention`、`mentionPatterns`）。
|
||||
- 渠道/群组 allowlist 不匹配。
|
||||
- 渠道/群组允许列表不匹配。
|
||||
|
||||
常见特征：
|
||||
|
||||
- `drop guild message (mention required` → 群组消息会被忽略，直到被提及。
|
||||
- `pairing request` → 发送者需要批准。
|
||||
- `blocked` / `allowlist` → 发送者/渠道已被策略过滤。
|
||||
- `blocked` / `allowlist` → 发送者/渠道被策略过滤。
|
||||
|
||||
相关：
|
||||
|
||||
@ -184,9 +184,9 @@ openclaw logs --follow
|
||||
- [群组](/zh-CN/channels/groups)
|
||||
- [配对](/zh-CN/channels/pairing)
|
||||
|
||||
## Dashboard 控制 UI 连接
|
||||
## 仪表板控制 UI 连接性
|
||||
|
||||
当 dashboard/control UI 无法连接时，请验证 URL、认证模式和安全上下文假设。
|
||||
当仪表板/控制 UI 无法连接时，请验证 URL、认证模式和安全上下文假设。
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -196,45 +196,45 @@ openclaw doctor
|
||||
openclaw gateway status --json
|
||||
```
|
||||
|
||||
查看：
|
||||
检查以下情况：
|
||||
|
||||
- 正确的探测 URL 和 dashboard URL。
|
||||
- 正确的探测 URL 和仪表板 URL。
|
||||
- 客户端与 Gateway 网关之间的认证模式/令牌不匹配。
|
||||
- 在需要设备身份的地方使用 HTTP。
|
||||
- 在需要设备身份的位置使用了 HTTP。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="连接/认证特征">
|
||||
- `device identity required` → 非安全上下文或缺少设备认证。
|
||||
- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正在从非 loopback 浏览器源连接，但没有显式 allowlist）。
|
||||
- `device nonce required` / `device nonce mismatch` → 客户端未完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。
|
||||
- `device signature invalid` / `device signature expired` → 客户端为当前握手签名了错误 payload（或时间戳过期）。
|
||||
- `AUTH_TOKEN_MISMATCH` 且带有 `canRetryWithDeviceToken=true` → 客户端可以用缓存的设备令牌执行一次受信重试。
|
||||
- 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存 scope 集。显式 `deviceToken` / 显式 `scopes` 调用方会保留其请求的 scope 集。
|
||||
- 在该重试路径之外，连接认证优先级是先显式共享令牌/密码，然后是显式 `deviceToken`，再是已存储设备令牌，最后是 bootstrap token。
|
||||
- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化。因此，同一客户端的两个并发错误重试可能会让第二次尝试显示 `retry later`，而不是两个普通不匹配。
|
||||
- 浏览器源 loopback 客户端出现 `too many failed authentication attempts (retry later)` → 来自同一规范化 `Origin` 的重复失败会被暂时锁定；另一个 localhost 源使用单独的桶。
|
||||
- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从没有显式允许列表的非 loopback 浏览器源连接）。
|
||||
- `device nonce required` / `device nonce mismatch` → 客户端未完成基于质询的设备认证流程（`connect.challenge` + `device.nonce`）。
|
||||
- `device signature invalid` / `device signature expired` → 客户端为当前握手签名了错误的载荷（或过期时间戳）。
|
||||
- `AUTH_TOKEN_MISMATCH` 且带有 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备令牌做一次受信任重试。
|
||||
- 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留其请求的作用域集合。
|
||||
- 在该重试路径之外，connect 认证优先级是：显式共享令牌/密码优先，然后是显式 `deviceToken`，再是已存储设备令牌，最后是引导令牌。
|
||||
- 在异步 Tailscale Serve 控制 UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败前被串行化。因此，来自同一客户端的两个错误并发重试可能会在第二次尝试时显示 `retry later`，而不是两个普通的不匹配。
|
||||
- 来自浏览器源 loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自同一个规范化 `Origin` 的重复失败会被临时锁定；另一个 localhost 源使用单独的桶。
|
||||
- 该重试后仍反复出现 `unauthorized` → 共享令牌/设备令牌漂移；刷新令牌配置，并在需要时重新批准/轮换设备令牌。
|
||||
- `gateway connect failed:` → host/port/url 目标错误。
|
||||
- `gateway connect failed:` → 主机/端口/URL 目标错误。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 认证详情代码快速映射
|
||||
### 认证详情代码速查表
|
||||
|
||||
使用失败 `connect` 响应中的 `error.details.code` 来选择下一步操作：
|
||||
|
||||
| 详情代码 | 含义 | 建议操作 |
|
||||
| 详细代码 | 含义 | 推荐操作 |
|
||||
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享令牌。 | 在客户端粘贴/设置令牌并重试。对于仪表板路径：`openclaw config get gateway.auth.token`，然后粘贴到控制 UI 设置中。 |
|
||||
| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关认证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次受信任重试。缓存令牌重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方会保留请求的作用域。如果仍然失败，请运行[令牌漂移恢复检查清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 |
|
||||
| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备令牌已过期或被撤销。 | 使用[设备 CLI](/zh-CN/cli/devices) 轮换/重新批准设备令牌，然后重新连接。 |
|
||||
| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后执行 `openclaw devices approve <requestId>`。作用域/角色升级在你审查请求的访问权限后使用同一流程。 |
|
||||
| `AUTH_TOKEN_MISSING` | 客户端没有发送必需的共享令牌。 | 在客户端粘贴/设置令牌，然后重试。对于控制台路径：先运行 `openclaw config get gateway.auth.token`，然后粘贴到控制 UI 设置中。 |
|
||||
| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关身份验证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次受信任重试。缓存令牌重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方会保留请求的作用域。如果仍然失败，请运行[令牌漂移恢复清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 |
|
||||
| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的按设备令牌已过期或已被撤销。 | 使用[设备 CLI](/zh-CN/cli/devices) 轮换/重新批准设备令牌，然后重新连接。 |
|
||||
| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：先运行 `openclaw devices list`，再运行 `openclaw devices approve <requestId>`。作用域/角色升级在你审查请求的访问权限后使用相同流程。 |
|
||||
|
||||
<Note>
|
||||
使用共享 Gateway 网关令牌/密码认证的直接 loopback 后端 RPC 不应依赖 CLI 的已配对设备作用域基线。如果子智能体或其他内部调用仍然因 `scope-upgrade` 失败，请确认调用方使用的是 `client.id: "gateway-client"` 和 `client.mode: "backend"`，且没有强制使用显式 `deviceIdentity` 或设备令牌。
|
||||
使用共享 Gateway 网关令牌/密码进行身份验证的直接环回后端 RPC 不应依赖 CLI 的已配对设备作用域基线。如果 subagent 或其他内部调用仍因 `scope-upgrade` 失败，请确认调用方正在使用 `client.id: "gateway-client"` 和 `client.mode: "backend"`，并且没有强制使用显式 `deviceIdentity` 或设备令牌。
|
||||
</Note>
|
||||
|
||||
设备认证 v2 迁移检查：
|
||||
设备身份验证 v2 迁移检查：
|
||||
|
||||
```bash
|
||||
openclaw --version
|
||||
@ -245,33 +245,33 @@ openclaw gateway status
|
||||
如果日志显示 nonce/签名错误，请更新连接客户端并验证它：
|
||||
|
||||
<Steps>
|
||||
<Step title="等待 connect.challenge">
|
||||
客户端等待 Gateway 网关签发的 `connect.challenge`。
|
||||
<Step title="Wait for connect.challenge">
|
||||
客户端等待 Gateway 网关发出的 `connect.challenge`。
|
||||
</Step>
|
||||
<Step title="签署载荷">
|
||||
客户端签署与 challenge 绑定的载荷。
|
||||
<Step title="Sign the payload">
|
||||
客户端对绑定挑战的载荷进行签名。
|
||||
</Step>
|
||||
<Step title="发送设备 nonce">
|
||||
客户端发送 `connect.params.device.nonce`，并使用相同的 challenge nonce。
|
||||
<Step title="Send the device nonce">
|
||||
客户端发送带有相同挑战 nonce 的 `connect.params.device.nonce`。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
如果 `openclaw devices rotate` / `revoke` / `remove` 意外被拒绝：
|
||||
|
||||
- 已配对设备令牌会话只能管理**自己的**设备，除非调用方也具有 `operator.admin`
|
||||
- `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的 operator 作用域
|
||||
- 已配对设备令牌会话只能管理**自己的**设备，除非调用方还拥有 `operator.admin`
|
||||
- `openclaw devices rotate --scope ...` 只能请求调用方会话已经持有的操作员作用域
|
||||
|
||||
相关：
|
||||
|
||||
- [配置](/zh-CN/gateway/configuration)（Gateway 网关认证模式）
|
||||
- [配置](/zh-CN/gateway/configuration)（Gateway 网关身份验证模式）
|
||||
- [控制 UI](/zh-CN/web/control-ui)
|
||||
- [设备](/zh-CN/cli/devices)
|
||||
- [远程访问](/zh-CN/gateway/remote)
|
||||
- [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)
|
||||
- [受信任代理身份验证](/zh-CN/gateway/trusted-proxy-auth)
|
||||
|
||||
## Gateway 网关服务未运行
|
||||
|
||||
当服务已安装但进程无法保持运行时使用此项。
|
||||
在服务已安装但进程无法保持运行时使用此项。
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -283,33 +283,34 @@ openclaw gateway status --deep # also scan system-level services
|
||||
|
||||
查找：
|
||||
|
||||
- `Runtime: stopped` 以及退出提示。
|
||||
- 带有退出提示的 `Runtime: stopped`。
|
||||
- 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。
|
||||
- 端口/监听器冲突。
|
||||
- 使用 `--deep` 时出现额外的 launchd/systemd/schtasks 安装。
|
||||
- `Other gateway-like services detected (best effort)` 清理提示。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="常见特征">
|
||||
- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 本地 Gateway 网关模式未启用，或配置文件被覆盖并丢失了 `gateway.mode`。修复：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。
|
||||
- `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径（令牌/密码，或已配置的受信任代理）的情况下绑定到非 loopback 地址。
|
||||
<Accordion title="Common signatures">
|
||||
- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 本地 Gateway 网关模式未启用，或者配置文件被覆盖并丢失了 `gateway.mode`。修复：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 来重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。
|
||||
- `refusing to bind gateway ... without auth` → 没有有效 Gateway 网关身份验证路径（令牌/密码，或已配置的受信任代理）时绑定到了非环回地址。
|
||||
- `another gateway instance is already listening` / `EADDRINUSE` → 端口冲突。
|
||||
- `Other gateway-like services detected (best effort)` → 存在陈旧或并行的 launchd/systemd/schtasks 单元。大多数设置应在每台机器上保留一个 Gateway 网关；如果确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。
|
||||
- 来自 Doctor 的 `System-level OpenClaw gateway service detected` → 存在一个 systemd 系统单元，而用户级服务缺失。在允许 Doctor 安装用户服务之前移除或禁用重复项，或者如果系统单元是预期的监督器，请设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
|
||||
- `Gateway service port does not match current gateway config` → 已安装的监督器仍然固定旧的 `--port`。运行 `openclaw doctor --fix` 或 `openclaw gateway install --force`，然后重启 Gateway 网关服务。
|
||||
- `Other gateway-like services detected (best effort)` → 存在陈旧或并行的 launchd/systemd/schtasks 单元。多数设置应在每台机器上只保留一个 Gateway 网关；如果确实需要多个，请隔离端口 + 配置/状态/工作区。请参阅 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。
|
||||
- Doctor 输出的 `System-level OpenClaw gateway service detected` → 存在 systemd 系统单元，而用户级服务缺失。在允许 Doctor 安装用户服务之前，移除或禁用重复项；如果该系统单元是预期的监督器，请设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
|
||||
- `Gateway service port does not match current gateway config` → 已安装的监督器仍固定旧的 `--port`。运行 `openclaw doctor --fix` 或 `openclaw gateway install --force`，然后重启 Gateway 网关服务。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
相关：
|
||||
|
||||
- [后台执行和进程工具](/zh-CN/gateway/background-process)
|
||||
- [后台 exec 和进程工具](/zh-CN/gateway/background-process)
|
||||
- [配置](/zh-CN/gateway/configuration)
|
||||
- [Doctor](/zh-CN/gateway/doctor)
|
||||
|
||||
## Gateway 网关恢复了最后已知良好配置
|
||||
## Gateway 网关拒绝了无效配置
|
||||
|
||||
当 Gateway 网关启动，但日志显示它恢复了 `openclaw.json` 时使用此项。
|
||||
在 Gateway 网关启动因 `Invalid config` 失败，或热重载日志提示
|
||||
它跳过了无效编辑时使用此项。
|
||||
|
||||
```bash
|
||||
openclaw logs --follow
|
||||
@ -320,22 +321,22 @@ openclaw doctor
|
||||
|
||||
查找：
|
||||
|
||||
- `Config auto-restored from last-known-good`
|
||||
- `gateway: invalid config was restored from last-known-good backup`
|
||||
- `config reload restored last-known-good config after invalid-config`
|
||||
- 活动配置旁带时间戳的 `openclaw.json.clobbered.*` 文件
|
||||
- 以 `Config recovery warning` 开头的主智能体系统事件
|
||||
- `Invalid config at ...`
|
||||
- `config reload skipped (invalid config): ...`
|
||||
- `Config write rejected: ...`
|
||||
- 活动配置旁带时间戳的 `openclaw.json.rejected.*` 文件
|
||||
- 如果 `doctor --fix` 修复了损坏的直接编辑，则会有带时间戳的 `openclaw.json.clobbered.*` 文件
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="发生了什么">
|
||||
- 被拒绝的配置在启动或热重载期间未通过验证。
|
||||
- OpenClaw 将被拒绝的载荷保留为 `.clobbered.*`。
|
||||
- 活动配置已从最后一次验证通过的最后已知良好副本恢复。
|
||||
- 下一个主智能体轮次会收到警告，不要盲目重写被拒绝的配置。
|
||||
- 如果所有验证问题都位于 `plugins.entries.<id>...` 下，OpenClaw 不会恢复整个文件。插件本地故障会保持显眼，而不相关的用户设置仍保留在活动配置中。
|
||||
<Accordion title="What happened">
|
||||
- 配置在启动、热重载或 OpenClaw 拥有的写入期间未通过验证。
|
||||
- Gateway 网关启动会失败关闭，而不是重写 `openclaw.json`。
|
||||
- 热重载会跳过无效的外部编辑，并保持当前运行时配置处于活动状态。
|
||||
- OpenClaw 拥有的写入会在提交前拒绝无效/破坏性载荷，并保存 `.rejected.*`。
|
||||
- `openclaw doctor --fix` 负责修复。它可以移除非 JSON 前缀，或恢复最后已知良好副本，同时将被拒绝的载荷保留为 `.clobbered.*`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="检查和修复">
|
||||
<Accordion title="Inspect and repair">
|
||||
```bash
|
||||
CONFIG="$(openclaw config file)"
|
||||
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
|
||||
@ -344,20 +345,21 @@ openclaw doctor
|
||||
openclaw doctor
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="常见特征">
|
||||
- `.clobbered.*` 存在 → 外部直接编辑或启动读取已被恢复。
|
||||
- `.rejected.*` 存在 → OpenClaw 拥有的配置写入在提交前未通过 schema 或覆盖检查。
|
||||
- `Config write rejected:` → 写入试图丢弃必需结构、让文件大幅缩小，或持久化无效配置。
|
||||
- `Rejected validation details:` → 恢复日志或主智能体通知包含导致恢复的 schema 路径，例如 `agents.defaults.execution` 或 `gateway.auth.password.source`。
|
||||
- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为被覆盖，因为与最后已知良好备份相比，它丢失了字段或大小减少。
|
||||
- `Config last-known-good promotion skipped` → 候选项包含经过脱敏的密钥占位符，例如 `***`。
|
||||
<Accordion title="Common signatures">
|
||||
- 存在 `.clobbered.*` → Doctor 在修复活动配置时保留了损坏的外部编辑。
|
||||
- 存在 `.rejected.*` → OpenClaw 拥有的配置写入在提交前未通过 schema 或覆盖检查。
|
||||
- `Config write rejected:` → 写入尝试丢弃必需结构、大幅缩小文件，或持久化无效配置。
|
||||
- `config reload skipped (invalid config):` → 直接编辑未通过验证，并被正在运行的 Gateway 网关忽略。
|
||||
- `Invalid config at ...` → 启动在 Gateway 网关服务启动前失败。
|
||||
- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → OpenClaw 拥有的写入被拒绝，因为相比最后已知良好备份，它丢失了字段或大小。
|
||||
- `Config last-known-good promotion skipped` → 候选内容包含已遮盖的密钥占位符，例如 `***`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="修复选项">
|
||||
1. 如果恢复后的活动配置正确，请保留它。
|
||||
2. 仅从 `.clobbered.*` 或 `.rejected.*` 复制预期键，然后使用 `openclaw config set` 或 `config.patch` 应用它们。
|
||||
<Accordion title="Fix options">
|
||||
1. 运行 `openclaw doctor --fix`，让 Doctor 修复带前缀/被覆盖的配置，或恢复最后已知良好配置。
|
||||
2. 仅从 `.clobbered.*` 或 `.rejected.*` 复制预期键名，然后使用 `openclaw config set` 或 `config.patch` 应用它们。
|
||||
3. 在重启前运行 `openclaw config validate`。
|
||||
4. 如果手动编辑，请保留完整 JSON5 配置，而不只是你想更改的局部对象。
|
||||
4. 如果你手动编辑，请保留完整 JSON5 配置，而不只是你想修改的部分对象。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -370,7 +372,7 @@ openclaw doctor
|
||||
|
||||
## Gateway 网关探测警告
|
||||
|
||||
当 `openclaw gateway probe` 能够到达某个对象，但仍打印警告块时使用此项。
|
||||
在 `openclaw gateway probe` 访问到某个目标，但仍打印警告块时使用此项。
|
||||
|
||||
```bash
|
||||
openclaw gateway probe
|
||||
@ -381,16 +383,16 @@ openclaw gateway probe --ssh user@gateway-host
|
||||
查找：
|
||||
|
||||
- JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。
|
||||
- 警告是否与 SSH 回退、多个 Gateway 网关、缺失作用域或未解析的认证引用有关。
|
||||
- 警告是否与 SSH 回退、多个 Gateway 网关、缺失作用域或未解析的身份验证引用有关。
|
||||
|
||||
常见特征：
|
||||
|
||||
- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍然尝试了直接配置目标/loopback 目标。
|
||||
- `multiple reachable gateways detected` → 多个目标有响应。通常这表示有意的多 Gateway 网关设置，或陈旧/重复的监听器。
|
||||
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详情 RPC 受作用域限制；请配对设备身份，或使用带有 `operator.read` 的凭据。
|
||||
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → 连接成功，但完整诊断 RPC 集超时或失败。将其视为可到达但诊断降级的 Gateway 网关；在 `--json` 输出中比较 `connect.ok` 和 `connect.rpcOk`。
|
||||
- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关有响应，但此客户端在正常 operator 访问前仍需要配对/批准。
|
||||
- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 此命令路径中，失败目标的认证材料不可用。
|
||||
- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但该命令仍尝试了直接配置/环回目标。
|
||||
- `multiple reachable gateways detected` → 有多个目标响应。通常这意味着有意的多 Gateway 网关设置，或陈旧/重复的监听器。
|
||||
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；请配对设备身份，或使用具有 `operator.read` 的凭据。
|
||||
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → 连接成功，但完整诊断 RPC 集超时或失败。将其视为可达但诊断能力降级的 Gateway 网关；比较 `--json` 输出中的 `connect.ok` 和 `connect.rpcOk`。
|
||||
- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但此客户端仍需要配对/批准后才能获得正常操作员访问权限。
|
||||
- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 失败目标在此命令路径中无法使用身份验证材料。
|
||||
|
||||
相关：
|
||||
|
||||
@ -398,9 +400,9 @@ openclaw gateway probe --ssh user@gateway-host
|
||||
- [同一主机上的多个 Gateway 网关](/zh-CN/gateway#multiple-gateways-same-host)
|
||||
- [远程访问](/zh-CN/gateway/remote)
|
||||
|
||||
## 渠道已连接，但消息未流动
|
||||
## 渠道已连接，但消息没有流动
|
||||
|
||||
如果渠道状态为已连接但消息流已停止，请关注策略、权限和渠道特定的投递规则。
|
||||
如果渠道状态为已连接但消息流已中断，请重点检查策略、权限和特定渠道的投递规则。
|
||||
|
||||
```bash
|
||||
openclaw channels status --probe
|
||||
@ -413,13 +415,13 @@ openclaw config get channels
|
||||
查找：
|
||||
|
||||
- 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。
|
||||
- 群组 allowlist 和提及要求。
|
||||
- 群组允许列表和提及要求。
|
||||
- 缺少渠道 API 权限/作用域。
|
||||
|
||||
常见特征：
|
||||
|
||||
- `mention required` → 消息被群组提及策略忽略。
|
||||
- `pairing` / 待批准跟踪信息 → 发送者未获批准。
|
||||
- `mention required` → 消息因群组提及策略被忽略。
|
||||
- `pairing` / 待批准跟踪 → 发送者未获批准。
|
||||
- `missing_scope`、`not_in_channel`、`Forbidden`、`401/403` → 渠道认证/权限问题。
|
||||
|
||||
相关：
|
||||
@ -431,7 +433,7 @@ openclaw config get channels
|
||||
|
||||
## Cron 和 Heartbeat 投递
|
||||
|
||||
如果 cron 或 Heartbeat 未运行或未投递，请先验证调度器状态，再验证投递目标。
|
||||
如果 cron 或 Heartbeat 没有运行或没有投递，请先验证调度器状态，再验证投递目标。
|
||||
|
||||
```bash
|
||||
openclaw cron status
|
||||
@ -441,21 +443,21 @@ openclaw system heartbeat last
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
检查：
|
||||
查找：
|
||||
|
||||
- Cron 已启用，并且存在下一次唤醒。
|
||||
- Cron 已启用，并且存在下一次唤醒时间。
|
||||
- 作业运行历史状态（`ok`、`skipped`、`error`）。
|
||||
- Heartbeat 跳过原因（`quiet-hours`、`requests-in-flight`、`cron-in-progress`、`lanes-busy`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="常见特征">
|
||||
<Accordion title="Common signatures">
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。
|
||||
- `cron: timer tick failed` → 调度器 tick 失败；检查文件/日志/运行时错误。
|
||||
- `heartbeat skipped` 且 `reason=quiet-hours` → 不在活跃时间窗口内。
|
||||
- `heartbeat skipped` 且 `reason=quiet-hours` → 当前不在活动时间窗口内。
|
||||
- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / markdown 标题，因此 OpenClaw 会跳过模型调用。
|
||||
- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但此 tick 没有到期任务。
|
||||
- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但本次 tick 没有任何任务到期。
|
||||
- `heartbeat: unknown accountId` → Heartbeat 投递目标的账号 ID 无效。
|
||||
- `heartbeat skipped` 且 `reason=dm-blocked` → Heartbeat 目标解析为私信式目的地，而 `agents.defaults.heartbeat.directPolicy`（或按智能体覆盖项）设置为 `block`。
|
||||
- `heartbeat skipped` 且 `reason=dm-blocked` → Heartbeat 目标解析为私信式目的地，而 `agents.defaults.heartbeat.directPolicy`（或单智能体覆盖项）设置为 `block`。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -478,18 +480,18 @@ openclaw logs --follow
|
||||
openclaw status
|
||||
```
|
||||
|
||||
检查：
|
||||
查找：
|
||||
|
||||
- 节点在线，并具备预期能力。
|
||||
- 摄像头/麦克风/位置/屏幕的操作系统权限授权。
|
||||
- Exec 批准和 allowlist 状态。
|
||||
- 摄像头/麦克风/定位/屏幕的操作系统权限授予。
|
||||
- Exec 批准和允许列表状态。
|
||||
|
||||
常见特征：
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须位于前台。
|
||||
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少操作系统权限。
|
||||
- `SYSTEM_RUN_DENIED: approval required` → exec 批准待处理。
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被 allowlist 阻止。
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表阻止。
|
||||
|
||||
相关：
|
||||
|
||||
@ -499,7 +501,7 @@ openclaw status
|
||||
|
||||
## 浏览器工具失败
|
||||
|
||||
当浏览器工具操作失败但 Gateway 网关本身健康时，使用此部分。
|
||||
当浏览器工具操作失败但 Gateway 网关本身健康时使用此项。
|
||||
|
||||
```bash
|
||||
openclaw browser status
|
||||
@ -509,41 +511,41 @@ openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
检查：
|
||||
查找：
|
||||
|
||||
- 是否设置了 `plugins.allow`，并且包含 `browser`。
|
||||
- `plugins.allow` 是否已设置并包含 `browser`。
|
||||
- 有效的浏览器可执行文件路径。
|
||||
- CDP 配置文件可达性。
|
||||
- `existing-session` / `user` 配置文件的本地 Chrome 可用性。
|
||||
- CDP 配置可达性。
|
||||
- `existing-session` / `user` 配置的本地 Chrome 可用性。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="插件 / 可执行文件特征">
|
||||
<Accordion title="Plugin / executable signatures">
|
||||
- `unknown command "browser"` 或 `unknown command 'browser'` → 内置浏览器插件被 `plugins.allow` 排除。
|
||||
- 浏览器工具缺失 / 不可用，而 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此插件从未加载。
|
||||
- 浏览器工具缺失 / 不可用，而 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此该插件从未加载。
|
||||
- `Failed to start Chrome CDP on port` → 浏览器进程启动失败。
|
||||
- `browser.executablePath not found` → 配置的路径无效。
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的方案，例如 `file:` 或 `ftp:`。
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不支持的协议，例如 `file:` 或 `ftp:`。
|
||||
- `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。
|
||||
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装缺少核心浏览器运行时依赖；重新安装或更新 OpenClaw，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍可工作，但导航、AI 快照、CSS 选择器元素截图和 PDF 导出仍不可用。
|
||||
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装缺少核心浏览器运行时依赖；重新安装或更新 OpenClaw，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍然可用，但导航、AI 快照、CSS 选择器元素截图以及 PDF 导出仍不可用。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Chrome MCP / existing-session 特征">
|
||||
- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 还无法附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器打开，批准第一次附加提示，然后重试。如果不需要已登录状态，优先使用托管的 `openclaw` 配置文件。
|
||||
- `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。
|
||||
<Accordion title="Chrome MCP / existing-session signatures">
|
||||
- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 尚无法附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器打开，批准首次附加提示，然后重试。如果不需要登录状态，优先使用托管的 `openclaw` 配置。
|
||||
- `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置没有打开的本地 Chrome 标签页。
|
||||
- `Remote CDP for profile "<name>" is not reachable` → 配置的远程 CDP 端点无法从 Gateway 网关主机访问。
|
||||
- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可达目标，或者 HTTP 端点已响应但 CDP WebSocket 仍无法打开。
|
||||
- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置没有可达目标，或 HTTP 端点有响应，但 CDP WebSocket 仍无法打开。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="元素 / 截图 / 上传特征">
|
||||
<Accordion title="Element / screenshot / upload signatures">
|
||||
- `fullPage is not supported for element screenshots` → 截图请求将 `--full-page` 与 `--ref` 或 `--element` 混用。
|
||||
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 截图调用必须使用页面捕获或快照 `--ref`，不能使用 CSS `--element`。
|
||||
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要快照引用，而不是 CSS 选择器。
|
||||
- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件上，每次调用发送一个上传。
|
||||
- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件上的对话框钩子不支持超时覆盖。
|
||||
- `existing-session type does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:type` 省略 `timeoutMs`，或者在需要自定义超时时使用托管/CDP 浏览器配置文件。
|
||||
- `existing-session evaluate does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:evaluate` 省略 `timeoutMs`，或者在需要自定义超时时使用托管/CDP 浏览器配置文件。
|
||||
- `response body is not supported for existing-session profiles yet.` → `responsebody` 仍需要托管浏览器或原始 CDP 配置文件。
|
||||
- 附加专用或远程 CDP 配置文件上的过期视口 / 深色模式 / 区域设置 / 离线覆盖 → 运行 `openclaw browser stop --browser-profile <name>` 以关闭活跃控制会话并释放 Playwright/CDP 仿真状态，而无需重启整个 Gateway 网关。
|
||||
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要快照 ref，而不是 CSS 选择器。
|
||||
- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置上，每次调用发送一个上传文件。
|
||||
- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置上的对话框钩子不支持超时覆盖。
|
||||
- `existing-session type does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置上的 `act:type` 省略 `timeoutMs`，或在需要自定义超时时使用托管/CDP 浏览器配置。
|
||||
- `existing-session evaluate does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置上的 `act:evaluate` 省略 `timeoutMs`，或在需要自定义超时时使用托管/CDP 浏览器配置。
|
||||
- `response body is not supported for existing-session profiles yet.` → `responsebody` 仍需要托管浏览器或原始 CDP 配置。
|
||||
- 仅附加或远程 CDP 配置上的过期视口 / 深色模式 / 区域设置 / 离线覆盖项 → 运行 `openclaw browser stop --browser-profile <name>` 关闭活动控制会话并释放 Playwright/CDP 模拟状态，无需重启整个 Gateway 网关。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -553,12 +555,12 @@ openclaw doctor
|
||||
- [浏览器（OpenClaw 托管）](/zh-CN/tools/browser)
|
||||
- [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)
|
||||
|
||||
## 如果你升级后某些内容突然损坏
|
||||
## 如果你升级后某些内容突然坏了
|
||||
|
||||
大多数升级后的故障来自配置漂移，或现在开始执行的更严格默认值。
|
||||
大多数升级后故障都是配置漂移，或现在开始强制执行更严格的默认值。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="1. 认证和 URL 覆盖行为已更改">
|
||||
<Accordion title="1. Auth and URL override behavior changed">
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw config get gateway.mode
|
||||
@ -566,10 +568,10 @@ openclaw doctor
|
||||
openclaw config get gateway.auth.mode
|
||||
```
|
||||
|
||||
要检查的内容：
|
||||
检查内容：
|
||||
|
||||
- 如果 `gateway.mode=remote`，CLI 调用可能会指向远程，而你的本地服务是正常的。
|
||||
- 显式 `--url` 调用不会回退到已存储的凭据。
|
||||
- 显式 `--url` 调用不会回退到已存储凭证。
|
||||
|
||||
常见特征：
|
||||
|
||||
@ -577,7 +579,7 @@ openclaw doctor
|
||||
- `unauthorized` → 端点可达，但认证错误。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. 绑定和认证护栏更严格">
|
||||
<Accordion title="2. Bind and auth guardrails are stricter">
|
||||
```bash
|
||||
openclaw config get gateway.bind
|
||||
openclaw config get gateway.auth.mode
|
||||
@ -586,18 +588,18 @@ openclaw doctor
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
要检查的内容：
|
||||
检查内容：
|
||||
|
||||
- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享令牌/密码认证，或配置正确的非 loopback `trusted-proxy` 部署。
|
||||
- 像 `gateway.token` 这样的旧键不会替代 `gateway.auth.token`。
|
||||
- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token/密码认证，或配置正确的非 loopback `trusted-proxy` 部署。
|
||||
- `gateway.token` 等旧键不能替代 `gateway.auth.token`。
|
||||
|
||||
常见特征：
|
||||
|
||||
- `refusing to bind gateway ... without auth` → 非 loopback 绑定没有有效的 Gateway 网关认证路径。
|
||||
- `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径。
|
||||
- `Connectivity probe: failed`，但运行时正在运行 → Gateway 网关存活，但使用当前认证/url 无法访问。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. 配对和设备身份状态已更改">
|
||||
<Accordion title="3. Pairing and device identity state changed">
|
||||
```bash
|
||||
openclaw devices list
|
||||
openclaw pairing list --channel <channel> [--account <id>]
|
||||
@ -605,20 +607,20 @@ openclaw doctor
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
要检查的内容：
|
||||
检查内容：
|
||||
|
||||
- dashboard/节点的设备批准待处理。
|
||||
- 策略或身份更改后的私信配对批准待处理。
|
||||
- 仪表板/节点存在待处理设备批准。
|
||||
- 策略或身份变更后存在待处理私信配对批准。
|
||||
|
||||
常见特征：
|
||||
|
||||
- `device identity required` → 设备认证未满足。
|
||||
- `pairing required` → 发送者/设备必须获批准。
|
||||
- `pairing required` → 发送者/设备必须获批。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
如果检查后服务配置和运行时仍不一致，请从同一配置文件/状态目录重新安装服务元数据：
|
||||
如果检查后服务配置和运行时仍不一致，请从同一个配置/状态目录重新安装服务元数据：
|
||||
|
||||
```bash
|
||||
openclaw gateway install --force
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,28 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- 安装或配置插件
|
||||
- 了解插件发现和加载规则
|
||||
- 了解插件发现与加载规则
|
||||
- 使用与 Codex/Claude 兼容的插件包
|
||||
sidebarTitle: Install and Configure
|
||||
summary: 安装、配置和管理 OpenClaw 插件
|
||||
title: 插件
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T15:53:26Z"
|
||||
generated_at: "2026-05-03T17:11:02Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 937623bf3bfd7832680264b28deaef58970b35fdae7cfa0e5731c097eccc38e6
|
||||
source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0
|
||||
source_path: tools/plugin.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
插件为 OpenClaw 扩展新能力：渠道、模型提供商、智能体执行框架、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起提供），另一些是**外部**插件。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。在迁移完成之前，npm 仍支持直接安装，也会临时承载一组 OpenClaw 拥有的插件包。
|
||||
插件为 OpenClaw 扩展新能力：渠道、模型提供商、智能体运行框架、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。一些插件是 **核心**（随 OpenClaw 分发），另一些是 **外部**。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。在该迁移完成之前，npm 仍支持直接安装，以及一组临时的 OpenClaw 自有插件包。
|
||||
|
||||
## 快速开始
|
||||
|
||||
如需可直接复制粘贴的安装、列表查看、卸载、更新和发布示例，请参阅[管理插件](/zh-CN/plugins/manage-plugins)。
|
||||
如需可直接复制粘贴的安装、列出、卸载、更新和发布示例，请参阅
|
||||
[管理插件](/zh-CN/plugins/manage-plugins)。
|
||||
|
||||
<Steps>
|
||||
<Step title="查看已加载的内容">
|
||||
<Step title="查看已加载内容">
|
||||
```bash
|
||||
openclaw plugins list
|
||||
```
|
||||
@ -58,9 +59,10 @@ x-i18n:
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="聊天原生管理">
|
||||
在运行中的 Gateway 网关里，仅限所有者使用的 `/plugins enable` 和 `/plugins disable`
|
||||
会触发 Gateway 网关配置重新加载器。Gateway 网关会在进程内重新加载插件运行时表面，新的智能体轮次会从刷新后的注册表重建工具列表。`/plugins install` 会更改插件源代码，因此 Gateway 网关会请求重启，而不是假装当前进程可以安全地重新加载已经导入的模块。
|
||||
<Step title="聊天内原生管理">
|
||||
在运行中的 Gateway 网关中，仅所有者可用的 `/plugins enable` 和 `/plugins disable`
|
||||
会触发 Gateway 网关配置重新加载器。Gateway 网关会在进程内重新加载插件运行时接口面，新的智能体轮次会从刷新后的注册表重建工具列表。`/plugins install`
|
||||
会更改插件源代码，因此 Gateway 网关会请求重启，而不是假定当前进程可以安全地重新加载已经导入的模块。
|
||||
|
||||
</Step>
|
||||
|
||||
@ -72,12 +74,12 @@ 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>
|
||||
@ -85,40 +87,49 @@ x-i18n:
|
||||
/plugin enable <plugin-id>
|
||||
```
|
||||
|
||||
安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 `clawhub:<pkg>`、显式 `npm:<pkg>`、显式 `git:<repo>`，或通过 npm 解析的裸包规范。
|
||||
安装路径使用与 CLI 相同的解析器：本地路径/归档、显式
|
||||
`clawhub:<pkg>`、显式 `npm:<pkg>`、显式 `git:<repo>`，或通过 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 网关启动期间，无效的插件配置会像任何其他无效配置一样导致启动拒绝继续。运行 `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` 安装。
|
||||
使用 `openclaw plugins list --json` 可以查看每个可见插件的静态 `dependencyStatus`，无需导入运行时代码或修复依赖。
|
||||
有关安装时生命周期，请参阅[插件依赖解析](/zh-CN/plugins/dependency-resolution)。
|
||||
插件依赖安装只会在显式安装/更新或 Doctor 修复流程中发生。Gateway 网关启动、配置重新加载和运行时检查不会运行包管理器，也不会修复依赖树。本地插件必须已经安装好依赖，而 npm、git 和 ClawHub 插件会安装到 OpenClaw 的托管插件根目录下。npm 依赖可能会在 OpenClaw 的托管 npm 根目录内提升；安装/更新会先扫描该托管根目录再信任它，卸载会通过 npm 移除由 npm 管理的包。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。
|
||||
使用 `openclaw plugins list --json` 可以查看每个可见插件的静态 `dependencyStatus`，而无需导入运行时代码或修复依赖。
|
||||
有关安装时生命周期，请参阅 [插件依赖解析](/zh-CN/plugins/dependency-resolution)。
|
||||
|
||||
对于 npm 安装，`latest` 或 dist-tag 等可变选择器会在安装前解析，然后固定到 OpenClaw 托管 npm 根目录中的精确已验证版本。npm 完成后，OpenClaw 会验证已安装的 `package-lock.json` 条目仍与解析出的版本和完整性匹配。如果 npm 写入了不同的包元数据，安装会失败，并回滚托管包，而不是接受不同的插件工件。
|
||||
对于 npm 安装，`latest` 或分发标签等可变选择器会在安装前解析，然后固定到 OpenClaw 托管 npm 根目录中经过精确验证的版本。npm 完成后，OpenClaw 会验证已安装的
|
||||
`package-lock.json` 条目仍然匹配解析出的版本和完整性。如果 npm 写入了不同的包元数据，安装会失败并回滚托管包，而不是接受不同的插件制品。
|
||||
|
||||
源码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置插件，请运行 `pnpm install`；随后 OpenClaw 会从 `extensions/<id>` 加载内置插件，因此编辑内容和包本地依赖会被直接使用。普通 npm 根目录安装适用于打包版 OpenClaw，而不是源码检出开发。
|
||||
源码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置插件，请运行 `pnpm install`；随后 OpenClaw 会从
|
||||
`extensions/<id>` 加载内置插件，以便直接使用编辑内容和包本地依赖。
|
||||
普通的 npm 根目录安装适用于打包版 OpenClaw，而不是源码检出开发。
|
||||
|
||||
## 插件类型
|
||||
|
||||
OpenClaw 识别两种插件格式：
|
||||
|
||||
| 格式 | 工作方式 | 示例 |
|
||||
| 格式 | 工作方式 | 示例 |
|
||||
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
|
||||
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
|
||||
| **Bundle** | Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
|
||||
| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
|
||||
| **包** | 兼容 Codex/Claude/Cursor 的布局；映射为 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
|
||||
|
||||
两者都会显示在 `openclaw plugins list` 下。有关 Bundle 详情，请参阅[插件 Bundle](/zh-CN/plugins/bundles)。
|
||||
两者都会显示在 `openclaw plugins list` 中。有关插件包的详细信息，请参阅 [插件包](/zh-CN/plugins/bundles)。
|
||||
|
||||
如果你正在编写原生插件，请从[构建插件](/zh-CN/plugins/building-plugins)和[插件 SDK 概览](/zh-CN/plugins/sdk-overview)开始。
|
||||
如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins)
|
||||
和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
|
||||
|
||||
## 包入口点
|
||||
|
||||
原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。每个条目都必须保留在包目录内部，并解析为可读取的运行时文件，或解析为一个 TypeScript 源文件，其内推的已构建 JavaScript 对等文件例如从 `src/index.ts` 到 `dist/index.js`。
|
||||
打包安装必须随包提供该 JavaScript 运行时输出。TypeScript 源码回退用于源码检出和本地开发路径，而不是用于安装到 OpenClaw 托管插件根目录中的 npm 包。
|
||||
原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。
|
||||
每个条目都必须位于包目录内，并解析为可读取的运行时文件，或解析为一个 TypeScript 源文件，且能够推断出对应的已构建 JavaScript 对等文件，例如从 `src/index.ts` 到 `dist/index.js`。
|
||||
打包安装必须随附该 JavaScript 运行时输出。TypeScript 源码回退用于源码检出和本地开发路径，不适用于安装到 OpenClaw 托管插件根目录中的 npm 包。
|
||||
|
||||
当发布的运行时文件与源条目不在相同路径时，请使用 `openclaw.runtimeExtensions`。存在时，`runtimeExtensions` 必须为每个 `extensions` 条目包含且仅包含一个条目。列表不匹配会导致安装和插件发现失败，而不是静默回退到源码路径。如果你也发布 `openclaw.setupEntry`，请为其已构建 JavaScript 对等文件使用 `openclaw.runtimeSetupEntry`；声明时该文件是必需的。
|
||||
当发布的运行时文件与源码条目不在相同路径时，请使用 `openclaw.runtimeExtensions`。存在时，`runtimeExtensions` 必须为每个 `extensions` 条目精确包含一个条目。列表不匹配会导致安装和插件发现失败，而不会静默回退到源码路径。如果你也发布 `openclaw.setupEntry`，请为它的已构建 JavaScript 对等文件使用 `openclaw.runtimeSetupEntry`；声明后该文件必须存在。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -132,13 +143,13 @@ 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/*` 插件包已弃用，该包版本来自较旧的外部包发布序列。在更新的 npm 包发布之前，请使用当前 OpenClaw 中的内置插件或本地检出。
|
||||
|
||||
| 插件 | 包 | 文档 |
|
||||
| 插件 | 包 | 文档 |
|
||||
| --------------- | -------------------------- | ------------------------------------------ |
|
||||
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/zh-CN/channels/bluebubbles) |
|
||||
| Discord | `@openclaw/discord` | [Discord](/zh-CN/channels/discord) |
|
||||
@ -154,7 +165,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="模型提供商（默认启用）">
|
||||
@ -166,10 +177,10 @@ 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"`）
|
||||
|
||||
有关 OpenAI 兼容的嵌入设置、Ollama 示例、召回限制和故障排除，请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)。
|
||||
有关兼容 OpenAI 的嵌入设置、Ollama 示例、召回限制和故障排除，请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -178,13 +189,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)。
|
||||
|
||||
## 配置
|
||||
|
||||
@ -202,35 +213,49 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 描述 |
|
||||
| 字段 | 说明 |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| `enabled` | 总开关（默认：`true`） |
|
||||
| `allow` | 插件允许列表（可选） |
|
||||
| `deny` | 插件拒绝列表（可选；拒绝优先） |
|
||||
| `load.paths` | 额外插件文件/目录 |
|
||||
| `slots` | 独占槽选择器（例如 `memory`、`contextEngine`） |
|
||||
| `entries.\<id\>` | 单个插件的开关 + 配置 |
|
||||
| `enabled` | 总开关（默认值：`true`） |
|
||||
| `allow` | 插件允许列表（可选） |
|
||||
| `deny` | 插件拒绝列表（可选；拒绝优先） |
|
||||
| `load.paths` | 额外插件文件/目录 |
|
||||
| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） |
|
||||
| `entries.\<id\>` | 每个插件的开关 + 配置 |
|
||||
|
||||
`plugins.allow` 是独占的。当它非空时，只有列出的插件可以加载或暴露工具，即使 `tools.allow` 包含 `"*"` 或特定插件拥有的工具名称。如果某个工具允许列表引用了插件工具，请把拥有这些工具的插件 id 添加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对这种形态发出警告。
|
||||
`plugins.allow` 是排他的。当它非空时，只有列出的插件可以加载
|
||||
或暴露工具，即使 `tools.allow` 包含 `"*"` 或某个插件拥有的
|
||||
具体工具名称。如果某个工具允许列表引用插件工具，请将所属插件 ID
|
||||
添加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对此
|
||||
形态发出警告。
|
||||
|
||||
通过 `/plugins enable` 或 `/plugins disable` 做出的配置更改会触发进程内 Gateway 网关插件重新加载。新的智能体轮次会从刷新后的插件注册表重建其工具列表。安装、更新和卸载等更改源代码的操作仍会重启 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="插件状态：已禁用、缺失、无效">
|
||||
- **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。
|
||||
- **缺失**：配置引用了设备发现未找到的插件 id。
|
||||
- **无效**：插件存在，但其配置不符合声明的 schema。Gateway 网关启动时只会跳过该插件；`openclaw doctor --fix` 可以通过禁用它并移除其配置负载来隔离这个无效条目。
|
||||
- **缺失**：配置引用了设备发现未找到的插件 ID。
|
||||
- **无效**：插件存在，但其配置与声明的架构不匹配。Gateway 网关启动时只跳过该插件；`openclaw doctor --fix` 可以通过禁用该插件并移除其配置载荷来隔离无效条目。
|
||||
|
||||
</Accordion>
|
||||
|
||||
## 设备发现和优先级
|
||||
|
||||
OpenClaw 按以下顺序扫描插件（第一个匹配项优先）：
|
||||
OpenClaw 按以下顺序扫描插件（第一个匹配项生效）：
|
||||
|
||||
<Steps>
|
||||
<Step title="配置路径">
|
||||
`plugins.load.paths` — 显式文件或目录路径。指回 OpenClaw 自身打包的内置插件目录的路径会被忽略；运行 `openclaw doctor --fix` 可移除这些过时别名。
|
||||
`plugins.load.paths` — 显式文件或目录路径。指回
|
||||
OpenClaw 自身打包的内置插件目录的路径会被忽略；
|
||||
运行 `openclaw doctor --fix` 可移除这些过时别名。
|
||||
</Step>
|
||||
|
||||
<Step title="工作区插件">
|
||||
@ -242,37 +267,62 @@ OpenClaw 按以下顺序扫描插件（第一个匹配项优先）：
|
||||
</Step>
|
||||
|
||||
<Step title="内置插件">
|
||||
随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。其他插件需要显式启用。
|
||||
随 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` 包之前发现它。这样可以让维护者容器
|
||||
循环继续工作，而无需将每个内置插件都切回 TypeScript 源码。
|
||||
设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist 包，
|
||||
即使存在源覆盖挂载也是如此。
|
||||
|
||||
### 启用规则
|
||||
|
||||
- `plugins.enabled: false` 会禁用所有插件，并跳过插件设备发现/加载工作
|
||||
- `plugins.enabled: false` 会禁用所有插件，并跳过插件发现/加载工作
|
||||
- `plugins.deny` 始终优先于 allow
|
||||
- `plugins.entries.\<id\>.enabled: false` 会禁用该插件
|
||||
- 工作区来源的插件**默认禁用**（必须显式启用）
|
||||
- 内置插件遵循内置的默认启用集合，除非被覆盖
|
||||
- 独占槽可以强制启用该槽所选的插件
|
||||
- 当配置命名了插件拥有的表面时，某些内置的选择加入插件会自动启用，例如提供商模型引用、渠道配置或 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`。
|
||||
- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 只会在一次模型尝试产生助手输出之后运行。
|
||||
- 如需证明有效会话模型，请使用 `openclaw sessions` 或 Gateway 网关会话/status 表面；调试提供商负载时，请使用 `--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
|
||||
- 运行 `openclaw gateway status --deep --require-rpc`，并确认活动的
|
||||
Gateway 网关 URL、配置文件、配置路径和进程就是你正在编辑的那些。
|
||||
- 在插件安装/配置/代码变更后重启实时 Gateway 网关。在包装器
|
||||
容器中，PID 1 可能只是一个监督进程；请重启或向子
|
||||
`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 网关会话/状态表面；在调试提供商载荷时，使用
|
||||
`--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
|
||||
|
||||
### 插件工具设置缓慢
|
||||
|
||||
如果智能体轮次在准备工具时看起来停滞，请启用 trace 日志记录，并检查插件工具工厂计时行：
|
||||
如果智能体轮次看起来在准备工具时卡住，请启用 trace 日志并
|
||||
检查插件工具工厂计时行：
|
||||
|
||||
```bash
|
||||
openclaw config set logging.level trace
|
||||
@ -285,17 +335,24 @@ openclaw logs --follow
|
||||
[trace:plugin-tools] factory timings ...
|
||||
```
|
||||
|
||||
摘要会列出总工厂时间和最慢的插件工具工厂，包括插件 id、声明的工具名称、结果形态，以及该工具是否可选。当单个工厂耗时至少 1 秒或总插件工具工厂准备耗时至少 5 秒时，慢速行会提升为警告。
|
||||
摘要会列出总工厂耗时和最慢的插件工具工厂，
|
||||
包括插件 ID、声明的工具名称、结果形态，以及该工具是否
|
||||
可选。当单个工厂耗时至少 1 秒，或插件工具工厂准备总耗时至少 5 秒时，
|
||||
慢速行会提升为警告。
|
||||
|
||||
OpenClaw 会缓存使用相同有效请求上下文重复解析时成功的插件工具工厂结果。缓存键包含有效运行时配置、工作区、智能体/会话 id、沙箱策略、浏览器设置、交付上下文、请求者身份和所有权状态，因此依赖这些可信字段的工厂会在上下文变化时重新运行。
|
||||
OpenClaw 会为相同有效请求上下文下的重复解析缓存成功的插件工具工厂结果。
|
||||
缓存键包含有效运行时配置、工作区、智能体/会话 ID、沙箱策略、浏览器设置、
|
||||
交付上下文、请求者身份和所有权状态，因此依赖这些可信字段的工厂会在
|
||||
上下文变化时重新运行。
|
||||
|
||||
如果某个插件占用了大部分时间，请检查其运行时注册：
|
||||
如果某个插件占用了主要耗时，请检查其运行时注册：
|
||||
|
||||
```bash
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
```
|
||||
|
||||
然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移到工具执行路径之后，而不是在工具工厂中执行。
|
||||
然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载
|
||||
移动到工具执行路径之后，而不是在工具工厂内执行。
|
||||
|
||||
### 重复的渠道或工具所有权
|
||||
|
||||
@ -305,24 +362,35 @@ openclaw plugins inspect <plugin-id> --runtime --json
|
||||
- `channel setup already registered: <channel-id> (<plugin-id>)`
|
||||
- `plugin tool name conflict (<plugin-id>): <tool-name>`
|
||||
|
||||
这些表示有多个已启用插件试图拥有同一个渠道、设置流程或工具名称。最常见原因是在现在提供相同渠道 id 的内置插件旁边安装了外部渠道插件。
|
||||
这些表示有多个已启用插件正在尝试拥有同一个渠道、
|
||||
设置流程或工具名称。最常见的原因是一个外部渠道插件
|
||||
安装在某个现在提供相同渠道 ID 的内置插件旁边。
|
||||
|
||||
调试步骤：
|
||||
|
||||
- 运行 `openclaw plugins list --enabled --verbose` 查看每个已启用插件及其来源。
|
||||
- 对每个可疑插件运行 `openclaw plugins inspect <id> --runtime --json`，并比较 `channels`、`channelConfigs`、`tools` 和诊断。
|
||||
- 安装或移除插件包后，运行 `openclaw plugins registry --refresh`，以便持久化元数据反映当前安装。
|
||||
- 运行 `openclaw plugins list --enabled --verbose` 查看每个已启用插件
|
||||
及其来源。
|
||||
- 对每个可疑插件运行 `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 会保留该请求并
|
||||
报告冲突。请为该渠道选择一个所有者，或重命名插件拥有的
|
||||
工具，使运行时表面没有歧义。
|
||||
|
||||
## 插件槽（独占类别）
|
||||
## 插件槽位（独占类别）
|
||||
|
||||
某些类别是独占的（同一时间只能有一个处于活动状态）：
|
||||
某些类别是独占的（一次只能有一个活动项）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -335,10 +403,10 @@ openclaw plugins inspect <plugin-id> --runtime --json
|
||||
}
|
||||
```
|
||||
|
||||
| 槽 | 控制内容 | 默认值 |
|
||||
| --------------- | ---------------- | ------------------- |
|
||||
| `memory` | 主动记忆插件 | `memory-core` |
|
||||
| `contextEngine` | 活动上下文引擎 | `legacy`（内置） |
|
||||
| 槽位 | 控制内容 | 默认值 |
|
||||
| --------------- | --------------------- | ------------------- |
|
||||
| `memory` | 活动记忆插件 | `memory-core` |
|
||||
| `contextEngine` | 活动上下文引擎 | `legacy`（内置） |
|
||||
|
||||
## CLI 参考
|
||||
|
||||
@ -388,35 +456,35 @@ 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` 一起使用，因为 `--link` 会复用源路径，而不是复制到托管安装目标上。
|
||||
`--force` 会就地覆盖现有已安装的插件或钩子包。使用 `openclaw plugins update <id-or-npm-spec>` 对受跟踪的 npm 插件进行常规升级。它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到托管安装目标上。
|
||||
|
||||
当 `plugins.allow` 已设置时，`openclaw plugins install` 会在启用已安装插件之前，将该插件 ID 添加到该允许列表。如果同一个插件 ID 存在于 `plugins.deny` 中，安装会移除这个过时的 deny 条目，以便显式安装在重启后立即可加载。
|
||||
当 `plugins.allow` 已设置时，`openclaw plugins install` 会先把已安装的插件 ID 添加到该允许列表，然后再启用它。如果同一个插件 ID 存在于 `plugins.deny` 中，安装会移除这条过时的拒绝项，使显式安装的插件在重启后可以立即加载。
|
||||
|
||||
OpenClaw 会保留一个持久化的本地插件注册表，作为插件清单、贡献归属和启动规划的冷读模型。安装、更新、卸载、启用和停用流程会在更改插件状态后刷新该注册表。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保留持久安装元数据，并在 `plugins` 中保留可重建的清单元数据。如果注册表缺失、过时或无效，`openclaw plugins registry --refresh` 会从安装记录、配置策略以及清单/包元数据中重建其清单视图，而无需加载插件运行时模块。
|
||||
`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带有 dist-tag 或精确版本的 npm 包规范时，会将包名解析回已跟踪的插件记录，并记录新规范以供后续更新。传入不带版本的包名时，会把精确固定的安装切回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的构件身份，OpenClaw 会跳过更新，不下载、不重新安装，也不重写配置。
|
||||
OpenClaw 会保留一个持久化的本地插件注册表，作为插件清单、贡献归属和启动规划的冷读取模型。安装、更新、卸载、启用和禁用流程会在更改插件状态后刷新该注册表。同一个 `plugins/installs.json` 文件会把持久安装元数据保存在顶层 `installRecords` 中，并把可重建的清单元数据保存在 `plugins` 中。如果注册表缺失、过时或无效，`openclaw plugins registry --refresh` 会从安装记录、配置策略以及清单/包元数据重建其清单视图，而不加载插件运行时模块。
|
||||
`openclaw plugins update <id-or-npm-spec>` 适用于受跟踪的安装。传入带有 dist-tag 或精确版本的 npm 包规范时，会把包名解析回受跟踪的插件记录，并记录新的规范以供未来更新。传入不带版本的包名时，会把精确固定版本的安装移回注册表的默认发布线。如果已安装的 npm 插件已经与解析出的版本和记录的构件身份一致，OpenClaw 会跳过更新，不下载、不重新安装，也不重写配置。
|
||||
当 `openclaw update` 在 beta 渠道上运行时，默认线 npm 和 ClawHub 插件记录会先尝试 `@beta`，并在不存在插件 beta 版本时回退到默认/latest。精确版本和显式标签会保持固定。
|
||||
|
||||
`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 规范。
|
||||
`--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 网关支持的技能依赖安装改用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是单独的 ClawHub 技能下载/安装流程。
|
||||
|
||||
如果你在 ClawHub 上发布的插件因扫描而被隐藏或阻断，请打开 ClawHub 控制台，或运行 `clawhub package rescan <name>` 来请求 ClawHub 再次检查它。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被阻断的版本公开。
|
||||
如果你发布到 ClawHub 的插件被扫描隐藏或阻止，请打开 ClawHub 仪表板，或运行 `clawhub package rescan <name>` 请求 ClawHub 再次检查它。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描该插件，也不会让被阻止的发布变为公开。
|
||||
|
||||
兼容包参与同一套插件列表/检查/启用/停用流程。当前运行时支持包括包内 Skills、Claude 命令 Skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor 命令 Skills，以及兼容的 Codex 钩子目录。
|
||||
兼容包会参与同一个插件列表/检查/启用/禁用流程。当前运行时支持包括包内 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex 钩子目录。
|
||||
|
||||
`openclaw plugins inspect <id>` 还会报告检测到的包能力，以及由包支持的插件中受支持或不受支持的 MCP 和 LSP 服务器条目。
|
||||
|
||||
Marketplace 来源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须留在克隆的 marketplace 仓库内，并且只能使用相对路径来源。
|
||||
Marketplace 源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内，并且只能使用相对路径源。
|
||||
|
||||
了解详情请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。
|
||||
请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins) 了解详情。
|
||||
|
||||
## 插件 API 概览
|
||||
|
||||
原生插件会导出一个暴露 `register(api)` 的入口对象。较旧的插件可能仍将 `activate(api)` 用作旧版别名，但新插件应使用 `register`。
|
||||
原生插件会导出一个入口对象，该对象暴露 `register(api)`。较旧的插件可能仍使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
|
||||
|
||||
```typescript
|
||||
export default definePluginEntry({
|
||||
@ -436,21 +504,21 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为较旧的插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公开契约。
|
||||
OpenClaw 会在插件激活期间加载入口对象并调用 `register(api)`。加载器仍会为较旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
|
||||
|
||||
`api.registrationMode` 会告诉插件其入口为何被加载：
|
||||
`api.registrationMode` 会告诉插件其入口为什么被加载：
|
||||
|
||||
| 模式 | 含义 |
|
||||
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `full` | 运行时激活。注册工具、钩子、服务、命令、路由和其他实时副作用。 |
|
||||
| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可能会加载，但跳过实时副作用。 |
|
||||
| `setup-only` | 通过轻量设置入口加载渠道设置元数据。 |
|
||||
| `full` | 运行时激活。注册工具、钩子、服务、命令、路由以及其他实时副作用。 |
|
||||
| `discovery` | 只读能力发现。注册提供商和元数据；受信任的插件入口代码可以加载，但应跳过实时副作用。 |
|
||||
| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 |
|
||||
| `setup-runtime` | 还需要运行时入口的渠道设置加载。 |
|
||||
| `cli-metadata` | 仅收集 CLI 命令元数据。 |
|
||||
|
||||
会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活的，但并非免导入：OpenClaw 可能会执行可信插件入口或渠道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移动到完整运行时路径之后。
|
||||
会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活式的，但并非免导入：OpenClaw 可能会求值受信任的插件入口或渠道插件模块以构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径后面。
|
||||
|
||||
常用注册方法：
|
||||
常见注册方法：
|
||||
|
||||
| 方法 | 注册内容 |
|
||||
| --------------------------------------- | --------------------------- |
|
||||
@ -465,7 +533,7 @@ OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`
|
||||
| `registerImageGenerationProvider` | 图像生成 |
|
||||
| `registerMusicGenerationProvider` | 音乐生成 |
|
||||
| `registerVideoGenerationProvider` | 视频生成 |
|
||||
| `registerWebFetchProvider` | Web 获取 / 抓取提供商 |
|
||||
| `registerWebFetchProvider` | Web 抓取 / 抓取提供商 |
|
||||
| `registerWebSearchProvider` | Web 搜索 |
|
||||
| `registerHttpRoute` | HTTP 端点 |
|
||||
| `registerCommand` / `registerCli` | CLI 命令 |
|
||||
@ -474,22 +542,22 @@ OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`
|
||||
|
||||
类型化生命周期钩子的钩子保护行为：
|
||||
|
||||
- `before_tool_call`：`{ block: true }` 是终止性的；低优先级处理器会被跳过。
|
||||
- `before_tool_call`：`{ block: false }` 是无操作，不会清除先前的阻断。
|
||||
- `before_install`：`{ block: true }` 是终止性的；低优先级处理器会被跳过。
|
||||
- `before_install`：`{ block: false }` 是无操作，不会清除先前的阻断。
|
||||
- `message_sending`：`{ cancel: true }` 是终止性的；低优先级处理器会被跳过。
|
||||
- `message_sending`：`{ cancel: false }` 是无操作，不会清除先前的取消。
|
||||
- `before_tool_call`：`{ block: true }` 是终止性的；较低优先级的处理程序会被跳过。
|
||||
- `before_tool_call`：`{ block: false }` 是无操作，并且不会清除先前的阻止。
|
||||
- `before_install`：`{ block: true }` 是终止性的；较低优先级的处理程序会被跳过。
|
||||
- `before_install`：`{ block: false }` 是无操作，并且不会清除先前的阻止。
|
||||
- `message_sending`：`{ cancel: true }` 是终止性的；较低优先级的处理程序会被跳过。
|
||||
- `message_sending`：`{ cancel: false }` 是无操作，并且不会清除先前的取消。
|
||||
|
||||
原生 Codex 应用服务器会把 Codex 原生工具事件桥接回这个钩子表面。插件可以通过 `before_tool_call` 阻断原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该桥接目前尚不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界位于 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。
|
||||
原生 Codex app-server 会把 Codex 原生工具事件桥接回这个钩子表面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该桥接目前还不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界位于 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。
|
||||
|
||||
完整的类型化钩子行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
|
||||
完整的类型化钩子行为请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
|
||||
|
||||
## 相关内容
|
||||
## 相关
|
||||
|
||||
- [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件
|
||||
- [插件包](/zh-CN/plugins/bundles) — Codex/Claude/Cursor 包兼容性
|
||||
- [插件清单](/zh-CN/plugins/manifest) — 清单 schema
|
||||
- [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
|
||||
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线
|
||||
- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载管线
|
||||
- [社区插件](/zh-CN/plugins/community) — 第三方列表
|
||||
|
||||
Loading…
Reference in New Issue
Block a user