diff --git a/docs/zh-CN/cli/onboard.md b/docs/zh-CN/cli/onboard.md index 47a086985..db8d75b21 100644 --- a/docs/zh-CN/cli/onboard.md +++ b/docs/zh-CN/cli/onboard.md @@ -1,13 +1,13 @@ --- read_when: - 你想通过引导式设置来配置 Gateway 网关、工作区、凭证、渠道和 Skills。 -summary: '`openclaw onboard` 的 CLI 参考（交互式新手引导）' +summary: '`openclaw onboard`（交互式新手引导）的 CLI 参考' title: 新手引导 x-i18n: - generated_at: "2026-04-25T08:03:59Z" + generated_at: "2026-04-27T04:33:50Z" model: gpt-5.4 provider: openai - source_hash: 234c308ea554195df1bd880bda7e30770e926af059740458d056e4a909aaeb07 + source_hash: 2fd532143ae8d9ba5b7abd297858a13c22eeeb995891f2c33ef9b8708d3438ec source_path: cli/onboard.md workflow: 15 --- @@ -18,11 +18,23 @@ x-i18n: ## 相关指南 -- CLI 新手引导中心：[设置向导（CLI）](/zh-CN/start/wizard) -- 新手引导概览：[新手引导概览](/zh-CN/start/onboarding-overview) -- CLI 新手引导参考：[CLI 设置参考](/zh-CN/start/wizard-cli-reference) -- CLI 自动化：[CLI 自动化](/zh-CN/start/wizard-cli-automation) -- macOS 新手引导：[新手引导（macOS 应用）](/zh-CN/start/onboarding) + + + 交互式 CLI 流程的演练说明。 + + + OpenClaw 新手引导的整体组成方式。 + + + 输出、内部机制以及各步骤行为。 + + + 非交互式标志和脚本化设置。 + + + macOS 菜单栏应用的新手引导流程。 + + ## 示例 @@ -36,11 +48,11 @@ openclaw onboard --mode remote --remote-url wss://gateway-host:18789 ``` `--modern` 会启动 Crestodian 对话式新手引导预览。 -如果不使用 `--modern`，`openclaw onboard` 会继续使用经典新手引导流程。 +如果不使用 `--modern`，`openclaw onboard` 将保持经典新手引导流程。 对于明文私有网络 `ws://` 目标（仅限受信任网络），请在新手引导进程环境中设置 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`。 -这个客户端传输层的紧急放行选项没有对应的 `openclaw.json` 配置项。 +这种客户端传输层紧急开关没有对应的 `openclaw.json` 配置项。 非交互式自定义提供商： @@ -57,7 +69,7 @@ openclaw onboard --non-interactive \ 在非交互式模式下，`--custom-api-key` 是可选的。 如果省略，新手引导会检查 `CUSTOM_API_KEY`。 -LM Studio 在非交互式模式下也支持提供商专用的密钥标志： +LM Studio 在非交互式模式下也支持提供商专用密钥标志： ```bash openclaw onboard --non-interactive \ @@ -79,8 +91,8 @@ openclaw onboard --non-interactive \ ``` `--custom-base-url` 默认值为 `http://127.0.0.1:11434`。 -`--custom-model-id` 是可选的；如果省略，新手引导会使用 Ollama 建议的默认值。 -像 `kimi-k2.5:cloud` 这样的云端模型 ID 在这里也可用。 +`--custom-model-id` 是可选项；如果省略，新手引导会使用 Ollama 建议的默认值。 +诸如 `kimi-k2.5:cloud` 之类的云端模型 ID 在这里也可用。 将提供商密钥存储为引用而不是明文： @@ -91,26 +103,26 @@ openclaw onboard --non-interactive \ --accept-risk ``` -使用 `--secret-input-mode ref` 时，新手引导会写入由环境变量支持的引用，而不是明文密钥值。 +使用 `--secret-input-mode ref` 时，新手引导会写入基于环境变量的引用，而不是明文密钥值。 对于基于 auth-profile 的提供商，这会写入 `keyRef` 条目；对于自定义提供商，这会将 `models.providers..apiKey` 写为环境变量引用（例如 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`）。 非交互式 `ref` 模式约定： - 在新手引导进程环境中设置提供商环境变量（例如 `OPENAI_API_KEY`）。 -- 不要传递内联密钥标志（例如 `--openai-api-key`），除非该环境变量也已设置。 -- 如果传递了内联密钥标志但未设置所需环境变量，新手引导会快速失败并给出指导。 +- 不要传递内联密钥标志（例如 `--openai-api-key`），除非同时设置了该环境变量。 +- 如果传递了内联密钥标志但缺少所需环境变量，新手引导会快速失败并提供指导。 非交互式模式下的 Gateway 网关令牌选项： -- `--gateway-auth token --gateway-token ` 会存储明文令牌。 -- `--gateway-auth token --gateway-token-ref-env ` 会将 `gateway.auth.token` 存储为环境变量 `SecretRef`。 +- `--gateway-auth token --gateway-token ` 存储明文令牌。 +- `--gateway-auth token --gateway-token-ref-env ` 将 `gateway.auth.token` 存储为环境变量 SecretRef。 - `--gateway-token` 和 `--gateway-token-ref-env` 互斥。 - `--gateway-token-ref-env` 要求在新手引导进程环境中存在非空环境变量。 -- 使用 `--install-daemon` 时，如果令牌认证需要令牌，由 `SecretRef` 管理的 Gateway 网关令牌会被验证，但不会以已解析的明文形式持久化到 supervisor 服务环境元数据中。 -- 使用 `--install-daemon` 时，如果令牌模式需要令牌，而配置的令牌 `SecretRef` 无法解析，新手引导会以关闭失败方式终止，并提供修复指导。 -- 使用 `--install-daemon` 时，如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，新手引导会阻止安装，直到显式设置模式。 -- 本地新手引导会将 `gateway.mode="local"` 写入配置。如果后续配置文件缺少 `gateway.mode`，应将其视为配置损坏或手动编辑不完整，而不是有效的本地模式快捷写法。 -- `--allow-unconfigured` 是单独的 Gateway 网关运行时紧急放行选项。它并不表示新手引导可以省略 `gateway.mode`。 +- 使用 `--install-daemon` 时，如果令牌认证需要令牌，由 SecretRef 管理的 Gateway 网关令牌会被验证，但不会以已解析的明文形式持久化到 supervisor 服务环境元数据中。 +- 使用 `--install-daemon` 时，如果令牌模式需要令牌且已配置的令牌 SecretRef 无法解析，新手引导会以封闭失败方式终止，并提供修复指引。 +- 使用 `--install-daemon` 时，如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，而 `gateway.auth.mode` 未设置，新手引导会阻止安装，直到显式设置 mode。 +- 本地新手引导会将 `gateway.mode="local"` 写入配置中。如果后续配置文件缺少 `gateway.mode`，应将其视为配置损坏或不完整的手动编辑，而不是有效的本地模式快捷方式。 +- `--allow-unconfigured` 是单独的 Gateway 网关运行时紧急开关。它并不表示新手引导可以省略 `gateway.mode`。 示例： @@ -126,25 +138,26 @@ openclaw onboard --non-interactive \ 非交互式本地 Gateway 网关健康检查： -- 除非你传递 `--skip-health`，否则新手引导会等待本地 Gateway 网关可达后才成功退出。 -- `--install-daemon` 会先启动受管 Gateway 网关安装路径。如果不使用它，你必须已经有一个正在运行的本地 Gateway 网关，例如 `openclaw gateway run`。 -- 如果你只想在自动化中写入配置 / 工作区 / bootstrap，请使用 `--skip-health`。 -- 如果你自己管理工作区文件，请传递 `--skip-bootstrap` 以设置 `agents.defaults.skipBootstrap: true`，并跳过创建 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 和 `BOOTSTRAP.md`。 -- 在原生 Windows 上，`--install-daemon` 会先尝试 “计划任务”，如果任务创建被拒绝，则回退到按用户的启动文件夹登录项。 +- 除非你传递 `--skip-health`，否则新手引导会等待可访问的本地 Gateway 网关，然后才会成功退出。 +- `--install-daemon` 会先启动受管 Gateway 网关安装路径。如果不使用它，你必须已经运行本地 Gateway 网关，例如 `openclaw gateway run`。 +- 如果你在自动化中只想写入配置 / 工作区 / bootstrap，请使用 `--skip-health`。 +- 如果你自行管理工作区文件，请传递 `--skip-bootstrap` 以设置 `agents.defaults.skipBootstrap: true`，并跳过创建 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 和 `BOOTSTRAP.md`。 +- 在原生 Windows 上，`--install-daemon` 会先尝试 Scheduled Tasks；如果任务创建被拒绝，则回退到按用户划分的 Startup 文件夹登录项。 -带引用模式的交互式新手引导行为： +使用引用模式时的交互式新手引导行为： -- 出现提示时，选择 **Use secret reference**。 +- 出现提示时，选择 **使用 SecretRef**。 - 然后选择以下之一： - - Environment variable - - Configured secret provider (`file` 或 `exec`) -- 在保存引用之前，新手引导会执行快速预检验证。 + - 环境变量 + - 已配置的 secret provider（`file` 或 `exec`） +- 新手引导会在保存引用前执行快速预检验证。 - 如果验证失败，新手引导会显示错误并允许你重试。 -非交互式 Z.AI 端点选择： +### 非交互式 Z.AI 端点选择 -注意：`--auth-choice zai-api-key` 现在会自动为你的密钥检测最佳 Z.AI 端点（优先使用通用 API 和 `zai/glm-5.1`）。 -如果你明确想使用 GLM Coding Plan 端点，请选择 `zai-coding-global` 或 `zai-coding-cn`。 + +`--auth-choice zai-api-key` 会自动检测最适合你的密钥的 Z.AI 端点（优先使用通用 API 和 `zai/glm-5.1`）。如果你明确想使用 GLM Coding Plan 端点，请选择 `zai-coding-global` 或 `zai-coding-cn`。 + ```bash # 无提示端点选择 @@ -166,18 +179,30 @@ openclaw onboard --non-interactive \ --mistral-api-key "$MISTRAL_API_KEY" ``` -流程说明： +## 流程说明 -- `quickstart`：最少提示，自动生成 Gateway 网关令牌。 -- `manual`：针对端口 / 绑定 / 认证提供完整提示（`advanced` 的别名）。 -- 当认证选项暗示首选提供商时，新手引导会将默认模型和 allowlist 选择器预先筛选到该提供商。对于 Volcengine 和 BytePlus（国际版），这也会匹配 coding-plan 变体（`volcengine-plan/*`、`byteplus-plan/*`）。 -- 如果首选提供商筛选后尚无已加载模型，新手引导会回退到未筛选的目录，而不是让选择器保持为空。 -- 在 web-search 步骤中，某些提供商可能会触发提供商专用的后续提示： - - **Grok** 可以提供可选的 `x_search` 设置，使用相同的 `XAI_API_KEY` 和一个 `x_search` 模型选择。 - - **Kimi** 可能会询问 Moonshot API 区域（`api.moonshot.ai` 或 `api.moonshot.cn`）以及默认的 Kimi web-search 模型。 -- 本地新手引导私信作用域行为：[CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals)。 -- 最快开始首次聊天：`openclaw dashboard`（Control UI，无需设置渠道）。 -- 自定义提供商：连接任何兼容 OpenAI 或 Anthropic 的端点，包括未列出的托管提供商。使用 Unknown 进行自动检测。 + + + - `quickstart`：最少提示，自动生成 Gateway 网关令牌。 + - `manual`：完整提示，包括端口、绑定和认证（`advanced` 的别名）。 + + + 当某个认证选择暗示首选提供商时，新手引导会将默认模型和 allowlist 选择器预筛选为该提供商。对于 Volcengine 和 BytePlus（国际版），这也会匹配 coding-plan 变体（`volcengine-plan/*`、`byteplus-plan/*`）。 + + 如果首选提供商筛选后仍没有任何已加载模型，新手引导会回退到未筛选的目录，而不是让选择器保持为空。 + + + 某些 Web 搜索提供商会触发提供商专用的后续提示： + + - **Grok** 可以提供可选的 `x_search` 设置，使用同一个 `XAI_API_KEY` 和一个 `x_search` 模型选择。 + - **Kimi** 可能会询问 Moonshot API 区域（`api.moonshot.ai` 与 `api.moonshot.cn`）以及默认的 Kimi Web 搜索模型。 + + + - 本地新手引导私信作用域行为：[CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals)。 + - 最快开始首次聊天：`openclaw dashboard`（Control UI，无需渠道设置）。 + - 自定义提供商：连接任何兼容 OpenAI 或 Anthropic 的端点，包括未列出的托管提供商。使用 Unknown 可自动检测。 + + ## 常见后续命令 @@ -187,5 +212,5 @@ openclaw agents add ``` -`--json` 并不表示非交互式模式。用于脚本时，请使用 `--non-interactive`。 +`--json` 并不意味着非交互式模式。脚本请使用 `--non-interactive`。 diff --git a/docs/zh-CN/cli/sandbox.md b/docs/zh-CN/cli/sandbox.md index 70d031dc7..311341a2f 100644 --- a/docs/zh-CN/cli/sandbox.md +++ b/docs/zh-CN/cli/sandbox.md @@ -4,37 +4,37 @@ status: active summary: 管理沙箱运行时并检查生效的沙箱策略 title: 沙箱 CLI x-i18n: - generated_at: "2026-04-24T03:38:27Z" + generated_at: "2026-04-27T04:33:47Z" model: gpt-5.4 provider: openai - source_hash: 4f2b5835968faac0a8243fd6eadfcecb51b211fe7b346454e215312b1b6d5e65 + source_hash: 65520040611ccf0cfc28b28f0caf2ed1c7d3b32de06eec7884131042bba4a01e source_path: cli/sandbox.md workflow: 15 --- -管理用于隔离智能体执行的沙箱运行时。 +为隔离的智能体执行管理沙箱运行时。 -## 概览 +## 概述 -OpenClaw 可以在隔离的沙箱运行时中运行智能体，以提升安全性。`sandbox` 命令可帮助你在更新或配置变更后检查并重建这些运行时。 +OpenClaw 可以让智能体在隔离的沙箱运行时中运行，以提升安全性。`sandbox` 命令可帮助你在更新或配置变更后检查并重新创建这些运行时。 -目前通常包括： +目前，这通常指的是： - Docker 沙箱容器 - 当 `agents.defaults.sandbox.backend = "ssh"` 时的 SSH 沙箱运行时 - 当 `agents.defaults.sandbox.backend = "openshell"` 时的 OpenShell 沙箱运行时 -对于 `ssh` 和 OpenShell `remote`，重建比 Docker 更重要： +对于 `ssh` 和 OpenShell `remote`，重新创建比 Docker 更重要： -- 初次初始化后，远程工作区是规范副本 -- `openclaw sandbox recreate` 会删除所选范围的该规范远程工作区 -- 下次使用时，会根据当前本地工作区重新初始化 +- 远程工作区在初次种子复制后就是权威副本 +- `openclaw sandbox recreate` 会删除所选作用域的这个权威远程工作区 +- 下次使用时会从当前本地工作区重新进行种子复制 ## 命令 ### `openclaw sandbox explain` -检查**生效的**沙箱 mode/scope/workspace access、沙箱工具策略和提权门控（包含修复用的配置键路径）。 +检查**生效的**沙箱模式/作用域/工作区访问、沙箱工具策略以及提权门控（附带修复配置键路径）。 ```bash openclaw sandbox explain @@ -58,31 +58,33 @@ openclaw sandbox list --json # JSON 输出 - 运行时名称和状态 - 后端（`docker`、`openshell` 等） - 配置标签，以及它是否与当前配置匹配 -- 存在时长（自创建以来的时间） -- 空闲时长（自上次使用以来的时间） +- 存续时间（自创建以来的时间） +- 空闲时间（自上次使用以来的时间） - 关联的会话/智能体 ### `openclaw sandbox recreate` -移除沙箱运行时，以便使用更新后的配置强制重新创建。 +移除沙箱运行时，以强制按更新后的配置重新创建。 ```bash -openclaw sandbox recreate --all # 重建所有容器 +openclaw sandbox recreate --all # 重新创建所有容器 openclaw sandbox recreate --session main # 指定会话 openclaw sandbox recreate --agent mybot # 指定智能体 -openclaw sandbox recreate --browser # 仅重建浏览器容器 +openclaw sandbox recreate --browser # 仅重新创建浏览器容器 openclaw sandbox recreate --all --force # 跳过确认 ``` **选项：** -- `--all`：重建所有沙箱容器 -- `--session `：重建指定会话对应的容器 -- `--agent `：重建指定智能体的容器 -- `--browser`：仅重建浏览器容器 +- `--all`：重新创建所有沙箱容器 +- `--session `：为指定会话重新创建容器 +- `--agent `：为指定智能体重新创建容器 +- `--browser`：仅重新创建浏览器容器 - `--force`：跳过确认提示 -**重要：** 当智能体下次被使用时，运行时会自动重新创建。 + +当智能体下次被使用时，运行时会自动重新创建。 + ## 使用场景 @@ -94,25 +96,25 @@ docker pull openclaw-sandbox:latest docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim # 更新配置以使用新镜像 -# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image) +# 编辑配置：agents.defaults.sandbox.docker.image（或 agents.list[].sandbox.docker.image） -# 重建容器 +# 重新创建容器 openclaw sandbox recreate --all ``` ### 更改沙箱配置后 ```bash -# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*) +# 编辑配置：agents.defaults.sandbox.*（或 agents.list[].sandbox.*） -# 重建以应用新配置 +# 重新创建以应用新配置 openclaw sandbox recreate --all ``` ### 更改 SSH 目标或 SSH 认证材料后 ```bash -# Edit config: +# 编辑配置： # - agents.defaults.sandbox.backend # - agents.defaults.sandbox.ssh.target # - agents.defaults.sandbox.ssh.workspaceRoot @@ -122,13 +124,13 @@ openclaw sandbox recreate --all openclaw sandbox recreate --all ``` -对于核心 `ssh` 后端，重建会删除 SSH 目标上按范围划分的远程工作区根目录。 -下一次运行时，会根据本地工作区重新初始化。 +对于核心 `ssh` 后端，重新创建会删除 SSH 目标上按作用域划分的远程工作区根目录。 +下次运行时会从本地工作区重新进行种子复制。 ### 更改 OpenShell 来源、策略或模式后 ```bash -# Edit config: +# 编辑配置： # - agents.defaults.sandbox.backend # - plugins.entries.openshell.config.from # - plugins.entries.openshell.config.mode @@ -137,40 +139,41 @@ openclaw sandbox recreate --all openclaw sandbox recreate --all ``` -对于 OpenShell `remote` 模式，重建会删除该范围的规范远程工作区。 -下一次运行时，会根据本地工作区重新初始化。 +对于 OpenShell `remote` 模式，重新创建会删除该作用域的权威远程工作区。 +下次运行时会从本地工作区重新进行种子复制。 ### 更改 setupCommand 后 ```bash openclaw sandbox recreate --all -# 或仅重建一个智能体： +# 或仅针对一个智能体： openclaw sandbox recreate --agent family ``` -### 仅针对某个特定智能体 +### 仅针对特定智能体 ```bash -# 仅更新某个智能体的容器 +# 仅更新一个智能体的容器 openclaw sandbox recreate --agent alfred ``` -## 为什么需要这样做？ +## 为什么需要这样做 -**问题：** 当你更新沙箱配置时： +当你更新沙箱配置时： -- 现有运行时会继续以旧设置运行 -- 运行时只有在空闲 24 小时后才会被清理 -- 经常使用的智能体会无限期保留旧运行时 +- 现有运行时会继续使用旧设置运行。 +- 运行时仅会在空闲 24 小时后被清理。 +- 经常使用的智能体会无限期保留旧运行时。 -**解决方案：** 使用 `openclaw sandbox recreate` 强制移除旧运行时。它们会在下次需要时根据当前设置自动重新创建。 +使用 `openclaw sandbox recreate` 可强制移除旧运行时。它们会在下次需要时按当前设置自动重新创建。 -提示：优先使用 `openclaw sandbox recreate`，而不是手动执行特定后端的清理。 -它使用 Gateway 网关的运行时注册表，可避免在范围/会话键变化时出现不匹配。 + +优先使用 `openclaw sandbox recreate`，而不是手动执行特定后端的清理。它使用 Gateway 网关的运行时注册表，并可避免在作用域或会话键发生变化时出现不匹配。 + ## 配置 -沙箱设置位于 `~/.openclaw/openclaw.json` 的 `agents.defaults.sandbox` 下（按智能体覆盖项位于 `agents.list[].sandbox`）： +沙箱设置位于 `~/.openclaw/openclaw.json` 中的 `agents.defaults.sandbox` 下（按智能体覆盖放在 `agents.list[].sandbox` 中）： ```jsonc { @@ -197,7 +200,7 @@ openclaw sandbox recreate --agent alfred ## 相关内容 -- [CLI 参考](/zh-CN/cli) +- [CLI reference](/zh-CN/cli) - [沙箱隔离](/zh-CN/gateway/sandboxing) - [智能体工作区](/zh-CN/concepts/agent-workspace) -- [Doctor](/zh-CN/gateway/doctor) — 检查沙箱设置 +- [Doctor](/zh-CN/gateway/doctor)：检查沙箱设置。 diff --git a/docs/zh-CN/cli/update.md b/docs/zh-CN/cli/update.md index bc72637ae..b353200da 100644 --- a/docs/zh-CN/cli/update.md +++ b/docs/zh-CN/cli/update.md @@ -1,14 +1,14 @@ --- read_when: - - 你想安全地更新一个源码检出副本 + - 你想安全地更新一个源代码检出副本 - 你需要理解 `--update` 简写行为 -summary: '`openclaw update` 的 CLI 参考（相对安全的源码更新 + Gateway 网关自动重启）' +summary: '`openclaw update` 的 CLI 参考（相对安全的源更新 + Gateway 网关自动重启）' title: 更新 x-i18n: - generated_at: "2026-04-26T09:50:06Z" + generated_at: "2026-04-27T04:33:48Z" model: gpt-5.4 provider: openai - source_hash: e86e7f8ffbf3f4ccd0787ba06aead35cb96e8db98c5d32c99b18ef9fda62efd6 + source_hash: 2e25774db66e013dd9f1727f3d917719cd5346d2bc8e91bec2802f64315fecd0 source_path: cli/update.md workflow: 15 --- @@ -17,8 +17,7 @@ x-i18n: 安全地更新 OpenClaw，并在 stable/beta/dev 渠道之间切换。 -如果你通过 **npm/pnpm/bun** 安装（全局安装，无 git 元数据）， -更新会通过 [更新](/zh-CN/install/updating) 中的软件包管理器流程进行。 +如果你通过 **npm/pnpm/bun** 安装（全局安装，没有 git 元数据），更新将通过 [更新](/zh-CN/install/updating) 中的软件包管理器流程进行。 ## 用法 @@ -42,16 +41,18 @@ openclaw --update - `--no-restart`：成功更新后跳过重启 Gateway 网关服务。对于确实会重启 Gateway 网关的软件包管理器更新，命令只有在验证重启后的服务报告了预期的更新版本后才会成功。 - `--channel `：设置更新渠道（git + npm；会持久化到配置中）。 - `--tag `：仅为本次更新覆盖软件包目标。对于软件包安装，`main` 会映射到 `github:openclaw/openclaw#main`。 -- `--dry-run`：预览计划中的更新操作（channel/tag/target/restart 流程），但不写入配置、不安装、不同步插件，也不重启。 -- `--json`：输出机器可读的 `UpdateRunResult` JSON；如果在更新后插件同步期间检测到 npm 插件产物漂移，还会包含 `postUpdate.plugins.integrityDrifts`。 -- `--timeout `：每个步骤的超时时间（默认值为 1800 秒）。 -- `--yes`：跳过确认提示（例如降级确认） +- `--dry-run`：预览计划中的更新操作（渠道/标签/目标/重启流程），但不写入配置、不安装、不同步插件，也不重启。 +- `--json`：打印机器可读的 `UpdateRunResult` JSON，包括当在更新后插件同步期间检测到 npm 插件制品漂移时的 `postUpdate.plugins.integrityDrifts`。 +- `--timeout `：每个步骤的超时时间（默认 1800 秒）。 +- `--yes`：跳过确认提示（例如降级确认）。 -注意：降级需要确认，因为旧版本可能会破坏配置。 + +降级需要确认，因为旧版本可能会破坏配置。 + ## `update status` -显示当前激活的更新渠道 + git tag/branch/SHA（针对源码检出副本），以及是否有可用更新。 +显示当前激活的更新渠道 + git 标签/分支/SHA（适用于源代码检出副本），以及更新可用性。 ```bash openclaw update status @@ -61,14 +62,12 @@ openclaw update status --timeout 10 选项： -- `--json`：输出机器可读的状态 JSON。 -- `--timeout `：检查超时时间（默认值为 3 秒）。 +- `--json`：打印机器可读的状态 JSON。 +- `--timeout `：检查超时时间（默认 3 秒）。 ## `update wizard` -交互式流程，用于选择更新渠道并确认更新后是否重启 Gateway 网关 -（默认会重启）。如果你在没有 git 检出副本的情况下选择 `dev`， -它会提供创建一个检出副本的选项。 +交互式流程，用于选择更新渠道并确认更新后是否重启 Gateway 网关（默认会重启）。如果你在没有 git 检出副本的情况下选择 `dev`，它会提供创建一个检出副本的选项。 选项： @@ -76,61 +75,73 @@ openclaw update status --timeout 10 ## 它的作用 -当你显式切换渠道（`--channel ...`）时，OpenClaw 也会让 -安装方式保持一致： +当你显式切换渠道（`--channel ...`）时，OpenClaw 还会保持安装方式一致： -- `dev` → 确保存在一个 git 检出副本（默认：`~/openclaw`，可通过 `OPENCLAW_GIT_DIR` 覆盖）， - 更新它，并从该检出副本安装全局 CLI。 +- `dev` → 确保存在一个 git 检出副本（默认：`~/openclaw`，可通过 `OPENCLAW_GIT_DIR` 覆盖），更新该检出副本，并从该检出副本安装全局 CLI。 - `stable` → 使用 `latest` 从 npm 安装。 -- `beta` → 优先使用 npm dist-tag `beta`，但如果 beta 不存在 - 或比当前 stable 发布更旧，则回退到 `latest`。 +- `beta` → 优先使用 npm 的 `beta` dist-tag，但当 beta 缺失或比当前 stable 发布版本更旧时，会回退到 `latest`。 -Gateway 网关核心自动更新器（在配置中启用时）会复用这同一条更新路径。 +Gateway 网关核心自动更新器（在配置中启用时）会复用这一路径进行更新。 -对于软件包管理器安装，`openclaw update` 会在调用软件包管理器之前 -解析目标软件包版本。即使已安装版本已经与目标一致，该命令仍会刷新 -全局软件包安装，然后执行插件同步、补全刷新和重启相关工作。这样可以确保 -打包的 sidecar 和渠道所属的插件记录与已安装的 OpenClaw -构建保持一致。 +对于软件包管理器安装，`openclaw update` 会在调用软件包管理器之前解析目标软件包版本。即使已安装版本已经与目标匹配，该命令仍会刷新全局软件包安装，然后执行插件同步、补全刷新和重启操作。这可以让打包的 sidecar 和渠道所拥有的插件记录与已安装的 OpenClaw 构建保持一致。 ## Git 检出副本流程 -渠道： +### 渠道选择 -- `stable`：检出最新的非 beta tag，然后执行 build + doctor。 -- `beta`：优先选择最新的 `-beta` tag，但如果 beta 不存在或更旧， - 则回退到最新的 stable tag。 -- `dev`：检出 `main`，然后执行 fetch + rebase。 +- `stable`：检出最新的非 beta 标签，然后构建并运行 doctor。 +- `beta`：优先选择最新的 `-beta` 标签，但如果 beta 缺失或更旧，则回退到最新的 stable 标签。 +- `dev`：检出 `main`，然后获取更新并执行 rebase。 -高级流程： +### 更新步骤 -1. 需要一个干净的工作区（没有未提交的更改）。 -2. 切换到所选渠道（tag 或 branch）。 -3. 获取上游更新（仅 dev）。 -4. 仅 dev：在临时工作区中执行预检 lint + TypeScript build；如果最新提交失败，则最多回退 10 个提交以找到最新的可干净构建版本。 -5. 变基到所选提交（仅 dev）。 -6. 使用仓库的软件包管理器安装依赖。对于 pnpm 检出副本，更新器会按需引导安装 `pnpm`（优先通过 `corepack`，然后使用临时的 `npm install pnpm@10` 作为回退），而不是在 pnpm workspace 内运行 `npm run build`。 -7. 执行 build + 构建 Control UI。 -8. 运行 `openclaw doctor` 作为最终的“安全更新”检查。 -9. 将插件同步到当前激活的渠道（dev 使用内置插件；stable/beta 使用 npm），并更新通过 npm 安装的插件。 + + + 要求没有未提交的更改。 + + + 切换到所选渠道（标签或分支）。 + + + 仅适用于 dev。 + + + 在临时 worktree 中运行 lint 和 TypeScript 构建。如果最新提交失败，会最多回退 10 个提交，以找到最新一个能干净构建的提交。 + + + Rebase 到所选提交之上（仅适用于 dev）。 + + + 使用仓库的软件包管理器。对于 pnpm 检出副本，更新器会按需引导 `pnpm`（优先通过 `corepack`，然后回退到临时执行 `npm install pnpm@10`），而不是在 pnpm workspace 中运行 `npm run build`。 + + + 构建 gateway 和 Control UI。 + + + `openclaw doctor` 会作为最终的安全更新检查运行。 + + + 将插件同步到当前激活的渠道。dev 使用内置插件；stable 和 beta 使用 npm。会更新通过 npm 安装的插件。 + + -如果某个精确固定版本的 npm 插件更新解析到的产物，其完整性与已存储的安装记录 -不同，`openclaw update` 会中止该插件产物更新，而不是安装它。只有在确认 -你信任新产物之后，才应显式重新安装或更新该插件。 + +如果某个精确固定版本的 npm 插件更新解析出的制品，其完整性与已存储的安装记录不同，`openclaw update` 会中止该插件制品更新，而不是安装它。只有在确认你信任这个新制品之后，才显式重新安装或更新该插件。 + -更新后插件同步失败会导致更新结果失败，并停止后续的重启相关工作。 -修复插件安装/更新错误后，再重新运行 -`openclaw update`。 + +更新后的插件同步失败会导致更新结果失败，并停止后续重启操作。请修复插件安装或更新错误，然后重新运行 `openclaw update`。 -如果 pnpm 引导安装仍然失败，更新器现在会提前停止，并返回一个针对软件包管理器的特定错误，而不是尝试在检出副本中执行 `npm run build`。 +如果 pnpm 引导仍然失败，更新器会提前停止，并给出特定于软件包管理器的错误，而不是尝试在检出副本内运行 `npm run build`。 + ## `--update` 简写 -`openclaw --update` 会被重写为 `openclaw update`（对 shell 和启动脚本很有用）。 +`openclaw --update` 会被重写为 `openclaw update`（对于 shell 和启动脚本很有用）。 ## 相关内容 -- `openclaw doctor`（在 git 检出副本上会先提供运行 update 的选项） +- `openclaw doctor`（在 git 检出副本上会先提供运行更新） - [开发渠道](/zh-CN/install/development-channels) - [更新](/zh-CN/install/updating) -- [CLI reference](/zh-CN/cli) +- [CLI 参考](/zh-CN/cli) diff --git a/docs/zh-CN/concepts/compaction.md b/docs/zh-CN/concepts/compaction.md index 9d94203e1..06f631427 100644 --- a/docs/zh-CN/concepts/compaction.md +++ b/docs/zh-CN/concepts/compaction.md @@ -1,33 +1,33 @@ --- read_when: - - 你想了解自动压缩整理和 `/compact` - - 你正在调试触及上下文限制的长会话 + - 你想了解自动压缩整理和 /compact + - 你正在调试因长会话触及上下文限制的问题 summary: OpenClaw 如何总结长对话以保持在模型限制范围内 title: 压缩整理 x-i18n: - generated_at: "2026-04-27T04:26:16Z" + generated_at: "2026-04-27T04:33:48Z" model: gpt-5.4 provider: openai - source_hash: df7fae12618d5522deabc13a2ff81b507ce3b01840fa5c5ef3ae144aa01ece16 + source_hash: c7eb6fe8ed5cc1a9db6db2867a6e1d3259fef3ac5f797e786e914459f9dacc89 source_path: concepts/compaction.md workflow: 15 --- -每个模型都有一个上下文窗口：也就是它最多能处理的 token 数量。当对话接近这个限制时，OpenClaw 会将较早的消息**压缩整理**为摘要，这样聊天就能继续进行。 +每个模型都有一个上下文窗口：也就是它一次最多能处理的 token 数量。当对话接近这个限制时，OpenClaw 会将较早的消息**压缩整理**为摘要，以便聊天可以继续进行。 ## 工作原理 -1. 较早的对话轮次会被总结成一条压缩条目。 -2. 摘要会保存在会话转录中。 -3. 最近的消息会保持原样。 +1. 较早的对话轮次会被总结为一条压缩整理条目。 +2. 该摘要会保存在会话转录中。 +3. 最近的消息会保持完整不变。 -当 OpenClaw 将历史记录拆分为压缩整理分块时，它会让智能体的工具调用与其对应的 `toolResult` 条目保持配对。如果拆分点落在一个工具块内部，OpenClaw 会移动边界，以便让这对记录保持在一起，并保留当前未总结的尾部内容。 +当 OpenClaw 将历史拆分为压缩整理分块时，它会让助手的工具调用与其对应的 `toolResult` 条目保持配对。如果分割点落在工具块内部，OpenClaw 会移动边界，以确保这一对内容保持在一起，并保留当前未总结的尾部内容。 -完整的对话历史仍然保存在磁盘上。压缩整理只会改变模型在下一轮中看到的内容。 +完整的对话历史仍会保存在磁盘上。压缩整理只会改变模型在下一轮看到的内容。 ## 自动压缩整理 -自动压缩整理默认开启。当会话接近上下文限制时，它会运行；或者当模型返回上下文溢出错误时也会运行（此时 OpenClaw 会先压缩整理再重试）。 +自动压缩整理默认开启。当会话接近上下文限制时，或者当模型返回上下文溢出错误时，它就会运行（后一种情况下，OpenClaw 会先进行压缩整理再重试）。 你会看到： @@ -35,7 +35,7 @@ x-i18n: - `/status` 显示 `🧹 Compactions: `。 -在压缩整理之前，OpenClaw 会自动提醒智能体将重要备注保存到 [memory](/zh-CN/concepts/memory) 文件中。这样可以防止上下文丢失。 +在压缩整理之前，OpenClaw 会自动提醒智能体将重要笔记保存到 [memory](/zh-CN/concepts/memory) 文件中。这样可以防止上下文丢失。 @@ -48,26 +48,27 @@ x-i18n: - `input token count exceeds the maximum number of input tokens` - `input is too long for the model` - `ollama error: context length exceeded` + ## 手动压缩整理 -在任意聊天中输入 `/compact` 即可强制执行一次压缩整理。你也可以添加说明来引导摘要内容： +在任意聊天中输入 `/compact` 即可强制执行一次压缩整理。你还可以附加说明来引导摘要内容： ``` /compact Focus on the API design decisions ``` -当设置了 `agents.defaults.compaction.keepRecentTokens` 时，手动压缩整理会遵循该 Pi 截断点，并在重建后的上下文中保留最近的尾部内容。如果没有显式的保留预算，手动压缩整理会表现为一个硬检查点，并仅基于新的摘要继续。 +当设置了 `agents.defaults.compaction.keepRecentTokens` 时，手动压缩整理会遵循该 Pi 截断点，并在重建后的上下文中保留最近的尾部内容。如果没有显式的保留预算，手动压缩整理会表现为一次硬检查点，并仅基于新的摘要继续。 ## 配置 -在你的 `openclaw.json` 中，通过 `agents.defaults.compaction` 配置压缩整理。下面列出了最常见的调节项；完整参考请见 [Session management deep dive](/zh-CN/reference/session-management-compaction)。 +在你的 `openclaw.json` 中，通过 `agents.defaults.compaction` 配置压缩整理。下面列出了最常用的选项；完整参考请参阅 [Session management deep dive](/zh-CN/reference/session-management-compaction)。 ### 使用不同的模型 -默认情况下，压缩整理会使用智能体的主模型。设置 `agents.defaults.compaction.model` 可以将摘要任务委托给一个能力更强或更专业的模型。这个覆盖值接受任意 `provider/model-id` 字符串： +默认情况下，压缩整理使用智能体的主模型。设置 `agents.defaults.compaction.model` 可将摘要生成委托给能力更强或更专门的模型。该覆盖项接受任意 `provider/model-id` 字符串： ```json { @@ -81,7 +82,7 @@ x-i18n: } ``` -这也适用于本地模型，例如专门用于摘要的第二个 Ollama 模型： +这同样适用于本地模型，例如专门用于摘要生成的第二个 Ollama 模型： ```json { @@ -95,27 +96,27 @@ x-i18n: } ``` -如果未设置，压缩整理会使用智能体的主模型。 +未设置时，压缩整理会使用智能体的主模型。 ### 标识符保留 -压缩整理摘要默认会保留不透明标识符（`identifierPolicy: "strict"`）。你可以将其改为 `identifierPolicy: "off"` 来禁用，或者使用 `identifierPolicy: "custom"` 并配合 `identifierInstructions` 来提供自定义指导。 +默认情况下，压缩整理摘要会保留不透明标识符（`identifierPolicy: "strict"`）。你可以通过设置 `identifierPolicy: "off"` 来禁用，或者通过设置 `identifierPolicy: "custom"` 并配合 `identifierInstructions` 提供自定义指导。 ### 活动转录字节保护 -当设置了 `agents.defaults.compaction.maxActiveTranscriptBytes` 时，如果活动 JSONL 达到该大小，OpenClaw 会在运行前触发常规本地压缩整理。这对于长时间运行的会话很有用：即使提供商侧的上下文管理可能让模型上下文保持健康，本地转录文件仍可能持续增长。它不会直接切分原始 JSONL 字节，而是调用常规压缩整理流水线来创建语义摘要。 +当设置了 `agents.defaults.compaction.maxActiveTranscriptBytes` 时，如果活动 JSONL 达到该大小，OpenClaw 会在运行前触发常规本地压缩整理。这对于长时间运行的会话很有用：即使提供商侧的上下文管理能让模型上下文保持健康，本地转录仍可能持续增长。它不会直接切分原始 JSONL 字节，而是会调用常规压缩整理流程来生成语义摘要。 -字节保护要求设置 `truncateAfterCompaction: true`。如果不进行转录轮转，活动文件不会缩小，该保护机制也就不会生效。 +字节保护要求设置 `truncateAfterCompaction: true`。如果不进行转录轮换，活动文件不会缩小，因此该保护机制将保持不活跃状态。 ### 后继转录 -当启用 `agents.defaults.compaction.truncateAfterCompaction` 时，OpenClaw 不会就地重写现有转录。它会基于压缩整理摘要、保留状态和未总结的尾部内容创建一个新的活动后继转录，同时将之前的 JSONL 保留为归档检查点来源。 +启用 `agents.defaults.compaction.truncateAfterCompaction` 后，OpenClaw 不会原地重写现有转录。它会基于压缩整理摘要、保留状态以及未总结的尾部内容创建一个新的活动后继转录，同时将之前的 JSONL 保留为已归档的检查点来源。 ### 压缩整理通知 -默认情况下，压缩整理会静默运行。将 `notifyUser` 设为开启后，会在压缩整理开始和完成时显示简短的状态消息： +默认情况下，压缩整理会静默运行。将 `notifyUser` 设为显示在压缩整理开始和完成时的简短状态消息： ```json5 { @@ -131,13 +132,13 @@ x-i18n: ### Memory 刷新 -在压缩整理之前，OpenClaw 可以运行一次**静默 Memory 刷新**轮次，将持久化备注保存到磁盘。详情和配置请见 [Memory](/zh-CN/concepts/memory)。 +在压缩整理之前，OpenClaw 可以执行一次**静默 Memory 刷新**轮次，将持久笔记保存到磁盘。详情和配置请参见 [Memory](/zh-CN/concepts/memory)。 -## 可插拔压缩整理提供商 +## 可插拔的压缩整理提供商 -插件可以通过插件 API 上的 `registerCompactionProvider()` 注册自定义压缩整理提供商。当某个提供商已注册并已配置时，OpenClaw 会将摘要工作委托给它，而不是使用内置的 LLM 流水线。 +插件可以通过插件 API 上的 `registerCompactionProvider()` 注册自定义压缩整理提供商。当某个提供商已注册并完成配置后，OpenClaw 会将摘要生成委托给它，而不是使用内置的 LLM 流程。 -要使用已注册的提供商，请在配置中设置它的 id： +要使用已注册的提供商，请在配置中设置其 id： ```json { @@ -151,35 +152,35 @@ x-i18n: } ``` -设置 `provider` 会自动强制使用 `mode: "safeguard"`。提供商会接收到与内置路径相同的压缩整理说明和标识符保留策略，而在提供商输出之后，OpenClaw 仍会保留最近轮次和拆分轮次的后缀上下文。 +设置 `provider` 会自动强制启用 `mode: "safeguard"`。提供商会接收与内置路径相同的压缩整理说明和标识符保留策略，并且在提供商输出之后，OpenClaw 仍会保留最近轮次和拆分轮次的后缀上下文。 -如果提供商失败或返回空结果，OpenClaw 会回退到内置的 LLM 摘要方式。 +如果提供商失败或返回空结果，OpenClaw 会回退到内置 LLM 摘要生成。 -## 压缩整理与修剪 +## 压缩整理与裁剪 -| | 压缩整理 | 修剪 | -| ---------------- | ---------------------------- | -------------------------------- | -| **作用** | 总结较早的对话 | 裁剪旧的工具结果 | -| **会保存吗？** | 会（保存在会话转录中） | 不会（仅保存在内存中，按请求） | -| **范围** | 整个对话 | 仅工具结果 | +| | 压缩整理 | 裁剪 | +| ---------------- | ------------------------ | ------------------------------ | +| **它的作用** | 总结较早的对话 | 修剪旧的工具结果 | +| **会保存吗？** | 会（保存在会话转录中） | 不会（仅在内存中、按请求进行） | +| **范围** | 整个对话 | 仅工具结果 | -[Session pruning](/zh-CN/concepts/session-pruning) 是一种更轻量的补充方式，它会在不进行摘要的情况下裁剪工具输出。 +[Session pruning](/zh-CN/concepts/session-pruning) 是一种更轻量的补充方式，它会在不生成摘要的情况下裁剪工具输出。 ## 故障排除 -**压缩整理得太频繁？** 模型的上下文窗口可能较小，或者工具输出可能很大。尝试启用 [session pruning](/zh-CN/concepts/session-pruning)。 +**压缩整理得太频繁？** 模型的上下文窗口可能较小，或者工具输出可能较大。你可以尝试启用 [session pruning](/zh-CN/concepts/session-pruning)。 -**压缩整理后感觉上下文不够新鲜？** 使用 `/compact Focus on ` 来引导摘要，或者启用 [memory flush](/zh-CN/concepts/memory)，这样备注就能保留下来。 +**压缩整理后感觉上下文变旧了？** 使用 `/compact Focus on ` 来引导摘要，或者启用 [memory flush](/zh-CN/concepts/memory)，让笔记得以保留。 -**需要一个全新的开始？** `/new` 会启动一个新的会话，而不会执行压缩整理。 +**需要一个全新的开始？** `/new` 会启动一个新的会话，而不会进行压缩整理。 -有关高级配置（保留 token、标识符保留、自定义上下文引擎、OpenAI 服务端压缩整理），请参阅 [Session management deep dive](/zh-CN/reference/session-management-compaction)。 +有关高级配置（预留 token、标识符保留、自定义上下文引擎、OpenAI 服务端压缩整理），请参阅 [Session management deep dive](/zh-CN/reference/session-management-compaction)。 ## 相关内容 -- [Session](/zh-CN/concepts/session)：会话管理和生命周期。 +- [Session](/zh-CN/concepts/session)：会话管理与生命周期。 - [Session pruning](/zh-CN/concepts/session-pruning)：裁剪工具结果。 - [Context](/zh-CN/concepts/context)：如何为智能体轮次构建上下文。 - [Hooks](/zh-CN/automation/hooks)：压缩整理生命周期钩子（`before_compaction`、`after_compaction`）。 diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index e45eccb06..2255a5978 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -1,30 +1,30 @@ --- read_when: - - 你需要一份按提供商分别说明的模型设置参考文档 - - 你想要模型提供商的示例配置或 CLI 新手引导命令 + - 你需要一份按提供商逐一说明的模型设置参考。 + - 你想要模型提供商的示例配置或 CLI 新手引导命令。 sidebarTitle: Model providers summary: 模型提供商概览，包含示例配置 + CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-04-26T07:48:30Z" + generated_at: "2026-04-27T04:33:49Z" model: gpt-5.4 provider: openai - source_hash: 925641c70780a5bc87c4fc8236bad56ba9e157df26d8084143eba4bf54e63159 + source_hash: 8db7b641b38aedfe14661d6d1de55500a1fd15e87b5f37845e7cad1627e45d55 source_path: concepts/model-providers.md workflow: 15 --- -**LLM/模型提供商**参考（不是像 WhatsApp/Telegram 这样的聊天渠道）。有关模型选择规则，请参阅 [Models](/zh-CN/concepts/models)。 +**LLM/模型提供商** 的参考（不是像 WhatsApp/Telegram 这样的聊天渠道）。关于模型选择规则，请参阅 [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.*.models[].contextWindow` 是模型原生元数据；`contextTokens` 是运行时的实际限制上限。 - - 回退规则、冷却探测和会话覆盖持久化：参见 [模型故障切换](/zh-CN/concepts/model-failover)。 + - `models.providers.*.models[].contextWindow` 是模型原生元数据；`contextTokens` 是运行时生效的上限。 + - 回退规则、冷却探测和会话覆盖持久化： [Model failover](/zh-CN/concepts/model-failover)。 OpenAI 系列路由按前缀区分： @@ -33,55 +33,55 @@ x-i18n: - `openai-codex/` 在 PI 中使用 Codex OAuth。 - `openai/` 加上 `agents.defaults.agentRuntime.id: "codex"` 时，使用原生 Codex 应用服务器 Codex harness。 - 参见 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果你对 provider/运行时的拆分感到困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 + 参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果你觉得提供商/运行时拆分让人困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 插件自动启用遵循相同边界：`openai-codex/` 属于 OpenAI 插件，而 Codex 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/` 引用启用。 - GPT-5.5 可通过 `openai/gpt-5.5` 用于直接 API 密钥流量，通过 `openai-codex/gpt-5.5` 在 PI 中用于 Codex OAuth，并在设置 `agentRuntime.id: "codex"` 时使用原生 Codex 应用服务器 Codex harness。 + GPT-5.5 可通过 `openai/gpt-5.5` 用于直接 API 密钥流量，通过 `openai-codex/gpt-5.5` 在 PI 中用于 Codex OAuth；当设置 `agentRuntime.id: "codex"` 时，则使用原生 Codex 应用服务器 Codex harness。 - 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/*` 引用会迁移回规范提供商引用，并将运行时单独记录。 -## 插件拥有的 provider 行为 +## 插件拥有的提供商行为 -大多数 provider 特定逻辑都位于 provider 插件（`registerProvider(...)`）中，而 OpenClaw 负责通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具 schema 清理、故障切换分类、OAuth 刷新、使用情况报告、thinking/reasoning 配置等。 +大多数提供商特定逻辑都位于提供商插件中（`registerProvider(...)`），而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具模式清理、故障切换分类、OAuth 刷新、使用情况报告、thinking/reasoning 配置等。 -完整的 provider SDK 钩子列表和内置插件示例位于 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个 provider 需要完全自定义的请求执行器，那会属于一个单独且更深层的扩展接口。 +提供商 SDK 钩子和内置插件示例的完整列表见 [Provider plugins](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，那就是另一个更深层的扩展接口。 -Provider 运行时 `capabilities` 是共享运行器元数据（provider 家族、转录/工具行为差异、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是一个插件注册了什么能力（文本推理、语音等）。 +提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录/工具行为差异、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。 ## API 密钥轮换 - 通过以下方式配置多个密钥： + 你可以通过以下方式配置多个密钥： - `OPENCLAW_LIVE__KEY`（单个实时覆盖，最高优先级） - `_API_KEYS`（逗号或分号分隔列表） - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） - 对于 Google providers，还会将 `GOOGLE_API_KEY` 作为回退来源。密钥选择顺序会保留优先级并去重。 + 对于 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`，或周期性的使用限制消息）。 + - 非速率限制失败会立即失败；不会尝试密钥轮换。 + - 当所有候选密钥都失败时，返回最后一次尝试的最终错误。 -## 内置 providers（pi-ai 目录） +## 内置提供商（pi-ai 目录） -OpenClaw 内置了 pi‑ai 目录。这些 providers **不需要** `models.providers` 配置；只需设置认证并选择一个模型。 +OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证并选择模型。 ### OpenAI @@ -89,17 +89,17 @@ OpenClaw 内置了 pi‑ai 目录。这些 providers **不需要** `models.provi - 认证：`OPENAI_API_KEY` - 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖） - 示例模型：`openai/gpt-5.5`、`openai/gpt-5.4-mini` -- 如果特定安装或 API 密钥行为不同，可使用 `openclaw models list --provider openai` 验证账户/模型可用性。 +- 如果某个安装或 API 密钥行为不同，可使用 `openclaw models list --provider openai` 验证账户/模型可用性。 - CLI：`openclaw onboard --auth-choice openai-api-key` - 默认传输为 `auto`（优先 WebSocket，回退 SSE） -- 可通过 `agents.defaults.models["openai/"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`） -- 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先处理 -- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority` -- 当你想显式指定层级而不是使用共享 `/fast` 开关时，请使用 `params.serviceTier` -- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理 -- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示以及 OpenAI reasoning 兼容载荷整形；代理路由不会 -- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为实时 OpenAI API 请求会拒绝它，而当前 Codex 目录也未公开它 +- 可通过 `agents.defaults.models["openai/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） +- OpenAI Responses WebSocket 预热默认启用，通过 `params.openaiWsWarmup` 控制（`true`/`false`） +- 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先级处理 +- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射为 `api.openai.com` 上的 `service_tier=priority` +- 如果你想显式指定层级，而不是使用共享 `/fast` 开关，请使用 `params.serviceTier` +- 隐藏的 OpenClaw 归因头（`originator`、`version`、`User-Agent`）只会应用于发往 `api.openai.com` 的原生 OpenAI 流量，不会应用于通用 OpenAI 兼容代理 +- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示和 OpenAI reasoning 兼容负载整形；代理路由不会 +- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意隐藏，因为实时 OpenAI API 请求会拒绝它，而当前 Codex 目录也未公开它 ```json5 { @@ -114,14 +114,14 @@ OpenClaw 内置了 pi‑ai 目录。这些 providers **不需要** `models.provi - 可选轮换：`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 请求支持共享 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`） - 推荐的 Claude CLI 配置会保持模型引用为规范形式，并单独选择 CLI - 后端：`anthropic/claude-opus-4-7` 搭配 + 后端：`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 用法再次被允许，因此 OpenClaw 目前将 Claude CLI 复用和 `claude -p` 用法视为此集成的获准方式，除非 Anthropic 发布新政策。Anthropic setup-token 仍然作为 OpenClaw 支持的令牌路径保留，但 OpenClaw 现在在可用时更倾向于 Claude CLI 复用和 `claude -p`。 ```json5 @@ -135,18 +135,18 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允 - 提供商：`openai-codex` - 认证：OAuth（ChatGPT） - PI 模型引用：`openai-codex/gpt-5.5` -- 原生 Codex 应用服务器 Codex harness 引用：`openai/gpt-5.5` 搭配 `agents.defaults.agentRuntime.id: "codex"` -- 原生 Codex 应用服务器 Codex harness 文档：[Codex harness](/zh-CN/plugins/codex-harness) +- 原生 Codex 应用服务器 Codex harness 引用：`openai/gpt-5.5` 配合 `agents.defaults.agentRuntime.id: "codex"` +- 原生 Codex 应用服务器 Codex harness 文档： [Codex harness](/zh-CN/plugins/codex-harness) - 旧版模型引用：`codex/gpt-*` -- 插件边界：`openai-codex/*` 加载 OpenAI 插件；原生 Codex 应用服务器插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选择。 +- 插件边界：`openai-codex/*` 会加载 OpenAI 插件；原生 Codex 应用服务器插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选择。 - CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex` - 默认传输为 `auto`（优先 WebSocket，回退 SSE） -- 可通过 `agents.defaults.models["openai-codex/"].params.transport` 按 PI 模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） +- 可通过 `agents.defaults.models["openai-codex/"].params.transport` 为每个 PI 模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） - `params.serviceTier` 也会转发到原生 Codex Responses 请求上（`chatgpt.com/backend-api`） -- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理 -- 与直接 `openai/*` 共用相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority` -- `openai-codex/gpt-5.5` 使用 Codex 目录原生 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 -- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部工具/工作流。 +- 隐藏的 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 OAuth/订阅路径时，请使用 `openai-codex/gpt-5.5`；当你的 API 密钥设置和本地目录公开了公共 API 路径时，请使用 `openai/gpt-5.5`。 ```json5 @@ -177,15 +177,15 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允 MiniMax Coding Plan OAuth 或 API 密钥访问。 - Qwen Cloud provider 接口，以及 Alibaba DashScope 和 Coding Plan 端点映射。 + Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射。 ### OpenCode - 认证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`） -- Zen 运行时 provider：`opencode` -- Go 运行时 provider：`opencode-go` +- Zen 运行时提供商：`opencode` +- Go 运行时提供商：`opencode-go` - 示例模型：`opencode/claude-opus-4-6`、`opencode-go/kimi-k2.6` - CLI：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go` @@ -204,7 +204,7 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允 - 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview` - CLI：`openclaw onboard --auth-choice gemini-api-key` - Thinking：`/think adaptive` 使用 Google 动态 thinking。Gemini 3/3.1 不包含固定 `thinkingLevel`；Gemini 2.5 会发送 `thinkingBudget: -1`。 -- 直接 Gemini 运行也接受 `agents.defaults.models["google/"].params.cachedContent`（或旧版 `cached_content`），用于转发 provider 原生 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` +- 直接 Gemini 运行还接受 `agents.defaults.models["google/"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` ### Google Vertex 和 Gemini CLI @@ -212,7 +212,7 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允 - 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程 -OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后，其 Google 账户受到限制。请查看 Google 条款，并在你决定继续时使用非关键账户。 +OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告在使用第三方客户端后遭遇 Google 账户限制。若你选择继续，请查看 Google 条款，并使用非关键账户。 Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 @@ -242,7 +242,7 @@ Gemini CLI OAuth 作为内置 `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 网关主机上的认证配置文件中。 + 默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不需要**把 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的认证配置文件中。 @@ -250,7 +250,7 @@ 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） @@ -258,7 +258,7 @@ Gemini CLI JSON 回复会从 `response` 中解析；使用量统计会回退到 - 认证：`ZAI_API_KEY` - 示例模型：`zai/glm-5.1` - CLI：`openclaw onboard --auth-choice zai-api-key` - - 别名：`z.ai/*` 和 `z-ai/*` 会被规范化为 `zai/*` + - 别名：`z.ai/*` 和 `z-ai/*` 会规范化为 `zai/*` - `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口 ### Vercel AI Gateway @@ -274,19 +274,19 @@ Gemini CLI JSON 回复会从 `response` 中解析；使用量统计会回退到 - 认证：`KILOCODE_API_KEY` - 示例模型：`kilocode/kilo/auto` - CLI：`openclaw onboard --auth-choice kilocode-api-key` -- Base URL：`https://api.kilo.ai/api/gateway/` -- 静态回退目录内置 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 发现还可以进一步扩展运行时目录。 -- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 网关负责，而不是在 OpenClaw 中硬编码。 +- 基础 URL：`https://api.kilo.ai/api/gateway/` +- 静态回退目录内置 `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)。 -### 其他内置 provider 插件 +### 其他内置提供商插件 | 提供商 | 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` | — | | 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` | — | @@ -303,7 +303,7 @@ Gemini CLI JSON 回复会从 `response` 中解析；使用量统计会回退到 | 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` | +| 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` | | Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | @@ -312,31 +312,31 @@ Gemini CLI JSON 回复会从 `response` 中解析；使用量统计会回退到 - 仅在已验证的 `openrouter.ai` 路由上应用其应用归因请求头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用可使用由 OpenRouter 管理的提示缓存 TTL，但不会接收 Anthropic 缓存标记。作为代理风格的 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的载荷整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI reasoning 兼容）。基于 Gemini 的引用仅保留代理 Gemini thought-signature 清理。 + 仅在已验证的 `openrouter.ai` 路由上应用其应用归因头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用可使用 OpenRouter 托管的提示缓存 TTL，但不会收到 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅原生 OpenAI 支持的整形逻辑（`serviceTier`、Responses `store`、提示缓存提示、OpenAI reasoning 兼容性）。Gemini 支持的引用仅保留代理 Gemini thought-signature 清理。 - 基于 Gemini 的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。 + Gemini 支持的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。 - API 密钥新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍由插件拥有的 `MiniMax-VL-01` 媒体 provider 处理。 + API 密钥新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在插件拥有的 `MiniMax-VL-01` 媒体提供商上。 - 使用 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` 禁用。 + 使用 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` 禁用。 - GLM 模型使用 `zai-glm-4.7` / `zai-glm-4.6`；OpenAI 兼容 Base URL 为 `https://api.cerebras.ai/v1`。 + GLM 模型使用 `zai-glm-4.7` / `zai-glm-4.6`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。 -## 通过 `models.providers` 配置的 providers（自定义/Base URL） +## 通过 `models.providers` 配置的提供商（自定义/基础 URL） -使用 `models.providers`（或 `models.json`）添加**自定义** providers 或兼容 OpenAI/Anthropic 的代理。 +使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。 -下方许多内置 provider 插件已经发布了默认目录。只有当你想覆盖默认 Base URL、请求头或模型列表时，才需要显式添加 `models.providers.` 条目。 +下面许多内置提供商插件已经发布了默认目录。只有当你想覆盖默认基础 URL、请求头或模型列表时，才需要使用显式 `models.providers.` 条目。 ### Moonshot AI（Kimi） -Moonshot 作为内置 provider 插件提供。默认请使用内置 provider，只有在你需要覆盖 Base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： +Moonshot 作为内置提供商插件提供。默认使用内置提供商；仅当你需要覆盖基础 URL 或模型元数据时，才添加显式 `models.providers.moonshot` 条目： - 提供商：`moonshot` - 认证：`MOONSHOT_API_KEY` @@ -391,13 +391,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： } ``` -旧版 `kimi/k2p5` 仍然作为兼容模型 id 被接受。 +旧版 `kimi/k2p5` 仍被接受为兼容模型 ID。 ### Volcano Engine（Doubao） -Volcano Engine（火山引擎）为中国用户提供对 Doubao 及其他模型的访问。 +Volcano Engine（火山引擎）为中国用户提供对 Doubao 和其他模型的访问。 -- 提供商：`volcengine`（Coding：`volcengine-plan`） +- 提供商：`volcengine`（编程：`volcengine-plan`） - 认证：`VOLCANO_ENGINE_API_KEY` - 示例模型：`volcengine-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice volcengine-api-key` @@ -410,9 +410,9 @@ Volcano Engine（火山引擎）为中国用户提供对 Doubao 及其他模型 } ``` -新手引导默认使用 Coding 接口，但通用 `volcengine/*` 目录也会同时注册。 +新手引导默认使用编程接口，但同时也会注册通用 `volcengine/*` 目录。 -在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商范围筛选的选择器。 +在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤目录，而不是显示一个空的按提供商筛选选择器。 @@ -422,7 +422,7 @@ Volcano Engine（火山引擎）为中国用户提供对 Doubao 及其他模型 - `volcengine/glm-4-7-251222`（GLM 4.7） - `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K） - + - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` - `volcengine-plan/kimi-k2.5` @@ -435,7 +435,7 @@ Volcano Engine（火山引擎）为中国用户提供对 Doubao 及其他模型 BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 -- 提供商：`byteplus`（Coding：`byteplus-plan`） +- 提供商：`byteplus`（编程：`byteplus-plan`） - 认证：`BYTEPLUS_API_KEY` - 示例模型：`byteplus-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice byteplus-api-key` @@ -448,9 +448,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 } ``` -新手引导默认使用 Coding 接口，但通用 `byteplus/*` 目录也会同时注册。 +新手引导默认使用编程接口，但同时也会注册通用 `byteplus/*` 目录。 -在新手引导/配置模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商范围筛选的选择器。 +在新手引导/配置模型选择器中，BytePlus（国际版）认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤目录，而不是显示一个空的按提供商筛选选择器。 @@ -458,7 +458,7 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 - `byteplus/kimi-k2-5-260127`（Kimi K2.5） - `byteplus/glm-4-7-251222`（GLM 4.7） - + - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` - `byteplus-plan/kimi-k2.5` @@ -469,7 +469,7 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 ### Synthetic -Synthetic 通过 `synthetic` 提供商提供兼容 Anthropic 的模型： +Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型： - 提供商：`synthetic` - 认证：`SYNTHETIC_API_KEY` @@ -505,26 +505,26 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点： - 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 搜索保持使用 provider id `minimax` +- 图像理解在两种 MiniMax 认证路径上都使用插件拥有的 `MiniMax-VL-01` +- Web 搜索仍使用提供商 id `minimax` ### LM Studio -LM Studio 作为内置 provider 插件提供，并使用原生 API： +LM Studio 作为内置提供商插件提供，并使用原生 API： - 提供商：`lmstudio` - 认证：`LM_API_TOKEN` -- 默认推理 Base URL：`http://localhost:1234/v1` +- 默认推理基础 URL：`http://localhost:1234/v1` 然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）： @@ -536,16 +536,16 @@ LM Studio 作为内置 provider 插件提供，并使用原生 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` 进行推理。设置和故障排除请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 ### Ollama -Ollama 作为内置 provider 插件提供，并使用 Ollama 原生 API： +Ollama 作为内置提供商插件提供，并使用 Ollama 原生 API： - 提供商：`ollama` -- 认证：无需（本地服务器） +- 认证：不需要（本地服务器） - 示例模型：`ollama/llama3.3` -- 安装：[https://ollama.com/download](https://ollama.com/download) +- 安装： [https://ollama.com/download](https://ollama.com/download) ```bash # 安装 Ollama，然后拉取一个模型： @@ -560,15 +560,15 @@ ollama pull llama3.3 } ``` -当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，并且内置 provider 插件会将 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 -vLLM 作为内置 provider 插件提供，用于本地/自托管 OpenAI 兼容服务器： +vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容服务器： - 提供商：`vllm` - 认证：可选（取决于你的服务器） -- 默认 Base URL：`http://127.0.0.1:8000/v1` +- 默认基础 URL：`http://127.0.0.1:8000/v1` 要在本地启用自动发现（如果你的服务器不强制认证，任意值都可以）： @@ -586,15 +586,15 @@ export VLLM_API_KEY="vllm-local" } ``` -有关详情，请参阅 [/providers/vllm](/zh-CN/providers/vllm)。 +详情请参阅 [/providers/vllm](/zh-CN/providers/vllm)。 ### SGLang -SGLang 作为内置 provider 插件提供，用于高性能自托管 OpenAI 兼容服务器： +SGLang 作为内置提供商插件提供，用于快速自托管的 OpenAI 兼容服务器： - 提供商：`sglang` - 认证：可选（取决于你的服务器） -- 默认 Base URL：`http://127.0.0.1:30000/v1` +- 默认基础 URL：`http://127.0.0.1:30000/v1` 要在本地启用自动发现（如果你的服务器不强制认证，任意值都可以）： @@ -612,7 +612,7 @@ export SGLANG_API_KEY="sglang-local" } ``` -有关详情，请参阅 [/providers/sglang](/zh-CN/providers/sglang)。 +详情请参阅 [/providers/sglang](/zh-CN/providers/sglang)。 ### 本地代理（LM Studio、vLLM、LiteLLM 等） @@ -632,6 +632,7 @@ export SGLANG_API_KEY="sglang-local" baseUrl: "http://localhost:1234/v1", apiKey: "${LM_API_TOKEN}", api: "openai-completions", + timeoutSeconds: 300, models: [ { id: "my-local-model", @@ -651,7 +652,7 @@ export SGLANG_API_KEY="sglang-local" - 对于自定义 providers，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。省略时，OpenClaw 默认使用： + 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。省略时，OpenClaw 默认值为： - `reasoning: false` - `input: ["text"]` @@ -659,14 +660,15 @@ export SGLANG_API_KEY="sglang-local" - `contextWindow: 200000` - `maxTokens: 8192` - 建议：设置与你的代理/模型限制一致的显式值。 + 建议：设置与你的代理/模型限制匹配的显式值。 - - 对于非原生端点上的 `api: "openai-completions"`（任意非空 `baseUrl`，且其主机不是 `api.openai.com`），OpenClaw 会强制 `compat.supportsDeveloperRole: false`，以避免 provider 因不支持 `developer` 角色而返回 400 错误。 - - 代理风格的 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求整形：没有 `service_tier`、没有 Responses `store`、没有 Completions `store`、没有提示缓存提示、没有 OpenAI reasoning 兼容载荷整形，也没有隐藏的 OpenClaw 归因请求头。 - - 对于需要厂商特定字段的 OpenAI 兼容 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以将额外 JSON 合并到出站请求体中。 - - 对于 vLLM chat-template 控制，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话 thinking level 关闭时，OpenClaw 会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。 + - 对于非原生端点上的 `api: "openai-completions"`（任何主机不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制设定 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 + - 代理式 OpenAI 兼容路由也会跳过仅原生 OpenAI 支持的请求整形：不发送 `service_tier`，不发送 Responses `store`，不发送 Completions `store`，不发送提示缓存提示，不执行 OpenAI reasoning 兼容负载整形，也不附加隐藏的 OpenClaw 归因头。 + - 对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以将额外 JSON 合并到出站请求体中。 + - 对于 vLLM chat-template 控制，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话 thinking 级别关闭时，OpenClaw 会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。 + - 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers..timeoutSeconds`。这会延长提供商模型 HTTP 请求处理时间，包括连接、请求头、正文流式传输和整体 guarded-fetch 中止时间，但不会增加整个智能体运行时超时。 - 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认 OpenAI 行为（即解析到 `api.openai.com`）。 - 出于安全考虑，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。 @@ -680,11 +682,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -另请参阅：[配置](/zh-CN/gateway/configuration) 了解完整配置示例。 +另请参阅： [Configuration](/zh-CN/gateway/configuration) 以获取完整配置示例。 ## 相关内容 -- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键 -- [模型故障切换](/zh-CN/concepts/model-failover) — 回退链和重试行为 +- [Configuration reference](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键 +- [Model failover](/zh-CN/concepts/model-failover) — 回退链和重试行为 - [Models](/zh-CN/concepts/models) — 模型配置和别名 -- [Providers](/zh-CN/providers) — 按 provider 分类的设置指南 +- [Providers](/zh-CN/providers) — 按提供商分类的设置指南 diff --git a/docs/zh-CN/gateway/local-models.md b/docs/zh-CN/gateway/local-models.md index 28e57e336..0d75b022c 100644 --- a/docs/zh-CN/gateway/local-models.md +++ b/docs/zh-CN/gateway/local-models.md @@ -1,26 +1,26 @@ --- read_when: - - 你想从你自己的 GPU 主机提供模型服务 - - 你正在接入 LM Studio 或兼容 OpenAI 的代理 - - 你需要最安全的本地模型使用指南 -summary: 在本地 LLM 上运行 OpenClaw（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点） + - 你希望从你自己的 GPU 主机提供模型服务 + - 你正在配置 LM Studio 或与 OpenAI 兼容的代理 + - 你需要最安全的本地模型指引 +summary: 在本地 LLM（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点）上运行 OpenClaw title: 本地模型 x-i18n: - generated_at: "2026-04-24T03:16:02Z" + generated_at: "2026-04-27T04:33:47Z" model: gpt-5.4 provider: openai - source_hash: 9315b03b4bacd44af50ebec899f1d13397b9ae91bde21742fe9f022c23d1e95c + source_hash: 7b6c3952f6384038fef3b2afd5cf623b6a1744072b789240f394dc7552751f2b source_path: gateway/local-models.md workflow: 15 --- -本地部署是可行的，但 OpenClaw 需要大上下文窗口以及对 prompt injection 的强防护。小显存卡会截断上下文并削弱安全性。目标配置应尽量高：**至少 2 台满配 Mac Studio 或同等级 GPU 设备（约 3 万美元以上）**。单张 **24 GB** GPU 只适用于更轻量的提示，同时延迟更高。请使用**你能运行的最大 / 全尺寸模型变体**；激进量化或 “small” 检查点会提高 prompt injection 风险（参见 [Security](/zh-CN/gateway/security)）。 +本地部署是可行的，但 OpenClaw 需要大上下文窗口，以及对提示注入的强防护。小显存显卡会截断上下文，并削弱安全性。目标配置要尽可能高：**≥ 2 台满配 Mac Studio 或同等级 GPU 设备（约 3 万美元以上）**。单张 **24 GB** GPU 只适合较轻量的提示词场景，而且延迟会更高。使用**你能运行的最大 / 全尺寸模型变体**；激进量化或“small”检查点会提高提示注入风险（参见 [Security](/zh-CN/gateway/security)）。 -如果你想要最低摩擦的本地配置，先从 [LM Studio](/zh-CN/providers/lmstudio) 或 [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 { @@ -60,15 +60,15 @@ x-i18n: **设置清单** - 安装 LM Studio：[https://lmstudio.ai](https://lmstudio.ai) -- 在 LM Studio 中，下载**当前可用的最大模型构建**（避免 “small” / 重度量化变体），启动服务器，并确认 `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 { @@ -109,18 +109,18 @@ x-i18n: } ``` -### 本地优先，同时保留托管安全网 +### 本地优先，托管模型作安全兜底 -交换主模型和回退模型的顺序；保留相同的 providers 块和 `models.mode: "merge"`，这样当本地主机不可用时，你仍然可以回退到 Sonnet 或 Opus。 +交换主模型和回退模型的顺序；保留相同的 provider 配置块和 `models.mode: "merge"`，这样当本地主机不可用时，你仍然可以回退到 Sonnet 或 Opus。 ### 区域托管 / 数据路由 -- 托管的 MiniMax / Kimi / GLM 变体也可通过 OpenRouter 的区域固定端点提供（例如托管在美国）。选择其中的区域变体，以便让流量保留在你选定的司法辖区内，同时仍可使用 `models.mode: "merge"` 作为 Anthropic / OpenAI 回退。 -- 纯本地仍然是隐私性最强的路径；当你需要提供商功能但又想控制数据流向时，区域托管路由是折中方案。 +- 托管的 MiniMax/Kimi/GLM 变体也可通过 OpenRouter 的区域固定端点提供（例如美国托管）。在那里选择区域变体，可以在继续使用 `models.mode: "merge"` 为 Anthropic/OpenAI 提供回退的同时，将流量限制在你选定的司法辖区内。 +- 纯本地仍然是隐私最强的路径；如果你需要 provider 功能，但又想控制数据流向，那么区域托管路由就是折中方案。 ## 其他 OpenAI 兼容本地代理 -vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关都可以使用，只要它们暴露了 OpenAI 风格的 `/v1` 端点。将上面的 provider 块替换为你的端点和模型 ID： +如果 vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关公开了 OpenAI 风格的 `/v1` 端点，也可以使用。将上面的 provider 配置块替换为你的端点和模型 ID： ```json5 { @@ -131,6 +131,7 @@ vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关都可以使用，只要 baseUrl: "http://127.0.0.1:8000/v1", apiKey: "sk-local", api: "openai-responses", + timeoutSeconds: 300, models: [ { id: "my-local-model", @@ -148,52 +149,34 @@ vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关都可以使用，只要 } ``` -保留 `models.mode: "merge"`，这样托管模型仍可作为回退使用。 +保留 `models.mode: "merge"`，这样托管模型仍可作为回退选项。 +对于较慢的本地或远程模型服务器，请先使用 `models.providers..timeoutSeconds`，再考虑提高 `agents.defaults.timeoutSeconds`。provider 超时仅适用于模型 HTTP 请求，包括连接、响应头、流式响应体，以及整个受保护获取请求的中止控制。 -关于本地 / 代理 `/v1` 后端的行为说明： +关于本地/代理 `/v1` 后端的行为说明： -- OpenClaw 会将这些后端视为代理式 OpenAI 兼容路由，而不是原生 - OpenAI 端点 -- 这里不会应用仅适用于原生 OpenAI 的请求整形：没有 - `service_tier`，没有 Responses `store`，没有 OpenAI 推理兼容负载整形， - 也没有 prompt-cache 提示 -- 不会在这些自定义代理 URL 上注入隐藏的 OpenClaw 归因头 - （`originator`、`version`、`User-Agent`） +- OpenClaw 将这些视为代理风格的 OpenAI 兼容路由，而不是原生 OpenAI 端点 +- 仅适用于原生 OpenAI 的请求整形在这里不会生效：没有 `service_tier`、没有 Responses `store`、没有 OpenAI 推理兼容负载整形，也没有提示缓存提示 +- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）不会注入到这些自定义代理 URL 中 针对更严格的 OpenAI 兼容后端的兼容性说明： -- 某些服务器在 Chat Completions 中只接受字符串类型的 `messages[].content`，而不接受 - 结构化内容片段数组。对此类端点，请设置 - `models.providers..models[].compat.requiresStringContent: true`。 -- 某些较小或更严格的本地后端在面对 OpenClaw 完整的 - 智能体运行时 prompt 结构时会不稳定，尤其是在包含工具 schema 时。如果该 - 后端能处理很小的直接 `/v1/chat/completions` 调用，却无法处理正常的 - OpenClaw 智能体轮次，请先尝试 - `agents.defaults.experimental.localModelLean: true`，以移除重量级 - 默认工具，如 `browser`、`cron` 和 `message`；这是一个实验性 - 标志，不是稳定的默认模式设置。参见 - [Experimental Features](/zh-CN/concepts/experimental-features)。如果这样仍然失败，请尝试 - `models.providers..models[].compat.supportsTools: false`。 -- 如果后端仍然只在更大的 OpenClaw 运行中失败， - 那么剩余问题通常是上游模型 / 服务器容量限制或后端 bug，而不是 OpenClaw 的 - 传输层。 +- 某些服务器在 Chat Completions 中只接受字符串形式的 `messages[].content`，不接受结构化内容片段数组。对于这些端点，请设置 `models.providers..models[].compat.requiresStringContent: true`。 +- 某些更小型或更严格的本地后端在处理 OpenClaw 完整的 Agent Runtimes 提示词结构时不稳定，尤其是在包含工具 schema 时。如果该后端可以处理极小的直接 `/v1/chat/completions` 调用，但在正常的 OpenClaw 智能体轮次中失败，请先尝试设置 `agents.defaults.experimental.localModelLean: true`，以去掉 `browser`、`cron` 和 `message` 等重量级默认工具；这是一个实验性标志，不是稳定的默认模式设置。参见 [Experimental Features](/zh-CN/concepts/experimental-features)。如果这样仍然失败，再尝试设置 `models.providers..models[].compat.supportsTools: false`。 +- 如果后端仍然只在更大的 OpenClaw 运行中失败，剩余问题通常是上游模型/服务器容量不足或后端 bug，而不是 OpenClaw 的传输层问题。 ## 故障排除 -- Gateway 网关能访问该代理吗？`curl http://127.0.0.1:1234/v1/models`。 -- LM Studio 模型已卸载？重新加载；冷启动是常见的“卡住”原因。 -- 当检测到上下文窗口低于 **32k** 时，OpenClaw 会发出警告；低于 **16k** 时会阻止运行。如果你触发了这个预检，请提高服务器 / 模型的上下文上限，或选择更大的模型。 -- 上下文错误？降低 `contextWindow` 或提高你的服务器上限。 +- Gateway 网关能连接到代理吗？`curl http://127.0.0.1:1234/v1/models`。 +- LM Studio 模型被卸载了吗？重新加载；冷启动是常见的“卡住”原因。 +- 当检测到的上下文窗口低于 **32k** 时，OpenClaw 会发出警告；低于 **16k** 时会阻止运行。如果你触发了这个预检，请提高服务器/模型的上下文限制，或选择更大的模型。 +- 出现上下文错误？降低 `contextWindow` 或提高服务器限制。 - OpenAI 兼容服务器返回 `messages[].content ... expected a string`？ - 在该模型条目上添加 - `compat.requiresStringContent: true`。 -- 很小的直接 `/v1/chat/completions` 调用能工作，但 `openclaw infer model run` - 在 Gemma 或其他本地模型上失败？先用 - `compat.supportsTools: false` 禁用工具 schema，然后重新测试。如果服务器仍然只在更大的 - OpenClaw prompt 下崩溃，请将其视为上游服务器 / 模型限制。 -- 安全性：本地模型会跳过提供商侧过滤；请让智能体保持收窄，并开启 compaction，以限制 prompt injection 的影响半径。 + 在对应模型条目上添加 `compat.requiresStringContent: true`。 +- 直接的小型 `/v1/chat/completions` 调用可以工作，但 `openclaw infer model run` 在 Gemma 或其他本地模型上失败？ + 先用 `compat.supportsTools: false` 禁用工具 schema，然后重新测试。如果服务器仍然只在较大的 OpenClaw 提示词下崩溃，就应将其视为上游服务器/模型限制。 +- 安全性：本地模型会跳过 provider 侧过滤；请保持智能体范围尽量窄，并启用压缩，以限制提示注入的影响范围。 ## 相关内容 -- [Configuration reference](/zh-CN/gateway/configuration-reference) -- [Model failover](/zh-CN/concepts/model-failover) +- [配置参考](/zh-CN/gateway/configuration-reference) +- [模型故障切换](/zh-CN/concepts/model-failover) diff --git a/docs/zh-CN/gateway/remote.md b/docs/zh-CN/gateway/remote.md index fd6e0212c..40fc4b846 100644 --- a/docs/zh-CN/gateway/remote.md +++ b/docs/zh-CN/gateway/remote.md @@ -1,75 +1,74 @@ --- read_when: - - 运行或排查远程 Gateway 网关设置故障 + - 运行或排查远程 Gateway 网关设置问题 summary: 使用 SSH 隧道（Gateway 网关 WS）和 tailnet 进行远程访问 title: 远程访问 x-i18n: - generated_at: "2026-04-26T04:11:39Z" + generated_at: "2026-04-27T04:33:47Z" model: gpt-5.4 provider: openai - source_hash: 208f0e6a4dbb342df878ea99d70606327efdfd3df36b07dfa3e68aafcae98e5c + source_hash: c1e618448d797a8003029b263dbab4a5393158c32198623fd9d1e52982567b0a source_path: gateway/remote.md workflow: 15 --- -这个仓库通过在专用主机（桌面机/服务器）上保持单个 Gateway 网关（主实例）运行，并让客户端连接到它，来支持“通过 SSH 远程访问”。 +此仓库支持通过 SSH 实现“远程访问”，方式是在专用主机（桌面机/服务器）上保持单个 Gateway 网关（主实例）运行，并让客户端连接到它。 -- 对于**操作端（你 / macOS 应用）**：SSH 隧道是通用的回退方案。 -- 对于**节点（iOS/Android 和未来设备）**：连接到 Gateway 网关 **WebSocket**（根据需要通过局域网 / tailnet 或 SSH 隧道）。 +- 对于**操作端（你 / macOS 应用）**：SSH 隧道是通用的兜底方案。 +- 对于**节点（iOS/Android 以及未来的设备）**：连接到 Gateway 网关 **WebSocket**（根据需要使用局域网 / tailnet 或 SSH 隧道）。 ## 核心思路 -- Gateway 网关 WebSocket 绑定到你配置端口上的**回环地址**（默认是 `18789`）。 -- 要远程使用时，你可以通过 SSH 转发这个回环端口（或者使用 tailnet/VPN 来减少隧道需求）。 +- Gateway 网关 WebSocket 绑定到你所配置端口的**loopback**（默认为 18789）。 +- 在远程使用时，你通过 SSH 转发这个 loopback 端口（或者使用 tailnet/VPN 来减少隧道需求）。 -## 常见的 VPN/tailnet 部署方式（智能体所在位置） +## 常见的 VPN 和 tailnet 设置 -把 **Gateway 网关主机**理解为“智能体所在的位置”。它负责会话、认证配置、渠道和状态。 -你的笔记本/台式机（以及节点）连接到这台主机。 +把 **Gateway 网关主机**理解为智能体所在的位置。它持有会话、认证配置、渠道和状态。你的笔记本、桌面机和节点都连接到这台主机。 -### 1）在你的 tailnet 中始终在线的 Gateway 网关（VPS 或家用服务器） +### 在你的 tailnet 中始终在线的 Gateway 网关 -在持久运行的主机上运行 Gateway 网关，并通过 **Tailscale** 或 SSH 访问它。 +在持久运行的主机（VPS 或家用服务器）上运行 Gateway 网关，并通过 **Tailscale** 或 SSH 访问它。 - **最佳体验：** 保持 `gateway.bind: "loopback"`，并为 Control UI 使用 **Tailscale Serve**。 -- **回退方案：** 保持回环绑定 + 从任何需要访问的机器建立 SSH 隧道。 -- **示例：** [exe.dev](/zh-CN/install/exe-dev)（简单 VM）或 [Hetzner](/zh-CN/install/hetzner)（生产 VPS）。 +- **兜底方案：** 保持 loopback，并从任何需要访问的机器建立 SSH 隧道。 +- **示例：** [exe.dev](/zh-CN/install/exe-dev)（简单 VM）或 [Hetzner](/zh-CN/install/hetzner)（生产环境 VPS）。 -当你的笔记本经常休眠，但你希望智能体始终在线时，这种方式非常理想。 +这非常适合笔记本经常休眠、但你希望智能体始终在线的场景。 -### 2）家里的台式机运行 Gateway 网关，笔记本作为远程控制端 +### 由家用桌面机运行 Gateway 网关 -笔记本**不**运行智能体。它以远程方式连接： +笔记本**不**运行智能体，而是远程连接： -- 使用 macOS 应用的**通过 SSH 远程访问**模式（设置 → 通用 → “OpenClaw 运行于”）。 -- 应用会打开并管理隧道，因此 WebChat 和健康检查都能“正常工作”。 +- 使用 macOS 应用的**通过 SSH 远程访问**模式（设置 → 通用 → OpenClaw runs）。 +- 应用会打开并管理隧道，因此 WebChat 和健康检查都能正常工作。 -操作手册：[macOS 远程访问](/zh-CN/platforms/mac/remote)。 +操作手册： [macOS 远程访问](/zh-CN/platforms/mac/remote)。 -### 3）笔记本运行 Gateway 网关，从其他机器远程访问 +### 由笔记本运行 Gateway 网关 -保持 Gateway 网关在本机运行，但安全地暴露它： +让 Gateway 网关保持本地运行，但以安全方式暴露： - 从其他机器通过 SSH 隧道连接到笔记本，或者 -- 通过 Tailscale Serve 提供 Control UI，同时让 Gateway 网关仅绑定回环地址。 +- 通过 Tailscale Serve 暴露 Control UI，并保持 Gateway 网关仅绑定 loopback。 -指南：[Tailscale](/zh-CN/gateway/tailscale) 和 [Web 概览](/zh-CN/web)。 +指南： [Tailscale](/zh-CN/gateway/tailscale) 和 [Web 概览](/zh-CN/web)。 -## 命令流（哪些组件运行在哪里） +## 命令流（哪些运行在哪） -一个 Gateway 网关服务负责状态 + 渠道。节点是外围设备。 +一个 Gateway 网关服务持有状态 + 渠道。节点是外围设备。 流程示例（Telegram → 节点）： - Telegram 消息到达 **Gateway 网关**。 - Gateway 网关运行**智能体**，并决定是否调用节点工具。 - Gateway 网关通过 Gateway 网关 WebSocket（`node.*` RPC）调用**节点**。 -- 节点返回结果；Gateway 网关再把回复发回 Telegram。 +- 节点返回结果；Gateway 网关再将回复发送回 Telegram。 说明： -- **节点不运行 gateway 服务。** 每台主机通常只应运行一个 gateway，除非你有意运行隔离配置文件（参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)）。 -- macOS 应用的“节点模式”只是一个通过 Gateway 网关 WebSocket 连接的节点客户端。 +- **节点不会运行 gateway 服务。** 每台主机上只应运行一个 gateway，除非你明确要运行隔离配置文件（参见 [多个 gateway](/zh-CN/gateway/multiple-gateways)）。 +- macOS 应用中的“节点模式”只是一个通过 Gateway 网关 WebSocket 连接的节点客户端。 ## SSH 隧道（CLI + 工具） @@ -81,16 +80,20 @@ ssh -N -L 18789:127.0.0.1:18789 user@host 隧道建立后： -- `openclaw health` 和 `openclaw status --deep` 现在会通过 `ws://127.0.0.1:18789` 访问远程 gateway。 -- `openclaw gateway status`、`openclaw gateway health`、`openclaw gateway probe` 和 `openclaw gateway call` 也可以在需要时通过 `--url` 指向这个转发后的 URL。 +- `openclaw health` 和 `openclaw status --deep` 现在会通过 `ws://127.0.0.1:18789` 连接到远程 gateway。 +- `openclaw gateway status`、`openclaw gateway health`、`openclaw gateway probe` 和 `openclaw gateway call` 在需要时也可以通过 `--url` 指向转发后的 URL。 -注意：请将 `18789` 替换为你配置的 `gateway.port`（或 `--port` / `OPENCLAW_GATEWAY_PORT`）。 -注意：当你传入 `--url` 时，CLI 不会回退到配置或环境中的凭证。 -请显式包含 `--token` 或 `--password`。缺少显式凭证会报错。 + +将 `18789` 替换为你配置的 `gateway.port`（或 `--port`，或 `OPENCLAW_GATEWAY_PORT`）。 + + + +传入 `--url` 时，CLI 不会回退到配置或环境变量中的凭证。请显式包含 `--token` 或 `--password`。缺少显式凭证会报错。 + ## CLI 远程默认值 -你可以持久化保存一个远程目标，让 CLI 命令默认使用它： +你可以持久化保存远程目标，这样 CLI 命令默认会使用它： ```json5 { @@ -104,27 +107,27 @@ ssh -N -L 18789:127.0.0.1:18789 user@host } ``` -当 gateway 仅绑定回环地址时，请将 URL 保持为 `ws://127.0.0.1:18789`，并先建立 SSH 隧道。 -在 macOS 应用的 SSH 隧道传输中，发现到的 gateway 主机名应放在 -`gateway.remote.sshTarget` 中；`gateway.remote.url` 仍然保持为本地隧道 URL。 +当 gateway 仅绑定 loopback 时，请将 URL 保持为 `ws://127.0.0.1:18789`，并先建立 SSH 隧道。 +在 macOS 应用的 SSH 隧道传输中，发现的 gateway 主机名应放在 +`gateway.remote.sshTarget`；`gateway.remote.url` 仍然保留为本地隧道 URL。 ## 凭证优先级 -Gateway 网关凭证解析在 call/probe/status 路径以及 Discord exec-approval 监控中遵循同一个共享约定。node-host 使用相同的基础约定，但有一个本地模式例外（它会有意忽略 `gateway.remote.*`）： +Gateway 网关凭证解析在 call/probe/status 路径以及 Discord 执行审批监控中遵循同一套共享契约。Node-host 使用相同的基础契约，但有一个本地模式例外（它会刻意忽略 `gateway.remote.*`）： -- 显式凭证（`--token`、`--password` 或工具中的 `gatewayToken`）在接受显式认证的调用路径中始终优先。 +- 显式凭证（`--token`、`--password` 或工具 `gatewayToken`）在接受显式认证的调用路径中始终优先。 - URL 覆盖安全规则： - - CLI URL 覆盖（`--url`）绝不会复用隐式的配置/环境凭证。 - - 环境 URL 覆盖（`OPENCLAW_GATEWAY_URL`）只能使用环境凭证（`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`）。 + - CLI URL 覆盖（`--url`）绝不会复用隐式的配置/环境变量凭证。 + - 环境变量 URL 覆盖（`OPENCLAW_GATEWAY_URL`）只能使用环境变量凭证（`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`）。 - 本地模式默认值： - token：`OPENCLAW_GATEWAY_TOKEN` -> `gateway.auth.token` -> `gateway.remote.token`（只有在本地认证 token 输入未设置时，才会应用远程回退） - password：`OPENCLAW_GATEWAY_PASSWORD` -> `gateway.auth.password` -> `gateway.remote.password`（只有在本地认证 password 输入未设置时，才会应用远程回退） - 远程模式默认值： - token：`gateway.remote.token` -> `OPENCLAW_GATEWAY_TOKEN` -> `gateway.auth.token` - password：`OPENCLAW_GATEWAY_PASSWORD` -> `gateway.remote.password` -> `gateway.auth.password` -- node-host 本地模式例外：会忽略 `gateway.remote.token` / `gateway.remote.password`。 -- 远程 probe/status token 检查默认是严格的：在以远程模式为目标时，它们只使用 `gateway.remote.token`（不回退到本地 token）。 -- Gateway 网关环境覆盖仅使用 `OPENCLAW_GATEWAY_*`。 +- Node-host 本地模式例外：忽略 `gateway.remote.token` / `gateway.remote.password`。 +- 远程 probe/status token 检查默认是严格的：在目标为远程模式时，它们只使用 `gateway.remote.token`（不会回退到本地 token）。 +- Gateway 网关环境变量覆盖仅使用 `OPENCLAW_GATEWAY_*`。 ## 通过 SSH 使用聊天 UI @@ -133,38 +136,36 @@ WebChat 不再使用单独的 HTTP 端口。SwiftUI 聊天 UI 直接连接到 Ga - 通过 SSH 转发 `18789`（见上文），然后让客户端连接到 `ws://127.0.0.1:18789`。 - 在 macOS 上，优先使用应用的“通过 SSH 远程访问”模式，它会自动管理隧道。 -## macOS 应用“通过 SSH 远程访问” +## macOS 应用的通过 SSH 远程访问 macOS 菜单栏应用可以端到端驱动同一套方案（远程状态检查、WebChat 和 Voice Wake 转发）。 -操作手册：[macOS 远程访问](/zh-CN/platforms/mac/remote)。 +操作手册： [macOS 远程访问](/zh-CN/platforms/mac/remote)。 ## 安全规则（远程 / VPN） -简短版本：除非你确定需要绑定到非回环地址，否则**保持 Gateway 网关仅绑定回环地址**。 +简短版本：**除非你确定需要绑定，否则让 Gateway 网关只绑定 loopback。** -- **回环地址 + SSH/Tailscale Serve** 是最安全的默认方案（不会公开暴露）。 -- 明文 `ws://` 默认仅限回环地址。对于受信任的私有网络， - 在客户端进程上设置 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` - 作为紧急放行手段。没有对应的 `openclaw.json` 配置项；这必须在发起 WebSocket 连接的客户端进程 - 环境中设置。 -- **非回环绑定**（`lan` / `tailnet` / `custom`，或在回环不可用时的 `auto`）必须使用 gateway 认证：token、password，或带 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。 -- `gateway.remote.token` / `.password` 是客户端凭证来源。它们**不会**单独配置服务器认证。 -- 本地调用路径只有在 `gateway.auth.*` 未设置时，才可以将 `gateway.remote.*` 用作回退。 -- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但未解析成功，则解析会失败关闭（不会用远程回退来掩盖问题）。 +- **loopback + SSH/Tailscale Serve** 是最安全的默认方案（不会公开暴露）。 +- 明文 `ws://` 默认仅限 loopback。对于受信任的私有网络， + 可在客户端进程上设置 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` + 作为应急措施。没有等价的 `openclaw.json` 配置；这必须设置在发起 + WebSocket 连接的客户端进程环境中。 +- **非 loopback 绑定**（`lan` / `tailnet` / `custom`，或在 loopback 不可用时使用 `auto`）必须使用 gateway 认证：token、password，或带有 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。 +- `gateway.remote.token` / `.password` 是客户端凭证来源。它们**不会**单独配置服务端认证。 +- 仅当 `gateway.auth.*` 未设置时，本地调用路径才可以将 `gateway.remote.*` 作为回退。 +- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但未成功解析，解析会以关闭方式失败（不会用远程回退来掩盖问题）。 - 使用 `wss://` 时，`gateway.remote.tlsFingerprint` 会固定远程 TLS 证书。 -- 当 `gateway.auth.allowTailscale: true` 时，**Tailscale Serve** 可以通过身份标头为 Control UI/WebSocket 流量提供认证；HTTP API 端点不使用这种 Tailscale 标头认证，而是遵循 gateway 的常规 HTTP - 认证模式。这个无 token 流程默认假设 gateway 主机是受信任的。如果你希望所有地方都使用共享密钥认证，请将其设为 - `false`。 -- **trusted-proxy** 认证仅适用于绑定到非回环地址、并使用身份感知代理的部署场景。 - 同主机上的回环反向代理不满足 `gateway.auth.mode: "trusted-proxy"` 的要求。 -- 将浏览器控制视为操作端访问：仅限 tailnet + 明确的节点配对。 +- 当 `gateway.auth.allowTailscale: true` 时，**Tailscale Serve** 可以通过身份标头认证 Control UI/WebSocket 流量；HTTP API 端点不会使用这种 Tailscale 标头认证，而是遵循 gateway 的常规 HTTP 认证模式。这种无 token 流程假定 gateway 主机是受信任的。如果你希望所有地方都使用共享密钥认证，请将其设为 `false`。 +- **trusted-proxy** 认证仅适用于非 loopback 的身份感知代理设置。 + 同主机上的 loopback 反向代理不满足 `gateway.auth.mode: "trusted-proxy"`。 +- 请将浏览器控制视为操作端访问：仅 tailnet + 有意识的节点配对。 -深入说明：[安全性](/zh-CN/gateway/security)。 +深入说明： [安全](/zh-CN/gateway/security)。 ### macOS：通过 LaunchAgent 持久化 SSH 隧道 -对于连接到远程 gateway 的 macOS 客户端，最简单的持久化方案是使用 SSH `LocalForward` 配置项加上 LaunchAgent，使隧道在重启和崩溃后仍能保持存活。 +对于连接到远程 gateway 的 macOS 客户端，最简单的持久化方案是使用 SSH `LocalForward` 配置项，再配合 LaunchAgent 让隧道在重启和崩溃后保持存活。 #### 第 1 步：添加 SSH 配置 @@ -178,7 +179,7 @@ Host remote-gateway IdentityFile ~/.ssh/id_rsa ``` -将 `` 和 `` 替换为你的值。 +将 `` 和 `` 替换为你的实际值。 #### 第 2 步：复制 SSH 密钥（一次性） @@ -188,7 +189,7 @@ ssh-copy-id -i ~/.ssh/id_rsa @ #### 第 3 步：配置 gateway token -将 token 存储到配置中，以便它在重启后仍然保留： +将 token 存入配置中，以便在重启后仍然保留： ```bash openclaw config set gateway.remote.token "" @@ -225,9 +226,11 @@ openclaw config set gateway.remote.token "" launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist ``` -隧道会在登录时自动启动、在崩溃后自动重启，并保持转发端口持续可用。 +该隧道会在登录时自动启动、崩溃后自动重启，并保持转发端口持续可用。 -注意：如果你还有旧部署遗留的 `com.openclaw.ssh-tunnel` LaunchAgent，请先卸载并删除它。 + +如果你有旧设置遗留的 `com.openclaw.ssh-tunnel` LaunchAgent，请先卸载并删除它。 + #### 故障排除 @@ -250,15 +253,15 @@ launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel ``` -| 配置项 | 作用 | +| 配置项 | 作用 | | ------------------------------------ | ------------------------------------------------------------ | -| `LocalForward 18789 127.0.0.1:18789` | 将本地端口 `18789` 转发到远程端口 `18789` | -| `ssh -N` | SSH 连接但不执行远程命令（仅做端口转发） | -| `KeepAlive` | 如果隧道崩溃则自动重启 | -| `RunAtLoad` | 在登录时 LaunchAgent 加载后启动隧道 | +| `LocalForward 18789 127.0.0.1:18789` | 将本地端口 18789 转发到远程端口 18789 | +| `ssh -N` | SSH 连接但不执行远程命令（仅进行端口转发） | +| `KeepAlive` | 如果隧道崩溃则自动重启 | +| `RunAtLoad` | 在登录时 LaunchAgent 加载后启动隧道 | ## 相关内容 - [Tailscale](/zh-CN/gateway/tailscale) -- [身份验证](/zh-CN/gateway/authentication) +- [Authentication](/zh-CN/gateway/authentication) - [远程 gateway 设置](/zh-CN/gateway/remote-gateway-readme) diff --git a/docs/zh-CN/install/updating.md b/docs/zh-CN/install/updating.md index ff7817307..96e38290a 100644 --- a/docs/zh-CN/install/updating.md +++ b/docs/zh-CN/install/updating.md @@ -5,15 +5,15 @@ read_when: summary: 安全更新 OpenClaw（全局安装或源码安装），以及回滚策略 title: 更新中 x-i18n: - generated_at: "2026-04-26T23:29:43Z" + generated_at: "2026-04-27T04:33:48Z" model: gpt-5.4 provider: openai - source_hash: 9ce89a768e26a5b8775794180e0f23da63040205507b0f6013210bdaafdd4856 + source_hash: ed243fbe421d379ba9b9756b2c63736f70cb9ed20a57299ccbfb8d846611efaa source_path: install/updating.md workflow: 15 --- -让 OpenClaw 保持最新。 +保持 OpenClaw 为最新版本。 ## 推荐：`openclaw update` @@ -23,7 +23,7 @@ x-i18n: openclaw update ``` -如需切换渠道或指定特定版本： +如需切换频道或指定特定版本： ```bash openclaw update --channel beta @@ -32,13 +32,13 @@ openclaw update --tag main openclaw update --dry-run # 仅预览，不实际应用 ``` -`--channel beta` 会优先选择 beta，但当 beta 标签缺失或比最新稳定版更旧时，运行时会回退到 stable/latest。若你想在一次性的包更新中使用原始 npm beta dist-tag，请使用 `--tag beta`。 +`--channel beta` 会优先选择 beta，但当 beta 标签不存在，或其版本比最新 stable 发布更旧时，运行时会回退到 stable/latest。如果你想进行一次性的包更新并使用原始 npm beta dist-tag，请使用 `--tag beta`。 -关于渠道语义，参见 [Development channels](/zh-CN/install/development-channels)。 +频道语义请参见 [Development channels](/zh-CN/install/development-channels)。 -## 在 npm 和 git 安装之间切换 +## 在 npm 安装和 git 安装之间切换 -当你想更改安装类型时，请使用渠道。更新器会保留你在 `~/.openclaw` 中的状态、配置、凭证和工作区；它只会更改 CLI 和 Gateway 网关所使用的 OpenClaw 代码安装方式。 +当你想更改安装类型时，请使用频道。更新器会保留你在 `~/.openclaw` 中的状态、配置、凭证和工作区；它只会更改 CLI 和 Gateway 网关所使用的 OpenClaw 代码安装方式。 ```bash # npm 包安装 -> 可编辑的 git 检出 @@ -48,24 +48,24 @@ openclaw update --channel dev openclaw update --channel stable ``` -先使用 `--dry-run` 运行，以预览确切的安装模式切换： +先使用 `--dry-run` 预览确切的安装模式切换： ```bash openclaw update --channel dev --dry-run openclaw update --channel stable --dry-run ``` -`dev` 渠道会确保存在一个 git 检出，构建它，并从该检出安装全局 CLI。`stable` 和 `beta` 渠道使用包安装。如果 Gateway 网关已经安装，`openclaw update` 会刷新服务元数据并重启它，除非你传入 `--no-restart`。 +`dev` 频道会确保存在一个 git 检出、构建它，并从该检出安装全局 CLI。`stable` 和 `beta` 频道使用包安装。如果 Gateway 网关已经安装，`openclaw update` 会刷新服务元数据并重启它，除非你传入 `--no-restart`。 -## 备选方式：重新运行安装器 +## 可选方案：重新运行安装器 ```bash curl -fsSL https://openclaw.ai/install.sh | bash ``` -添加 `--no-onboard` 以跳过新手引导。若要通过安装器强制指定安装类型，请传入 `--install-method git --no-onboard` 或 `--install-method npm --no-onboard`。 +添加 `--no-onboard` 以跳过新手引导。若要通过安装器强制指定安装类型，可传入 `--install-method git --no-onboard` 或 `--install-method npm --no-onboard`。 -如果 `openclaw update` 在 npm 包安装阶段之后失败，请重新运行安装器。安装器不会调用旧的更新器；它会直接运行全局包安装，并且可以恢复部分更新的 npm 安装。 +如果 `openclaw update` 在 npm 包安装阶段之后失败，请重新运行安装器。安装器不会调用旧的更新器；它会直接运行全局包安装，因此可以恢复部分更新成功的 npm 安装。 ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm @@ -77,13 +77,13 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version ``` -## 备选方式：手动使用 npm、pnpm 或 bun +## 可选方案：手动使用 npm、pnpm 或 bun ```bash npm i -g openclaw@latest ``` -当 `openclaw update` 管理全局 npm 安装时，它会先运行常规的全局安装命令。如果该命令失败，OpenClaw 会使用 `--omit=optional` 重试一次。这个重试有助于处理那些无法编译原生可选依赖的主机，同时在回退也失败时仍保留原始失败信息。 +当 `openclaw update` 管理全局 npm 安装时，它会先运行常规的全局安装命令。如果该命令失败，OpenClaw 会使用 `--omit=optional` 重试一次。这个重试有助于处理那些无法编译原生可选依赖的主机，同时如果回退方案也失败，原始错误仍然可见。 ```bash pnpm add -g openclaw@latest @@ -93,28 +93,33 @@ pnpm add -g openclaw@latest bun add -g openclaw@latest ``` -### 全局 npm 安装与运行时依赖 +### 高级 npm 安装主题 -OpenClaw 会将打包的全局安装在运行时视为只读，即使当前用户对全局包目录有写权限也是如此。内置插件的运行时依赖会暂存到一个可写的运行时目录中，而不是修改包树。这样可以避免 `openclaw update` 与正在运行的 Gateway 网关或本地智能体发生竞争，因为后者可能会在同一次安装期间修复插件依赖。 + + + 即使全局包目录对当前用户可写，OpenClaw 在运行时也会将打包的全局安装视为只读。内置插件运行时依赖会暂存到一个可写的运行时目录，而不是修改包目录树。这样可以避免 `openclaw update` 与正在运行的 Gateway 网关或本地智能体发生竞争，因为它们可能在同一次安装期间修复插件依赖。 -某些 Linux npm 配置会将全局包安装到 root 拥有的目录中，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 通过相同的外部暂存路径支持这种布局。 + 某些 Linux npm 配置会将全局包安装到 root 拥有的目录下，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 通过同一个外部暂存路径支持这种布局。 + + + 设置一个包含在 `ReadWritePaths` 中的可写暂存目录： -对于强化过的 systemd 单元，请设置一个可写的暂存目录，并将其包含在 `ReadWritePaths` 中： + ```ini + Environment=OPENCLAW_PLUGIN_STAGE_DIR=/var/lib/openclaw/plugin-runtime-deps + ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp + ``` -```ini -Environment=OPENCLAW_PLUGIN_STAGE_DIR=/var/lib/openclaw/plugin-runtime-deps -ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp -``` + 如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在 systemd 提供 `$STATE_DIRECTORY` 时优先使用它，然后回退到 `~/.openclaw/plugin-runtime-deps`。修复步骤会将该暂存目录视为 OpenClaw 自有的本地包根目录，并忽略用户的 npm prefix 和全局设置，因此全局安装的 npm 配置不会将内置插件依赖重定向到 `~/node_modules` 或全局包目录树中。 + + + 在包更新以及内置运行时依赖修复之前，OpenClaw 会尽最大努力对目标卷执行磁盘空间检查。空间不足会产生一条警告，其中包含被检查的路径，但不会阻止更新，因为文件系统配额、快照和网络卷可能会在检查后发生变化。实际的 npm 安装、复制和安装后验证仍然是最终依据。 + + + 打包安装会将内置插件运行时依赖保留在只读包目录树之外。在启动期间以及执行 `openclaw doctor --fix` 时，OpenClaw 只会为以下内置插件修复运行时依赖：在配置中处于活动状态、通过旧版渠道配置处于活动状态，或由其内置清单默认启用的插件。仅有持久化的渠道认证状态，并不会触发 Gateway 网关启动时的运行时依赖修复。 -如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在 systemd 提供 `$STATE_DIRECTORY` 时使用它，否则回退到 `~/.openclaw/plugin-runtime-deps`。修复步骤会将该暂存区视为 OpenClaw 自有的本地包根目录，并忽略用户的 npm prefix/global 设置，因此全局安装的 npm 配置不会把内置插件依赖重定向到 `~/node_modules` 或全局包树中。 - -在包更新和内置运行时依赖修复之前，OpenClaw 会尽力对目标卷执行一次磁盘空间检查。空间不足会产生一条警告，并包含所检查的路径，但不会阻止更新，因为文件系统配额、快照和网络卷可能会在检查后发生变化。实际的 npm 安装、复制和安装后验证仍然是最终依据。 - -### 内置插件运行时依赖 - -打包安装会将内置插件运行时依赖保留在只读包树之外。在启动时以及执行 `openclaw doctor --fix` 期间，OpenClaw 只会为以下内置插件修复运行时依赖：在配置中处于激活状态、通过旧版渠道配置处于激活状态，或由其内置清单默认启用。仅持久化的渠道凭证状态本身不会触发 Gateway 网关启动时的运行时依赖修复。 - -显式禁用优先。如果某个插件或渠道已被禁用，它不会仅因为存在于包中就获得运行时依赖修复。外部插件和自定义加载路径仍应使用 `openclaw plugins install` 或 `openclaw plugins update`。 + 显式禁用具有最高优先级。被禁用的插件或渠道，不会仅仅因为它存在于包中就修复其运行时依赖。外部插件和自定义加载路径仍然使用 `openclaw plugins install` 或 `openclaw plugins update`。 + + ## 自动更新器 @@ -134,13 +139,13 @@ ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp } ``` -| 渠道 | 行为 | -| -------- | ------------------------------------------------------------------------------------------------------------- | -| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内以确定性抖动方式应用（分散发布）。 | -| `beta` | 每 `betaCheckIntervalHours` 检查一次（默认：每小时），并立即应用。 | +| Channel | 行为 | +| -------- | ---- | +| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内通过确定性抖动应用更新（分散发布）。 | +| `beta` | 每隔 `betaCheckIntervalHours` 检查一次（默认：每小时），并立即应用。 | | `dev` | 不自动应用。请手动使用 `openclaw update`。 | -Gateway 网关也会在启动时记录一条更新提示（可通过 `update.checkOnStart: false` 禁用）。 +Gateway 网关还会在启动时记录更新提示（可用 `update.checkOnStart: false` 禁用）。 ## 更新后 @@ -152,7 +157,7 @@ Gateway 网关也会在启动时记录一条更新提示（可通过 `update.che openclaw doctor ``` -迁移配置、审计私信策略，并检查 Gateway 网关健康状态。详情参见：[Doctor](/zh-CN/gateway/doctor) +迁移配置、审计私信策略，并检查 Gateway 网关健康状态。详情请参见：[Doctor](/zh-CN/gateway/doctor) ### 重启 Gateway 网关 @@ -178,7 +183,9 @@ openclaw doctor openclaw gateway restart ``` -提示：`npm view openclaw version` 会显示当前已发布版本。 + +`npm view openclaw version` 会显示当前已发布的版本。 + ### 固定到某个提交（源码） @@ -189,17 +196,17 @@ pnpm install && pnpm build openclaw gateway restart ``` -如需返回最新版本：`git checkout main && git pull`。 +如需回到最新版本：`git checkout main && git pull`。 ## 如果你卡住了 -- 再次运行 `openclaw doctor`，并仔细阅读输出。 +- 再次运行 `openclaw doctor`，并仔细阅读输出内容。 - 对于源码检出上的 `openclaw update --channel dev`，更新器会在需要时自动引导安装 `pnpm`。如果你看到 pnpm/corepack 引导错误，请手动安装 `pnpm`（或重新启用 `corepack`），然后重新运行更新。 - 查看：[故障排除](/zh-CN/gateway/troubleshooting) - 在 Discord 中提问：[https://discord.gg/clawd](https://discord.gg/clawd) ## 相关内容 -- [Install Overview](/zh-CN/install) — 所有安装方式 -- [Doctor](/zh-CN/gateway/doctor) — 更新后的健康检查 -- [Migrating](/zh-CN/install/migrating) — 主要版本迁移指南 +- [安装概览](/zh-CN/install)：所有安装方法。 +- [Doctor](/zh-CN/gateway/doctor)：更新后的健康检查。 +- [迁移](/zh-CN/install/migrating)：主要版本迁移指南。 diff --git a/docs/zh-CN/providers/ollama.md b/docs/zh-CN/providers/ollama.md index 53d44403b..6360ebd94 100644 --- a/docs/zh-CN/providers/ollama.md +++ b/docs/zh-CN/providers/ollama.md @@ -1,45 +1,46 @@ --- read_when: - - 你想通过 Ollama 使用云端或本地模型运行 OpenClaw + - 你想通过 Ollama 使用云端或本地模型来运行 OpenClaw - 你需要 Ollama 的设置和配置指南 - - 你想使用 Ollama 视觉模型进行图像理解 + - 你想使用 Ollama 视觉模型来进行图像理解 summary: 使用 Ollama（云端和本地模型）运行 OpenClaw title: Ollama x-i18n: - generated_at: "2026-04-27T04:26:16Z" + generated_at: "2026-04-27T04:34:09Z" model: gpt-5.4 provider: openai - source_hash: a7b3e603309f08f9b7eb5ab3d7dbe527c7a0e54f4f4e7a38ca615d35da0d323b + source_hash: afb9ecca376bb6522eacb195e6c0c590029e3deb9e2f673505008cdc86883800 source_path: providers/ollama.md workflow: 15 --- -OpenClaw 通过 Ollama 的原生 API（`/api/chat`）集成托管云模型以及本地/自托管的 Ollama 服务器。你可以通过三种模式使用 Ollama：通过可访问的 Ollama 主机实现的 `Cloud + Local`、针对 `https://ollama.com` 的 `Cloud only`，或针对可访问的 Ollama 主机的 `Local only`。 +OpenClaw 与 Ollama 的原生 API（`/api/chat`）集成，可用于托管云模型以及本地/自托管的 Ollama 服务器。你可以通过三种模式使用 Ollama：通过可访问的 Ollama 主机实现的 `Cloud + Local`、指向 `https://ollama.com` 的 `Cloud only`，或指向可访问 Ollama 主机的 `Local only`。 -**远程 Ollama 用户**：不要在 OpenClaw 中使用 `/v1` OpenAI 兼容 URL（`http://host:11434/v1`）。这会破坏工具调用，而且模型可能会把原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL：`baseUrl: "http://host:11434"`（不要带 `/v1`）。 +**远程 Ollama 用户**：不要在 OpenClaw 中使用 `/v1` OpenAI 兼容 URL（`http://host:11434/v1`）。这会破坏工具调用，模型还可能将原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL：`baseUrl: "http://host:11434"`（不要带 `/v1`）。 -Ollama provider 配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 `baseURL`，以兼容 OpenAI SDK 风格的示例，但新的配置应优先使用 `baseUrl`。 +Ollama provider 配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 `baseURL`，以兼容 OpenAI SDK 风格的示例，但新配置应优先使用 `baseUrl`。 -### 认证规则 +## 认证规则 - 本地和局域网的 Ollama 主机不需要真实的 bearer token。对于 loopback、私有网络、`.local` 和裸主机名的 Ollama base URL，OpenClaw 仅使用本地 `ollama-local` 标记。 + 本地和局域网 Ollama 主机不需要真实的 bearer token。OpenClaw 仅对 loopback、私有网络、`.local` 和裸主机名的 Ollama base URL 使用本地 `ollama-local` 标记。 - 远程公网主机和 Ollama Cloud（`https://ollama.com`）需要通过 `OLLAMA_API_KEY`、认证配置文件或该 provider 的 `apiKey` 提供真实凭证。 + 远程公网主机和 Ollama Cloud（`https://ollama.com`）需要通过 `OLLAMA_API_KEY`、认证配置文件或 provider 的 `apiKey` 提供真实凭证。 - 将 `api: "ollama"` 设为自定义 provider id 的配置遵循相同规则。例如，指向私有局域网 Ollama 主机的 `ollama-remote` provider 可以使用 `apiKey: "ollama-local"`，子智能体会通过 Ollama provider hook 解析该标记，而不是将其视为缺失的凭证。 + 将 `api: "ollama"` 设为自定义 provider id 时，遵循相同规则。例如，指向私有局域网 Ollama 主机的 `ollama-remote` provider 可以使用 `apiKey: "ollama-local"`，子智能体会通过 Ollama provider hook 解析该标记，而不是将其视为缺失凭证。 - - 当 Ollama 用于 memory embeddings 时，bearer 认证会限定在声明它的主机范围内： + + 当 Ollama 用于 Memory 嵌入时，bearer 认证会限定在声明它的主机范围内： - - provider 级别的 key 只会发送到该 provider 的 Ollama 主机。 - - `agents.*.memorySearch.remote.apiKey` 只会发送到它自己的远程嵌入主机。 + - provider 级密钥只会发送到该 provider 的 Ollama 主机。 + - `agents.*.memorySearch.remote.apiKey` 只会发送到它的远程嵌入主机。 - 纯 `OLLAMA_API_KEY` 环境变量值会被视为 Ollama Cloud 约定，默认不会发送到本地或自托管主机。 + @@ -49,7 +50,7 @@ Ollama provider 配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 ` - **最适合：** 以最快方式完成可用的 Ollama 云端或本地设置。 + **最适合：** 以最快路径完成可用的 Ollama 云端或本地设置。 @@ -57,7 +58,7 @@ Ollama provider 配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 ` openclaw onboard ``` - 在 provider 列表中选择 **Ollama**。 + 从 provider 列表中选择 **Ollama**。 - **Cloud + Local** — 本地 Ollama 主机加上通过该主机路由的云模型 @@ -65,7 +66,7 @@ Ollama provider 配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 ` - **Local only** — 仅使用本地模型 - `Cloud only` 会提示输入 `OLLAMA_API_KEY`，并建议托管云端默认模型。`Cloud + Local` 和 `Local only` 会要求提供 Ollama base URL，发现可用模型，并在所选本地模型尚不可用时自动拉取该模型。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以获得云访问权限。 + `Cloud only` 会提示输入 `OLLAMA_API_KEY`，并推荐托管云默认模型。`Cloud + Local` 和 `Local only` 会要求提供 Ollama base URL、发现可用模型，并在所选本地模型尚不可用时自动拉取。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以启用云访问。 ```bash @@ -82,7 +83,7 @@ Ollama provider 配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 ` --accept-risk ``` - 你也可以选择指定自定义 base URL 或模型： + 你也可以指定自定义 base URL 或模型： ```bash openclaw onboard --non-interactive \ @@ -113,7 +114,7 @@ Ollama provider 配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 ` ``` - 对于 `Cloud only`，请使用真实的 `OLLAMA_API_KEY`。对于基于主机的设置，任意占位值都可以： + 对于 `Cloud only`，使用你真实的 `OLLAMA_API_KEY`。对于基于主机的设置，任意占位值都可以： ```bash # 云端 @@ -122,7 +123,7 @@ Ollama provider 配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 ` # 仅本地 export OLLAMA_API_KEY="ollama-local" - # 或在你的配置文件中进行配置 + # 或在你的配置文件中配置 openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY" ``` @@ -155,43 +156,43 @@ Ollama provider 配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 ` `Cloud + Local` 使用可访问的 Ollama 主机作为本地模型和云模型的统一控制点。这是 Ollama 推荐的混合流程。 - 在设置期间使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama base URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以获取云访问权限。当主机已登录时，OpenClaw 还会建议托管云端默认模型，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。 + 在设置期间使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama base URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以启用云访问。当主机已登录时，OpenClaw 还会推荐托管云默认模型，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。 - 如果该主机尚未登录，OpenClaw 会将设置保持为仅本地模式，直到你运行 `ollama signin`。 + 如果主机尚未登录，OpenClaw 会将设置保持为仅本地模式，直到你运行 `ollama signin`。 - `Cloud only` 针对 Ollama 的托管 API `https://ollama.com` 运行。 + `Cloud only` 通过 Ollama 的托管 API `https://ollama.com` 运行。 在设置期间使用 **Cloud only**。OpenClaw 会提示输入 `OLLAMA_API_KEY`，设置 `baseUrl: "https://ollama.com"`，并初始化托管云模型列表。此路径**不**需要本地 Ollama 服务器或 `ollama signin`。 - `openclaw onboard` 期间显示的云模型列表会从 `https://ollama.com/api/tags` 实时填充，最多 500 项，因此选择器反映的是当前托管目录，而不是静态预设。如果在设置时无法访问 `ollama.com` 或它未返回任何模型，OpenClaw 会回退到之前的硬编码建议，以确保新手引导仍可完成。 + `openclaw onboard` 中显示的云模型列表会通过 `https://ollama.com/api/tags` 实时获取，最多 500 项，因此选择器反映的是当前托管目录，而不是静态种子数据。如果设置时 `ollama.com` 不可访问或未返回模型，OpenClaw 会回退到之前的硬编码建议，以确保新手引导仍可完成。 - 在仅本地模式下，OpenClaw 会从已配置的 Ollama 实例中发现模型。此路径适用于本地或自托管 Ollama 服务器。 + 在仅本地模式下，OpenClaw 会从已配置的 Ollama 实例中发现模型。此路径适用于本地或自托管的 Ollama 服务器。 - OpenClaw 当前建议 `gemma4` 作为本地默认值。 + OpenClaw 当前推荐 `gemma4` 作为本地默认模型。 ## 模型发现（隐式 provider） -当你设置了 `OLLAMA_API_KEY`（或认证配置文件），且**没有**定义 `models.providers.ollama` 时，OpenClaw 会从 `http://127.0.0.1:11434` 的本地 Ollama 实例发现模型。 +当你设置了 `OLLAMA_API_KEY`（或认证配置文件）且**未**定义 `models.providers.ollama` 时，OpenClaw 会从位于 `http://127.0.0.1:11434` 的本地 Ollama 实例发现模型。 | 行为 | 详情 | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 目录查询 | 查询 `/api/tags` | -| 能力检测 | 使用尽力而为的 `/api/show` 查找来读取 `contextWindow`、扩展后的 `num_ctx` Modelfile 参数，以及包括 vision/tools 在内的能力 | -| 视觉模型 | 如果 `/api/show` 报告模型具有 `vision` 能力，则这些模型会被标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图像注入到提示中 | -| 推理检测 | 使用模型名称启发式（`r1`、`reasoning`、`think`）标记 `reasoning` | +| 能力检测 | 使用尽力而为的 `/api/show` 查找，以读取 `contextWindow`、展开后的 `num_ctx` Modelfile 参数，以及包括 vision/tools 在内的能力 | +| 视觉模型 | `/api/show` 报告具有 `vision` 能力的模型会被标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图像注入提示词 | +| 推理检测 | 通过模型名称启发式（`r1`、`reasoning`、`think`）标记 `reasoning` | | token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 | | 成本 | 将所有成本设置为 `0` | -这样可以避免手动添加模型条目，同时让目录与本地 Ollama 实例保持同步。 +这样可以避免手动填写模型条目，同时让目录与本地 Ollama 实例保持一致。 ```bash # 查看有哪些模型可用 @@ -199,7 +200,7 @@ ollama list openclaw models list ``` -要添加新模型，只需用 Ollama 拉取它： +要添加新模型，只需使用 Ollama 拉取它： ```bash ollama pull mistral @@ -208,21 +209,21 @@ ollama pull mistral 新模型会被自动发现并可立即使用。 -如果你显式设置了 `models.providers.ollama`，则会跳过自动发现，你必须手动定义模型。请参阅下面的显式配置部分。 +如果你显式设置了 `models.providers.ollama`，则会跳过自动发现，你必须手动定义模型。请参见下方的显式配置部分。 -## 视觉和图像描述 +## 视觉与图像描述 -内置的 Ollama 插件会将 Ollama 注册为支持图像的媒体理解 provider。这使 OpenClaw 能够通过本地或托管的 Ollama 视觉模型，路由显式的图像描述请求以及已配置的默认图像模型。 +内置的 Ollama 插件会将 Ollama 注册为支持图像的媒体理解 provider。这样 OpenClaw 就能通过本地或托管的 Ollama 视觉模型来路由显式图像描述请求，以及已配置的默认图像模型。 -对于本地视觉模型，请拉取一个支持图像的模型： +对于本地视觉功能，请拉取支持图像的模型： ```bash ollama pull qwen2.5vl:7b export OLLAMA_API_KEY="ollama-local" ``` -然后使用 infer CLI 进行验证： +然后使用 infer CLI 验证： ```bash openclaw infer image describe \ @@ -231,7 +232,7 @@ openclaw infer image describe \ --json ``` -`--model` 必须是完整的 `` 引用。设置后，`openclaw infer image describe` 会直接运行该模型，而不是因为该模型支持原生视觉而跳过描述。 +`--model` 必须是完整的 `` 引用。设置后，`openclaw infer image describe` 会直接运行该模型，而不会因为该模型支持原生视觉而跳过描述。 要让 Ollama 成为入站媒体的默认图像理解模型，请配置 `agents.defaults.imageModel`： @@ -259,7 +260,7 @@ openclaw infer image describe \ } ``` -OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。在隐式发现模式下，当 `/api/show` 报告 vision 能力时，OpenClaw 会从 Ollama 读取该信息。 +对于未标记为支持图像的模型，OpenClaw 会拒绝图像描述请求。使用隐式发现时，如果 `/api/show` 报告了 vision 能力，OpenClaw 会从 Ollama 中读取该信息。 ## 配置 @@ -278,7 +279,7 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。在 - 当你想要托管云端设置、Ollama 运行在其他主机/端口、你想强制指定特定上下文窗口或模型列表，或者你想完全手动定义模型时，请使用显式配置。 + 当你需要托管云设置、Ollama 运行在其他主机/端口上、你想强制指定特定上下文窗口或模型列表，或你希望完全手动定义模型时，请使用显式配置。 ```json5 { @@ -316,7 +317,7 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。在 providers: { ollama: { apiKey: "ollama-local", - baseUrl: "http://ollama-host:11434", // 不要加 /v1——请使用原生 Ollama API URL + baseUrl: "http://ollama-host:11434", // 不要加 /v1 - 使用原生 Ollama API URL api: "ollama", // 显式设置以确保原生工具调用行为 timeoutSeconds: 300, // 可选：为冷启动的本地模型提供更长的连接和流式传输时间 models: [ @@ -324,7 +325,7 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。在 id: "qwen3:32b", name: "qwen3:32b", params: { - keep_alive: "15m", // 可选：在多轮之间保持模型已加载状态 + keep_alive: "15m", // 可选：让模型在多轮之间保持已加载状态 }, }, ], @@ -335,7 +336,7 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。在 ``` - 不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama base URL。 + 不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama 基础 URL。 @@ -358,9 +359,12 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。在 } ``` -也支持自定义 Ollama provider id。当模型引用使用活动 provider 前缀时，例如 `ollama-spark/qwen3:32b`，OpenClaw 在调用 Ollama 前只会去掉该前缀，因此服务器收到的仍是 `qwen3:32b`。 +也支持自定义 Ollama provider id。当模型引用使用活动 +provider 前缀时，例如 `ollama-spark/qwen3:32b`，OpenClaw 在调用 Ollama 前只会去掉该 +前缀，因此服务器接收到的是 `qwen3:32b`。 -对于较慢的本地模型，优先考虑使用 provider 作用域的请求调优，而不是提高整个 Agent Runtimes 超时时间： +对于较慢的本地模型，优先考虑使用 provider 级请求调优，而不是提高 +整个智能体运行时超时时间： ```json5 { @@ -381,19 +385,22 @@ OpenClaw 会拒绝未标记为支持图像的模型的图像描述请求。在 } ``` -`timeoutSeconds` 适用于模型 HTTP 请求，包括连接建立、headers、body 流式传输以及整个受保护的 fetch 中止。`params.keep_alive` 会作为顶层 `keep_alive` 转发给 Ollama 的原生 `/api/chat` 请求；当首轮加载时间是瓶颈时，请按模型进行设置。 +`timeoutSeconds` 适用于模型 HTTP 请求，包括连接建立、 +响应头、请求体流式传输，以及整体受保护获取的中止。`params.keep_alive` +会在原生 `/api/chat` 请求中作为顶层 `keep_alive` 转发给 Ollama； +当首轮加载时间是瓶颈时，可按模型进行设置。 ## Ollama Web 搜索 OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 -| Property | 详情 | +| 属性 | 详情 | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Host | 使用你配置的 Ollama 主机（设置了 `models.providers.ollama.baseUrl` 时使用该值，否则使用 `http://127.0.0.1:11434`）；`https://ollama.com` 直接使用托管 API | -| Auth | 对于已登录的本地 Ollama 主机无需 key；对于直接使用 `https://ollama.com` 的搜索或受认证保护的主机，需要 `OLLAMA_API_KEY` 或已配置的 provider 认证 | -| Requirement | 本地/自托管主机必须处于运行状态并已通过 `ollama signin` 登录；直接使用托管搜索则需要 `baseUrl: "https://ollama.com"` 加上真实的 Ollama API key | +| 主机 | 使用你已配置的 Ollama 主机（若设置了 `models.providers.ollama.baseUrl` 则使用它，否则使用 `http://127.0.0.1:11434`）；`https://ollama.com` 直接使用托管 API | +| 认证 | 对已登录的本地 Ollama 主机无需密钥；对于直接访问 `https://ollama.com` 的搜索或受保护主机，使用 `OLLAMA_API_KEY` 或已配置的 provider 认证 | +| 要求 | 本地/自托管主机必须正在运行并已通过 `ollama signin` 登录；直接使用托管搜索则需要 `baseUrl: "https://ollama.com"` 加上真实的 Ollama API key | -在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 **Ollama Web 搜索**，或者设置： +在 `openclaw onboard` 或 `openclaw configure --section web` 中选择 **Ollama Web 搜索**，或设置： ```json5 { @@ -408,7 +415,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 ``` -完整的设置和行为细节，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。 +有关完整设置和行为细节，请参见 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。 ## 高级配置 @@ -416,10 +423,10 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 - **在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为代理使用 OpenAI 格式且不依赖原生工具调用行为时，才使用此模式。 + **在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为代理使用 OpenAI 格式，且不依赖原生工具调用行为时，才应使用此模式。 - 如果你需要改用 OpenAI 兼容端点（例如，在仅支持 OpenAI 格式的代理之后），请显式设置 `api: "openai-completions"`： + 如果你需要改用 OpenAI 兼容端点（例如在仅支持 OpenAI 格式的代理后面），请显式设置 `api: "openai-completions"`： ```json5 { @@ -428,7 +435,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 ollama: { baseUrl: "http://ollama-host:11434/v1", api: "openai-completions", - injectNumCtxForOpenAICompat: true, // 默认值：true + injectNumCtxForOpenAICompat: true, // 默认：true apiKey: "ollama-local", models: [...] } @@ -437,9 +444,9 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 } ``` - 此模式可能不支持同时使用流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 来禁用流式传输。 + 此模式可能不支持同时使用流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 禁用流式传输。 - 当 `api: "openai-completions"` 与 Ollama 一起使用时，OpenClaw 默认会注入 `options.num_ctx`，以避免 Ollama 静默回退到 4096 的上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段，请禁用此行为： + 当 Ollama 搭配 `api: "openai-completions"` 使用时，OpenClaw 默认会注入 `options.num_ctx`，以避免 Ollama 静默回退到 4096 的上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段，请禁用此行为： ```json5 { @@ -460,11 +467,11 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 - 对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，包括来自自定义 Modelfile 的更大 `PARAMETER num_ctx` 值。否则，它会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。 + 对于自动发现的模型，只要 Ollama 可提供相关信息，OpenClaw 就会使用 Ollama 报告的上下文窗口，包括来自自定义 Modelfile 的更大 `PARAMETER num_ctx` 值。否则，它会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。 - 你可以在显式 provider 配置中覆盖 `contextWindow` 和 `maxTokens`。若要在不重建 Modelfile 的情况下限制 Ollama 每次请求的运行时上下文，请设置 `params.num_ctx`；OpenClaw 会将其作为 `options.num_ctx` 发送给原生 Ollama 和 OpenAI 兼容的 Ollama 适配器。无效、零、负数和非有限值会被忽略，并回退到 `contextWindow`。 + 你可以在显式 provider 配置中覆盖 `contextWindow` 和 `maxTokens`。若要在不重建 Modelfile 的情况下限制 Ollama 的单次请求运行时上下文，请设置 `params.num_ctx`；OpenClaw 会在原生 Ollama 和 OpenAI 兼容 Ollama 适配器中都将其作为 `options.num_ctx` 发送。无效值、零、负数以及非有限值会被忽略，并回退到 `contextWindow`。 - 原生 Ollama 模型条目还支持在 `params` 下使用常见的 Ollama 运行时选项，包括 `temperature`、`top_p`、`top_k`、`min_p`、`num_predict`、`stop`、`repeat_penalty`、`num_batch`、`num_thread` 和 `use_mmap`。OpenClaw 只会转发 Ollama 请求键，因此像 `streaming` 这样的 OpenClaw 运行时参数不会泄露给 Ollama。使用 `params.think` 或 `params.thinking` 可以发送顶层 Ollama `think`；对于 Qwen 风格的 thinking 模型，`false` 会禁用 API 级 thinking。 + 原生 Ollama 模型条目也支持在 `params` 下配置常见的 Ollama 运行时选项，包括 `temperature`、`top_p`、`top_k`、`min_p`、`num_predict`、`stop`、`repeat_penalty`、`num_batch`、`num_thread` 和 `use_mmap`。OpenClaw 只会转发 Ollama 请求键，因此像 `streaming` 这样的 OpenClaw 运行时参数不会泄露给 Ollama。使用 `params.think` 或 `params.thinking` 可发送顶层 Ollama `think`；对 Qwen 风格思考模型，`false` 会禁用 API 级思考。 ```json5 { @@ -490,12 +497,12 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 } ``` - 每模型的 `agents.defaults.models["ollama/"].params.num_ctx` 也可以使用。如果两者都已配置，则显式 provider 模型条目的优先级高于智能体默认值。 + 按模型配置的 `agents.defaults.models["ollama/"].params.num_ctx` 也同样有效。如果两者都已配置，则显式 provider 模型条目优先于智能体默认值。 - OpenClaw 默认将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为具备推理能力。 + OpenClaw 默认将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 等字样的模型视为支持推理的模型。 ```bash ollama pull deepseek-r1:32b @@ -506,18 +513,21 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 - Ollama 是免费的并且在本地运行，因此所有模型成本都设置为 $0。这同时适用于自动发现和手动定义的模型。 + Ollama 是免费的，并且在本地运行，因此所有模型成本都设为 $0。这同时适用于自动发现和手动定义的模型。 - 内置的 Ollama 插件会为 [memory search](/zh-CN/concepts/memory) 注册一个 memory embedding provider。它使用已配置的 Ollama base URL 和 API key，调用 Ollama 当前的 `/api/embed` 端点，并在可能时将多个 memory 块批量合并到一个 `input` 请求中。 + 内置的 Ollama 插件为 + [memory search](/zh-CN/concepts/memory) 注册了一个 Memory 嵌入 provider。它使用已配置的 Ollama base URL + 和 API key，调用 Ollama 当前的 `/api/embed` 端点，并在可能时 + 将多个 memory 块批量合并到一个 `input` 请求中。 - | Property | Value | + | 属性 | 值 | | ------------- | ------------------- | - | Default model | `nomic-embed-text` | - | Auto-pull | 是——如果嵌入模型在本地不存在，将自动拉取 | + | 默认模型 | `nomic-embed-text` | + | 自动拉取 | 是 — 如果嵌入模型在本地不存在，会自动拉取 | - 要将 Ollama 选作 memory search 的嵌入 provider： + 要选择 Ollama 作为 memory search 的嵌入 provider： ```json5 { @@ -532,12 +542,12 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 - OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），它完全支持同时进行流式传输和工具调用。不需要任何特殊配置。 + OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），它完全支持同时进行流式传输和工具调用。不需要特殊配置。 - 对于原生 `/api/chat` 请求，OpenClaw 也会直接将 thinking 控制转发给 Ollama：`/think off` 和 `openclaw agent --thinking off` 会发送顶层 `think: false`，而 `/think low|medium|high` 会发送对应的顶层 `think` 强度字符串。`/think max` 会映射为 Ollama 的最高原生强度，即 `think: "high"`。 + 对于原生 `/api/chat` 请求，OpenClaw 还会直接将思考控制转发给 Ollama：`/think off` 和 `openclaw agent --thinking off` 会发送顶层 `think: false`，而 `/think low|medium|high` 会发送对应的顶层 `think` 强度字符串。`/think max` 会映射到 Ollama 原生最高强度，即 `think: "high"`。 - 如果你需要使用 OpenAI 兼容端点，请参阅上面的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。 + 如果你需要使用 OpenAI 兼容端点，请参见上方的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。 @@ -562,10 +572,10 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 - 如果你的模型未列出，请在本地拉取该模型，或在 `models.providers.ollama` 中显式定义它。 + 如果列表中没有你的模型，请在本地拉取该模型，或在 `models.providers.ollama` 中显式定义它。 ```bash - ollama list # 查看已安装的模型 + ollama list # 查看已安装内容 ollama pull gemma4 ollama pull gpt-oss:20b ollama pull llama3.3 # 或其他模型 @@ -580,14 +590,14 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 # 检查 Ollama 是否正在运行 ps aux | grep ollama - # 或重新启动 Ollama + # 或重启 Ollama ollama serve ``` - - 大型本地模型在开始流式传输前，首次加载可能需要较长时间。请将超时限制在 Ollama provider 范围内，并可选择要求 Ollama 在多轮之间保持模型已加载状态： + + 大型本地模型在开始流式传输前，首次加载可能需要较长时间。请将超时设置限制在 Ollama provider 范围内，并可选地要求 Ollama 在多轮之间保持模型已加载： ```json5 { @@ -608,7 +618,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 } ``` - 如果主机本身接受连接的速度很慢，`timeoutSeconds` 也会延长该 provider 的受保护 Undici 连接超时时间。 + 如果主机本身接受连接很慢，`timeoutSeconds` 也会为该 provider 延长受保护的 Undici 连接超时。 @@ -621,13 +631,13 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。 - 所有 provider、模型引用和故障转移行为的概览。 + 所有 provider、模型引用和故障切换行为概览。 如何选择和配置模型。 - 由 Ollama 驱动的网页搜索的完整设置和行为细节。 + 关于 Ollama 驱动网页搜索的完整设置和行为细节。 完整配置参考。 diff --git a/docs/zh-CN/providers/vllm.md b/docs/zh-CN/providers/vllm.md index ce5e198e4..955d757bd 100644 --- a/docs/zh-CN/providers/vllm.md +++ b/docs/zh-CN/providers/vllm.md @@ -1,25 +1,23 @@ --- read_when: - - 你想让 OpenClaw 对接本地 vLLM 服务器运行 - - 你希望使用兼容 OpenAI 的 `/v1` 端点，并接入你自己的模型 + - 你想让 OpenClaw 连接到本地 vLLM 服务器运行 + - 你想使用 OpenAI 兼容的 `/v1` 端点和你自己的模型 summary: 使用 vLLM（兼容 OpenAI 的本地服务器）运行 OpenClaw title: vLLM x-i18n: - generated_at: "2026-04-26T03:01:23Z" + generated_at: "2026-04-27T04:34:10Z" model: gpt-5.4 provider: openai - source_hash: fbf424cb532f2b3e188c39545b187e5db6274ff2fadc01c9e4cb0901dbe9824c + source_hash: 60d82c078af1e7565900eab879d30fe4e6c6ee4f3733df6f19d5f30d5cbd0b59 source_path: providers/vllm.md workflow: 15 --- -vLLM 可以通过 **兼容 OpenAI** 的 HTTP API 提供开源模型（以及一些自定义模型）。OpenClaw 使用 `openai-completions` API 连接到 vLLM。 +vLLM 可以通过 **OpenAI 兼容** 的 HTTP API 提供开源模型（以及一些自定义模型）。OpenClaw 使用 `openai-completions` API 连接到 vLLM。 -当你设置 `VLLM_API_KEY` 以启用此功能时（如果你的服务器不强制验证，任意值都可以），并且你没有定义显式的 `models.providers.vllm` 条目，OpenClaw 还可以从 vLLM **自动发现** 可用模型。 +当你选择启用 `VLLM_API_KEY` 时，OpenClaw 还可以从 vLLM **自动发现** 可用模型（如果你的服务器不强制要求认证，任意值都可以），前提是你没有定义显式的 `models.providers.vllm` 条目。 -OpenClaw 将 `vllm` 视为本地的兼容 OpenAI 的提供商，并支持 -流式使用量统计，因此状态 / 上下文令牌计数可以根据 -`stream_options.include_usage` 响应进行更新。 +OpenClaw 将 `vllm` 视为支持流式用量统计的本地 OpenAI 兼容提供商，因此状态/上下文 token 计数可以通过 `stream_options.include_usage` 响应进行更新。 | 属性 | 值 | | ---------------- | ---------------------------------------- | @@ -32,7 +30,7 @@ OpenClaw 将 `vllm` 视为本地的兼容 OpenAI 的提供商，并支持 - 你的 base URL 应该暴露 `/v1` 端点（例如 `/v1/models`、`/v1/chat/completions`）。vLLM 通常运行在： + 你的 base URL 应暴露 `/v1` 端点（例如 `/v1/models`、`/v1/chat/completions`）。vLLM 通常运行在： ``` http://127.0.0.1:8000/v1 @@ -40,7 +38,7 @@ OpenClaw 将 `vllm` 视为本地的兼容 OpenAI 的提供商，并支持 - 如果你的服务器不强制认证，任意值都可以： + 如果你的服务器不强制要求认证，任意值都可以： ```bash export VLLM_API_KEY="vllm-local" @@ -48,7 +46,7 @@ OpenClaw 将 `vllm` 视为本地的兼容 OpenAI 的提供商，并支持 - 替换为你的某个 vLLM 模型 ID： + 替换为你的 vLLM 模型 ID 之一： ```json5 { @@ -87,9 +85,9 @@ GET http://127.0.0.1:8000/v1/models 在以下情况下使用显式配置： - vLLM 运行在不同的主机或端口上 -- 你想固定 `contextWindow` 或 `maxTokens` 的值 +- 你想固定 `contextWindow` 或 `maxTokens` 值 - 你的服务器需要真实的 API 密钥（或者你想控制请求头） -- 你连接到受信任的 loopback、LAN 或 Tailscale vLLM 端点 +- 你要连接到受信任的 loopback、LAN 或 Tailscale vLLM 端点 ```json5 { @@ -100,6 +98,7 @@ GET http://127.0.0.1:8000/v1/models apiKey: "${VLLM_API_KEY}", api: "openai-completions", request: { allowPrivateNetwork: true }, + timeoutSeconds: 300, // 可选：为较慢的本地模型延长连接/请求头/响应体/请求超时 models: [ { id: "your-model-id", @@ -121,24 +120,21 @@ GET http://127.0.0.1:8000/v1/models - vLLM 被视为代理式的兼容 OpenAI 的 `/v1` 后端，而不是原生 - OpenAI 端点。这意味着： + vLLM 被视为代理式的 OpenAI 兼容 `/v1` 后端，而不是原生的 OpenAI 端点。这意味着： | 行为 | 是否应用？ | |----------|----------| - | 原生 OpenAI 请求塑形 | 否 | + | 原生 OpenAI 请求整形 | 否 | | `service_tier` | 不发送 | | 响应 `store` | 不发送 | | 提示缓存提示 | 不发送 | - | OpenAI 推理兼容载荷塑形 | 不应用 | + | OpenAI reasoning 兼容负载整形 | 不应用 | | 隐藏的 OpenClaw 归因请求头 | 在自定义 base URL 上不注入 | - vLLM / Nemotron 3 可以使用聊天模板 kwargs 来控制推理内容是 - 作为隐藏推理返回，还是作为可见答案文本返回。当 OpenClaw 会话 - 使用 `vllm/nemotron-3-*` 且关闭 thinking 时，OpenClaw 会发送： + vLLM/Nemotron 3 可以使用 chat-template kwargs 来控制推理内容是作为隐藏推理返回，还是作为可见答案文本返回。当 OpenClaw 会话在关闭 thinking 的情况下使用 `vllm/nemotron-3-*` 时，OpenClaw 会发送： ```json { @@ -150,8 +146,7 @@ GET http://127.0.0.1:8000/v1/models ``` 要自定义这些值，请在模型参数下设置 `chat_template_kwargs`。 - 如果你还设置了 `params.extra_body.chat_template_kwargs`，该值将拥有 - 最终优先级，因为 `extra_body` 是对请求体的最后覆盖。 + 如果你同时设置了 `params.extra_body.chat_template_kwargs`，该值将具有最终优先级，因为 `extra_body` 是最后应用的请求体覆盖项。 ```json5 { @@ -186,6 +181,7 @@ GET http://127.0.0.1:8000/v1/models apiKey: "${VLLM_API_KEY}", api: "openai-completions", request: { allowPrivateNetwork: true }, + timeoutSeconds: 300, models: [ { id: "my-custom-model", @@ -208,18 +204,40 @@ GET http://127.0.0.1:8000/v1/models ## 故障排除 - + + 对于大型本地模型、远程 LAN 主机或 tailnet 链路，请设置提供商范围的请求超时： + + ```json5 + { + models: { + providers: { + vllm: { + baseUrl: "http://192.168.1.50:8000/v1", + apiKey: "${VLLM_API_KEY}", + api: "openai-completions", + request: { allowPrivateNetwork: true }, + timeoutSeconds: 300, + models: [{ id: "your-model-id", name: "Local vLLM Model" }], + }, + }, + }, + } + ``` + + `timeoutSeconds` 仅适用于 vLLM 模型 HTTP 请求，包括连接建立、响应头、响应体流传输以及受保护获取的总中止时间。在提高控制整个智能体运行的 `agents.defaults.timeoutSeconds` 之前，优先使用此设置。 + + + + 检查 vLLM 服务器是否正在运行并且可访问： ```bash curl http://127.0.0.1:8000/v1/models ``` - 如果你看到连接错误，请确认主机、端口，以及 vLLM 是否以兼容 OpenAI 的服务器模式启动。 - 对于显式的 loopback、LAN 或 Tailscale 端点，还需要设置 - `models.providers.vllm.request.allowPrivateNetwork: true`；提供商 - 请求默认会阻止私有网络 URL，除非该提供商被 - 显式信任。 + 如果你看到连接错误，请确认主机、端口以及 vLLM 是否以兼容 OpenAI 的服务器模式启动。 + 对于显式的 loopback、LAN 或 Tailscale 端点，还要设置 + `models.providers.vllm.request.allowPrivateNetwork: true`；默认情况下，除非显式信任该提供商，否则提供商请求会阻止私有网络 URL。 @@ -227,13 +245,13 @@ GET http://127.0.0.1:8000/v1/models 如果请求因认证错误而失败，请设置与你的服务器配置匹配的真实 `VLLM_API_KEY`，或者在 `models.providers.vllm` 下显式配置该提供商。 - 如果你的 vLLM 服务器不强制认证，任意非空的 `VLLM_API_KEY` 值都可以作为 OpenClaw 的启用信号。 + 如果你的 vLLM 服务器不强制要求认证，任何非空的 `VLLM_API_KEY` 值都可以作为 OpenClaw 的启用信号。 - - 自动发现要求设置 `VLLM_API_KEY`，**并且**不能存在显式的 `models.providers.vllm` 配置条目。如果你已经手动定义了该提供商，OpenClaw 会跳过发现，只使用你声明的模型。 + + 自动发现要求设置 `VLLM_API_KEY`，**并且**不能存在显式的 `models.providers.vllm` 配置条目。如果你已手动定义该提供商，OpenClaw 会跳过发现，只使用你声明的模型。 @@ -248,7 +266,7 @@ GET http://127.0.0.1:8000/v1/models 选择提供商、模型引用和故障切换行为。 - 原生 OpenAI provider 和兼容 OpenAI 的路由行为。 + 原生 OpenAI provider 和 OpenAI 兼容路由行为。 认证细节和凭证复用规则。