From 37e78300fcd9a19e3ff82b09daf7da28989b9309 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 13 Apr 2026 07:26:19 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/model-providers.md | 322 +++++++++++++----------- docs/zh-CN/gateway/local-models.md | 80 +++--- docs/zh-CN/providers/index.md | 27 +- docs/zh-CN/providers/lmstudio.md | 163 ++++++++++++ docs/zh-CN/reference/api-usage-costs.md | 188 +++++++------- 5 files changed, 474 insertions(+), 306 deletions(-) create mode 100644 docs/zh-CN/providers/lmstudio.md diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index 15e09e2bc..901f97481 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -1,14 +1,14 @@ --- read_when: - - 你需要一份按提供商分别说明的模型设置参考。 + - 你需要一份按提供商分类的模型设置参考。 - 你想要模型提供商的示例配置或 CLI 新手引导命令。 -summary: 模型提供商概览，附带示例配置 + CLI 流程 +summary: 模型提供商概览，包含示例配置 + CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-04-10T21:05:12Z" + generated_at: "2026-04-13T07:24:20Z" model: gpt-5.4 provider: openai - source_hash: 910ea7895e74c03910757d9d3e02825754b779b204eca7275b28422647ed0151 + source_hash: 66ba688c4b4366eec07667571e835d4cfeee684896e2ffae11d601b5fa0a4b98 source_path: concepts/model-providers.md workflow: 15 --- @@ -16,116 +16,116 @@ x-i18n: # 模型提供商 本页介绍 **LLM/模型提供商**（不是像 WhatsApp/Telegram 这样的聊天渠道）。 -有关模型选择规则，请参见 [/concepts/models](/zh-CN/concepts/models)。 +关于模型选择规则，参见 [/concepts/models](/zh-CN/concepts/models)。 ## 快速规则 -- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。 +- 模型引用使用 `provider/model`（例如：`opencode/claude-opus-4-6`）。 - 如果你设置了 `agents.defaults.models`，它就会成为允许列表。 -- CLI 帮助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 -- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover) 中。 +- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 +- 运行时回退规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover) 中。 - `models.providers.*.models[].contextWindow` 是原生模型元数据；`models.providers.*.models[].contextTokens` 是实际运行时上限。 - 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前将该输出合并到 `models.providers` 中。 -- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样通用的基于环境变量的凭证探测和提供商变体就不需要加载插件运行时。剩余的核心环境变量映射现在仅用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic 的 API 密钥优先新手引导。 +- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样通用的基于环境变量的凭证探测和提供商变体就不需要加载插件运行时。剩余的核心环境变量映射现在仅用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic API 密钥优先的新手引导。 - 提供商插件还可以通过 `normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 和 `onModelSelected` 来管理提供商运行时行为。 -- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录/工具特殊行为、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么内容（文本推理、语音等）。 -- 内置的 `codex` 提供商与内置的 Codex 智能体运行器配套使用。当你需要 Codex 自有的登录、模型发现、原生线程恢复和应用服务器执行时，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍会使用 OpenAI 提供商和正常的 OpenClaw 提供商传输。纯 Codex 部署可以通过 `agents.defaults.embeddedHarness.fallback: "none"` 禁用自动 PI 回退；参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 +- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录/工具怪癖、传输/缓存提示）。它与[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)不同，后者描述的是插件注册了什么能力（文本推理、语音等）。 +- 内置的 `codex` 提供商与内置 Codex 智能体 harness 配对使用。当你想要使用 Codex 自有登录、模型发现、原生线程恢复和 app-server 执行时，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍然使用 OpenAI 提供商和常规 OpenClaw 提供商传输。仅使用 Codex 的部署可以通过设置 `agents.defaults.embeddedHarness.fallback: "none"` 来禁用自动 PI 回退；参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 -## 插件自主管理的提供商行为 +## 插件自有的提供商行为 -提供商插件现在可以管理大多数提供商特定逻辑，而 OpenClaw 保留通用推理循环。 +现在，提供商插件可以拥有大部分提供商特定逻辑，而 OpenClaw 保持通用推理循环。 -典型分工： +典型划分： -- `auth[].run` / `auth[].runNonInteractive`：提供商管理 `openclaw onboard`、`openclaw models auth` 和无头设置的引导/登录流程 -- `wizard.setup` / `wizard.modelPicker`：提供商管理凭证选择标签、旧版别名、引导允许列表提示，以及新手引导/模型选择器中的设置条目 -- `catalog`：提供商会显示在 `models.providers` 中 +- `auth[].run` / `auth[].runNonInteractive`：提供商负责 `openclaw onboard`、`openclaw models auth` 和无头设置的引导/登录流程 +- `wizard.setup` / `wizard.modelPicker`：提供商负责凭证选择标签、旧版别名、引导允许列表提示，以及新手引导/模型选择器中的设置条目 +- `catalog`：提供商会出现在 `models.providers` 中 - `normalizeModelId`：提供商在查找或规范化之前标准化旧版/预览模型 ID -- `normalizeTransport`：提供商在通用模型组装之前标准化传输家族 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后再检查其他支持该钩子的提供商插件，直到其中一个实际更改了传输 -- `normalizeConfig`：提供商在运行时使用前标准化 `models.providers.` 配置；OpenClaw 会先检查匹配的提供商，然后再检查其他支持该钩子的提供商插件，直到其中一个实际更改了配置。如果没有提供商钩子重写配置，内置的 Google 家族帮助器仍会标准化受支持的 Google 提供商条目。 +- `normalizeTransport`：提供商在通用模型组装之前标准化传输家族的 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后再检查其他具备 hook 能力的提供商插件，直到其中一个实际更改了传输 +- `normalizeConfig`：提供商在运行时使用之前标准化 `models.providers.` 配置；OpenClaw 会先检查匹配的提供商，然后再检查其他具备 hook 能力的提供商插件，直到其中一个实际更改了配置。如果没有提供商 hook 重写配置，内置的 Google 系列辅助逻辑仍会标准化受支持的 Google 提供商条目。 - `applyNativeStreamingUsageCompat`：提供商为配置型提供商应用由端点驱动的原生流式使用量兼容性重写 -- `resolveConfigApiKey`：提供商为配置型提供商解析环境变量标记凭证，而无需强制加载完整运行时凭证。`amazon-bedrock` 在这里也有一个内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是 AWS SDK 默认链。 -- `resolveSyntheticAuth`：提供商可以暴露本地/自托管或其他基于配置的凭证可用性，而无需持久化明文密钥 -- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置文件占位符标记为低于环境变量/配置型凭证的优先级 -- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 ID +- `resolveConfigApiKey`：提供商为配置型提供商解析环境变量标记凭证，而无需强制加载完整运行时凭证。`amazon-bedrock` 在这里也有一个内置 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是 AWS SDK 默认链。 +- `resolveSyntheticAuth`：提供商可以公开本地/自托管或其他基于配置的凭证可用性，而无需持久化明文密钥 +- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成资料占位符标记为低于环境变量/配置型凭证的优先级 +- `resolveDynamicModel`：提供商接受本地静态目录中尚未存在的模型 ID - `prepareDynamicModel`：提供商在重试动态解析之前需要刷新元数据 - `normalizeResolvedModel`：提供商需要重写传输或基础 URL -- `contributeResolvedModelCompat`：即使其供应商模型通过另一种兼容传输到达，提供商仍会为其贡献兼容性标记 -- `capabilities`：提供商发布转录/工具/提供商家族特殊行为 -- `normalizeToolSchemas`：提供商在内置运行器看到工具 schema 之前对其进行清理 -- `inspectToolSchemas`：提供商在标准化后暴露传输特定的 schema 警告 -- `resolveReasoningOutputMode`：提供商选择原生或带标签的推理输出协议 -- `prepareExtraParams`：提供商为每个模型请求参数设置默认值或进行标准化 -- `createStreamFn`：提供商用完全自定义的传输替换正常流式路径 +- `contributeResolvedModelCompat`：提供商为其供应商模型提供兼容性标志，即使这些模型是通过另一个兼容传输接入的 +- `capabilities`：提供商发布转录/工具/提供商家族怪癖 +- `normalizeToolSchemas`：提供商在内置运行器看到工具 schema 之前先对其进行清理 +- `inspectToolSchemas`：提供商在标准化之后暴露传输特定的 schema 警告 +- `resolveReasoningOutputMode`：提供商选择原生还是带标签的推理输出契约 +- `prepareExtraParams`：提供商为每个模型的请求参数设置默认值或进行标准化 +- `createStreamFn`：提供商使用完全自定义的传输替换正常的流式路径 - `wrapStreamFn`：提供商应用请求头/请求体/模型兼容性包装器 -- `resolveTransportTurnState`：提供商为每一轮提供原生传输请求头或元数据 -- `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话请求头或会话冷却策略 -- `createEmbeddingProvider`：当内存嵌入行为更适合放在提供商插件中而不是核心嵌入调度器中时，由提供商负责管理 -- `formatApiKey`：提供商将已存储的凭证配置文件格式化为传输所需的运行时 `apiKey` 字符串 -- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足以满足需求时，由提供商管理 OAuth 刷新 +- `resolveTransportTurnState`：提供商提供每轮的原生传输头或元数据 +- `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话头或会话冷却策略 +- `createEmbeddingProvider`：当记忆嵌入行为应属于提供商插件而不是核心嵌入调度器时，由提供商负责 +- `formatApiKey`：提供商将已存储的凭证资料格式化为传输所期望的运行时 `apiKey` 字符串 +- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足时，由提供商负责 OAuth 刷新 - `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商追加修复指导 -- `matchesContextOverflowError`：提供商识别通用启发式方法可能漏掉的提供商特定上下文窗口溢出错误 -- `classifyFailoverReason`：提供商将原始的提供商特定传输/API 错误映射为回退原因，例如速率限制或过载 +- `matchesContextOverflowError`：提供商识别通用启发式规则可能漏掉的提供商特定上下文窗口溢出错误 +- `classifyFailoverReason`：提供商将提供商特定的原始传输/API 错误映射为回退原因，例如速率限制或过载 - `isCacheTtlEligible`：提供商决定哪些上游模型 ID 支持提示缓存 TTL -- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用凭证存储错误 -- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以在直接解析失败时返回供应商自主管理的错误 -- `augmentModelCatalog`：在发现和配置合并之后，提供商追加合成/最终目录条目 -- `isBinaryThinking`：提供商管理二元开/关思考体验 -- `supportsXHighThinking`：提供商为选定模型启用 `xhigh` -- `resolveDefaultThinkingLevel`：提供商管理某个模型家族的默认 `/think` 策略 -- `applyConfigDefaults`：提供商根据凭证模式、环境或模型家族，在配置具体化期间应用提供商特定的全局默认值 -- `isModernModelRef`：提供商管理 live/smoke 首选模型匹配 +- `buildMissingAuthMessage`：提供商使用提供商特定的恢复提示替换通用凭证存储错误 +- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以为直接解析失败返回供应商自有错误 +- `augmentModelCatalog`：提供商在发现和配置合并之后追加合成/最终目录条目 +- `isBinaryThinking`：提供商负责二元开/关的思考 UX +- `supportsXHighThinking`：提供商将选定模型加入 `xhigh` +- `resolveDefaultThinkingLevel`：提供商负责某个模型家族默认的 `/think` 策略 +- `applyConfigDefaults`：提供商在配置具体化期间，根据凭证模式、环境变量或模型家族应用提供商特定的全局默认值 +- `isModernModelRef`：提供商负责实时/冒烟测试的首选模型匹配 - `prepareRuntimeAuth`：提供商将已配置的凭证转换为短期运行时令牌 -- `resolveUsageAuth`：提供商为 `/usage` 及相关状态/报告界面解析用量/配额凭证 -- `fetchUsageSnapshot`：提供商负责用量端点的抓取/解析，而核心仍负责摘要外壳和格式化 -- `onModelSelected`：提供商在模型选中后运行副作用，例如遥测或提供商自主管理的会话记账 +- `resolveUsageAuth`：提供商为 `/usage` 及相关状态/报告界面解析使用量/配额凭证 +- `fetchUsageSnapshot`：提供商负责使用量端点的获取/解析，而核心仍负责摘要外壳和格式化 +- `onModelSelected`：提供商在模型被选中后执行副作用，例如遥测或提供商自有的会话簿记 当前内置示例： -- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、用量端点抓取、缓存 TTL/提供商家族元数据，以及带凭证感知的全局配置默认值 -- `amazon-bedrock`：由提供商自主管理 Bedrock 特定节流/未就绪错误的上下文溢出匹配和回退原因分类，外加共享的 `anthropic-by-model` 重放家族，用于 Anthropic 流量上仅限 Claude 的重放策略保护 -- `anthropic-vertex`：用于 Anthropic-message 流量上仅限 Claude 的重放策略保护 -- `openrouter`：直通模型 ID、请求包装器、提供商能力提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族进行代理推理注入、路由元数据转发，以及缓存 TTL 策略 -- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude-thinking 转录提示、运行时令牌交换，以及用量端点抓取 -- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输标准化、支持 Codex 的缺失凭证提示、Spark 屏蔽、合成 OpenAI/Codex 目录条目、thinking/live-model 策略、用量令牌别名标准化（`input` / `output` 和 `prompt` / `completion` 家族）、用于原生 OpenAI/Codex 包装器的共享 `openai-responses-defaults` 流家族、提供商家族元数据、为 `gpt-image-1` 内置图像生成提供商注册，以及为 `sora-2` 内置视频生成提供商注册 -- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、引导重放清理、带标签的推理输出模式、现代模型匹配、为 Gemini 图像预览模型内置图像生成提供商注册，以及为 Veo 模型内置视频生成提供商注册；Gemini CLI OAuth 还自主管理凭证配置文件令牌格式化、用量令牌解析和用于用量界面的配额端点抓取 -- `moonshot`：共享传输，由插件自主管理 thinking 负载标准化 -- `kilocode`：共享传输、由插件自主管理请求头、推理负载标准化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略 -- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元 thinking/live-model 策略，以及用量凭证 + 配额抓取；未知的 `glm-5*` ID 会基于内置的 `glm-4.7` 模板合成 -- `xai`：原生 Responses 传输标准化、用于 Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特定工具 schema / 推理负载清理，以及为 `grok-imagine-video` 内置视频生成提供商注册 -- `mistral`：由插件自主管理能力元数据 -- `opencode` 和 `opencode-go`：由插件自主管理能力元数据，外加代理 Gemini thought-signature 清理 -- `alibaba`：由插件自主管理直接 Wan 模型引用的视频生成目录，例如 `alibaba/wan2.6-t2v` -- `byteplus`：由插件自主管理目录，外加为 Seedance 文生视频/图生视频模型内置视频生成提供商注册 -- `fal`：为托管的第三方图像生成 FLUX 图像模型内置图像生成提供商注册，外加为托管的第三方视频模型内置视频生成提供商注册 -- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅由插件自主管理目录 -- `qwen`：文本模型目录由插件自主管理，另外其多模态界面使用共享的媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点和内置 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v` -- `runway`：为原生 Runway 基于任务的模型（如 `gen4.5`）由插件自主管理视频生成提供商注册 -- `minimax`：由插件自主管理目录、为 Hailuo 视频模型内置视频生成提供商注册、为 `image-01` 内置图像生成提供商注册、混合 Anthropic/OpenAI 重放策略选择，以及用量凭证/快照逻辑 -- `together`：由插件自主管理目录，外加为 Wan 视频模型内置视频生成提供商注册 -- `xiaomi`：由插件自主管理目录，外加用量凭证/快照逻辑 +- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、使用量端点获取、缓存 TTL/提供商家族元数据，以及具备凭证感知能力的全局配置默认值 +- `amazon-bedrock`：由提供商自有的上下文溢出匹配，以及针对 Bedrock 特有节流/未就绪错误的回退原因分类，另外还包括共享的 `anthropic-by-model` 重放家族，用于 Anthropic 流量上仅限 Claude 的重放策略保护 +- `anthropic-vertex`：针对 Anthropic-message 流量的仅限 Claude 的重放策略保护 +- `openrouter`：透传模型 ID、请求包装器、提供商能力提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族注入代理推理、路由元数据转发，以及缓存 TTL 策略 +- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude 思考转录提示、运行时令牌交换，以及使用量端点获取 +- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输标准化、具备 Codex 感知能力的缺失凭证提示、Spark 屏蔽、合成 OpenAI/Codex 目录条目、thinking/live-model 策略、使用量令牌别名标准化（`input` / `output` 和 `prompt` / `completion` 家族）、用于原生 OpenAI/Codex 包装器的共享 `openai-responses-defaults` 流家族、提供商家族元数据、为 `gpt-image-1` 注册的内置图像生成提供商，以及为 `sora-2` 注册的内置视频生成提供商 +- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、bootstrap 重放清理、带标签的推理输出模式、现代模型匹配、为 Gemini 图像预览模型注册的内置图像生成提供商，以及为 Veo 模型注册的内置视频生成提供商；Gemini CLI OAuth 还负责凭证资料令牌格式化、使用量令牌解析，以及为使用量界面获取配额端点 +- `moonshot`：共享传输，由插件自有的思考负载标准化 +- `kilocode`：共享传输、由插件自有的请求头、推理负载标准化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略 +- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元思考/live-model 策略，以及使用量凭证 + 配额获取；未知的 `glm-5*` ID 会基于内置的 `glm-4.7` 模板合成 +- `xai`：原生 Responses 传输标准化、针对 Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特有的工具 schema / 推理负载清理，以及为 `grok-imagine-video` 注册的内置视频生成提供商 +- `mistral`：由插件自有的能力元数据 +- `opencode` 和 `opencode-go`：由插件自有的能力元数据，外加代理 Gemini thought-signature 清理 +- `alibaba`：由插件自有的直连 Wan 模型引用视频生成目录，例如 `alibaba/wan2.6-t2v` +- `byteplus`：由插件自有的目录，以及为 Seedance 文生视频/图生视频模型注册的内置视频生成提供商 +- `fal`：为托管第三方图像生成提供商注册的内置图像生成提供商（用于 FLUX 图像模型），以及为托管第三方视频模型注册的内置视频生成提供商 +- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅由插件自有目录 +- `qwen`：文本模型由插件自有目录，另外其多模态界面使用共享的媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点以及内置 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v` +- `runway`：为原生 Runway 基于任务的模型（例如 `gen4.5`）注册的插件自有视频生成提供商 +- `minimax`：由插件自有目录、为 Hailuo 视频模型注册的内置视频生成提供商、为 `image-01` 注册的内置图像生成提供商、混合 Anthropic/OpenAI 重放策略选择，以及使用量凭证/快照逻辑 +- `together`：由插件自有目录，外加为 Wan 视频模型注册的内置视频生成提供商 +- `xiaomi`：由插件自有目录，外加使用量凭证/快照逻辑 -内置的 `openai` 插件现在同时管理这两个提供商 ID：`openai` 和 `openai-codex`。 +内置的 `openai` 插件现在同时拥有这两个提供商 ID：`openai` 和 `openai-codex`。 -以上涵盖了仍适配 OpenClaw 常规传输的提供商。需要完全自定义请求执行器的提供商，则属于另一个更深层的扩展接口。 +以上涵盖了仍然适配 OpenClaw 常规传输的提供商。需要完全自定义请求执行器的提供商则属于另一个更深层的扩展接口。 ## API 密钥轮换 -- 支持为选定提供商进行通用提供商轮换。 +- 对选定提供商支持通用提供商轮换。 - 通过以下方式配置多个密钥： - - `OPENCLAW_LIVE__KEY`（单个 live 覆盖，优先级最高） + - `OPENCLAW_LIVE__KEY`（单个实时覆盖，最高优先级） - `_API_KEYS`（逗号或分号分隔列表） - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） - 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。 -- 密钥选择顺序会保留优先级并去重。 -- 仅在速率限制响应时，请求才会使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 或周期性的用量限制消息）。 +- 密钥选择顺序会保留优先级并去重值。 +- 只有在速率限制响应时，请求才会使用下一个密钥重试（例如 `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 @@ -134,15 +134,15 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖） - 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-pro` - CLI：`openclaw onboard --auth-choice openai-api-key` -- 默认传输为 `auto`（WebSocket 优先，SSE 回退） -- 可通过 `agents.defaults.models["openai/"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） +- 默认传输为 `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` +- OpenAI 优先处理可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 +- `/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 中被刻意屏蔽，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex +- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示以及 OpenAI 推理兼容负载整形；代理路由不会 +- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为实时 OpenAI API 会拒绝它；Spark 被视为仅限 Codex ```json5 { @@ -157,9 +157,9 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 可选轮换：`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 密钥和 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`。 +- 直接公共 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 { @@ -173,14 +173,14 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 凭证：OAuth（ChatGPT） - 示例模型：`openai-codex/gpt-5.4` - CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex` -- 默认传输为 `auto`（WebSocket 优先，SSE 回退） -- 可通过 `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` 覆盖（`"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` - 当 Codex OAuth 目录暴露它时，`openai-codex/gpt-5.3-codex-spark` 仍然可用；是否可用取决于权限 -- `openai-codex/gpt-5.4` 保留原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 -- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这样的外部工具/工作流。 +- `openai-codex/gpt-5.4` 保持原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 +- 策略说明：OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部工具/工作流。 ```json5 { @@ -228,13 +228,13 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 示例模型：`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`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` +- 直接 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` @@ -242,9 +242,9 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 启用：`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 登录流程会将令牌存储在 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`。 + - Gemini CLI JSON 回复从 `response` 解析；使用量会回退到 `stats`，其中 `stats.cached` 会被标准化为 OpenClaw `cacheRead`。 ### Z.AI（GLM） @@ -253,7 +253,7 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 示例模型：`zai/glm-5.1` - CLI：`openclaw onboard --auth-choice zai-api-key` - 别名：`z.ai/*` 和 `z-ai/*` 会被标准化为 `zai/*` - - `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口 + - `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定界面 ### Vercel AI Gateway @@ -268,23 +268,23 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 凭证：`KILOCODE_API_KEY` - 示例模型：`kilocode/kilo/auto` - CLI：`openclaw onboard --auth-choice kilocode-api-key` -- 基础 URL：`https://api.kilo.ai/api/gateway/` +- Base 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` 背后的精确上游路由由 Kilo Gateway 负责，不是 OpenClaw 中硬编码的。 -有关设置详情，请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。 +设置详情参见 [/providers/kilocode](/zh-CN/providers/kilocode)。 ### 其他内置提供商插件 - OpenRouter：`openrouter`（`OPENROUTER_API_KEY`） - 示例模型：`openrouter/auto` -- 只有当请求实际目标为 `openrouter.ai` 时，OpenClaw 才会应用 OpenRouter 文档中说明的应用归因请求头 -- OpenRouter 特定的 Anthropic `cache_control` 标记同样只会应用到已验证的 OpenRouter 路由，而不会应用到任意代理 URL -- OpenRouter 仍然走代理风格的 OpenAI 兼容路径，因此不会转发仅适用于原生 OpenAI 的请求整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容负载） -- 基于 Gemini 的 OpenRouter 引用仅保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和引导重写仍保持关闭 +- 仅当请求实际发送到 `openrouter.ai` 时，OpenClaw 才会应用 OpenRouter 文档中的应用归因请求头 +- OpenRouter 特有的 Anthropic `cache_control` 标记同样仅限于已验证的 OpenRouter 路由，而不是任意代理 URL +- OpenRouter 仍走代理式 OpenAI 兼容路径，因此原生 OpenAI 专属请求整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容负载）不会被转发 +- 基于 Gemini 的 OpenRouter 引用仅保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和 bootstrap 重写保持关闭 - Kilo Gateway：`kilocode`（`KILOCODE_API_KEY`） - 示例模型：`kilocode/kilo/auto` -- 基于 Gemini 的 Kilo 引用会保留相同的代理 Gemini thought-signature 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的提示会跳过代理推理注入 +- 基于 Gemini 的 Kilo 引用保留相同的代理 Gemini thought-signature 清理路径；`kilocode/kilo/auto` 以及其他不支持代理推理的提示会跳过代理推理注入 - MiniMax：`minimax`（API 密钥）和 `minimax-portal`（OAuth） - 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` - 示例模型：`minimax/MiniMax-M2.7` 或 `minimax-portal/MiniMax-M2.7` @@ -315,28 +315,28 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 示例模型：`byteplus-plan/ark-code-latest` - xAI：`xai`（`XAI_API_KEY`） - 原生内置 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` + - `/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` 可禁用它 - Mistral：`mistral`（`MISTRAL_API_KEY`） - 示例模型：`mistral/mistral-large-latest` - CLI：`openclaw onboard --auth-choice mistral-api-key` - Groq：`groq`（`GROQ_API_KEY`） - Cerebras：`cerebras`（`CEREBRAS_API_KEY`） - Cerebras 上的 GLM 模型使用 ID `zai-glm-4.7` 和 `zai-glm-4.6`。 - - OpenAI 兼容基础 URL：`https://api.cerebras.ai/v1`。 + - OpenAI 兼容 Base URL：`https://api.cerebras.ai/v1`。 - GitHub Copilot：`github-copilot`（`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`） - Hugging Face Inference 示例模型：`huggingface/deepseek-ai/DeepSeek-R1`；CLI：`openclaw onboard --auth-choice huggingface-api-key`。参见 [Hugging Face（Inference）](/zh-CN/providers/huggingface)。 -## 通过 `models.providers` 配置的提供商（自定义/基础 URL） +## 通过 `models.providers` 使用提供商（自定义/Base URL） 使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。 下面许多内置提供商插件已经发布了默认目录。 -只有当你想覆盖默认基础 URL、请求头或模型列表时，才使用显式的 `models.providers.` 条目。 +只有当你想覆盖默认 base URL、请求头或模型列表时，才使用显式的 `models.providers.` 条目。 ### Moonshot AI（Kimi） -Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在你需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： +Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在你需要覆盖 base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： - 提供商：`moonshot` - 凭证：`MOONSHOT_API_KEY` @@ -390,7 +390,7 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： } ``` -旧版 `kimi/k2p5` 仍然作为兼容模型 ID 被接受。 +旧版 `kimi/k2p5` 仍作为兼容模型 ID 被接受。 ### Volcano Engine（Doubao） @@ -409,9 +409,9 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访 } ``` -新手引导默认使用编程接口，但同时也会注册通用的 `volcengine/*` 目录。 +新手引导默认使用编程界面，但同时也会注册通用的 `volcengine/*` 目录。 -在新手引导/配置模型选择器中，Volcengine 的凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示一个空的按提供商范围筛选的选择器。 +在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -431,7 +431,7 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访 ### BytePlus（国际版） -BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 +BytePlus ARK 为国际用户提供对与 Volcano Engine 相同模型的访问。 - 提供商：`byteplus`（编程版：`byteplus-plan`） - 凭证：`BYTEPLUS_API_KEY` @@ -446,9 +446,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 } ``` -新手引导默认使用编程接口，但同时也会注册通用的 `byteplus/*` 目录。 +新手引导默认使用编程界面，但同时也会注册通用的 `byteplus/*` 目录。 -在新手引导/配置模型选择器中，BytePlus（国际版）的凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示一个空的按提供商范围筛选的选择器。 +在新手引导/配置模型选择器中，BytePlus（国际版）凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -496,22 +496,43 @@ Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型： MiniMax 通过 `models.providers` 配置，因为它使用自定义端点： -- MiniMax OAuth（Global）：`--auth-choice minimax-global-oauth` -- MiniMax OAuth（CN）：`--auth-choice minimax-cn-oauth` -- MiniMax API 密钥（Global）：`--auth-choice minimax-global-api` -- MiniMax API 密钥（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 + +LM Studio 作为内置提供商插件提供，并使用原生 API： + +- 提供商：`lmstudio` +- 凭证：`LM_API_TOKEN` +- 默认推理 Base URL：`http://localhost:1234/v1` + +然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的其中一个 ID）： + +```json5 +{ + agents: { + defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } }, + }, +} +``` + +OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` 进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。 +设置与故障排除参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 ### Ollama @@ -535,7 +556,8 @@ ollama pull llama3.3 } ``` -当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，并且内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。 +当你通过 `OLLAMA_API_KEY` 选择启用时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到，并且内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。 +关于新手引导、云端/本地模式和自定义配置，参见 [/providers/ollama](/zh-CN/providers/ollama)。 ### vLLM @@ -543,15 +565,15 @@ vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容 - 提供商：`vllm` - 凭证：可选（取决于你的服务器） -- 默认基础 URL：`http://127.0.0.1:8000/v1` +- 默认 base URL：`http://127.0.0.1:8000/v1` -要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）： +若要在本地选择启用自动发现（如果你的服务器不强制凭证，任意值都可以）： ```bash export VLLM_API_KEY="vllm-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `/v1/models` 返回的其中一个 ID）： ```json5 { @@ -561,23 +583,23 @@ export VLLM_API_KEY="vllm-local" } ``` -详见 [/providers/vllm](/zh-CN/providers/vllm)。 +详情参见 [/providers/vllm](/zh-CN/providers/vllm)。 ### SGLang -SGLang 作为内置提供商插件提供，用于快速自托管的 OpenAI 兼容服务器： +SGLang 作为内置提供商插件提供，用于高速自托管的 OpenAI 兼容服务器： - 提供商：`sglang` - 凭证：可选（取决于你的服务器） -- 默认基础 URL：`http://127.0.0.1:30000/v1` +- 默认 base URL：`http://127.0.0.1:30000/v1` -要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）： +若要在本地选择启用自动发现（如果你的服务器不强制凭证，任意值都可以）： ```bash export SGLANG_API_KEY="sglang-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `/v1/models` 返回的其中一个 ID）： ```json5 { @@ -587,7 +609,7 @@ export SGLANG_API_KEY="sglang-local" } ``` -详见 [/providers/sglang](/zh-CN/providers/sglang)。 +详情参见 [/providers/sglang](/zh-CN/providers/sglang)。 ### 本地代理（LM Studio、vLLM、LiteLLM 等） @@ -598,19 +620,19 @@ export SGLANG_API_KEY="sglang-local" agents: { defaults: { model: { primary: "lmstudio/my-local-model" }, - models: { "lmstudio/my-local-model": { alias: "本地" } }, + models: { "lmstudio/my-local-model": { alias: "Local" } }, }, }, models: { providers: { lmstudio: { baseUrl: "http://localhost:1234/v1", - apiKey: "LMSTUDIO_KEY", + apiKey: "${LM_API_TOKEN}", api: "openai-completions", models: [ { id: "my-local-model", - name: "本地模型", + name: "Local Model", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -627,17 +649,17 @@ export SGLANG_API_KEY="sglang-local" 说明： - 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。 - 如果省略，OpenClaw 默认使用： + 若省略，OpenClaw 默认使用： - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` - 建议：设置与你的代理/模型限制相匹配的显式值。 -- 对于非原生端点上的 `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`）。 -- 出于安全考虑，即使在非原生 `openai-completions` 端点上显式设置了 `compat.supportsDeveloperRole: true`，也仍会被覆盖。 +- 对于非原生端点上的 `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` 端点上仍会被覆盖。 ## CLI 示例 @@ -647,7 +669,7 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -另见：[/gateway/configuration](/zh-CN/gateway/configuration)，查看完整配置示例。 +另见：[/gateway/configuration](/zh-CN/gateway/configuration)，其中提供了完整配置示例。 ## 相关内容 diff --git a/docs/zh-CN/gateway/local-models.md b/docs/zh-CN/gateway/local-models.md index 199ca0ff9..1dfff362a 100644 --- a/docs/zh-CN/gateway/local-models.md +++ b/docs/zh-CN/gateway/local-models.md @@ -1,28 +1,28 @@ --- read_when: - - 你想从你自己的 GPU 主机提供模型 - - 你正在连接 LM Studio 或兼容 OpenAI 的代理 - - 你需要最安全的本地模型指导 + - 你想从你自己的 GPU 机器提供模型服务 + - 你正在配置 LM Studio 或兼容 OpenAI 的代理服务 + - 你需要最安全的本地模型使用指引 summary: 在本地 LLM 上运行 OpenClaw（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点） title: 本地模型 x-i18n: - generated_at: "2026-04-07T14:57:30Z" + generated_at: "2026-04-13T07:24:29Z" model: gpt-5.4 provider: openai - source_hash: d619d72b0e06914ebacb7e9f38b746caf1b9ce8908c9c6638c3acdddbaa025e8 + source_hash: 3ecb61b3e6e34d3666f9b688cd694d92c5fb211cf8c420fa876f7ccf5789154a source_path: gateway/local-models.md workflow: 15 --- # 本地模型 -本地部署是可行的，但 OpenClaw 需要大上下文窗口以及对提示注入的强防护。小显卡会截断上下文并削弱安全性。尽量配置更高：**≥2 台满配 Mac Studio 或同等 GPU 主机（约 3 万美元以上）**。单张 **24 GB** GPU 只适用于较轻的提示词，而且延迟更高。使用**你能运行的最大 / 完整尺寸模型变体**；激进量化或“小型”检查点会提高提示注入风险（参见[安全](/zh-CN/gateway/security)）。 +本地部署是可行的，但 OpenClaw 需要大上下文窗口以及强大的提示注入防御能力。小显存卡会截断上下文并削弱安全性。尽量追求高配置：**≥ 2 台满配 Mac Studio 或同等级别的 GPU 设备（约 3 万美元以上）**。单张 **24 GB** GPU 仅适用于较轻量的提示词场景，且延迟会更高。使用**你能够运行的最大 / 完整尺寸模型变体**；激进量化或“small”检查点会提高提示注入风险（参见 [安全](/zh-CN/gateway/security)）。 -如果你想要最低摩擦的本地配置，先从 [Ollama](/zh-CN/providers/ollama) 和 `openclaw onboard` 开始。本页是面向更高端本地栈和自定义兼容 OpenAI 的本地服务器的推荐指南。 +如果你想要摩擦最小的本地配置方式，先从 [LM Studio](/zh-CN/providers/lmstudio) 或 [Ollama](/zh-CN/providers/ollama) 和 `openclaw onboard` 开始。本页是针对更高端本地堆栈以及自定义兼容 OpenAI 的本地服务器的倾向性指南。 ## 推荐：LM Studio + 大型本地模型（Responses API） -这是当前最推荐的本地方案。在 LM Studio 中加载一个大型模型（例如完整尺寸的 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 将推理内容与最终文本分离。 +这是当前最好的本地方案。先在 LM Studio 中加载一个大型模型（例如完整尺寸的 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 让推理过程与最终文本分离。 ```json5 { @@ -59,18 +59,18 @@ x-i18n: } ``` -**设置清单** +**设置检查清单** - 安装 LM Studio：[https://lmstudio.ai](https://lmstudio.ai) -- 在 LM Studio 中，下载**可用的最大模型构建**（避免“小型”/重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 已列出该模型。 +- 在 LM Studio 中，下载**当前可用的最大模型构建**（避免使用 “small”/重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 能列出该模型。 - 将 `my-local-model` 替换为 LM Studio 中显示的实际模型 ID。 - 保持模型处于已加载状态；冷加载会增加启动延迟。 -- 如果你的 LM Studio 构建不同，请调整 `contextWindow` / `maxTokens`。 +- 如果你的 LM Studio 构建不同，请调整 `contextWindow`/`maxTokens`。 - 对于 WhatsApp，坚持使用 Responses API，这样只会发送最终文本。 -即使在本地运行，也请保留托管模型配置；使用 `models.mode: "merge"`，这样回退模型仍然可用。 +即使在运行本地模型时，也要保留托管模型配置；使用 `models.mode: "merge"`，这样回退模型仍然可用。 -### 混合配置：托管模型为主，本地模型回退 +### 混合配置：托管模型为主，本地模型为回退 ```json5 { @@ -111,18 +111,18 @@ x-i18n: } ``` -### 本地优先，托管模型作安全兜底 +### 本地优先，并保留托管安全网 -交换 primary 和 fallback 的顺序；保留相同的 providers 配置块以及 `models.mode: "merge"`，这样当本地主机不可用时，你仍然可以回退到 Sonnet 或 Opus。 +交换 `primary` 和 `fallbacks` 的顺序；保留相同的 providers 配置块以及 `models.mode: "merge"`，这样当本地机器不可用时，你仍然可以回退到 Sonnet 或 Opus。 ### 区域托管 / 数据路由 -- 托管版的 MiniMax / Kimi / GLM 变体也可通过 OpenRouter 的区域固定端点提供（例如托管在美国的端点）。你可以在那里选择区域变体，使流量保留在你指定的司法辖区内，同时仍然使用 `models.mode: "merge"` 作为 Anthropic / OpenAI 的回退。 -- 纯本地仍然是隐私性最强的方案；当你需要提供商功能，但又希望控制数据流向时，区域托管路由是折中方案。 +- 托管版的 MiniMax/Kimi/GLM 变体也可通过 OpenRouter 的区域固定端点使用（例如托管在美国的端点）。你可以在那里选择区域变体，从而让流量保留在你指定的司法辖区内，同时仍然使用 `models.mode: "merge"` 来保留 Anthropic/OpenAI 回退。 +- 纯本地仍然是隐私性最强的方案；当你需要提供商特性、但又希望控制数据流向时，区域托管路由是折中选择。 ## 其他兼容 OpenAI 的本地代理 -只要 vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关 暴露的是兼容 OpenAI 风格的 `/v1` 端点，就可以使用。将上面的 provider 配置块替换为你的端点和模型 ID： +只要 vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关暴露的是兼容 OpenAI 风格的 `/v1` 端点，就可以使用。将上面的 provider 配置块替换为你的端点和模型 ID： ```json5 { @@ -150,41 +150,25 @@ x-i18n: } ``` -保留 `models.mode: "merge"`，这样托管模型仍然可以作为回退使用。 +保留 `models.mode: "merge"`，这样托管模型仍可作为回退选项使用。 -关于本地 / 代理 `/v1` 后端的行为说明： +针对本地 / 代理 `/v1` 后端的行为说明： -- OpenClaw 将这些视为代理风格的兼容 OpenAI 路由，而不是原生 - OpenAI 端点 -- 仅适用于原生 OpenAI 的请求整形不会在这里生效：没有 - `service_tier`，没有 Responses `store`，没有 OpenAI 推理兼容负载 - 整形，也没有提示缓存提示 -- 隐藏的 OpenClaw 归因头（`originator`、`version`、`User-Agent`） - 不会注入到这些自定义代理 URL 上 +- OpenClaw 会将这些路径视为代理风格的兼容 OpenAI 路由，而不是原生 OpenAI 端点 +- 仅适用于原生 OpenAI 的请求整形不会在这里生效：没有 `service_tier`、没有 Responses `store`、没有 OpenAI 推理兼容负载整形，也没有提示缓存提示 +- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）不会注入到这些自定义代理 URL 中 -对于更严格的兼容 OpenAI 后端的兼容性说明： +针对更严格的兼容 OpenAI 后端的兼容性说明： -- 某些服务器在 Chat Completions 中只接受字符串类型的 `messages[].content`，而不接受 - 结构化的内容片段数组。对于这类端点，请设置 - `models.providers..models[].compat.requiresStringContent: true`。 -- 某些更小型或更严格的本地后端无法稳定处理 OpenClaw 完整的 - 智能体运行时提示结构，尤其是在包含工具 schema 时。如果该 - 后端可以处理很小的直接 `/v1/chat/completions` 调用，但在正常 - OpenClaw 智能体轮次中失败，请先尝试设置 - `models.providers..models[].compat.supportsTools: false`。 -- 如果后端仅在更大的 OpenClaw 运行中仍然失败，剩余问题通常 - 是上游模型 / 服务器容量不足，或后端自身的 bug，而不是 OpenClaw 的 - 传输层问题。 +- 有些服务器在 Chat Completions 中只接受字符串形式的 `messages[].content`，而不接受结构化内容片段数组。对于这些端点，请设置 `models.providers..models[].compat.requiresStringContent: true`。 +- 一些较小或更严格的本地后端在面对 OpenClaw 完整的智能体运行时提示格式时会不稳定，尤其是在包含工具 schema 时。如果该后端可以处理很小的直接 `/v1/chat/completions` 调用，但在正常的 OpenClaw 智能体轮次中失败，请先尝试设置 `models.providers..models[].compat.supportsTools: false`。 +- 如果后端仍然只在较大的 OpenClaw 运行中失败，剩余问题通常是上游模型 / 服务器容量不足或后端 bug，而不是 OpenClaw 的传输层问题。 ## 故障排除 -- Gateway 网关 能连接到代理吗？`curl http://127.0.0.1:1234/v1/models`。 +- Gateway 网关能访问代理吗？`curl http://127.0.0.1:1234/v1/models` - LM Studio 模型被卸载了？重新加载；冷启动是常见的“卡住”原因。 -- 上下文报错？降低 `contextWindow` 或提高你的服务器限制。 -- 兼容 OpenAI 的服务器返回 `messages[].content ... expected a string`？ - 在该模型条目上添加 `compat.requiresStringContent: true`。 -- 直接的小型 `/v1/chat/completions` 调用可以工作，但 `openclaw infer model run` - 在 Gemma 或其他本地模型上失败？先使用 - `compat.supportsTools: false` 禁用工具 schema，然后重新测试。如果服务器仍然只在 - 更大的 OpenClaw 提示上崩溃，请将其视为上游服务器 / 模型限制。 -- 安全性：本地模型会跳过提供商侧过滤；请保持智能体范围收窄，并启用压缩，以限制提示注入的影响范围。 +- 上下文报错？降低 `contextWindow`，或提高服务器限制。 +- 兼容 OpenAI 的服务器返回 `messages[].content ... expected a string`？在该模型项上添加 `compat.requiresStringContent: true`。 +- 很小的直接 `/v1/chat/completions` 调用能工作，但 `openclaw infer model run` 在 Gemma 或其他本地模型上失败？先用 `compat.supportsTools: false` 禁用工具 schema，然后重新测试。如果服务器仍然只会在更大的 OpenClaw 提示下崩溃，请将其视为上游服务器 / 模型限制。 +- 安全性：本地模型会跳过提供商侧过滤；请保持智能体范围收敛，并开启压缩，以限制提示注入的影响范围。 diff --git a/docs/zh-CN/providers/index.md b/docs/zh-CN/providers/index.md index 5b9dec4c9..1695a8d30 100644 --- a/docs/zh-CN/providers/index.md +++ b/docs/zh-CN/providers/index.md @@ -1,14 +1,14 @@ --- read_when: - - 你想选择一个模型提供商 - - 你需要快速了解受支持的 LLM 后端 + - 你想要选择一个模型提供商 + - 你需要快速了解受支持的 LLM 后端概览 summary: OpenClaw 支持的模型提供商（LLM） title: 提供商目录 x-i18n: - generated_at: "2026-04-07T14:57:15Z" + generated_at: "2026-04-13T07:24:18Z" model: gpt-5.4 provider: openai - source_hash: e7bee5528b7fc9a982b3d0eaa4930cb77f7bded19a47aec00572b6fcbd823a70 + source_hash: 3bc682d008119719826f71f74959ab32bedf14214459f5e6ac9cb70371d3c540 source_path: providers/index.md workflow: 15 --- @@ -17,11 +17,11 @@ x-i18n: OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份验证，然后将默认模型设置为 `provider/model`。 -在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/ 等）？请参阅 [渠道](/zh-CN/channels)。 +在寻找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/等）？请参阅 [Channels](/zh-CN/channels)。 ## 快速开始 -1. 使用该提供商完成身份验证（通常通过 `openclaw onboard`）。 +1. 使用提供商完成身份验证（通常通过 `openclaw onboard`）。 2. 设置默认模型： ```json5 @@ -32,7 +32,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份 ## 提供商文档 -- [Alibaba Model Studio](/zh-CN/providers/alibaba) +- [阿里巴巴 Model Studio](/zh-CN/providers/alibaba) - [Amazon Bedrock](/zh-CN/providers/bedrock) - [Anthropic（API + Claude CLI）](/zh-CN/providers/anthropic) - [Arcee AI（Trinity 模型）](/zh-CN/providers/arcee) @@ -51,6 +51,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份 - [inferrs（本地模型）](/zh-CN/providers/inferrs) - [Kilocode](/zh-CN/providers/kilocode) - [LiteLLM（统一 Gateway 网关）](/zh-CN/providers/litellm) +- [LM Studio（本地模型）](/zh-CN/providers/lmstudio) - [MiniMax](/zh-CN/providers/minimax) - [Mistral](/zh-CN/providers/mistral) - [Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot) @@ -60,7 +61,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份 - [OpenCode](/zh-CN/providers/opencode) - [OpenCode Go](/zh-CN/providers/opencode-go) - [OpenRouter](/zh-CN/providers/openrouter) -- [Perplexity（Web 搜索）](/zh-CN/providers/perplexity-provider) +- [Perplexity（网络搜索）](/zh-CN/providers/perplexity-provider) - [Qianfan](/zh-CN/providers/qianfan) - [Qwen Cloud](/zh-CN/providers/qwen) - [Runway](/zh-CN/providers/runway) @@ -80,9 +81,9 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份 ## 共享概览页面 - [其他内置变体](/zh-CN/providers/models#additional-bundled-provider-variants) - Anthropic Vertex、Copilot Proxy 和 Gemini CLI OAuth -- [图像生成](/zh-CN/tools/image-generation) - 共享的 `image_generate` 工具、提供商选择和故障转移 -- [音乐生成](/zh-CN/tools/music-generation) - 共享的 `music_generate` 工具、提供商选择和故障转移 -- [视频生成](/zh-CN/tools/video-generation) - 共享的 `video_generate` 工具、提供商选择和故障转移 +- [图像生成](/zh-CN/tools/image-generation) - 通用 `image_generate` 工具、提供商选择和故障切换 +- [音乐生成](/zh-CN/tools/music-generation) - 通用 `music_generate` 工具、提供商选择和故障切换 +- [视频生成](/zh-CN/tools/video-generation) - 通用 `video_generate` 工具、提供商选择和故障切换 ## 转录提供商 @@ -90,6 +91,6 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份 ## 社区工具 -- [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请确认 Anthropic 的政策/条款） +- [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 面向 Claude 订阅凭证的社区代理（使用前请核实 Anthropic 的政策/条款） -如需查看完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。 +有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。 diff --git a/docs/zh-CN/providers/lmstudio.md b/docs/zh-CN/providers/lmstudio.md new file mode 100644 index 000000000..cccf9d6ab --- /dev/null +++ b/docs/zh-CN/providers/lmstudio.md @@ -0,0 +1,163 @@ +--- +read_when: + - 你想通过 LM Studio 使用开源模型运行 OpenClaw。 + - 你想设置并配置 LM Studio。 +summary: 使用 LM Studio 运行 OpenClaw +title: LM Studio +x-i18n: + generated_at: "2026-04-13T07:24:19Z" + model: gpt-5.4 + provider: openai + source_hash: 11264584e8277260d4215feb7c751329ce04f59e9228da1c58e147c21cd9ac2c + source_path: providers/lmstudio.md + workflow: 15 +--- + +# LM Studio + +LM Studio 是一款友好且功能强大的应用，可让你在自己的硬件上运行开放权重模型。它支持运行 llama.cpp（GGUF）或 MLX 模型（Apple Silicon）。提供 GUI 安装包，也提供无头守护进程（`llmster`）。有关产品和设置文档，请参阅 [lmstudio.ai](https://lmstudio.ai/)。 + +## 快速开始 + +1. 安装 LM Studio（桌面版）或 `llmster`（无头版），然后启动本地服务器： + +```bash +curl -fsSL https://lmstudio.ai/install.sh | bash +``` + +2. 启动服务器 + +请确保你要么启动桌面应用，要么使用以下命令运行守护进程： + +```bash +lms daemon up +``` + +```bash +lms server start --port 1234 +``` + +如果你使用的是应用，请确保已启用 JIT，以获得流畅体验。了解更多信息，请参阅 [LM Studio JIT and TTL guide](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict)。 + +3. OpenClaw 需要一个 LM Studio token 值。设置 `LM_API_TOKEN`： + +```bash +export LM_API_TOKEN="your-lm-studio-api-token" +``` + +如果 LM Studio 身份验证已禁用，请使用任意非空 token 值： + +```bash +export LM_API_TOKEN="placeholder-key" +``` + +有关 LM Studio 身份验证设置的详细信息，请参阅 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)。 + +4. 运行新手引导并选择 `LM Studio`： + +```bash +openclaw onboard +``` + +5. 在新手引导中，使用 `Default model` 提示来选择你的 LM Studio 模型。 + +你也可以稍后设置或更改它： + +```bash +openclaw models set lmstudio/qwen/qwen3.5-9b +``` + +LM Studio 模型键采用 `author/model-name` 格式（例如 `qwen/qwen3.5-9b`）。OpenClaw 模型引用会在前面加上提供商名称：`lmstudio/qwen/qwen3.5-9b`。你可以通过运行 `curl http://localhost:1234/api/v1/models` 并查看 `key` 字段来找到某个模型的准确键名。 + +## 非交互式新手引导 + +当你想以脚本方式完成设置时（CI、配置、远程引导），请使用非交互式新手引导： + +```bash +openclaw onboard \ + --non-interactive \ + --accept-risk \ + --auth-choice lmstudio +``` + +或者使用 API key 指定 base URL 或模型： + +```bash +openclaw onboard \ + --non-interactive \ + --accept-risk \ + --auth-choice lmstudio \ + --custom-base-url http://localhost:1234/v1 \ + --lmstudio-api-key "$LM_API_TOKEN" \ + --custom-model-id qwen/qwen3.5-9b +``` + +`--custom-model-id` 接收 LM Studio 返回的模型键（例如 `qwen/qwen3.5-9b`），不包含 `lmstudio/` 提供商前缀。 + +非交互式新手引导需要 `--lmstudio-api-key`（或环境中的 `LM_API_TOKEN`）。 +对于未启用身份验证的 LM Studio 服务器，任意非空 token 值都可以使用。 + +`--custom-api-key` 仍然保留以兼容旧用法，但对于 LM Studio，优先使用 `--lmstudio-api-key`。 + +这会写入 `models.providers.lmstudio`，将默认模型设置为 +`lmstudio/`，并写入 `lmstudio:default` 身份验证配置文件。 + +交互式设置可以提示输入一个可选的首选加载上下文长度，并将其应用到保存到配置中的已发现 LM Studio 模型。 + +## 配置 + +### 显式配置 + +```json5 +{ + models: { + providers: { + lmstudio: { + baseUrl: "http://localhost:1234/v1", + apiKey: "${LM_API_TOKEN}", + api: "openai-completions", + models: [ + { + id: "qwen/qwen3-coder-next", + name: "Qwen 3 Coder Next", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 128000, + maxTokens: 8192, + }, + ], + }, + }, + }, +} +``` + +## 故障排除 + +### 未检测到 LM Studio + +请确保 LM Studio 正在运行，并且你已设置 `LM_API_TOKEN`（对于未启用身份验证的服务器，任意非空 token 值都可以使用）： + +```bash +# 通过桌面应用启动，或以无头方式启动： +lms server start --port 1234 +``` + +验证 API 可访问： + +```bash +curl http://localhost:1234/api/v1/models +``` + +### 身份验证错误（HTTP 401） + +如果设置过程中报告 HTTP 401，请检查你的 API key： + +- 检查 `LM_API_TOKEN` 是否与 LM Studio 中配置的 key 匹配。 +- 有关 LM Studio 身份验证设置的详细信息，请参阅 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)。 +- 如果你的服务器不需要身份验证，请为 `LM_API_TOKEN` 使用任意非空 token 值。 + +### 即时模型加载 + +LM Studio 支持即时（JIT）模型加载，即模型会在第一次请求时加载。请确保已启用此功能，以避免出现“Model not loaded”错误。 diff --git a/docs/zh-CN/reference/api-usage-costs.md b/docs/zh-CN/reference/api-usage-costs.md index 7e574ab7d..d72c290d2 100644 --- a/docs/zh-CN/reference/api-usage-costs.md +++ b/docs/zh-CN/reference/api-usage-costs.md @@ -1,201 +1,199 @@ --- read_when: - - 你想了解哪些功能可能会调用付费 API - - 你需要审计密钥、成本和用量可见性 - - 你正在解释 /status 或 /usage 成本报告 -summary: 审计哪些功能会花钱、使用哪些密钥，以及如何查看用量 -title: API 使用与成本 + - 你想了解哪些功能可能会调用付费 API】【。analysis to=functions.read рацәcommentary ￣色json {"path":"/home/runner/work/docs/docs/source/AGENTS.md","offset":1,"limit":40} + - 你需要审查密钥、费用和用量可见性 + - 你在说明 `/status` 或 `/usage` 的费用报告 +summary: 审查哪些内容会花钱、使用了哪些密钥，以及如何查看用量 +title: API 用量和费用 x-i18n: - generated_at: "2026-04-06T15:31:12Z" + generated_at: "2026-04-13T07:24:24Z" model: gpt-5.4 provider: openai - source_hash: ab6eefcde9ac014df6cdda7aaa77ef48f16936ab12eaa883d9fe69425a31a2dd + source_hash: f5077e74d38ef781ac7a72603e9f9e3829a628b95c5a9967915ab0f321565429 source_path: reference/api-usage-costs.md workflow: 15 --- -# API 使用与成本 +# API 用量与费用 -本文档列出了**可能调用 API 密钥的功能**以及它们的成本会显示在哪里。重点关注 -可能产生提供商用量或付费 API 调用的 OpenClaw 功能。 +本文档列出**可能调用 API 密钥的功能**以及其费用会显示在哪里。它重点介绍 +OpenClaw 中可能产生提供商用量或付费 API 调用的功能。 -## 成本显示位置（聊天 + CLI） +## 费用显示位置（聊天 + CLI） -**按会话的成本快照** +**按会话显示的费用快照** -- `/status` 会显示当前会话模型、上下文用量和上一条回复的 token 数。 -- 如果模型使用的是 **API 密钥认证**，`/status` 还会显示上一条回复的**估算成本**。 -- 如果 live 会话元数据较少，`/status` 可以从最新的转录用量条目中恢复 token/缓存 - 计数器以及当前活动运行时模型标签。现有的非零 live 值仍然优先， - 当已存储总量缺失或更小时，按提示词大小计算的转录总量可以胜出。 +- `/status` 会显示当前会话的模型、上下文用量以及上次回复的 token 数。 +- 如果模型使用**API 密钥认证**，`/status` 还会显示上次回复的**预估费用**。 +- 如果实时会话元数据较少，`/status` 可以从最新的转录用量条目中恢复 token/缓存 + 计数器以及当前运行时模型标签。现有的非零实时数值仍然优先；当存储的总计缺失或更小时， + 基于提示词大小的转录总计可能会优先生效。 -**按消息的成本页脚** +**按消息显示的费用页脚** -- `/usage full` 会在每条回复后追加用量页脚，其中包括**估算成本**（仅 API 密钥）。 -- `/usage tokens` 仅显示 token；订阅式 OAuth/token 和 CLI 流程会隐藏美元成本。 +- `/usage full` 会在每条回复后附加一个用量页脚，包括**预估费用**（仅限 API 密钥）。 +- `/usage tokens` 只显示 token；订阅式 OAuth/token 和 CLI 流程会隐藏美元费用。 - Gemini CLI 说明：当 CLI 返回 JSON 输出时，OpenClaw 会从 - `stats` 中读取用量，将 `stats.cached` 标准化为 `cacheRead`，并在需要时从 - `stats.input_tokens - stats.cached` 推导输入 token。 + `stats` 读取用量，将 `stats.cached` 规范化为 `cacheRead`，并在需要时根据 + `stats.input_tokens - stats.cached` 推导输入 token 数。 -Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用量 -现在再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法 -视为此集成的许可方式，除非 Anthropic 发布新的政策。 -Anthropic 仍然没有提供 OpenClaw 可以在 `/usage full` 中 -显示的逐消息美元估算。 +Anthropic 说明：Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 用量 +再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用量视为此集成的 +受认可方式，除非 Anthropic 发布新的政策。 +Anthropic 仍然不会提供 OpenClaw 能在 `/usage full` 中显示的按消息美元预估。 **CLI 用量窗口（提供商配额）** - `openclaw status --usage` 和 `openclaw channels list` 会显示提供商的**用量窗口** - （配额快照，而不是逐消息成本）。 -- 面向人的输出会在各提供商之间标准化为 `X% left`。 + （配额快照，而不是按消息计费）。 +- 面向用户的输出会在各提供商之间统一为 `X% left`。 - 当前支持用量窗口的提供商：Anthropic、GitHub Copilot、Gemini CLI、 OpenAI Codex、MiniMax、Xiaomi 和 z.ai。 - MiniMax 说明：其原始 `usage_percent` / `usagePercent` 字段表示的是剩余 - 配额，因此 OpenClaw 会在显示前将其反转。如果存在基于计数的字段， - 仍然优先使用计数字段。如果提供商返回 `model_remains`，OpenClaw 会优先使用 - 聊天模型条目，必要时从时间戳推导窗口标签，并在套餐标签中 - 包含模型名称。 -- 这些配额窗口的用量认证会在可用时来自提供商特定钩子；否则 OpenClaw 会回退到从 - 认证 profile、环境变量或配置中匹配 OAuth/API 密钥 - 凭证。 + 配额，因此 OpenClaw 会在显示前对其取反。如果存在按次数计数字段，则这些字段仍优先。 + 如果提供商返回 `model_remains`，OpenClaw 会优先选择聊天模型条目， + 在需要时根据时间戳推导窗口标签，并在计划标签中包含模型名称。 +- 这些配额窗口的用量认证在可用时来自提供商特定的钩子；否则 OpenClaw 会回退为匹配 + 来自认证配置文件、环境变量或配置中的 OAuth/API 密钥凭证。 -详情和示例参见 [Token 使用与成本](/zh-CN/reference/token-use)。 +详见[Token 用量与费用](/zh-CN/reference/token-use)中的详细说明和示例。 ## 如何发现密钥 OpenClaw 可以从以下位置获取凭证： -- **认证 profile**（每个智能体单独存储在 `auth-profiles.json` 中）。 +- **认证配置文件**（按智能体区分，存储在 `auth-profiles.json` 中）。 - **环境变量**（例如 `OPENAI_API_KEY`、`BRAVE_API_KEY`、`FIRECRAWL_API_KEY`）。 - **配置**（`models.providers.*.apiKey`、`plugins.entries.*.config.webSearch.apiKey`、 `plugins.entries.firecrawl.config.webFetch.apiKey`、`memorySearch.*`、 `talk.providers.*.apiKey`）。 -- **Skills**（`skills.entries..apiKey`），它们可能会将密钥导出到 Skill 进程环境变量中。 +- **Skills**（`skills.entries..apiKey`），它们可能会将密钥导出到 Skill 进程环境中。 -## 会消耗密钥的功能 +## 可能会消耗密钥的功能 -### 1）核心模型回复（聊天 + 工具） +### 1) 核心模型响应（聊天 + 工具） -每条回复或工具调用都会使用**当前模型提供商**（OpenAI、Anthropic 等）。这是 -用量和成本的主要来源。 +每次回复或工具调用都会使用**当前模型提供商**（OpenAI、Anthropic 等）。这是 +用量和费用的主要来源。 -这也包括仍在 OpenClaw 本地 UI 之外计费的订阅式托管提供商， -例如 **OpenAI Codex**、**Alibaba Cloud Model Studio +这也包括订阅式托管提供商，它们仍会在 OpenClaw 本地 UI 之外计费，例如 +**OpenAI Codex**、**Alibaba Cloud Model Studio Coding Plan**、**MiniMax Coding Plan**、**Z.AI / GLM Coding Plan**，以及 -启用了 **Extra Usage** 的 Anthropic OpenClaw Claude 登录路径。 +Anthropic 的启用了 **Extra Usage** 的 OpenClaw Claude 登录路径。 -定价配置参见 [模型](/zh-CN/providers/models)，显示方式参见 [Token 使用与成本](/zh-CN/reference/token-use)。 +有关定价配置，请参见[模型](/zh-CN/providers/models)；有关显示方式，请参见[Token 用量与费用](/zh-CN/reference/token-use)。 -### 2）媒体理解（音频/图像/视频） +### 2) 媒体理解（音频/图像/视频） -在执行回复之前，入站媒体可能会先被摘要/转录。这会使用模型/提供商 API。 +在回复开始前，传入媒体可能会先被总结/转录。这会使用模型/提供商 API。 - 音频：OpenAI / Groq / Deepgram / Google / Mistral。 -- 图像：OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot AI / Qwen / Z.AI。 -- 视频：Google / Qwen / Moonshot AI。 +- 图像：OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot / Qwen / Z.AI。 +- 视频：Google / Qwen / Moonshot。 -参见 [媒体理解](/zh-CN/nodes/media-understanding)。 +参见[媒体理解](/zh-CN/nodes/media-understanding)。 -### 3）图像和视频生成 +### 3) 图像和视频生成 -共享的生成能力也可能消耗提供商密钥： +共享生成能力也可能消耗提供商密钥： - 图像生成：OpenAI / Google / fal / MiniMax - 视频生成：Qwen -当 -`agents.defaults.imageGenerationModel` 未设置时，图像生成可以推断出一个基于认证的默认提供商。视频生成当前 -要求显式设置 `agents.defaults.videoGenerationModel`，例如 +当 `agents.defaults.imageGenerationModel` 未设置时，图像生成可以推断 +一个基于认证的提供商默认值。视频生成目前仍需要显式设置 +`agents.defaults.videoGenerationModel`，例如 `qwen/wan2.6-t2v`。 -参见 [图像生成](/zh-CN/tools/image-generation)、[Qwen Cloud](/zh-CN/providers/qwen) -和 [模型](/zh-CN/concepts/models)。 +参见[图像生成](/zh-CN/tools/image-generation)、[Qwen Cloud](/zh-CN/providers/qwen) +和[模型](/zh-CN/concepts/models)。 -### 4）记忆嵌入 + 语义搜索 +### 4) Memory 嵌入 + 语义搜索 -配置为远程提供商时，语义记忆搜索会使用**嵌入 API**： +语义 Memory 搜索在配置为远程提供商时会使用**嵌入 API**： - `memorySearch.provider = "openai"` → OpenAI embeddings - `memorySearch.provider = "gemini"` → Gemini embeddings - `memorySearch.provider = "voyage"` → Voyage embeddings - `memorySearch.provider = "mistral"` → Mistral embeddings +- `memorySearch.provider = "lmstudio"` → LM Studio embeddings（本地/自托管） - `memorySearch.provider = "ollama"` → Ollama embeddings（本地/自托管；通常不会产生托管 API 计费） - 如果本地 embeddings 失败，可选择回退到远程提供商 -你可以通过 `memorySearch.provider = "local"` 保持本地运行（不使用 API）。 +你可以通过设置 `memorySearch.provider = "local"` 保持完全本地运行（无 API 用量）。 -参见 [Memory](/zh-CN/concepts/memory)。 +参见[Memory](/zh-CN/concepts/memory)。 -### 5）Web 搜索工具 +### 5) Web 搜索工具 `web_search` 可能会根据你的提供商产生用量费用： - **Brave Search API**：`BRAVE_API_KEY` 或 `plugins.entries.brave.config.webSearch.apiKey` - **Exa**：`EXA_API_KEY` 或 `plugins.entries.exa.config.webSearch.apiKey` - **Firecrawl**：`FIRECRAWL_API_KEY` 或 `plugins.entries.firecrawl.config.webSearch.apiKey` -- **Gemini（Google 搜索）**：`GEMINI_API_KEY` 或 `plugins.entries.google.config.webSearch.apiKey` +- **Gemini（Google Search）**：`GEMINI_API_KEY` 或 `plugins.entries.google.config.webSearch.apiKey` - **Grok（xAI）**：`XAI_API_KEY` 或 `plugins.entries.xai.config.webSearch.apiKey` -- **Kimi（Moonshot AI）**：`KIMI_API_KEY`、`MOONSHOT_API_KEY` 或 `plugins.entries.moonshot.config.webSearch.apiKey` +- **Kimi（Moonshot）**：`KIMI_API_KEY`、`MOONSHOT_API_KEY` 或 `plugins.entries.moonshot.config.webSearch.apiKey` - **MiniMax Search**：`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`、`MINIMAX_API_KEY` 或 `plugins.entries.minimax.config.webSearch.apiKey` -- **Ollama Web 搜索**：默认不需要密钥，但要求可访问的 Ollama 主机以及 `ollama signin`；当主机要求时，也可以复用普通的 Ollama 提供商 bearer 认证 +- **Ollama Web 搜索**：默认不需要密钥，但需要可访问的 Ollama 主机以及 `ollama signin`；当主机要求认证时，也可以复用普通的 Ollama 提供商 bearer 认证 - **Perplexity Search API**：`PERPLEXITY_API_KEY`、`OPENROUTER_API_KEY` 或 `plugins.entries.perplexity.config.webSearch.apiKey` - **Tavily**：`TAVILY_API_KEY` 或 `plugins.entries.tavily.config.webSearch.apiKey` -- **DuckDuckGo**：无密钥回退方案（不产生 API 计费，但属于非官方且基于 HTML） -- **SearXNG**：`SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`（无密钥/自托管；不产生托管 API 计费） +- **DuckDuckGo**：无密钥回退方案（无 API 计费，但为非官方且基于 HTML） +- **SearXNG**：`SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`（无密钥/自托管；无托管 API 计费） -旧版 `tools.web.search.*` 提供商路径仍会通过临时兼容层加载，但它们已不再是推荐的配置接口。 +旧版 `tools.web.search.*` 提供商路径仍会通过临时兼容层加载，但它们已不再是推荐的配置入口。 -**Brave Search 免费额度：** 每个 Brave 套餐都包含每月 \$5 的可续期 -免费额度。Search 套餐价格为每 1,000 次请求 \$5，因此该额度可覆盖 -每月 1,000 次免费请求。请在 Brave 控制台中设置用量上限， -以避免意外费用。 +**Brave Search 免费额度：** 每个 Brave 套餐都包含每月 \$5 的可续期免费额度。 +Search 套餐的价格为每 1,000 次请求 \$5，因此该额度可覆盖每月 +1,000 次免费请求。请在 Brave 控制台中设置用量上限，以避免意外收费。 -参见 [Web 工具](/zh-CN/tools/web)。 +参见[Web 工具](/zh-CN/tools/web)。 -### 5）Web 抓取工具（Firecrawl） +### 5) Web 抓取工具（Firecrawl） 当存在 API 密钥时，`web_fetch` 可以调用 **Firecrawl**： - `FIRECRAWL_API_KEY` 或 `plugins.entries.firecrawl.config.webFetch.apiKey` -如果未配置 Firecrawl，该工具会回退到直接抓取 + readability（无付费 API）。 +如果未配置 Firecrawl，该工具会回退为直接抓取 + readability（不使用付费 API）。 -参见 [Web 工具](/zh-CN/tools/web)。 +参见[Web 工具](/zh-CN/tools/web)。 -### 6）提供商用量快照（状态/健康） +### 6) 提供商用量快照（状态/健康） -某些状态命令会调用**提供商用量端点**以显示配额窗口或认证健康状态。 -这些通常是低频调用，但仍会命中提供商 API： +某些状态命令会调用**提供商用量端点**来显示配额窗口或认证健康状态。 +这些通常是低频调用，但仍会访问提供商 API： - `openclaw status --usage` - `openclaw models status --json` -参见 [Models CLI](/cli/models)。 +参见[模型 CLI](/cli/models)。 -### 7）压缩保护摘要 +### 7) 压缩保护摘要 -压缩保护机制可以使用**当前模型**对会话历史进行摘要， -运行时会调用提供商 API。 +压缩保护功能可以使用**当前模型**来总结会话历史，这会在运行时 +调用提供商 API。 -参见 [会话管理 + 压缩](/zh-CN/reference/session-management-compaction)。 +参见[会话管理 + 压缩](/zh-CN/reference/session-management-compaction)。 -### 8）模型扫描 / 探测 +### 8) 模型扫描 / 探测 -在启用探测时，`openclaw models scan` 可以探测 OpenRouter 模型，并使用 `OPENROUTER_API_KEY`。 +`openclaw models scan` 可以探测 OpenRouter 模型，并会在 +启用探测时使用 `OPENROUTER_API_KEY`。 -参见 [Models CLI](/cli/models)。 +参见[模型 CLI](/cli/models)。 -### 9）Talk（语音） +### 9) Talk（语音） -配置后，Talk 模式可以调用 **ElevenLabs**： +Talk 模式在配置后可以调用 **ElevenLabs**： - `ELEVENLABS_API_KEY` 或 `talk.providers.elevenlabs.apiKey` -参见 [Talk 模式](/zh-CN/nodes/talk)。 +参见[Talk 模式](/zh-CN/nodes/talk)。 -### 10）Skills（第三方 API） +### 10) Skills（第三方 API） Skills 可以在 `skills.entries..apiKey` 中存储 `apiKey`。如果某个 Skill 使用该密钥访问外部 -API，它就可能按该 Skill 提供商的规则产生费用。 +API，就可能根据该 Skill 的提供商产生费用。 -参见 [Skills](/zh-CN/tools/skills)。 +参见[Skills](/zh-CN/tools/skills)。