openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-24 04:57:15 +00:00
parent f4a4266bd8
commit 7dd71f873c
2 changed files with 366 additions and 364 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

289
docs/zh-CN/help/testing-live.md
View File

@ -7,105 +7,105 @@ sidebarTitle: Live tests
summary: 实时（涉及网络）的测试：模型矩阵、CLI 后端、ACP、媒体提供商、凭证
title: 测试：实时测试套件
x-i18n:
generated_at: "2026-04-24T04:20:46Z"
generated_at: "2026-04-24T04:55:21Z"
model: gpt-5.4
provider: openai
source_hash: db73b9ad5c15569f5772a91d0d2532923015bf98a21da9c833c59a9cfa5cec4e
source_hash: 2a2f29767c3f8595d76c7502b1319e329dc87232cbde8fe205a83476b297f8af
source_path: help/testing-live.md
workflow: 15
---
如需了解快速开始、QA 运行器、单元/集成测试套件以及 Docker 流程，请参阅
如需了解快速开始、QA 运行器、单元/集成测试以及 Docker 流程，请参阅
[测试](/zh-CN/help/testing)。本页介绍**实时**（涉及网络）的测试
套件：模型矩阵、CLI 后端、ACP 和媒体提供商实时测试，以及
凭证处理。
## 实时：Android 节点能力全面检查
## 实时：Android 节点能力扫描
- 测试：`src/gateway/android-node.capabilities.live.test.ts`
- 脚本：`pnpm android:test:integration`
- 目标：调用已连接 Android 节点当前**发布的每一个命令**，并断言命令契约行为。
- 目标：调用已连接 Android 节点当前**宣告的每一条命令**，并断言命令契约行为。
- 范围：
- 预设条件 / 手动设置（该测试套件不会安装 / 运行 / 配对应用）。
- 针对所选 Android 节点逐个命令进行 Gateway 网关 `node.invoke` 校验。
- 预先准备 / 手动设置（该套件不会安装 / 运行 / 配对应用）。
- 针对所选 Android 节点，逐条进行 Gateway 网关 `node.invoke` 验证。
- 必需的预先设置：
- Android 应用已连接并与 Gateway 网关配对。
- 应用保持在前台。
- 已为你期望通过的能力授予权限 / 捕获同意。
- 应用保持在前台运行。
- 已授予你期望通过的能力所需的权限 / 捕获同意。
- 可选目标覆盖：
- `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。
- 完整 Android 设置详情： [Android App](/zh-CN/platforms/android)
## 实时：模型冒烟测试（配置档键）
## 实时：模型冒烟测试（profile 键）
实时测试分为两层，以便我们隔离故障：
- “Direct model” 用于确认提供商 / 模型在给定密钥下是否至少能够响应。
- “Gateway smoke” 用于确认该模型的完整 Gateway 网关 + 智能体流水线正常工作（会话、历史记录、工具、沙箱策略等）。
- “Direct model” 用于确认在给定密钥下，提供商 / 模型本身是否至少能响应。
- “Gateway smoke” 用于确认该模型的完整 Gateway 网关 + 智能体流水线是否正常工作（会话、历史、工具、沙箱策略等）。
### 第 1 层：直接模型补全（无 Gateway 网关）
### 第 1 层：Direct model completion（无 Gateway 网关）
- 测试：`src/agents/models.profiles.live.test.ts`
- 目标：
- 枚举已发现的模型
- 使用 `getApiKeyForModel` 选择你拥有凭证的模型
- 为每个模型运行一个小型补全（并在需要时运行定向回归测试）
- 使用 `getApiKeyForModel` 选择你有凭证的模型
- 对每个模型运行一次小型 completion（并在需要时运行针对性的回归测试）
- 启用方式：
- `pnpm test:live`（或者如果你直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）来实际运行此套件；否则它会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 网关冒烟测试
- `pnpm test:live`（或者如果直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）才会实际运行此套件；否则它会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 网关冒烟测试
- 选择模型的方法：
- `OPENCLAW_LIVE_MODELS=modern` 运行现代允许列表（Opus / Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_MODELS=all` 是现代允许列表的别名
- 或者 `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,..."`（逗号分隔的允许列表）
- modern / all 全量检查默认使用精心挑选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可执行完整的 modern 全量检查，或设置为正数以使用更小的上限。
- 完整全量检查对整个直接模型测试超时使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS`。默认值：60 分钟。
- 设置 `OPENCLAW_LIVE_MODEL_CONCURRENCY=10` 可并行运行直接模型探测。默认值：1。
- `OPENCLAW_LIVE_MODELS=modern` 运行现代 allowlist（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_MODELS=all` 是现代 allowlist 的别名
- 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,..."`（逗号分隔的 allowlist）
- modern / all 扫描默认使用精心筛选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可执行完整的 modern 扫描，或设置为正数以使用更小的上限。
- 完整扫描对整个 Direct model 测试超时使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS`。默认值：60 分钟。
- 设置 `OPENCLAW_LIVE_MODEL_CONCURRENCY=20` 以并行运行 Direct model 探测。默认值：1。
- 选择提供商的方法：
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔的允许列表）
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔的 allowlist）
- 密钥来源：
- 默认：配置档存储和环境变量回退
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅使用配置档存储**
- 存在原因：
- 将“提供商 API 已损坏 / 密钥无效”和“Gateway 网关智能体流水线已损坏”区分开来
- 包含小型、隔离的回归测试（示例：OpenAI Responses / Codex Responses 推理回放 + 工具调用流程）
- 默认：profile 存储和环境变量回退
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅使用 profile 存储**
- 存在意义：
- 将“提供商 API 已损坏 / 密钥无效”与“Gateway 网关智能体流水线已损坏”区分开
- 包含小型、隔离的回归测试（示例：OpenAI Responses / Codex Responses 推理重放 + tool-call 流程）
### 第 2 层：Gateway 网关 + dev 智能体冒烟测试（也就是 “@openclaw” 实际执行的内容）
- 测试：`src/gateway/gateway-models.profiles.live.test.ts`
- 目标：
- 启动一个进程内 Gateway 网关
- 创建 / 修补一个 `agent:dev:*` 会话（每次运行时覆盖模型）
- 遍历带有密钥的模型并断言：
- “有意义”的响应（无工具）
- 一次真实的工具调用可正常工作（读取探针）
- 可选的额外工具探针（exec + read 探针）
- OpenAI 回归路径（仅工具调用 → 后续跟进）继续保持正常
- 探针详情（这样你可以快速解释故障）：
- `read` 探针：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 它并回显该 nonce。
- `exec+read` 探针：测试要求智能体通过 `exec` 将 nonce 写入临时文件，然后再将其 `read` 回来。
- image 探针：测试附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat <CODE>`。
- 创建 / 修补一个 `agent:dev:*` 会话（每次运行按模型覆盖）
- 遍历带密钥的模型并断言：
- “有意义的”响应（无工具）
- 一次真实的工具调用可正常工作（read 探针）
- 可选的额外工具探针（exec+read 探针）
- OpenAI 回归路径（仅 tool-call → 后续跟进）持续正常
- 探针详情（这样你可以快速解释失败原因）：
- `read` 探针：测试会在工作区中写入一个 nonce 文件，并要求智能体 `read` 它并回显 nonce。
- `exec+read` 探针：测试会要求智能体通过 `exec` 将 nonce 写入临时文件，然后再 `read` 回来。
- image 探针：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat <CODE>`。
- 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。
- 启用方式：
- `pnpm test:live`（或者如果你直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
- `pnpm test:live`（或者如果直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
- 选择模型的方法：
- 默认：现代允许列表（Opus / Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是现代允许列表的别名
- 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号分隔列表）以缩小范围
- modern / all Gateway 网关全量检查默认使用精心挑选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可执行完整的 modern 全量检查，或设置为正数以使用更小的上限。
- 选择提供商的方法（避免“OpenRouter 全部都测”）：
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔的允许列表）
- 工具和图像探针在此实时测试中始终启用：
- 默认：现代 allowlist（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是现代 allowlist 的别名
- 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号分隔列表）来缩小范围
- modern / all Gateway 网关扫描默认使用精心筛选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可执行完整的 modern 扫描，或设置为正数以使用更小的上限。
- 选择提供商的方法（避免 “OpenRouter everything”）：
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔的 allowlist）
- 工具 + 图像探针在此实时测试中始终启用：
- `read` 探针 + `exec+read` 探针（工具压力测试）
- 当模型声明支持图像输入时，会运行 image 探针
- 当模型宣告支持图像输入时，image 探针会运行
- 流程（高层概述）：
- 测试生成一个带有 “CAT” + 随机代码的小型 PNG（`src/gateway/live-image-probe.ts`）
- 测试生成一个包含 “CAT” + 随机代码的小型 PNG（`src/gateway/live-image-probe.ts`）
- 通过 `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]` 发送
- Gateway 网关将附件解析为 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
- 内嵌智能体将多模态用户消息转发给模型
- 断言：回复中包含 `cat` + 该代码（OCR 容错：允许轻微错误）
- 嵌入式智能体将多模态用户消息转发给模型
- 断言：回复包含 `cat` + 该代码（OCR 容错：允许轻微错误）
提示：要查看你在本机上可以测试什么（以及精确的 `provider/model` ID），请运行：
提示：如需查看你在本机上可以测试的内容（以及精确的 `provider/model` id），请运行：
```bash
openclaw models list
@ -116,22 +116,22 @@ openclaw models list --json
- 测试：`src/gateway/gateway-cli-backend.live.test.ts`
- 目标：在不触碰你的默认配置的情况下，使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线。
- 后端专用的冒烟测试默认值位于对应扩展的 `cli-backend.ts` 定义中。
- 后端专用的默认冒烟配置位于所属扩展的 `cli-backend.ts` 定义中。
- 启用：
- `pnpm test:live`（或者如果你直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
- `pnpm test:live`（或者如果直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
- `OPENCLAW_LIVE_CLI_BACKEND=1`
- 默认值：
- 默认提供商 / 模型：`claude-cli/claude-sonnet-4-6`
- 默认 provider / model：`claude-cli/claude-sonnet-4-6`
- command / args / image 行为来自所属 CLI 后端插件元数据。
- 覆盖项（可选）：
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2"`
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径会注入到提示中）。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 通过 CLI 参数传递图像文件路径，而不是注入到提示中。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）用于在设置 `IMAGE_ARG` 时控制图像参数的传递方式。
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮消息并验证恢复流程。
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` 禁用默认的 Claude Sonnet -> Opus 同会话连续性探针（当所选模型支持切换目标时，可设为 `1` 以强制启用）。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径会注入到提示词中）。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 将图像文件路径作为 CLI 参数传递，而不是注入到提示词中。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）用于控制在设置 `IMAGE_ARG` 时如何传递图像参数。
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮并验证恢复流程。
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` 禁用默认的 Claude Sonnet -> Opus 同会话连续性探针（当所选模型支持切换目标时，设置为 `1` 可强制启用）。
示例：
@ -159,26 +159,26 @@ pnpm test:docker:live-cli-backend:gemini
说明：
- Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。
- 它会以非 root 的 `node` 用户身份，在仓库 Docker 镜像中运行实时 CLI 后端冒烟测试。
- 它会从所属扩展解析 CLI 冒烟测试元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到缓存的可写前缀 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 中（默认值：`~/.cache/openclaw/docker-cli-tools`）。
- `pnpm test:docker:live-cli-backend:claude-subscription` 需要可移植的 Claude Code 订阅 OAuth，可通过带有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供。它会先在 Docker 中验证直接 `claude -p`，然后在不保留 Anthropic API 密钥环境变量的情况下运行两轮 Gateway 网关 CLI 后端测试。该订阅测试默认禁用 Claude MCP / 工具和图像探针，因为 Claude 当前会将第三方应用使用路由到额外用量计费，而不是常规订阅套餐限制。
- 实时 CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮次、图像分类轮次，然后是通过 Gateway 网关 CLI 验证的 MCP `cron` 工具调用。
- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍然记得之前的备注。
- 它会在仓库 Docker 镜像内以非 root 的 `node` 用户身份运行实时 CLI 后端冒烟测试。
- 它会从所属扩展解析 CLI 冒烟元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 指定的可写缓存前缀中（默认：`~/.cache/openclaw/docker-cli-tools`）。
- `pnpm test:docker:live-cli-backend:claude-subscription` 需要通过 `~/.claude/.credentials.json` 中的 `claudeAiOauth.subscriptionType`，或通过 `claude setup-token` 获取的 `CLAUDE_CODE_OAUTH_TOKEN`，来提供可移植的 Claude Code 订阅 OAuth。它会先在 Docker 中验证直接执行 `claude -p`，然后在不保留 Anthropic API-key 环境变量的情况下运行两轮 Gateway 网关 CLI 后端测试。这个订阅测试默认禁用 Claude MCP / 工具和图像探针，因为 Claude 当前会将第三方应用使用量计入额外使用计费，而不是普通订阅计划限额。
- 实时 CLI 后端冒烟测试现在对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮次、图像分类轮次，然后是通过 Gateway 网关 CLI 验证的 MCP `cron` 工具调用。
- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍记得之前的注释。
## 实时：ACP 绑定冒烟测试（`/acp spawn ... --bind here`）
- 测试：`src/gateway/gateway-acp-bind.live.test.ts`
- 目标：使用实时 ACP 智能体验证真实 ACP 会话绑定流程：
- 目标：使用实时 ACP 智能体验证真实的 ACP 会话绑定流程：
- 发送 `/acp spawn <agent> --bind here`
- 原地绑定一个合成的消息渠道会话
- 在同一会话中发送普通后续消息
- 验证该后续消息进入已绑定 ACP 会话的转录中
- 在同一个会话上发送普通的后续消息
- 验证该后续消息进入已绑定 ACP 会话的 transcript
- 启用：
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
- `OPENCLAW_LIVE_ACP_BIND=1`
- 默认值：
- Docker 中的 ACP 智能体：`claude,codex,gemini`
- 直接 `pnpm test:live ...` 使用的 ACP 智能体：`claude`
- 直接执行 `pnpm test:live ...` 时使用的 ACP 智能体：`claude`
- 合成渠道：Slack 私信风格的会话上下文
- ACP 后端：`acpx`
- 覆盖项：
@ -190,8 +190,8 @@ pnpm test:docker:live-cli-backend:gemini
- `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.2`
- `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.2`
- 说明：
- 此测试路径使用 Gateway 网关 `chat.send` 接口，并带有仅管理员可用的合成来源路由字段，这样测试就可以附加消息渠道上下文，而无需伪装成外部投递。
- 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会对所选 ACP harness 智能体使用内嵌 `acpx` 插件的内置智能体注册表。
- 这一测试通道使用 Gateway 网关 `chat.send` 接口，并带有仅管理员可用的合成 originating-route 字段，以便测试可以附加消息渠道上下文，而无需伪装成外部投递。
- 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用嵌入式 `acpx` 插件内置的智能体注册表来选择 ACP harness 智能体。
示例：
@ -218,10 +218,10 @@ pnpm test:docker:live-acp-bind:gemini
Docker 说明：
- Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。
- 默认情况下，它会按顺序对所有受支持的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后 `gemini`。
- 默认情况下，它会按顺序针对所有受支持的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后是 `gemini`。
- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 可缩小矩阵范围。
- 它会加载 `~/.profile`，将匹配的 CLI 凭证材料暂存到容器中，在可写 npm 前缀中安装 `acpx`，然后在缺失时安装所请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。
- 在 Docker 内部，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，以便 acpx 保留来自已加载 profile 的提供商环境变量，并将其提供给子 harness CLI。
- 它会读取 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，将 `acpx` 安装到可写 npm 前缀中，然后在缺失时安装所请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。
- 在 Docker 内，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，以便 acpx 让来自已加载 profile 的 provider 环境变量对其子 harness CLI 保持可用。
## 实时：Codex app-server harness 冒烟测试
@ -229,25 +229,25 @@ Docker 说明：
`agent` 方法验证由插件拥有的 Codex harness：
- 加载内置的 `codex` 插件
- 选择 `OPENCLAW_AGENT_RUNTIME=codex`
- 向 `openai/gpt-5.2` 发送第一轮 Gateway 网关智能体请求，并强制使用 Codex harness
- 向同一个 OpenClaw 会话发送第二轮消息，并验证 app-server
- 在强制使用 Codex harness 的情况下，向 `openai/gpt-5.2` 发送第一轮 Gateway 网关智能体请求
- 向同一个 OpenClaw 会话发送第二轮请求，并验证 app-server
线程可以恢复
- 通过同一个 Gateway 网关命令
- 通过相同的 Gateway 网关命令
路径运行 `/codex status` 和 `/codex models`
- 可选运行两个经 Guardian 审核的提权 shell 探针：一个应被批准的
无害命令，以及一个应被
拒绝从而让智能体回问的伪造密钥上传操作
- 可选运行两个经过 Guardian 审核的提权 shell 探针：一个应被批准的无害
命令，以及一个应被拒绝的伪造密钥上传，
从而让智能体回头询问
- 测试：`src/gateway/gateway-codex-harness.live.test.ts`
- 启用：`OPENCLAW_LIVE_CODEX_HARNESS=1`
- 默认模型：`openai/gpt-5.2`
- 可选图像探针：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- 可选 MCP / 工具探针：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
- 可选 Guardian 探针：`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，这样损坏的 Codex
harness 就无法通过悄悄回退到 PI 来蒙混过关。
- 此冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，因此损坏的 Codex
harness 无法通过静默回退到 PI 来蒙混过关。
- 认证：Codex app-server 认证来自本地 Codex 订阅登录。Docker
冒烟测试在适用时也可为非 Codex 探针提供 `OPENAI_API_KEY`，
另外还可选复制 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
冒烟测试在适用时也可以为非 Codex 探针提供 `OPENAI_API_KEY`，
以及可选复制的 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
本地配方：
@ -271,22 +271,23 @@ pnpm test:docker:live-codex-harness
Docker 说明：
- Docker 运行器位于 `scripts/test-live-codex-harness-docker.sh`。
- 它会加载挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI
- 它会读取挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI
认证文件，将 `@openai/codex` 安装到可写的挂载 npm
前缀中，暂存源代码树，然后只运行 Codex-harness 实时测试。
前缀中，暂存源码树，然后仅运行 Codex harness 实时测试。
- Docker 默认启用图像、MCP / 工具和 Guardian 探针。设置
`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或
`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`，即可在需要更窄范围调试运行时使用。
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`，可在你需要更窄范围调试
运行时使用。
- Docker 还会导出 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，与实时
测试配置保持一致，这样旧别名或回退到 PI 都无法掩盖 Codex harness
测试配置保持一致，因此旧别名或回退到 PI 无法掩盖 Codex harness
回归问题。
### 推荐的实时测试配方
范围窄、明确的允许列表速度最快，也最不容易出问题：
范围更窄、显式的 allowlist 最快，也最不容易出错：
- 单模型，直接测试（无 Gateway 网关）：
- 单模型，直连（无 Gateway 网关）：
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts`
- 单模型，Gateway 网关冒烟测试：
@ -303,18 +304,18 @@ Docker 说明：
- `google/...` 使用 Gemini API（API 密钥）。
- `google-antigravity/...` 使用 Antigravity OAuth 桥接（Cloud Code Assist 风格的智能体端点）。
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（单独的认证 + 工具行为差异）。
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立认证 + 工具行为差异）。
- Gemini API 与 Gemini CLI：
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / 配置档认证）；这通常是大多数用户所说的 “Gemini”。
- CLI：OpenClaw 会调用本地 `gemini` 二进制；它有自己的认证方式，行为也可能不同（流式传输 / 工具支持 / 版本偏差）。
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / profile 认证）；这是大多数用户提到 “Gemini” 时的含义。
- CLI：OpenClaw 调用本地 `gemini` 二进制；它有自己的认证方式，并且行为可能不同（流式传输 / 工具支持 / 版本偏差）。
## 实时：模型矩阵（我们的覆盖范围）
## 实时：模型矩阵（我们覆盖什么）
没有固定的“CI 模型列表”（实时测试为按需启用），但以下是**推荐**在有密钥的开发机器上定期覆盖的模型。
没有固定的“CI 模型列表”（实时测试为可选启用），但以下是建议你在有密钥的开发机器上定期覆盖的**推荐**模型。
### 现代冒烟测试集（工具调用 + 图像）
这是我们期望持续保持可用的“常用模型”运行集：
这是我们期望持续保持可用的“常见模型”运行集合：
- OpenAI（非 Codex）：`openai/gpt-5.2`
- OpenAI Codex OAuth：`openai-codex/gpt-5.2`
@ -324,12 +325,12 @@ Docker 说明：
- Z.AI（GLM）：`zai/glm-4.7`
- MiniMax：`minimax/MiniMax-M2.7`
运行带工具 + 图像的 Gateway 网关冒烟测试：
使用工具 + 图像运行 Gateway 网关冒烟测试：
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
### 基线：工具调用（Read + 可选 Exec）
每个提供商家族至少选一个：
每个提供商家族至少选择一个：
- OpenAI：`openai/gpt-5.2`
- Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
@ -337,46 +338,46 @@ Docker 说明：
- Z.AI（GLM）：`zai/glm-4.7`
- MiniMax：`minimax/MiniMax-M2.7`
可选的附加覆盖（有更好，没有也行）：
可选的额外覆盖（锦上添花）：
- xAI：`xai/grok-4`（或最新可用版本）
- Mistral：`mistral/`…（选择一个你已启用、支持 “tools” 的模型）
- Mistral：`mistral/`…（选择一个你已启用、支持工具的模型）
- Cerebras：`cerebras/`…（如果你有访问权限）
- LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式）
### Vision：图像发送（附件 → 多模态消息）
### 视觉：图像发送（附件 → 多模态消息）
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude / Gemini / OpenAI 支持 Vision 的变体等），以执行图像探针。
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude / Gemini / OpenAI 的支持视觉输入的变体等），以覆盖图像探针。
### 聚合器 / 替代 Gateway 网关
如果你已启用相关密钥，我们还支持通过以下方式进行测试：
如果你已启用密钥，我们也支持通过以下方式进行测试：
- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选模型）
- OpenRouter：`openrouter/...`（数百种模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选模型）
- OpenCode：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）
你还可以在实时矩阵中加入更多提供商（如果你有凭证 / 配置）：
你也可以将更多提供商加入实时矩阵（如果你有凭证 / 配置）：
- 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot`
- 通过 `models.providers`（自定义端点）：`minimax`（云 / API），以及任何兼容 OpenAI / Anthropic 的代理（LM Studio、vLLM、LiteLLM 等）
- 通过 `models.providers`（自定义端点）：`minimax`（云端 / API），以及任何兼容 OpenAI / Anthropic 的代理（LM Studio、vLLM、LiteLLM 等）
提示：不要试图在文档中硬编码 “all models”。权威列表始终是你机器上 `discoverModels(...)` 的返回结果，加上当前可用的密钥。
提示：不要试图在文档中硬编码“所有模型”。权威列表是你机器上 `discoverModels(...)` 返回的结果，加上当前可用的密钥。
## 凭证（切勿提交）
## 凭证（绝不要提交）
实时测试发现凭证的方式与 CLI 相同。实际含义如下：
- 如果 CLI 能用，实时测试也应该能找到同样的密钥。
- 如果 CLI 可用，实时测试应该也能找到相同的密钥。
- 如果某个实时测试提示 “no creds”，请像调试 `openclaw models list` / 模型选择那样去调试。
- 每个智能体的认证配置档：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试中 “profile keys” 的含义）
- 每个智能体的认证 profile：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试中 “profile keys” 的含义）
- 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- 旧版状态目录：`~/.openclaw/credentials/`（存在时会被复制到暂存的实时测试 home 中，但它不是主配置档密钥存储）
- 实时本地运行默认会将当前活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录复制到临时测试 home；暂存的实时 home 会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，以确保探针不会落到你的真实宿主工作区上。
- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时测试 home 中，但它不是主 profile-key 存储）
- 本地实时运行默认会将当前活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录复制到临时测试 home；暂存的实时测试 home 会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，这样探针就不会落到你真实主机的工作区中。
如果你想依赖环境变量密钥（例如在你的 `~/.profile` 中导出），请在执行本地测试前运行 `source ~/.profile`，或使用下面的 Docker 运行器（它们可以把 `~/.profile` 挂载进容器）。
如果你想依赖环境变量密钥（例如在你的 `~/.profile` 中导出的密钥），请在执行本地测试前运行 `source ~/.profile`，或者使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载进容器）。
## Deepgram 实时测试（音频转写）
## Deepgram 实时测试（音频转录）
- 测试：`extensions/deepgram/audio.live.test.ts`
- 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
@ -393,8 +394,8 @@ Docker 说明：
- 启用：`OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
- 范围：
- 覆盖内置 comfy 图像、视频和 `music_generate` 路径
- 除非配置了 `models.providers.comfy.<capability>`，否则会跳过各项能力
- 在修改 comfy 工作流提交、轮询、下载或插件注册后非常有用
- 除非已配置 `models.providers.comfy.<capability>`，否则会跳过各项能力
- 在更改 comfy 工作流提交、轮询、下载或插件注册之后特别有用
## 图像生成实时测试
@ -404,8 +405,8 @@ Docker 说明：
- 范围：
- 枚举每个已注册的图像生成提供商插件
- 在探测前从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置档，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
- 跳过没有可用认证 / 配置档 / 模型的提供商
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
- 跳过没有可用认证 / profile / 模型的提供商
- 通过共享运行时能力运行标准图像生成变体：
- `google:flash-generate`
- `google:pro-generate`
@ -424,7 +425,7 @@ Docker 说明：
- `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"`
- 可选认证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用配置档存储认证，并忽略仅环境变量覆盖
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用 profile 存储认证，并忽略仅环境变量覆盖
## 音乐生成实时测试
@ -435,20 +436,20 @@ Docker 说明：
- 覆盖共享的内置音乐生成提供商路径
- 当前覆盖 Google 和 MiniMax
- 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置档，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
- 跳过没有可用认证 / 配置档 / 模型的提供商
- 在可用时运行两个已声明的运行时模式：
- 使用仅提示输入的 `generate`
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
- 跳过没有可用认证 / profile / 模型的提供商
- 在可用时运行两种声明的运行时模式：
- 使用仅提示词输入的 `generate`
- 当提供商声明 `capabilities.edit.enabled` 时运行 `edit`
- 当前共享测试路径覆盖：
- 当前共享测试通道覆盖：
- `google`：`generate`、`edit`
- `minimax`：`generate`
- `comfy`：单独的 Comfy 实时文件，不属于该共享全量检查
- `comfy`：单独的 Comfy 实时测试文件，不在此共享扫描内
- 可选缩小范围：
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"`
- 可选认证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用配置档存储认证，并忽略仅环境变量覆盖
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用 profile 存储认证，并忽略仅环境变量覆盖
## 视频生成实时测试
@ -457,38 +458,38 @@ Docker 说明：
- Harness：`pnpm test:live:media video`
- 范围：
- 覆盖共享的内置视频生成提供商路径
- 默认使用适合发布的冒烟测试路径：非 FAL 提供商、每个提供商一个文生视频请求、时长一秒的龙虾提示词，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每提供商操作上限（默认值为 `180000`）
- 默认使用适合发布的冒烟测试路径：非 FAL 提供商、每个提供商一次 text-to-video 请求、1 秒龙虾提示词，以及由 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 控制的每提供商操作上限（默认 `180000`）
- 默认跳过 FAL，因为提供商侧队列延迟可能主导发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行它
- 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置档，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
- 跳过没有可用认证 / 配置档 / 模型的提供商
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证 profile，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
- 跳过没有可用认证 / profile / 模型的提供商
- 默认仅运行 `generate`
- 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`，在可用时也会运行已声明的转换模式：
- 当提供商声明 `capabilities.imageToVideo.enabled`，且所选提供商 / 模型在共享全量检查中接受基于缓冲区的本地图像输入时，运行 `imageToVideo`
- 当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商 / 模型在共享全量检查中接受基于缓冲区的本地视频输入时，运行 `videoToVideo`
- 共享全量检查中当前已声明但跳过的 `imageToVideo` 提供商：
- `vydra`，因为内置的 `veo3` 仅支持文本，而内置的 `kling` 需要远程图像 URL
- 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 可在可用时也运行已声明的转换模式：
- 当提供商声明 `capabilities.imageToVideo.enabled` 且所选提供商 / 模型在共享扫描中接受基于缓冲区的本地图像输入时，运行 `imageToVideo`
- 当提供商声明 `capabilities.videoToVideo.enabled` 且所选提供商 / 模型在共享扫描中接受基于缓冲区的本地视频输入时，运行 `videoToVideo`
- 当前在共享扫描中已声明但被跳过的 `imageToVideo` 提供商：
- `vydra`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL
- 提供商专用的 Vydra 覆盖：
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
- 该文件默认运行 `veo3` 文生视频，以及一个使用远程图像 URL 固定数据的 `kling` 测试路径
- 当前 `videoToVideo` 实时覆盖：
- 仅 `runway`，且所选模型为 `runway/gen4_aleph` 时
- 共享全量检查中当前已声明但跳过的 `videoToVideo` 提供商：
- 该文件会运行 `veo3` text-to-video，以及一个默认使用远程图像 URL 固定数据的 `kling` 测试通道
- 当前 `videoToVideo` 实时测试覆盖：
- 仅 `runway`，且所选模型为 `runway/gen4_aleph`
- 当前在共享扫描中已声明但被跳过的 `videoToVideo` 提供商：
- `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 参考 URL
- `google`，因为当前共享 Gemini / Veo 路径使用基于本地缓冲区的输入，而该路径在共享全量检查中不被接受
- `openai`，因为当前共享路径缺乏针对组织的视频修补 / remix 访问保证
- `google`，因为当前共享 Gemini / Veo 测试通道使用基于本地缓冲区的输入，而该路径在共享扫描中不被接受
- `openai`，因为当前共享测试通道缺少针对组织的 video inpaint / remix 访问保证
- 可选缩小范围：
- `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 以在默认全量检查中包含所有提供商，包括 FAL
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 以降低每个提供商的操作上限，用于激进的冒烟测试运行
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 以在默认扫描中包含所有提供商，包括 FAL
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 以缩短每个提供商的操作上限，用于更激进的冒烟测试运行
- 可选认证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用配置档存储认证，并忽略仅环境变量覆盖
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用 profile 存储认证，并忽略仅环境变量覆盖
## 媒体实时测试 Harness
- 命令：`pnpm test:live:media`
- 目的：
- 用途：
- 通过一个仓库原生入口点运行共享的图像、音乐和视频实时测试套件
- 自动从 `~/.profile` 加载缺失的提供商环境变量
- 默认自动将每个测试套件缩小到当前具有可用认证的提供商

441
docs/zh-CN/plugins/manifest.md
View File

@ -1,21 +1,21 @@
---
read_when:
- 你正在构建一个 OpenClaw 插件
- 你需要交付插件配置模式，或调试插件验证错误
summary: 插件清单 + JSON 模式要求（严格配置验证）
- 你需要提供插件配置 schema，或调试插件校验错误
summary: 插件清单 + JSON schema 要求（严格配置校验）
title: 插件清单
x-i18n:
generated_at: "2026-04-24T03:06:50Z"
generated_at: "2026-04-24T04:55:18Z"
model: gpt-5.4
provider: openai
source_hash: 2e9e38ce695faf9638538b6d4761ee64126f5adee944be1373a02e897853a49d
source_hash: fd130accdaf606afc07a34cf064588087227bafc23279d31e33c4fdc8863a4a4
source_path: plugins/manifest.md
workflow: 15
---
此页面仅适用于**原生 OpenClaw 插件清单**。
如需兼容的 bundle 布局，请参阅 [Plugin bundles](/zh-CN/plugins/bundles)。
有关兼容的 bundle 布局，请参阅 [Plugin bundles](/zh-CN/plugins/bundles)。
兼容的 bundle 格式使用不同的清单文件：
@ -23,30 +23,31 @@ x-i18n:
- Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件布局
- Cursor bundle：`.cursor-plugin/plugin.json`
OpenClaw 也会自动检测这些 bundle 布局，但它们不会根据此处描述的 `openclaw.plugin.json` 模式进行验证。
OpenClaw 也会自动检测这些 bundle 布局，但它们不会根据此处描述的 `openclaw.plugin.json` schema 进行校验。
对于兼容 bundle，当前当其布局符合 OpenClaw 运行时预期时，OpenClaw 会读取 bundle 元数据，以及已声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、Claude bundle 的 LSP 默认值，以及受支持的 hook packs。
对于兼容 bundle，OpenClaw 目前会在布局符合 OpenClaw 运行时预期时，读取 bundle 元数据，以及声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、Claude bundle 的 LSP 默认值，以及受支持的 hook pack。
每个原生 OpenClaw 插件**都必须**在**插件根目录**提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码的情况下**验证配置。缺失或无效的清单会被视为插件错误，并阻止配置验证。
每个原生 OpenClaw 插件**都必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用这个清单在**不执行插件代码的情况下**校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。
请参阅完整的插件系统指南：[Plugins](/zh-CN/tools/plugin)。
关于原生能力模型和当前外部兼容性指导，请参阅：[Capability model](/zh-CN/plugins/architecture#public-capability-model)。
查看完整的插件系统指南：[Plugins](/zh-CN/tools/plugin)。
有关原生能力模型和当前外部兼容性指南，请参阅：
[Capability model](/zh-CN/plugins/architecture#public-capability-model)。
## 此文件的作用
## 这个文件的作用
`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。下面的所有内容都必须足够轻量，能够在不启动插件运行时的情况下进行检查。
`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。下面的所有内容都必须足够轻量，以便在不启动插件运行时的情况下进行检查。
**用于：**
**将其用于：**
- 插件标识、配置验证和配置 UI 提示
- 凭证、onboarding 和设置元数据（别名、自动启用、provider 环境变量、凭证选择）
- 控制平面表面的激活提示
- 简写的模型家族归属
- 插件标识、配置校验，以及配置 UI 提示
- 认证、新手引导和设置元数据（别名、自动启用、provider 环境变量、认证选项）
- 控制平面界面的激活提示
- 简写模型族归属
- 静态能力归属快照（`contracts`）
- 供共享 `openclaw qa` 主机检查的 QA runner 元数据
- 合并到 catalog 和验证表面的渠道特定配置元数据
- 共享 `openclaw qa` 主机可检查的 QA 运行器元数据
- 合并到目录和校验界面中的渠道专用配置元数据
**不要用于：**注册运行时行为、声明代码入口点或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。
**不要将其用于：**注册运行时行为、声明代码入口点，或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。
## 最小示例
@ -126,65 +127,66 @@ OpenClaw 也会自动检测这些 bundle 布局，但它们不会根据此处描
## 顶层字段参考
| 字段 | 必填 | 类型 | 含义 |
| ------------------------------------ | -------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | 是 | `string` | 规范的插件 id。这是 `plugins.entries.<id>` 中使用的 id。 |
| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 |
| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略该字段，或将其设置为任何非 `true` 的值，都会让插件默认保持禁用。 |
| `legacyPluginIds` | 否 | `string[]` | 会规范化为此规范插件 id 的旧版 id。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当凭证、配置或模型引用提到这些 provider id 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明由 `plugins.slots.*` 使用的排他性插件类型。 |
| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于设备发现和配置验证。 |
| `providers` | 否 | `string[]` | 由此插件拥有的 provider id。 |
| `modelSupport` | 否 | `object` | 由清单持有的简写模型家族元数据，用于在运行时之前自动加载插件。 |
| `providerEndpoints` | 否 | `object[]` | 由清单持有的端点 host/baseUrl 元数据，用于核心在 provider 运行时加载之前对 provider 路由进行分类。 |
| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 |
| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载之前、冷模型发现期间，应探测其插件持有 synthetic auth hook 的 provider 或 CLI 后端引用。 |
| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件持有的占位 API key 值，用于表示非密钥的本地、OAuth 或环境凭证状态。 |
| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称，应在运行时加载之前生成带有插件感知的配置和 CLI 诊断信息。 |
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量 provider 凭证环境变量元数据。 |
| `providerAuthAliases` | 否 | `Record<string, string>` | 应复用另一个 provider id 进行凭证查找的 provider id，例如与基础 provider 共享 API key 和凭证配置文件的 coding provider。 |
| `channelEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量渠道环境变量元数据。将其用于由环境变量驱动的渠道设置或凭证表面，以便通用启动/配置辅助工具能够识别。 |
| `providerAuthChoices` | 否 | `object[]` | 用于 onboarding 选择器、首选 provider 解析和简单 CLI 标志接线的轻量凭证选择元数据。 |
| `activation` | 否 | `object` | 用于 provider、命令、渠道、路由和能力触发加载的轻量激活提示。仅为元数据；插件运行时仍然拥有实际行为。 |
| `setup` | 否 | `object` | 设备发现和设置表面可在不加载插件运行时的情况下检查的轻量 setup/onboarding 描述符。 |
| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载之前使用的轻量 QA runner 描述符。 |
| `contracts` | 否 | `object` | 针对外部凭证 hooks、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、Web 搜索和工具归属的静态内置能力快照。 |
| `mediaUnderstandingProviderMetadata` | 否 | `Record<string, object>` | 为 `contracts.mediaUnderstandingProviders` 中声明的 provider id 提供的轻量媒体理解默认元数据。 |
| `channelConfigs` | 否 | `Record<string, object>` | 由清单持有的渠道配置元数据，在运行时加载之前合并到设备发现和验证表面中。 |
| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 |
| `name` | 否 | `string` | 人类可读的插件名称。 |
| `description` | 否 | `string` | 在插件表面中显示的简短摘要。 |
| `version` | 否 | `string` | 信息性插件版本。 |
| `uiHints` | 否 | `Record<string, object>` | 配置字段的 UI 标签、占位符和敏感性提示。 |
| 字段 | 必填 | 类型 | 含义 |
| ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | 是 | `string` | 规范的插件 id。这是 `plugins.entries.<id>` 中使用的 id。 |
| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 |
| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略此字段，或将其设为任何非 `true` 的值，则该插件默认保持禁用。 |
| `legacyPluginIds` | 否 | `string[]` | 会规范化为此标准插件 id 的旧版 id。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些 provider id 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明由 `plugins.slots.*` 使用的排他性插件类型。 |
| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于发现和配置校验。 |
| `providers` | 否 | `string[]` | 由此插件拥有的 provider id。 |
| `providerDiscoveryEntry` | 否 | `string` | 轻量级 provider 发现模块路径，相对于插件根目录，用于可在不激活完整插件运行时的情况下加载的、限定于清单范围内的 provider 目录元数据。 |
| `modelSupport` | 否 | `object` | 由清单持有的简写模型族元数据，用于在运行时之前自动加载插件。 |
| `providerEndpoints` | 否 | `object[]` | 由清单持有的 endpoint host/baseUrl 元数据，用于核心在 provider 运行时加载前必须分类的 provider 路由。 |
| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 |
| `syntheticAuthRefs` | 否 | `string[]` | provider 或 CLI 后端引用；在运行时加载前的冷启动模型发现期间，应探测其由插件持有的 synthetic auth hook。 |
| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件持有的占位 API key 值，表示非密钥的本地、OAuth 或环境凭证状态。 |
| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称；在运行时加载前，这些名称应生成具备插件感知能力的配置和 CLI 诊断信息。 |
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量级 provider 认证环境变量元数据。 |
| `providerAuthAliases` | 否 | `Record<string, string>` | 应复用另一个 provider id 进行认证查找的 provider id，例如与基础 provider 共享 API key 和认证配置文件的 coding provider。 |
| `channelEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量级渠道环境变量元数据。将其用于由环境变量驱动的渠道设置或认证界面，以便通用启动/配置辅助工具能够识别。 |
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选 provider 解析和简单 CLI 标志绑定的轻量级认证选项元数据。 |
| `activation` | 否 | `object` | 用于 provider、命令、渠道、路由和能力触发加载的轻量级激活提示。仅为元数据；实际行为仍由插件运行时负责。 |
| `setup` | 否 | `object` | 轻量级设置/新手引导描述符，供发现和设置界面在不加载插件运行时的情况下检查。 |
| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载前使用的轻量级 QA 运行器描述符。 |
| `contracts` | 否 | `object` | 外部认证 hook、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、网页搜索和工具归属的静态内置能力快照。 |
| `mediaUnderstandingProviderMetadata` | 否 | `Record<string, object>` | 为 `contracts.mediaUnderstandingProviders` 中声明的 provider id 提供的轻量级媒体理解默认元数据。 |
| `channelConfigs` | 否 | `Record<string, object>` | 由清单持有的渠道配置元数据，会在运行时加载前合并到发现和校验界面中。 |
| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 |
| `name` | 否 | `string` | 人类可读的插件名称。 |
| `description` | 否 | `string` | 显示在插件界面中的简短摘要。 |
| `version` | 否 | `string` | 信息性插件版本。 |
| `uiHints` | 否 | `Record<string, object>` | 配置字段的 UI 标签、占位符和敏感性提示。 |
## `providerAuthChoices` 参考
每个 `providerAuthChoices` 条目描述一个 onboarding 或凭证选择。
OpenClaw 会在 provider 运行时加载之前读取这些内容。
每个 `providerAuthChoices` 条目都描述一个新手引导或认证选项。
OpenClaw 会在 provider 运行时加载前读取这些内容。
| 字段 | 必填 | 类型 | 含义 |
| --------------------- | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `provider` | 是 | `string` | 此选择所属的 provider id。 |
| `method` | 是 | `string` | 要分发到的凭证方法 id。 |
| `choiceId` | 是 | `string` | onboarding 和 CLI 流程使用的稳定凭证选择 id。 |
| `choiceLabel` | 否 | `string` | 面向用户的标签。如省略，OpenClaw 会回退到 `choiceId`。 |
| `choiceHint` | 否 | `string` | 选择器中的简短辅助文本。 |
| `assistantPriority` | 否 | `number` | 在由 assistant 驱动的交互式选择器中，值越小排序越靠前。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在 assistant 选择器中隐藏该选项，但仍允许手动 CLI 选择。 |
| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选择的旧版 choice id。 |
| `groupId` | 否 | `string` | 用于对相关选择进行分组的可选分组 id。 |
| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 |
| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 |
| `optionKey` | 否 | `string` | 用于简单单标志凭证流程的内部选项键。 |
| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 |
| `cliOption` | 否 | `string` | 完整的 CLI 选项形式，例如 `--openrouter-api-key <key>`。 |
| `cliDescription` | 否 | `string` | CLI 帮助中使用的描述。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选择应出现在哪些 onboarding 表面中。如省略，则默认是 `["text-inference"]`。 |
| 字段 | 必填 | 类型 | 含义 |
| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `provider` | 是 | `string` | 此选项所属的 provider id。 |
| `method` | 是 | `string` | 要分发到的认证方法 id。 |
| `choiceId` | 是 | `string` | 新手引导和 CLI 流程使用的稳定认证选项 id。 |
| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 |
| `choiceHint` | 否 | `string` | 选择器的简短辅助文本。 |
| `assistantPriority` | 否 | `number` | 在由助手驱动的交互式选择器中，值越小排序越靠前。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，但仍允许手动通过 CLI 选择。 |
| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 id。 |
| `groupId` | 否 | `string` | 用于对相关选项进行分组的可选分组 id。 |
| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 |
| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 |
| `optionKey` | 否 | `string` | 用于简单单标志认证流程的内部选项键。 |
| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 |
| `cliOption` | 否 | `string` | 完整的 CLI 选项形式，例如 `--openrouter-api-key <key>`。 |
| `cliDescription` | 否 | `string` | 用于 CLI 帮助中的说明。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应出现在哪些新手引导界面中。如果省略，默认值为 `["text-inference"]`。 |
## `commandAliases` 参考
当插件拥有某个运行时命令名称，而用户可能会误将其放入 `plugins.allow` 中，或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用这些元数据生成诊断信息，而无需导入插件运行时代码。
当插件拥有一个运行时命令名称，而用户可能误将其放入 `plugins.allow`，或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用这些元数据进行诊断，而无需导入插件运行时代码。
```json
{
@ -198,38 +200,38 @@ OpenClaw 会在 provider 运行时加载之前读取这些内容。
}
```
| 字段 | 必填 | 类型 | 含义 |
| ------------ | -------- | ----------------- | ------------------------------------------------------------------ |
| `name` | 是 | `string` | 属于此插件的命令名称。 |
| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根 CLI 命令。 |
| `cliCommand` | 否 | `string` | 若存在，用于 CLI 操作时建议的相关根 CLI 命令。 |
| 字段 | 必填 | 类型 | 含义 |
| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- |
| `name` | 是 | `string` | 属于此插件的命令名称。 |
| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根 CLI 命令。 |
| `cliCommand` | 否 | `string` | 若存在相关的根 CLI 命令，则建议用于 CLI 操作的命令。 |
## `activation` 参考
当插件可以轻量声明哪些控制平面事件应在之后激活它时，请使用 `activation`。
当插件可以低成本地声明哪些控制平面事件应在稍后激活它时，请使用 `activation`。
## `qaRunners` 参考
当插件在共享 `openclaw qa` 根下贡献一个或多个传输 runner 时，请使用 `qaRunners`。保持这些元数据轻量且静态；插件运行时仍通过导出 `qaRunnerCliRegistrations` 的轻量 `runtime-api.ts` 表面拥有实际的 CLI 注册。
当插件在共享 `openclaw qa` 根命令下贡献一个或多个传输运行器时，请使用 `qaRunners`。保持这些元数据轻量且静态；实际的 CLI 注册仍由插件运行时通过导出 `qaRunnerCliRegistrations` 的轻量级 `runtime-api.ts` 接口负责。
```json
{
"qaRunners": [
{
"commandName": "matrix",
"description": "针对一次性 homeserver 运行由 Docker 支持的 Matrix 实时 QA 通道"
"description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
}
]
}
```
| 字段 | 必填 | 类型 | 含义 |
| ------------- | -------- | -------- | ------------------------------------------------------------ |
| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 |
| `description` | 否 | `string` | 当共享主机需要一个存根命令时使用的回退帮助文本。 |
| 字段 | 必填 | 类型 | 含义 |
| ------------- | -------- | -------- | ------------------------------------------------------------------ |
| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 |
| `description` | 否 | `string` | 当共享主机需要一个占位命令时使用的回退帮助文本。 |
此区块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时/插件入口点。
当前消费者在更广泛的插件加载之前将其用作收窄提示，因此缺少激活元数据通常只会带来性能成本；只要旧版清单归属回退仍然存在，它就不应影响正确性。
此区块仅包含元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时/插件入口点。
当前使用方将其作为更广泛插件加载前的收窄提示，因此缺少激活元数据通常只会带来性能损耗；在旧版清单归属回退机制仍存在时，它不应改变正确性。
```json
{
@ -243,27 +245,27 @@ OpenClaw 会在 provider 运行时加载之前读取这些内容。
}
```
| 字段 | 必填 | 类型 | 含义 |
| ---------------- | -------- | ---------------------------------------------------- | -------------------------------------------------------- |
| `onProviders` | 否 | `string[]` | 请求这些 provider id 时应激活此插件。 |
| `onCommands` | 否 | `string[]` | 应激活此插件的命令 id。 |
| `onChannels` | 否 | `string[]` | 应激活此插件的渠道 id。 |
| `onRoutes` | 否 | `string[]` | 应激活此插件的路由类型。 |
| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。 |
| 字段 | 必填 | 类型 | 含义 |
| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
| `onProviders` | 否 | `string[]` | 请求这些 provider id 时应激活此插件。 |
| `onCommands` | 否 | `string[]` | 应激活此插件的命令 id。 |
| `onChannels` | 否 | `string[]` | 应激活此插件的渠道 id。 |
| `onRoutes` | 否 | `string[]` | 应激活此插件的路由类型。 |
| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。 |
当前的实时消费者：
当前在线使用方：
- 由命令触发的 CLI 规划会回退到旧版
- 命令触发的 CLI 规划会回退到旧版的
`commandAliases[].cliCommand` 或 `commandAliases[].name`
- 由渠道触发的设置/渠道规划在缺少显式渠道激活元数据时，会回退到旧版 `channels[]`
- 渠道触发的设置/渠道规划在缺少显式渠道激活元数据时，会回退到旧版 `channels[]`
归属
- 由 provider 触发的设置/运行时规划在缺少显式 provider
- provider 触发的设置/运行时规划在缺少显式 provider
激活元数据时，会回退到旧版 `providers[]` 和顶层 `cliBackends[]`
归属
## `setup` 参考
当设置和 onboarding 表面需要在运行时加载之前使用由插件持有的轻量元数据时，请使用 `setup`。
当设置和新手引导界面需要在运行时加载前使用由插件持有的轻量级元数据时，请使用 `setup`。
```json
{
@ -282,32 +284,32 @@ OpenClaw 会在 provider 运行时加载之前读取这些内容。
}
```
顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是用于控制平面/设置流程的、特定于 setup 的描述符表面，应保持为纯元数据。
顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是面向控制平面/设置流程的设置专用描述符界面，应保持为纯元数据。
存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现时首选的描述符优先查找表面。如果描述符只用于收窄候选插件，而设置仍需要更丰富的设置时运行时 hook，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。
存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现的首选“描述符优先”查找界面。如果描述符仅用于收窄候选插件，而设置仍需要更丰富的设置期运行时 hook，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。
由于设置查找可能会执行插件持有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现插件之间保持唯一。归属不明确时会以失败关闭，而不是根据发现顺序选出一个赢家。
由于设置查找可能会执行由插件持有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现的插件之间保持唯一。归属不明确时会采用失败即关闭的方式，而不是按发现顺序选择一个胜出者。
### `setup.providers` 参考
| 字段 | 必填 | 类型 | 含义 |
| 字段 | 必填 | 类型 | 含义 |
| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ |
| `id` | 是 | `string` | 在设置或 onboarding 期间暴露的 provider id。保持规范化 id 在全局唯一。 |
| `authMethods` | 否 | `string[]` | 此 provider 在不加载完整运行时的情况下支持的 setup/凭证方法 id。 |
| `envVars` | 否 | `string[]` | 通用设置/状态表面可在插件运行时加载之前检查的环境变量。 |
| `id` | 是 | `string` | 在设置或新手引导期间暴露的 provider id。保持规范化 id 在全局唯一。 |
| `authMethods` | 否 | `string[]` | 此 provider 在不加载完整运行时的情况下支持的设置/认证方法 id。 |
| `envVars` | 否 | `string[]` | 通用设置/状态界面可在插件运行时加载前检查的环境变量。 |
### `setup` 字段
| 字段 | 必填 | 类型 | 含义 |
| ------------------ | -------- | ---------- | ------------------------------------------------------------------------------------------------- |
| `providers` | 否 | `object[]` | 在设置和 onboarding 期间暴露的 provider 设置描述符。 |
| `cliBackends` | 否 | `string[]` | 用于描述符优先设置查找的设置时后端 id。保持规范化 id 在全局唯一。 |
| `configMigrations` | 否 | `string[]` | 属于此插件 setup 表面的配置迁移 id。 |
| `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 |
| 字段 | 必填 | 类型 | 含义 |
| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的 provider 设置描述符。 |
| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置期后端 id。保持规范化 id 在全局唯一。 |
| `configMigrations` | 否 | `string[]` | 由此插件的设置界面拥有的配置迁移 id。 |
| `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 |
## `uiHints` 参考
`uiHints` 是从配置字段名到小型渲染提示的映射。
`uiHints` 是从配置字段名称到小型渲染提示的映射。
```json
{
@ -324,18 +326,18 @@ OpenClaw 会在 provider 运行时加载之前读取这些内容。
每个字段提示可包含：
| 字段 | 类型 | 含义 |
| ------------- | ---------- | -------------------------------------- |
| `label` | `string` | 面向用户的字段标签。 |
| `help` | `string` | 简短辅助文本。 |
| `tags` | `string[]` | 可选的 UI 标签。 |
| `advanced` | `boolean` | 将该字段标记为高级项。 |
| `sensitive` | `boolean` | 将该字段标记为密钥或敏感项。 |
| `placeholder` | `string` | 表单输入的占位符文本。 |
| 字段 | 类型 | 含义 |
| ------------- | ---------- | --------------------------------------- |
| `label` | `string` | 面向用户的字段标签。 |
| `help` | `string` | 简短辅助文本。 |
| `tags` | `string[]` | 可选的 UI 标签。 |
| `advanced` | `boolean` | 将该字段标记为高级项。 |
| `sensitive` | `boolean` | 将该字段标记为密钥或敏感项。 |
| `placeholder` | `string` | 表单输入的占位文本。 |
## `contracts` 参考
仅在 OpenClaw 能够在不导入插件运行时的情况下读取静态能力归属元数据时，使用 `contracts`。
仅当 `contracts` 用于 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据时，才使用它。
```json
{
@ -358,31 +360,30 @@ OpenClaw 会在 provider 运行时加载之前读取这些内容。
每个列表都是可选的：
| 字段 | 类型 | 含义 |
| -------------------------------- | ---------- | ------------------------------------------------------------------ |
| `embeddedExtensionFactories` | `string[]` | 内置插件可为其注册工厂的嵌入式运行时 id。 |
| `externalAuthProviders` | `string[]` | 此插件拥有其外部凭证配置文件 hook 的 provider id。 |
| `speechProviders` | `string[]` | 此插件拥有的语音 provider id。 |
| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录 provider id。 |
| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音 provider id。 |
| `memoryEmbeddingProviders` | `string[]` | 此插件拥有的 Memory 嵌入 provider id。 |
| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解 provider id。 |
| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成 provider id。 |
| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成 provider id。 |
| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取 provider id。 |
| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索 provider id。 |
| `tools` | `string[]` | 此插件拥有的智能体工具名称，用于内置契约检查。 |
| 字段 | 类型 | 含义 |
| -------------------------------- | ---------- | ----------------------------------------------------------------- |
| `embeddedExtensionFactories` | `string[]` | 内置插件可为其注册工厂的嵌入式运行时 id。 |
| `externalAuthProviders` | `string[]` | 此插件拥有其外部认证配置文件 hook 的 provider id。 |
| `speechProviders` | `string[]` | 此插件拥有的语音 provider id。 |
| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录 provider id。 |
| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音 provider id。 |
| `memoryEmbeddingProviders` | `string[]` | 此插件拥有的 Memory 嵌入 provider id。 |
| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解 provider id。 |
| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成 provider id。 |
| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成 provider id。 |
| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取 provider id。 |
| `webSearchProviders` | `string[]` | 此插件拥有的网页搜索 provider id。 |
| `tools` | `string[]` | 此插件为内置契约检查所拥有的智能体工具名称。 |
实现 `resolveExternalAuthProfiles` 的 provider 插件应声明
实现了 `resolveExternalAuthProfiles` 的 provider 插件应声明
`contracts.externalAuthProviders`。未声明的插件仍会通过已弃用的兼容性回退路径运行，但该回退路径更慢，并将在迁移窗口结束后移除。
内置的 Memory 嵌入 provider 应为其公开的每个适配器 id 声明
`contracts.memoryEmbeddingProviders`，包括诸如 `local` 之类的内置适配器。
独立 CLI 路径使用此清单契约，在完整 Gateway 网关运行时注册 provider 之前，仅加载所属插件。
`contracts.memoryEmbeddingProviders`，包括诸如 `local` 之类的内置适配器。独立 CLI 路径使用此清单契约在完整 Gateway 网关运行时注册 provider 之前，仅加载所属插件。
## `mediaUnderstandingProviderMetadata` 参考
当媒体理解 provider 具有默认模型、自动凭证回退优先级，或 generic core helpers 在运行时加载之前需要的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键也必须在 `contracts.mediaUnderstandingProviders` 中声明。
当媒体理解 provider 具有默认模型、自动认证回退优先级或原生文档支持，且通用核心辅助工具在运行时加载前需要这些信息时，请使用 `mediaUnderstandingProviderMetadata`。键也必须在 `contracts.mediaUnderstandingProviders` 中声明。
```json
{
@ -407,16 +408,16 @@ OpenClaw 会在 provider 运行时加载之前读取这些内容。
每个 provider 条目可包含：
| 字段 | 类型 | 含义 |
| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------ |
| `capabilities` | `("image" \| "audio" \| "video")[]` | 此 provider 公开的媒体能力。 |
| `defaultModels` | `Record<string, string>` | 当配置未指定模型时使用的“能力到模型”默认值。 |
| `autoPriority` | `Record<string, number>` | 用于基于凭证的自动 provider 回退时，数字越小排序越靠前。 |
| `nativeDocumentInputs` | `"pdf"[]` | provider 支持的原生文档输入。 |
| 字段 | 类型 | 含义 |
| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
| `capabilities` | `("image" \| "audio" \| "video")[]` | 此 provider 提供的媒体能力。 |
| `defaultModels` | `Record<string, string>` | 当配置未指定模型时使用的“能力到模型”默认值。 |
| `autoPriority` | `Record<string, number>` | 用于基于凭证自动回退 provider 时，数字越小排序越靠前。 |
| `nativeDocumentInputs` | `"pdf"[]` | 该 provider 支持的原生文档输入。 |
## `channelConfigs` 参考
当渠道插件在运行时加载之前需要轻量配置元数据时，请使用 `channelConfigs`。
当渠道插件在运行时加载前需要低成本的配置元数据时，请使用 `channelConfigs`。
```json
{
@ -445,17 +446,17 @@ OpenClaw 会在 provider 运行时加载之前读取这些内容。
每个渠道条目可包含：
| 字段 | 类型 | 含义 |
| 字段 | 类型 | 含义 |
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| `schema` | `object` | `channels.<id>` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 |
| `uiHints` | `Record<string, object>` | 该渠道配置部分的可选 UI 标签/占位符/敏感性提示。 |
| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查表面的渠道标签。 |
| `description` | `string` | 用于检查和 catalog 表面的简短渠道描述。 |
| `preferOver` | `string[]` | 在选择表面中，此渠道应优先于其排序的旧版或较低优先级插件 id。 |
| `schema` | `object` | `channels.<id>` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 |
| `uiHints` | `Record<string, object>` | 该渠道配置区块的可选 UI 标签 / 占位符 / 敏感性提示。 |
| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面中的渠道标签。 |
| `description` | `string` | 用于检查和目录界面的简短渠道说明。 |
| `preferOver` | `string[]` | 在选择界面中，此渠道应优先于的旧版或较低优先级插件 id。 |
## `modelSupport` 参考
当 OpenClaw 应在插件运行时加载之前，根据诸如 `gpt-5.5` 或 `claude-sonnet-4.6` 这样的简写模型 id 推断你的 provider 插件时，请使用 `modelSupport`。
当 OpenClaw 应在插件运行时加载前，根据诸如 `gpt-5.5` 或 `claude-sonnet-4.6` 这样的简写模型 id 推断出你的 provider 插件时，请使用 `modelSupport`。
```json
{
@ -466,19 +467,19 @@ OpenClaw 会在 provider 运行时加载之前读取这些内容。
}
```
OpenClaw 按以下优先级应用：
OpenClaw 按以下优先级处理：
- 显式的 `provider/model` 引用使用所属 `providers` 清单元数据
- 显式 `provider/model` 引用使用所属 `providers` 清单元数据
- `modelPatterns` 优先于 `modelPrefixes`
- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出
- 其余歧义会被忽略，直到用户或配置指定 provider
- 若仍存在歧义，则在用户或配置明确指定 provider 之前会忽略该歧义
字段：
| 字段 | 类型 | 含义 |
| --------------- | ---------- | -------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | 使用 `startsWith` 针对简写模型 id 进行匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除 profile 后缀后，针对简写模型 id 进行匹配的正则表达式源。 |
| 字段 | 类型 | 含义 |
| --------------- | ---------- | ------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | 对简写模型 id 使用 `startsWith` 进行匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除 profile 后缀后，对简写模型 id 进行匹配的正则表达式源码。 |
旧版顶层能力键已弃用。使用 `openclaw doctor --fix` 将
`speechProviders`、`realtimeTranscriptionProviders`、
@ -486,56 +487,55 @@ OpenClaw 按以下优先级应用：
`imageGenerationProviders`、`videoGenerationProviders`、
`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；常规清单加载不再将这些顶层字段视为能力归属。
## 清单与 package.json 的区别
## 清单与 `package.json` 的区别
这两个文件承担不同的职责：
这两个文件承担不同职责：
| 文件 | 用途 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw.plugin.json` | 设备发现、配置验证、凭证选择元数据，以及在插件代码运行前必须存在的 UI 提示 |
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、setup 或 catalog 元数据的 `openclaw` 区块 |
| 文件 | 用途 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | 发现、配置校验、认证选项元数据，以及在插件代码运行前必须存在的 UI 提示 |
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 区块 |
如果你不确定某段元数据应放在哪里，请使用以下规则：
如果你不确定某条元数据应放在哪里，请使用以下规则：
- 如果 OpenClaw 必须在加载插件代码之前知道它，请将其放在 `openclaw.plugin.json` 中
- 如果它与打包、入口文件或 npm 安装行为有关，请将其放在 `package.json` 中
- 如果 OpenClaw 必须在加载插件代码前知道它，请将其放在 `openclaw.plugin.json`
- 如果它与打包、入口文件或 npm 安装行为有关，请将其放在 `package.json`
### 影响设备发现的 `package.json` 字段
### 会影响发现流程的 `package.json` 字段
某些运行时前插件元数据有意放在 `package.json` 的 `openclaw` 区块下，而不是 `openclaw.plugin.json` 中。
某些运行时前的插件元数据被有意放在 `package.json` 的
`openclaw` 区块下，而不是 `openclaw.plugin.json` 中。
重要示例：
| 字段 | 含义 |
| 字段 | 含义 |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw.extensions` | 声明原生插件入口点。必须保持在插件包目录内。 |
| `openclaw.runtimeExtensions` | 为已安装包声明已构建的 JavaScript 运行时入口点。必须保持在插件包目录内。 |
| `openclaw.setupEntry` | 在 onboarding、延迟渠道启动和只读渠道状态/SecretRef 发现期间使用的轻量仅 setup 入口点。必须保持在插件包目录内。 |
| `openclaw.runtimeSetupEntry` | 为已安装包声明已构建的 JavaScript setup 入口点。必须保持在插件包目录内。 |
| `openclaw.channel` | 轻量渠道 catalog 元数据，例如标签、文档路径、别名和选择文案。 |
| `openclaw.channel.configuredState` | 轻量 configured-state 检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅由环境变量驱动的设置？”。 |
| `openclaw.channel.persistedAuthState` | 轻量持久化凭证检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何账户登录？”。 |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置插件和外部发布插件的安装/更新提示。 |
| `openclaw.install.defaultChoice` | 当存在多个安装来源时的首选安装路径。 |
| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw host 版本，使用如 `>=2026.3.22` 这样的 semver 下限。 |
| `openclaw.install.expectedIntegrity` | 预期的 npm 分发完整性字符串，例如 `sha512-...`；安装和更新流程会根据它验证获取的构件。 |
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个范围很窄的内置插件重新安装恢复路径。 |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许仅 setup 的渠道表面在启动期间先于完整渠道插件加载。 |
| `openclaw.extensions` | 声明原生插件入口点。必须保持在插件包目录内。 |
| `openclaw.runtimeExtensions` | 为已安装包声明构建后的 JavaScript 运行时入口点。必须保持在插件包目录内。 |
| `openclaw.setupEntry` | 在新手引导、延迟渠道启动以及只读渠道状态 / SecretRef 发现期间使用的轻量级仅设置入口点。必须保持在插件包目录内。 |
| `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保持在插件包目录内。 |
| `openclaw.channel` | 轻量级渠道目录元数据，例如标签、文档路径、别名和选择文案。 |
| `openclaw.channel.configuredState` | 轻量级已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅环境变量设置？”。 |
| `openclaw.channel.persistedAuthState` | 轻量级持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何账号登录？”。 |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置插件和外部发布插件的安装 / 更新提示。 |
| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 |
| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用如 `>=2026.3.22` 这样的 semver 下限。 |
| `openclaw.install.expectedIntegrity` | 预期的 npm 分发完整性字符串，例如 `sha512-...`；安装和更新流程会据此校验获取到的工件。 |
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个范围很窄的内置插件重新安装恢复路径。 |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置用的渠道界面，再加载完整渠道插件。 |
清单元数据决定了在运行时加载之前，哪些 provider/渠道/setup 选项会出现在 onboarding 中。`package.json#openclaw.install` 则告诉 onboarding，当用户选择其中某个选项时，应如何获取或启用该插件。不要将安装提示移到 `openclaw.plugin.json` 中。
清单元数据决定了在运行时加载前，新手引导中会出现哪些 provider / 渠道 / 设置选项。`package.json#openclaw.install` 则告诉新手引导，当用户选择其中某个选项时，应如何获取或启用该插件。不要将安装提示移到 `openclaw.plugin.json` 中。
`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；较新的但有效的值会导致插件在较旧 host 上被跳过。
`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会让该插件在较旧主机上被跳过。
精确的 npm 版本固定已经存在于 `npmSpec` 中，例如
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。当你希望如果获取到的
npm 构件不再匹配固定版本时，更新流程以失败关闭的方式处理，就将其与
`expectedIntegrity` 搭配使用。交互式 onboarding 会提供受信任注册表的 npm 规范，包括裸包名和 dist-tag。存在 `expectedIntegrity` 时，安装/更新流程会强制校验它；省略时，将记录注册表解析结果，但不会固定完整性。
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。当你希望一旦获取到的 npm 工件不再匹配固定发布版本时，更新流程能够以失败即关闭的方式处理，就应将其与 `expectedIntegrity` 搭配使用。交互式新手引导会提供受信任注册表的 npm 规格，包括裸包名和 dist-tag。存在 `expectedIntegrity` 时，安装 / 更新流程会强制校验它；省略时，注册表解析结果会被记录，但不会带完整性固定。
当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账户时，渠道插件应提供 `openclaw.setupEntry`。该 setup 入口点应公开渠道元数据，以及对 setup 安全的配置、状态和密钥适配器；将网络客户端、Gateway 网关监听器和传输运行时保留在主扩展入口点中。
渠道插件应提供 `openclaw.setupEntry`，以便状态、渠道列表或 SecretRef 扫描在不加载完整运行时的情况下识别已配置账号。该设置入口点应暴露渠道元数据以及可安全用于设置的配置、状态和 secrets 适配器；网络客户端、网关监听器和传输运行时应保留在主扩展入口点中。
运行时入口点字段不会覆盖源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越界的 `openclaw.extensions` 路径变得可加载。
运行时入口点字段不会覆盖源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越出边界的 `openclaw.extensions` 路径变为可加载。
`openclaw.install.allowInvalidConfigRecovery` 的范围是有意收窄的。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一内置插件下陈旧的 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并将操作人员引导到 `openclaw doctor --fix`。
`openclaw.install.allowInvalidConfigRecovery` 的设计范围刻意很窄。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一内置插件的陈旧 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并将操作员引导至 `openclaw doctor --fix`。
`openclaw.channel.persistedAuthState` 是一个微型检查器模块的包元数据：
@ -553,9 +553,9 @@ npm 构件不再匹配固定版本时，更新流程以失败关闭的方式处
}
```
当 setup、Doctor 或 configured-state 流程需要在完整渠道插件加载之前进行轻量的是/否凭证探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 转发它。
当设置、Doctor 或已配置状态流程在完整渠道插件加载前需要一个低成本的认证“是 / 否”探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 暴露它。
`openclaw.channel.configuredState` 对应廉价的仅环境变量 configured 检查，结构相同：
`openclaw.channel.configuredState` 对低成本的仅环境变量配置检查使用相同结构：
```json
{
@ -571,57 +571,58 @@ npm 构件不再匹配固定版本时，更新流程以失败关闭的方式处
}
```
当一个渠道可以从环境变量或其他轻量非运行时输入回答 configured-state 时，请使用它。如果检查需要完整配置解析或真实渠道运行时，则应将该逻辑保留在插件的 `config.hasConfiguredState` hook 中。
当某个渠道可以仅通过环境变量或其他很小的非运行时输入来回答已配置状态时，请使用它。如果检查需要完整配置解析或真实的渠道运行时，则应将该逻辑保留在插件 `config.hasConfiguredState` hook 中。
## 设备发现优先级（重复插件 id）
## 发现优先级（重复插件 id）
OpenClaw 会从多个根位置发现插件（内置、全局安装、工作区、显式配置选择的路径）。如果两个发现结果共享同一个 `id`，则只保留**优先级最高**的清单；优先级较低的重复项会被丢弃，而不是并行加载。
OpenClaw 会从多个根位置发现插件（内置、全局安装、工作区、配置中显式选择的路径）。如果两个发现结果共享相同的 `id`，则只保留**优先级最高**的清单；优先级较低的重复项会被丢弃，而不是与其并行加载。
优先级从高到低如下：
1. **配置选择** —— 在 `plugins.entries.<id>` 中显式固定的路径
1. **配置选定** —— 在 `plugins.entries.<id>` 中显式固定的路径
2. **内置** —— 随 OpenClaw 一起发布的插件
3. **全局安装** —— 安装到全局 OpenClaw 插件根目录中的插件
3. **全局安装** —— 安装到全局 OpenClaw 插件根目录的插件
4. **工作区** —— 相对于当前工作区发现的插件
含义：
影响：
- 放在工作区中的某个内置插件分叉版或陈旧副本，不会遮蔽内置构建。
- 如果要真正用本地插件覆盖内置插件，请通过 `plugins.entries.<id>` 固定它，使其凭借优先级取胜，而不是依赖工作区发现。
- 被丢弃的重复项会记录日志，以便 Doctor 和启动诊断能够指向被舍弃的副本。
- 位于工作区中的某个内置插件 fork 或过时副本，不会遮蔽内置构建版本。
- 如果你确实要用本地插件覆盖某个内置插件，应通过 `plugins.entries.<id>` 固定它，使其凭借优先级获胜，而不是依赖工作区发现。
- 重复项丢弃会被记录日志，这样 Doctor 和启动诊断就能指出被丢弃的副本。
## JSON Schema 要求
- **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。
- 接受空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。
- Schema 会在配置读取/写入时验证，而不是在运行时验证。
- 允许使用空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。
- Schema 会在配置读取 / 写入时校验，而不是在运行时校验。
## 验证行为
## 校验行为
- 未知的 `channels.*` 键是**错误**，除非该渠道 id 已由某个插件清单声明。
- 未知的 `channels.*` 键是**错误**，除非该渠道 id 由某个插件清单声明。
- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*`
必须引用**可发现**的插件 id。未知 id 属于**错误**。
- 如果插件已安装，但其清单或 schema 损坏或缺失，验证会失败，Doctor 会报告该插件错误。
- 如果插件配置存在，但插件已**禁用**，则配置会被保留，并且 Doctor + 日志中会显示**警告**。
必须引用**可发现的**插件 id。未知 id 属于**错误**。
- 如果某个插件已安装，但其清单或 schema 缺失或损坏，则校验会失败，Doctor 会报告该插件错误。
- 如果插件配置存在，但插件处于**禁用**状态，配置会被保留，并且 Doctor + 日志中会显示一条**警告**。
有关完整的 `plugins.*` 模式，请参阅[配置参考](/zh-CN/gateway/configuration)。
完整的 `plugins.*` schema 请参阅 [配置参考](/zh-CN/gateway/configuration)。
## 说明
- 对于**原生 OpenClaw 插件**，包括本地文件系统加载，清单都是**必需的**。运行时仍会单独加载插件模块；清单仅用于设备发现 + 验证。
- 原生清单使用 JSON5 解析，因此只要最终值仍是对象，就接受注释、尾随逗号和未加引号的键。
- 清单加载器只会读取文档中说明的清单字段。避免使用自定义顶层键。
- 当插件不需要它们时，`channels`、`providers`、`cliBackends` 和 `skills` 都可以省略。
- 排他性插件类型通过 `plugins.slots.*` 选择：`kind: "memory"` 通过 `plugins.slots.memory` 选择，`kind: "context-engine"` 通过 `plugins.slots.contextEngine` 选择（默认 `legacy`）。
- 环境变量元数据（`providerAuthEnvVars`、`channelEnvVars`）仅为声明式。状态、审计、cron 投递验证以及其他只读表面，在将环境变量视为已配置之前，仍会应用插件信任和有效激活策略。
- 有关需要 provider 代码的运行时向导元数据，请参阅 [Provider runtime hooks](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。
- 对于**原生 OpenClaw 插件**，包括本地文件系统加载，清单都是**必需的**。运行时仍会单独加载插件模块；清单仅用于发现 + 校验。
- 原生清单使用 JSON5 解析，因此允许注释、尾随逗号和未加引号的键，只要最终值仍是一个对象即可。
- 清单加载器只会读取有文档说明的清单字段。避免使用自定义顶层键。
- 当插件不需要时，`channels`、`providers`、`cliBackends` 和 `skills` 都可以省略。
- `providerDiscoveryEntry` 必须保持轻量，不应导入庞大的运行时代码；应将其用于静态 provider 目录元数据或窄范围发现描述符，而不是请求时执行。
- 排他性插件类型通过 `plugins.slots.*` 选择：`kind: "memory"` 通过 `plugins.slots.memory`，`kind: "context-engine"` 通过 `plugins.slots.contextEngine`（默认 `legacy`）。
- 环境变量元数据（`providerAuthEnvVars`、`channelEnvVars`）仅具声明性。状态、审计、cron 投递校验和其他只读界面，在将环境变量视为已配置之前，仍会应用插件信任和有效激活策略。
- 对于需要 provider 代码的运行时向导元数据，请参阅 [Provider runtime hooks](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。
- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器 allowlist 要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild <package>`）。
## 相关内容
<CardGroup cols={3}>
<Card title="构建插件" href="/zh-CN/plugins/building-plugins" icon="rocket">
插件快速开始。
插件入门指南。
</Card>
<Card title="插件架构" href="/zh-CN/plugins/architecture" icon="diagram-project">
内部架构和能力模型。