diff --git a/docs/zh-CN/providers/anthropic.md b/docs/zh-CN/providers/anthropic.md index 4ac6198a0..915ac6c5c 100644 --- a/docs/zh-CN/providers/anthropic.md +++ b/docs/zh-CN/providers/anthropic.md @@ -4,10 +4,10 @@ read_when: summary: 在 OpenClaw 中通过 API 密钥或 Claude CLI 使用 Anthropic Claude title: Anthropic x-i18n: - generated_at: "2026-04-12T09:49:15Z" + generated_at: "2026-04-12T11:08:22Z" model: gpt-5.4 provider: openai - source_hash: dabb5adc0d626995c3649c57cf4e1a94e48ce8908c004eecc21582af9c227f4d + source_hash: 5e3dda5f98ade9d4c3841888103bfb43d59e075d358a701ed0ae3ffb8d5694a7 source_path: providers/anthropic.md workflow: 15 --- @@ -17,25 +17,28 @@ x-i18n: Anthropic 构建了 **Claude** 模型系列。OpenClaw 支持两种认证方式： - **API 密钥** — 直接访问 Anthropic API，并按使用量计费（`anthropic/*` 模型） -- **Claude CLI** — 复用同一主机上现有的 Claude CLI 登录 +- **Claude CLI** — 在同一主机上复用现有的 Claude CLI 登录 -Anthropic 员工告诉我们，OpenClaw 这种风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为已获认可。 +Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 +除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` +用法视为已获认可。 -对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是最清晰、最可预测的生产路径。 +对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是最明确且 +最可预测的生产路径。 Anthropic 当前的公开文档： -- [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference) -- [Claude Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview) -- [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) -- [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/) +- [Claude Code CLI 参考](https://code.claude.com/docs/en/cli-reference) +- [Claude Agent SDK 概览](https://platform.claude.com/docs/en/agent-sdk/overview) +- [在你的 Pro 或 Max 套餐中使用 Claude Code](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) +- [在你的 Team 或 Enterprise 套餐中使用 Claude Code](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/) ## 入门指南 - + **最适合：** 标准 API 访问和按使用量计费。 @@ -48,7 +51,7 @@ Anthropic 当前的公开文档： # choose: Anthropic API key ``` - 或直接传入密钥： + 或者直接传入密钥： ```bash openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" @@ -77,7 +80,7 @@ Anthropic 当前的公开文档： - 通过以下命令验证： + 验证方式如下： ```bash claude --version @@ -99,7 +102,7 @@ Anthropic 当前的公开文档： - Claude CLI 后端的设置和运行时细节见 [CLI Backends](/zh-CN/gateway/cli-backends)。 + Claude CLI 后端的设置与运行时细节见 [CLI 后端](/zh-CN/gateway/cli-backends)。 @@ -109,11 +112,11 @@ Anthropic 当前的公开文档： -## Thinking 默认设置（Claude 4.6） +## 思考默认值（Claude 4.6） -当未设置显式的 thinking 级别时，Claude 4.6 模型在 OpenClaw 中默认使用 `adaptive` thinking。 +当未设置显式思考级别时，Claude 4.6 模型在 OpenClaw 中默认使用 `adaptive` 思考。 -可通过 `/think:` 按消息覆盖，或在模型参数中设置： +可通过 `/think:` 为每条消息覆盖，或在模型参数中设置： ```json5 { @@ -131,19 +134,19 @@ Anthropic 当前的公开文档： 相关 Anthropic 文档： -- [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking) -- [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) +- [自适应思考](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking) +- [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) -## 提示缓存 +## 提示词缓存 -OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。 +OpenClaw 支持 Anthropic 在 API 密钥认证下的提示词缓存功能。 -| 值 | 缓存时长 | 描述 | -| ------------------- | -------- | ------------------------------------ | -| `"short"`（默认） | 5 分钟 | 对 API 密钥认证自动应用 | -| `"long"` | 1 小时 | 扩展缓存 | -| `"none"` | 不缓存 | 禁用提示缓存 | +| 值 | 缓存时长 | 说明 | +| ------------------- | -------- | ------------------------------ | +| `"short"`（默认） | 5 分钟 | 对 API 密钥认证自动启用 | +| `"long"` | 1 小时 | 扩展缓存 | +| `"none"` | 不缓存 | 禁用提示词缓存 | ```json5 { @@ -161,7 +164,7 @@ OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。 - 使用模型级 `params` 作为基线，然后通过 `agents.list[].params` 覆盖特定智能体： + 使用模型级参数作为基线，然后通过 `agents.list[].params` 覆盖特定智能体： ```json5 { @@ -187,14 +190,14 @@ OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。 1. `agents.defaults.models["provider/model"].params` 2. `agents.list[].params`（匹配 `id`，按键覆盖） - 这样可以让一个智能体保留长期缓存，而同一模型上的另一个智能体为突发性或低复用流量禁用缓存。 + 这样可以让一个智能体保留长期缓存，而同一模型上的另一个智能体则为突发型 / 低复用流量禁用缓存。 - Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）在已配置时接受 `cacheRetention` 透传。 - - 非 Anthropic 的 Bedrock 模型在运行时会被强制设置为 `cacheRetention: "none"`。 - - 当未设置显式值时，API 密钥的智能默认值也会为 Bedrock 上的 Claude 引用注入 `cacheRetention: "short"`。 + - 非 Anthropic 的 Bedrock 模型会在运行时被强制设为 `cacheRetention: "none"`。 + - 当未设置显式值时，API 密钥的智能默认值也会为 Bedrock 上的 Claude 引用预填 `cacheRetention: "short"`。 @@ -202,7 +205,7 @@ OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。 - OpenClaw 的共享 `/fast` 切换支持直连 Anthropic 流量（API 密钥以及到 `api.anthropic.com` 的 OAuth）。 + OpenClaw 的共享 `/fast` 开关支持直连 Anthropic 流量（API 密钥以及面向 `api.anthropic.com` 的 OAuth）。 | Command | Maps to | |---------|---------| @@ -225,14 +228,29 @@ OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。 - 仅对直连 `api.anthropic.com` 的请求注入。代理路由会保持 `service_tier` 不变。 - - 当同时设置时，显式的 `serviceTier` 或 `service_tier` 参数会覆盖 `/fast`。 - - 对于没有 Priority Tier 容量的账户，`service_tier: "auto"` 可能会解析为 `standard`。 + - 如果同时设置了显式 `serviceTier` 或 `service_tier` 参数，它们会覆盖 `/fast`。 + - 在没有 Priority Tier 容量的账户上，`service_tier: "auto"` 可能会解析为 `standard`。 - - Anthropic 的 1M 上下文窗口受 beta 限制控制。可按模型启用： + + 内置的 Anthropic 插件注册了图片和 PDF 理解能力。OpenClaw + 会根据已配置的 Anthropic 认证自动解析媒体能力——无需 + 额外配置。 + + | Property | Value | + | --------------- | -------------------- | + | Default model | `claude-opus-4-6` | + | Supported input | Images, PDF documents | + + 当图片或 PDF 附加到会话中时，OpenClaw 会自动 + 通过 Anthropic 媒体理解提供商进行路由。 + + + + + Anthropic 的 1M 上下文窗口受测试版权限控制。请按模型启用： ```json5 { @@ -251,7 +269,7 @@ OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。 OpenClaw 会将其映射为请求中的 `anthropic-beta: context-1m-2025-08-07`。 - 需要你的 Anthropic 凭证具备长上下文访问权限。旧版令牌认证（`sk-ant-oat-*`）会被拒绝用于 1M 上下文请求——OpenClaw 会记录一条警告，并回退到标准上下文窗口。 + 需要你的 Anthropic 凭证具备长上下文访问权限。旧版令牌认证（`sk-ant-oat-*`）不支持 1M 上下文请求——OpenClaw 会记录一条警告并回退到标准上下文窗口。 @@ -261,19 +279,19 @@ OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。 - Anthropic 令牌认证可能会过期或被撤销。对于新的设置，请迁移到 Anthropic API 密钥。 + Anthropic 令牌认证可能过期或被撤销。对于新配置，建议迁移到 Anthropic API 密钥。 - 认证是**按智能体**进行的。新智能体不会继承主智能体的密钥。请为该智能体重新运行新手引导，或在 Gateway 网关主机上配置 API 密钥，然后使用 `openclaw models status` 验证。 + 认证是**按智能体**区分的。新智能体不会继承主智能体的密钥。请为该智能体重新运行新手引导，或在 Gateway 网关主机上配置 API 密钥，然后使用 `openclaw models status` 验证。 - 运行 `openclaw models status` 查看当前启用了哪个认证配置文件。重新运行新手引导，或为该配置文件路径配置 API 密钥。 + 运行 `openclaw models status` 以查看当前启用的是哪个认证配置文件。重新运行新手引导，或为该配置文件路径配置 API 密钥。 - 检查 `openclaw models status --json` 中的 `auth.unusableProfiles`。Anthropic 的速率限制冷却可能是按模型范围生效的，因此同级的另一个 Anthropic 模型仍可能可用。添加另一个 Anthropic 配置文件，或等待冷却结束。 + 检查 `openclaw models status --json` 中的 `auth.unusableProfiles`。Anthropic 的速率限制冷却可能是按模型作用域生效的，因此同级的其他 Anthropic 模型可能仍可使用。添加另一个 Anthropic 配置文件，或等待冷却结束。 @@ -285,13 +303,13 @@ OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。 - 选择提供商、模型引用和故障转移行为。 + 选择提供商、模型引用和故障切换行为。 - Claude CLI 后端设置和运行时细节。 + Claude CLI 后端设置与运行时细节。 - - 提示缓存在各提供商间的工作方式。 + + 提示词缓存在各提供商中的工作方式。 认证细节和凭证复用规则。 diff --git a/docs/zh-CN/providers/github-copilot.md b/docs/zh-CN/providers/github-copilot.md index fcd69fd66..b585bff44 100644 --- a/docs/zh-CN/providers/github-copilot.md +++ b/docs/zh-CN/providers/github-copilot.md @@ -5,23 +5,23 @@ read_when: summary: 使用设备流程从 OpenClaw 登录 GitHub Copilot title: GitHub Copilot x-i18n: - generated_at: "2026-04-12T10:30:09Z" + generated_at: "2026-04-12T11:08:20Z" model: gpt-5.4 provider: openai - source_hash: 147a3c2d37919a36e54fb2739a54500be7ebd34eeed0efe3bde448da7376d541 + source_hash: 51fee006e7d4e78e37b0c29356b0090b132de727d99b603441767d3fb642140b source_path: providers/github-copilot.md workflow: 15 --- # GitHub Copilot -GitHub Copilot 是 GitHub 的 AI 编码助手。它会为你的 GitHub 账号和套餐提供对 Copilot 模型的访问。OpenClaw 可以通过两种不同方式将 Copilot 用作模型提供商。 +GitHub Copilot 是 GitHub 的 AI 编码助手。它会为你的 GitHub 账号和订阅计划提供对 Copilot 模型的访问权限。OpenClaw 可以通过两种不同方式将 Copilot 用作模型提供商。 ## 在 OpenClaw 中使用 Copilot 的两种方式 - 使用原生设备登录流程获取 GitHub 令牌，然后在 OpenClaw 运行时将其交换为 Copilot API 令牌。这是**默认**且最简单的路径，因为它不需要 VS Code。 + 使用原生设备登录流程获取 GitHub 令牌，然后在 OpenClaw 运行时将其交换为 Copilot API 令牌。这是**默认**且最简单的方式，因为它不需要 VS Code。 @@ -29,7 +29,7 @@ GitHub Copilot 是 GitHub 的 AI 编码助手。它会为你的 GitHub 账号和 openclaw models auth login-github-copilot ``` - 系统会提示你访问一个 URL 并输入一次性代码。在流程完成之前，请保持终端打开。 + 系统会提示你访问一个 URL 并输入一次性代码。在流程完成前，请保持终端处于打开状态。 ```bash @@ -49,10 +49,10 @@ GitHub Copilot 是 GitHub 的 AI 编码助手。它会为你的 GitHub 账号和 - 使用 **Copilot Proxy** VS Code 扩展作为本地桥接。OpenClaw 会连接到该代理的 `/v1` 端点，并使用你在其中配置的模型列表。 + 使用 **Copilot Proxy** VS Code 扩展作为本地桥接。OpenClaw 会与代理的 `/v1` 端点通信，并使用你在其中配置的模型列表。 - 如果你已经在 VS Code 中运行 Copilot Proxy，或者需要通过它进行路由，请选择此项。你必须启用该插件，并保持 VS Code 扩展持续运行。 + 如果你已经在 VS Code 中运行 Copilot Proxy，或需要通过它进行路由，请选择此方式。你必须启用该插件，并保持 VS Code 扩展持续运行。 @@ -60,7 +60,7 @@ GitHub Copilot 是 GitHub 的 AI 编码助手。它会为你的 GitHub 账号和 ## 可选标志 -| Flag | 说明 | +| Flag | 描述 | | --------------- | --------------------------------------------------- | | `--yes` | 跳过确认提示 | | `--set-default` | 同时应用该提供商推荐的默认模型 | @@ -75,19 +75,32 @@ openclaw models auth login --provider github-copilot --method device --set-defau - 设备登录流程需要交互式 TTY。请直接在终端中运行，而不要在非交互式脚本或 CI 流水线中运行。 + 设备登录流程需要交互式 TTY。请直接在终端中运行，不要在非交互式脚本或 CI 流水线中运行。 - - Copilot 模型的可用性取决于你的 GitHub 套餐。如果某个模型被拒绝，请尝试其他 ID（例如 `github-copilot/gpt-4.1`）。 + + Copilot 模型的可用性取决于你的 GitHub 订阅计划。如果某个模型被拒绝，请尝试其他 ID（例如 `github-copilot/gpt-4.1`）。 - - Claude 模型 ID 会自动使用 Anthropic Messages 传输协议。GPT、o-series 和 Gemini 模型会继续使用 OpenAI Responses 传输协议。OpenClaw 会根据模型 ref 选择正确的传输协议。 + + Claude 模型 ID 会自动使用 Anthropic Messages 传输方式。GPT、o-series 和 Gemini 模型会继续使用 OpenAI Responses 传输方式。OpenClaw 会根据模型 ref 选择正确的传输方式。 + + + + OpenClaw 会按以下优先级顺序从环境变量中解析 Copilot 身份验证信息： + + | Priority | Variable | 说明 | + | -------- | --------------------- | -------------------------------- | + | 1 | `COPILOT_GITHUB_TOKEN` | 最高优先级，Copilot 专用 | + | 2 | `GH_TOKEN` | GitHub CLI 令牌（回退） | + | 3 | `GITHUB_TOKEN` | 标准 GitHub 令牌（最低优先级） | + + 当设置了多个环境变量时，OpenClaw 会使用优先级最高的那个。设备登录流程（`openclaw models auth login-github-copilot`）会将其令牌存储到身份验证配置文件存储中，并且优先于所有环境变量。 + - 登录会将 GitHub 令牌存储在认证配置文件存储中，并在 OpenClaw 运行时将其交换为 Copilot API 令牌。你不需要手动管理该令牌。 + 登录流程会将 GitHub 令牌存储到身份验证配置文件存储中，并在 OpenClaw 运行时将其交换为 Copilot API 令牌。你无需手动管理该令牌。 @@ -99,9 +112,9 @@ openclaw models auth login --provider github-copilot --method device --set-defau - 选择提供商、模型 ref 和故障切换行为。 + 选择提供商、模型 ref 和故障转移行为。 - - 认证细节和凭证复用规则。 + + 身份验证细节和凭证复用规则。 diff --git a/docs/zh-CN/providers/ollama.md b/docs/zh-CN/providers/ollama.md index 6e9ddbc09..b6fe4361d 100644 --- a/docs/zh-CN/providers/ollama.md +++ b/docs/zh-CN/providers/ollama.md @@ -1,33 +1,33 @@ --- read_when: - - 你想通过 Ollama 使用云端或本地模型来运行 OpenClaw + - 你想通过 Ollama 使用云端或本地模型运行 OpenClaw - 你需要 Ollama 的设置和配置指南 summary: 使用 Ollama 运行 OpenClaw（云端和本地模型） title: Ollama x-i18n: - generated_at: "2026-04-12T10:03:23Z" + generated_at: "2026-04-12T11:08:21Z" model: gpt-5.4 provider: openai - source_hash: 48c956d7b933d2ac637784eff1f0613b15a2b3eb5da7c030133427a73b064117 + source_hash: ec796241b884ca16ec7077df4f3f1910e2850487bb3ea94f8fdb37c77e02b219 source_path: providers/ollama.md workflow: 15 --- # Ollama -Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上运行开源模型。OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），支持流式传输和工具调用，并且当你选择启用 `OLLAMA_API_KEY`（或认证配置文件）且未定义显式的 `models.providers.ollama` 条目时，可以自动发现本地 Ollama 模型。 +Ollama 是一个本地 LLM 运行时，让你可以轻松在自己的机器上运行开源模型。OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），支持流式传输和工具调用，并且当你通过 `OLLAMA_API_KEY`（或认证配置）启用时，且未显式定义 `models.providers.ollama` 条目，它可以自动发现本地 Ollama 模型。 -**远程 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 设置，并自动发现模型。 + **最适合：** 以最快路径完成可用的 Ollama 设置，并自动发现模型。 @@ -35,16 +35,16 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上 openclaw onboard ``` - 在提供商列表中选择 **Ollama**。 + 从提供商列表中选择 **Ollama**。 - - **云端 + 本地** — 同时使用云端托管模型和本地模型 - - **仅本地** — 仅使用本地模型 + - **Cloud + Local** — 同时使用云端托管模型和本地模型 + - **Local** — 仅使用本地模型 - 如果你选择 **云端 + 本地** 且尚未登录 ollama.com，新手引导会打开浏览器登录流程。 + 如果你选择 **Cloud + Local**，但尚未登录 ollama.com，新手引导会打开浏览器登录流程。 - 新手引导会发现可用模型并推荐默认项。如果所选模型在本地不可用，它会自动拉取该模型。 + 新手引导会发现可用模型并推荐默认选项。如果所选模型尚未在本地可用，它会自动拉取该模型。 ```bash @@ -61,7 +61,7 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上 --accept-risk ``` - 你也可以选择性指定自定义基础 URL 或模型： + 你也可以选择性指定自定义 base URL 或模型： ```bash openclaw onboard --non-interactive \ @@ -74,7 +74,7 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上 - **最适合：** 完全掌控安装、模型拉取和配置。 + **最适合：** 完全控制安装、模型拉取和配置。 @@ -90,7 +90,7 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上 ``` - 如果你还想使用云端模型： + 如果你也想使用云端模型： ```bash ollama signin @@ -107,7 +107,7 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上 openclaw config set models.providers.ollama.apiKey "ollama-local" ``` - + ```bash openclaw models list openclaw models set ollama/gemma4 @@ -133,10 +133,10 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上 ## 云端模型 - - 云端模型让你能够在使用本地模型的同时，也使用云端托管模型。例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud` —— 这些都**不需要**本地执行 `ollama pull`。 + + 云端模型让你可以将云端托管模型与本地模型一起使用。示例包括 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud` —— 这些**不**需要本地执行 `ollama pull`。 - 在设置期间选择 **云端 + 本地** 模式。向导会检查你是否已登录，并在需要时打开浏览器登录流程。如果无法验证认证状态，向导会回退到本地模型默认设置。 + 在设置期间选择 **Cloud + Local** 模式。向导会检查你是否已登录，并在需要时打开浏览器登录流程。如果无法验证认证状态，向导会回退到本地模型默认值。 你也可以直接在 [ollama.com/signin](https://ollama.com/signin) 登录。 @@ -145,27 +145,27 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上 - 在仅本地模式下，OpenClaw 会从本地 Ollama 实例中发现模型。不需要云端登录。 + 在仅本地模式下，OpenClaw 会从本地 Ollama 实例发现模型。不需要登录云端。 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` 并检测能力（包括视觉） | -| 视觉模型 | 如果 `/api/show` 报告模型具有 `vision` 能力，则将其标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图像注入提示中 | +| 视觉模型 | 对于 `/api/show` 报告具有 `vision` 能力的模型，会将其标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图像注入到提示中 | | 推理检测 | 使用模型名称启发式规则（`r1`、`reasoning`、`think`）标记 `reasoning` | -| Token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 | +| token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 | | 成本 | 将所有成本设置为 `0` | -这样可以避免手动添加模型条目，同时让目录与本地 Ollama 实例保持一致。 +这样可以避免手动填写模型条目，同时使目录与本地 Ollama 实例保持一致。 ```bash # 查看有哪些可用模型 @@ -173,7 +173,7 @@ ollama list openclaw models list ``` -要添加新模型，只需使用 Ollama 拉取它： +要添加新模型，只需通过 Ollama 拉取它： ```bash ollama pull mistral @@ -189,14 +189,14 @@ ollama pull mistral - 启用 Ollama 的最简单方式是通过环境变量： + 启用 Ollama 的最简单方式是使用环境变量： ```bash export OLLAMA_API_KEY="ollama-local" ``` - 如果设置了 `OLLAMA_API_KEY`，你可以在提供商条目中省略 `apiKey`，OpenClaw 会为可用性检查自动填充它。 + 如果已设置 `OLLAMA_API_KEY`，你可以在 provider 条目中省略 `apiKey`，OpenClaw 会自动填充它以进行可用性检查。 @@ -231,7 +231,7 @@ ollama pull mistral - + 如果 Ollama 运行在不同的主机或端口上（显式配置会禁用自动发现，因此你需要手动定义模型）： ```json5 @@ -240,8 +240,8 @@ ollama pull mistral providers: { ollama: { apiKey: "ollama-local", - baseUrl: "http://ollama-host:11434", // 不要加 /v1 - 请使用原生 Ollama API URL - api: "ollama", // 显式设置以确保原生工具调用行为 + baseUrl: "http://ollama-host:11434", // 不要带 /v1 - 使用原生 Ollama API URL + api: "ollama", // 显式设置以确保使用原生工具调用行为 }, }, }, @@ -249,7 +249,7 @@ ollama pull mistral ``` - 不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用不可靠。请使用不带路径后缀的 Ollama 基础 URL。 + 不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama 基础 URL。 @@ -274,15 +274,15 @@ ollama pull mistral ## Ollama Web 搜索 -OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商。 +OpenClaw 支持 **Ollama Web 搜索**，它作为内置的 `web_search` 提供商提供。 | 属性 | 详情 | | ----------- | ----------------------------------------------------------------------------------------------------------------- | -| 主机 | 使用你配置的 Ollama 主机（如果设置了 `models.providers.ollama.baseUrl` 则使用该值，否则使用 `http://127.0.0.1:11434`） | +| 主机 | 使用你配置的 Ollama 主机（设置了 `models.providers.ollama.baseUrl` 时使用其值，否则为 `http://127.0.0.1:11434`） | | 认证 | 无需密钥 | | 要求 | Ollama 必须正在运行，并且已通过 `ollama signin` 登录 | -在执行 `openclaw onboard` 或 `openclaw configure --section web` 时选择 **Ollama Web 搜索**，或者设置： +在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 **Ollama Web 搜索**，或者设置： ```json5 { @@ -297,7 +297,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商 ``` -有关完整的设置和行为详情，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。 +有关完整设置和行为细节，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。 ## 高级配置 @@ -305,7 +305,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商 - **在 OpenAI 兼容模式下，工具调用并不可靠。** 只有当你需要为代理使用 OpenAI 格式且不依赖原生工具调用行为时，才应使用此模式。 + **在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为代理使用 OpenAI 格式，且不依赖原生工具调用行为时，才使用此模式。 如果你需要改用 OpenAI 兼容端点（例如在仅支持 OpenAI 格式的代理之后），请显式设置 `api: "openai-completions"`： @@ -326,9 +326,9 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商 } ``` - 在此模式下，可能无法同时支持流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 来禁用流式传输。 + 此模式可能不支持同时进行流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 禁用流式传输。 - 当对 Ollama 使用 `api: "openai-completions"` 时，OpenClaw 默认会注入 `options.num_ctx`，以避免 Ollama 静默回退到 4096 上下文窗口。如果你的代理或上游拒绝未知的 `options` 字段，请禁用此行为： + 当 Ollama 使用 `api: "openai-completions"` 时，OpenClaw 默认会注入 `options.num_ctx`，这样 Ollama 就不会悄悄回退到 4096 的上下文窗口。如果你的代理或上游拒绝未知的 `options` 字段，请禁用此行为： ```json5 { @@ -351,7 +351,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商 对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，否则会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。 - 你可以在显式提供商配置中覆盖 `contextWindow` 和 `maxTokens`： + 你可以在显式 provider 配置中覆盖 `contextWindow` 和 `maxTokens`： ```json5 { @@ -374,25 +374,50 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商 - OpenClaw 默认会将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为具备推理能力。 + 默认情况下，OpenClaw 会将名称包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为具备推理能力。 ```bash ollama pull deepseek-r1:32b ``` - 不需要额外配置 —— OpenClaw 会自动标记它们。 + 不需要额外配置——OpenClaw 会自动标记它们。 - Ollama 是免费的，并且在本地运行，因此所有模型成本都设置为 $0。这同时适用于自动发现的模型和手动定义的模型。 + Ollama 可免费使用并在本地运行，因此所有模型成本都设置为 $0。这同时适用于自动发现和手动定义的模型。 + + + + 内置的 Ollama 插件为 + [记忆搜索](/zh-CN/concepts/memory) + 注册了一个记忆嵌入提供商。它使用已配置的 Ollama base URL + 和 API 密钥。 + + | 属性 | 值 | + | ------------- | ------------------- | + | 默认模型 | `nomic-embed-text` | + | 自动拉取 | 是——如果嵌入模型尚未在本地存在，将自动拉取 | + + 要将 Ollama 选为记忆搜索的嵌入提供商： + + ```json5 + { + agents: { + defaults: { + memorySearch: { provider: "ollama" }, + }, + }, + } + ``` + - OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），它完全支持同时进行流式传输和工具调用。不需要任何特殊配置。 + OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），可同时完整支持流式传输和工具调用。不需要特殊配置。 - 如果你需要使用 OpenAI 兼容端点，请参阅上方的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。 + 如果你需要使用 OpenAI 兼容端点，请参阅上方“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。 @@ -402,7 +427,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商 - 请确认 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或认证配置文件），同时你**没有**定义显式的 `models.providers.ollama` 条目： + 请确认 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或认证配置），且你**没有**定义显式的 `models.providers.ollama` 条目： ```bash ollama serve @@ -429,7 +454,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商 - 检查 Ollama 是否正在正确的端口上运行： + 检查 Ollama 是否在正确的端口上运行： ```bash # 检查 Ollama 是否正在运行 @@ -456,7 +481,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商 如何选择和配置模型。 - 了解由 Ollama 驱动的 Web 搜索的完整设置和行为详情。 + 由 Ollama 提供支持的 Web 搜索的完整设置和行为细节。 完整配置参考。 diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index 5b32fde91..97e52c39f 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -1,35 +1,35 @@ --- read_when: - - 你想在 OpenClaw 中使用 OpenAI 模型 - - 你希望使用 Codex 订阅凭证，而不是 API 密钥 - - 你需要更严格的 GPT-5 智能体执行行为 -summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI + - 你想在 OpenClaw 中使用 OpenAI 模型。 + - 你想使用 Codex 订阅凭证，而不是 API 密钥。 + - 你需要更严格的 GPT-5 智能体执行行为。 +summary: 在 OpenClaw 中使用 OpenAI，可通过 API 密钥或 Codex 订阅。 title: OpenAI x-i18n: - generated_at: "2026-04-12T09:46:32Z" + generated_at: "2026-04-12T11:08:20Z" model: gpt-5.4 provider: openai - source_hash: 0a2eb5f742a68c4cdd1cff3bc9c0f52663b3d668b00a0db61ccf7dfb0d3f7b1d + source_hash: 6aeb756618c5611fed56e4bf89015a2304ff2e21596104b470ec6e7cb459d1c9 source_path: providers/openai.md workflow: 15 --- # OpenAI -OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持两种凭证方式： +OpenAI 提供用于 GPT 模型的开发者 API。OpenClaw 支持两种凭证方式： -- **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型） +- **API 密钥** — 直接访问 OpenAI Platform，并按用量计费（`openai/*` 模型） - **Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型） -OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。 +OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth。 ## 入门指南 -选择你偏好的凭证方式，并按照设置步骤操作。 +选择你偏好的凭证方式，并按照设置步骤进行操作。 - **最适合：** 直接 API 访问和按使用量计费。 + **最适合：** 直接访问 API 并按用量计费。 @@ -74,13 +74,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA ``` - OpenClaw **不会**在直接 API 路径中暴露 `openai/gpt-5.3-codex-spark`。真实的 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。 + OpenClaw **不会** 在直接 API 路径上暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。 - **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex 云需要 ChatGPT 登录。 + **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要使用 ChatGPT 登录。 @@ -111,10 +111,10 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA | 模型引用 | 路由 | 凭证 | |-----------|-------|------| | `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex 登录 | - | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于权限） | + | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于 entitlement） | - 此路由与 `openai/gpt-5.4` 是有意分开的。直接 Platform 访问请使用带 API 密钥的 `openai/*`，Codex 订阅访问请使用 `openai-codex/*`。 + 这一路由与 `openai/gpt-5.4` 是有意分开的。使用 API 密钥配合 `openai/*` 以直接访问 Platform，而使用 `openai-codex/*` 以通过 Codex 订阅访问。 ### 配置示例 @@ -126,7 +126,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA ``` - 如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续由 Codex CLI 管理。凭证过期后，OpenClaw 会先重新读取外部 Codex 来源，再将刷新的凭证写回 Codex 存储。 + 如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续由 Codex CLI 管理。凭证过期时，OpenClaw 会先重新读取外部 Codex 来源，然后将刷新的凭证写回 Codex 存储。 ### 上下文窗口上限 @@ -138,7 +138,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA - 原生 `contextWindow`：`1050000` - 默认运行时 `contextTokens` 上限：`272000` - 在实践中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它： + 较小的默认上限在实践中通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它： ```json5 { @@ -163,13 +163,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA 内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。 -| 功能 | 值 | +| 能力 | 值 | | ------------------------- | ---------------------------------- | | 默认模型 | `openai/gpt-image-1` | | 每次请求的最大图像数 | 4 | | 编辑模式 | 已启用（最多 5 张参考图像） | | 尺寸覆盖 | 支持 | -| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | +| 宽高比 / 分辨率 | 不会转发给 OpenAI Images API | ```json5 { @@ -189,13 +189,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA 内置的 `openai` 插件通过 `video_generate` 工具注册视频生成功能。 -| 功能 | 值 | +| 能力 | 值 | | ---------------- | --------------------------------------------------------------------------------- | | 默认模型 | `openai/sora-2` | -| 模式 | 文生视频、图生视频、单视频编辑 | +| 模式 | 文本生成视频、图像生成视频、单视频编辑 | | 参考输入 | 1 张图像或 1 个视频 | | 尺寸覆盖 | 支持 | -| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并附带工具警告 | +| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 | ```json5 { @@ -211,13 +211,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA 有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。 -## 个性叠加层 +## 个性覆盖层 -对于 `openai/*` 和 `openai-codex/*` 运行，OpenClaw 会添加一个小型的 OpenAI 专属提示词叠加层。该叠加层会让助手保持温和、协作、简洁，并稍微更具情感表达，同时不会替换基础系统提示词。 +OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI 专属提示词覆盖层。该覆盖层会让助手保持温暖、协作、简洁，并带有稍强一些的情感表达，但不会替代基础系统提示词。 | 值 | 效果 | | ---------------------- | ---------------------------------- | -| `"friendly"`（默认） | 启用 OpenAI 专属叠加层 | +| `"friendly"`（默认） | 启用 OpenAI 专属覆盖层 | | `"on"` | `"friendly"` 的别名 | | `"off"` | 仅使用基础 OpenClaw 提示词 | @@ -241,20 +241,91 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA -运行时值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用该叠加层。 +运行时会以不区分大小写的方式处理这些值，因此 `"Off"` 和 `"off"` 都会禁用该覆盖层。 +## 语音与语音处理 + + + + 内置的 `openai` 插件会为 `messages.tts` 接口注册语音合成功能。 + + | 设置 | 配置路径 | 默认值 | + |---------|------------|---------| + | 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | + | 声音 | `messages.tts.providers.openai.voice` | `coral` | + | 语速 | `messages.tts.providers.openai.speed` | （未设置） | + | 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） | + | 格式 | `messages.tts.providers.openai.responseFormat` | 语音笔记使用 `opus`，文件使用 `mp3` | + | API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` | + | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | + + 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用声音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 + + ```json5 + { + messages: { + tts: { + providers: { + openai: { model: "gpt-4o-mini-tts", voice: "coral" }, + }, + }, + }, + } + ``` + + + 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 Base URL，而不会影响聊天 API 端点。 + + + + + + 内置的 `openai` 插件会为 Voice Call 插件注册实时转录功能。 + + | 设置 | 配置路径 | 默认值 | + |---------|------------|---------| + | 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | + | 静音时长 | `...openai.silenceDurationMs` | `800` | + | VAD 阈值 | `...openai.vadThreshold` | `0.5` | + | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | + + + 使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并采用 G.711 u-law 音频。 + + + + + + 内置的 `openai` 插件会为 Voice Call 插件注册实时语音功能。 + + | 设置 | 配置路径 | 默认值 | + |---------|------------|---------| + | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime` | + | 声音 | `...openai.voice` | `alloy` | + | 温度 | `...openai.temperature` | `0.8` | + | VAD 阈值 | `...openai.vadThreshold` | `0.5` | + | 静音时长 | `...openai.silenceDurationMs` | `500` | + | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | + + + 通过 `azureEndpoint` 和 `azureDeployment` 配置键支持 Azure OpenAI。支持双向工具调用。使用 G.711 u-law 音频格式。 + + + + + ## 高级配置 - 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都默认采用 WebSocket 优先，并在失败时回退到 SSE（`"auto"`）。 + 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先、SSE 回退（`"auto"`）的策略。 在 `"auto"` 模式下，OpenClaw 会： - - 在回退到 SSE 之前，重试一次早期 WebSocket 失败 - - 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE - - 为重试和重连附加稳定的会话与轮次身份标头 - - 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`） + - 在回退到 SSE 之前，对一次早期 WebSocket 失败进行重试 + - 发生失败后，将 WebSocket 标记为降级状态约 60 秒，并在冷却期间使用 SSE + - 为重试和重连附加稳定的会话与轮次标识头 + - 在不同传输变体之间标准化用量计数器（`input_tokens` / `prompt_tokens`） | 值 | 行为 | |-------|----------| @@ -283,7 +354,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA - 对于 `openai/*`，OpenClaw 默认启用 WebSocket 预热，以降低首轮延迟。 + OpenClaw 默认会为 `openai/*` 启用 WebSocket 预热，以减少首轮延迟。 ```json5 // 禁用预热 @@ -303,7 +374,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA - OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供统一的快速模式开关： + OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供共享的快速模式开关： - **聊天 / UI：** `/fast status|on|off` - **配置：** `agents.defaults.models["/"].params.fastMode` @@ -324,7 +395,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA ``` - 会话覆盖优先生效。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置中的默认值。 + 会话覆盖的优先级高于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置中的默认值。 @@ -348,17 +419,17 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA 支持的值：`auto`、`default`、`flex`、`priority`。 - `serviceTier` 只会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 原样不变。 + `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。 - 对于直接使用 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩： + 对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩： - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` - - 默认 `compact_threshold`：`contextWindow` 的 70%（若不可用则为 `80000`） + - 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`） @@ -414,13 +485,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA - `responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性配置将 `supportsStore` 设为 `false`。 + `responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。 - - 对于 `openai/*` 和 `openai-codex/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的内嵌执行契约： + + 对于 `openai/*` 和 `openai-codex/*` 上 GPT-5 系列的运行，OpenClaw 可以使用更严格的内嵌执行契约： ```json5 { @@ -432,32 +503,32 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA } ``` - 启用 `strict-agentic` 后，OpenClaw 会： - - 当有可用工具操作时，不再将仅规划的轮次视为成功进展 - - 使用“立即行动”的引导重试该轮次 - - 对于实质性工作自动启用 `update_plan` - - 如果模型持续规划而不执行操作，则显示明确的受阻状态 + 使用 `strict-agentic` 时，OpenClaw 会： + - 当工具操作可用时，不再将“仅做计划”的轮次视为成功推进 + - 通过“立即行动”的引导重试该轮 + - 对于较大工作自动启用 `update_plan` + - 如果模型持续只做计划而不行动，则显示明确的阻塞状态 - 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列保持默认行为。 + 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列将保持默认行为。 - - OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用的 OpenAI 兼容 `/v1` 代理不同： + + OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI-compatible `/v1` 代理： **原生路由**（`openai/*`、`openai-codex/*`、Azure OpenAI）： - 当明确禁用推理时，保留 `reasoning: { effort: "none" }` - 默认将工具 schema 设为严格模式 - - 仅在已验证的原生主机上附加隐藏归因标头 - - 保留 OpenAI 专属的请求整形（`service_tier`、`store`、推理兼容性、提示词缓存提示） + - 仅在已验证的原生主机上附加隐藏归因头 + - 保留 OpenAI 专属请求整形（`service_tier`、`store`、推理兼容性、提示词缓存提示） - **代理 / 兼容路由：** + **代理 / compatible 路由：** - 使用更宽松的兼容行为 - - 不会强制严格工具 schema 或原生专属标头 + - 不强制严格工具 schema 或原生专属头 - Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因标头。 + Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因头。 @@ -474,7 +545,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA 共享视频工具参数和提供商选择。 - - 凭证细节和凭证复用规则。 + + 凭证详情和凭证复用规则。 diff --git a/docs/zh-CN/providers/qwen.md b/docs/zh-CN/providers/qwen.md index 7861a3a74..49acb34c1 100644 --- a/docs/zh-CN/providers/qwen.md +++ b/docs/zh-CN/providers/qwen.md @@ -5,10 +5,10 @@ read_when: summary: 通过 OpenClaw 内置的 qwen 提供商使用 Qwen Cloud title: Qwen x-i18n: - generated_at: "2026-04-12T10:12:20Z" + generated_at: "2026-04-12T11:08:22Z" model: gpt-5.4 provider: openai - source_hash: bbd8efa131d37a5dc7578aa0318b8bcb6d492b35858fa611f3fbd8416cf6b866 + source_hash: 5247f851ef891645df6572d748ea15deeea47cd1d75858bc0d044a2930065106 source_path: providers/qwen.md workflow: 15 --- @@ -17,23 +17,23 @@ x-i18n: -**Qwen OAuth 已被移除。** 使用 `portal.qwen.ai` 端点的免费层 OAuth 集成 -（`qwen-portal`）现已不可用。背景信息请参见 -[Issue #49557](https://github.com/openclaw/openclaw/issues/49557)。 +**Qwen OAuth 已被移除。** 之前使用 `portal.qwen.ai` 端点的免费层 OAuth 集成 +（`qwen-portal`）现已不可用。 +背景信息请参见 [Issue #49557](https://github.com/openclaw/openclaw/issues/49557)。 -OpenClaw 现在将 Qwen 视为一级内置提供商，其规范 id +OpenClaw 现在将 Qwen 视为一等内置提供商，其规范 id 为 `qwen`。该内置提供商面向 Qwen Cloud / Alibaba DashScope 和 Coding Plan 端点，并保留旧版 `modelstudio` id 作为兼容性别名。 - 提供商：`qwen` - 首选环境变量：`QWEN_API_KEY` -- 也接受以下兼容变量：`MODELSTUDIO_API_KEY`、`DASHSCOPE_API_KEY` -- API 风格：兼容 OpenAI +- 出于兼容性也接受：`MODELSTUDIO_API_KEY`、`DASHSCOPE_API_KEY` +- API 风格：与 OpenAI 兼容 -如果你想使用 `qwen3.6-plus`，建议优先选择**标准版（按量付费）**端点。 +如果你想使用 `qwen3.6-plus`，建议优先选择**标准版（按量计费）**端点。 Coding Plan 支持可能会落后于公开目录。 @@ -81,14 +81,15 @@ Coding Plan 支持可能会落后于公开目录。 - 旧版 `modelstudio-*` auth-choice id 和 `modelstudio/...` 模型引用仍然可作为兼容性别名继续使用，但新的设置流程应优先使用规范的 + 旧版 `modelstudio-*` auth-choice id 和 `modelstudio/...` 模型引用仍然 + 可以作为兼容性别名继续使用，但新的设置流程应优先使用规范的 `qwen-*` auth-choice id 和 `qwen/...` 模型引用。 - - **最适合：** 通过标准版 Model Studio 端点进行按量付费访问，包括 `qwen3.6-plus` 等在 Coding Plan 中可能不可用的模型。 + + **最适合：** 通过标准版 Model Studio 端点进行按量计费访问，包括像 `qwen3.6-plus` 这样在 Coding Plan 中可能不可用的模型。 @@ -126,7 +127,8 @@ Coding Plan 支持可能会落后于公开目录。 - 旧版 `modelstudio-*` auth-choice id 和 `modelstudio/...` 模型引用仍然可作为兼容性别名继续使用，但新的设置流程应优先使用规范的 + 旧版 `modelstudio-*` auth-choice id 和 `modelstudio/...` 模型引用仍然 + 可以作为兼容性别名继续使用，但新的设置流程应优先使用规范的 `qwen-*` auth-choice id 和 `qwen/...` 模型引用。 @@ -137,14 +139,14 @@ Coding Plan 支持可能会落后于公开目录。 | 套餐 | 区域 | Auth choice | 端点 | | -------------------------- | ------ | -------------------------- | ------------------------------------------------ | -| 标准版（按量付费） | 中国 | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` | -| 标准版（按量付费） | 全球 | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` | +| 标准版（按量计费） | 中国 | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` | +| 标准版（按量计费） | 全球 | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` | | Coding Plan（订阅制） | 中国 | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` | | Coding Plan（订阅制） | 全球 | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | -该提供商会根据你的 auth choice 自动选择端点。规范 choice 使用 -`qwen-*` 系列；`modelstudio-*` 仅保留作兼容用途。 -你可以在配置中使用自定义 `baseUrl` 进行覆盖。 +该提供商会根据你的 auth choice 自动选择端点。规范选择使用 `qwen-*` +系列；`modelstudio-*` 仅保留用于兼容性。 +你也可以在配置中通过自定义 `baseUrl` 进行覆盖。 **管理密钥：** [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys) | @@ -153,19 +155,21 @@ Coding Plan 支持可能会落后于公开目录。 ## 内置目录 -OpenClaw 当前内置以下 Qwen 目录。已配置的目录会感知端点类型：Coding Plan 配置会省略那些仅已知可在标准版端点上运行的模型。 +OpenClaw 当前内置了以下 Qwen 目录。已配置的目录会感知端点： +Coding Plan 配置会省略那些目前仅确认可在 +标准版端点上运行的模型。 | 模型引用 | 输入 | 上下文 | 说明 | | --------------------------- | ----------- | --------- | -------------------------------------------------- | | `qwen/qwen3.5-plus` | text, image | 1,000,000 | 默认模型 | -| `qwen/qwen3.6-plus` | text, image | 1,000,000 | 需要此模型时，建议优先使用标准版端点 | +| `qwen/qwen3.6-plus` | text, image | 1,000,000 | 当你需要此模型时，建议优先使用标准版端点 | | `qwen/qwen3-max-2026-01-23` | text | 262,144 | Qwen Max 系列 | | `qwen/qwen3-coder-next` | text | 262,144 | 编码 | | `qwen/qwen3-coder-plus` | text | 1,000,000 | 编码 | | `qwen/MiniMax-M2.5` | text | 1,000,000 | 已启用推理 | | `qwen/glm-5` | text | 202,752 | GLM | | `qwen/glm-4.7` | text | 202,752 | GLM | -| `qwen/kimi-k2.5` | text, image | 262,144 | Moonshot AI，经由 Alibaba | +| `qwen/kimi-k2.5` | text, image | 262,144 | 通过 Alibaba 提供的 Moonshot AI | 即使某个模型出现在内置目录中，其可用性仍可能因端点和计费套餐而异。 @@ -173,11 +177,11 @@ OpenClaw 当前内置以下 Qwen 目录。已配置的目录会感知端点类 ## 多模态附加能力 -`qwen` 扩展还在**标准版** -DashScope 端点上提供多模态能力（不包括 Coding Plan 端点）： +`qwen` 扩展还会在**标准版** +DashScope 端点（而非 Coding Plan 端点）上提供多模态能力： -- **视频理解**：通过 `qwen-vl-max-latest` -- **Wan 视频生成**：通过 `wan2.6-t2v`（默认）、`wan2.6-i2v`、`wan2.6-r2v`、`wan2.6-r2v-flash`、`wan2.7-r2v` +- 通过 `qwen-vl-max-latest` 提供**视频理解** +- 通过 `wan2.6-t2v`（默认）、`wan2.6-i2v`、`wan2.6-r2v`、`wan2.6-r2v-flash`、`wan2.7-r2v` 提供 **Wan 视频生成** 要将 Qwen 用作默认视频提供商： @@ -192,66 +196,84 @@ DashScope 端点上提供多模态能力（不包括 Coding Plan 端点）： ``` -共享工具参数、提供商选择和故障转移行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。 +有关共享工具参数、提供商选择和故障切换行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。 ## 高级 + + 内置的 Qwen 插件会在**标准版** DashScope 端点（而非 Coding Plan 端点）上为图像和视频注册媒体理解能力。 + + | 属性 | 值 | + | ------------- | --------------------- | + | 模型 | `qwen-vl-max-latest` | + | 支持的输入 | 图像、视频 | + + 媒体理解会根据已配置的 Qwen 凭证自动解析—— + 无需额外配置。请确保你使用的是支持媒体理解的标准版（按量计费） + 端点。 + + + - `qwen3.6-plus` 可在标准版（按量付费）Model Studio + `qwen3.6-plus` 可在标准版（按量计费）Model Studio 端点上使用： - 中国：`dashscope.aliyuncs.com/compatible-mode/v1` - 全球：`dashscope-intl.aliyuncs.com/compatible-mode/v1` - 如果 Coding Plan 端点对 - `qwen3.6-plus` 返回“unsupported model”错误，请切换到标准版（按量付费），而不是继续使用 Coding Plan - 端点/密钥组合。 + 如果 Coding Plan 端点对 `qwen3.6-plus` 返回“unsupported model”错误， + 请切换到标准版（按量计费），而不是继续使用 Coding Plan + 端点 / 密钥组合。 - `qwen` 扩展正被定位为完整 Qwen - Cloud 能力面的厂商归属点，而不仅仅是编码/文本模型。 + `qwen` 扩展正在被定位为完整 Qwen + Cloud 能力面的厂商归属入口，而不仅仅是编码 / 文本模型。 - - **文本/聊天模型：** 当前已内置 - - **工具调用、结构化输出、思考：** 继承自兼容 OpenAI 的传输层 - - **图像生成：** 计划在提供商插件层提供 - - **图像/视频理解：** 当前已在标准版端点内置 - - **语音/音频：** 计划在提供商插件层提供 - - **Memory 嵌入/重排：** 计划通过嵌入适配器能力面提供 - - **视频生成：** 当前已通过共享的视频生成能力内置 + - **文本 / 聊天模型：** 现已内置 + - **工具调用、结构化输出、思维链：** 继承自与 OpenAI 兼容的传输层 + - **图像生成：** 计划在提供商插件层支持 + - **图像 / 视频理解：** 现已在标准版端点内置 + - **语音 / 音频：** 计划在提供商插件层支持 + - **Memory 嵌入 / 重排序：** 计划通过嵌入适配器能力面支持 + - **视频生成：** 现已通过共享视频生成能力内置 - 对于视频生成，OpenClaw 会先将已配置的 Qwen 区域映射到对应的 + 对于视频生成，OpenClaw 会先将已配置的 Qwen 区域映射到匹配的 DashScope AIGC 主机，然后再提交任务： - - 全球/国际版：`https://dashscope-intl.aliyuncs.com` + - 全球 / 国际版：`https://dashscope-intl.aliyuncs.com` - 中国：`https://dashscope.aliyuncs.com` 这意味着，普通的 `models.providers.qwen.baseUrl` 即使指向 - Coding Plan 或标准版 Qwen 主机之一，视频生成仍会使用正确的区域性 DashScope 视频端点。 + Coding Plan 或标准版 Qwen 主机之一， + 视频生成仍会使用正确的区域性 DashScope 视频端点。 - 当前内置的 Qwen 视频生成限制： + 当前内置 Qwen 视频生成限制： - - 每次请求最多 **1** 个输出视频 + - 每个请求最多 **1** 个输出视频 - 最多 **1** 张输入图片 - 最多 **4** 个输入视频 - 最长 **10 秒** 时长 - 支持 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` - - 参考图片/视频模式当前要求使用**远程 http(s) URL**。本地 - 文件路径会被提前拒绝，因为 DashScope 视频端点不接受这些参考内容的本地缓冲区上传。 + - 参考图片 / 视频模式目前要求使用**远程 http(s) URL**。本地 + 文件路径会被预先拒绝，因为 DashScope 视频端点不接受 + 为这些参考上传本地缓冲区。 - - 原生 Model Studio 端点会在共享的 - `openai-completions` 传输上声明流式使用量兼容性。OpenClaw 现在会基于端点能力来判断，因此，指向相同原生主机的 DashScope 兼容自定义提供商 id 也会继承相同的流式使用量行为，而不再要求必须是内置 `qwen` 提供商 id。 + + 原生 Model Studio 端点会在共享 `openai-completions` 传输层上声明 + 流式使用兼容性。OpenClaw 现在基于端点能力来判断这一点，因此面向相同原生主机的 + DashScope 兼容自定义提供商 id 也会继承相同的流式使用行为， + 而不再要求必须使用内置 `qwen` 提供商 id。 - 原生流式使用量兼容性同时适用于 Coding Plan 主机和 + 原生流式使用兼容性同时适用于 Coding Plan 主机和 标准版 DashScope 兼容主机： - `https://coding.dashscope.aliyuncs.com/v1` @@ -265,13 +287,13 @@ DashScope 端点上提供多模态能力（不包括 Coding Plan 端点）： 多模态能力面（视频理解和 Wan 视频生成）使用的是 **标准版** DashScope 端点，而不是 Coding Plan 端点： - - 全球/国际版标准 base URL：`https://dashscope-intl.aliyuncs.com/compatible-mode/v1` + - 全球 / 国际版标准 base URL：`https://dashscope-intl.aliyuncs.com/compatible-mode/v1` - 中国标准 base URL：`https://dashscope.aliyuncs.com/compatible-mode/v1` - 如果 Gateway 网关以守护进程方式运行（launchd/systemd），请确保 `QWEN_API_KEY` + 如果 Gateway 网关以守护进程（launchd/systemd）方式运行，请确保 `QWEN_API_KEY` 对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。 @@ -281,7 +303,7 @@ DashScope 端点上提供多模态能力（不包括 Coding Plan 端点）： - 选择提供商、模型引用和故障转移行为。 + 选择提供商、模型引用和故障切换行为。 共享视频工具参数和提供商选择。 @@ -290,6 +312,6 @@ DashScope 端点上提供多模态能力（不包括 Coding Plan 端点）： 旧版 ModelStudio 提供商和迁移说明。 - 通用故障排除和常见问题。 + 常规故障排除和常见问题。 diff --git a/docs/zh-CN/providers/xai.md b/docs/zh-CN/providers/xai.md index be322481f..bbbf11e32 100644 --- a/docs/zh-CN/providers/xai.md +++ b/docs/zh-CN/providers/xai.md @@ -1,14 +1,14 @@ --- read_when: - 你想在 OpenClaw 中使用 Grok 模型 - - 你正在配置 xAI 的身份验证或模型 ID + - 你正在配置 xAI 的凭证或模型 ID summary: 在 OpenClaw 中使用 xAI Grok 模型 title: xAI x-i18n: - generated_at: "2026-04-12T10:19:18Z" + generated_at: "2026-04-12T11:08:20Z" model: gpt-5.4 provider: openai - source_hash: 064aa758f9791f704dc6b0cc0059bb73b7de68ae2edd731bb87dbc26730eea9f + source_hash: 820fef290c67d9815e41a96909d567216f67ca0f01df1d325008fd04666ad255 source_path: providers/xai.md workflow: 15 --- @@ -41,17 +41,17 @@ OpenClaw 内置了一个用于 Grok 模型的 `xai` 提供商插件。 -OpenClaw 使用 xAI Responses API 作为内置的 xAI 传输层。相同的 -`XAI_API_KEY` 也可用于由 Grok 驱动的 `web_search`、原生 +OpenClaw 使用 xAI Responses API 作为内置 xAI 传输方式。同一个 +`XAI_API_KEY` 也可用于由 Grok 支持的 `web_search`、原生 `x_search` 以及远程 `code_execution`。 如果你将 xAI 密钥存储在 `plugins.entries.xai.config.webSearch.apiKey` 下， -内置的 xAI 模型提供商也会将该密钥复用为回退值。 -`code_execution` 调优配置位于 `plugins.entries.xai.config.codeExecution` 下。 +内置的 xAI 模型提供商也会回退复用该密钥。 +`code_execution` 调优配置位于 `plugins.entries.xai.config.codeExecution`。 ## 内置模型目录 -OpenClaw 开箱即用地包含以下 xAI 模型家族： +OpenClaw 默认包含以下 xAI 模型家族： | 家族 | 模型 ID | | -------------- | ------------------------------------------------------------------------ | @@ -62,8 +62,8 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族： | Grok 4.20 Beta | `grok-4.20-beta-latest-reasoning`, `grok-4.20-beta-latest-non-reasoning` | | Grok Code | `grok-code-fast-1` | -当较新的 `grok-4*` 和 `grok-code-fast*` ID 遵循相同的 API 形式时， -该插件也会继续将其转发解析。 +当较新的 `grok-4*` 和 `grok-code-fast*` ID +遵循相同的 API 形态时，该插件也会将其转发解析。 `grok-4-fast`、`grok-4-1-fast` 以及 `grok-4.20-beta-*` 变体， @@ -73,7 +73,7 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族： ### 快速模式映射 `/fast on` 或 `agents.defaults.models["xai/"].params.fastMode: true` -会按如下方式重写原生 xAI 请求： +会将原生 xAI 请求重写如下： | 源模型 | 快速模式目标 | | ------------- | ------------------ | @@ -84,7 +84,7 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族： ### 旧版兼容别名 -旧版别名仍会规范化为标准的内置 ID： +旧版别名仍会规范化为标准内置 ID： | 旧版别名 | 标准 ID | | ------------------------- | ------------------------------------- | @@ -106,15 +106,15 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族： - 内置的 `xai` 插件通过共享的 - `video_generate` 工具注册了视频生成功能。 + 内置 `xai` 插件通过共享的 + `video_generate` 工具注册视频生成功能。 - 默认视频模型：`xai/grok-imagine-video` - 模式：文生视频、图生视频，以及远程视频编辑/扩展流程 - 支持 `aspectRatio` 和 `resolution` - 不接受本地视频缓冲区。请对视频参考和编辑输入使用远程 `http(s)` URL。 + 不接受本地视频缓冲区。请为视频参考和编辑输入使用远程 `http(s)` URL。 要将 xAI 用作默认视频提供商： @@ -132,14 +132,87 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族： ``` - 有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。 + 请参阅 [视频生成](/zh-CN/tools/video-generation) 以了解共享工具参数、 + 提供商选择和故障转移行为。 + + 内置 xAI 插件将 `x_search` 作为 OpenClaw 工具公开， + 用于通过 Grok 搜索 X（原 Twitter）内容。 + + 配置路径：`plugins.entries.xai.config.xSearch` + + | 键名 | 类型 | 默认值 | 描述 | + | ------------------ | ------- | ------------------ | ------------------------------------ | + | `enabled` | boolean | — | 启用或禁用 x_search | + | `model` | string | `grok-4-1-fast` | 用于 x_search 请求的模型 | + | `inlineCitations` | boolean | — | 在结果中包含内联引用 | + | `maxTurns` | number | — | 最大对话轮数 | + | `timeoutSeconds` | number | — | 请求超时时间（秒） | + | `cacheTtlMinutes` | number | — | 缓存存活时间（分钟） | + + ```json5 + { + plugins: { + entries: { + xai: { + config: { + xSearch: { + enabled: true, + model: "grok-4-1-fast", + inlineCitations: true, + }, + }, + }, + }, + }, + } + ``` + + + + + 内置 xAI 插件将 `code_execution` 作为 OpenClaw 工具公开， + 用于在 xAI 的沙箱环境中执行远程代码。 + + 配置路径：`plugins.entries.xai.config.codeExecution` + + | 键名 | 类型 | 默认值 | 描述 | + | ----------------- | ------- | ------------------ | ---------------------------------------- | + | `enabled` | boolean | `true`（如果密钥可用） | 启用或禁用代码执行 | + | `model` | string | `grok-4-1-fast` | 用于代码执行请求的模型 | + | `maxTurns` | number | — | 最大对话轮数 | + | `timeoutSeconds` | number | — | 请求超时时间（秒） | + + + 这是远程 xAI 沙箱执行，不是本地 [`exec`](/zh-CN/tools/exec)。 + + + ```json5 + { + plugins: { + entries: { + xai: { + config: { + codeExecution: { + enabled: true, + model: "grok-4-1-fast", + }, + }, + }, + }, + }, + } + ``` + + + - - 当前身份验证仅支持 API 密钥。OpenClaw 尚不支持 xAI OAuth 或设备代码流程。 - - `grok-4.20-multi-agent-experimental-beta-0304` 在常规 xAI 提供商路径中不受支持，因为它所需的上游 API 接口不同于标准的 OpenClaw xAI 传输层。 + - 当前仅支持 API 密钥凭证。OpenClaw 还不支持 xAI OAuth 或设备码流程。 + - `grok-4.20-multi-agent-experimental-beta-0304` 在常规 xAI 提供商路径上不受支持， + 因为它所需的上游 API 接口不同于标准 OpenClaw xAI 传输方式。 @@ -147,10 +220,13 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族： - 原生 xAI 请求默认使用 `tool_stream: true`。将 `agents.defaults.models["xai/"].params.tool_stream` 设为 `false` 可禁用它。 - - 内置的 xAI 包装器会在发送原生 xAI 请求前，去除不受支持的严格工具 schema 标志和推理负载键。 - - `web_search`、`x_search` 和 `code_execution` 以 OpenClaw 工具的形式公开。OpenClaw 会在每次工具请求中启用它所需的特定 xAI 内置能力，而不是在每次聊天轮次中附加所有原生工具。 - - `x_search` 和 `code_execution` 由内置的 xAI 插件负责，而不是硬编码在核心模型运行时中。 - - `code_execution` 是远程 xAI 沙箱执行，不是本地的 + - 内置 xAI 包装器会在发送原生 xAI 请求前，移除不受支持的严格工具 schema 标志和推理载荷键。 + - `web_search`、`x_search` 和 `code_execution` 会作为 OpenClaw + 工具公开。OpenClaw 会在每个工具请求内启用所需的特定 xAI 内置能力， + 而不是在每次聊天轮次中附加所有原生工具。 + - `x_search` 和 `code_execution` 由内置 xAI 插件负责， + 而不是硬编码在核心模型运行时中。 + - `code_execution` 是远程 xAI 沙箱执行，不是本地 [`exec`](/zh-CN/tools/exec)。 @@ -159,15 +235,15 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族： - 选择提供商、模型引用和故障切换行为。 + 选择提供商、模型引用和故障转移行为。 共享视频工具参数和提供商选择。 - 更全面的提供商概览。 + 更广泛的提供商概览。 - 常见问题及修复方法。 + 常见问题和修复方法。 diff --git a/docs/zh-CN/providers/zai.md b/docs/zh-CN/providers/zai.md index 2573d5857..b0acc718b 100644 --- a/docs/zh-CN/providers/zai.md +++ b/docs/zh-CN/providers/zai.md @@ -2,20 +2,22 @@ read_when: - 你想在 OpenClaw 中使用 Z.AI / GLM 模型 - 你需要一个简单的 `ZAI_API_KEY` 设置 -summary: 使用 OpenClaw 搭配 Z.AI（GLM 模型） +summary: 使用 Z.AI（GLM 模型）与 OpenClaw 配合使用 title: Z.AI x-i18n: - generated_at: "2026-04-12T10:33:26Z" + generated_at: "2026-04-12T11:08:28Z" model: gpt-5.4 provider: openai - source_hash: eddb57770e6f1f9c72e62585d7d43a5e25f0d08f1b793f1ba5b0168c4c47f3cd + source_hash: 972b467dab141c8c5126ac776b7cb6b21815c27da511b3f34e12bd9e9ac953b7 source_path: providers/zai.md workflow: 15 --- # Z.AI -Z.AI 是 **GLM** 模型的 API 平台。它为 GLM 提供 REST API，并使用 API 密钥进行身份验证。在 Z.AI 控制台中创建你的 API 密钥。OpenClaw 使用 `zai` 提供商和 Z.AI API 密钥。 +Z.AI 是 **GLM** 模型的 API 平台。它为 GLM 提供 REST API，并使用 API 密钥 +进行身份验证。在 Z.AI 控制台中创建你的 API 密钥。OpenClaw 使用 `zai` 提供商 +和 Z.AI API 密钥。 - 提供商：`zai` - 凭证：`ZAI_API_KEY` @@ -91,35 +93,37 @@ Z.AI 是 **GLM** 模型的 API 平台。它为 GLM 提供 REST API，并使用 A OpenClaw 目前为内置 `zai` 提供商预置了以下内容： -| Model ref | 说明 | -| -------------------- | ------------ | -| `zai/glm-5.1` | 默认模型 | -| `zai/glm-5` | | -| `zai/glm-5-turbo` | | -| `zai/glm-5v-turbo` | | -| `zai/glm-4.7` | | -| `zai/glm-4.7-flash` | | -| `zai/glm-4.7-flashx` | | -| `zai/glm-4.6` | | -| `zai/glm-4.6v` | | -| `zai/glm-4.5` | | -| `zai/glm-4.5-air` | | -| `zai/glm-4.5-flash` | | -| `zai/glm-4.5v` | | +| Model ref | 说明 | +| -------------------- | -------- | +| `zai/glm-5.1` | 默认模型 | +| `zai/glm-5` | | +| `zai/glm-5-turbo` | | +| `zai/glm-5v-turbo` | | +| `zai/glm-4.7` | | +| `zai/glm-4.7-flash` | | +| `zai/glm-4.7-flashx` | | +| `zai/glm-4.6` | | +| `zai/glm-4.6v` | | +| `zai/glm-4.5` | | +| `zai/glm-4.5-air` | | +| `zai/glm-4.5-flash` | | +| `zai/glm-4.5v` | | -GLM 模型可作为 `zai/` 使用（例如：`zai/glm-5`）。默认的内置模型引用是 `zai/glm-5.1`。 +GLM 模型可用 `zai/` 的形式使用（例如：`zai/glm-5`）。默认内置模型引用是 `zai/glm-5.1`。 ## 高级配置 - 未知的 `glm-5*` id 在匹配当前 GLM-5 家族形态时，仍会通过内置提供商路径进行前向解析，方法是基于 `glm-4.7` 模板合成提供商自有元数据。 + 未知的 `glm-5*` id 仍会在内置提供商路径上执行前向解析： + 当该 id 符合当前 GLM-5 系列的形态时， + 系统会基于 `glm-4.7` 模板合成提供商自有元数据。 - 默认已为 Z.AI 工具调用流式传输启用 `tool_stream`。如需禁用： + 默认启用 `tool_stream` 用于 Z.AI 工具调用流式传输。要禁用它： ```json5 { @@ -137,6 +141,18 @@ GLM 模型可作为 `zai/` 使用（例如：`zai/glm-5`）。默认的 + + 内置 Z.AI 插件已注册图像理解能力。 + + | Property | Value | + | ------------- | ----------- | + | 模型 | `glm-4.6v` | + + 图像理解会根据已配置的 Z.AI 凭证自动解析—— + 无需额外配置。 + + + - Z.AI 使用你的 API 密钥进行 Bearer 身份验证。 - `zai-api-key` 新手引导选项会根据密钥前缀自动检测匹配的 Z.AI 端点。 @@ -147,10 +163,10 @@ GLM 模型可作为 `zai/` 使用（例如：`zai/glm-5`）。默认的 ## 相关内容 - - GLM 的模型系列概览。 + + GLM 的模型家族概览。 - 选择提供商、模型引用和故障切换行为。 + 选择提供商、模型引用和故障转移行为。