openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-12 11:09:10 +00:00
parent 1b8d1c8acb
commit ae349552be
7 changed files with 508 additions and 267 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
docs/zh-CN/providers/anthropic.md
View File

@ -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 登录
<Warning>
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/)
</Warning>
## 入门指南
<Tabs>
<Tab title="API key">
<Tab title="API 密钥">
**最适合：** 标准 API 访问和按使用量计费。
<Steps>
@ -48,7 +51,7 @@ Anthropic 当前的公开文档：
# choose: Anthropic API key
```
或直接传入密钥：
或者直接传入密钥：
```bash
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
@ -77,7 +80,7 @@ Anthropic 当前的公开文档：
<Steps>
<Step title="确保已安装 Claude CLI 并完成登录">
通过以下命令验证：
验证方式如下：
```bash
claude --version
@ -99,7 +102,7 @@ Anthropic 当前的公开文档：
</Steps>
<Note>
Claude CLI 后端的设置和运行时细节见 [CLI Backends](/zh-CN/gateway/cli-backends)。
Claude CLI 后端的设置与运行时细节见 [CLI 后端](/zh-CN/gateway/cli-backends)。
</Note>
<Tip>
@ -109,11 +112,11 @@ Anthropic 当前的公开文档：
</Tab>
</Tabs>
## Thinking 默认设置（Claude 4.6）
## 思考默认值（Claude 4.6）
当未设置显式的 thinking 级别时，Claude 4.6 模型在 OpenClaw 中默认使用 `adaptive` thinking。
当未设置显式思考级别时，Claude 4.6 模型在 OpenClaw 中默认使用 `adaptive` 思考。
可通过 `/think:<level>` 按消息覆盖，或在模型参数中设置：
可通过 `/think:<level>` 为每条消息覆盖，或在模型参数中设置：
```json5
{
@ -131,19 +134,19 @@ Anthropic 当前的公开文档：
<Note>
相关 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)
</Note>
## 提示缓存
## 提示词缓存
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 密钥认证。
<AccordionGroup>
<Accordion title="按智能体覆盖缓存">
使用模型级 `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`，按键覆盖）
这样可以让一个智能体保留长期缓存，而同一模型上的另一个智能体为突发性或低复用流量禁用缓存。
这样可以让一个智能体保留长期缓存，而同一模型上的另一个智能体则为突发型 / 低复用流量禁用缓存。
</Accordion>
<Accordion title="Bedrock Claude 说明">
- 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"`。
</Accordion>
</AccordionGroup>
@ -202,7 +205,7 @@ OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。
<AccordionGroup>
<Accordion title="快速模式">
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 密钥认证。
<Note>
- 仅对直连 `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`。
</Note>
</Accordion>
<Accordion title="1M 上下文窗口（beta）">
Anthropic 的 1M 上下文窗口受 beta 限制控制。可按模型启用：
<Accordion title="媒体理解（图片和 PDF）">
内置的 Anthropic 插件注册了图片和 PDF 理解能力。OpenClaw
会根据已配置的 Anthropic 认证自动解析媒体能力——无需
额外配置。
| Property | Value |
| --------------- | -------------------- |
| Default model | `claude-opus-4-6` |
| Supported input | Images, PDF documents |
当图片或 PDF 附加到会话中时，OpenClaw 会自动
通过 Anthropic 媒体理解提供商进行路由。
</Accordion>
<Accordion title="1M 上下文窗口（测试版）">
Anthropic 的 1M 上下文窗口受测试版权限控制。请按模型启用：
```json5
{
@ -251,7 +269,7 @@ OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。
OpenClaw 会将其映射为请求中的 `anthropic-beta: context-1m-2025-08-07`。
<Warning>
需要你的 Anthropic 凭证具备长上下文访问权限。旧版令牌认证（`sk-ant-oat-*`）会被拒绝用于 1M 上下文请求——OpenClaw 会记录一条警告，并回退到标准上下文窗口。
需要你的 Anthropic 凭证具备长上下文访问权限。旧版令牌认证（`sk-ant-oat-*`）不支持 1M 上下文请求——OpenClaw 会记录一条警告并回退到标准上下文窗口。
</Warning>
</Accordion>
@ -261,19 +279,19 @@ OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。
<AccordionGroup>
<Accordion title="401 错误 / 令牌突然失效">
Anthropic 令牌认证可能会过期或被撤销。对于新的设置，请迁移到 Anthropic API 密钥。
Anthropic 令牌认证可能过期或被撤销。对于新配置，建议迁移到 Anthropic API 密钥。
</Accordion>
<Accordion title='未找到提供商 "anthropic" 的 API 密钥'>
认证是**按智能体**进行的。新智能体不会继承主智能体的密钥。请为该智能体重新运行新手引导，或在 Gateway 网关主机上配置 API 密钥，然后使用 `openclaw models status` 验证。
认证是**按智能体**区分的。新智能体不会继承主智能体的密钥。请为该智能体重新运行新手引导，或在 Gateway 网关主机上配置 API 密钥，然后使用 `openclaw models status` 验证。
</Accordion>
<Accordion title='未找到配置文件 "anthropic:default" 的凭证'>
运行 `openclaw models status` 查看当前启用了哪个认证配置文件。重新运行新手引导，或为该配置文件路径配置 API 密钥。
运行 `openclaw models status` 以查看当前启用的是哪个认证配置文件。重新运行新手引导，或为该配置文件路径配置 API 密钥。
</Accordion>
<Accordion title="没有可用的认证配置文件（全部处于冷却中）">
检查 `openclaw models status --json` 中的 `auth.unusableProfiles`。Anthropic 的速率限制冷却可能是按模型范围生效的，因此同级的另一个 Anthropic 模型仍可能可用。添加另一个 Anthropic 配置文件，或等待冷却结束。
检查 `openclaw models status --json` 中的 `auth.unusableProfiles`。Anthropic 的速率限制冷却可能是按模型作用域生效的，因此同级的其他 Anthropic 模型可能仍可使用。添加另一个 Anthropic 配置文件，或等待冷却结束。
</Accordion>
</AccordionGroup>
@ -285,13 +303,13 @@ OpenClaw 支持 Anthropic 的提示缓存功能，用于 API 密钥认证。
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="CLI 后端" href="/zh-CN/gateway/cli-backends" icon="terminal">
Claude CLI 后端设置和运行时细节。
Claude CLI 后端设置与运行时细节。
</Card>
<Card title="提示缓存" href="/zh-CN/reference/prompt-caching" icon="database">
提示缓存在各提供商间的工作方式。
<Card title="提示词缓存" href="/zh-CN/reference/prompt-caching" icon="database">
提示词缓存在各提供商中的工作方式。
</Card>
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
认证细节和凭证复用规则。

47
docs/zh-CN/providers/github-copilot.md
View File

@ -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 的两种方式
<Tabs>
<Tab title="内置提供商（github-copilot）">
使用原生设备登录流程获取 GitHub 令牌，然后在 OpenClaw 运行时将其交换为 Copilot API 令牌。这是**默认**且最简单的路径，因为它不需要 VS Code。
使用原生设备登录流程获取 GitHub 令牌，然后在 OpenClaw 运行时将其交换为 Copilot API 令牌。这是**默认**且最简单的方式，因为它不需要 VS Code。
<Steps>
<Step title="运行登录命令">
@ -29,7 +29,7 @@ GitHub Copilot 是 GitHub 的 AI 编码助手。它会为你的 GitHub 账号和
openclaw models auth login-github-copilot
```
系统会提示你访问一个 URL 并输入一次性代码。在流程完成之前，请保持终端打开。
系统会提示你访问一个 URL 并输入一次性代码。在流程完成前，请保持终端处于打开状态。
</Step>
<Step title="设置默认模型">
```bash
@ -49,10 +49,10 @@ GitHub Copilot 是 GitHub 的 AI 编码助手。它会为你的 GitHub 账号和
</Tab>
<Tab title="Copilot Proxy 插件（copilot-proxy）">
使用 **Copilot Proxy** VS Code 扩展作为本地桥接。OpenClaw 会连接到该代理的 `/v1` 端点，并使用你在其中配置的模型列表。
使用 **Copilot Proxy** VS Code 扩展作为本地桥接。OpenClaw 会与代理的 `/v1` 端点通信，并使用你在其中配置的模型列表。
<Note>
如果你已经在 VS Code 中运行 Copilot Proxy，或者需要通过它进行路由，请选择此项。你必须启用该插件，并保持 VS Code 扩展持续运行。
如果你已经在 VS Code 中运行 Copilot Proxy，或需要通过它进行路由，请选择此方式。你必须启用该插件，并保持 VS Code 扩展持续运行。
</Note>
</Tab>
@ -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
<AccordionGroup>
<Accordion title="需要交互式 TTY">
设备登录流程需要交互式 TTY。请直接在终端中运行，而不要在非交互式脚本或 CI 流水线中运行。
设备登录流程需要交互式 TTY。请直接在终端中运行，不要在非交互式脚本或 CI 流水线中运行。
</Accordion>
<Accordion title="模型可用性取决于你的套餐">
Copilot 模型的可用性取决于你的 GitHub 套餐。如果某个模型被拒绝，请尝试其他 ID（例如 `github-copilot/gpt-4.1`）。
<Accordion title="模型可用性取决于你的订阅计划">
Copilot 模型的可用性取决于你的 GitHub 订阅计划。如果某个模型被拒绝，请尝试其他 ID（例如 `github-copilot/gpt-4.1`）。
</Accordion>
<Accordion title="传输协议选择">
Claude 模型 ID 会自动使用 Anthropic Messages 传输协议。GPT、o-series 和 Gemini 模型会继续使用 OpenAI Responses 传输协议。OpenClaw 会根据模型 ref 选择正确的传输协议。
<Accordion title="传输方式选择">
Claude 模型 ID 会自动使用 Anthropic Messages 传输方式。GPT、o-series 和 Gemini 模型会继续使用 OpenAI Responses 传输方式。OpenClaw 会根据模型 ref 选择正确的传输方式。
</Accordion>
<Accordion title="环境变量 解析顺序">
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`）会将其令牌存储到身份验证配置文件存储中，并且优先于所有环境变量。
</Accordion>
<Accordion title="令牌存储">
登录会将 GitHub 令牌存储在认证配置文件存储中，并在 OpenClaw 运行时将其交换为 Copilot API 令牌。你不需要手动管理该令牌。
登录流程会将 GitHub 令牌存储到身份验证配置文件存储中，并在 OpenClaw 运行时将其交换为 Copilot API 令牌。你无需手动管理该令牌。
</Accordion>
</AccordionGroup>
@ -99,9 +112,9 @@ openclaw models auth login --provider github-copilot --method device --set-defau
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型 ref 和故障切换行为。
选择提供商、模型 ref 和故障转移行为。
</Card>
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
认证细节和凭证复用规则。
<Card title="OAuth 和身份验证" href="/zh-CN/gateway/authentication" icon="key">
身份验证细节和凭证复用规则。
</Card>
</CardGroup>

