From 3703c6d3b825e478e9d93bb5229e06aadddf4d4a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 11 Apr 2026 01:20:52 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/gateway/cli-backends.md | 154 ++++++------ docs/zh-CN/plugins/sdk-provider-plugins.md | 258 ++++++++++++--------- 2 files changed, 238 insertions(+), 174 deletions(-) diff --git a/docs/zh-CN/gateway/cli-backends.md b/docs/zh-CN/gateway/cli-backends.md index 3035d5b0f..246c4a4fc 100644 --- a/docs/zh-CN/gateway/cli-backends.md +++ b/docs/zh-CN/gateway/cli-backends.md @@ -1,41 +1,41 @@ --- read_when: - - 当 API 提供商失败时，你需要一个可靠的回退方案 + - 当 API 提供商失败时，你希望有一个可靠的回退方案 - 你正在运行 Codex CLI 或其他本地 AI CLI，并希望复用它们 - 你想了解用于 CLI 后端工具访问的 MCP loopback bridge -summary: CLI 后端：本地 AI CLI 回退，支持可选的 MCP 工具桥接 +summary: CLI 后端：带可选 MCP 工具桥接的本地 AI CLI 回退方案 title: CLI 后端 x-i18n: - generated_at: "2026-04-10T12:46:45Z" + generated_at: "2026-04-11T01:19:09Z" model: gpt-5.4 provider: openai - source_hash: e122831eec29a5df302a7a72e57882c566398d29d6a79be924f601ce2f7a2291 + source_hash: d108dbea043c260a80d15497639298f71a6b4d800f68d7b39bc129f7667ca608 source_path: gateway/cli-backends.md workflow: 15 --- # CLI 后端（回退运行时） -当 API 提供商不可用、触发速率限制或暂时行为异常时，OpenClaw 可以将**本地 AI CLI** 作为**纯文本回退**来运行。这一设计有意保持保守： +当 API 提供商不可用、受到速率限制或暂时行为异常时，OpenClaw 可以运行**本地 AI CLI** 作为**纯文本回退**。这是一种有意保守的设计： -- **不会直接注入 OpenClaw 工具**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP bridge 接收 Gateway 网关工具。 -- 对支持的 CLI 提供 **JSONL 流式传输**。 -- **支持会话**（因此后续轮次能够保持连贯）。 -- 如果 CLI 接受图片路径，**图片可以透传**。 +- **OpenClaw 工具不会被直接注入**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP bridge 接收 Gateway 网关工具。 +- 支持相关 CLI 的 **JSONL 流式传输**。 +- **支持会话**（因此后续轮次能保持连贯）。 +- 如果 CLI 接受图像路径，**图片可以透传**。 -这被设计为一个**安全网**，而不是主要路径。当你希望获得“不管怎样都能工作”的文本响应，而不依赖外部 API 时，可以使用它。 +这被设计为一个**安全兜底方案**，而不是主要路径。当你希望在不依赖外部 API 的情况下获得“始终可用”的文本响应时，可以使用它。 -如果你需要带有 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。 +如果你想要具备 ACP 会话控制、后台任务、线程/会话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。 -## 面向初学者的快速开始 +## 适合初学者的快速开始 -你可以在**无需任何配置**的情况下使用 Codex CLI（内置 OpenAI 插件会注册一个默认后端）： +你可以**无需任何配置**使用 Codex CLI（内置的 OpenAI 插件会注册一个默认后端）： ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -如果你的 Gateway 网关运行在 launchd/systemd 下，且 PATH 很精简，只需添加命令路径： +如果你的 Gateway 网关运行在 launchd/systemd 下，且 `PATH` 很精简，只需添加命令路径： ```json5 { @@ -51,13 +51,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 } ``` -就是这样。除 CLI 本身之外，不需要密钥，也不需要额外的凭证配置。 +就这些。除了 CLI 自身之外，不需要密钥，也不需要额外的认证配置。 -如果你在 Gateway 网关主机上将某个内置 CLI 后端作为**主要消息提供商**使用，那么当你的配置在模型引用或 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。 +如果你在 Gateway 网关主机上将某个内置 CLI 后端用作**主要消息提供商**，当你的配置在模型引用中或在 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。 -## 将其用作回退 +## 将其用作回退方案 -将一个 CLI 后端添加到你的回退列表中，这样它只会在主模型失败时运行： +将一个 CLI 后端加入你的回退列表，这样它只会在主模型失败时运行： ```json5 { @@ -78,8 +78,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 说明： -- 如果你使用 `agents.defaults.models`（allowlist），你也必须把 CLI 后端模型包含进去。 -- 如果主提供商失败（凭证、速率限制、超时），OpenClaw 会接着尝试 CLI 后端。 +- 如果你使用 `agents.defaults.models`（允许列表），你也必须在其中包含你的 CLI 后端模型。 +- 如果主提供商失败（认证、速率限制、超时），OpenClaw 将接着尝试 CLI 后端。 ## 配置概览 @@ -90,7 +90,7 @@ agents.defaults.cliBackends ``` 每个条目都以一个**提供商 id** 为键（例如 `codex-cli`、`my-cli`）。 -这个提供商 id 会成为你的模型引用左侧部分： +该提供商 id 会成为你的模型引用左侧部分： ``` / @@ -120,7 +120,7 @@ agents.defaults.cliBackends sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", - // 对于 Codex 风格的 CLI，也可以改为指向一个提示词文件： + // 对于 Codex 风格的 CLI，也可以改为指向一个 prompt 文件： // systemPromptFileConfigArg: "-c", // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", @@ -136,66 +136,66 @@ agents.defaults.cliBackends ## 工作原理 -1. 根据提供商前缀（`codex-cli/...`）**选择一个后端**。 -2. 使用相同的 OpenClaw 提示词和工作区上下文**构建系统提示词**。 -3. 如果支持，则使用会话 id **执行 CLI**，以便历史保持一致。 +1. 根据提供商前缀（`codex-cli/...`）**选择后端**。 +2. 使用相同的 OpenClaw prompt 和工作区上下文**构建系统 prompt**。 +3. 如果支持，会使用会话 id **执行 CLI**，以保持历史一致。 4. **解析输出**（JSON 或纯文本）并返回最终文本。 -5. 按后端**持久化会话 id**，以便后续轮次复用相同的 CLI 会话。 +5. 按后端**持久化会话 id**，以便后续轮次复用同一个 CLI 会话。 -内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 工作人员告诉我们，允许以 OpenClaw 风格使用 Claude CLI，因此除非 Anthropic 发布新的政策，否则 OpenClaw 会将 `claude -p` 用法视为此集成场景下被认可的方式。 +内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，允许使用 OpenClaw 风格的 Claude CLI，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将这种 `claude -p` 用法视为该集成的许可方式。 -内置的 OpenAI `codex-cli` 后端会通过 Codex 的 `model_instructions_file` 配置覆盖项（`-c -model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 不提供类似 Claude 的 `--append-system-prompt` 标志，因此对于每个新的 Codex CLI 会话，OpenClaw 都会将组装后的提示词写入一个临时文件。 +内置的 OpenAI `codex-cli` 后端会通过 Codex 的 `model_instructions_file` 配置覆盖（`-c +model_instructions_file="..."`）传递 OpenClaw 的系统 prompt。Codex 没有提供类似 Claude 的 `--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话把组装后的 prompt 写入一个临时文件。 -内置的 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw Skills 快照：一种是附加到系统提示词中的精简版 OpenClaw Skills 目录，另一种是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件仅包含对该智能体/会话符合条件的 Skills，因此 Claude Code 原生的技能解析器看到的过滤集合，与 OpenClaw 否则会在提示词中公布的集合相同。对于本次运行，Skill 环境/API 密钥覆盖仍会由 OpenClaw 应用到子进程环境中。 +内置的 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw 的 Skills 快照：一是附加系统 prompt 中的精简 OpenClaw Skills 目录，二是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件仅包含对当前智能体/会话符合条件的 Skills，因此 Claude Code 的原生 skill 解析器看到的过滤结果，与 OpenClaw 原本会在 prompt 中通告的结果一致。对于运行过程，Skill 的环境变量/API 密钥覆盖仍然由 OpenClaw 应用到子进程环境中。 ## 会话 - 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或 - `sessionArgs`（占位符 `{sessionId}`），用于在需要将该 ID 插入多个标志时使用。 + `sessionArgs`（占位符 `{sessionId}`），以便在需要将 ID 插入多个标志时使用。 - 如果 CLI 使用带有不同标志的**恢复子命令**，请设置 `resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput` （用于非 JSON 恢复）。 - `sessionMode`： - - `always`：始终发送会话 id（如果没有已存储的就生成一个新的 UUID）。 + - `always`：始终发送会话 id（如果尚未存储，则生成新的 UUID）。 - `existing`：仅当之前已存储会话 id 时才发送。 - `none`：从不发送会话 id。 -串行化说明： +序列化说明： -- `serialize: true` 会让同一通道上的运行保持顺序。 -- 大多数 CLI 会在同一提供商通道上串行执行。 -- 当后端凭证状态发生变化时，包括重新登录、令牌轮换或凭证配置文件发生变化，OpenClaw 会丢弃已存储的 CLI 会话复用状态。 +- `serialize: true` 会让同一通道的运行保持顺序。 +- 大多数 CLI 会在一个提供商通道上串行执行。 +- 当后端认证状态发生变化时，包括重新登录、令牌轮换或认证配置文件凭证变更，OpenClaw 会丢弃已存储的 CLI 会话复用状态。 ## 图片（透传） -如果你的 CLI 接受图片路径，请设置 `imageArg`： +如果你的 CLI 接受图像路径，请设置 `imageArg`： ```json5 imageArg: "--image", imageMode: "repeat" ``` -OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传递。如果缺少 `imageArg`，OpenClaw 会将文件路径附加到提示词中（路径注入）；这对于那些可以从普通路径自动加载本地文件的 CLI 来说已经足够。 +OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传递。如果缺少 `imageArg`，OpenClaw 会将文件路径附加到 prompt 中（路径注入），这对于那些能从普通路径自动加载本地文件的 CLI 已经足够。 ## 输入 / 输出 -- `output: "json"`（默认）会尝试解析 JSON，并提取文本与会话 id。 +- `output: "json"`（默认）会尝试解析 JSON，并提取文本 + 会话 id。 - 对于 Gemini CLI 的 JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 `stats` 读取用量。 -- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及存在时的会话标识符。 +- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并在存在时提取最终智能体消息和会话标识符。 - `output: "text"` 会将 stdout 视为最终响应。 输入模式： -- `input: "arg"`（默认）将提示词作为最后一个 CLI 参数传递。 -- `input: "stdin"` 通过 stdin 发送提示词。 -- 如果提示词很长且设置了 `maxPromptArgChars`，则会改用 stdin。 +- `input: "arg"`（默认）将 prompt 作为最后一个 CLI 参数传递。 +- `input: "stdin"` 通过 stdin 发送 prompt。 +- 如果 prompt 很长且设置了 `maxPromptArgChars`，则会改用 stdin。 ## 默认值（插件自有） -内置 OpenAI 插件也会为 `codex-cli` 注册一个默认值： +内置的 OpenAI 插件还为 `codex-cli` 注册了默认值： - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -206,7 +206,7 @@ OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`， - `imageArg: "--image"` - `sessionMode: "existing"` -内置 Google 插件也会为 `google-gemini-cli` 注册一个默认值： +内置的 Google 插件也为 `google-gemini-cli` 注册了默认值： - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -217,8 +217,8 @@ OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`， - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -前提条件：本地 Gemini CLI 必须已安装，并且可以通过 `PATH` 中的 -`gemini` 使用（`brew install gemini-cli` 或 +前提条件：本地 Gemini CLI 必须已安装，并且可在 +`PATH` 中作为 `gemini` 使用（`brew install gemini-cli` 或 `npm install -g @google/gemini-cli`）。 Gemini CLI JSON 说明： @@ -233,46 +233,70 @@ Gemini CLI JSON 说明： ## 插件自有默认值 -CLI 后端默认值现在是插件接口的一部分： +CLI 后端默认值现在是插件表面的一部分： -- 插件通过 `api.registerCliBackend(...)` 注册它们。 +- 插件使用 `api.registerCliBackend(...)` 注册它们。 - 后端的 `id` 会成为模型引用中的提供商前缀。 - `agents.defaults.cliBackends.` 中的用户配置仍会覆盖插件默认值。 -- 后端特定的配置清理由可选的 `normalizeConfig` hook 继续保持为插件自有。 +- 特定后端的配置清理仍由插件通过可选的 + `normalizeConfig` hook 自行处理。 -## Bundle MCP 覆盖层 +需要进行轻量 prompt/消息兼容性调整的插件，可以声明双向文本转换，而无需替换提供商或 CLI 后端： -CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 选择接收一个生成的 MCP 配置覆盖层。 +```typescript +api.registerTextTransforms({ + input: [ + { from: /red basket/g, to: "blue basket" }, + { from: /paper ticket/g, to: "digital ticket" }, + { from: /left shelf/g, to: "right shelf" }, + ], + output: [ + { from: /blue basket/g, to: "red basket" }, + { from: /digital ticket/g, to: "paper ticket" }, + { from: /right shelf/g, to: "left shelf" }, + ], +}); +``` + +`input` 会重写传递给 CLI 的系统 prompt 和用户 prompt。`output` +会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式传输的 assistant 增量内容以及解析后的最终文本。 + +对于输出与 Claude Code stream-json 兼容的 JSONL 的 CLI，请在该后端配置上设置 +`jsonlDialect: "claude-stream-json"`。 + +## bundle MCP 覆盖层 + +CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 选择接收生成的 MCP 配置覆盖层。 当前内置行为： -- `claude-cli`：生成严格的 MCP 配置文件 -- `codex-cli`：对 `mcp_servers` 的内联配置覆盖 -- `google-gemini-cli`：生成 Gemini system settings 文件 +- `claude-cli`：生成的严格 MCP 配置文件 +- `codex-cli`：针对 `mcp_servers` 的内联配置覆盖 +- `google-gemini-cli`：生成的 Gemini 系统设置文件 -启用 bundle MCP 时，OpenClaw 会： +启用 bundle MCP 后，OpenClaw 会： - 启动一个 loopback HTTP MCP 服务器，将 Gateway 网关工具暴露给 CLI 进程 -- 使用每会话令牌（`OPENCLAW_MCP_TOKEN`）对 bridge 进行认证 -- 将工具访问范围限制在当前会话、账户和渠道上下文中 +- 使用每个会话独有的令牌（`OPENCLAW_MCP_TOKEN`）对 bridge 进行认证 +- 将工具访问范围限定为当前会话、账户和渠道上下文 - 为当前工作区加载已启用的 bundle-MCP 服务器 - 将它们与任何现有的后端 MCP 配置/设置结构合并 -- 使用所属扩展中由后端自有的集成模式重写启动配置 +- 使用所属扩展中由后端自行定义的集成模式重写启动配置 -如果没有启用任何 MCP 服务器，只要某个后端选择启用 bundle MCP，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。 +即使没有启用任何 MCP 服务器，只要后端选择启用 bundle MCP，OpenClaw 仍会注入严格配置，以确保后台运行保持隔离。 ## 限制 - **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用注入到 - CLI 后端协议中。后端只有在选择启用 `bundleMcp: true` 时才会看到 Gateway 网关工具。 -- **流式传输取决于后端。** 某些后端会流式输出 JSONL；其他后端则会缓冲直到退出。 + CLI 后端协议中。后端只有在选择 `bundleMcp: true` 时，才能看到 Gateway 网关工具。 +- **流式传输是后端特定的。** 有些后端会流式输出 JSONL；另一些则会一直缓冲到退出。 - **结构化输出** 取决于 CLI 的 JSON 格式。 -- **Codex CLI 会话** 通过文本输出恢复（没有 JSONL），其结构性不如初始的 `--json` 运行。OpenClaw 会话本身仍可正常工作。 +- **Codex CLI 会话** 通过文本输出恢复（不是 JSONL），其结构化程度低于初始的 `--json` 运行。不过 OpenClaw 会话仍能正常工作。 ## 故障排除 - **找不到 CLI**：将 `command` 设置为完整路径。 -- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。 +- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射为 CLI 模型。 - **没有会话连续性**：确保已设置 `sessionArg`，并且 `sessionMode` 不是 - `none`（Codex CLI 当前无法通过 JSON 输出恢复）。 + `none`（Codex CLI 目前无法以 JSON 输出恢复）。 - **图片被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。 diff --git a/docs/zh-CN/plugins/sdk-provider-plugins.md b/docs/zh-CN/plugins/sdk-provider-plugins.md index f553cc81a..844049901 100644 --- a/docs/zh-CN/plugins/sdk-provider-plugins.md +++ b/docs/zh-CN/plugins/sdk-provider-plugins.md @@ -1,30 +1,30 @@ --- read_when: - 你正在构建一个新的模型提供商插件 - - 你想将兼容 OpenAI 的代理或自定义 LLM 添加到 OpenClaw 中 - - 你需要理解提供商凭证、目录和运行时钩子 + - 你想将一个兼容 OpenAI 的代理或自定义 LLM 添加到 OpenClaw 中 + - 你需要了解提供商认证、目录和运行时钩子 sidebarTitle: Provider Plugins summary: 为 OpenClaw 构建模型提供商插件的分步指南 title: 构建提供商插件 x-i18n: - generated_at: "2026-04-10T20:23:44Z" + generated_at: "2026-04-11T01:19:18Z" model: gpt-5.4 provider: openai - source_hash: b81b80627fd594e2dc889c95359df665ebbbb85c74c231a226219dcb556f193b + source_hash: 06d7c5da6556dc3d9673a31142ff65eb67ddc97fc0c1a6f4826a2c7693ecd5e3 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # 构建提供商插件 -本指南将带你构建一个为 OpenClaw 添加模型提供商（LLM）的提供商插件。完成后，你将拥有一个包含模型目录、API 密钥凭证以及动态模型解析的提供商。 +本指南将带你构建一个为 OpenClaw 添加模型提供商（LLM）的提供商插件。完成后，你将拥有一个带有模型目录、API 密钥认证和动态模型解析的提供商。 - 如果你之前没有构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基础包结构和清单设置。 + 如果你之前从未构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins) 以了解基础包结构和清单设置。 - 提供商插件会将模型添加到 OpenClaw 的常规推理循环中。如果模型必须通过一个拥有线程、压缩或工具事件的原生智能体守护进程运行，请将该提供商与 [agent harness](/zh-CN/plugins/sdk-agent-harness) 搭配使用，而不是把守护进程协议细节放进核心中。 + 提供商插件会将模型添加到 OpenClaw 的常规推理循环中。如果模型必须通过一个原生智能体守护进程运行，并且该守护进程负责线程、压缩或工具事件，请将该提供商与一个 [agent harness](/zh-CN/plugins/sdk-agent-harness) 配合使用，而不是把守护进程协议细节放进核心中。 ## 演练 @@ -57,7 +57,7 @@ x-i18n: { "id": "acme-ai", "name": "Acme AI", - "description": "Acme AI 模型提供商", + "description": "Acme AI model provider", "providers": ["acme-ai"], "modelSupport": { "modelPrefixes": ["acme-"] @@ -73,12 +73,12 @@ x-i18n: "provider": "acme-ai", "method": "api-key", "choiceId": "acme-ai-api-key", - "choiceLabel": "Acme AI API 密钥", + "choiceLabel": "Acme AI API key", "groupId": "acme-ai", "groupLabel": "Acme AI", "cliFlag": "--acme-ai-api-key", "cliOption": "--acme-ai-api-key ", - "cliDescription": "Acme AI API 密钥" + "cliDescription": "Acme AI API key" } ], "configSchema": { @@ -89,7 +89,7 @@ x-i18n: ``` - 清单声明了 `providerAuthEnvVars`，这样 OpenClaw 无需加载你的插件运行时就能检测凭证。当某个提供商变体应复用另一个提供商 id 的凭证时，请添加 `providerAuthAliases`。`modelSupport` 是可选的，它允许 OpenClaw 在运行时钩子存在之前，先根据类似 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你要在 ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段是必需的。 + 清单声明了 `providerAuthEnvVars`，这样 OpenClaw 无需加载你的插件运行时就能检测凭证。当某个提供商变体应复用另一个提供商 id 的认证时，添加 `providerAuthAliases`。`modelSupport` 是可选的，它允许 OpenClaw 在运行时钩子存在之前，就根据像 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你要在 ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段是必需的。 @@ -165,9 +165,30 @@ x-i18n: }); ``` - 这样就得到一个可工作的提供商了。用户现在可以运行 `openclaw onboard --acme-ai-api-key ` 并选择 `acme-ai/acme-large` 作为他们的模型。 + 这就是一个可用的提供商。现在用户可以运行 + `openclaw onboard --acme-ai-api-key `，并选择 + `acme-ai/acme-large` 作为他们的模型。 - 对于只注册一个文本提供商、使用 API 密钥凭证，并且只有一个基于目录的运行时的内置提供商，优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数： + 如果上游提供商使用的控制令牌与 OpenClaw 不同，请添加一个小型双向文本转换，而不是替换流路径： + + ```typescript + api.registerTextTransforms({ + input: [ + { from: /red basket/g, to: "blue basket" }, + { from: /paper ticket/g, to: "digital ticket" }, + { from: /left shelf/g, to: "right shelf" }, + ], + output: [ + { from: /blue basket/g, to: "red basket" }, + { from: /digital ticket/g, to: "paper ticket" }, + { from: /right shelf/g, to: "left shelf" }, + ], + }); + ``` + + `input` 会在传输前重写最终系统提示和文本消息内容。`output` 会在 OpenClaw 解析其自身控制标记或进行渠道投递之前，重写助手文本增量和最终文本。 + + 对于只注册一个带 API 密钥认证的文本提供商，并且只有一个基于目录的运行时的内置提供商，优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助方法： ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -202,9 +223,9 @@ x-i18n: }); ``` - 如果你的凭证流程还需要在新手引导期间修补 `models.providers.*`、别名以及智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数包括 `createDefaultModelPresetAppliers(...)`、`createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。 + 如果你的认证流程还需要在新手引导期间修补 `models.providers.*`、别名以及智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助方法。最窄的辅助方法是 `createDefaultModelPresetAppliers(...)`、`createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。 - 当某个提供商的原生端点在常规 `openai-completions` 传输协议上支持分块流式传输使用量块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和 `applyProviderNativeStreamingUsageCompat(...)` 会根据端点能力映射检测支持情况，因此即使插件使用的是自定义提供商 id，原生 Moonshot/DashScope 风格端点仍然可以选择启用。 + 当提供商的原生端点在常规 `openai-completions` 传输上支持分块流式传输使用块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助方法，而不是硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和 `applyProviderNativeStreamingUsageCompat(...)` 会从端点能力映射中检测支持情况，因此即使插件使用的是自定义提供商 id，原生 Moonshot/DashScope 风格的端点仍然可以选择启用。 @@ -230,14 +251,14 @@ x-i18n: }); ``` - 如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步预热 —— 完成后会再次运行 `resolveDynamicModel`。 + 如果解析需要进行网络调用，请使用 `prepareDynamicModel` 进行异步预热 —— 在其完成后会再次运行 `resolveDynamicModel`。 - 大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着你的提供商提出更高要求，再逐步添加钩子。 + 大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着你的提供商需要更多能力，再逐步添加钩子。 - 共享辅助构建器现在已覆盖最常见的重放/工具兼容性系列，因此插件通常不需要手动逐个连接每个钩子： + 共享辅助构建器现在已经覆盖最常见的重放/工具兼容性系列，因此插件通常不需要逐个手动接线每个钩子： ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -259,13 +280,13 @@ x-i18n: 当前可用的重放系列： - | 系列 | 它会接入的内容 | + | 系列 | 接入内容 | | --- | --- | - | `openai-compatible` | OpenAI 兼容传输协议的共享 OpenAI 风格重放策略，包括工具调用 id 清理、assistant-first 顺序修复，以及传输协议需要时的通用 Gemini 轮次校验 | - | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知重放策略，因此 Anthropic 消息传输协议只会在解析出的模型确实是 Claude id 时，才获得 Claude 专用的思维块清理 | - | `google-gemini` | 原生 Gemini 重放策略，加上引导重放清理和带标签的推理输出模式 | - | `passthrough-gemini` | 用于通过 OpenAI 兼容代理传输协议运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini 重放校验或引导重写 | - | `hybrid-anthropic-openai` | 适用于在一个插件中混合 Anthropic 消息和 OpenAI 兼容模型面的提供商的混合策略；可选的仅 Claude 思维块丢弃仍然只作用于 Anthropic 一侧 | + | `openai-compatible` | 用于兼容 OpenAI 传输的共享 OpenAI 风格重放策略，包括工具调用 id 清理、助手优先顺序修复，以及在传输需要时的通用 Gemini 回合校验 | + | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知重放策略，因此 Anthropic 消息传输只有在解析后的模型确实是 Claude id 时，才会获得 Claude 特有的思维块清理 | + | `google-gemini` | 原生 Gemini 重放策略，外加引导重放清理和带标签的推理输出模式 | + | `passthrough-gemini` | 用于通过兼容 OpenAI 的代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini 重放校验或引导重写 | + | `hybrid-anthropic-openai` | 适用于在同一个插件中混合 Anthropic 消息和兼容 OpenAI 的模型表面的提供商的混合策略；可选的仅 Claude 思维块丢弃仍然只作用于 Anthropic 一侧 | 真实的内置示例： @@ -275,17 +296,17 @@ x-i18n: - `minimax`：`hybrid-anthropic-openai` - `moonshot`、`ollama`、`xai` 和 `zai`：`openai-compatible` - 当前可用的流式系列： + 当前可用的流系列： - | 系列 | 它会接入的内容 | + | 系列 | 接入内容 | | --- | --- | | `google-thinking` | 共享流路径上的 Gemini thinking 负载规范化 | - | `kilocode-thinking` | 共享代理流路径上的 Kilo 推理包装器，其中 `kilo/auto` 和不受支持的代理推理 id 会跳过注入的 thinking | - | `moonshot-thinking` | 根据配置和 `/think` 级别，将 Moonshot 二进制原生 thinking 负载进行映射 | - | `minimax-fast-mode` | 共享流路径上的 MiniMax fast-mode 模型重写 | - | `openai-responses-defaults` | 共享原生 OpenAI/Codex Responses 包装器：归因头、`/fast`/`serviceTier`、文本冗长度、原生 Codex web search、推理兼容负载整形，以及 Responses 上下文管理 | - | `openrouter-thinking` | 用于代理路由的 OpenRouter 推理包装器，集中处理不受支持模型和 `auto` 跳过逻辑 | - | `tool-stream-default-on` | 为像 Z.AI 这样希望默认启用工具流式传输的提供商提供默认开启的 `tool_stream` 包装器，除非显式禁用 | + | `kilocode-thinking` | 共享代理流路径上的 Kilo 推理包装器，其中 `kilo/auto` 和不支持代理推理 id 的情况会跳过注入的 thinking | + | `moonshot-thinking` | 基于配置和 `/think` 级别的 Moonshot 二进制原生 thinking 负载映射 | + | `minimax-fast-mode` | 共享流路径上的 MiniMax 快速模式模型重写 | + | `openai-responses-defaults` | 共享原生 OpenAI/Codex Responses 包装器：归属标头、`/fast`/`serviceTier`、文本详细程度、原生 Codex web 搜索、推理兼容负载整形以及 Responses 上下文管理 | + | `openrouter-thinking` | 用于代理路由的 OpenRouter 推理包装器，并集中处理不支持模型/`auto` 的跳过逻辑 | + | `tool-stream-default-on` | 为像 Z.AI 这样的提供商提供默认开启的 `tool_stream` 包装器，除非被显式禁用 | 真实的内置示例： @@ -297,44 +318,58 @@ x-i18n: - `openrouter`：`openrouter-thinking` - `zai`：`tool-stream-default-on` - `openclaw/plugin-sdk/provider-model-shared` 也导出了 replay-family 枚举，以及这些系列所基于的共享辅助函数。常见的公共导出包括： + `openclaw/plugin-sdk/provider-model-shared` 还会导出 replay 系列枚举，以及这些系列所基于的共享辅助方法。常见的公共导出包括： - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` - - 共享重放构建器，例如 `buildOpenAICompatibleReplayPolicy(...)`、`buildAnthropicReplayPolicyForModel(...)`、`buildGoogleGeminiReplayPolicy(...)` 和 `buildHybridAnthropicOrOpenAIReplayPolicy(...)` - - Gemini 重放辅助函数，例如 `sanitizeGoogleGeminiReplayHistory(...)` 和 `resolveTaggedReasoningOutputMode()` - - 端点/模型辅助函数，例如 `resolveProviderEndpoint(...)`、`normalizeProviderId(...)`、`normalizeGooglePreviewModelId(...)` 和 `normalizeNativeXaiModelId(...)` + - 共享 replay 构建器，例如 `buildOpenAICompatibleReplayPolicy(...)`、 + `buildAnthropicReplayPolicyForModel(...)`、 + `buildGoogleGeminiReplayPolicy(...)` 和 + `buildHybridAnthropicOrOpenAIReplayPolicy(...)` + - Gemini replay 辅助方法，例如 `sanitizeGoogleGeminiReplayHistory(...)` + 和 `resolveTaggedReasoningOutputMode()` + - 端点/模型辅助方法，例如 `resolveProviderEndpoint(...)`、 + `normalizeProviderId(...)`、`normalizeGooglePreviewModelId(...)` 和 + `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` 同时公开了系列构建器以及这些系列复用的公共包装辅助函数。常见的公共导出包括： + `openclaw/plugin-sdk/provider-stream` 同时公开系列构建器和这些系列复用的公共包装器辅助方法。常见的公共导出包括： - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` - `composeProviderStreamWrappers(...)` - - 共享的 OpenAI/Codex 包装器，例如 `createOpenAIAttributionHeadersWrapper(...)`、`createOpenAIFastModeWrapper(...)`、`createOpenAIServiceTierWrapper(...)`、`createOpenAIResponsesContextManagementWrapper(...)` 和 `createCodexNativeWebSearchWrapper(...)` - - 共享代理/提供商包装器，例如 `createOpenRouterWrapper(...)`、`createToolStreamWrapper(...)` 和 `createMinimaxFastModeWrapper(...)` + - 共享 OpenAI/Codex 包装器，例如 + `createOpenAIAttributionHeadersWrapper(...)`、 + `createOpenAIFastModeWrapper(...)`、 + `createOpenAIServiceTierWrapper(...)`、 + `createOpenAIResponsesContextManagementWrapper(...)` 和 + `createCodexNativeWebSearchWrapper(...)` + - 共享代理/提供商包装器，例如 `createOpenRouterWrapper(...)`、 + `createToolStreamWrapper(...)` 和 `createMinimaxFastModeWrapper(...)` - 有些流式辅助函数会有意保持为提供商本地实现。当前的内置示例：`@openclaw/anthropic-provider` 从其公共 `api.ts` / `contract-api.ts` 接缝导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及更底层的 Anthropic 包装器构建器。这些辅助函数仍然保持为 Anthropic 专用，因为它们还编码了 Claude OAuth beta 处理和 `context1m` 门控。 + 一些流辅助方法会有意保留在提供商本地。当前的内置示例：`@openclaw/anthropic-provider` 通过其公共 `api.ts` / `contract-api.ts` 接缝导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 Anthropic 包装器构建器。这些辅助方法仍然保持为 Anthropic 专用，因为它们还编码了 Claude OAuth beta 处理和 `context1m` 门控。 - 其他内置提供商也会在行为无法在系列之间清晰共享时，将传输协议专用包装器保留为本地实现。当前示例：内置的 xAI 插件将原生 xAI Responses 整形保留在它自己的 `wrapStreamFn` 中，其中包括 `/fast` 别名重写、默认 `tool_stream`、不受支持的 strict-tool 清理，以及 xAI 专用的 reasoning-payload 移除。 + 其他内置提供商也会在行为无法在系列之间清晰共享时，将传输专用包装器保留在本地。当前示例：内置 xAI 插件将原生 xAI Responses 整形保留在自己的 `wrapStreamFn` 中，包括 `/fast` 别名重写、默认 `tool_stream`、不受支持的严格工具清理，以及 xAI 专用的推理负载移除。 - `openclaw/plugin-sdk/provider-tools` 当前公开了一个共享工具模式系列，以及共享模式/兼容性辅助函数： + `openclaw/plugin-sdk/provider-tools` 当前公开一个共享工具 schema 系列，以及共享 schema/兼容辅助方法： - - `ProviderToolCompatFamily` 记录了当前共享系列清单。 - - `buildProviderToolCompatFamilyHooks("gemini")` 会为需要 Gemini 安全工具模式的提供商接入 Gemini 模式清理和诊断。 - - `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)` 是底层的公共 Gemini 模式辅助函数。 - - `resolveXaiModelCompatPatch()` 返回内置的 xAI 兼容性补丁：`toolSchemaProfile: "xai"`、不受支持的模式关键字、原生 `web_search` 支持，以及 HTML 实体工具调用参数解码。 - - `applyXaiModelCompat(model)` 会在解析出的模型到达运行器之前，将同样的 xAI 兼容性补丁应用到该模型上。 + - `ProviderToolCompatFamily` 记录了当前共享的系列清单。 + - `buildProviderToolCompatFamilyHooks("gemini")` 为需要 Gemini 安全工具 schema 的提供商接入 Gemini schema 清理 + 诊断。 + - `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)` 是底层的公共 Gemini schema 辅助方法。 + - `resolveXaiModelCompatPatch()` 返回内置 xAI 兼容补丁： + `toolSchemaProfile: "xai"`、不受支持的 schema 关键字、原生 + `web_search` 支持，以及 HTML 实体工具调用参数解码。 + - `applyXaiModelCompat(model)` 会在解析后的模型到达运行器之前，对其应用相同的 xAI 兼容补丁。 - 真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 加上 `contributeResolvedModelCompat`，以便让该兼容性元数据由提供商自己维护，而不是在核心中硬编码 xAI 规则。 + 真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 和 `contributeResolvedModelCompat`，从而让这些兼容元数据由提供商自行维护，而不是在核心中硬编码 xAI 规则。 - 同样的包根模式也支撑着其他内置提供商： + 相同的包根模式也支持其他内置提供商： - - `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助函数和 realtime 提供商构建器 - - `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导/配置辅助函数 + - `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助方法和 realtime 提供商构建器 + - `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导/配置辅助方法 - 对于需要在每次推理调用前进行令牌交换的提供商： + 对于需要在每次推理调用之前进行令牌交换的提供商： ```typescript prepareRuntimeAuth: async (ctx) => { @@ -347,8 +382,8 @@ x-i18n: }, ``` - - 对于需要自定义请求头或请求体修改的提供商： + + 对于需要自定义请求标头或请求体修改的提供商： ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -365,8 +400,8 @@ x-i18n: }, ``` - - 对于需要在通用 HTTP 或 WebSocket 传输协议上附加原生请求/会话请求头或元数据的提供商： + + 对于需要在通用 HTTP 或 WebSocket 传输上添加原生请求/会话标头或元数据的提供商： ```typescript resolveTransportTurnState: (ctx) => ({ @@ -387,7 +422,7 @@ x-i18n: ``` - 对于提供用量/计费数据的提供商： + 对于公开用量/计费数据的提供商： ```typescript resolveUsageAuth: async (ctx) => { @@ -402,72 +437,74 @@ x-i18n: - OpenClaw 会按以下顺序调用这些钩子。大多数提供商只会用到 2-3 个： + OpenClaw 会按如下顺序调用钩子。大多数提供商只会用到 2-3 个： | # | 钩子 | 何时使用 | | --- | --- | --- | - | 1 | `catalog` | 模型目录或基础 URL 默认值 | - | 2 | `applyConfigDefaults` | 配置实体化期间由提供商拥有的全局默认值 | - | 3 | `normalizeModelId` | 查找前清理旧版/预览版模型 id 别名 | - | 4 | `normalizeTransport` | 通用模型组装前进行提供商系列的 `api` / `baseUrl` 清理 | + | 1 | `catalog` | 模型目录或 `baseUrl` 默认值 | + | 2 | `applyConfigDefaults` | 配置具体化期间由提供商拥有的全局默认值 | + | 3 | `normalizeModelId` | 查找前清理旧版/预览模型 id 别名 | + | 4 | `normalizeTransport` | 通用模型组装前清理提供商系列的 `api` / `baseUrl` | | 5 | `normalizeConfig` | 规范化 `models.providers.` 配置 | - | 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生分块流式传输用量兼容性重写 | - | 7 | `resolveConfigApiKey` | 由提供商拥有的环境变量标记凭证解析 | - | 8 | `resolveSyntheticAuth` | 本地/自托管或基于配置的合成凭证 | - | 9 | `shouldDeferSyntheticProfileAuth` | 将合成的已存储配置文件占位符优先级降到环境变量/配置凭证之后 | + | 6 | `applyNativeStreamingUsageCompat` | 针对配置提供商的原生流式用量兼容重写 | + | 7 | `resolveConfigApiKey` | 由提供商拥有的环境标记认证解析 | + | 8 | `resolveSyntheticAuth` | 本地/自托管或基于配置的合成认证 | + | 9 | `shouldDeferSyntheticProfileAuth` | 将合成的已存储配置文件占位符降级到环境变量/配置认证之后 | | 10 | `resolveDynamicModel` | 接受任意上游模型 id | - | 11 | `prepareDynamicModel` | 解析前异步获取元数据 | - | 12 | `normalizeResolvedModel` | 运行器之前的传输协议重写 | + | 11 | `prepareDynamicModel` | 解析前的异步元数据获取 | + | 12 | `normalizeResolvedModel` | 运行器之前的传输重写 | 运行时回退说明： - - `normalizeConfig` 会先检查匹配的提供商，然后再检查其他具备钩子能力的提供商插件，直到其中一个真正更改了配置。 - 如果没有任何提供商钩子重写受支持的 Google 系列配置项，内置的 Google 配置规范化器仍会生效。 - - `resolveConfigApiKey` 会在提供商暴露该钩子时使用提供商钩子。内置的 `amazon-bedrock` 路径在这里也有一个内建的 AWS 环境变量标记解析器，即使 Bedrock 运行时凭证本身仍然使用 AWS SDK 默认链。 - | 13 | `contributeResolvedModelCompat` | 为运行在另一种兼容传输协议后的厂商模型提供兼容性标志 | - | 14 | `capabilities` | 旧版静态能力包；仅为兼容性保留 | - | 15 | `normalizeToolSchemas` | 注册前由提供商拥有的工具模式清理 | - | 16 | `inspectToolSchemas` | 由提供商拥有的工具模式诊断 | + - `normalizeConfig` 会先检查匹配的提供商，然后再检查其他支持钩子的提供商插件，直到某个插件实际修改了配置。 + 如果没有任何提供商钩子重写受支持的 Google 系列配置项，内置的 Google 配置规范化仍会应用。 + - `resolveConfigApiKey` 会在暴露该钩子时使用提供商钩子。内置的 + `amazon-bedrock` 路径在这里也有一个内建的 AWS 环境标记解析器，尽管 Bedrock 运行时认证本身仍然使用 AWS SDK 默认链。 + | 13 | `contributeResolvedModelCompat` | 为运行在其他兼容传输之后的厂商模型提供兼容标志 | + | 14 | `capabilities` | 旧版静态能力包；仅用于兼容 | + | 15 | `normalizeToolSchemas` | 注册前由提供商拥有的工具 schema 清理 | + | 16 | `inspectToolSchemas` | 由提供商拥有的工具 schema 诊断 | | 17 | `resolveReasoningOutputMode` | 带标签与原生推理输出契约 | | 18 | `prepareExtraParams` | 默认请求参数 | - | 19 | `createStreamFn` | 完全自定义的 StreamFn 传输协议 | - | 20 | `wrapStreamFn` | 常规流路径上的自定义请求头/请求体包装器 | - | 21 | `resolveTransportTurnState` | 原生逐轮请求头/元数据 | - | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话请求头/冷却时间 | - | 23 | `formatApiKey` | 自定义运行时令牌格式 | + | 19 | `createStreamFn` | 完全自定义的 `StreamFn` 传输 | + | 20 | `wrapStreamFn` | 常规流路径上的自定义标头/请求体包装器 | + | 21 | `resolveTransportTurnState` | 原生逐回合标头/元数据 | + | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话标头/冷却时间 | + | 23 | `formatApiKey` | 自定义运行时令牌形态 | | 24 | `refreshOAuth` | 自定义 OAuth 刷新 | - | 25 | `buildAuthDoctorHint` | 凭证修复指导 | - | 26 | `matchesContextOverflowError` | 由提供商拥有的上下文溢出检测 | + | 25 | `buildAuthDoctorHint` | 认证修复指导 | + | 26 | `matchesContextOverflowError` | 由提供商拥有的溢出检测 | | 27 | `classifyFailoverReason` | 由提供商拥有的限流/过载分类 | - | 28 | `isCacheTtlEligible` | 提示词缓存 TTL 门控 | - | 29 | `buildMissingAuthMessage` | 自定义缺失凭证提示 | - | 30 | `suppressBuiltInModel` | 隐藏过时的上游行 | - | 31 | `augmentModelCatalog` | 合成的前向兼容行 | + | 28 | `isCacheTtlEligible` | 提示缓存 TTL 门控 | + | 29 | `buildMissingAuthMessage` | 自定义缺失认证提示 | + | 30 | `suppressBuiltInModel` | 隐藏过时的上游条目 | + | 31 | `augmentModelCatalog` | 合成的前向兼容条目 | | 32 | `isBinaryThinking` | 二进制 thinking 开/关 | | 33 | `supportsXHighThinking` | `xhigh` 推理支持 | | 34 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略 | | 35 | `isModernModelRef` | live/smoke 模型匹配 | - | 36 | `prepareRuntimeAuth` | 推理前进行令牌交换 | + | 36 | `prepareRuntimeAuth` | 推理前的令牌交换 | | 37 | `resolveUsageAuth` | 自定义用量凭证解析 | | 38 | `fetchUsageSnapshot` | 自定义用量端点 | - | 39 | `createEmbeddingProvider` | 用于 memory/search 的由提供商拥有的嵌入适配器 | - | 40 | `buildReplayPolicy` | 自定义转录重放/压缩策略 | - | 41 | `sanitizeReplayHistory` | 通用清理后的提供商专用重放重写 | - | 42 | `validateReplayTurns` | 嵌入式运行器之前的严格重放轮次校验 | + | 39 | `createEmbeddingProvider` | 用于记忆/搜索的、由提供商拥有的 embedding 适配器 | + | 40 | `buildReplayPolicy` | 自定义转录 replay/压缩策略 | + | 41 | `sanitizeReplayHistory` | 通用清理之后的提供商专用 replay 重写 | + | 42 | `validateReplayTurns` | 嵌入式运行器之前的严格 replay 回合校验 | | 43 | `onModelSelected` | 选择模型后的回调（例如遥测） | - 提示词调优说明： + 提示调优说明： - - `resolveSystemPromptContribution` 允许提供商为某个模型系列注入具备缓存感知能力的 system prompt 指导。对于属于某一个提供商/模型系列且应保留稳定/动态缓存拆分的行为，优先使用它，而不是 `before_prompt_build`。 + - `resolveSystemPromptContribution` 允许提供商为某个模型系列注入具备缓存感知能力的系统提示指导。对于属于单个提供商/模型系列并且应保留稳定/动态缓存拆分的行为，优先使用它而不是 `before_prompt_build`。 - 如需详细说明和真实示例，请参阅 [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture#provider-runtime-hooks)。 + 有关详细说明和真实示例，请参阅 + [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture#provider-runtime-hooks)。 - 提供商插件除了文本推理之外，还可以注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和网页搜索： + 提供商插件除了文本推理之外，还可以注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、web 抓取和 web 搜索： ```typescript register(api) { @@ -550,7 +587,7 @@ x-i18n: api.registerWebFetchProvider({ id: "acme-ai-fetch", label: "Acme Fetch", - hint: "通过 Acme 的渲染后端抓取页面。", + hint: "Fetch pages through Acme's rendering backend.", envVars: ["ACME_FETCH_API_KEY"], placeholder: "acme-...", signupUrl: "https://acme.example.com/fetch", @@ -561,7 +598,7 @@ x-i18n: acme.apiKey = value; }, createTool: () => ({ - description: "通过 Acme Fetch 抓取页面。", + description: "Fetch a page through Acme Fetch.", parameters: {}, execute: async (args) => ({ content: [] }), }), @@ -575,11 +612,13 @@ x-i18n: } ``` - OpenClaw 会将其归类为 **hybrid-capability** 插件。这是公司插件（每个厂商一个插件）的推荐模式。请参阅 [内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。 + OpenClaw 会将其归类为 **hybrid-capability** 插件。这是公司插件（每个厂商一个插件）的推荐模式。参见 [内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。 - 对于视频生成，优先使用上面展示的具备模式感知的能力结构：`generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages`、`maxInputVideos` 和 `maxDurationSeconds` 这样的扁平聚合字段，不足以清晰表达转换模式支持或已禁用的模式。 + 对于视频生成，优先使用上面展示的按模式区分的能力结构： + `generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages`、`maxInputVideos` 和 `maxDurationSeconds` 这样的扁平聚合字段，不足以清晰地声明转换模式支持或已禁用模式。 - 音乐生成提供商也应遵循同样的模式：`generate` 用于仅基于提示词的生成，`edit` 用于基于参考图像的生成。像 `maxInputImages`、`supportsLyrics` 和 `supportsFormat` 这样的扁平聚合字段，不足以表达编辑支持；显式的 `generate` / `edit` 块才是预期契约。 + 音乐生成提供商也应遵循相同模式： + `generate` 用于仅基于提示词的生成，`edit` 用于基于参考图像的生成。像 `maxInputImages`、`supportsLyrics` 和 `supportsFormat` 这样的扁平聚合字段，不足以声明编辑支持；显式的 `generate` / `edit` 块才是预期契约。 @@ -620,21 +659,22 @@ x-i18n: ## 发布到 ClawHub -提供商插件的发布方式与其他外部代码插件相同： +提供商插件的发布方式与任何其他外部代码插件相同： ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -这里不要使用旧版仅适用于 skill 的发布别名；插件包应使用 `clawhub package publish`。 +这里不要使用旧版仅限 Skills 的发布别名；插件包应使用 +`clawhub package publish`。 ## 文件结构 ``` /acme-ai/ ├── package.json # openclaw.providers 元数据 -├── openclaw.plugin.json # 包含提供商凭证元数据的清单 +├── openclaw.plugin.json # 带有提供商认证元数据的清单 ├── index.ts # definePluginEntry + registerProvider └── src/ ├── provider.test.ts # 测试 @@ -643,18 +683,18 @@ clawhub package publish your-org/your-plugin ## 目录顺序参考 -`catalog.order` 控制你的目录相对于内置提供商的合并时机： +`catalog.order` 控制你的目录相对于内置提供商在何时合并： | 顺序 | 时机 | 使用场景 | | --------- | ------------- | ----------------------------------------------- | -| `simple` | 第一轮 | 纯 API 密钥提供商 | -| `profile` | 在 simple 之后 | 受凭证配置文件控制的提供商 | +| `simple` | 第一轮 | 普通 API 密钥提供商 | +| `profile` | 在 simple 之后 | 受认证配置文件控制的提供商 | | `paired` | 在 profile 之后 | 合成多个相关条目 | -| `late` | 最后一轮 | 覆盖现有提供商（冲突时胜出） | +| `late` | 最后一轮 | 覆盖现有提供商（冲突时获胜） | ## 后续步骤 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 如果你的插件也提供一个渠道 -- [插件 SDK 运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助函数（TTS、搜索、子智能体） -- [插件 SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考 +- [SDK 运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助方法（TTS、搜索、subagent） +- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考 - [插件内部机制](/zh-CN/plugins/architecture#provider-runtime-hooks) — 钩子细节和内置示例