From 33051cdc100470fcb7232d92848c2c489cb2ed70 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 05:44:00 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/model-providers.md | 274 ++++++++++---------- docs/zh-CN/providers/openai.md | 343 +++++++++++++------------ docs/zh-CN/tools/plugin.md | 224 +++++++--------- 3 files changed, 409 insertions(+), 432 deletions(-) diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index 87fc9ec1f..ccc51ec19 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -1,68 +1,60 @@ --- read_when: - - 你需要一份按提供商划分的模型设置参考 + - 你需要一份按提供商逐一说明的模型设置参考文档 - 你想要模型提供商的示例配置或 CLI 新手引导命令 -summary: 模型提供商概览，包含示例配置和 CLI 流程 +summary: 模型提供商概览，包含示例配置 + CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-04-24T03:38:59Z" + generated_at: "2026-04-24T05:42:12Z" model: gpt-5.4 provider: openai - source_hash: ce2fc2b932ddc5d5b6066b70c4b0090868ad450e193f48d89daee9e65ceb9200 + source_hash: ac9bf48897446576d8bc339b340295691741a589863bb57b379c17a5519bffd7 source_path: concepts/model-providers.md workflow: 15 --- -本页介绍的是 **LLM/模型提供商**（不是 WhatsApp/Telegram 这类聊天渠道）。 -有关模型选择规则，请参阅 [/concepts/models](/zh-CN/concepts/models)。 +此页面介绍的是 **LLM/模型提供商**（不是像 WhatsApp/Telegram 这样的聊天渠道）。 +关于模型选择规则，请参阅 [/concepts/models](/zh-CN/concepts/models)。 ## 快速规则 -- 模型引用使用 `provider/model`（例如：`opencode/claude-opus-4-6`）。 -- 设置后，`agents.defaults.models` 会充当允许列表。 -- CLI 帮助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 -- `models.providers.*.models[].contextWindow` 是原生模型元数据；`contextTokens` 是运行时实际生效的上限。 -- 回退规则、冷却探测和会话覆盖持久化：参见 [Model failover](/zh-CN/concepts/model-failover)。 -- OpenAI 系列路由按前缀区分：`openai/` 在 PI 中使用直接 OpenAI API key 提供商，`openai-codex/` 在 PI 中使用 Codex OAuth，而 `openai/` 加上 `agents.defaults.embeddedHarness.runtime: "codex"` 则使用原生 Codex app-server harness。请参阅 [OpenAI](/zh-CN/providers/openai) - 和 [Codex harness](/zh-CN/plugins/codex-harness)。 -- GPT-5.5 当前可通过订阅/OAuth 路由使用： - 在 PI 中使用 `openai-codex/gpt-5.5`，或配合 Codex app-server - harness 使用 `openai/gpt-5.5`。一旦 - OpenAI 在公共 API 上启用 GPT-5.5，就支持 `openai/gpt-5.5` 的直接 API key 路由； - 在那之前，对于 `OPENAI_API_KEY` 设置，请使用已支持 API 的模型， - 例如 `openai/gpt-5.4`。 +- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。 +- 设置后，`agents.defaults.models` 会作为允许列表。 +- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 +- `models.providers.*.models[].contextWindow` 是模型原生元数据；`contextTokens` 是运行时生效的上限。 +- 回退规则、冷却探测和会话覆盖持久化：参阅 [模型故障切换](/zh-CN/concepts/model-failover)。 +- OpenAI 系列路由按前缀区分：`openai/` 在 PI 中使用直连 OpenAI API 密钥提供商，`openai-codex/` 在 PI 中使用 Codex OAuth，而 `openai/` 配合 `agents.defaults.embeddedHarness.runtime: "codex"` 则使用原生 Codex 应用服务器 harness。参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。 +- 插件自动启用也遵循同样的边界：`openai-codex/` 属于 OpenAI 插件，而 Codex 插件由 `embeddedHarness.runtime: "codex"` 或旧版 `codex/` 引用启用。 +- GPT-5.5 当前可通过订阅 / OAuth 路由使用：在 PI 中使用 `openai-codex/gpt-5.5`，或使用 Codex 应用服务器 harness 时使用 `openai/gpt-5.5`。当 OpenAI 在公开 API 上启用 GPT-5.5 后，才支持 `openai/gpt-5.5` 的直连 API 密钥路由；在此之前，对于 `OPENAI_API_KEY` 设置，请使用已支持 API 的模型，例如 `openai/gpt-5.4`。 ## 插件拥有的提供商行为 -大多数提供商特定逻辑都位于提供商插件中（`registerProvider(...)`），而 OpenClaw 仅保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、thinking/reasoning 配置等。 +大多数提供商特定逻辑都位于提供商插件中（`registerProvider(...)`），而 OpenClaw 负责通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输 / 配置规范化、工具模式清理、故障切换分类、OAuth 刷新、用量报告、思考 / 推理配置等。 -完整的 provider SDK hook 列表和内置插件示例位于 [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，那属于另一个更深层的扩展面。 +提供商 SDK 钩子的完整列表以及内置插件示例，请参阅 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，那属于另一个更深层的扩展接口。 -提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、transcript/工具特性、传输/缓存提示）。它不同于[公开 capability 模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。 +提供商运行时 `capabilities` 是共享的运行器元数据（提供商家族、转录 / 工具怪癖、传输 / 缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。 -## API key 轮换 +## API 密钥轮换 -- 支持为选定提供商进行通用提供商轮换。 -- 通过以下方式配置多个 key： - - `OPENCLAW_LIVE__KEY`（单个实时覆盖，最高优先级） - - `_API_KEYS`（逗号或分号分隔的列表） - - `_API_KEY`（主 key） +- 支持为选定提供商进行通用提供商密钥轮换。 +- 可通过以下方式配置多个密钥： + - `OPENCLAW_LIVE__KEY`（单个实时覆盖，优先级最高） + - `_API_KEYS`（逗号或分号分隔列表） + - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） -- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退选项。 -- key 选择顺序会保留优先级并去重。 -- 只有在收到限流响应时，请求才会使用下一个 key 重试（例如 - `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many -concurrent requests`、`ThrottlingException`、`concurrency limit reached`、 - `workers_ai ... quota limit exceeded`，或周期性的使用限制消息）。 -- 非限流失败会立即失败；不会尝试 key 轮换。 -- 当所有候选 key 都失败时，会返回最后一次尝试的最终错误。 +- 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退项包含在内。 +- 密钥选择顺序会保留优先级并对值去重。 +- 仅在收到限流响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。 +- 非限流失败会立即失败；不会尝试密钥轮换。 +- 当所有候选密钥都失败时，将返回最后一次尝试的最终错误。 ## 内置提供商（pi-ai 目录） -OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** -`models.providers` 配置；只需设置认证信息并选择模型即可。 +OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** +`models.providers` 配置；只需设置认证信息并选择一个模型。 ### OpenAI @@ -70,20 +62,17 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 认证：`OPENAI_API_KEY` - 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖） - 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-mini` -- 一旦 OpenAI 在 API 上公开 GPT-5.5，这里就已为 GPT-5.5 的直接 API 支持做好准备 +- 一旦 OpenAI 在 API 中开放 GPT-5.5，这里就可直接支持 GPT-5.5 API - CLI：`openclaw onboard --auth-choice openai-api-key` -- 默认传输为 `auto`（优先 WebSocket，回退 SSE） -- 可按模型通过 `agents.defaults.models["openai/"].params.transport` 覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`） -- 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先处理 -- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority` -- 当你希望使用显式 tier，而不是共享的 `/fast` 开关时，请使用 `params.serviceTier` -- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、 - `User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量， - 不适用于通用 OpenAI 兼容代理 -- 原生 OpenAI 路由还会保留 Responses `store`、prompt-cache 提示，以及 - OpenAI reasoning 兼容的负载整形；代理路由则不会 -- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录也未公开它 +- 默认传输为 `auto`（优先 WebSocket，回退到 SSE） +- 可通过 `agents.defaults.models["openai/"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） +- OpenAI Responses WebSocket 预热默认启用，通过 `params.openaiWsWarmup` 控制（`true`/`false`） +- 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先级处理 +- `/fast` 和 `params.fastMode` 会将直连 `openai/*` Responses 请求映射为发送到 `api.openai.com` 的 `service_tier=priority` +- 如果你希望使用显式层级而不是共享的 `/fast` 开关，请使用 `params.serviceTier` +- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理 +- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示以及 OpenAI 推理兼容负载整形；代理路由不会 +- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中会被刻意屏蔽，因为实时 OpenAI API 请求会拒绝它，而当前 Codex 目录也未公开它 ```json5 { @@ -98,9 +87,9 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖） - 示例模型：`anthropic/claude-opus-4-6` - CLI：`openclaw onboard --auth-choice apiKey` -- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 认证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 与 `standard_only`） -- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成的受认可方式，除非 Anthropic 发布新政策。 -- Anthropic setup-token 仍作为受支持的 OpenClaw token 路径提供，但 OpenClaw 现在在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。 +- 直连公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`） +- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为该集成已获认可，除非 Anthropic 发布新的政策。 +- Anthropic setup-token 仍然作为受支持的 OpenClaw 令牌路径保留，但 OpenClaw 现在在可用时优先使用 Claude CLI 复用和 `claude -p`。 ```json5 { @@ -113,19 +102,18 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 提供商：`openai-codex` - 认证：OAuth（ChatGPT） - PI 模型引用：`openai-codex/gpt-5.5` -- 原生 Codex app-server harness 引用：`openai/gpt-5.5`，并设置 `agents.defaults.embeddedHarness.runtime: "codex"` +- 原生 Codex 应用服务器 harness 引用：`openai/gpt-5.5`，并设置 `agents.defaults.embeddedHarness.runtime: "codex"` - 旧版模型引用：`codex/gpt-*` +- 插件边界：`openai-codex/*` 会加载 OpenAI 插件；原生 Codex 应用服务器插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选择 - CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex` -- 默认传输为 `auto`（优先 WebSocket，回退 SSE） -- 可按 PI 模型通过 `agents.defaults.models["openai-codex/"].params.transport` 覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）中透传 -- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、 - `User-Agent`）仅附加到发往 - `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理 -- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority` +- 默认传输为 `auto`（优先 WebSocket，回退到 SSE） +- 可通过 `agents.defaults.models["openai-codex/"].params.transport` 按 PI 模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） +- `params.serviceTier` 也会转发到原生 Codex Responses 请求（`chatgpt.com/backend-api`） +- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理 +- 与直连 `openai/*` 共享同样的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority` - `openai-codex/gpt-5.5` 保留原生 `contextWindow = 1000000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 -- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部工具/工作流。 -- 当前 GPT-5.5 访问使用此 OAuth/订阅路由，直到 OpenAI 在公共 API 上启用 GPT-5.5。 +- 策略说明：OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部工具 / 工作流。 +- 当前的 GPT-5.5 访问使用此 OAuth / 订阅路由，直到 OpenAI 在公开 API 中启用 GPT-5.5。 ```json5 { @@ -148,7 +136,7 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** ### 其他订阅式托管选项 - [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射 -- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API key 访问 +- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问 - [GLM Models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点 ### OpenCode @@ -165,23 +153,23 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** } ``` -### Google Gemini（API key） +### Google Gemini（API 密钥） - 提供商：`google` - 认证：`GEMINI_API_KEY` -- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） +- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） - 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview` - 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview` - CLI：`openclaw onboard --auth-choice gemini-api-key` -- 直接 Gemini 运行也接受 `agents.defaults.models["google/"].params.cachedContent` - （或旧版 `cached_content`），以透传提供商原生的 +- 直连 Gemini 运行也接受 `agents.defaults.models["google/"].params.cachedContent` + （或旧版 `cached_content`），用于转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` ### Google Vertex 和 Gemini CLI - 提供商：`google-vertex`、`google-gemini-cli` - 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程 -- 注意：OpenClaw 中的 Gemini CLI OAuth 属于非官方集成。部分用户报告在使用第三方客户端后，其 Google 账户受到了限制。若你选择继续，请查看 Google 条款并使用非关键账户。 +- 注意：OpenClaw 中的 Gemini CLI OAuth 属于非官方集成。一些用户报告称，使用第三方客户端后 Google 账号会受到限制。若你选择继续，请先查看 Google 条款，并使用非关键账号。 - Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 - 先安装 Gemini CLI： - `brew install gemini-cli` @@ -189,8 +177,7 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 启用：`openclaw plugins enable google` - 登录：`openclaw models auth login --provider google-gemini-cli --set-default` - 默认模型：`google-gemini-cli/gemini-3-flash-preview` - - 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将 - token 存储在 Gateway 网关主机上的认证配置文件中。 + - 注意：你**不需要**把 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的认证配置文件中。 - 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。 - Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 @@ -219,11 +206,10 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** - 示例模型：`kilocode/kilo/auto` - CLI：`openclaw onboard --auth-choice kilocode-api-key` - 基础 URL：`https://api.kilo.ai/api/gateway/` -- 静态回退目录附带 `kilocode/kilo/auto`；实时 - `https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时 - 目录。 -- `kilocode/kilo/auto` 背后的具体上游路由由 Kilo Gateway - 管理，而不是在 OpenClaw 中硬编码。 +- 静态回退目录内置 `kilocode/kilo/auto`；实时 + `https://api.kilo.ai/api/gateway/models` 发现机制可以进一步扩展运行时目录。 +- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 决定， + 并非 OpenClaw 内部硬编码。 设置详情请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。 @@ -236,9 +222,9 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** | Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | | GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | | Groq | `groq` | `GROQ_API_KEY` | — | -| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | +| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | | Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | -| Kimi Coding | `kimi` | `KIMI_API_KEY` or `KIMICODE_API_KEY` | `kimi/kimi-code` | +| Kimi Coding | `kimi` | `KIMI_API_KEY` 或 `KIMICODE_API_KEY` | `kimi/kimi-code` | | MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | | Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | | Moonshot AI | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | @@ -254,34 +240,34 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** | xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | | Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | -值得了解的特殊行为： +值得了解的特殊点： -- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其应用归因请求头和 Anthropic `cache_control` 标记。作为代理风格的 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的整形逻辑（`serviceTier`、Responses `store`、prompt-cache 提示、OpenAI reasoning 兼容处理）。基于 Gemini 的引用仅保留代理 Gemini 的 thought-signature 清理。 -- **Kilo Gateway** 中基于 Gemini 的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。 -- **MiniMax** API key 新手引导会写入显式的 M2.7 模型定义，并带有 `input: ["text", "image"]`；在该配置被具体写入之前，内置目录会将聊天引用保持为仅文本。 -- **xAI** 使用 xAI Responses 路径。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为其 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/"].params.tool_stream=false` 禁用。 +- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其应用归因请求头和 Anthropic `cache_control` 标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的整形处理（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容性）。以 Gemini 为后端的引用仅保留代理 Gemini 的 thought-signature 清理。 +- **Kilo Gateway** 以 Gemini 为后端的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。 +- **MiniMax** API 密钥新手引导会写入显式的 M2.7 模型定义，并设置 `input: ["text", "image"]`；在该配置具体化之前，内置目录会将聊天引用保持为纯文本。 +- **xAI** 使用 xAI Responses 路径。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 改写为对应的 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/"].params.tool_stream=false` 禁用。 - **Cerebras** GLM 模型使用 `zai-glm-4.7` / `zai-glm-4.6`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。 -## 通过 `models.providers` 使用提供商（自定义/基础 URL） +## 通过 `models.providers` 配置的提供商（自定义 / 基础 URL） -使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 -与 OpenAI/Anthropic 兼容的代理。 +使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或 +兼容 OpenAI/Anthropic 的代理。 -下面的许多内置提供商插件已经发布了默认目录。 -只有当你想覆盖默认基础 URL、请求头或模型列表时， -才需要显式使用 `models.providers.` 条目。 +下面许多内置提供商插件已经发布了默认目录。 +只有在你想覆盖默认基础 URL、请求头或模型列表时，才需要使用显式的 +`models.providers.` 条目。 ### Moonshot AI（Kimi） -Moonshot 作为内置提供商插件提供。默认情况下应使用内置提供商， -只有当你需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： +Moonshot 作为内置提供商插件提供。默认情况下请使用内置提供商，只有在你 +需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： - 提供商：`moonshot` - 认证：`MOONSHOT_API_KEY` - 示例模型：`moonshot/kimi-k2.6` - CLI：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn` -Kimi K2 模型 id： +Kimi K2 模型 ID： [//]: # "moonshot-kimi-k2-model-refs:start" @@ -329,13 +315,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： } ``` -旧版 `kimi/k2p5` 仍然作为兼容模型 id 被接受。 +旧版 `kimi/k2p5` 仍然作为兼容性模型 ID 被接受。 ### Volcano Engine（Doubao） Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。 -- 提供商：`volcengine`（编码方案：`volcengine-plan`） +- 提供商：`volcengine`（编程：`volcengine-plan`） - 认证：`VOLCANO_ENGINE_API_KEY` - 示例模型：`volcengine-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice volcengine-api-key` @@ -348,13 +334,12 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访 } ``` -新手引导默认使用编码接口，但通用 `volcengine/*` +新手引导默认使用编程接口，但通用 `volcengine/*` 目录也会同时注册。 -在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 +在新手引导 / 配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载， -OpenClaw 会回退到未过滤的目录，而不是显示一个空的 -按提供商过滤选择器。 +OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -364,7 +349,7 @@ OpenClaw 会回退到未过滤的目录，而不是显示一个空的 - `volcengine/glm-4-7-251222`（GLM 4.7） - `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K） -编码模型（`volcengine-plan`）： +编程模型（`volcengine-plan`）： - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` @@ -374,9 +359,9 @@ OpenClaw 会回退到未过滤的目录，而不是显示一个空的 ### BytePlus（国际版） -BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 +BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。 -- 提供商：`byteplus`（编码方案：`byteplus-plan`） +- 提供商：`byteplus`（编程：`byteplus-plan`） - 认证：`BYTEPLUS_API_KEY` - 示例模型：`byteplus-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice byteplus-api-key` @@ -389,13 +374,12 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 } ``` -新手引导默认使用编码接口，但通用 `byteplus/*` +新手引导默认使用编程接口，但通用 `byteplus/*` 目录也会同时注册。 -在新手引导/配置模型选择器中，BytePlus（国际版）认证选项会优先显示 +在新手引导 / 配置模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载， -OpenClaw 会回退到未过滤的目录，而不是显示一个空的 -按提供商过滤选择器。 +OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -403,7 +387,7 @@ OpenClaw 会回退到未过滤的目录，而不是显示一个空的 - `byteplus/kimi-k2-5-260127`（Kimi K2.5） - `byteplus/glm-4-7-251222`（GLM 4.7） -编码模型（`byteplus-plan`）： +编程模型（`byteplus-plan`）： - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` @@ -413,7 +397,7 @@ OpenClaw 会回退到未过滤的目录，而不是显示一个空的 ### Synthetic -Synthetic 通过 `synthetic` 提供商提供与 Anthropic 兼容的模型： +Synthetic 通过 `synthetic` 提供商提供兼容 Anthropic 的模型： - 提供商：`synthetic` - 认证：`SYNTHETIC_API_KEY` @@ -441,27 +425,27 @@ Synthetic 通过 `synthetic` 提供商提供与 Anthropic 兼容的模型： ### MiniMax -MiniMax 通过 `models.providers` 进行配置，因为它使用自定义端点： +MiniMax 通过 `models.providers` 配置，因为它使用自定义端点： -- MiniMax OAuth（Global）：`--auth-choice minimax-global-oauth` -- MiniMax OAuth（CN）：`--auth-choice minimax-cn-oauth` -- MiniMax API key（Global）：`--auth-choice minimax-global-api` -- MiniMax API key（CN）：`--auth-choice minimax-cn-api` +- MiniMax OAuth（全球）：`--auth-choice minimax-global-oauth` +- MiniMax OAuth（中国）：`--auth-choice minimax-cn-oauth` +- MiniMax API 密钥（全球）：`--auth-choice minimax-global-api` +- MiniMax API 密钥（中国）：`--auth-choice minimax-cn-api` - 认证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` -有关设置详情、模型选项和配置片段，请参阅 [/providers/minimax](/zh-CN/providers/minimax)。 +设置详情、模型选项和配置片段请参阅 [/providers/minimax](/zh-CN/providers/minimax)。 -在 MiniMax 与 Anthropic 兼容的流式传输路径上，OpenClaw 默认禁用 thinking， -除非你显式设置它；同时 `/fast on` 会将 -`MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 +在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认会禁用 thinking， +除非你显式设置它；而 `/fast on` 会将 +`MiniMax-M2.7` 改写为 `MiniMax-M2.7-highspeed`。 插件拥有的能力拆分： -- 文本/聊天默认仍使用 `minimax/MiniMax-M2.7` -- 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01` -- 图像理解在两种 MiniMax 认证路径上都使用由插件管理的 `MiniMax-VL-01` -- Web 搜索仍使用提供商 id `minimax` +- 文本 / 聊天默认保持在 `minimax/MiniMax-M2.7` +- 图像生成为 `minimax/image-01` 或 `minimax-portal/image-01` +- 图像理解在两个 MiniMax 认证路径上都使用由插件管理的 `MiniMax-VL-01` +- Web 搜索保持使用提供商 id `minimax` ### LM Studio @@ -471,7 +455,7 @@ LM Studio 作为内置提供商插件提供，并使用原生 API： - 认证：`LM_API_TOKEN` - 默认推理基础 URL：`http://localhost:1234/v1` -然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 id）： +然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）： ```json5 { @@ -482,8 +466,8 @@ LM Studio 作为内置提供商插件提供，并使用原生 API： ``` OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` -进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。 -有关设置和故障排除，请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 +进行发现 + 自动加载，默认使用 `/v1/chat/completions` 进行推理。 +设置和故障排除请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 ### Ollama @@ -495,7 +479,7 @@ Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API： - 安装：[https://ollama.com/download](https://ollama.com/download) ```bash -# 安装 Ollama，然后拉取一个模型： +# Install Ollama, then pull a model: ollama pull llama3.3 ``` @@ -509,26 +493,26 @@ ollama pull llama3.3 当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama， -并且内置提供商插件会将 Ollama 直接添加到 -`openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式及自定义配置， +而内置提供商插件会将 Ollama 直接添加到 +`openclaw onboard` 和模型选择器中。关于新手引导、云端 / 本地模式和自定义配置， 请参阅 [/providers/ollama](/zh-CN/providers/ollama)。 ### vLLM -vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容 +vLLM 作为内置提供商插件提供，用于本地 / 自托管的 OpenAI 兼容 服务器： - 提供商：`vllm` - 认证：可选（取决于你的服务器） - 默认基础 URL：`http://127.0.0.1:8000/v1` -要在本地启用自动发现（如果你的服务器不强制认证，任意值都可以）： +要在本地启用自动发现（如果你的服务器不强制认证，任意值都可用）： ```bash export VLLM_API_KEY="vllm-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 id）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： ```json5 { @@ -549,14 +533,14 @@ OpenAI 兼容服务器： - 认证：可选（取决于你的服务器） - 默认基础 URL：`http://127.0.0.1:30000/v1` -要在本地启用自动发现（如果你的服务器不 -强制认证，任意值都可以）： +要在本地启用自动发现（如果你的服务器未强制 +认证，任意值都可用）： ```bash export SGLANG_API_KEY="sglang-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 id）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： ```json5 { @@ -570,7 +554,7 @@ export SGLANG_API_KEY="sglang-local" ### 本地代理（LM Studio、vLLM、LiteLLM 等） -示例（与 OpenAI 兼容）： +示例（兼容 OpenAI）： ```json5 { @@ -612,14 +596,14 @@ export SGLANG_API_KEY="sglang-local" - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- 建议：设置与你的代理/模型限制相匹配的显式值。 -- 对于非原生端点上的 `api: "openai-completions"`（任何非空的 `baseUrl`，且其 host 不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 -- 代理风格的 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求 - 整形逻辑：没有 `service_tier`，没有 Responses `store`，没有 prompt-cache 提示，没有 - OpenAI reasoning 兼容负载整形，也没有隐藏的 OpenClaw 归因 +- 建议：设置与你的代理 / 模型限制相匹配的显式值。 +- 对于非原生端点上的 `api: "openai-completions"`（即任意非空 `baseUrl` 且其主机不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 +- 代理式 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求 + 整形：没有 `service_tier`、没有 Responses `store`、没有提示缓存提示、没有 + OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归因 请求头。 -- 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认 OpenAI 行为（即解析到 `api.openai.com`）。 -- 出于安全考虑，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。 +- 如果 `baseUrl` 为空 / 省略，OpenClaw 会保留默认的 OpenAI 行为（即解析到 `api.openai.com`）。 +- 为安全起见，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。 ## CLI 示例 @@ -633,7 +617,7 @@ openclaw models list ## 相关内容 -- [Models](/zh-CN/concepts/models) —— 模型配置与别名 -- [Model Failover](/zh-CN/concepts/model-failover) —— 回退链与重试行为 -- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) —— 模型配置键 -- [Providers](/zh-CN/providers) —— 按提供商划分的设置指南 +- [Models](/zh-CN/concepts/models) — 模型配置和别名 +- [模型故障切换](/zh-CN/concepts/model-failover) — 回退链和重试行为 +- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键 +- [Providers](/zh-CN/providers) — 按提供商分类的设置指南 diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index 2315c0da6..4c8cc1793 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -1,34 +1,40 @@ --- read_when: - 你想在 OpenClaw 中使用 OpenAI 模型 - - 你希望使用 Codex 订阅认证，而不是 API 密钥 + - 你想使用 Codex 订阅认证，而不是 API 密钥 - 你需要更严格的 GPT-5 智能体执行行为 -summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI +summary: 在 OpenClaw 中使用 API 密钥或 Codex 订阅来接入 OpenAI title: OpenAI x-i18n: - generated_at: "2026-04-24T02:36:59Z" + generated_at: "2026-04-24T05:42:15Z" model: gpt-5.4 provider: openai - source_hash: 8337990d0de692b32746b05ab344695fc5a54ab3855993ac7795fabf38d4d19d + source_hash: 3d533338fa15d866bb69584706162ce099bb4a1edc9851183fb5442730ebdd9b source_path: providers/openai.md workflow: 15 --- -OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列接入方式。模型前缀决定所使用的接入方式： +OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列接入路径。模型前缀决定所使用的路径： -- **API 密钥** — 通过按量计费直接访问 OpenAI Platform（`openai/*` 模型） -- **通过 PI 的 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型） +- **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型） +- **通过 PI 的 Codex 订阅** — 使用 ChatGPT/Codex 登录，并通过订阅获得访问权限（`openai-codex/*` 模型） - **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，外加 `agents.defaults.embeddedHarness.runtime: "codex"`） -OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用基于订阅的 OAuth。 +OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用基于订阅的 OAuth。 -GPT-5.5 目前可通过 OpenClaw 中基于订阅 / OAuth 的接入方式使用： -使用 PI runner 时为 -`openai-codex/gpt-5.5`，使用 -Codex app-server harness 时为 `openai/gpt-5.5`。 -`openai/gpt-5.5` 的直接 API 密钥访问会在 OpenAI 在公共 API 上启用 GPT-5.5 后得到支持；在此之前，请在 -`OPENAI_API_KEY` 配置中使用已支持 API 的模型，例如 `openai/gpt-5.4`。 +GPT-5.5 当前可通过订阅/OAuth 路径在 OpenClaw 中使用： +`openai-codex/gpt-5.5` 配合 PI runner，或 `openai/gpt-5.5` 配合 +Codex app-server harness。`openai/gpt-5.5` 的直接 API 密钥访问 +会在 OpenAI 为公共 API 启用 GPT-5.5 后受支持；在此之前，请为 +`OPENAI_API_KEY` 配置使用支持 API 的模型，例如 `openai/gpt-5.4`。 + + + +启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会启用内置的 +Codex app-server 插件。只有当你显式选择原生 Codex harness，即设置 +`embeddedHarness.runtime: "codex"`，或使用旧版 `codex/*` 模型引用时， +OpenClaw 才会启用该插件。 ## OpenClaw 功能覆盖范围 @@ -36,57 +42,59 @@ Codex app-server harness 时为 `openai/gpt-5.5`。 | OpenAI 能力 | OpenClaw 表面 | 状态 | | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ | | 聊天 / Responses | `openai/` 模型提供商 | 是 | -| Codex 订阅模型 | 带 `openai-codex` OAuth 的 `openai-codex/` | 是 | -| Codex app-server harness | 带 `embeddedHarness.runtime: codex` 的 `openai/` | 是 | -| 服务端 web 搜索 | 原生 OpenAI Responses 工具 | 是，启用 web 搜索且未固定提供商时 | +| Codex 订阅模型 | 使用 `openai-codex` OAuth 的 `openai-codex/` | 是 | +| Codex app-server harness | 使用 `embeddedHarness.runtime: codex` 的 `openai/` | 是 | +| 服务端 web 搜索 | 原生 OpenAI Responses 工具 | 是，当启用 web 搜索且未固定提供商时 | | 图像 | `image_generate` | 是 | | 视频 | `video_generate` | 是 | | 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 | | 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 | -| 流式语音转文本 | 语音通话 `streaming.provider: "openai"` | 是 | -| 实时语音 | 语音通话 `realtime.provider: "openai"` / 控制 UI Talk | 是 | -| Embeddings | memory embedding provider | 是 | +| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 | +| 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 | +| Embeddings | memory embedding 提供商 | 是 | ## 入门指南 -选择你偏好的认证方式，并按照设置步骤操作。 +选择你偏好的认证方式，并按照设置步骤进行操作。 - **最适合：** 直接 API 访问和按量计费。 + **最适合：** 直接访问 API，并按使用量计费。 - 在 [OpenAI Platform 仪表板](https://platform.openai.com/api-keys) 中创建或复制一个 API 密钥。 + 在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 中创建或复制 API 密钥。 ```bash openclaw onboard --auth-choice openai-api-key ``` - 或者直接传入密钥： + 或直接传入密钥： ```bash openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` - ### 接入方式摘要 + ### 路径摘要 - | Model ref | 接入方式 | 认证 | + | Model ref | 路径 | 认证 | |-----------|-------|------| | `openai/gpt-5.4` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | | `openai/gpt-5.4-mini` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | - | `openai/gpt-5.5` | 未来当 OpenAI 在 API 上启用 GPT-5.5 后可直接通过 API 使用 | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | 一旦 OpenAI 在 API 中启用 GPT-5.5 后的未来直接 API 路径 | `OPENAI_API_KEY` | - 除非你明确强制使用 Codex app-server harness，否则 `openai/*` 就是直接的 OpenAI API 密钥接入方式。GPT-5.5 本身目前仅支持订阅 / OAuth；如需通过默认 PI runner 使用 Codex OAuth，请使用 `openai-codex/*`。 + `openai/*` 默认是直接 OpenAI API 密钥路径，除非你显式强制使用 + Codex app-server harness。GPT-5.5 本身当前仅支持订阅/OAuth； + 如需通过默认 PI runner 使用 Codex OAuth，请使用 `openai-codex/*`。 ### 配置示例 @@ -105,7 +113,7 @@ Codex app-server harness 时为 `openai/gpt-5.5`。 - **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要使用 ChatGPT 登录。 + **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。 @@ -119,7 +127,7 @@ Codex app-server harness 时为 `openai/gpt-5.5`。 openclaw models auth login --provider openai-codex ``` - 对于无头环境或不适合回调的环境，可添加 `--device-code`，以使用 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调： + 对于无头环境或不适合回调的设置，可添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调： ```bash openclaw models auth login --provider openai-codex --device-code @@ -130,22 +138,24 @@ Codex app-server harness 时为 `openai/gpt-5.5`。 openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` - ### 接入方式摘要 + ### 路径摘要 - | Model ref | 接入方式 | 认证 | + | Model ref | 路径 | 认证 | |-----------|-------|------| | `openai-codex/gpt-5.5` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 | | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | Codex app-server 认证 | - 对于认证 / 配置文件命令，请继续使用 `openai-codex` 提供商 id。`openai-codex/*` 模型前缀同时也是用于 Codex OAuth 的显式 PI 路径。 + 对于认证/配置文件命令，请继续使用 `openai-codex` provider id。 + `openai-codex/*` 模型前缀也是 Codex OAuth 通过 PI 的显式路径。 + 它不会选择或自动启用内置的 Codex app-server harness。 ### 配置示例 @@ -157,26 +167,28 @@ Codex app-server harness 时为 `openai/gpt-5.5`。 ``` - 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录——OpenClaw 会在自己的智能体认证存储中管理生成的凭证。 + 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录——OpenClaw 会在自己的智能体认证存储中管理生成的凭证。 ### 状态指示器 - 聊天中的 `/status` 会显示当前 - 会话正在使用哪个 embedded harness。默认的 PI harness 显示为 `Runner: pi (embedded)`，不会额外添加单独的标记。选择内置的 Codex app-server harness 时，`/status` 会在 `Fast` 后追加非 PI harness id，例如 - `Fast · codex`。现有会话会保留其记录的 harness id，因此如果你在更改 `embeddedHarness` 后希望 `/status` 反映新的 PI / Codex 选择，请使用 + 聊天中的 `/status` 会显示当前会话正在使用哪个嵌入式 harness。 + 默认的 PI harness 显示为 `Runner: pi (embedded)`，不会额外添加单独标记。 + 当选中内置 Codex app-server harness 时，`/status` 会在 `Fast` 后附加非 PI 的 harness id，例如 + `Fast · codex`。现有会话会保留其已记录的 harness id，因此如果你在更改 + `embeddedHarness` 后希望 `/status` 反映新的 PI/Codex 选择，请使用 `/new` 或 `/reset`。 ### 上下文窗口上限 - OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。 + OpenClaw 将模型元数据与运行时上下文上限视为两个独立的值。 对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`： - 原生 `contextWindow`：`1000000` - 默认运行时 `contextTokens` 上限：`272000` - 较小的默认上限在实践中通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它： + 在实践中，这个更小的默认上限通常具有更好的延迟和质量特性。你可以用 `contextTokens` 覆盖它： ```json5 { @@ -191,7 +203,7 @@ Codex app-server harness 时为 `openai/gpt-5.5`。 ``` - 使用 `contextWindow` 声明模型原生元数据。使用 `contextTokens` 限制运行时上下文预算。 + 使用 `contextWindow` 来声明模型原生元数据。使用 `contextTokens` 来限制运行时上下文预算。 @@ -200,18 +212,18 @@ Codex app-server harness 时为 `openai/gpt-5.5`。 ## 图像生成 内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。 -它同时支持基于 OpenAI API 密钥的图像生成和基于 Codex OAuth 的图像生成， -两者都使用同一个 `openai/gpt-image-2` 模型引用。 +它同时支持通过 OpenAI API 密钥进行图像生成，以及通过 Codex OAuth +使用同一个 `openai/gpt-image-2` 模型引用进行图像生成。 | 能力 | OpenAI API 密钥 | Codex OAuth | | ------------------------- | ---------------------------------- | ------------------------------------ | | Model ref | `openai/gpt-image-2` | `openai/gpt-image-2` | | 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 | | 传输 | OpenAI Images API | Codex Responses 后端 | -| 每次请求的最大图像数量 | 4 | 4 | -| 编辑模式 | 已启用（最多 5 张参考图） | 已启用（最多 5 张参考图） | -| 尺寸覆盖 | 支持，包括 2K / 4K 尺寸 | 支持，包括 2K / 4K 尺寸 | -| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全时映射到受支持的尺寸 | +| 每次请求最大图像数 | 4 | 4 | +| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） | +| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 | +| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射到受支持尺寸 | ```json5 { @@ -224,31 +236,33 @@ Codex app-server harness 时为 `openai/gpt-5.5`。 ``` -有关共享工具参数、提供商选择和故障切换行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。 +有关共享工具参数、提供商选择和故障切换行为，请参见 [Image Generation](/zh-CN/tools/image-generation)。 -`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。 +`gpt-image-2` 是 OpenAI 文本生成图像和图像编辑的默认模型。 +`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流 +应使用 `openai/gpt-image-2`。 -对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。配置了 -`openai-codex` OAuth 配置文件后，OpenClaw 会解析该已存储的 OAuth -访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会为该请求静默回退到 API 密钥。 -当你希望改用直接 OpenAI Images API -路径时，请为 `models.providers.openai` 显式配置 API 密钥、 -自定义 base URL 或 Azure endpoint。 -如果该自定义图像端点位于受信任的 LAN / 私有地址上，还需设置 -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非显式选择启用此项， -否则 OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图像端点。 +对于 Codex OAuth 安装，请保持使用相同的 `openai/gpt-image-2` 引用。 +当已配置 `openai-codex` OAuth 配置文件时，OpenClaw 会解析该已存储的 OAuth +访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 +`OPENAI_API_KEY`，也不会为该请求静默回退到 API 密钥。 +当你希望改用直接 OpenAI Images API 路径时，请使用 API 密钥、 +自定义 base URL 或 Azure endpoint 显式配置 `models.providers.openai`。 +如果该自定义图像端点位于受信任的 LAN/私有地址上，还需要设置 +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若未显式启用此项， +OpenClaw 会继续阻止私有/内部的 OpenAI 兼容图像端点。 生成： ``` -/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 +/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精致的发布海报" size=3840x2160 count=1 ``` 编辑： ``` -/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 +/tool image_generate model=openai/gpt-image-2 prompt="保留物体形状，将材质改为半透明玻璃" image=/path/to/reference.png size=1024x1536 ``` ## 视频生成 @@ -258,8 +272,8 @@ Codex app-server harness 时为 `openai/gpt-5.5`。 | 能力 | 值 | | ---------------- | --------------------------------------------------------------------------------- | | 默认模型 | `openai/sora-2` | -| 模式 | 文生视频、图生视频、单视频编辑 | -| 参考输入 | 1 张图片或 1 个视频 | +| 模式 | 文本生成视频、图像生成视频、单视频编辑 | +| 参考输入 | 1 张图像或 1 个视频 | | 尺寸覆盖 | 支持 | | 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 | @@ -274,20 +288,20 @@ Codex app-server harness 时为 `openai/gpt-5.5`。 ``` -有关共享工具参数、提供商选择和故障切换行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。 +有关共享工具参数、提供商选择和故障切换行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。 ## GPT-5 提示词贡献 -OpenClaw 会为跨提供商的 GPT-5 系列运行添加一个共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.4`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会接收相同的覆盖层。较旧的 GPT-4.x 模型则不会。 +OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.4`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会收到相同的叠加层。较旧的 GPT-4.x 模型则不会。 -内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 heartbeat 覆盖层，因此，即使 Codex 接管了 harness 提示词的其余部分，强制通过 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.x` 会话仍会保留相同的后续执行和主动 heartbeat 指导。 +内置的原生 Codex harness 通过 Codex app-server developer instructions 使用相同的 GPT-5 行为和心跳叠加层，因此，即使 Codex 接管了其余的 harness 提示词，强制通过 `embeddedHarness.runtime: "codex"` 运行的 `openai/gpt-5.x` 会话仍会保留相同的持续跟进和主动心跳指导。 -GPT-5 提示词贡献添加了一个带标记的行为契约，涵盖 persona 持续性、执行安全、工具纪律、输出形态、完成检查和验证。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。GPT-5 指导会始终对匹配的模型启用。友好交互风格层是单独的，并且可配置。 +这个 GPT-5 贡献增加了一个带标签的行为约定，用于规范 persona 持续性、执行安全、工具纪律、输出形态、完成检查和验证。特定于渠道的回复行为和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好的交互风格层则是独立的，并且可配置。 | 值 | 效果 | | ---------------------- | ------------------------------------------- | -| `"friendly"`（默认） | 启用友好交互风格层 | +| `"friendly"`（默认） | 启用友好的交互风格层 | | `"on"` | `"friendly"` 的别名 | | `"off"` | 仅禁用友好风格层 | @@ -313,14 +327,14 @@ GPT-5 提示词贡献添加了一个带标记的行为契约，涵盖 persona -这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 +在运行时，这些值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 -旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退项被读取，前提是未设置共享的 `agents.defaults.promptOverlays.gpt5.personality`。 +当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 配置时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。 -## 语音和语音识别 +## 语音与语音识别 @@ -329,14 +343,14 @@ GPT-5 提示词贡献添加了一个带标记的行为契约，涵盖 persona | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | - | 音色 | `messages.tts.providers.openai.voice` | `coral` | - | 速度 | `messages.tts.providers.openai.speed` | （未设置） | - | 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅适用于 `gpt-4o-mini-tts`） | - | 格式 | `messages.tts.providers.openai.responseFormat` | 语音笔记为 `opus`，文件为 `mp3` | + | 声音 | `messages.tts.providers.openai.voice` | `coral` | + | 语速 | `messages.tts.providers.openai.speed` | （未设置） | + | 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） | + | 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` | | API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` | | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | - 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用音色：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 + 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用声音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 ```json5 { @@ -351,7 +365,7 @@ GPT-5 提示词贡献添加了一个带标记的行为契约，涵盖 persona ``` - 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 base URL，而不会影响聊天 API 端点。 + 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 base URL，而不会影响聊天 API endpoint。 @@ -361,13 +375,13 @@ GPT-5 提示词贡献添加了一个带标记的行为契约，涵盖 persona OpenClaw 的媒体理解转录表面注册了批量语音转文本功能。 - 默认模型：`gpt-4o-transcribe` - - 端点：OpenAI REST `/v1/audio/transcriptions` + - Endpoint：OpenAI REST `/v1/audio/transcriptions` - 输入路径：multipart 音频文件上传 - 在 OpenClaw 中，只要入站音频转录使用 - `tools.media.audio`，就可得到支持，包括 Discord 语音频道片段和渠道 + `tools.media.audio`，就支持该功能，包括 Discord 语音频道片段和渠道 音频附件 - 要强制将 OpenAI 用于入站音频转录： + 要强制对入站音频转录使用 OpenAI： ```json5 { @@ -387,39 +401,39 @@ GPT-5 提示词贡献添加了一个带标记的行为契约，涵盖 persona } ``` - 当共享音频媒体配置或按次调用的转录请求提供了语言和提示信息时， - 这些提示会被转发给 OpenAI。 + 当共享音频媒体配置或单次转录请求提供了语言和提示信息时， + OpenClaw 会将它们转发给 OpenAI。 - 内置的 `openai` 插件为语音通话插件注册了实时转录功能。 + 内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | | 语言 | `...openai.language` | （未设置） | - | 提示 | `...openai.prompt` | （未设置） | - | 静默时长 | `...openai.silenceDurationMs` | `800` | + | 提示词 | `...openai.prompt` | （未设置） | + | 静音时长 | `...openai.silenceDurationMs` | `800` | | VAD 阈值 | `...openai.vadThreshold` | `0.5` | | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | - 使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频格式。这个流式提供商用于语音通话的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。 + 使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。 - 内置的 `openai` 插件为语音通话插件注册了实时语音功能。 + 内置的 `openai` 插件为 Voice Call 插件注册了实时语音功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | - | 音色 | `...openai.voice` | `alloy` | + | 声音 | `...openai.voice` | `alloy` | | Temperature | `...openai.temperature` | `0.8` | | VAD 阈值 | `...openai.vadThreshold` | `0.5` | - | 静默时长 | `...openai.silenceDurationMs` | `500` | + | 静音时长 | `...openai.silenceDurationMs` | `500` | | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | @@ -429,28 +443,28 @@ GPT-5 提示词贡献添加了一个带标记的行为契约，涵盖 persona -## Azure OpenAI 端点 +## Azure OpenAI endpoint -内置的 `openai` 提供商可通过覆盖 base URL，将图像生成请求指向 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 中的 Azure 主机名，并自动切换到 Azure 的请求格式。 +内置的 `openai` 提供商可以通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 中的 Azure 主机名，并自动切换到 Azure 的请求格式。 实时语音使用单独的配置路径 （`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`）， -不受 `models.providers.openai.baseUrl` 影响。其 Azure 设置请参阅 [语音和语音识别](#voice-and-speech) 下 **实时语音** -折叠项。 +不受 `models.providers.openai.baseUrl` 影响。其 Azure 设置请参见 +[语音与语音识别](#voice-and-speech) 下 **实时语音** 折叠面板。 在以下情况下使用 Azure OpenAI： -- 你已经有 Azure OpenAI 订阅、配额或企业协议 +- 你已经拥有 Azure OpenAI 订阅、配额或企业协议 - 你需要 Azure 提供的区域数据驻留或合规控制 -- 你希望将流量保留在现有 Azure 租户内 +- 你希望将流量保留在现有的 Azure tenancy 内部 ### 配置 对于通过内置 `openai` 提供商进行的 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 -Azure OpenAI 密钥（不是 OpenAI Platform 密钥）： +Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： ```json5 { @@ -465,7 +479,7 @@ Azure OpenAI 密钥（不是 OpenAI Platform 密钥）： } ``` -OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成接入方式： +OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成路径： - `*.openai.azure.com` - `*.services.ai.azure.com` @@ -473,23 +487,24 @@ OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成接入方式 对于发送到已识别 Azure 主机的图像生成请求，OpenClaw 会： -- 发送 `api-key` 请求头，而不是 `Authorization: Bearer` -- 使用按 deployment 限定的路径（`/openai/deployments/{deployment}/...`） -- 为每个请求追加 `?api-version=...` +- 发送 `api-key` header，而不是 `Authorization: Bearer` +- 使用部署作用域路径（`/openai/deployments/{deployment}/...`） +- 为每个请求附加 `?api-version=...` -其他 base URL（公共 OpenAI、兼容 OpenAI 的代理）会继续使用标准的 +其他 base URL（公共 OpenAI、OpenAI 兼容代理）则继续使用标准的 OpenAI 图像请求格式。 -`openai` 提供商图像生成路径的 Azure 路由要求 +`openai` 提供商图像生成路径的 Azure 路由功能需要 OpenClaw 2026.4.22 或更高版本。更早的版本会将任何自定义 -`openai.baseUrl` 都视为公共 OpenAI 端点，因此在 Azure -图像 deployment 上会失败。 +`openai.baseUrl` 都视为公共 OpenAI endpoint，并在对接 Azure +图像部署时失败。 ### API 版本 -设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本： +设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的 +Azure 预览版或正式版版本： ```bash export AZURE_OPENAI_API_VERSION="2024-12-01-preview" @@ -497,60 +512,64 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" 如果未设置该变量，默认值为 `2024-12-01-preview`。 -### 模型名称就是 deployment 名称 +### 模型名称就是部署名称 -Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure deployment 名称**，而不是公共 OpenAI 模型 id。 +Azure OpenAI 将模型绑定到部署。对于通过内置 `openai` 提供商路由的 +Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure portal 中配置的 +**Azure 部署名称**，而不是公共 OpenAI 模型 id。 -如果你创建了一个名为 `gpt-image-2-prod`、用于提供 `gpt-image-2` 的 deployment： +如果你创建了一个名为 `gpt-image-2-prod` 的部署，用于提供 `gpt-image-2`： ``` -/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 +/tool image_generate model=openai/gpt-image-2-prod prompt="一张简洁的海报" size=1024x1024 count=1 ``` -同样的 deployment 名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。 +同样的部署名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。 ### 区域可用性 Azure 图像生成目前仅在部分区域可用 （例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、 -`uaenorth`）。在创建 deployment 之前，请先查看 Microsoft 的最新区域列表，并确认你的区域提供了对应的具体模型。 +`uaenorth`）。在创建部署之前，请先查看 Microsoft 当前的区域列表， +并确认你的区域提供所需的具体模型。 ### 参数差异 -Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。 -Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如 -`gpt-image-2` 上的某些 `background` 值），或者仅在特定模型版本上提供它们。这些差异来自 Azure 和底层模型，而不是 -OpenClaw。如果 Azure 请求因验证错误而失败，请在 -Azure 门户中检查你的具体 deployment 和 API 版本所支持的参数集。 +Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。 +Azure 可能会拒绝公共 OpenAI 允许的选项（例如在 `gpt-image-2` 上的某些 +`background` 值），或者仅在特定模型版本上提供这些选项。 +这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请检查 Azure portal 中你的具体部署和 API 版本所支持的参数集。 Azure OpenAI 使用原生传输和兼容行为，但不会接收 -OpenClaw 的隐藏 attribution 请求头——请参阅 [高级配置](#advanced-configuration) 下 **原生与兼容 OpenAI 的接入方式** -折叠项。 +OpenClaw 的隐藏 attribution headers——请参见 +[高级配置](#advanced-configuration) 下 **原生与 OpenAI 兼容路径** +折叠面板。 -对于 Azure 上的聊天或 Responses 流量（不止图像生成），请使用 -新手引导流程或专用的 Azure provider 配置——仅设置 `openai.baseUrl` -并不会自动采用 Azure 的 API / 认证格式。还存在一个单独的 -`azure-openai-responses/*` 提供商；请参阅下方的“服务端压缩”折叠项。 +对于 Azure 上的聊天或 Responses 流量（图像生成之外），请使用 +新手引导流程或专用的 Azure 提供商配置——仅设置 `openai.baseUrl` +并不会自动采用 Azure 的 API/认证格式。另有一个独立的 +`azure-openai-responses/*` 提供商；请参见下方的 +服务端压缩折叠面板。 ## 高级配置 - 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都默认采用 WebSocket 优先、SSE 回退（`"auto"`）策略。 + OpenClaw 对 `openai/*` 和 `openai-codex/*` 都默认使用 WebSocket 优先并在失败时回退到 SSE（`"auto"`）。 在 `"auto"` 模式下，OpenClaw 会： - 在回退到 SSE 之前，重试一次早期 WebSocket 失败 - - 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE - - 为重试和重连附加稳定的会话与轮次标识请求头 - - 在不同传输变体间标准化用量计数器（`input_tokens` / `prompt_tokens`） + - 在发生失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE + - 为重试和重连附加稳定的会话和轮次身份 header + - 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`） | 值 | 行为 | |-------|----------| | `"auto"`（默认） | WebSocket 优先，SSE 回退 | - | `"sse"` | 仅强制使用 SSE | - | `"websocket"` | 仅强制使用 WebSocket | + | `"sse"` | 强制仅使用 SSE | + | `"websocket"` | 强制仅使用 WebSocket | ```json5 { @@ -570,13 +589,13 @@ OpenClaw 的隐藏 attribution 请求头——请参阅 [高级配置](#advanced ``` 相关 OpenAI 文档： - - [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) - - [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses) + - [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket) + - [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses) - 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 默认启用 WebSocket 预热，以减少首轮延迟。 + OpenClaw 默认对 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低首轮延迟。 ```json5 // 禁用预热 @@ -595,13 +614,13 @@ OpenClaw 的隐藏 attribution 请求头——请参阅 [高级配置](#advanced - - OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了共享的快速模式开关： + + OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了共享的 Fast 模式开关： - - **聊天 / UI：** `/fast status|on|off` + - **聊天/UI：** `/fast status|on|off` - **配置：** `agents.defaults.models["/"].params.fastMode` - 启用后，OpenClaw 会将快速模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。 + 启用后，OpenClaw 会将 Fast 模式映射为 OpenAI 优先级处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，Fast 模式不会重写 `reasoning` 或 `text.verbosity`。 ```json5 { @@ -616,13 +635,13 @@ OpenClaw 的隐藏 attribution 请求头——请参阅 [高级配置](#advanced ``` - 会话级覆盖优先于配置。在 Sessions UI 中清除会话级覆盖后，该会话会恢复为配置的默认值。 + 会话覆盖的优先级高于配置。在 Sessions UI 中清除会话覆盖后，会话会恢复为配置中的默认值。 - - OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型设置它： + + OpenAI 的 API 通过 `service_tier` 提供优先级处理能力。你可以在 OpenClaw 中按模型进行设置： ```json5 { @@ -639,23 +658,23 @@ OpenClaw 的隐藏 attribution 请求头——请参阅 [高级配置](#advanced 支持的值：`auto`、`default`、`flex`、`priority`。 - `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。 + `serviceTier` 仅会被转发到原生 OpenAI endpoint（`api.openai.com`）和原生 Codex endpoint（`chatgpt.com/backend-api`）。如果你通过代理路由其中任一提供商，OpenClaw 会保持 `service_tier` 不变。 - 对于直接 OpenAI Responses 模型（位于 `api.openai.com` 的 `openai/*`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩： + 对于直接的 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩： - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` - - 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`） + - 默认 `compact_threshold`：`contextWindow` 的 70%（若不可用则为 `80000`） - 这适用于内置的 Pi harness 路径，也适用于嵌入式运行所使用的 OpenAI provider hook。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。 + 这适用于内置的 Pi harness 路径，也适用于嵌入式运行所使用的 OpenAI 提供商 hook。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。 - 对于 Azure OpenAI Responses 等兼容端点，这会很有用： + 适用于 Azure OpenAI Responses 这类兼容 endpoint： ```json5 { @@ -707,13 +726,13 @@ OpenClaw 的隐藏 attribution 请求头——请参阅 [高级配置](#advanced - `responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。 + `responsesServerCompaction` 仅控制 `context_management` 的注入。直接的 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。 - - 对于运行在 `openai/*` 上的 GPT-5 系列，OpenClaw 可以使用更严格的嵌入式执行契约： + + 对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行约定： ```json5 { @@ -726,32 +745,32 @@ OpenClaw 的隐藏 attribution 请求头——请参阅 [高级配置](#advanced ``` 使用 `strict-agentic` 时，OpenClaw 会： - - 当存在可用工具动作时，不再将仅规划的轮次视为成功推进 - - 使用“立即执行”的引导重试该轮次 - - 对于实质性工作自动启用 `update_plan` - - 如果模型持续规划而不执行，则显式显示阻塞状态 + - 当有可用工具操作时，不再将“仅规划”的轮次视为成功进展 + - 通过立即执行引导来重试该轮次 + - 对于实质性工作，自动启用 `update_plan` + - 如果模型持续只规划而不执行，则明确显示阻塞状态 - 仅作用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧模型家族仍保持默认行为。 + 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧模型系列保持默认行为。 - - OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的兼容 OpenAI 的 `/v1` 代理： + + OpenClaw 会将直接 OpenAI、Codex 和 Azure OpenAI endpoint 与通用的 OpenAI 兼容 `/v1` 代理区分对待： - **原生接入方式**（`openai/*`、Azure OpenAI）： + **原生路径**（`openai/*`、Azure OpenAI）： - 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }` - - 对拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用推理设置 + - 对于拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用的 reasoning - 默认将工具 schema 设为严格模式 - - 仅在已验证的原生主机上附加隐藏 attribution 请求头 - - 保留 OpenAI 专用的请求格式处理（`service_tier`、`store`、reasoning 兼容性、prompt-cache 提示） + - 仅在已验证的原生主机上附加隐藏 attribution headers + - 保留 OpenAI 专有的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示） - **代理 / 兼容接入方式：** + **代理/兼容路径：** - 使用更宽松的兼容行为 - - 不强制使用严格工具 schema 或原生专用请求头 + - 不强制严格工具 schema，也不附加仅限原生的 headers - Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏 attribution 请求头。 + Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏的 attribution headers。 @@ -763,10 +782,10 @@ OpenClaw 的隐藏 attribution 请求头——请参阅 [高级配置](#advanced 选择提供商、模型引用和故障切换行为。 - 共享图像工具参数和提供商选择。 + 共享的图像工具参数和提供商选择。 - 共享视频工具参数和提供商选择。 + 共享的视频工具参数和提供商选择。 认证细节和凭证复用规则。 diff --git a/docs/zh-CN/tools/plugin.md b/docs/zh-CN/tools/plugin.md index fbd2d1264..b73847cf1 100644 --- a/docs/zh-CN/tools/plugin.md +++ b/docs/zh-CN/tools/plugin.md @@ -1,29 +1,26 @@ --- read_when: - - 安装或配置插件时 ауаҩы to=final code omitted - - 了解插件发现和加载规则时��� to=final code omitted - - 使用兼容 Codex/Claude 的插件包时 + - 安装或配置插件 + - 了解插件发现和加载规则 + - 使用与 Codex/Claude 兼容的插件包 sidebarTitle: Install and Configure summary: 安装、配置和管理 OpenClaw 插件 title: 插件 x-i18n: - generated_at: "2026-04-23T21:09:43Z" + generated_at: "2026-04-24T05:42:16Z" model: gpt-5.4 provider: openai - source_hash: a2cf5cb6146ae5e52a32201ee08c03211dbea2313b884c696307abc56d3f9cbf + source_hash: a93114ddb312552f4c321b6e318f3e19810cf5059dd0c68fde93da41936566b8 source_path: tools/plugin.md workflow: 15 --- -插件会为 OpenClaw 扩展新能力：渠道、模型提供商、 -工具、Skills、语音、实时转写、实时语音、 -媒体理解、图像生成、视频生成、网页抓取、Web -搜索等等。有些插件是**核心**插件（随 OpenClaw 一起发布），另一些则是**外部**插件（由社区发布到 npm）。 +插件通过新增能力来扩展 OpenClaw：渠道、模型提供商、工具、skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起发布），另一些是**外部**插件（由社区发布到 npm）。 ## 快速开始 - + ```bash openclaw plugins list ``` @@ -31,10 +28,10 @@ x-i18n: ```bash - # From npm + # 从 npm openclaw plugins install @openclaw/voice-call - # From a local directory or archive + # 从本地目录或归档文件 openclaw plugins install ./my-plugin openclaw plugins install ./my-plugin.tgz ``` @@ -46,12 +43,12 @@ x-i18n: openclaw gateway restart ``` - 然后在配置文件中的 `plugins.entries.\.config` 下进行配置。 + 然后在你的配置文件中，通过 `plugins.entries.\.config` 进行配置。 -如果你更喜欢聊天原生控制，请启用 `commands.plugins: true` 并使用： +如果你更喜欢原生聊天方式控制，请启用 `commands.plugins: true` 并使用： ```text /plugin install clawhub:@openclaw/voice-call @@ -59,20 +56,11 @@ x-i18n: /plugin enable voice-call ``` -安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 -`clawhub:`，或裸包规范（优先 ClawHub，然后回退 npm）。 +安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:`，或裸包规范（优先 ClawHub，然后回退到 npm）。 -如果配置无效，安装通常会以关闭失败方式终止，并提示你运行 -`openclaw doctor --fix`。唯一的恢复例外是一个窄范围的内置插件 -重装路径，适用于选择加入 -`openclaw.install.allowInvalidConfigRecovery` 的插件。 +如果配置无效，安装通常会以失败并阻止继续的方式结束，并引导你使用 `openclaw doctor --fix`。唯一的恢复例外是一个较窄的内置插件重装路径，适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。 -打包版 OpenClaw 不会急切地安装每个内置插件的 -运行时依赖树。当某个 OpenClaw 自有内置插件因 -插件配置、旧版渠道配置或默认启用的 manifest 而处于活动状态时，启动 -只会在导入该插件前修复它声明的运行时依赖。 -外部插件和自定义加载路径仍然必须通过 -`openclaw plugins install` 安装。 +打包后的 OpenClaw 安装不会急切安装每个内置插件的运行时依赖树。当一个由 OpenClaw 拥有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于活动状态时，启动过程只会在导入该插件之前修复该插件声明的运行时依赖。外部插件和自定义加载路径仍然必须通过 `openclaw plugins install` 安装。 ## 插件类型 @@ -80,19 +68,19 @@ OpenClaw 可识别两种插件格式： | 格式 | 工作方式 | 示例 | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | -| **Native** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 | -| **Bundle** | 兼容 Codex/Claude/Cursor 的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | +| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 软件包 | +| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | -这两类都会出现在 `openclaw plugins list` 中。有关 bundle 细节，请参见 [Plugin Bundles](/zh-CN/plugins/bundles)。 +两者都会显示在 `openclaw plugins list` 中。有关 bundle 的详细信息，请参阅 [Plugin Bundles](/zh-CN/plugins/bundles)。 -如果你在编写 Native 插件，请从 [Building Plugins](/zh-CN/plugins/building-plugins) +如果你要编写原生插件，请从 [Building Plugins](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。 ## 官方插件 ### 可安装（npm） -| 插件 | 包名 | 文档 | +| 插件 | 软件包 | 文档 | | --------------- | ---------------------- | ------------------------------------ | | Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) | | Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) | @@ -105,29 +93,29 @@ OpenClaw 可识别两种插件格式： - `anthropic`、`byteplus`、`cloudflare-ai-gateway`、`github-copilot`、`google`、 - `huggingface`、`kilocode`、`kimi-coding`、`minimax`、`mistral`、`qwen`、 - `moonshot`、`nvidia`、`openai`、`opencode`、`opencode-go`、`openrouter`、 - `qianfan`、`synthetic`、`together`、`venice`、 - `vercel-ai-gateway`、`volcengine`、`xiaomi`、`zai` + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, + `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, + `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, + `qianfan`, `synthetic`, `together`, `venice`, + `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - - - `memory-core` —— 内置记忆搜索（默认通过 `plugins.slots.memory` 启用） - - `memory-lancedb` —— 按需安装的长期记忆，支持自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`） + + - `memory-core` — 内置内存搜索（通过 `plugins.slots.memory` 默认启用） + - `memory-lancedb` — 按需安装的长期记忆，带自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`） - `elevenlabs`、`microsoft` + `elevenlabs`, `microsoft` - - `browser` —— 用于浏览器工具、`openclaw browser` CLI、`browser.request` gateway 方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；在替换它之前请先禁用） - - `copilot-proxy` —— VS Code Copilot Proxy bridge（默认禁用） + - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用） + - `copilot-proxy` — VS Code Copilot Proxy 桥接器（默认禁用） -想找第三方插件？请参见 [Community Plugins](/zh-CN/plugins/community)。 +在找第三方插件？请参阅 [Community Plugins](/zh-CN/plugins/community)。 ## 配置 @@ -148,25 +136,23 @@ OpenClaw 可识别两种插件格式： | 字段 | 描述 | | ---------------- | --------------------------------------------------------- | | `enabled` | 主开关（默认：`true`） | -| `allow` | 插件 allowlist（可选） | -| `deny` | 插件 denylist（可选；deny 优先） | +| `allow` | 插件允许列表（可选） | +| `deny` | 插件拒绝列表（可选；拒绝优先） | | `load.paths` | 额外的插件文件/目录 | -| `slots` | 排他性 slot 选择器（例如 `memory`、`contextEngine`） | -| `entries.\` | 按插件划分的开关 + 配置 | +| `slots` | 独占插槽选择器（例如 `memory`、`contextEngine`） | +| `entries.\` | 每个插件的开关 + 配置 | -配置更改**需要重启 gateway**。如果 Gateway 网关以启用配置 -监视 + 进程内重启的方式运行（默认的 `openclaw gateway` 路径），该 -重启通常会在配置写入后不久自动执行。 +配置更改**需要重启 Gateway 网关**。如果 Gateway 网关正在以启用配置监听 + 进程内重启的方式运行（默认的 `openclaw gateway` 路径），那么在配置写入完成后，通常会自动在稍后执行重启。 - - - **Disabled**：插件存在，但启用规则将其关闭。配置会被保留。 - - **Missing**：配置引用了某个插件 id，但发现过程中未找到它。 - - **Invalid**：插件存在，但其配置与声明的 schema 不匹配。 + + - **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。 + - **缺失**：配置引用了某个插件 id，但设备发现未找到该插件。 + - **无效**：插件存在，但其配置不匹配声明的 schema。 -## 发现与优先级 +## 发现顺序和优先级 -OpenClaw 按以下顺序扫描插件（先匹配者获胜）： +OpenClaw 按以下顺序扫描插件（先匹配者优先）： @@ -182,46 +168,51 @@ OpenClaw 按以下顺序扫描插件（先匹配者获胜）： - 随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。 - 其他则需要显式启用。 + 随 OpenClaw 一起发布。很多默认启用（模型提供商、语音）。 + 其他插件则需要显式启用。 ### 启用规则 - `plugins.enabled: false` 会禁用所有插件 -- `plugins.deny` 永远优先于 allow +- `plugins.deny` 始终优先于 allow - `plugins.entries.\.enabled: false` 会禁用该插件 - 来自工作区的插件**默认禁用**（必须显式启用） - 内置插件遵循内建的默认启用集合，除非被覆盖 -- 排他性 slot 可以强制启用该 slot 所选的插件 +- 独占插槽可以强制启用该插槽中被选中的插件 +- 某些内置的可选加入插件会在配置命名某个由插件拥有的表面时自动启用，例如提供商模型引用、渠道配置或 harness 运行时 +- OpenAI 系列的 Codex 路由保持独立的插件边界： + `openai-codex/*` 属于 OpenAI 插件，而内置的 Codex + app-server 插件则通过 `embeddedHarness.runtime: "codex"` 或旧版 + `codex/*` 模型引用来选择 -## 插件 slots（排他性类别） +## 插件 slots（独占类别） -某些类别是排他的（同一时间只能有一个处于活动状态）： +某些类别是独占的（一次只能有一个处于活动状态）： ```json5 { plugins: { slots: { - memory: "memory-core", // or "none" to disable - contextEngine: "legacy", // or a plugin id + memory: "memory-core", // 或使用 "none" 进行禁用 + contextEngine: "legacy", // 或某个插件 id }, }, } ``` -| Slot | 它控制什么 | 默认值 | +| 插槽 | 控制内容 | 默认值 | | --------------- | --------------------- | ------------------- | -| `memory` | 活动的记忆插件 | `memory-core` | -| `contextEngine` | 活动的上下文引擎 | `legacy`（内建） | +| `memory` | 活动中的 Memory 插件 | `memory-core` | +| `contextEngine` | 活动中的上下文引擎 | `legacy`（内置） | ## CLI 参考 ```bash openclaw plugins list # 紧凑清单 -openclaw plugins list --enabled # 仅显示已加载插件 -openclaw plugins list --verbose # 按插件显示详细行 +openclaw plugins list --enabled # 仅显示已加载的插件 +openclaw plugins list --verbose # 每个插件的详细信息行 openclaw plugins list --json # 机器可读清单 openclaw plugins inspect # 深度详情 openclaw plugins inspect --json # 机器可读 @@ -233,15 +224,15 @@ openclaw plugins install # 安装（优先 ClawHub，然后 np openclaw plugins install clawhub: # 仅从 ClawHub 安装 openclaw plugins install --force # 覆盖现有安装 openclaw plugins install # 从本地路径安装 -openclaw plugins install -l # link（不复制），用于开发 +openclaw plugins install -l # 链接（不复制），用于开发 openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # 记录精确解析后的 npm spec +openclaw plugins install --pin # 记录精确解析后的 npm 规范 openclaw plugins install --dangerously-force-unsafe-install openclaw plugins update # 更新单个插件 openclaw plugins update --dangerously-force-unsafe-install openclaw plugins update --all # 更新全部 -openclaw plugins uninstall # 移除配置/安装记录 +openclaw plugins uninstall # 删除配置/安装记录 openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -250,54 +241,39 @@ openclaw plugins enable openclaw plugins disable ``` -内置插件随 OpenClaw 一起发布。许多默认启用（例如 -内置模型提供商、内置语音提供商，以及内置浏览器 -插件）。其他内置插件仍然需要 `openclaw plugins enable `。 +内置插件随 OpenClaw 一起发布。很多默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）。其他内置插件仍然需要 `openclaw plugins enable `。 -`--force` 会原地覆盖现有已安装插件或 hook pack。对于已跟踪 npm -插件的日常升级，请使用 `openclaw plugins update `。 -它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是 -复制到受管理的安装目标中。 +`--force` 会原地覆盖现有已安装插件或 hook 包。对于受跟踪的 npm +插件的常规升级，请使用 `openclaw plugins update `。它不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到受管理的安装目标。 -当已经设置了 `plugins.allow` 时，`openclaw plugins install` 会在 -启用插件前先将该插件 id 添加到该 allowlist 中，因此重启后即可立即加载。 +当 `plugins.allow` 已经设置时，`openclaw plugins install` 会在启用插件之前先将已安装的插件 id 添加到该允许列表中，因此插件在重启后可以立即加载。 -`openclaw plugins update ` 适用于已跟踪安装。传入 -带 dist-tag 或精确版本的 npm 包规范时，会将包名重新解析回已跟踪插件记录，并为将来的更新记录新规范。 -传入不带版本的包名时，会将精确固定的安装切回 -注册表的默认发布线。如果已安装的 npm 插件已经与 -解析出的版本和记录的工件身份匹配，OpenClaw 会跳过此次更新，而不会下载、 -重新安装或重写配置。 +`openclaw plugins update ` 适用于受跟踪的安装。传入带 dist-tag 或精确版本的 npm 包规范时，会将该包名解析回受跟踪的插件记录，并记录新的规范以供后续更新。传入不带版本的包名时，会将一个精确固定版本的安装移回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的工件标识，OpenClaw 会跳过更新，而不会下载、重新安装或重写配置。 -`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 -marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 规范。 +`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 规范。 -`--dangerously-force-unsafe-install` 是针对内置危险代码扫描器误报的 break-glass 覆盖。它允许插件安装 -和插件更新在内置 `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 下载/安装流程。 -兼容的 bundle 会参与同样的插件 list/inspect/enable/disable -流程。当前运行时支持 bundle Skills、Claude command-skills、 -Claude `settings.json` 默认值、Claude `.lsp.json` 以及 manifest 声明的 +兼容的 bundle 会参与同一套插件 list/inspect/enable/disable +流程。当前运行时支持包括 bundle skills、Claude command-skills、 +Claude `settings.json` 默认值、Claude `.lsp.json` 以及清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。 -`openclaw plugins inspect ` 还会为基于 bundle 的插件报告检测到的 bundle 能力，以及受支持或不受支持的 MCP 和 LSP 服务器条目。 +`openclaw plugins inspect ` 还会报告已检测到的 bundle 能力，以及针对由 bundle 支持的插件所支持或不受支持的 MCP 和 LSP 服务器条目。 -Marketplace 来源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 +Marketplace 来源可以是来自 +`~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 -URL，或 git URL。对于远程 marketplaces，插件条目必须保持在 -克隆后的 marketplace 仓库内部，并且只能使用相对路径来源。 +URL，或 git URL。对于远程 marketplace，插件条目必须保留在已克隆的 marketplace 仓库内部，并且只能使用相对路径来源。 -完整细节请参见 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。 +有关完整详情，请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。 ## 插件 API 概览 -Native 插件会导出一个入口对象，暴露 `register(api)`。较旧的 +原生插件会导出一个入口对象，并公开 `register(api)`。较旧的 插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。 @@ -319,18 +295,16 @@ export default definePluginEntry({ }); ``` -OpenClaw 会加载该入口对象，并在插件 -激活期间调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`， -但内置插件和新的外部插件应将 `register` 视为公共契约。 +OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。加载器仍会对旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。 -常见注册方法： +常见的注册方法： -| 方法 | 它注册的内容 | +| 方法 | 注册内容 | | --------------------------------------- | --------------------------- | | `registerProvider` | 模型提供商（LLM） | | `registerChannel` | 聊天渠道 | | `registerTool` | 智能体工具 | -| `registerHook` / `on(...)` | 生命周期 hooks | +| `registerHook` / `on(...)` | 生命周期 hook | | `registerSpeechProvider` | 文本转语音 / STT | | `registerRealtimeTranscriptionProvider` | 流式 STT | | `registerRealtimeVoiceProvider` | 双工实时语音 | @@ -339,28 +313,28 @@ OpenClaw 会加载该入口对象，并在插件 | `registerMusicGenerationProvider` | 音乐生成 | | `registerVideoGenerationProvider` | 视频生成 | | `registerWebFetchProvider` | 网页抓取 / 抓取提供商 | -| `registerWebSearchProvider` | Web 搜索 | +| `registerWebSearchProvider` | 网页搜索 | | `registerHttpRoute` | HTTP 端点 | | `registerCommand` / `registerCli` | CLI 命令 | | `registerContextEngine` | 上下文引擎 | | `registerService` | 后台服务 | -带类型生命周期 hooks 的 hook 护栏行为： +带类型生命周期 hook 的 guard 行为： -- `before_tool_call`：`{ block: true }` 是终止性的；会跳过更低优先级处理器。 -- `before_tool_call`：`{ block: false }` 是无操作，不会清除更早的 block。 -- `before_install`：`{ block: true }` 是终止性的；会跳过更低优先级处理器。 -- `before_install`：`{ block: false }` 是无操作，不会清除更早的 block。 -- `message_sending`：`{ cancel: true }` 是终止性的；会跳过更低优先级处理器。 -- `message_sending`：`{ cancel: false }` 是无操作，不会清除更早的 cancel。 +- `before_tool_call`：`{ block: true }` 是终止性的；较低优先级的处理程序会被跳过。 +- `before_tool_call`：`{ block: false }` 是空操作，不会清除更早的 block。 +- `before_install`：`{ block: true }` 是终止性的；较低优先级的处理程序会被跳过。 +- `before_install`：`{ block: false }` 是空操作，不会清除更早的 block。 +- `message_sending`：`{ cancel: true }` 是终止性的；较低优先级的处理程序会被跳过。 +- `message_sending`：`{ cancel: false }` 是空操作，不会清除更早的 cancel。 -完整的类型化 hook 行为请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。 +有关完整的类型化 hook 行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。 ## 相关内容 -- [Building Plugins](/zh-CN/plugins/building-plugins) —— 创建你自己的插件 -- [Plugin Bundles](/zh-CN/plugins/bundles) —— Codex/Claude/Cursor bundle 兼容性 -- [Plugin Manifest](/zh-CN/plugins/manifest) —— manifest schema -- [Registering Tools](/zh-CN/plugins/building-plugins#registering-agent-tools) —— 在插件中添加智能体工具 -- [Plugin Internals](/zh-CN/plugins/architecture) —— 能力模型和加载流水线 -- [Community Plugins](/zh-CN/plugins/community) —— 第三方列表 +- [Building Plugins](/zh-CN/plugins/building-plugins) — 创建你自己的插件 +- [Plugin Bundles](/zh-CN/plugins/bundles) — Codex/Claude/Cursor bundle 兼容性 +- [Plugin Manifest](/zh-CN/plugins/manifest) — 清单 schema +- [Registering Tools](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具 +- [Plugin Internals](/zh-CN/plugins/architecture) — 能力模型和加载流水线 +- [Community Plugins](/zh-CN/plugins/community) — 第三方列表