diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index dc66ee2e1..a90aca46c 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -1,95 +1,95 @@ --- read_when: - 你需要一份按提供商划分的模型设置参考 - - 你想要模型提供商的配置示例或 CLI 新手引导命令 + - 你想要模型提供商的示例配置或 CLI 新手引导命令 sidebarTitle: Model providers -summary: 模型提供商概览，包含配置示例和 CLI 流程 +summary: 模型提供商概览，包含配置示例 + CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-05-02T02:37:18Z" + generated_at: "2026-05-02T05:17:43Z" model: gpt-5.5 provider: openai - source_hash: 34e6a6b691b447a66a94f69a7b609f26c587eaa5bc55c5ed62460ce14cc288fd + source_hash: 02494bfb71c0e0449eacd9ec028316e7a1479e51c6591aea5885baf3941272d5 source_path: concepts/model-providers.md workflow: 16 --- -LLM/模型提供商（不是 WhatsApp/Telegram 这样的聊天渠道）参考。模型选择规则见 [Models](/zh-CN/concepts/models)。 +模型选择规则请参阅 [Models](/zh-CN/concepts/models)。 ## 快速规则 - 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。 - - 设置后，`agents.defaults.models` 会作为允许列表。 + - 设置 `agents.defaults.models` 后，它会作为允许列表。 - CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 - - `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 会按模型覆盖这些默认值。 + - `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 会按模型覆盖它们。 - 回退规则、冷却探测和会话覆盖持久化：[模型故障转移](/zh-CN/concepts/model-failover)。 - 添加提供商或重新认证提供商时，`openclaw configure` 会保留现有的 `agents.defaults.model.primary`。提供商插件仍可能在其凭证配置补丁中返回推荐的默认模型，但如果主模型已存在，configure 会将其视为“让这个模型可用”，而不是“替换当前主模型”。 + 当你添加提供商或重新授权提供商时，`openclaw configure` 会保留现有的 `agents.defaults.model.primary`。提供商插件仍可能在其凭证配置补丁中返回推荐的默认模型，但如果主模型已经存在，configure 会将其视为“让此模型可用”，而不是“替换当前主模型”。 若要有意切换默认模型，请使用 `openclaw models set ` 或 `openclaw models auth login --provider --set-default`。 - + OpenAI 系列路由按前缀区分： - `openai/` 加上 `agents.defaults.agentRuntime.id: "codex"` 使用原生 Codex 应用服务器 harness。这是常见的 ChatGPT/Codex 订阅设置。 - `openai-codex/` 在 PI 中使用 Codex OAuth。 - - 没有 Codex 运行时覆盖的 `openai/` 在 PI 中使用直接 OpenAI API key 提供商。 + - 没有 Codex 运行时覆盖的 `openai/` 使用 PI 中的直接 OpenAI API key 提供商。 - 见 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果提供商/运行时拆分让人困惑，请先阅读 [Agent runtimes](/zh-CN/concepts/agent-runtimes)。 + 请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果 provider/运行时拆分令人困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 - 插件自动启用遵循同一边界：`openai-codex/` 属于 OpenAI 插件，而 Codex 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/` 引用启用。 + 插件自动启用遵循相同边界：`openai-codex/` 属于 OpenAI 插件，而 Codex 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/` 引用启用。 - 设置 `agentRuntime.id: "codex"` 时，可通过原生 Codex 应用服务器 harness 使用 GPT-5.5；在 PI 中可通过 `openai-codex/gpt-5.5` 使用 Codex OAuth；当你的账号暴露该模型时，在 PI 中可通过 `openai/gpt-5.5` 使用直接 API key 流量。 + 设置 `agentRuntime.id: "codex"` 时，GPT-5.5 可通过原生 Codex 应用服务器 harness 使用；对于 Codex OAuth，可通过 PI 中的 `openai-codex/gpt-5.5` 使用；当你的账号开放该模型时，对于直接 API-key 流量，可通过 PI 中的 `openai/gpt-5.5` 使用。 - CLI 运行时使用相同的拆分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在你需要本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。 + CLI 运行时使用相同拆分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在需要本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。 - 旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范提供商引用，并单独记录运行时。 + 旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范提供商引用，并将运行时单独记录。 ## 插件拥有的提供商行为 -大多数提供商专用逻辑位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、凭证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、思考/推理 profile 等能力。 +大多数提供商特定逻辑位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、凭证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、thinking/reasoning 配置等。 -提供商 SDK 钩子和内置插件示例的完整列表位于 [Provider plugins](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于一个独立且更深的扩展面。 +提供商 SDK 钩子和内置插件示例的完整列表位于[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于单独且更深层的扩展面。 -提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求辅助函数。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容性，不再由共享 runner 逻辑读取。 +提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求辅助工具。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容性，不再由共享 runner 逻辑读取。 ## API key 轮换 - - 通过以下方式配置多个 key： + + 通过以下方式配置多个密钥： - `OPENCLAW_LIVE__KEY`（单个实时覆盖，最高优先级） - `_API_KEYS`（逗号或分号列表） - - `_API_KEY`（主 key） + - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） - 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。Key 选择顺序会保留优先级并对值去重。 + 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。密钥选择顺序会保留优先级并对值去重。 - - - 只有在限流响应时，请求才会使用下一个 key 重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。 - - 非限流失败会立即失败；不会尝试 key 轮换。 - - 当所有候选 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 @@ -102,12 +102,12 @@ OpenClaw 随附 pi‑ai 目录。这些提供商**不需要** `models.providers` - 默认传输为 `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 优先处理 +- 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 兼容代理 +- 当你想要显式层级而不是共享的 `/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 目录未暴露它 +- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未公开它 ```json5 { @@ -122,14 +122,14 @@ 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 key 与 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`） -- 首选 Claude CLI 配置会保留规范模型引用，并单独选择 CLI +- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API-key 和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`） +- 首选 Claude CLI 配置会保持模型引用规范，并单独选择 CLI 后端：`anthropic/claude-opus-4-7` 搭配 `agents.defaults.agentRuntime.id: "claude-cli"`。旧版 - `claude-cli/claude-opus-4-7` 引用仍可用于兼容性。 + `claude-cli/claude-opus-4-7` 引用仍可用于兼容。 -Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用方式已再次被允许，因此除非 Anthropic 发布新策略，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成中受认可的方式。Anthropic setup-token 仍作为受支持的 OpenClaw 令牌路径可用，但 OpenClaw 现在优先使用 Claude CLI 复用和可用时的 `claude -p`。 +Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将此集成中的 Claude CLI 复用和 `claude -p` 用法视为已获准。Anthropic setup-token 仍作为受支持的 OpenClaw token 路径可用，但 OpenClaw 现在会在可用时优先使用 Claude CLI 复用和 `claude -p`。 ```json5 @@ -141,7 +141,7 @@ Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用方式 ### OpenAI Codex OAuth - 提供商：`openai-codex` -- 凭证：OAuth（ChatGPT） +- 凭证：OAuth (ChatGPT) - PI 模型引用：`openai-codex/gpt-5.5` - 原生 Codex 应用服务器 harness 引用：`openai/gpt-5.5` 搭配 `agents.defaults.agentRuntime.id: "codex"` - 原生 Codex 应用服务器 harness 文档：[Codex harness](/zh-CN/plugins/codex-harness) @@ -151,12 +151,12 @@ Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用方式 - 默认传输为 `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 兼容代理 +- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不附加到通用 OpenAI 兼容代理 - 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射到 `service_tier=priority` -- `openai-codex/gpt-5.5` 使用 Codex 目录原生 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；使用 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 -- 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 这样的外部工具/工作流。 -- 对于常见的订阅加原生 Codex 运行时路由，请使用 `openai-codex` 凭证登录，但配置 `openai/gpt-5.5` 加 `agents.defaults.agentRuntime.id: "codex"`。 -- 只有当你想通过 PI 使用 Codex OAuth/订阅路由时，才使用 `openai-codex/gpt-5.5`；当你的 API key 设置和本地目录暴露公共 API 路由时，请使用没有 Codex 运行时覆盖的 `openai/gpt-5.5`。 +- `openai-codex/gpt-5.5` 使用 Codex 目录原生 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 +- 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 这类外部工具/工作流。 +- 对于常见的订阅加原生 Codex 运行时路由，请使用 `openai-codex` 凭证登录，但配置 `openai/gpt-5.5` 加上 `agents.defaults.agentRuntime.id: "codex"`。 +- 仅当你希望通过 PI 使用 Codex OAuth/订阅路由时，才使用 `openai-codex/gpt-5.5`；当你的 API-key 设置和本地目录公开公共 API 路由时，请使用不带 Codex 运行时覆盖的 `openai/gpt-5.5`。 ```json5 { @@ -216,22 +216,22 @@ Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用方式 - 凭证：`GEMINI_API_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` -- 别名：`google/gemini-3.1-pro` 会被接受，并规范化为 Google 的实时 Gemini API id，即 `google/gemini-3.1-pro-preview` +- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会规范化为 `google/gemini-3-flash-preview` +- 别名：`google/gemini-3.1-pro` 可被接受，并规范化为 Google 实时 Gemini API ID：`google/gemini-3.1-pro-preview` - CLI：`openclaw onboard --auth-choice gemini-api-key` - 思考：`/think adaptive` 使用 Google 动态思考。Gemini 3/3.1 会省略固定的 `thinkingLevel`；Gemini 2.5 会发送 `thinkingBudget: -1`。 -- 直接运行 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 流程 +- 凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程 -OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，使用第三方客户端后遇到了 Google 账号限制。请查看 Google 条款；如果你选择继续，建议使用非关键账号。 +OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后遇到 Google 账号限制。如果你选择继续，请查看 Google 条款，并使用非关键账号。 -Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 +Gemini CLI OAuth 作为内置 `google` 插件的一部分发布。 @@ -258,7 +258,7 @@ Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 openclaw models auth login --provider google-gemini-cli --set-default ``` - 默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不**需要把客户端 id 或密钥粘贴到 `openclaw.json`。CLI 登录流程会把令牌存储在 Gateway 网关主机上的凭证配置文件中。 + 默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不**需要把客户端 ID 或密钥粘贴到 `openclaw.json`。CLI 登录流程会将令牌存储在 Gateway 网关主机上的认证配置文件中。 @@ -266,16 +266,16 @@ Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 -Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 +Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，并将 `stats.cached` 规范化为 OpenClaw `cacheRead`。 -### Z.AI（GLM） +### Z.AI (GLM) - 提供商：`zai` - 凭证：`ZAI_API_KEY` - 示例模型：`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 网关 @@ -291,25 +291,25 @@ Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`， - 示例模型：`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)。 +有关设置详情，请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。 ### 其他内置提供商插件 -| 提供商 | Id | 凭证环境变量 | 示例模型 | +| 提供商 | ID | 凭证环境变量 | 示例模型 | | ----------------------- | -------------------------------- | ------------------------------------------------------------ | --------------------------------------------- | | BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | | Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | -| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | +| Cloudflare AI Gateway 网关 | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | | DeepInfra | `deepinfra` | `DEEPINFRA_API_KEY` | `deepinfra/deepseek-ai/DeepSeek-V3.2` | | DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | | 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` | -| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | -| Kimi Coding | `kimi` | `KIMI_API_KEY` or `KIMICODE_API_KEY` | `kimi/kimi-code` | +| 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` 或 `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 | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | @@ -320,31 +320,31 @@ Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`， | StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | | Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | | Venice | `venice` | `VENICE_API_KEY` | — | -| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | -| Volcano Engine（Doubao） | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | +| Vercel AI Gateway 网关 | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | +| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | | xAI | `xai` | `XAI_API_KEY` | `xai/grok-4.3` | | Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | -#### 值得了解的特殊情况 +#### 需要了解的特性 - 仅在已验证的 `openrouter.ai` 路由上应用其应用归因标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 管理的提示缓存 TTL 条件，但不会收到 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的塑形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容）。Gemini 后端引用仅保留代理 Gemini 思维签名清理。 + 仅在已验证的 `openrouter.ai` 路由上应用其应用归属标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 托管提示缓存的缓存 TTL 条件，但不会接收 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的形态调整（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容）。Gemini 支持的引用仅保留代理 Gemini 思维签名清理。 - Gemini 后端引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。 + Gemini 支持的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。 - API key 新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍由插件自有的 `MiniMax-VL-01` 媒体提供商处理。 + API key 新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍使用插件拥有的 `MiniMax-VL-01` 媒体提供商。 - 模型 ID 使用 `nvidia//` 命名空间（例如 `nvidia/nvidia/nemotron-...` 以及 `nvidia/moonshotai/kimi-k2.5`）；选择器会保留字面量 `/` 组合，而发送到 API 的规范键仍保持单前缀。 + 模型 ID 使用 `nvidia//` 命名空间（例如 `nvidia/nvidia/nemotron-...` 以及 `nvidia/moonshotai/kimi-k2.5`）；选择器会保留字面上的 `/` 组合，而发送到 API 的规范键保持单前缀。 - 使用 xAI Responses 路径。`grok-4.3` 是内置默认聊天模型。`/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` 禁用。 + 使用 xAI Responses 路径。`grok-4.3` 是内置的默认聊天模型。`/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`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。 + 作为内置的 `cerebras` 提供商插件交付。GLM 使用 `zai-glm-4.7`；OpenAI 兼容的基础 URL 是 `https://api.cerebras.ai/v1`。 @@ -354,14 +354,14 @@ Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`， 下面许多内置提供商插件已经发布默认目录。仅当你想覆盖默认基础 URL、标头或模型列表时，才使用显式的 `models.providers.` 条目。 -Gateway 网关模型能力检查也会读取显式的 `models.providers..models[]` 元数据。如果自定义或代理模型接受图像，请在该模型上设置 `input: ["text", "image"]`，这样 WebChat 和源自节点的附件路径会将图像作为原生模型输入传递，而不是作为纯文本媒体引用。 +Gateway 网关模型能力检查也会读取显式的 `models.providers..models[]` 元数据。如果自定义或代理模型接受图像，请在该模型上设置 `input: ["text", "image"]`，以便 WebChat 和节点来源附件路径将图像作为原生模型输入传递，而不是作为纯文本媒体引用。 -### Moonshot AI (Kimi) +### Moonshot AI（Kimi） -Moonshot 作为内置提供商插件发布。默认使用内置提供商，并且仅在需要覆盖基础 URL 或模型元数据时才添加显式的 `models.providers.moonshot` 条目： +Moonshot 作为内置提供商插件交付。默认使用内置提供商，仅当需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： - 提供商：`moonshot` -- 认证：`MOONSHOT_API_KEY` +- 凭证：`MOONSHOT_API_KEY` - 示例模型：`moonshot/kimi-k2.6` - CLI：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn` @@ -401,7 +401,7 @@ Kimi K2 模型 ID： Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： - 提供商：`kimi` -- 认证：`KIMI_API_KEY` +- 凭证：`KIMI_API_KEY` - 示例模型：`kimi/kimi-code` ```json5 @@ -413,11 +413,11 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： } ``` -旧版 `kimi/k2p5` 仍作为兼容性模型 ID 被接受。 +旧版 `kimi/k2p5` 仍作为兼容模型 ID 被接受。 -### Volcano Engine（豆包） +### Volcano Engine（Doubao） -Volcano Engine（火山引擎）提供在中国访问豆包和其他模型的能力。 +Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。 - 提供商：`volcengine`（编码：`volcengine-plan`） - 凭证：`VOLCANO_ENGINE_API_KEY` @@ -432,9 +432,9 @@ Volcano Engine（火山引擎）提供在中国访问豆包和其他模型的能 } ``` -新手引导默认使用编码接口，但通用 `volcengine/*` 目录会同时注册。 +新手引导默认使用编码入口，但同时会注册通用的 `volcengine/*` 目录。 -在新手引导/配置模型选择器中，Volcengine 凭证选项优先显示 `volcengine/*` 和 `volcengine-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。 +在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个按提供商范围过滤后为空的选择器。 @@ -457,7 +457,7 @@ Volcano Engine（火山引擎）提供在中国访问豆包和其他模型的能 ### BytePlus（国际版） -BytePlus ARK 为国际用户提供访问与 Volcano Engine 相同模型的能力。 +BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。 - 提供商：`byteplus`（编码：`byteplus-plan`） - 凭证：`BYTEPLUS_API_KEY` @@ -472,9 +472,9 @@ BytePlus ARK 为国际用户提供访问与 Volcano Engine 相同模型的能力 } ``` -新手引导默认使用编码接口，但通用 `byteplus/*` 目录会同时注册。 +新手引导默认使用编码入口，但同时会注册通用的 `byteplus/*` 目录。 -在新手引导/配置模型选择器中，BytePlus 凭证选项优先显示 `byteplus/*` 和 `byteplus-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。 +在新手引导/配置模型选择器中，BytePlus 凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个按提供商范围过滤后为空的选择器。 @@ -495,7 +495,7 @@ BytePlus ARK 为国际用户提供访问与 Volcano Engine 相同模型的能力 ### Synthetic -Synthetic 在 `synthetic` 提供商后提供 Anthropic 兼容模型： +Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型： - 提供商：`synthetic` - 凭证：`SYNTHETIC_API_KEY` @@ -531,28 +531,28 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点： - MiniMax API key（中国）：`--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 默认禁用思考，并且 `/fast on` 会把 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 +在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置，否则 OpenClaw 默认会禁用思考，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -插件拥有的能力拆分： +插件拥有的能力划分： - 文本/聊天默认值保持在 `minimax/MiniMax-M2.7` - 图像生成是 `minimax/image-01` 或 `minimax-portal/image-01` -- 图像理解是在两个 MiniMax 凭证路径上由插件拥有的 `MiniMax-VL-01` +- 图像理解是在两条 MiniMax 凭证路径上均由插件拥有的 `MiniMax-VL-01` - Web 搜索保持在提供商 ID `minimax` ### LM Studio -LM Studio 作为内置提供商插件发布，并使用原生 API： +LM Studio 作为内置提供商插件提供，并使用原生 API： - 提供商：`lmstudio` - 凭证：`LM_API_TOKEN` - 默认推理基础 URL：`http://localhost:1234/v1` -然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的任一 ID）： ```json5 { @@ -562,14 +562,14 @@ LM Studio 作为内置提供商插件发布，并使用原生 API： } ``` -OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 进行设备发现 + 自动加载，默认使用 `/v1/chat/completions` 进行推理。设置和故障排除见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 +OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 进行设备发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。如果你希望由 LM Studio 的 JIT 加载、TTL 和自动驱逐来管理模型生命周期，请设置 `models.providers.lmstudio.params.preload: false`。查看 [/providers/lmstudio](/zh-CN/providers/lmstudio) 了解设置和故障排除。 ### Ollama -Ollama 作为内置提供商插件发布，并使用 Ollama 的原生 API： +Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API： - 提供商：`ollama` -- 凭证：不需要（本地服务器） +- 凭证：无需（本地服务器） - 示例模型：`ollama/llama3.3` - 安装：[https://ollama.com/download](https://ollama.com/download) @@ -586,23 +586,23 @@ ollama pull llama3.3 } ``` -当你通过 `OLLAMA_API_KEY` 选择启用时，OpenClaw 会在本地 `http://127.0.0.1:11434` 检测 Ollama，且内置提供商插件会把 Ollama 直接添加到 `openclaw onboard` 和模型选择器。新手引导、云端/本地模式和自定义配置见 [/providers/ollama](/zh-CN/providers/ollama)。 +当你通过 `OLLAMA_API_KEY` 选择启用时，OpenClaw 会在本地 `http://127.0.0.1:11434` 检测 Ollama，且内置提供商插件会将 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 { @@ -612,23 +612,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` -要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任何值都可以）： +要在本地选择启用自动发现（如果你的服务器不强制凭证，任意值都可以）： ```bash export SGLANG_API_KEY="sglang-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `/v1/models` 返回的任一 ID）： ```json5 { @@ -638,7 +638,7 @@ export SGLANG_API_KEY="sglang-local" } ``` -详情见 [/providers/sglang](/zh-CN/providers/sglang)。 +查看 [/providers/sglang](/zh-CN/providers/sglang) 了解详情。 ### 本地代理（LM Studio、vLLM、LiteLLM 等） @@ -678,7 +678,7 @@ export SGLANG_API_KEY="sglang-local" - 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 是可选的。省略时，OpenClaw 默认使用： + 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。省略时，OpenClaw 默认使用： - `reasoning: false` - `input: ["text"]` @@ -690,14 +690,14 @@ export SGLANG_API_KEY="sglang-local" - - 对于非原生端点上的 `api: "openai-completions"`（任何非空 `baseUrl` 且其主机不是 `api.openai.com`），OpenClaw 会强制 `compat.supportsDeveloperRole: false`，以避免提供商因不支持的 `developer` 角色返回 400 错误。 - - 代理风格的 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求塑形：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有提示缓存提示，没有 OpenAI 推理兼容载荷塑形，也没有隐藏的 OpenClaw 归因标头。 - - 对于需要厂商特定字段的 OpenAI 兼容 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以把额外 JSON 合并到出站请求体中。 - - 对于 vLLM 聊天模板控件，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话思考级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。 - - 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers..timeoutSeconds`。这会延长提供商模型 HTTP 请求处理时间，包括连接、标头、正文流式传输和总的受保护获取中止时间，而不会增加整个智能体运行时超时。 - - 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（解析到 `api.openai.com`）。 + - 对非原生端点上的 `api: "openai-completions"`（任何非空 `baseUrl` 且其主机不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 + - 代理式 OpenAI 兼容路由还会跳过仅适用于原生 OpenAI 的请求塑形：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有提示缓存提示，没有 OpenAI 推理兼容载荷塑形，也没有隐藏的 OpenClaw 归因标头。 + - 对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以将额外 JSON 合并到出站请求体中。 + - 对于 vLLM 聊天模板控制，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话思考级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。 + - 对于缓慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers..timeoutSeconds`。这会扩展提供商模型 HTTP 请求处理，包括连接、标头、正文流式传输以及总的受保护 fetch 中止时间，而不会增加整个智能体运行时超时。 + - 如果 `baseUrl` 为空/省略，OpenClaw 会保持默认的 OpenAI 行为（解析到 `api.openai.com`）。 - 为安全起见，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。 - - 对于非直连端点上的 `api: "anthropic-messages"`（除规范 `anthropic` 之外的任何提供商，或自定义 `models.providers.anthropic.baseUrl` 且其主机不是公共 `api.anthropic.com` 端点），OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，以便自定义 Anthropic 兼容代理不会拒绝不支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 `models.providers..headers["anthropic-beta"]`。 + - 对非直连端点上的 `api: "anthropic-messages"`（canonical `anthropic` 以外的任何提供商，或自定义 `models.providers.anthropic.baseUrl` 且其主机不是公开 `api.anthropic.com` 端点），OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，因此自定义 Anthropic 兼容代理不会拒绝不支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 `models.providers..headers["anthropic-beta"]`。 @@ -712,9 +712,9 @@ openclaw models list 另见：[配置](/zh-CN/gateway/configuration) 了解完整配置示例。 -## 相关 +## 相关内容 - [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键 - [模型故障转移](/zh-CN/concepts/model-failover) — 回退链和重试行为 - [Models](/zh-CN/concepts/models) — 模型配置和别名 -- [提供商](/zh-CN/providers) — 按提供商划分的设置指南 +- [提供商](/zh-CN/providers) — 各提供商设置指南 diff --git a/docs/zh-CN/providers/lmstudio.md b/docs/zh-CN/providers/lmstudio.md index 28561ece5..a5647b6f5 100644 --- a/docs/zh-CN/providers/lmstudio.md +++ b/docs/zh-CN/providers/lmstudio.md @@ -5,15 +5,15 @@ read_when: summary: 使用 LM Studio 运行 OpenClaw title: LM Studio x-i18n: - generated_at: "2026-04-27T12:55:45Z" - model: gpt-5.4 + generated_at: "2026-05-02T05:17:38Z" + model: gpt-5.5 provider: openai - source_hash: fe6d1feadf355579b244ab4187a8d3b8bad661a5605aed906eedf361d6fcae3f + source_hash: 3971bc471e5d8b0f142394b7b1897f8fdb2be283082245fbb2cf744d06143292 source_path: providers/lmstudio.md - workflow: 15 + workflow: 16 --- -LM Studio 是一款对用户友好但功能强大的应用，可让你在自己的硬件上运行开放权重模型。它支持运行 llama.cpp（GGUF）或 MLX 模型（Apple Silicon）。提供 GUI 应用包，也提供无头守护进程（`llmster`）。产品和设置文档请参见 [lmstudio.ai](https://lmstudio.ai/)。 +LM Studio 是一款友好且强大的应用，可在你自己的硬件上运行开放权重模型。它让你可以运行 llama.cpp（GGUF）或 MLX 模型（Apple Silicon）。它提供 GUI 软件包或无头守护进程（`llmster`）。产品和设置文档见 [lmstudio.ai](https://lmstudio.ai/)。 ## 快速开始 @@ -25,7 +25,7 @@ curl -fsSL https://lmstudio.ai/install.sh | bash 2. 启动服务器 -请确保你要么启动桌面应用，要么使用以下命令运行守护进程： +确保你已启动桌面应用，或使用以下命令运行守护进程： ```bash lms daemon up @@ -35,17 +35,17 @@ lms daemon up lms server start --port 1234 ``` -如果你使用的是应用，请确保已启用 JIT，以获得更流畅的体验。更多信息请参见 [LM Studio JIT and TTL guide](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict)。 +如果你使用应用，请确保已启用 JIT，以获得流畅体验。请阅读 [LM Studio JIT 和 TTL 指南](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict)了解详情。 -3. 如果启用了 LM Studio 认证，请设置 `LM_API_TOKEN`： +3. 如果已启用 LM Studio 身份验证，请设置 `LM_API_TOKEN`： ```bash export LM_API_TOKEN="your-lm-studio-api-token" ``` -如果禁用了 LM Studio 认证，你可以在交互式 OpenClaw 设置期间将 API 密钥留空。 +如果已禁用 LM Studio 身份验证，你可以在交互式 OpenClaw 设置期间将 API key 留空。 -关于 LM Studio 认证设置的详细信息，请参见 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)。 +有关 LM Studio 身份验证设置详情，请参阅 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)。 4. 运行新手引导并选择 `LM Studio`： @@ -53,7 +53,7 @@ export LM_API_TOKEN="your-lm-studio-api-token" openclaw onboard ``` -5. 在新手引导中，使用 `Default model` 提示来选择你的 LM Studio 模型。 +5. 在新手引导中，使用 `Default model` 提示选择你的 LM Studio 模型。 你也可以稍后设置或更改它： @@ -61,11 +61,11 @@ openclaw onboard 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` 字段，以找到某个模型的精确键名。 +LM Studio 模型键遵循 `author/model-name` 格式（例如 `qwen/qwen3.5-9b`）。OpenClaw 模型引用会添加提供商名称前缀：`lmstudio/qwen/qwen3.5-9b`。你可以运行 `curl http://localhost:1234/api/v1/models` 并查看 `key` 字段，找到模型的确切键。 ## 非交互式新手引导 -当你想通过脚本完成设置（CI、预配、远程引导）时，请使用非交互式新手引导： +当你想通过脚本设置（CI、预配、远程引导）时，请使用非交互式新手引导： ```bash openclaw onboard \ @@ -74,7 +74,7 @@ openclaw onboard \ --auth-choice lmstudio ``` -或者指定基础 URL、模型和可选的 API 密钥： +或者指定基础 URL、模型和可选 API key： ```bash openclaw onboard \ @@ -86,25 +86,25 @@ openclaw onboard \ --custom-model-id qwen/qwen3.5-9b ``` -`--custom-model-id` 接受 LM Studio 返回的模型键（例如 `qwen/qwen3.5-9b`），不包含 `lmstudio/` 提供商前缀。 +`--custom-model-id` 使用 LM Studio 返回的模型键（例如 `qwen/qwen3.5-9b`），不包含 `lmstudio/` 提供商前缀。 -对于启用了认证的 LM Studio 服务器，请传入 `--lmstudio-api-key` 或设置 `LM_API_TOKEN`。 -对于未启用认证的 LM Studio 服务器，请省略该密钥；OpenClaw 会存储一个本地的非秘密标记。 +对于已启用身份验证的 LM Studio 服务器，传入 `--lmstudio-api-key` 或设置 `LM_API_TOKEN`。 +对于未启用身份验证的 LM Studio 服务器，省略该键；OpenClaw 会存储一个本地非密钥标记。 -出于兼容性考虑，`--custom-api-key` 仍受支持，但对于 LM Studio，优先使用 `--lmstudio-api-key`。 +`--custom-api-key` 仍受支持以保持兼容性，但对于 LM Studio，建议使用 `--lmstudio-api-key`。 -这会写入 `models.providers.lmstudio`，并将默认模型设置为 `lmstudio/`。当你提供 API 密钥时，设置流程还会写入 `lmstudio:default` 认证配置文件。 +这会写入 `models.providers.lmstudio`，并将默认模型设置为 `lmstudio/`。当你提供 API key 时，设置还会写入 `lmstudio:default` 身份验证配置文件。 -交互式设置可以提示输入一个可选的首选加载上下文长度，并将其应用到保存进配置中的已发现 LM Studio 模型。 -LM Studio 插件配置会信任已配置的 LM Studio 端点，用于模型请求，包括 loopback、LAN 和 tailnet 主机。你可以通过设置 `models.providers.lmstudio.request.allowPrivateNetwork: false` 来选择退出。 +交互式设置可以提示输入可选的首选加载上下文长度，并将其应用到保存进配置的已发现 LM Studio 模型。 +LM Studio 插件配置会信任已配置的 LM Studio 端点来处理模型请求，包括 loopback、LAN 和 tailnet 主机。你可以通过设置 `models.providers.lmstudio.request.allowPrivateNetwork: false` 选择退出。 ## 配置 -### 流式 usage 兼容性 +### 流式用量兼容性 -LM Studio 与流式 usage 兼容。当它没有发出符合 OpenAI 形态的 `usage` 对象时，OpenClaw 会改为从 llama.cpp 风格的 `timings.prompt_n` / `timings.predicted_n` 元数据中恢复 token 计数。 +LM Studio 兼容流式用量。当它未发出 OpenAI 形态的 `usage` 对象时，OpenClaw 会改为从 llama.cpp 风格的 `timings.prompt_n` / `timings.predicted_n` 元数据恢复 token 计数。 -相同的流式 usage 行为也适用于这些兼容 OpenAI 的本地后端： +相同的流式用量行为适用于这些 OpenAI 兼容的本地后端： - vLLM - SGLang @@ -114,9 +114,9 @@ LM Studio 与流式 usage 兼容。当它没有发出符合 OpenAI 形态的 `us - TabbyAPI - text-generation-webui -### Thinking 兼容性 +### 思考兼容性 -当 LM Studio 的 `/api/v1/models` 发现流程报告模型特定的推理选项时，OpenClaw 会在模型兼容性元数据中保留这些原生值。对于宣称 `allowed_options: ["off", "on"]` 的二元 thinking 模型，OpenClaw 会将禁用 thinking 映射为 `off`，并将启用的 `/think` 级别映射为 `on`，而不会发送仅适用于 OpenAI 的值，例如 `low` 或 `medium`。 +当 LM Studio 的 `/api/v1/models` 设备发现报告模型特定的推理选项时，OpenClaw 会在模型兼容性元数据中保留这些原生值。对于声明 `allowed_options: ["off", "on"]` 的二元思考模型，OpenClaw 会将禁用思考映射为 `off`，并将启用的 `/think` 级别映射为 `on`，而不是发送仅适用于 OpenAI 的值，例如 `low` 或 `medium`。 ### 显式配置 @@ -149,10 +149,10 @@ LM Studio 与流式 usage 兼容。当它没有发出符合 OpenAI 形态的 `us ### 未检测到 LM Studio -请确保 LM Studio 正在运行。如果启用了认证，还要设置 `LM_API_TOKEN`： +确保 LM Studio 正在运行。如果已启用身份验证，也请设置 `LM_API_TOKEN`： ```bash -# 通过桌面应用启动，或无头启动： +# Start via desktop app, or headless: lms server start --port 1234 ``` @@ -162,21 +162,36 @@ lms server start --port 1234 curl http://localhost:1234/api/v1/models ``` -### 认证错误（HTTP 401） +### 身份验证错误（HTTP 401） -如果设置过程报告 HTTP 401，请检查你的 API 密钥： +如果设置报告 HTTP 401，请验证你的 API key： -- 检查 `LM_API_TOKEN` 是否与 LM Studio 中配置的密钥一致。 -- 关于 LM Studio 认证设置的详细信息，请参见 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)。 -- 如果你的服务器不要求认证，请在设置期间将密钥留空。 +- 检查 `LM_API_TOKEN` 是否与 LM Studio 中配置的键一致。 +- 有关 LM Studio 身份验证设置详情，请参阅 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)。 +- 如果你的服务器不需要身份验证，请在设置期间将键留空。 ### 即时模型加载 -LM Studio 支持即时（JIT）模型加载，即模型在首次请求时才加载。请确保你已启用此功能，以避免出现“Model not loaded”错误。 +LM Studio 支持即时（JIT）模型加载，即模型会在首次请求时加载。OpenClaw 默认通过 LM Studio 的原生加载端点预加载模型，这在禁用 JIT 时很有用。若要让 LM Studio 的 JIT、空闲 TTL 和自动驱逐行为负责模型生命周期，请禁用 OpenClaw 的预加载步骤： + +```json5 +{ + models: { + providers: { + lmstudio: { + baseUrl: "http://localhost:1234/v1", + api: "openai-completions", + params: { preload: false }, + models: [{ id: "qwen/qwen3.5-9b" }], + }, + }, + }, +} +``` ### LAN 或 tailnet LM Studio 主机 -请使用 LM Studio 主机的可达地址，保留 `/v1`，并确保该机器上的 LM Studio 绑定到了 loopback 之外的地址： +使用 LM Studio 主机的可达地址，保留 `/v1`，并确保该机器上的 LM Studio 绑定到 loopback 之外的地址： ```json5 { @@ -193,7 +208,7 @@ LM Studio 支持即时（JIT）模型加载，即模型在首次请求时才加 } ``` -与通用的兼容 OpenAI 提供商不同，`lmstudio` 会自动信任其已配置的本地/私有端点，用于受保护的模型请求。像 `localhost` 或 `127.0.0.1` 这样的自定义 loopback 提供商 id 也会被自动信任；对于 LAN、tailnet 或私有 DNS 自定义提供商 id，请显式设置 `models.providers..request.allowPrivateNetwork: true`。 +与通用 OpenAI 兼容提供商不同，`lmstudio` 会自动信任其已配置的本地/私有端点，用于受保护的模型请求。自定义 loopback 提供商 ID（例如 `localhost` 或 `127.0.0.1`）也会自动受信任；对于 LAN、tailnet 或私有 DNS 自定义提供商 ID，请显式设置 `models.providers..request.allowPrivateNetwork: true`。 ## 相关内容 diff --git a/docs/zh-CN/web/tui.md b/docs/zh-CN/web/tui.md index 73521dff5..b24695bb5 100644 --- a/docs/zh-CN/web/tui.md +++ b/docs/zh-CN/web/tui.md @@ -1,16 +1,16 @@ --- read_when: - - 你想要一份适合初学者的 TUI 使用指南 - - 你需要 TUI 功能、命令和快捷键的完整列表 -summary: 终端 UI（TUI）：连接到 Gateway 网关或以嵌入模式在本地运行 -title: TUI + - 你想要一份适合初学者的 TUI 演练 + - 你需要完整的 TUI 功能、命令和快捷键列表 +summary: 终端 UI (TUI)：连接到 Gateway 网关，或在嵌入模式下本地运行 +title: 文本用户界面 x-i18n: - generated_at: "2026-04-27T06:07:36Z" - model: gpt-5.4 + generated_at: "2026-05-02T05:17:42Z" + model: gpt-5.5 provider: openai - source_hash: 5caca4b3f4df02ce1226a8ed0d759023464e5b0752b9cd1b7922b20099d58df1 + source_hash: 5c13268991bf11eece9984f21eb959e7a5fab7071be6dc3a47855b525bfe80d8 source_path: web/tui.md - workflow: 15 + workflow: 16 --- ## 快速开始 @@ -41,7 +41,7 @@ openclaw tui --url ws://: --token ### 本地模式 -无需 Gateway 网关即可运行 TUI： +不使用 Gateway 网关运行 TUI： ```bash openclaw chat @@ -49,63 +49,64 @@ openclaw chat openclaw tui --local ``` -说明： +注意： - `openclaw chat` 和 `openclaw terminal` 是 `openclaw tui --local` 的别名。 -- `--local` 不能与 `--url`、`--token` 或 `--password` 一起使用。 -- 本地模式直接使用嵌入式智能体运行时。大多数本地工具都能工作，但 Gateway 网关专属功能不可用。 +- `--local` 不能与 `--url`、`--token` 或 `--password` 组合使用。 +- 本地模式会直接使用嵌入式智能体运行时。大多数本地工具可以工作，但仅 Gateway 网关可用的功能不可用。 - `openclaw` 和 `openclaw crestodian` 也使用这个 TUI shell，其中 Crestodian 作为本地设置和修复聊天后端。 ## 你会看到什么 -- 页眉：连接 URL、当前智能体、当前会话。 +- 标头：连接 URL、当前智能体、当前会话。 - 聊天日志：用户消息、助手回复、系统通知、工具卡片。 -- 状态行：连接 / 运行状态（connecting、running、streaming、idle、error）。 -- 页脚：连接状态 + 智能体 + 会话 + 模型 + think / fast / verbose / trace / reasoning + token 计数 + deliver。 +- Status 行：连接/运行状态（正在连接、正在运行、流式传输中、空闲、错误）。 +- 页脚：连接状态 + 智能体 + 会话 + 模型 + think/fast/verbose/trace/reasoning + 令牌计数 + deliver。 - 输入区：带自动补全的文本编辑器。 ## 心智模型：智能体 + 会话 -- 智能体是唯一 slug（例如 `main`、`research`）。Gateway 网关会暴露该列表。 +- 智能体是唯一的 slug（例如 `main`、`research`）。Gateway 网关会公开该列表。 - 会话属于当前智能体。 - 会话键以 `agent::` 形式存储。 - 如果你输入 `/session main`，TUI 会将其展开为 `agent::main`。 - - 如果你输入 `/session agent:other:main`，你会显式切换到那个智能体会话。 + - 如果你输入 `/session agent:other:main`，你会显式切换到该智能体会话。 - 会话范围： - `per-sender`（默认）：每个智能体有多个会话。 - `global`：TUI 始终使用 `global` 会话（选择器可能为空）。 - 当前智能体 + 会话始终显示在页脚中。 +- 在没有 `--session` 的情况下启动时，如果该会话仍然存在，Gateway 网关模式 TUI 会为同一 Gateway 网关、智能体和会话范围恢复上次选择的会话。传入 `--session`、`/session`、`/new` 或 `/reset` 仍然是显式操作。 -## 发送 + 投递 +## 发送 + 交付 -- 消息会发送到 Gateway 网关；默认不会投递给 provider。 -- 打开轮次投递： +- 消息会发送到 Gateway 网关；默认关闭向提供商交付。 +- 开启交付： - `/deliver on` - - 或在设置面板中打开 - - 或启动时使用 `openclaw tui --deliver` + - 或 Settings 面板 + - 或使用 `openclaw tui --deliver` 启动 ## 选择器 + 覆盖层 -- 模型选择器：列出可用模型并设置会话覆盖。 -- 智能体选择器：选择不同的智能体。 -- 会话选择器：只显示当前智能体的会话。 -- 设置：切换 deliver、工具输出展开和 thinking 可见性。 +- 模型选择器：列出可用模型并设置会话覆盖项。 +- 智能体选择器：选择其他智能体。 +- 会话选择器：仅显示当前智能体的会话。 +- Settings：切换 deliver、工具输出展开和思考可见性。 ## 键盘快捷键 - Enter：发送消息 -- Esc：中止当前运行 +- Esc：中止活动运行 - Ctrl+C：清空输入（按两次退出） - Ctrl+D：退出 - Ctrl+L：模型选择器 - Ctrl+G：智能体选择器 - Ctrl+P：会话选择器 - Ctrl+O：切换工具输出展开 -- Ctrl+T：切换 thinking 可见性（会重新加载历史） +- Ctrl+T：切换思考可见性（重新加载历史） -## 斜杠命令 +## Slash commands -核心命令： +核心： - `/help` - `/status` @@ -128,35 +129,31 @@ openclaw tui --local 会话生命周期： - `/new` 或 `/reset`（重置会话） -- `/abort`（中止当前运行） +- `/abort`（中止活动运行） - `/settings` - `/exit` 仅本地模式： -- `/auth [provider]` 会在 TUI 内打开 provider 认证 / 登录流程。 +- `/auth [provider]` 会在 TUI 内打开提供商认证/登录流程。 -其他 Gateway 网关斜杠命令（例如 `/context`）会转发到 Gateway 网关，并显示为系统输出。参见[斜杠命令](/zh-CN/tools/slash-commands)。 +其他 Gateway 网关 Slash commands（例如 `/context`）会转发到 Gateway 网关，并显示为系统输出。参见 [Slash commands](/zh-CN/tools/slash-commands)。 ## 本地 shell 命令 -- 在一行前加上 `!` 可在 TUI 主机上运行本地 shell 命令。 -- TUI 会在每个会话中提示一次是否允许本地执行；如果拒绝，本次会话中的 `!` 会保持禁用。 -- 命令会在 TUI 工作目录中的一个全新、非交互式 shell 中运行（不会持久保留 `cd` / env）。 -- 本地 shell 命令会在其环境变量中接收 `OPENCLAW_SHELL=tui-local`。 -- 单独一个 `!` 会作为普通消息发送；前导空格不会触发本地 exec。 +- 在一行前加上 `!`，即可在 TUI 主机上运行本地 shell 命令。 +- TUI 每个会话会提示一次是否允许本地执行；拒绝后，该会话会保持禁用 `!`。 +- 命令会在 TUI 工作目录中的全新非交互式 shell 中运行（没有持久化的 `cd`/env）。 +- 本地 shell 命令会在其环境中收到 `OPENCLAW_SHELL=tui-local`。 +- 单独的 `!` 会作为普通消息发送；前导空格不会触发本地执行。 ## 从本地 TUI 修复配置 -当当前配置已经通过校验，并且你希望让 -嵌入式智能体在同一台机器上检查它、与文档进行比对， -并在不依赖运行中的 Gateway 网关的情况下帮助修复漂移时，请使用本地模式。 +当当前配置已经验证通过，并且你希望嵌入式智能体在同一台机器上检查它、与文档对比，并在不依赖正在运行的 Gateway 网关的情况下帮助修复漂移时，请使用本地模式。 -如果 `openclaw config validate` 已经失败，请先从 `openclaw configure` -或 `openclaw doctor --fix` 开始。`openclaw chat` 不会绕过无效配置 -保护。 +如果 `openclaw config validate` 已经失败，请先从 `openclaw configure` 或 `openclaw doctor --fix` 开始。`openclaw chat` 不会绕过无效配置保护。 -典型流程： +典型循环： 1. 启动本地模式： @@ -170,7 +167,7 @@ openclaw chat Compare my gateway auth config with the docs and suggest the smallest fix. ``` -3. 使用本地 shell 命令获取精确证据并进行验证： +3. 使用本地 shell 命令获取准确证据并进行验证： ```text !openclaw config file @@ -179,73 +176,73 @@ Compare my gateway auth config with the docs and suggest the smallest fix. !openclaw doctor ``` -4. 使用 `openclaw config set` 或 `openclaw configure` 进行小范围修改，然后重新运行 `!openclaw config validate`。 -5. 如果 Doctor 建议进行自动迁移或修复，请先审查，再运行 `!openclaw doctor --fix`。 +4. 使用 `openclaw config set` 或 `openclaw configure` 应用范围较小的更改，然后重新运行 `!openclaw config validate`。 +5. 如果 Doctor 建议自动迁移或修复，请先审查它，再运行 `!openclaw doctor --fix`。 提示： - 优先使用 `openclaw config set` 或 `openclaw configure`，而不是手动编辑 `openclaw.json`。 -- `openclaw docs ""` 会在同一台机器上搜索实时文档索引。 -- 当你需要结构化的 schema 和 SecretRef / 可解析性错误时，`openclaw config validate --json` 很有用。 +- `openclaw docs ""` 会从同一台机器搜索实时文档索引。 +- 当你需要结构化 schema 和 SecretRef/可解析性错误时，`openclaw config validate --json` 很有用。 ## 工具输出 -- 工具调用会显示为带参数 + 结果的卡片。 -- Ctrl+O 可在折叠 / 展开视图之间切换。 -- 工具运行时，部分更新会流式进入同一张卡片。 +- 工具调用会显示为包含 args + results 的卡片。 +- Ctrl+O 会在折叠/展开视图之间切换。 +- 工具运行时，部分更新会流式写入同一张卡片。 ## 终端颜色 -- TUI 会让助手正文文本保持使用你终端的默认前景色，因此深色和浅色终端都能保持可读性。 -- 如果你的终端使用浅色背景且自动检测有误，请在启动 `openclaw tui` 前设置 `OPENCLAW_THEME=light`。 -- 若要强制使用原始深色调色板，请设置 `OPENCLAW_THEME=dark`。 +- TUI 会将助手正文文本保持为你的终端默认前景色，因此深色和浅色终端都能保持可读。 +- 如果你的终端使用浅色背景且自动检测错误，请在启动 `openclaw tui` 前设置 `OPENCLAW_THEME=light`。 +- 如果要改为强制使用原始深色调色板，请设置 `OPENCLAW_THEME=dark`。 -## 历史记录 + 流式传输 +## 历史 + 流式传输 -- 连接时，TUI 会加载最新历史记录（默认 200 条消息）。 +- 连接时，TUI 会加载最新历史（默认 200 条消息）。 - 流式响应会原地更新，直到最终完成。 -- TUI 还会监听智能体工具事件，以显示更丰富的工具卡片。 +- TUI 还会监听智能体工具事件，以提供更丰富的工具卡片。 ## 连接详情 -- TUI 会以 `mode: "tui"` 的身份向 Gateway 网关注册。 -- 重连时会显示系统消息；事件缺口也会显示在日志中。 +- TUI 会以 `mode: "tui"` 向 Gateway 网关注册。 +- 重新连接会显示一条系统消息；事件缺口会在日志中呈现。 ## 选项 - `--local`：针对本地嵌入式智能体运行时运行 -- `--url `：Gateway 网关 WebSocket URL（默认为配置中的值，或 `ws://127.0.0.1:`） -- `--token `：Gateway 网关 token（如果需要） +- `--url `：Gateway 网关 WebSocket URL（默认为配置或 `ws://127.0.0.1:`） +- `--token `：Gateway 网关令牌（如果需要） - `--password `：Gateway 网关密码（如果需要） -- `--session `：会话键（默认：`main`，若范围为 global 则为 `global`） -- `--deliver`：将助手回复投递给 provider（默认关闭） -- `--thinking `：覆盖发送时的 thinking 级别 -- `--message `：连接后发送一条初始消息 -- `--timeout-ms `：智能体超时时间（毫秒，默认取自 `agents.defaults.timeoutSeconds`） -- `--history-limit `：要加载的历史记录条数（默认 `200`） +- `--session `：会话键（默认：`main`，当范围为 global 时为 `global`） +- `--deliver`：将助手回复交付给提供商（默认关闭） +- `--thinking `：覆盖发送时的思考级别 +- `--message `：连接后发送初始消息 +- `--timeout-ms `：智能体超时时间，单位 ms（默认为 `agents.defaults.timeoutSeconds`） +- `--history-limit `：要加载的历史条目数（默认 `200`） -设置 `--url` 时，TUI 不会回退到配置或环境变量凭证。请显式传入 `--token` 或 `--password`。缺少显式凭证会报错。在本地模式中，不要传入 `--url`、`--token` 或 `--password`。 +当你设置 `--url` 时，TUI 不会回退到配置或环境凭据。请显式传入 `--token` 或 `--password`。缺少显式凭据会报错。在本地模式下，不要传入 `--url`、`--token` 或 `--password`。 ## 故障排除 发送消息后没有输出： -- 在 TUI 中运行 `/status`，确认 Gateway 网关已连接且处于 idle / busy 状态。 +- 在 TUI 中运行 `/status`，确认 Gateway 网关已连接且处于空闲/忙碌状态。 - 检查 Gateway 网关日志：`openclaw logs --follow`。 - 确认智能体可以运行：`openclaw status` 和 `openclaw models status`。 -- 如果你希望消息出现在聊天渠道中，请启用投递（`/deliver on` 或 `--deliver`）。 +- 如果你期望消息出现在聊天渠道中，请启用交付（`/deliver on` 或 `--deliver`）。 ## 连接故障排除 -- `disconnected`：确认 Gateway 网关正在运行，并且你的 `--url/--token/--password` 正确。 +- `disconnected`：确保 Gateway 网关正在运行，并且你的 `--url/--token/--password` 正确。 - 选择器中没有智能体：检查 `openclaw agents list` 和你的路由配置。 -- 会话选择器为空：你可能处于 global 范围，或者还没有任何会话。 +- 会话选择器为空：你可能处于 global 范围，或者还没有会话。 -## 相关内容 +## 相关 - [Control UI](/zh-CN/web/control-ui) — 基于 Web 的控制界面 -- [Config](/zh-CN/cli/config) — 检查、验证并编辑 `openclaw.json` +- [配置](/zh-CN/cli/config) — 检查、验证并编辑 `openclaw.json` - [Doctor](/zh-CN/cli/doctor) — 引导式修复和迁移检查 - [CLI 参考](/zh-CN/cli) — 完整 CLI 命令参考 diff --git a/docs/zh-CN/web/webchat.md b/docs/zh-CN/web/webchat.md index 411014430..198f5a6ec 100644 --- a/docs/zh-CN/web/webchat.md +++ b/docs/zh-CN/web/webchat.md @@ -1,62 +1,71 @@ --- read_when: - - 调试或配置 WebChat 访问 -summary: local loopback WebChat 静态主机和 Gateway 网关 WS 用法，用于聊天 UI + - 调试或配置 WebChat 访问权限 +summary: 用于聊天 UI 的 Loopback WebChat 静态主机和 Gateway 网关 WS 用法 title: WebChat x-i18n: - generated_at: "2026-04-27T19:49:36Z" - model: gpt-5.4 + generated_at: "2026-05-02T05:17:37Z" + model: gpt-5.5 provider: openai - source_hash: d8a4fef0aab37ca82bff249c6b31eb65475f12c16dfb9b86ddd62c1a938a34f3 + source_hash: fe6d3cb30ed18d651b0d0ca8fd188b47c5f1d186410ee340deb79315f194ed8d source_path: web/webchat.md - workflow: 15 + workflow: 16 --- Status：macOS/iOS SwiftUI 聊天 UI 直接与 Gateway 网关 WebSocket 通信。 ## 它是什么 -- 一个适用于网关的原生聊天 UI（没有嵌入式浏览器，也没有本地静态服务器）。 +- 用于 Gateway 网关的原生聊天 UI（没有嵌入式浏览器，也没有本地静态服务器）。 - 使用与其他渠道相同的会话和路由规则。 - 确定性路由：回复始终返回到 WebChat。 ## 快速开始 -1. 启动网关。 -2. 打开 WebChat UI（macOS/iOS 应用）或 Control UI 聊天选项卡。 -3. 确保已配置有效的网关凭证路径（默认使用 shared-secret， +1. 启动 Gateway 网关。 +2. 打开 WebChat UI（macOS/iOS 应用）或 Control UI 聊天标签页。 +3. 确保已配置有效的 Gateway 网关身份验证路径（默认使用共享密钥， 即使在 loopback 上也是如此）。 -## 工作原理（行为） +## 工作方式（行为） - UI 连接到 Gateway 网关 WebSocket，并使用 `chat.history`、`chat.send` 和 `chat.inject`。 -- `chat.history` 为了稳定性设置了边界：Gateway 网关可能会截断长文本字段、省略较重的元数据，并将超大条目替换为 `[chat.history omitted: message too large]`。 -- 对于现代追加式会话文件，`chat.history` 会遵循当前活动的转录分支，因此已放弃的重写分支和已被替代的提示副本不会在 WebChat 中渲染。 -- 在为新的 `chat.send` 运行 id 生成之前，Control UI 会对同一会话、消息和附件的重复进行中的提交进行合并；Gateway 网关仍会对重复使用相同幂等键的请求进行去重。 -- `chat.history` 也会进行显示规范化：仅运行时的 OpenClaw 上下文、入站信封包装器、内联投递指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 负载（包括 `...`、`...`、`...`、`...` 以及被截断的工具调用块），以及泄漏的 ASCII/全角模型控制标记，都会从可见文本中移除；而且，若某条 assistant 条目的全部可见文本仅为完全匹配的静默标记 `NO_REPLY` / `no_reply`，则该条目会被省略。 -- 带有推理标记的回复负载（`isReasoning: true`）会从 WebChat 助手内容、转录回放文本和音频内容块中排除，因此仅思考用的负载不会显示为可见的助手消息，也不会成为可播放音频。 -- `chat.inject` 会将一条助手备注直接追加到转录中，并广播到 UI（不会触发智能体运行）。 -- 已中止的运行可以在 UI 中保留部分助手输出可见。 -- 当存在缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史中，并使用中止元数据标记这些条目。 -- 历史记录始终从网关获取（不会监视本地文件）。 -- 如果网关不可达，WebChat 为只读。 +- 为了稳定性，`chat.history` 是有界的：Gateway 网关可能会截断长文本字段、省略体量较大的元数据，并用 `[chat.history omitted: message too large]` 替换过大的条目。 +- 对于现代仅追加会话文件，`chat.history` 会跟随活动转录分支，因此已放弃的重写分支和被取代的提示词副本不会在 WebChat 中渲染。 +- Control UI 会记住 `chat.history` 返回的后端 Gateway 网关 `sessionId`，并在后续 `chat.send` 调用中包含它，因此重新连接和页面刷新会继续同一个已存储对话，除非用户启动或重置会话。 +- Control UI 会在生成新的 `chat.send` 运行 id 之前，合并同一会话、消息和附件的重复进行中提交；Gateway 网关仍会对复用同一幂等键的重复请求进行去重。 +- `chat.history` 也会进行显示归一化：仅运行时的 OpenClaw 上下文、 + 入站信封包装、内联投递指令标签 + 例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`、纯文本工具调用 XML + 载荷（包括 `...`、 + `...`、`...`、 + `...` 以及被截断的工具调用块），以及 + 泄漏的 ASCII/全角模型控制令牌都会从可见文本中剥离， + 并且如果助手条目的全部可见文本只是精确的静默令牌 + `NO_REPLY` / `no_reply`，该条目会被省略。 +- 标记为推理的回复载荷（`isReasoning: true`）会从 WebChat 助手内容、转录回放文本和音频内容块中排除，因此仅思考载荷不会显示为可见助手消息或可播放音频。 +- `chat.inject` 会将助手备注直接追加到转录中，并广播到 UI（不运行智能体）。 +- 已中止的运行可以让部分助手输出在 UI 中保持可见。 +- 当存在缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史中，并用中止元数据标记这些条目。 +- 历史始终从 Gateway 网关获取（不进行本地文件监听）。 +- 如果 Gateway 网关无法访问，WebChat 为只读模式。 ## Control UI 智能体工具面板 -- Control UI 的 `/agents` 工具面板有两个独立视图： - - **Available Right Now** 使用 `tools.effective(sessionKey=...)`，显示当前 +- Control UI `/agents` 工具面板有两个独立视图： + - **当前可用** 使用 `tools.effective(sessionKey=...)`，并显示当前 会话在运行时实际可用的内容，包括核心、插件和渠道拥有的工具。 - - **Tool Configuration** 使用 `tools.catalog`，并始终聚焦于配置文件、覆盖项和 + - **工具配置** 使用 `tools.catalog`，并专注于配置文件、覆盖项和 目录语义。 -- 运行时可用性以会话为作用域。在同一个智能体上切换会话，可能会改变 - **Available Right Now** 列表。 -- 配置编辑器并不意味着运行时可用性；实际访问权限仍遵循策略优先级 - （`allow`/`deny`、按智能体以及 provider/渠道覆盖）。 +- 运行时可用性按会话限定。在同一智能体上切换会话可能会改变 + **当前可用** 列表。 +- 配置编辑器并不意味着运行时可用；有效访问仍遵循策略 + 优先级（`allow`/`deny`，以及按智能体和提供商/渠道设置的覆盖项）。 ## 远程使用 -- 远程模式通过 SSH/Tailscale 隧道传输网关 WebSocket。 -- 你不需要运行单独的 WebChat 服务器。 +- 远程模式通过 SSH/Tailscale 隧道传输 Gateway 网关 WebSocket。 +- 你无需运行单独的 WebChat 服务器。 ## 配置参考（WebChat） @@ -64,20 +73,20 @@ Status：macOS/iOS SwiftUI 聊天 UI 直接与 Gateway 网关 WebSocket 通信 WebChat 选项： -- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 响应中文本字段的最大字符数。当转录条目超过此限制时，Gateway 网关会截断长文本字段，并且可能用占位符替换超大的消息。客户端也可以按请求发送 `maxChars`，以便仅对单次 `chat.history` 调用覆盖此默认值。 +- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 响应中文本字段的最大字符数。当转录条目超过此限制时，Gateway 网关会截断长文本字段，并可能用占位符替换过大的消息。客户端也可以发送按请求设置的 `maxChars`，以便仅为单次 `chat.history` 调用覆盖此默认值。 相关全局选项： - `gateway.port`、`gateway.bind`：WebSocket 主机/端口。 - `gateway.auth.mode`、`gateway.auth.token`、`gateway.auth.password`： - shared-secret WebSocket 凭证。 -- `gateway.auth.allowTailscale`：启用后，浏览器中的 Control UI 聊天选项卡可以使用 Tailscale + 共享密钥 WebSocket 身份验证。 +- `gateway.auth.allowTailscale`：启用后，浏览器 Control UI 聊天标签页可以使用 Tailscale Serve 身份标头。 -- `gateway.auth.mode: "trusted-proxy"`：为位于具备身份感知能力的**非 loopback** 代理源之后的浏览器客户端提供反向代理凭证（参见[Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。 -- `gateway.remote.url`、`gateway.remote.token`、`gateway.remote.password`：远程网关目标。 +- `gateway.auth.mode: "trusted-proxy"`：面向位于具备身份感知能力的**非 loopback**代理源后方的浏览器客户端的反向代理身份验证（参见 [可信代理身份验证](/zh-CN/gateway/trusted-proxy-auth)）。 +- `gateway.remote.url`、`gateway.remote.token`、`gateway.remote.password`：远程 Gateway 网关目标。 - `session.*`：会话存储和主键默认值。 -## 相关内容 +## 相关 - [Control UI](/zh-CN/web/control-ui) -- [Dashboard](/zh-CN/web/dashboard) +- [仪表板](/zh-CN/web/dashboard)