121
docs/zh-CN/providers/ollama.md
View File

@ -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 模型。
<Warning>
**远程 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`）。
</Warning>
## 入门指南
选择你偏好的设置方式和模式。
选择你偏好的设置方法和模式。
<Tabs>
<Tab title="新手引导（推荐）">
**最适合：** 以最快方式完成可用的 Ollama 设置，并自动发现模型。
**最适合：** 以最快路径完成可用的 Ollama 设置，并自动发现模型。
<Steps>
<Step title="运行新手引导">
@ -35,16 +35,16 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上
openclaw onboard
```
在提供商列表中选择 **Ollama**。
从提供商列表中选择 **Ollama**。
</Step>
<Step title="选择你的模式">
- **云端 + 本地** — 同时使用云端托管模型和本地模型
- **仅本地** — 仅使用本地模型
- **Cloud + Local** — 同时使用云端托管模型和本地模型
- **Local** — 仅使用本地模型
如果你选择 **云端 + 本地** 且尚未登录 ollama.com，新手引导会打开浏览器登录流程。
如果你选择 **Cloud + Local**，但尚未登录 ollama.com，新手引导会打开浏览器登录流程。
</Step>
<Step title="选择模型">
新手引导会发现可用模型并推荐默认项。如果所选模型在本地不可用，它会自动拉取该模型。
新手引导会发现可用模型并推荐默认选项。如果所选模型尚未在本地可用，它会自动拉取该模型。
</Step>
<Step title="验证模型是否可用">
```bash
@ -61,7 +61,7 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上
--accept-risk
```
你也可以选择性指定自定义基础 URL 或模型：
你也可以选择性指定自定义 base URL 或模型：
```bash
openclaw onboard --non-interactive \
@ -74,7 +74,7 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上
</Tab>
<Tab title="手动设置">
**最适合：** 完全掌控安装、模型拉取和配置。
**最适合：** 完全控制安装、模型拉取和配置。
<Steps>
<Step title="安装 Ollama">
@ -90,7 +90,7 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上
```
</Step>
<Step title="登录以使用云端模型（可选）">
如果你还想使用云端模型：
如果你也想使用云端模型：
```bash
ollama signin
@ -107,7 +107,7 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上
openclaw config set models.providers.ollama.apiKey "ollama-local"
```
</Step>
<Step title="检查并设置你的模型">
<Step title="查看并设置你的模型">
```bash
openclaw models list
openclaw models set ollama/gemma4
@ -133,10 +133,10 @@ Ollama 是一个本地 LLM 运行时，让你能够轻松在自己的机器上
## 云端模型
<Tabs>
<Tab title="云端 + 本地">
云端模型让你能够在使用本地模型的同时，也使用云端托管模型。例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud` —— 这些都**不需要**本地执行 `ollama pull`。
<Tab title="Cloud + Local">
云端模型让你可以将云端托管模型与本地模型一起使用。示例包括 `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 运行时，让你能够轻松在自己的机器上
</Tab>
<Tab title="仅本地">
在仅本地模式下，OpenClaw 会从本地 Ollama 实例中发现模型。不需要云端登录。
在仅本地模式下，OpenClaw 会从本地 Ollama 实例发现模型。不需要登录云端。
OpenClaw 当前推荐 `gemma4` 作为本地默认模型。
</Tab>
</Tabs>
## 模型发现（隐式提供商）
## 模型发现（隐式 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
<Tabs>
<Tab title="基础（隐式发现）">
启用 Ollama 的最简单方式是通过环境变量：
启用 Ollama 的最简单方式是使用环境变量：
```bash
export OLLAMA_API_KEY="ollama-local"
```
<Tip>
如果设置了 `OLLAMA_API_KEY`，你可以在提供商条目中省略 `apiKey`，OpenClaw 会为可用性检查自动填充它。
如果已设置 `OLLAMA_API_KEY`，你可以在 provider 条目中省略 `apiKey`，OpenClaw 会自动填充它以进行可用性检查。
</Tip>
</Tab>
@ -231,7 +231,7 @@ ollama pull mistral
</Tab>
<Tab title="自定义基础 URL">
<Tab title="自定义 base URL">
如果 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
```
<Warning>
不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用不可靠。请使用不带路径后缀的 Ollama 基础 URL。
不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama 基础 URL。
</Warning>
</Tab>
@ -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` 提供商
```
<Note>
有关完整的设置和行为详情，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。
有关完整设置和行为细节，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。
</Note>
## 高级配置
@ -305,7 +305,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商
<AccordionGroup>
<Accordion title="旧版 OpenAI 兼容模式">
<Warning>
**在 OpenAI 兼容模式下，工具调用并不可靠。** 只有当你需要为代理使用 OpenAI 格式且不依赖原生工具调用行为时，才应使用此模式。
**在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为代理使用 OpenAI 格式，且不依赖原生工具调用行为时，才使用此模式。
</Warning>
如果你需要改用 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` 提供商
<Accordion title="上下文窗口">
对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，否则会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。
你可以在显式提供商配置中覆盖 `contextWindow` 和 `maxTokens`：
你可以在显式 provider 配置中覆盖 `contextWindow` 和 `maxTokens`：
```json5
{
@ -374,25 +374,50 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商
</Accordion>
<Accordion title="推理模型">
OpenClaw 默认会将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为具备推理能力。
默认情况下，OpenClaw 会将名称包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为具备推理能力。
```bash
ollama pull deepseek-r1:32b
```
不需要额外配置 —— OpenClaw 会自动标记它们。
不需要额外配置——OpenClaw 会自动标记它们。
</Accordion>
<Accordion title="模型成本">
Ollama 是免费的，并且在本地运行，因此所有模型成本都设置为 $0。这同时适用于自动发现的模型和手动定义的模型。
Ollama 可免费使用并在本地运行，因此所有模型成本都设置为 $0。这同时适用于自动发现和手动定义的模型。
</Accordion>
<Accordion title="记忆嵌入">
内置的 Ollama 插件为
[记忆搜索](/zh-CN/concepts/memory)
注册了一个记忆嵌入提供商。它使用已配置的 Ollama base URL
和 API 密钥。
| 属性 | 值 |
| ------------- | ------------------- |
| 默认模型 | `nomic-embed-text` |
| 自动拉取 | 是——如果嵌入模型尚未在本地存在，将自动拉取 |
要将 Ollama 选为记忆搜索的嵌入提供商：
```json5
{
agents: {
defaults: {
memorySearch: { provider: "ollama" },
},
},
}
```
</Accordion>
<Accordion title="流式传输配置">
OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），它完全支持同时进行流式传输和工具调用。不需要任何特殊配置。
OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），可同时完整支持流式传输和工具调用。不需要特殊配置。
<Tip>
如果你需要使用 OpenAI 兼容端点，请参阅上方的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。
如果你需要使用 OpenAI 兼容端点，请参阅上方“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。
</Tip>
</Accordion>
@ -402,7 +427,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商
<AccordionGroup>
<Accordion title="未检测到 Ollama">
请确认 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` 提供商
</Accordion>
<Accordion title="连接被拒绝">
检查 Ollama 是否正在正确的端口上运行：
检查 Ollama 是否在正确的端口上运行：
```bash
# 检查 Ollama 是否正在运行
@ -456,7 +481,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商
如何选择和配置模型。
</Card>
<Card title="Ollama Web 搜索" href="/zh-CN/tools/ollama-search" icon="magnifying-glass">
了解由 Ollama 驱动的 Web 搜索的完整设置和行为详情。
由 Ollama 提供支持的 Web 搜索的完整设置和行为细节。
</Card>
<Card title="配置" href="/zh-CN/gateway/configuration" icon="gear">
完整配置参考。

181
docs/zh-CN/providers/openai.md
View File

@ -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。
## 入门指南
选择你偏好的凭证方式，并按照设置步骤操作。
选择你偏好的凭证方式，并按照设置步骤进行操作。
<Tabs>
<Tab title="API 密钥（OpenAI Platform）">
**最适合：** 直接 API 访问和按使用量计费。
**最适合：** 直接访问 API 并按用量计费。
<Steps>
<Step title="获取你的 API 密钥">
@ -74,13 +74,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<Warning>
OpenClaw **不会**在直接 API 路径中暴露 `openai/gpt-5.3-codex-spark`。真实的 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
OpenClaw **不会** 在直接 API 路径上暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
</Warning>
</Tab>
<Tab title="Codex 订阅">
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex 云需要 ChatGPT 登录。
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要使用 ChatGPT 登录。
<Steps>
<Step title="运行 Codex OAuth">
@ -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） |
<Note>
此路由与 `openai/gpt-5.4` 是有意分开的。直接 Platform 访问请使用带 API 密钥的 `openai/*`，Codex 订阅访问请使用 `openai-codex/*`。
这一路由与 `openai/gpt-5.4` 是有意分开的。使用 API 密钥配合 `openai/*` 以直接访问 Platform，而使用 `openai-codex/*` 以通过 Codex 订阅访问。
</Note>
### 配置示例
@ -126,7 +126,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<Tip>
如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续由 Codex CLI 管理。凭证过期后，OpenClaw 会先重新读取外部 Codex 来源，再将刷新的凭证写回 Codex 存储。
如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续由 Codex CLI 管理。凭证过期时，OpenClaw 会先重新读取外部 Codex 来源，然后将刷新的凭证写回 Codex 存储。
</Tip>
### 上下文窗口上限
@ -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)。
</Note>
## 个性叠加层
## 个性覆盖层
对于 `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
</Tabs>
<Tip>
运行时值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用该叠加层。
运行时会以不区分大小写的方式处理这些值，因此 `"Off"` 和 `"off"` 都会禁用该覆盖层。
</Tip>
## 语音与语音处理
<AccordionGroup>
<Accordion title="语音合成（TTS）">
内置的 `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" },
},
},
},
}
```
<Note>
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 Base URL，而不会影响聊天 API 端点。
</Note>
</Accordion>
<Accordion title="实时转录">
内置的 `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` |
<Note>
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并采用 G.711 u-law 音频。
</Note>
</Accordion>
<Accordion title="实时语音">
内置的 `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` |
<Note>
通过 `azureEndpoint` 和 `azureDeployment` 配置键支持 Azure OpenAI。支持双向工具调用。使用 G.711 u-law 音频格式。
</Note>
</Accordion>
</AccordionGroup>
## 高级配置
<AccordionGroup>
<Accordion title="传输方式（WebSocket 与 SSE）">
对于 `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
</Accordion>
<Accordion title="WebSocket 预热">
对于 `openai/*`，OpenClaw 默认启用 WebSocket 预热，以降低首轮延迟。
OpenClaw 默认会为 `openai/*` 启用 WebSocket 预热，以减少首轮延迟。
```json5
// 禁用预热
@ -303,7 +374,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
</Accordion>
<Accordion title="快速模式">
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供统一的快速模式开关：
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供共享的快速模式开关：
- **聊天 / UI：** `/fast status|on|off`
- **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
@ -324,7 +395,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<Note>
会话覆盖优先生效。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置中的默认值。
会话覆盖的优先级高于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置中的默认值。
</Note>
</Accordion>
@ -348,17 +419,17 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
支持的值：`auto`、`default`、`flex`、`priority`。
<Warning>
`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` 不变。
</Warning>
</Accordion>
<Accordion title="服务端压缩（Responses API）">
对于直接使用 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`）
<Tabs>
<Tab title="显式启用">
@ -414,13 +485,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
</Tabs>
<Note>
`responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性配置将 `supportsStore` 设为 `false`。
`responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。
</Note>
</Accordion>
<Accordion title="严格智能体 GPT 模式">
对于 `openai/*` 和 `openai-codex/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的内嵌执行契约：
<Accordion title="严格智能体式 GPT 模式">
对于 `openai/*` 和 `openai-codex/*` 上 GPT-5 系列的运行，OpenClaw 可以使用更严格的内嵌执行契约：
```json5
{
@ -432,32 +503,32 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
}
```
启用 `strict-agentic` 后，OpenClaw 会：
- 当有可用工具操作时，不再将仅规划的轮次视为成功进展
- 使用“立即行动”的引导重试该轮次
- 对于实质性工作自动启用 `update_plan`
- 如果模型持续规划而不执行操作，则显示明确的受阻状态
使用 `strict-agentic` 时，OpenClaw 会：
- 当工具操作可用时，不再将“仅做计划”的轮次视为成功推进
- 通过“立即行动”的引导重试该轮
- 对于较大工作自动启用 `update_plan`
- 如果模型持续只做计划而不行动，则显示明确的阻塞状态
<Note>
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列保持默认行为。
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列将保持默认行为。
</Note>
</Accordion>
<Accordion title="原生路由与 OpenAI 兼容路由">
OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用的 OpenAI 兼容 `/v1` 代理不同：
<Accordion title="原生路由与 OpenAI-compatible 路由">
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 使用原生传输和兼容行为，但不会接收隐藏归因头。
</Accordion>
</AccordionGroup>
@ -474,7 +545,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
</Card>
<Card title="OAuth 与凭证" href="/zh-CN/gateway/authentication" icon="key">
凭证细节和凭证复用规则。
<Card title="OAuth 和凭证" href="/zh-CN/gateway/authentication" icon="key">
凭证详情和凭证复用规则。
</Card>
</CardGroup>

130
docs/zh-CN/providers/qwen.md
View File

@ -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:
<Warning>
**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)。
</Warning>
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 兼容
<Tip>
如果你想使用 `qwen3.6-plus`，建议优先选择**标准版（按量付费）**端点。
如果你想使用 `qwen3.6-plus`，建议优先选择**标准版（按量计费）**端点。
Coding Plan 支持可能会落后于公开目录。
</Tip>
@ -81,14 +81,15 @@ Coding Plan 支持可能会落后于公开目录。
</Steps>
<Note>
旧版 `modelstudio-*` auth-choice id 和 `modelstudio/...` 模型引用仍然可作为兼容性别名继续使用，但新的设置流程应优先使用规范的
旧版 `modelstudio-*` auth-choice id 和 `modelstudio/...` 模型引用仍然
可以作为兼容性别名继续使用，但新的设置流程应优先使用规范的
`qwen-*` auth-choice id 和 `qwen/...` 模型引用。
</Note>
</Tab>
<Tab title="标准版（按量付费）">
**最适合：** 通过标准版 Model Studio 端点进行按量付费访问，包括 `qwen3.6-plus` 等在 Coding Plan 中可能不可用的模型。
<Tab title="标准版（按量计费）">
**最适合：** 通过标准版 Model Studio 端点进行按量计费访问，包括像 `qwen3.6-plus` 这样在 Coding Plan 中可能不可用的模型。
<Steps>
<Step title="获取你的 API 密钥">
@ -126,7 +127,8 @@ Coding Plan 支持可能会落后于公开目录。
</Steps>
<Note>
旧版 `modelstudio-*` auth-choice id 和 `modelstudio/...` 模型引用仍然可作为兼容性别名继续使用，但新的设置流程应优先使用规范的
旧版 `modelstudio-*` auth-choice id 和 `modelstudio/...` 模型引用仍然
可以作为兼容性别名继续使用，但新的设置流程应优先使用规范的
`qwen-*` auth-choice id 和 `qwen/...` 模型引用。
</Note>
@ -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` 进行覆盖。
<Tip>
**管理密钥：** [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 |
<Note>
即使某个模型出现在内置目录中，其可用性仍可能因端点和计费套餐而异。
@ -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 端点）：
```
<Note>
共享工具参数、提供商选择和故障转移行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。
有关共享工具参数、提供商选择和故障切换行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。
</Note>
## 高级
<AccordionGroup>
<Accordion title="图像和视频理解">
内置的 Qwen 插件会在**标准版** DashScope 端点（而非 Coding Plan 端点）上为图像和视频注册媒体理解能力。
| 属性 | 值 |
| ------------- | --------------------- |
| 模型 | `qwen-vl-max-latest` |
| 支持的输入 | 图像、视频 |
媒体理解会根据已配置的 Qwen 凭证自动解析——
无需额外配置。请确保你使用的是支持媒体理解的标准版（按量计费）
端点。
</Accordion>
<Accordion title="Qwen 3.6 Plus 可用性">
`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
端点 / 密钥组合。
</Accordion>
<Accordion title="能力规划">
`qwen` 扩展正被定位为完整 Qwen
Cloud 能力面的厂商归属点，而不仅仅是编码/文本模型。
`qwen` 扩展正在被定位为完整 Qwen
Cloud 能力面的厂商归属入口，而不仅仅是编码 / 文本模型。
- **文本/聊天模型：** 当前已内置
- **工具调用、结构化输出、思考：** 继承自兼容 OpenAI 的传输层
- **图像生成：** 计划在提供商插件层提供
- **图像/视频理解：** 当前已在标准版端点内置
- **语音/音频：** 计划在提供商插件层提供
- **Memory 嵌入/重排：** 计划通过嵌入适配器能力面提供
- **视频生成：** 当前已通过共享的视频生成能力内置
- **文本 / 聊天模型：** 现已内置
- **工具调用、结构化输出、思维链：** 继承自与 OpenAI 兼容的传输层
- **图像生成：** 计划在提供商插件层支持
- **图像 / 视频理解：** 现已在标准版端点内置
- **语音 / 音频：** 计划在提供商插件层支持
- **Memory 嵌入 / 重排序：** 计划通过嵌入适配器能力面支持
- **视频生成：** 现已通过共享视频生成能力内置
</Accordion>
<Accordion title="视频生成详情">
对于视频生成，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 视频端点不接受
为这些参考上传本地缓冲区。
</Accordion>
<Accordion title="流式使用量兼容性">
原生 Model Studio 端点会在共享的
`openai-completions` 传输上声明流式使用量兼容性。OpenClaw 现在会基于端点能力来判断，因此，指向相同原生主机的 DashScope 兼容自定义提供商 id 也会继承相同的流式使用量行为，而不再要求必须是内置 `qwen` 提供商 id。
<Accordion title="流式使用兼容性">
原生 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`
</Accordion>
<Accordion title="环境和守护进程设置">
如果 Gateway 网关以守护进程方式运行（launchd/systemd），请确保 `QWEN_API_KEY`
如果 Gateway 网关以守护进程（launchd/systemd）方式运行，请确保 `QWEN_API_KEY`
对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过
`env.shellEnv` 提供）。
</Accordion>
@ -281,7 +303,7 @@ DashScope 端点上提供多模态能力（不包括 Coding Plan 端点）：
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
@ -290,6 +312,6 @@ DashScope 端点上提供多模态能力（不包括 Coding Plan 端点）：
旧版 ModelStudio 提供商和迁移说明。
</Card>
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
通用故障排除和常见问题。
常规故障排除和常见问题。
</Card>
</CardGroup>

126
docs/zh-CN/providers/xai.md
View File

@ -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` 提供商插件。
</Steps>
<Note>
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`。
</Note>
## 内置模型目录
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 形态时，该插件也会将其转发解析。
<Tip>
`grok-4-fast`、`grok-4-1-fast` 以及 `grok-4.20-beta-*` 变体，
@ -73,7 +73,7 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族：
### 快速模式映射
`/fast on` 或 `agents.defaults.models["xai/<model>"].params.fastMode: true`
会按如下方式重写原生 xAI 请求：
会将原生 xAI 请求重写如下：
| 源模型 | 快速模式目标 |
| ------------- | ------------------ |
@ -84,7 +84,7 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族：
### 旧版兼容别名
旧版别名仍会规范化为标准的内置 ID：
旧版别名仍会规范化为标准内置 ID：
| 旧版别名 | 标准 ID |
| ------------------------- | ------------------------------------- |
@ -106,15 +106,15 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族：
</Accordion>
<Accordion title="视频生成">
内置的 `xai` 插件通过共享的
`video_generate` 工具注册了视频生成功能。
内置 `xai` 插件通过共享的
`video_generate` 工具注册视频生成功能。
- 默认视频模型：`xai/grok-imagine-video`
- 模式：文生视频、图生视频，以及远程视频编辑/扩展流程
- 支持 `aspectRatio` 和 `resolution`
<Warning>
不接受本地视频缓冲区。请对视频参考和编辑输入使用远程 `http(s)` URL。
不接受本地视频缓冲区。请为视频参考和编辑输入使用远程 `http(s)` URL。
</Warning>
要将 xAI 用作默认视频提供商：
@ -132,14 +132,87 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族：
```
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
请参阅 [视频生成](/zh-CN/tools/video-generation) 以了解共享工具参数、
提供商选择和故障转移行为。
</Note>
</Accordion>
<Accordion title="x_search 配置">
内置 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,
},
},
},
},
},
}
```
</Accordion>
<Accordion title="code_execution 配置">
内置 xAI 插件将 `code_execution` 作为 OpenClaw 工具公开，
用于在 xAI 的沙箱环境中执行远程代码。
配置路径：`plugins.entries.xai.config.codeExecution`
| 键名 | 类型 | 默认值 | 描述 |
| ----------------- | ------- | ------------------ | ---------------------------------------- |
| `enabled` | boolean | `true`（如果密钥可用） | 启用或禁用代码执行 |
| `model` | string | `grok-4-1-fast` | 用于代码执行请求的模型 |
| `maxTurns` | number | — | 最大对话轮数 |
| `timeoutSeconds` | number | — | 请求超时时间（秒） |
<Note>
这是远程 xAI 沙箱执行，不是本地 [`exec`](/zh-CN/tools/exec)。
</Note>
```json5
{
plugins: {
entries: {
xai: {
config: {
codeExecution: {
enabled: true,
model: "grok-4-1-fast",
},
},
},
},
},
}
```
</Accordion>
<Accordion title="已知限制">
- 当前身份验证仅支持 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 传输方式。
</Accordion>
<Accordion title="高级说明">
@ -147,10 +220,13 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族：
- 原生 xAI 请求默认使用 `tool_stream: true`。将
`agents.defaults.models["xai/<model>"].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)。
</Accordion>
</AccordionGroup>
@ -159,15 +235,15 @@ OpenClaw 开箱即用地包含以下 xAI 模型家族：
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障切换行为。
选择提供商、模型引用和故障转移行为。
</Card>
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
</Card>
<Card title="所有提供商" href="/zh-CN/providers/index" icon="grid-2">
更全面的提供商概览。
更广泛的提供商概览。
</Card>
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
常见问题及修复方法。
常见问题和修复方法。
</Card>
</CardGroup>

66
docs/zh-CN/providers/zai.md
View File

@ -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` | |
<Tip>
GLM 模型可作为 `zai/<model>` 使用（例如：`zai/glm-5`）。默认的内置模型引用是 `zai/glm-5.1`。
GLM 模型可用 `zai/<model>` 的形式使用（例如：`zai/glm-5`）。默认内置模型引用是 `zai/glm-5.1`。
</Tip>
## 高级配置
<AccordionGroup>
<Accordion title="前向解析未知的 GLM-5 模型">
未知的 `glm-5*` id 在匹配当前 GLM-5 家族形态时，仍会通过内置提供商路径进行前向解析，方法是基于 `glm-4.7` 模板合成提供商自有元数据。
未知的 `glm-5*` id 仍会在内置提供商路径上执行前向解析：
当该 id 符合当前 GLM-5 系列的形态时，
系统会基于 `glm-4.7` 模板合成提供商自有元数据。
</Accordion>
<Accordion title="工具调用流式传输">
默认已为 Z.AI 工具调用流式传输启用 `tool_stream`。如需禁用：
默认启用 `tool_stream` 用于 Z.AI 工具调用流式传输。要禁用它：
```json5
{
@ -137,6 +141,18 @@ GLM 模型可作为 `zai/<model>` 使用（例如：`zai/glm-5`）。默认的
</Accordion>
<Accordion title="图像理解">
内置 Z.AI 插件已注册图像理解能力。
| Property | Value |
| ------------- | ----------- |
| 模型 | `glm-4.6v` |
图像理解会根据已配置的 Z.AI 凭证自动解析——
无需额外配置。
</Accordion>
<Accordion title="凭证详情">
- Z.AI 使用你的 API 密钥进行 Bearer 身份验证。
- `zai-api-key` 新手引导选项会根据密钥前缀自动检测匹配的 Z.AI 端点。
@ -147,10 +163,10 @@ GLM 模型可作为 `zai/<model>` 使用（例如：`zai/glm-5`）。默认的
## 相关内容
<CardGroup cols={2}>
<Card title="GLM 模型系列" href="/zh-CN/providers/glm" icon="microchip">
GLM 的模型系列概览。
<Card title="GLM 模型家族" href="/zh-CN/providers/glm" icon="microchip">
GLM 的模型家族概览。
</Card>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障切换行为。
选择提供商、模型引用和故障转移行为。
</Card>
</CardGroup>