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 10:04:18 +00:00
parent 0a13fb2342
commit 4090a214a2
5 changed files with 1289 additions and 913 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

437
docs/zh-CN/providers/bedrock.md
View File

@ -1,155 +1,200 @@
---
read_when:
- 你想将 Amazon Bedrock 模型与 OpenClaw 配合使用
- 你需要为模型调用设置 AWS 凭证/区域
summary: 使用 Amazon Bedrock（Converse API）模型与 OpenClaw 配合
- 你想在 OpenClaw 中使用 Amazon Bedrock 模型
- 你需要先设置 AWS 凭证和区域，才能发起模型调用
summary: 使用 OpenClaw 搭配 Amazon Bedrock（Converse API）模型
title: Amazon Bedrock
x-i18n:
generated_at: "2026-04-06T00:33:38Z"
generated_at: "2026-04-12T10:03:22Z"
model: gpt-5.4
provider: openai
source_hash: 70bb29fe9199084b1179ced60935b5908318f5b80ced490bf44a45e0467c4929
source_hash: 88e7e24907ec26af098b648e2eeca32add090a9e381c818693169ab80aeccc47
source_path: providers/bedrock.md
workflow: 15
---
# Amazon Bedrock
OpenClaw 可以通过 pi‑ai 的 **Bedrock Converse** 流式传输提供商使用 **Amazon Bedrock** 模型。Bedrock 认证使用 **AWS SDK 默认凭证链**，而不是 API 密钥。
OpenClaw 可以通过 pi-ai 的 **Bedrock Converse** 流式 provider 使用 **Amazon Bedrock** 模型。Bedrock 身份验证使用 **AWS SDK 默认凭证链**，而不是 API key。
## pi-ai 支持的内容
| 属性 | 值 |
| -------- | ----------------------------------------------------------- |
| 提供商 | `amazon-bedrock` |
| API | `bedrock-converse-stream` |
| 身份验证 | AWS 凭证（环境变量、共享配置或实例角色） |
| 区域 | `AWS_REGION` 或 `AWS_DEFAULT_REGION`（默认：`us-east-1`） |
- 提供商：`amazon-bedrock`
- API：`bedrock-converse-stream`
- 认证：AWS 凭证（环境变量、共享配置或实例角色）
- 区域：`AWS_REGION` 或 `AWS_DEFAULT_REGION`（默认：`us-east-1`）
## 入门指南
选择你偏好的身份验证方式，并按照设置步骤进行操作。
<Tabs>
<Tab title="访问密钥 / 环境变量">
**最适合：** 直接管理 AWS 凭证的开发机器、CI 或主机。
<Steps>
<Step title="在 Gateway 网关主机上设置 AWS 凭证">
```bash
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"
# 可选：
export AWS_SESSION_TOKEN="..."
export AWS_PROFILE="your-profile"
# 可选（Bedrock API key / bearer token）：
export AWS_BEARER_TOKEN_BEDROCK="..."
```
</Step>
<Step title="将 Bedrock provider 和模型添加到你的配置中">
不需要 `apiKey`。请使用 `auth: "aws-sdk"` 配置该 provider：
```json5
{
models: {
providers: {
"amazon-bedrock": {
baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
api: "bedrock-converse-stream",
auth: "aws-sdk",
models: [
{
id: "us.anthropic.claude-opus-4-6-v1:0",
name: "Claude Opus 4.6 (Bedrock)",
reasoning: true,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 200000,
maxTokens: 8192,
},
],
},
},
},
agents: {
defaults: {
model: { primary: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0" },
},
},
}
```
</Step>
<Step title="验证模型可用">
```bash
openclaw models list
```
</Step>
</Steps>
<Tip>
使用环境变量标记身份验证（`AWS_ACCESS_KEY_ID`、`AWS_PROFILE` 或 `AWS_BEARER_TOKEN_BEDROCK`）时，OpenClaw 会自动启用隐式 Bedrock provider 以进行模型发现，无需额外配置。
</Tip>
</Tab>
<Tab title="EC2 实例角色（IMDS）">
**最适合：** 附加了 IAM 角色、并使用实例元数据服务进行身份验证的 EC2 实例。
<Steps>
<Step title="显式启用发现">
使用 IMDS 时，OpenClaw 无法仅通过环境变量标记检测 AWS 身份验证，因此你必须手动启用：
```bash
openclaw config set plugins.entries.amazon-bedrock.config.discovery.enabled true
openclaw config set plugins.entries.amazon-bedrock.config.discovery.region us-east-1
```
</Step>
<Step title="可选：添加环境变量标记以启用自动模式">
如果你还希望基于环境变量标记的自动检测路径生效（例如用于 `openclaw status` 相关界面）：
```bash
export AWS_PROFILE=default
export AWS_REGION=us-east-1
```
你**不**需要伪造的 API key。
</Step>
<Step title="验证模型已被发现">
```bash
openclaw models list
```
</Step>
</Steps>
<Warning>
附加到你的 EC2 实例的 IAM 角色必须具有以下权限：
- `bedrock:InvokeModel`
- `bedrock:InvokeModelWithResponseStream`
- `bedrock:ListFoundationModels`（用于自动发现）
- `bedrock:ListInferenceProfiles`（用于推理配置文件发现）
或者附加托管策略 `AmazonBedrockFullAccess`。
</Warning>
<Note>
只有在你明确希望为自动模式或状态界面提供环境变量标记时，才需要设置 `AWS_PROFILE=default`。实际的 Bedrock 运行时身份验证路径使用 AWS SDK 默认链，因此即使没有环境变量标记，IMDS 实例角色身份验证也能工作。
</Note>
</Tab>
</Tabs>
## 自动模型发现
OpenClaw 可以自动发现支持**流式传输**和**文本输出**的 Bedrock 模型。发现过程使用 `bedrock:ListFoundationModels` 和 `bedrock:ListInferenceProfiles`，结果会被缓存（默认：1 小时）。
OpenClaw 可以自动发现支持 **流式传输** 和 **文本输出** 的 Bedrock 模型。发现过程使用 `bedrock:ListFoundationModels` 和 `bedrock:ListInferenceProfiles`，结果会被缓存（默认：1 小时）。
隐式提供商的启用方式：
隐式 provider 的启用方式如下：
- 如果 `plugins.entries.amazon-bedrock.config.discovery.enabled` 为 `true`，即使不存在 AWS 环境变量标记，OpenClaw 也会尝试发现。
- 如果 `plugins.entries.amazon-bedrock.config.discovery.enabled` 未设置，OpenClaw 只会在看到以下任一 AWS 认证标记时自动添加隐式 Bedrock 提供商：
`AWS_BEARER_TOKEN_BEDROCK`、`AWS_ACCESS_KEY_ID` +
`AWS_SECRET_ACCESS_KEY`，或 `AWS_PROFILE`。
- 实际的 Bedrock 运行时认证路径仍然使用 AWS SDK 默认链，因此即使发现过程需要使用 `enabled: true` 显式启用，共享配置、SSO 和 IMDS 实例角色认证也仍然可以工作。
- 如果 `plugins.entries.amazon-bedrock.config.discovery.enabled` 为 `true`，即使不存在 AWS 环境变量标记，OpenClaw 也会尝试执行发现。
- 如果 `plugins.entries.amazon-bedrock.config.discovery.enabled` 未设置，OpenClaw 只有在检测到以下 AWS 身份验证标记之一时，才会自动添加隐式 Bedrock provider：`AWS_BEARER_TOKEN_BEDROCK`、`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`，或 `AWS_PROFILE`。
- 实际的 Bedrock 运行时身份验证路径仍然使用 AWS SDK 默认链，因此即使发现过程需要通过 `enabled: true` 手动启用，共享配置、SSO 和 IMDS 实例角色身份验证仍然可以正常工作。
配置选项位于 `plugins.entries.amazon-bedrock.config.discovery` 下：
<Note>
对于显式 `models.providers["amazon-bedrock"]` 条目，OpenClaw 仍然可以从 AWS 环境变量标记（例如 `AWS_BEARER_TOKEN_BEDROCK`）中提前解析 Bedrock 环境变量标记身份验证，而无需强制加载完整的运行时身份验证。实际的模型调用身份验证路径仍然使用 AWS SDK 默认链。
</Note>
```json5
{
plugins: {
entries: {
"amazon-bedrock": {
config: {
discovery: {
enabled: true,
region: "us-east-1",
providerFilter: ["anthropic", "amazon"],
refreshInterval: 3600,
defaultContextWindow: 32000,
defaultMaxTokens: 4096,
<AccordionGroup>
<Accordion title="发现配置选项">
配置选项位于 `plugins.entries.amazon-bedrock.config.discovery` 下：
```json5
{
plugins: {
entries: {
"amazon-bedrock": {
config: {
discovery: {
enabled: true,
region: "us-east-1",
providerFilter: ["anthropic", "amazon"],
refreshInterval: 3600,
defaultContextWindow: 32000,
defaultMaxTokens: 4096,
},
},
},
},
},
},
},
}
```
}
```
说明：
| 选项 | 默认值 | 描述 |
| ------ | ------- | ----------- |
| `enabled` | 自动 | 在自动模式下，OpenClaw 仅在检测到受支持的 AWS 环境变量标记时启用隐式 Bedrock provider。设置为 `true` 可强制执行发现。 |
| `region` | `AWS_REGION` / `AWS_DEFAULT_REGION` / `us-east-1` | 用于发现 API 调用的 AWS 区域。 |
| `providerFilter` | （全部） | 匹配 Bedrock provider 名称（例如 `anthropic`、`amazon`）。 |
| `refreshInterval` | `3600` | 缓存持续时间（秒）。设置为 `0` 可禁用缓存。 |
| `defaultContextWindow` | `32000` | 用于已发现模型的上下文窗口（如果你知道模型限制，可覆盖此值）。 |
| `defaultMaxTokens` | `4096` | 用于已发现模型的最大输出 token 数（如果你知道模型限制，可覆盖此值）。 |
- `enabled` 默认为自动模式。在自动模式下，OpenClaw 仅在检测到受支持的 AWS 环境变量标记时启用隐式 Bedrock 提供商。
- `region` 默认为 `AWS_REGION` 或 `AWS_DEFAULT_REGION`，然后回退到 `us-east-1`。
- `providerFilter` 匹配 Bedrock 提供商名称（例如 `anthropic`）。
- `refreshInterval` 的单位是秒；设为 `0` 可禁用缓存。
- `defaultContextWindow`（默认：`32000`）和 `defaultMaxTokens`（默认：`4096`）用于发现到的模型（如果你知道模型限制，可以覆盖这些值）。
- 对于显式的 `models.providers["amazon-bedrock"]` 条目，OpenClaw 仍然可以从诸如 `AWS_BEARER_TOKEN_BEDROCK` 之类的 AWS 环境变量标记中提前解析 Bedrock 环境变量标记认证，而无需强制加载完整运行时认证。实际的模型调用认证路径仍然使用 AWS SDK 默认链。
## 新手引导
1. 确保 AWS 凭证在**网关主机**上可用：
```bash
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"
# 可选：
export AWS_SESSION_TOKEN="..."
export AWS_PROFILE="your-profile"
# 可选（Bedrock API 密钥 / bearer token）：
export AWS_BEARER_TOKEN_BEDROCK="..."
```
2. 在你的配置中添加一个 Bedrock 提供商和模型（不需要 `apiKey`）：
```json5
{
models: {
providers: {
"amazon-bedrock": {
baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
api: "bedrock-converse-stream",
auth: "aws-sdk",
models: [
{
id: "us.anthropic.claude-opus-4-6-v1:0",
name: "Claude Opus 4.6（Bedrock）",
reasoning: true,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 200000,
maxTokens: 8192,
},
],
},
},
},
agents: {
defaults: {
model: { primary: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0" },
},
},
}
```
## EC2 实例角色
当在附加了 IAM 角色的 EC2 实例上运行 OpenClaw 时，AWS SDK 可以使用实例元数据服务（IMDS）进行认证。对于 Bedrock 模型发现，除非你显式设置
`plugins.entries.amazon-bedrock.config.discovery.enabled: true`，否则 OpenClaw 仅会根据 AWS 环境变量标记自动启用隐式提供商。
适用于基于 IMDS 的主机的推荐设置：
- 将 `plugins.entries.amazon-bedrock.config.discovery.enabled` 设为 `true`。
- 设置 `plugins.entries.amazon-bedrock.config.discovery.region`（或导出 `AWS_REGION`）。
- 你**不**需要伪造的 API 密钥。
- 只有在你明确希望为自动模式或状态界面提供环境变量标记时，才需要 `AWS_PROFILE=default`。
```bash
# 推荐：显式启用发现并设置区域
openclaw config set plugins.entries.amazon-bedrock.config.discovery.enabled true
openclaw config set plugins.entries.amazon-bedrock.config.discovery.region us-east-1
# 可选：如果你希望在不显式启用的情况下使用自动模式，可添加环境变量标记
export AWS_PROFILE=default
export AWS_REGION=us-east-1
```
EC2 实例角色所需的 **IAM 权限**：
- `bedrock:InvokeModel`
- `bedrock:InvokeModelWithResponseStream`
- `bedrock:ListFoundationModels`（用于自动发现）
- `bedrock:ListInferenceProfiles`（用于推理配置文件发现）
或者附加托管策略 `AmazonBedrockFullAccess`。
</Accordion>
</AccordionGroup>
## 快速开始（AWS 路径）
本演练将创建一个 IAM 角色、附加 Bedrock 权限、关联实例配置文件，并在 EC2 主机上启用 OpenClaw 发现。
```bash
# 1. 创建 IAM 角色和实例配置文件
# 1. Create IAM role and instance profile
aws iam create-role --role-name EC2-Bedrock-Access \
--assume-role-policy-document '{
"Version": "2012-10-17",
@ -168,93 +213,123 @@ aws iam add-role-to-instance-profile \
--instance-profile-name EC2-Bedrock-Access \
--role-name EC2-Bedrock-Access
# 2. 将其附加到你的 EC2 实例
# 2. Attach to your EC2 instance
aws ec2 associate-iam-instance-profile \
--instance-id i-xxxxx \
--iam-instance-profile Name=EC2-Bedrock-Access
# 3. 在 EC2 实例上显式启用发现
# 3. On the EC2 instance, enable discovery explicitly
openclaw config set plugins.entries.amazon-bedrock.config.discovery.enabled true
openclaw config set plugins.entries.amazon-bedrock.config.discovery.region us-east-1
# 4. 可选：如果你希望在不显式启用的情况下使用自动模式，可添加环境变量标记
# 4. Optional: add an env marker if you want auto mode without explicit enable
echo 'export AWS_PROFILE=default' >> ~/.bashrc
echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
source ~/.bashrc
# 5. 验证模型已被发现
# 5. Verify models are discovered
openclaw models list
```
## 推理配置文件
## 高级配置
OpenClaw 会在发现基础模型的同时发现**区域性和全局推理配置文件**。当某个配置文件映射到已知基础模型时，该配置文件会继承该模型的能力（上下文窗口、最大令牌数、推理、视觉），并自动注入正确的 Bedrock 请求区域。这意味着跨区域 Claude 配置文件无需手动覆盖提供商设置即可工作。
<AccordionGroup>
<Accordion title="推理配置文件">
OpenClaw 会同时发现 **区域性和全局推理配置文件** 以及基础模型。当某个配置文件映射到已知的基础模型时，该配置文件会继承该模型的能力（上下文窗口、最大 token 数、推理、视觉），并且会自动注入正确的 Bedrock 请求区域。这意味着跨区域 Claude 配置文件无需手动覆盖 provider 即可工作。
推理配置文件 ID 看起来像 `us.anthropic.claude-opus-4-6-v1:0`（区域性）或 `anthropic.claude-opus-4-6-v1:0`（全局）。如果其后端模型已经出现在发现结果中，该配置文件会继承其完整能力集；否则将应用安全默认值。
推理配置文件 ID 的格式可能是 `us.anthropic.claude-opus-4-6-v1:0`（区域性）或 `anthropic.claude-opus-4-6-v1:0`（全局）。如果其底层模型已出现在发现结果中，该配置文件会继承其完整能力集；否则会应用安全默认值。
不需要额外配置。只要发现已启用，且 IAM 主体拥有 `bedrock:ListInferenceProfiles` 权限，配置文件就会与基础模型一起显示在 `openclaw models list` 中。
不需要额外配置。只要发现已启用，并且 IAM 主体具有 `bedrock:ListInferenceProfiles` 权限，配置文件就会与基础模型一起出现在 `openclaw models list` 中。
## 说明
</Accordion>
- Bedrock 要求在你的 AWS 账户 / 区域中启用**模型访问**。
- 自动发现需要 `bedrock:ListFoundationModels` 和
`bedrock:ListInferenceProfiles` 权限。
- 如果你依赖自动模式，请在网关主机上设置一个受支持的 AWS 认证环境变量标记。如果你更倾向于使用无环境变量标记的 IMDS / 共享配置认证，请设置
`plugins.entries.amazon-bedrock.config.discovery.enabled: true`。
- OpenClaw 按以下顺序显示凭证来源：`AWS_BEARER_TOKEN_BEDROCK`，
然后是 `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`，接着是 `AWS_PROFILE`，最后是默认 AWS SDK 链。
- 推理支持取决于具体模型；请查看 Bedrock 模型卡以了解当前能力。
- 如果你更喜欢托管密钥流程，也可以在 Bedrock 前面放置一个兼容 OpenAI 的代理，并将其配置为 OpenAI 提供商。
<Accordion title="Guardrails">
你可以通过向 `amazon-bedrock` 插件配置添加 `guardrail` 对象，将 [Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) 应用于所有 Bedrock 模型调用。Guardrails 可让你强制执行内容过滤、主题拒绝、词语过滤、敏感信息过滤和上下文依据检查。
## Guardrails
你可以通过在 `amazon-bedrock` 插件配置中添加 `guardrail` 对象，将 [Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) 应用于所有 Bedrock 模型调用。Guardrails 允许你强制执行内容过滤、主题拒绝、词语过滤、敏感信息过滤和上下文基础校验。
```json5
{
plugins: {
entries: {
"amazon-bedrock": {
config: {
guardrail: {
guardrailIdentifier: "abc123", // guardrail ID 或完整 ARN
guardrailVersion: "1", // 版本号或 "DRAFT"
streamProcessingMode: "sync", // 可选："sync" 或 "async"
trace: "enabled", // 可选："enabled"、"disabled" 或 "enabled_full"
```json5
{
plugins: {
entries: {
"amazon-bedrock": {
config: {
guardrail: {
guardrailIdentifier: "abc123", // guardrail ID or full ARN
guardrailVersion: "1", // version number or "DRAFT"
streamProcessingMode: "sync", // optional: "sync" or "async"
trace: "enabled", // optional: "enabled", "disabled", or "enabled_full"
},
},
},
},
},
},
},
}
```
}
```
- `guardrailIdentifier`（必需）接受 guardrail ID（例如 `abc123`）或完整 ARN（例如 `arn:aws:bedrock:us-east-1:123456789012:guardrail/abc123`）。
- `guardrailVersion`（必需）指定要使用的已发布版本，或使用 `"DRAFT"` 表示工作草稿。
- `streamProcessingMode`（可选）控制在流式传输期间，guardrail 评估是同步运行（`"sync"`）还是异步运行（`"async"`）。如果省略，Bedrock 会使用其默认行为。
- `trace`（可选）在 API 响应中启用 guardrail 跟踪输出。调试时设为 `"enabled"` 或 `"enabled_full"`；在生产环境中请省略或设为 `"disabled"`。
| 选项 | 必填 | 描述 |
| ------ | -------- | ----------- |
| `guardrailIdentifier` | 是 | Guardrail ID（例如 `abc123`）或完整 ARN（例如 `arn:aws:bedrock:us-east-1:123456789012:guardrail/abc123`）。 |
| `guardrailVersion` | 是 | 已发布的版本号，或工作草稿的 `"DRAFT"`。 |
| `streamProcessingMode` | 否 | 流式传输期间 guardrail 评估的 `"sync"` 或 `"async"`。如果省略，Bedrock 将使用其默认值。 |
| `trace` | 否 | 用于调试时设为 `"enabled"` 或 `"enabled_full"`；在生产环境中请省略或设为 `"disabled"`。 |
Gateway 网关使用的 IAM 主体除标准调用权限外，还必须具有 `bedrock:ApplyGuardrail` 权限。
<Warning>
Gateway 网关使用的 IAM 主体除标准调用权限外，还必须具有 `bedrock:ApplyGuardrail` 权限。
</Warning>
## 用于内存搜索的 Embeddings
</Accordion>
Bedrock 也可以作为
[内存搜索](/zh-CN/concepts/memory-search) 的嵌入提供商。这与推理提供商分开配置 —— 将 `agents.defaults.memorySearch.provider` 设为 `"bedrock"`：
<Accordion title="用于记忆搜索的 Embeddings">
Bedrock 也可以作为 [记忆搜索](/zh-CN/concepts/memory-search) 的 embedding provider。该配置与推理 provider 分开设置——请将 `agents.defaults.memorySearch.provider` 设为 `"bedrock"`：
```json5
{
agents: {
defaults: {
memorySearch: {
provider: "bedrock",
model: "amazon.titan-embed-text-v2:0", // 默认
```json5
{
agents: {
defaults: {
memorySearch: {
provider: "bedrock",
model: "amazon.titan-embed-text-v2:0", // default
},
},
},
},
},
}
```
}
```
Bedrock embeddings 与推理使用相同的 AWS SDK 凭证链（实例角色、SSO、访问密钥、共享配置和 Web 身份）。不需要 API 密钥。当 `provider` 为 `"auto"` 时，如果该凭证链成功解析，Bedrock 会被自动检测到。
Bedrock embeddings 与推理使用相同的 AWS SDK 凭证链（实例角色、SSO、访问密钥、共享配置和 web identity）。不需要 API key。当 `provider` 为 `"auto"` 时，如果该凭证链成功解析，Bedrock 会被自动检测为可用。
支持的嵌入模型包括 Amazon Titan Embed（v1、v2）、Amazon Nova Embed、Cohere Embed（v3、v4）和 TwelveLabs Marengo。完整模型列表和维度选项，请参阅
[内存配置参考 — Bedrock](/zh-CN/reference/memory-config#bedrock-embedding-config)。
支持的 embedding 模型包括 Amazon Titan Embed（v1、v2）、Amazon Nova
Embed、Cohere Embed（v3、v4）以及 TwelveLabs Marengo。完整模型列表和维度选项请参阅
[记忆配置参考 -- Bedrock](/zh-CN/reference/memory-config#bedrock-embedding-config)。
</Accordion>
<Accordion title="说明与注意事项">
- Bedrock 要求你在 AWS 账户/区域中启用**模型访问**。
- 自动发现需要 `bedrock:ListFoundationModels` 和
`bedrock:ListInferenceProfiles` 权限。
- 如果你依赖自动模式，请在 Gateway 网关主机上设置受支持的 AWS 身份验证环境变量标记之一。如果你更倾向于使用无环境变量标记的 IMDS / 共享配置身份验证，请设置
`plugins.entries.amazon-bedrock.config.discovery.enabled: true`。
- OpenClaw 会按以下顺序显示凭证来源：`AWS_BEARER_TOKEN_BEDROCK`，
然后是 `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`，接着是 `AWS_PROFILE`，最后是
默认 AWS SDK 链。
- 推理支持取决于具体模型；请查看 Bedrock 模型卡以了解当前能力。
- 如果你更倾向于托管密钥流程，也可以在 Bedrock 前面放置一个兼容 OpenAI 的
代理，并将其配置为 OpenAI provider。
</Accordion>
</AccordionGroup>
## 相关内容
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
</Card>
<Card title="记忆搜索" href="/zh-CN/concepts/memory-search" icon="magnifying-glass">
用于记忆搜索配置的 Bedrock embeddings。
</Card>
<Card title="记忆配置参考" href="/zh-CN/reference/memory-config#bedrock-embedding-config" icon="database">
完整的 Bedrock embedding 模型列表和维度选项。
</Card>
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
常规故障排除和常见问题。
</Card>
</CardGroup>

261
docs/zh-CN/providers/google.md
View File

@ -2,87 +2,128 @@
read_when:
- 你想在 OpenClaw 中使用 Google Gemini 模型
- 你需要 API 密钥或 OAuth 认证流程
summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、Web 搜索）
summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、网络搜索）
title: Google（Gemini）
x-i18n:
generated_at: "2026-04-08T06:28:43Z"
generated_at: "2026-04-12T10:03:27Z"
model: gpt-5.4
provider: openai
source_hash: fad2ff68987301bd86145fa6e10de8c7b38d5bd5dbcd13db9c883f7f5b9a4e01
source_hash: 64b848add89061b208a5d6b19d206c433cace5216a0ca4b63d56496aecbde452
source_path: providers/google.md
workflow: 15
---
# Google（Gemini）
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及通过 Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）和 Web 搜索。
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及通过 Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）和网络搜索。
- 提供商：`google`
- 认证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
- API：Google Gemini API
- 替代提供商：`google-gemini-cli`（OAuth）
## 快速开始
## 入门指南
1. 设置 API 密钥：
选择你偏好的认证方式，并按照设置步骤操作。
```bash
openclaw onboard --auth-choice gemini-api-key
```
<Tabs>
<Tab title="API 密钥">
**最适合：** 通过 Google AI Studio 进行标准的 Gemini API 访问。
2. 设置默认模型：
<Steps>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice gemini-api-key
```
```json5
{
agents: {
defaults: {
model: { primary: "google/gemini-3.1-pro-preview" },
},
},
}
```
或直接传入密钥：
## 非交互式示例
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice gemini-api-key \
--gemini-api-key "$GEMINI_API_KEY"
```
</Step>
<Step title="设置默认模型">
```json5
{
agents: {
defaults: {
model: { primary: "google/gemini-3.1-pro-preview" },
},
},
}
```
</Step>
<Step title="验证模型可用">
```bash
openclaw models list --provider google
```
</Step>
</Steps>
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice gemini-api-key \
--gemini-api-key "$GEMINI_API_KEY"
```
<Tip>
环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可接受。使用你已经配置好的那个即可。
</Tip>
## OAuth（Gemini CLI）
</Tab>
另一个提供商 `google-gemini-cli` 使用 PKCE OAuth，而不是 API 密钥。这个集成并非官方集成；一些用户反馈会遇到账户限制。使用风险由你自行承担。
<Tab title="Gemini CLI（OAuth）">
**最适合：** 通过 PKCE OAuth 复用已有的 Gemini CLI 登录，而不是单独使用 API 密钥。
- 默认模型：`google-gemini-cli/gemini-3-flash-preview`
- 别名：`gemini-cli`
- 安装前提：本地可用的 Gemini CLI，命令名为 `gemini`
- Homebrew：`brew install gemini-cli`
- npm：`npm install -g @google/gemini-cli`
- 登录：
<Warning>
`google-gemini-cli` 提供商是非官方集成。一些用户报告称，以这种方式使用 OAuth 时会遇到账户限制。请自行承担使用风险。
</Warning>
```bash
openclaw models auth login --provider google-gemini-cli --set-default
```
<Steps>
<Step title="安装 Gemini CLI">
本地 `gemini` 命令必须可在 `PATH` 上使用。
环境变量：
```bash
# Homebrew
brew install gemini-cli
- `OPENCLAW_GEMINI_OAUTH_CLIENT_ID`
- `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET`
# or npm
npm install -g @google/gemini-cli
```
（或使用 `GEMINI_CLI_*` 变体。）
OpenClaw 同时支持 Homebrew 安装和全局 npm 安装，包括常见的 Windows/npm 布局。
</Step>
<Step title="通过 OAuth 登录">
```bash
openclaw models auth login --provider google-gemini-cli --set-default
```
</Step>
<Step title="验证模型可用">
```bash
openclaw models list --provider google-gemini-cli
```
</Step>
</Steps>
如果在登录后 Gemini CLI OAuth 请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`，然后重试。
- 默认模型：`google-gemini-cli/gemini-3-flash-preview`
- 别名：`gemini-cli`
如果在浏览器流程开始前登录失败，请确认本地 `gemini` 命令已安装并且在 `PATH` 中。OpenClaw 同时支持 Homebrew 安装和全局 npm 安装，包括常见的 Windows/npm 布局。
**环境变量：**
Gemini CLI JSON 使用说明：
- `OPENCLAW_GEMINI_OAUTH_CLIENT_ID`
- `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET`
- 回复文本来自 CLI JSON 的 `response` 字段。
- 当 CLI 将 `usage` 留空时，用量会回退到 `stats`。
- `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
- 如果 `stats.input` 缺失，OpenClaw 会根据 `stats.input_tokens - stats.cached` 推导输入 token 数。
（或使用 `GEMINI_CLI_*` 变体。）
<Note>
如果 Gemini CLI OAuth 请求在登录后失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`，然后重试。
</Note>
<Note>
如果在浏览器流程开始前登录就失败，请确认本地 `gemini` 命令已安装并且位于 `PATH` 上。
</Note>
仅支持 OAuth 的 `google-gemini-cli` 提供商是一个独立的文本推理接口。图像生成、媒体理解和 Gemini Grounding 仍然使用 `google` 提供商 id。
</Tab>
</Tabs>
## 功能
@ -92,40 +133,15 @@ Gemini CLI JSON 使用说明：
| 图像生成 | 是 |
| 音乐生成 | 是 |
| 图像理解 | 是 |
| 音频转写 | 是 |
| 音频转录 | 是 |
| 视频理解 | 是 |
| Web 搜索（Grounding） | 是 |
| 网络搜索（Grounding） | 是 |
| 思考/推理 | 是（Gemini 3.1+） |
| Gemma 4 模型 | 是 |
Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会将 `thinkingBudget` 重写为 Gemma 4 支持的 Google `thinkingLevel`。将 thinking 设置为 `off` 时，会保持禁用 thinking，而不是映射为 `MINIMAL`。
## 直接复用 Gemini 缓存
对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw 现在会将已配置的 `cachedContent` 句柄传递给 Gemini 请求。
- 可以使用 `cachedContent` 或旧版 `cached_content` 配置按模型或全局参数
- 如果两者同时存在，优先使用 `cachedContent`
- 示例值：`cachedContents/prebuilt-context`
- Gemini 缓存命中用量会根据上游 `cachedContentTokenCount` 规范化为 OpenClaw `cacheRead`
示例：
```json5
{
agents: {
defaults: {
models: {
"google/gemini-2.5-pro": {
params: {
cachedContent: "cachedContents/prebuilt-context",
},
},
},
},
},
}
```
<Tip>
Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会将 `thinkingBudget` 重写为 Google 支持的 `thinkingLevel`，以适配 Gemma 4。将 thinking 设置为 `off` 会保持禁用思考，而不是映射为 `MINIMAL`。
</Tip>
## 图像生成
@ -136,9 +152,7 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会
- 编辑模式：已启用，最多支持 5 张输入图像
- 几何控制：`size`、`aspectRatio` 和 `resolution`
仅支持 OAuth 的 `google-gemini-cli` 提供商是一个独立的文本推理接口。图像生成、媒体理解和 Gemini Grounding 仍然使用 `google` 提供商 id。
要将 Google 设为默认图像提供商：
要将 Google 用作默认图像提供商：
```json5
{
@ -152,18 +166,20 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会
}
```
有关共享工具参数、提供商选择和故障切换行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。
</Note>
## 视频生成
内置的 `google` 插件还通过共享的 `video_generate` 工具注册了视频生成功能。
内置的 `google` 插件还会通过共享的 `video_generate` 工具注册视频生成功能。
- 默认视频模型：`google/veo-3.1-fast-generate-preview`
- 模式：文生视频、图生视频，以及单视频参考流程
- 支持 `aspectRatio`、`resolution` 和 `audio`
- 当前时长限制：**4 到 8 秒**
要将 Google 设为默认视频提供商：
要将 Google 用作默认视频提供商：
```json5
{
@ -177,20 +193,22 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会
}
```
有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。
</Note>
## 音乐生成
内置的 `google` 插件还通过共享的 `music_generate` 工具注册了音乐生成功能。
内置的 `google` 插件还会通过共享的 `music_generate` 工具注册音乐生成功能。
- 默认音乐模型：`google/lyria-3-clip-preview`
- 也支持 `google/lyria-3-pro-preview`
- 提示词控制：`lyrics` 和 `instrumental`
- 输出格式：默认 `mp3`，并且 `google/lyria-3-pro-preview` 还支持 `wav`
- 输出格式：默认 `mp3`，在 `google/lyria-3-pro-preview` 上还支持 `wav`
- 参考输入：最多 10 张图像
- 基于会话的运行会通过共享的任务/状态流程分离处理，包括 `action: "status"`
- 基于会话的运行会通过共享的任务/状态流程分离执行，包括 `action: "status"`
要将 Google 设为默认音乐提供商：
要将 Google 用作默认音乐提供商：
```json5
{
@ -204,8 +222,67 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会
}
```
有关共享工具参数、提供商选择和故障切换行为，请参阅 [音乐生成](/zh-CN/tools/music-generation)。
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [Music Generation](/zh-CN/tools/music-generation)。
</Note>
## 环境说明
## 高级配置
如果 Gateway 网关以守护进程方式运行（launchd/systemd），请确保该进程可以访问 `GEMINI_API_KEY`（例如在 `~/.openclaw/.env` 中，或通过 `env.shellEnv`）。
<AccordionGroup>
<Accordion title="直接复用 Gemini 缓存">
对于直接的 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw 会将已配置的 `cachedContent` 句柄透传给 Gemini 请求。
- 可使用 `cachedContent` 或旧版 `cached_content` 配置按模型或全局参数
- 如果两者同时存在，`cachedContent` 优先
- 示例值：`cachedContents/prebuilt-context`
- Gemini 的缓存命中用量会从上游的 `cachedContentTokenCount` 规范化为 OpenClaw 的 `cacheRead`
```json5
{
agents: {
defaults: {
models: {
"google/gemini-2.5-pro": {
params: {
cachedContent: "cachedContents/prebuilt-context",
},
},
},
},
},
}
```
</Accordion>
<Accordion title="Gemini CLI JSON 使用说明">
使用 `google-gemini-cli` OAuth 提供商时，OpenClaw 会按如下方式规范化 CLI JSON 输出：
- 回复文本来自 CLI JSON 的 `response` 字段。
- 当 CLI 将 `usage` 留空时，用量会回退到 `stats`。
- `stats.cached` 会被规范化为 OpenClaw 的 `cacheRead`。
- 如果 `stats.input` 缺失，OpenClaw 会根据 `stats.input_tokens - stats.cached` 推导输入 token 数。
</Accordion>
<Accordion title="环境和守护进程设置">
如果 Gateway 网关以守护进程形式运行（launchd/systemd），请确保 `GEMINI_API_KEY` 对该进程可用（例如在 `~/.openclaw/.env` 中，或通过 `env.shellEnv`）。
</Accordion>
</AccordionGroup>
## 相关内容
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
共享图像工具参数和提供商选择。
</Card>
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
</Card>
<Card title="音乐生成" href="/zh-CN/tools/music-generation" icon="music">
共享音乐工具参数和提供商选择。
</Card>
</CardGroup>

557
docs/zh-CN/providers/minimax.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 你想在 OpenClaw 中使用 MiniMax 模型
- 你需要 MiniMax 设置指南
- 你需要 MiniMax 设置指导
summary: 在 OpenClaw 中使用 MiniMax 模型
title: MiniMax
x-i18n:
generated_at: "2026-04-06T00:52:43Z"
generated_at: "2026-04-12T10:03:26Z"
model: gpt-5.4
provider: openai
source_hash: 9ca35c43cdde53f6f09d9e12d48ce09e4c099cf8cbe1407ac6dbb45b1422507e
source_hash: ee9c89faf57384feb66cda30934000e5746996f24b59122db309318f42c22389
source_path: providers/minimax.md
workflow: 15
---
@ -19,31 +19,212 @@ OpenClaw 的 MiniMax 提供商默认使用 **MiniMax M2.7**。
MiniMax 还提供：
- 通过 T2A v2 内置的语音合成
- 通过 `MiniMax-VL-01` 内置的图像理解
- 通过 `music-2.5+` 内置的音乐生成
- 通过 MiniMax Coding Plan 搜索 API 内置的 `web_search`
- 通过 T2A v2 内置语音合成
- 通过 `MiniMax-VL-01` 内置图像理解
- 通过 `music-2.5+` 内置音乐生成
- 通过 MiniMax Coding Plan 搜索 API 内置 `web_search`
提供商拆分如下：
提供商拆分：
- `minimax`：基于 API 密钥的文本提供商，另加内置的图像生成、图像理解、语音和网页搜索
- `minimax-portal`：基于 OAuth 的文本提供商，另加内置的图像生成和图像理解
| Provider ID | 鉴权方式 | 能力 |
| ---------------- | -------- | --------------------------------------------------------------- |
| `minimax` | API 密钥 | 文本、图像生成、图像理解、语音、网页搜索 |
| `minimax-portal` | OAuth | 文本、图像生成、图像理解 |
## 模型阵容
- `MiniMax-M2.7`：默认托管推理模型。
- `MiniMax-M2.7-highspeed`：更快的 M2.7 推理层级。
- `image-01`：图像生成模型（生成和图生图编辑）。
| 模型 | 类型 | 说明 |
| ------------------------ | ---------------- | ---------------------------------------- |
| `MiniMax-M2.7` | 聊天（推理） | 默认托管推理模型 |
| `MiniMax-M2.7-highspeed` | 聊天（推理） | 更快的 M2.7 推理层级 |
| `MiniMax-VL-01` | 视觉 | 图像理解模型 |
| `image-01` | 图像生成 | 文生图和图像到图像编辑 |
| `music-2.5+` | 音乐生成 | 默认音乐模型 |
| `music-2.5` | 音乐生成 | 上一代音乐生成层级 |
| `music-2.0` | 音乐生成 | 旧版音乐生成层级 |
| `MiniMax-Hailuo-2.3` | 视频生成 | 文生视频和图像参考流程 |
## 图像生成
## 入门指南
MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持：
选择你偏好的鉴权方式，并按照设置步骤进行操作。
- 具有宽高比控制的**文生图生成**。
- 具有宽高比控制的**图生图编辑**（主体参考）。
- 每次请求最多生成 **9 张输出图像**。
- 每次编辑请求最多支持 **1 张参考图像**。
- 支持的宽高比：`1:1`、`16:9`、`4:3`、`3:2`、`2:3`、`3:4`、`9:16`、`21:9`。
<Tabs>
<Tab title="OAuth (Coding Plan)">
**最适合：** 通过 OAuth 快速设置 MiniMax Coding Plan，无需 API 密钥。
<Tabs>
<Tab title="International">
<Steps>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice minimax-global-oauth
```
这会对 `api.minimax.io` 进行身份验证。
</Step>
<Step title="验证模型可用">
```bash
openclaw models list --provider minimax-portal
```
</Step>
</Steps>
</Tab>
<Tab title="China">
<Steps>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice minimax-cn-oauth
```
这会对 `api.minimaxi.com` 进行身份验证。
</Step>
<Step title="验证模型可用">
```bash
openclaw models list --provider minimax-portal
```
</Step>
</Steps>
</Tab>
</Tabs>
<Note>
OAuth 设置使用 `minimax-portal` 提供商 id。模型引用采用 `minimax-portal/MiniMax-M2.7` 这种形式。
</Note>
<Tip>
MiniMax Coding Plan 推荐链接（九折优惠）：[MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
</Tip>
</Tab>
<Tab title="API key">
**最适合：** 使用兼容 Anthropic API 的托管 MiniMax。
<Tabs>
<Tab title="International">
<Steps>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice minimax-global-api
```
这会将 `api.minimax.io` 配置为基础 URL。
</Step>
<Step title="验证模型可用">
```bash
openclaw models list --provider minimax
```
</Step>
</Steps>
</Tab>
<Tab title="China">
<Steps>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice minimax-cn-api
```
这会将 `api.minimaxi.com` 配置为基础 URL。
</Step>
<Step title="验证模型可用">
```bash
openclaw models list --provider minimax
```
</Step>
</Steps>
</Tab>
</Tabs>
### 配置示例
```json5
{
env: { MINIMAX_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "minimax/MiniMax-M2.7" } } },
models: {
mode: "merge",
providers: {
minimax: {
baseUrl: "https://api.minimax.io/anthropic",
apiKey: "${MINIMAX_API_KEY}",
api: "anthropic-messages",
models: [
{
id: "MiniMax-M2.7",
name: "MiniMax M2.7",
reasoning: true,
input: ["text", "image"],
cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
contextWindow: 204800,
maxTokens: 131072,
},
{
id: "MiniMax-M2.7-highspeed",
name: "MiniMax M2.7 Highspeed",
reasoning: true,
input: ["text", "image"],
cost: { input: 0.6, output: 2.4, cacheRead: 0.06, cacheWrite: 0.375 },
contextWindow: 204800,
maxTokens: 131072,
},
],
},
},
},
}
```
<Warning>
在兼容 Anthropic 的流式传输路径上，除非你显式自行设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。MiniMax 的流式传输端点会以 OpenAI 风格的 delta 分块形式输出 `reasoning_content`，而不是原生 Anthropic thinking block；如果在未明确配置的情况下保持启用，内部推理内容可能会泄露到可见输出中。
</Warning>
<Note>
API 密钥设置使用 `minimax` 提供商 id。模型引用采用 `minimax/MiniMax-M2.7` 这种形式。
</Note>
</Tab>
</Tabs>
## 通过 `openclaw configure` 配置
使用交互式配置向导设置 MiniMax，无需编辑 JSON：
<Steps>
<Step title="启动向导">
```bash
openclaw configure
```
</Step>
<Step title="选择模型/鉴权">
在菜单中选择 **模型/鉴权**。
</Step>
<Step title="选择一个 MiniMax 鉴权选项">
从可用的 MiniMax 选项中选择一个：
| 鉴权选项 | 说明 |
| --- | --- |
| `minimax-global-oauth` | 国际版 OAuth（Coding Plan） |
| `minimax-cn-oauth` | 中国版 OAuth（Coding Plan） |
| `minimax-global-api` | 国际版 API 密钥 |
| `minimax-cn-api` | 中国版 API 密钥 |
</Step>
<Step title="选择你的默认模型">
在提示时选择你的默认模型。
</Step>
</Steps>
## 能力
### 图像生成
MiniMax 插件会为 `image_generate` 工具注册 `image-01` 模型。它支持：
- **文生图生成**，支持宽高比控制
- **图像到图像编辑**（主体参考），支持宽高比控制
- 每次请求最多输出 **9 张图像**
- 每次编辑请求最多支持 **1 张参考图**
- 支持的宽高比：`1:1`、`16:9`、`4:3`、`3:2`、`2:3`、`3:4`、`9:16`、`21:9`
要将 MiniMax 用于图像生成，请将其设置为图像生成提供商：
@ -57,32 +238,31 @@ MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持
}
```
该插件对文本模型使用相同的 `MINIMAX_API_KEY` 或 OAuth 认证。如果 MiniMax 已经设置完成，则无需额外配置。
该插件对文本模型使用相同的 `MINIMAX_API_KEY` 或 OAuth 鉴权。如果 MiniMax 已经设置完成，则无需额外配置。
`minimax` 和 `minimax-portal` 都会使用相同的
`image-01` 模型注册 `image_generate`。基于 API 密钥的设置使用 `MINIMAX_API_KEY`；基于 OAuth 的设置则可以改用
内置的 `minimax-portal` 认证路径。
`image-01` 模型注册 `image_generate`。API 密钥设置使用 `MINIMAX_API_KEY`；OAuth 设置则可以改用内置的 `minimax-portal` 鉴权路径。
当新手引导或基于 API 密钥的设置写入显式的 `models.providers.minimax`
条目时，OpenClaw 会具体化 `MiniMax-M2.7` 和
`MiniMax-M2.7-highspeed`，并设置 `input: ["text", "image"]`。
当新手引导或 API 密钥设置写入显式的 `models.providers.minimax`
条目时，OpenClaw 会实例化 `MiniMax-M2.7` 和
`MiniMax-M2.7-highspeed`，并带有 `input: ["text", "image"]`。
内置的 MiniMax 文本目录本身会保持为仅文本元数据，
直到存在该显式提供商配置。图像理解则通过插件自有的 `MiniMax-VL-01` 媒体提供商单独暴露。
内置的 MiniMax 文本模型目录本身在存在该显式提供商配置之前，仍保持为仅文本的元数据。图像理解则通过插件自有的 `MiniMax-VL-01` 媒体提供商单独公开。
参见 [图像生成](/zh-CN/tools/image-generation)，了解共享工具
参数、提供商选择和故障切换行为。
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。
</Note>
## 音乐生成
### 音乐生成
内置的 `minimax` 插件还通过共享的
`music_generate` 工具注册了音乐生成功能。
内置的 `minimax` 插件还会通过共享的
`music_generate` 工具注册音乐生成功能。
- 默认音乐模型：`minimax/music-2.5+`
- 也支持 `minimax/music-2.5` 和 `minimax/music-2.0`
- 提示词控制：`lyrics`、`instrumental`、`durationSeconds`
- 输出格式：`mp3`
- 基于会话的运行会通过共享的任务/状态流程分离执行，包括 `action: "status"`
- 基于会话的运行会通过共享任务/状态流程分离执行，包括 `action: "status"`
要将 MiniMax 用作默认音乐提供商：
@ -98,13 +278,14 @@ MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持
}
```
参见 [音乐生成](/zh-CN/tools/music-generation)，了解共享工具
参数、提供商选择和故障切换行为。
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [音乐生成](/zh-CN/tools/music-generation)。
</Note>
## 视频生成
### 视频生成
内置的 `minimax` 插件还通过共享的
`video_generate` 工具注册了视频生成功能。
内置的 `minimax` 插件还会通过共享的
`video_generate` 工具注册视频生成功能。
- 默认视频模型：`minimax/MiniMax-Hailuo-2.3`
- 模式：文生视频和单图参考流程
@ -124,224 +305,164 @@ MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持
}
```
参见 [视频生成](/zh-CN/tools/video-generation)，了解共享工具
参数、提供商选择和故障切换行为。
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
</Note>
## 图像理解
### 图像理解
MiniMax 插件将图像理解与文本
目录分开注册：
MiniMax 插件将图像理解与文本模型目录分开注册：
- `minimax`：默认图像模型为 `MiniMax-VL-01`
- `minimax-portal`：默认图像模型为 `MiniMax-VL-01`
| Provider ID | 默认图像模型 |
| ---------------- | ----------------- |
| `minimax` | `MiniMax-VL-01` |
| `minimax-portal` | `MiniMax-VL-01` |
这就是为什么自动媒体路由即使在
内置文本提供商目录仍显示为仅文本的 M2.7 聊天引用时，
也可以使用 MiniMax 图像理解。
这就是为什么自动媒体路由即使在内置文本提供商目录仍显示为仅文本的 M2.7 聊天模型引用时，也可以使用 MiniMax 图像理解。
## 网页搜索
### 网页搜索
MiniMax 插件还通过 MiniMax Coding Plan
搜索 API 注册了 `web_search`。
MiniMax 插件还会通过 MiniMax Coding Plan
搜索 API 注册 `web_search`。
- 提供商 id：`minimax`
- 结构化结果：标题、URL、摘要、相关查询
- 首选环境变量：`MINIMAX_CODE_PLAN_KEY`
- 可接受的环境变量别名：`MINIMAX_CODING_API_KEY`
- 兼容性回退：当 `MINIMAX_API_KEY` 已指向 coding-plan 令牌时可使用它
- 区域复用：`plugins.entries.minimax.config.webSearch.region`，然后是 `MINIMAX_API_HOST`，再然后是 MiniMax 提供商基础 URL
- 搜索始终保留在提供商 id `minimax`；OAuth 中国区/国际版设置仍可通过 `models.providers.minimax-portal.baseUrl` 间接引导区域
- 接受的环境变量别名：`MINIMAX_CODING_API_KEY`
- 兼容性回退：如果 `MINIMAX_API_KEY` 已经指向 coding-plan 令牌，也可使用
- 区域复用：`plugins.entries.minimax.config.webSearch.region`，然后是 `MINIMAX_API_HOST`，然后是 MiniMax 提供商基础 URL
- 搜索始终保留在提供商 id `minimax` 上；OAuth 中国版/国际版设置仍然可以通过 `models.providers.minimax-portal.baseUrl` 间接引导区域
配置位于 `plugins.entries.minimax.config.webSearch.*` 下。
参见 [MiniMax Search](/zh-CN/tools/minimax-search)。
## 选择一种设置方式
<Note>
有关完整的网页搜索配置和用法，请参阅 [MiniMax 搜索](/zh-CN/tools/minimax-search)。
</Note>
### MiniMax OAuth（Coding Plan） - 推荐
## 高级配置
**最适合：** 通过 OAuth 快速设置 MiniMax Coding Plan，无需 API 密钥。
<AccordionGroup>
<Accordion title="配置选项">
| 选项 | 说明 |
| --- | --- |
| `models.providers.minimax.baseUrl` | 优先使用 `https://api.minimax.io/anthropic`（兼容 Anthropic）；`https://api.minimax.io/v1` 可选，用于兼容 OpenAI 的负载 |
| `models.providers.minimax.api` | 优先使用 `anthropic-messages`；`openai-completions` 可选，用于兼容 OpenAI 的负载 |
| `models.providers.minimax.apiKey` | MiniMax API 密钥（`MINIMAX_API_KEY`） |
| `models.providers.minimax.models` | 定义 `id`、`name`、`reasoning`、`contextWindow`、`maxTokens`、`cost` |
| `agents.defaults.models` | 为你希望加入 allowlist 的模型设置别名 |
| `models.mode` | 如果你想在内置模型之外添加 MiniMax，请保持为 `merge` |
</Accordion>
使用明确的区域 OAuth 选项进行认证：
<Accordion title="thinking 默认值">
在 `api: "anthropic-messages"` 上，除非参数/配置中已经显式设置了 thinking，否则 OpenClaw 会注入 `thinking: { type: "disabled" }`。
```bash
openclaw onboard --auth-choice minimax-global-oauth
# or
openclaw onboard --auth-choice minimax-cn-oauth
```
这样可以防止 MiniMax 的流式传输端点以 OpenAI 风格的 delta 分块形式输出 `reasoning_content`，从而将内部推理泄露到可见输出中。
选项映射：
</Accordion>
- `minimax-global-oauth`：国际用户（`api.minimax.io`）
- `minimax-cn-oauth`：中国用户（`api.minimaxi.com`）
<Accordion title="快速模式">
`/fast on` 或 `params.fastMode: true` 会在兼容 Anthropic 的流式传输路径上，将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
</Accordion>
详情请参见 OpenClaw 仓库中的 MiniMax 插件包 README。
<Accordion title="故障切换示例">
**最适合：** 将你最强的最新一代模型保留为主模型，并在失败时切换到 MiniMax M2.7。下面的示例使用 Opus 作为具体的主模型；你也可以替换为自己偏好的最新一代主模型。
### MiniMax M2.7（API 密钥）
**最适合：** 使用与 Anthropic 兼容 API 的托管 MiniMax。
通过 CLI 配置：
- 交互式新手引导：
```bash
openclaw onboard --auth-choice minimax-global-api
# or
openclaw onboard --auth-choice minimax-cn-api
```
- `minimax-global-api`：国际用户（`api.minimax.io`）
- `minimax-cn-api`：中国用户（`api.minimaxi.com`）
```json5
{
env: { MINIMAX_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "minimax/MiniMax-M2.7" } } },
models: {
mode: "merge",
providers: {
minimax: {
baseUrl: "https://api.minimax.io/anthropic",
apiKey: "${MINIMAX_API_KEY}",
api: "anthropic-messages",
models: [
{
id: "MiniMax-M2.7",
name: "MiniMax M2.7",
reasoning: true,
input: ["text", "image"],
cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
contextWindow: 204800,
maxTokens: 131072,
```json5
{
env: { MINIMAX_API_KEY: "sk-..." },
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": { alias: "primary" },
"minimax/MiniMax-M2.7": { alias: "minimax" },
},
{
id: "MiniMax-M2.7-highspeed",
name: "MiniMax M2.7 Highspeed",
reasoning: true,
input: ["text", "image"],
cost: { input: 0.6, output: 2.4, cacheRead: 0.06, cacheWrite: 0.375 },
contextWindow: 204800,
maxTokens: 131072,
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["minimax/MiniMax-M2.7"],
},
],
},
},
},
},
}
```
}
```
在与 Anthropic 兼容的流式传输路径上，OpenClaw 现在默认会禁用 MiniMax 的
thinking，除非你显式自行设置了 `thinking`。MiniMax 的
流式端点会以 OpenAI 风格的 delta 分块形式发出 `reasoning_content`，
而不是原生的 Anthropic thinking 块，
如果默认启用，可能会将内部推理泄露到可见输出中。
</Accordion>
### 将 MiniMax M2.7 用作回退模型（示例）
**最适合：** 将你最强的最新一代模型保留为主模型，在失败时回退到 MiniMax M2.7。
下面的示例使用 Opus 作为具体主模型；你可以替换为自己偏好的最新一代主模型。
```json5
{
env: { MINIMAX_API_KEY: "sk-..." },
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": { alias: "primary" },
"minimax/MiniMax-M2.7": { alias: "minimax" },
},
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["minimax/MiniMax-M2.7"],
},
},
},
}
```
## 通过 `openclaw configure` 配置
使用交互式配置向导来设置 MiniMax，而无需编辑 JSON：
1. 运行 `openclaw configure`。
2. 选择 **Model/auth**。
3. 选择一个 **MiniMax** 认证选项。
4. 在提示时选择你的默认模型。
向导/CLI 中当前可用的 MiniMax 认证选项：
- `minimax-global-oauth`
- `minimax-cn-oauth`
- `minimax-global-api`
- `minimax-cn-api`
## 配置选项
- `models.providers.minimax.baseUrl`：优先使用 `https://api.minimax.io/anthropic`（与 Anthropic 兼容）；也可选用 `https://api.minimax.io/v1` 以使用与 OpenAI 兼容的负载。
- `models.providers.minimax.api`：优先使用 `anthropic-messages`；也可选用 `openai-completions` 以使用与 OpenAI 兼容的负载。
- `models.providers.minimax.apiKey`：MiniMax API 密钥（`MINIMAX_API_KEY`）。
- `models.providers.minimax.models`：定义 `id`、`name`、`reasoning`、`contextWindow`、`maxTokens`、`cost`。
- `agents.defaults.models`：为你想加入 allowlist 的模型设置别名。
- `models.mode`：如果你想在内置提供商之外添加 MiniMax，请保持为 `merge`。
<Accordion title="Coding Plan 使用详情">
- Coding Plan 用量 API：`https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains`（需要 coding plan 密钥）。
- OpenClaw 会将 MiniMax coding plan 用量标准化为与其他提供商相同的“% 剩余”显示。MiniMax 原始的 `usage_percent` / `usagePercent` 字段表示的是剩余额度，而不是已用额度，因此 OpenClaw 会将其反转处理。若存在按次数计数的字段，则优先使用这些字段。
- 当 API 返回 `model_remains` 时，OpenClaw 会优先选择聊天模型条目，并在需要时根据 `start_time` / `end_time` 推导窗口标签，同时在计划标签中包含所选模型名称，以便更容易区分不同的 coding-plan 窗口。
- 用量快照会将 `minimax`、`minimax-cn` 和 `minimax-portal` 视为同一个 MiniMax 配额层面，并优先使用已存储的 MiniMax OAuth，其次才回退到 Coding Plan 密钥环境变量。
</Accordion>
</AccordionGroup>
## 说明
- 模型引用遵循认证路径：
- 模型引用遵循鉴权路径：
- API 密钥设置：`minimax/<model>`
- OAuth 设置：`minimax-portal/<model>`
- 默认聊天模型：`MiniMax-M2.7`
- 备用聊天模型：`MiniMax-M2.7-highspeed`
- 在 `api: "anthropic-messages"` 上，OpenClaw 会注入
`thinking: { type: "disabled" }`，除非在
params/config 中已经显式设置了 thinking。
- `/fast on` 或 `params.fastMode: true` 会在与 Anthropic 兼容的流式路径上，
将 `MiniMax-M2.7` 重写为
`MiniMax-M2.7-highspeed`。
- 新手引导和直接 API 密钥设置会为
两个 M2.7 变体都写入显式模型定义，并设置
`input: ["text", "image"]`
- 在存在显式 MiniMax 提供商配置之前，
内置提供商目录目前会将聊天引用显示为仅文本
元数据
- Coding Plan 用量 API：`https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains`（需要 coding plan 密钥）。
- OpenClaw 会将 MiniMax coding-plan 用量归一化为与其他提供商相同的 `% left` 显示。
MiniMax 原始的 `usage_percent` / `usagePercent`
字段表示的是剩余配额，而不是已消耗配额，因此 OpenClaw 会将其反转。
如果存在基于计数的字段，则优先使用。当 API 返回 `model_remains` 时，
OpenClaw 会优先选择聊天模型条目，在需要时从
`start_time` / `end_time` 推导窗口标签，并将所选模型名称
包含在计划标签中，以便更容易区分 coding-plan 窗口。
- 用量快照会将 `minimax`、`minimax-cn` 和 `minimax-portal` 视为
同一个 MiniMax 配额面，并优先使用已存储的 MiniMax OAuth，然后才回退到 Coding Plan 密钥环境变量。
- 如果你需要精确的成本跟踪，请更新 `models.json` 中的定价值。
- MiniMax Coding Plan 推荐链接（九折优惠）：[https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
- 提供商规则参见 [/concepts/model-providers](/zh-CN/concepts/model-providers)。
- 使用 `openclaw models list` 确认当前提供商 id，然后通过
`openclaw models set minimax/MiniMax-M2.7` 或
`openclaw models set minimax-portal/MiniMax-M2.7` 进行切换。
- 新手引导和直接 API 密钥设置会为这两个 M2.7 变体写入带有 `input: ["text", "image"]` 的显式模型定义
- 在存在显式 MiniMax 提供商配置之前，内置提供商目录当前会将这些聊天模型引用显示为仅文本元数据
- 如果你需要精确的成本跟踪，请更新 `models.json` 中的定价值
- 使用 `openclaw models list` 确认当前的提供商 id，然后通过 `openclaw models set minimax/MiniMax-M2.7` 或 `openclaw models set minimax-portal/MiniMax-M2.7` 进行切换
<Tip>
MiniMax Coding Plan 推荐链接（九折优惠）：[MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
</Tip>
<Note>
有关提供商规则，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。
</Note>
## 故障排除
### “Unknown model: minimax/MiniMax-M2.7”
<AccordionGroup>
<Accordion title='"未知模型：minimax/MiniMax-M2.7"'>
这通常意味着 **MiniMax 提供商尚未配置**（没有匹配的提供商条目，也没有找到 MiniMax 鉴权配置文件/环境变量密钥）。针对这一检测问题的修复已包含在 **2026.1.12** 中。可通过以下方式修复：
这通常意味着 **MiniMax 提供商尚未配置**（没有匹配的
提供商条目，且未找到 MiniMax 认证配置文件/环境变量密钥）。此检测问题的修复已包含在 **2026.1.12** 中。可通过以下方式修复：
- 升级到 **2026.1.12**（或从源码 `main` 运行），然后重启 Gateway 网关。
- 运行 `openclaw configure` 并选择一个 **MiniMax** 鉴权选项，或
- 手动添加匹配的 `models.providers.minimax` 或 `models.providers.minimax-portal` 配置块，或
- 设置 `MINIMAX_API_KEY`、`MINIMAX_OAUTH_TOKEN` 或 MiniMax 鉴权配置文件，以便注入匹配的提供商。
- 升级到 **2026.1.12**（或从源码 `main` 运行），然后重启 Gateway 网关。
- 运行 `openclaw configure` 并选择一个 **MiniMax** 认证选项，或
- 手动添加匹配的 `models.providers.minimax` 或
`models.providers.minimax-portal` 配置块，或
- 设置 `MINIMAX_API_KEY`、`MINIMAX_OAUTH_TOKEN` 或 MiniMax 认证配置文件，
以便注入匹配的提供商。
请确保模型 id **区分大小写**：
请确保模型 id **区分大小写**：
- API 密钥路径：`minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`
- OAuth 路径：`minimax-portal/MiniMax-M2.7` 或 `minimax-portal/MiniMax-M2.7-highspeed`
- API 密钥路径：`minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`
- OAuth 路径：`minimax-portal/MiniMax-M2.7` 或
`minimax-portal/MiniMax-M2.7-highspeed`
然后使用以下命令重新检查：
然后重新检查：
```bash
openclaw models list
```
```bash
openclaw models list
```
</Accordion>
</AccordionGroup>
<Note>
更多帮助： [故障排除](/zh-CN/help/troubleshooting) 和 [常见问题](/zh-CN/help/faq)。
</Note>
## 相关内容
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
共享图像工具参数和提供商选择。
</Card>
<Card title="音乐生成" href="/zh-CN/tools/music-generation" icon="music">
共享音乐工具参数和提供商选择。
</Card>
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
</Card>
<Card title="MiniMax 搜索" href="/zh-CN/tools/minimax-search" icon="magnifying-glass">
通过 MiniMax Coding Plan 进行网页搜索配置。
</Card>
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
常规故障排除和常见问题。
</Card>
</CardGroup>

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

@ -1,142 +1,174 @@
---
read_when:
- 你想通过 Ollama 使用云端或本地模型运行 OpenClaw
- 你想通过 Ollama 使用云端或本地模型来运行 OpenClaw
- 你需要 Ollama 的设置和配置指南
summary: 通过 Ollama（云端和本地模型）运行 OpenClaw
summary: 使用 Ollama 运行 OpenClaw（云端和本地模型）
title: Ollama
x-i18n:
generated_at: "2026-04-08T06:29:11Z"
generated_at: "2026-04-12T10:03:23Z"
model: gpt-5.4
provider: openai
source_hash: d3295a7c879d3636a2ffdec05aea6e670e54a990ef52bd9b0cae253bc24aa3f7
source_hash: 48c956d7b933d2ac637784eff1f0613b15a2b3eb5da7c030133427a73b064117
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>
## 快速开始
## 入门指南
### 新手引导（推荐）
选择你偏好的设置方式和模式。
设置 Ollama 的最快方式是通过新手引导：
<Tabs>
<Tab title="新手引导（推荐）">
**最适合：** 以最快方式完成可用的 Ollama 设置，并自动发现模型。
```bash
openclaw onboard
```
<Steps>
<Step title="运行新手引导">
```bash
openclaw onboard
```
从提供商列表中选择 **Ollama**。新手引导将会：
在提供商列表中选择 **Ollama**。
</Step>
<Step title="选择你的模式">
- **云端 + 本地** — 同时使用云端托管模型和本地模型
- **仅本地** — 仅使用本地模型
1. 询问你的 Ollama 基础 URL，也就是你的实例可被访问的地址（默认是 `http://127.0.0.1:11434`）。
2. 让你选择 **Cloud + Local**（云端模型和本地模型）或 **Local**（仅本地模型）。
3. 如果你选择 **Cloud + Local** 且尚未登录 ollama.com，则打开浏览器登录流程。
4. 发现可用模型并推荐默认值。
5. 如果所选模型在本地不可用，则自动拉取该模型。
如果你选择 **云端 + 本地** 且尚未登录 ollama.com，新手引导会打开浏览器登录流程。
</Step>
<Step title="选择模型">
新手引导会发现可用模型并推荐默认项。如果所选模型在本地不可用，它会自动拉取该模型。
</Step>
<Step title="验证模型是否可用">
```bash
openclaw models list --provider ollama
```
</Step>
</Steps>
也支持非交互模式：
### 非交互模式
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--accept-risk
```
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--accept-risk
```
你也可以选择指定自定义基础 URL 或模型：
你也可以选择性指定自定义基础 URL 或模型：
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
### 手动设置
</Tab>
1. 安装 Ollama：[https://ollama.com/download](https://ollama.com/download)
<Tab title="手动设置">
**最适合：** 完全掌控安装、模型拉取和配置。
2. 如果你想使用本地推理，先拉取一个本地模型：
<Steps>
<Step title="安装 Ollama">
从 [ollama.com/download](https://ollama.com/download) 下载。
</Step>
<Step title="拉取本地模型">
```bash
ollama pull gemma4
# 或
ollama pull gpt-oss:20b
# 或
ollama pull llama3.3
```
</Step>
<Step title="登录以使用云端模型（可选）">
如果你还想使用云端模型：
```bash
ollama pull gemma4
# 或
ollama pull gpt-oss:20b
# 或
ollama pull llama3.3
```
```bash
ollama signin
```
</Step>
<Step title="为 OpenClaw 启用 Ollama">
为 API 密钥设置任意值即可（Ollama 不需要真实密钥）：
3. 如果你也想使用云端模型，请先登录：
```bash
# 设置环境变量
export OLLAMA_API_KEY="ollama-local"
```bash
ollama signin
```
# 或在你的配置文件中设置
openclaw config set models.providers.ollama.apiKey "ollama-local"
```
</Step>
<Step title="检查并设置你的模型">
```bash
openclaw models list
openclaw models set ollama/gemma4
```
4. 运行新手引导并选择 `Ollama`：
或者在配置中设置默认值：
```bash
openclaw onboard
```
```json5
{
agents: {
defaults: {
model: { primary: "ollama/gemma4" },
},
},
}
```
</Step>
</Steps>
- `Local`：仅本地模型
- `Cloud + Local`：本地模型加云端模型
- `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud` 等云端模型**不**需要本地执行 `ollama pull`
</Tab>
</Tabs>
OpenClaw 当前推荐：
## 云端模型
- 本地默认：`gemma4`
- 云端默认：`kimi-k2.5:cloud`、`minimax-m2.7:cloud`、`glm-5.1:cloud`
<Tabs>
<Tab title="云端 + 本地">
云端模型让你能够在使用本地模型的同时，也使用云端托管模型。例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud` —— 这些都**不需要**本地执行 `ollama pull`。
5. 如果你更喜欢手动设置，也可以直接为 OpenClaw 启用 Ollama（任意值都可以；Ollama 不需要真实密钥）：
在设置期间选择 **云端 + 本地** 模式。向导会检查你是否已登录，并在需要时打开浏览器登录流程。如果无法验证认证状态，向导会回退到本地模型默认设置。
```bash
# 设置环境变量
export OLLAMA_API_KEY="ollama-local"
你也可以直接在 [ollama.com/signin](https://ollama.com/signin) 登录。
# 或在你的配置文件中设置
openclaw config set models.providers.ollama.apiKey "ollama-local"
```
OpenClaw 当前推荐以下云端默认模型：`kimi-k2.5:cloud`、`minimax-m2.7:cloud`、`glm-5.1:cloud`。
6. 查看或切换模型：
</Tab>
```bash
openclaw models list
openclaw models set ollama/gemma4
```
<Tab title="仅本地">
在仅本地模式下，OpenClaw 会从本地 Ollama 实例中发现模型。不需要云端登录。
7. 或者在配置中设置默认模型：
OpenClaw 当前推荐 `gemma4` 作为本地默认模型。
```json5
{
agents: {
defaults: {
model: { primary: "ollama/gemma4" },
},
},
}
```
</Tab>
</Tabs>
## 模型发现（隐式提供商）
当你设置了 `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 会自动将图像注入到这些模型的提示中
- 使用模型名称启发式规则为 `reasoning` 赋值（`r1`、`reasoning`、`think`）
- 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限
- 将所有费用设为 `0`
| 行为 | 详情 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 目录查询 | 查询 `/api/tags` |
| 能力检测 | 使用尽力而为的 `/api/show` 查询来读取 `contextWindow` 并检测能力（包括视觉） |
| 视觉模型 | 如果 `/api/show` 报告模型具有 `vision` 能力，则将其标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图像注入提示中 |
| 推理检测 | 使用模型名称启发式规则（`r1`、`reasoning`、`think`）标记 `reasoning` |
| Token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 |
| 成本 | 将所有成本设置为 `0` |
这样可以避免手动填写模型条目，同时让模型目录与本地 Ollama 实例保持一致。
要查看有哪些可用模型：
这样可以避免手动添加模型条目，同时让目录与本地 Ollama 实例保持一致。
```bash
# 查看有哪些可用模型
ollama list
openclaw models list
```
@ -149,74 +181,79 @@ ollama pull mistral
新模型会被自动发现并可立即使用。
如果你显式设置了 `models.providers.ollama`，则会跳过自动发现，你必须手动定义模型（见下文）。
<Note>
如果你显式设置了 `models.providers.ollama`，则会跳过自动发现，你必须手动定义模型。请参阅下方的显式配置部分。
</Note>
## 配置
### 基本设置（隐式发现）
<Tabs>
<Tab title="基础（隐式发现）">
启用 Ollama 的最简单方式是通过环境变量：
启用 Ollama 最简单的方法是设置环境变量：
```bash
export OLLAMA_API_KEY="ollama-local"
```
```bash
export OLLAMA_API_KEY="ollama-local"
```
<Tip>
如果设置了 `OLLAMA_API_KEY`，你可以在提供商条目中省略 `apiKey`，OpenClaw 会为可用性检查自动填充它。
</Tip>
### 显式设置（手动模型）
</Tab>
以下情况请使用显式配置：
<Tab title="显式（手动模型）">
当 Ollama 运行在其他主机或端口上、你希望强制指定特定上下文窗口或模型列表，或者你希望完全手动定义模型时，请使用显式配置。
- Ollama 运行在其他主机或端口上。
- 你想强制指定特定的上下文窗口或模型列表。
- 你想完全手动定义模型。
```json5
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434",
apiKey: "ollama-local",
api: "ollama",
models: [
{
id: "gpt-oss:20b",
name: "GPT-OSS 20B",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 8192,
maxTokens: 8192 * 10
```json5
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434",
apiKey: "ollama-local",
api: "ollama",
models: [
{
id: "gpt-oss:20b",
name: "GPT-OSS 20B",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 8192,
maxTokens: 8192 * 10
}
]
}
]
}
}
}
}
}
```
```
如果设置了 `OLLAMA_API_KEY`，你可以在提供商条目中省略 `apiKey`，OpenClaw 会在可用性检查时自动补上它。
</Tab>
### 自定义基础 URL（显式配置）
<Tab title="自定义基础 URL">
如果 Ollama 运行在不同的主机或端口上（显式配置会禁用自动发现，因此你需要手动定义模型）：
如果 Ollama 运行在不同的主机或端口上（显式配置会禁用自动发现，因此你需要手动定义模型）：
```json5
{
models: {
providers: {
ollama: {
apiKey: "ollama-local",
baseUrl: "http://ollama-host:11434", // 不要加 /v1 - 请使用原生 Ollama API URL
api: "ollama", // 显式设置以确保原生工具调用行为
```json5
{
models: {
providers: {
ollama: {
apiKey: "ollama-local",
baseUrl: "http://ollama-host:11434", // 不要加 /v1 - 请使用原生 Ollama API URL
api: "ollama", // 显式设置以确保原生工具调用行为
},
},
},
},
},
}
```
}
```
<Warning>
不要在 URL 中添加 `/v1`。`/v1` 路径会启用 OpenAI 兼容模式，而该模式下工具调用不可靠。请使用不带路径后缀的基础 Ollama URL。
</Warning>
<Warning>
不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用不可靠。请使用不带路径后缀的 Ollama 基础 URL。
</Warning>
</Tab>
</Tabs>
### 模型选择
@ -235,26 +272,17 @@ export OLLAMA_API_KEY="ollama-local"
}
```
## 云端模型
云端模型让你可以在本地模型之外，同时运行云端托管的模型（例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud`、`glm-5.1:cloud`）。
要使用云端模型，请在设置过程中选择 **Cloud + Local** 模式。向导会检查你是否已登录，并在需要时打开浏览器登录流程。如果无法验证认证状态，向导会回退为本地模型默认值。
你也可以直接在 [ollama.com/signin](https://ollama.com/signin) 登录。
## Ollama Web 搜索
OpenClaw 还支持将 **Ollama Web 搜索** 作为内置的 `web_search`
提供商。
OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` 提供商。
- 它使用你已配置的 Ollama 主机（已设置时使用 `models.providers.ollama.baseUrl`，
否则使用 `http://127.0.0.1:11434`）。
- 它不需要密钥。
- 它要求 Ollama 正在运行，并且你已通过 `ollama signin` 登录。
| 属性 | 详情 |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| 主机 | 使用你配置的 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
{
@ -268,120 +296,169 @@ OpenClaw 还支持将 **Ollama Web 搜索** 作为内置的 `web_search`
}
```
有关完整设置和行为细节，请参见 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。
<Note>
有关完整的设置和行为详情，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。
</Note>
## 高级
## 高级配置
### 推理模型
<AccordionGroup>
<Accordion title="旧版 OpenAI 兼容模式">
<Warning>
**在 OpenAI 兼容模式下，工具调用并不可靠。** 只有当你需要为代理使用 OpenAI 格式且不依赖原生工具调用行为时，才应使用此模式。
</Warning>
OpenClaw 默认将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为具备推理能力：
如果你需要改用 OpenAI 兼容端点（例如在仅支持 OpenAI 格式的代理之后），请显式设置 `api: "openai-completions"`：
```bash
ollama pull deepseek-r1:32b
```
### 模型费用
Ollama 是免费的并且在本地运行，因此所有模型费用均设为 $0。
### 流式传输配置
OpenClaw 默认使用 **原生 Ollama API**（`/api/chat`）集成 Ollama，它完全支持同时进行流式传输和工具调用。无需任何特殊配置。
#### 旧版 OpenAI 兼容模式
<Warning>
**在 OpenAI 兼容模式下，工具调用不可靠。** 仅当你需要为代理使用 OpenAI 格式，并且不依赖原生工具调用行为时，才使用此模式。
</Warning>
如果你需要改用 OpenAI 兼容端点（例如在仅支持 OpenAI 格式的代理后面），请显式设置 `api: "openai-completions"`：
```json5
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434/v1",
api: "openai-completions",
injectNumCtxForOpenAICompat: true, // 默认值：true
apiKey: "ollama-local",
models: [...]
```json5
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434/v1",
api: "openai-completions",
injectNumCtxForOpenAICompat: true, // 默认值：true
apiKey: "ollama-local",
models: [...]
}
}
}
}
}
}
```
```
此模式可能不支持同时进行流式传输和工具调用。你可能需要在模型配置中通过 `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
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434/v1",
api: "openai-completions",
injectNumCtxForOpenAICompat: false,
apiKey: "ollama-local",
models: [...]
```json5
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434/v1",
api: "openai-completions",
injectNumCtxForOpenAICompat: false,
apiKey: "ollama-local",
models: [...]
}
}
}
}
}
}
```
```
### 上下文窗口
</Accordion>
对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，否则会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。你也可以在显式提供商配置中覆盖 `contextWindow` 和 `maxTokens`。
<Accordion title="上下文窗口">
对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，否则会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。
你可以在显式提供商配置中覆盖 `contextWindow` 和 `maxTokens`：
```json5
{
models: {
providers: {
ollama: {
models: [
{
id: "llama3.3",
contextWindow: 131072,
maxTokens: 65536,
}
]
}
}
}
}
```
</Accordion>
<Accordion title="推理模型">
OpenClaw 默认会将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为具备推理能力。
```bash
ollama pull deepseek-r1:32b
```
不需要额外配置 —— OpenClaw 会自动标记它们。
</Accordion>
<Accordion title="模型成本">
Ollama 是免费的，并且在本地运行，因此所有模型成本都设置为 $0。这同时适用于自动发现的模型和手动定义的模型。
</Accordion>
<Accordion title="流式传输配置">
OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），它完全支持同时进行流式传输和工具调用。不需要任何特殊配置。
<Tip>
如果你需要使用 OpenAI 兼容端点，请参阅上方的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。
</Tip>
</Accordion>
</AccordionGroup>
## 故障排除
### 未检测到 Ollama
<AccordionGroup>
<Accordion title="未检测到 Ollama">
请确认 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或认证配置文件），同时你**没有**定义显式的 `models.providers.ollama` 条目：
请确保 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或认证配置），同时你**没有**定义显式的 `models.providers.ollama` 条目：
```bash
ollama serve
```
```bash
ollama serve
```
验证 API 是否可访问：
并确认 API 可访问：
```bash
curl http://localhost:11434/api/tags
```
```bash
curl http://localhost:11434/api/tags
```
</Accordion>
### 没有可用模型
<Accordion title="没有可用模型">
如果你的模型未列出，请在本地拉取该模型，或在 `models.providers.ollama` 中显式定义它。
如果你的模型未列出，可以：
```bash
ollama list # 查看已安装的模型
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3 # 或其他模型
```
- 在本地拉取该模型，或
- 在 `models.providers.ollama` 中显式定义该模型。
</Accordion>
要添加模型：
<Accordion title="连接被拒绝">
检查 Ollama 是否正在正确的端口上运行：
```bash
ollama list # 查看已安装的模型
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3 # 或其他模型
```
```bash
# 检查 Ollama 是否正在运行
ps aux | grep ollama
### 连接被拒绝
# 或重启 Ollama
ollama serve
```
检查 Ollama 是否运行在正确的端口上：
</Accordion>
</AccordionGroup>
```bash
# 检查 Ollama 是否正在运行
ps aux | grep ollama
<Note>
更多帮助：[故障排除](/zh-CN/help/troubleshooting) 和 [常见问题](/zh-CN/help/faq)。
</Note>
# 或重启 Ollama
ollama serve
```
## 相关内容
## 另请参阅
- [模型提供商](/zh-CN/concepts/model-providers) - 所有提供商的概览
- [模型选择](/zh-CN/concepts/models) - 如何选择模型
- [配置](/zh-CN/gateway/configuration) - 完整配置参考
<CardGroup cols={2}>
<Card title="模型提供商" href="/zh-CN/concepts/model-providers" icon="layers">
所有提供商、模型引用和故障切换行为的概览。
</Card>
<Card title="模型选择" href="/zh-CN/concepts/models" icon="brain">
如何选择和配置模型。
</Card>
<Card title="Ollama Web 搜索" href="/zh-CN/tools/ollama-search" icon="magnifying-glass">
了解由 Ollama 驱动的 Web 搜索的完整设置和行为详情。
</Card>
<Card title="配置" href="/zh-CN/gateway/configuration" icon="gear">
完整配置参考。
</Card>
</CardGroup>

384
docs/zh-CN/providers/venice.md
View File

@ -1,102 +1,106 @@
---
read_when:
- 你想在 OpenClaw 中使用注重隐私的推理
- 你想获取 Venice AI 设置指南
summary: 在 OpenClaw 中使用注重隐私的 Venice AI 模型
- 你希望在 OpenClaw 中使用注重隐私的推理模型
- 你希望获得 Venice AI 的设置指南
summary: 在 OpenClaw 中使用 Venice AI 的隐私导向模型
title: Venice AI
x-i18n:
generated_at: "2026-04-05T10:07:42Z"
generated_at: "2026-04-12T10:03:24Z"
model: gpt-5.4
provider: openai
source_hash: 53313e45e197880feb7e90764ee8fd6bb7f5fd4fe03af46b594201c77fbc8eab
source_hash: 6f8005edb1d7781316ce8b5432bf4f9375c16113594a2a588912dce82234a9e5
source_path: providers/venice.md
workflow: 15
---
# Venice AI（Venice 亮点）
# Venice AI
**Venice** 是我们重点推荐的 Venice 设置，适合用于以隐私为先的推理，并可选择通过匿名访问专有模型。
Venice AI 提供以隐私为中心的 AI 推理，支持未审查模型，并可通过其匿名代理访问主流专有模型。所有推理默认都是私密的——不会用你的数据训练，也不会记录日志。
Venice AI 提供**注重隐私的 AI 推理**，支持无审查模型，并可通过其匿名代理访问主流专有模型。所有推理默认都是私密的——不会用你的数据进行训练，也不会记录日志。
## 为什么在 OpenClaw 中使用 Venice
- **私密推理**，适用于开源模型（不记录日志）。
- **未审查模型**，在你需要时可用。
- **匿名访问** 专有模型（Opus/GPT/Gemini），在质量重要时尤其有用。
- **私密推理**：用于开源模型（不记录日志）。
- **无审查模型**：在你需要时可用。
- **对专有模型的匿名访问**：当质量更重要时，可使用（Opus/GPT/Gemini）。
- 兼容 OpenAI 的 `/v1` 端点。
## 隐私模式
Venice 提供两种隐私级别——理解这一点对于选择模型至关重要：
Venice 提供两种隐私级别——理解这一点是选择模型的关键：
| 模式 | 描述 | 模型 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Private** | 完全私密。提示词/响应 **永不存储或记录**。短暂存在。 | Llama、Qwen、DeepSeek、Kimi、MiniMax、Venice Uncensored 等 |
| **Anonymized** | 通过 Venice 代理并去除元数据。底层提供商（OpenAI、Anthropic、Google、xAI）看到的是匿名请求。 | Claude、GPT、Gemini、Grok |
| **私密** | 完全私密。提示词/响应**绝不会被存储或记录**。临时性。 | Llama、Qwen、DeepSeek、Kimi、MiniMax、Venice Uncensored 等。 |
| **匿名化** | 通过 Venice 代理并剥离元数据。底层提供商（OpenAI、Anthropic、Google、xAI）看到的是匿名化请求。 | Claude、GPT、Gemini、Grok |
<Warning>
匿名化模型**并非**完全私密。Venice 会在转发前剥离元数据，但底层提供商（OpenAI、Anthropic、Google、xAI）仍会处理该请求。若你需要完全隐私，请选择**私密**模型。
</Warning>
## 功能
- **注重隐私**：可在 “private”（完全私密）和 “anonymized”（代理匿名）模式之间选择
- **未审查模型**：可访问不受内容限制的模型
- **注重隐私**：可在“私密”（完全私密）和“匿名化”（代理）模式之间选择
- **无审查模型**：可访问没有内容限制的模型
- **主流模型访问**：通过 Venice 的匿名代理使用 Claude、GPT、Gemini 和 Grok
- **兼容 OpenAI 的 API**：标准 `/v1` 端点，便于集成
- **流式传输**：✅ 所有模型均支持
- **函数调用**：✅ 部分模型支持（请检查模型能力）
- **视觉**：✅ 具备视觉能力的模型支持
- **流式传输**：所有模型均支持
- **函数调用**：部分模型支持（请检查模型能力）
- **视觉**：支持具备视觉能力的模型
- **无硬性速率限制**：极端使用情况下可能会触发公平使用限流
## 设置
## 入门指南
### 1. 获取 API 密钥
<Steps>
<Step title="获取你的 API 密钥">
1. 在 [venice.ai](https://venice.ai) 注册
2. 前往**设置 > API Keys > Create new key**
3. 复制你的 API 密钥（格式：`vapi_xxxxxxxxxxxx`）
</Step>
<Step title="配置 OpenClaw">
选择你偏好的设置方式：
1. 在 [venice.ai](https://venice.ai) 注册
2. 进入 **Settings → API Keys → Create new key**
3. 复制你的 API 密钥（格式：`vapi_xxxxxxxxxxxx`）
<Tabs>
<Tab title="交互式（推荐）">
```bash
openclaw onboard --auth-choice venice-api-key
```
### 2. 配置 OpenClaw
这将会：
1. 提示你输入 API 密钥（或使用现有的 `VENICE_API_KEY`）
2. 显示所有可用的 Venice 模型
3. 让你选择默认模型
4. 自动配置该提供商
</Tab>
<Tab title="环境变量">
```bash
export VENICE_API_KEY="vapi_xxxxxxxxxxxx"
```
</Tab>
<Tab title="非交互式">
```bash
openclaw onboard --non-interactive \
--auth-choice venice-api-key \
--venice-api-key "vapi_xxxxxxxxxxxx"
```
</Tab>
</Tabs>
**选项 A：环境变量**
```bash
export VENICE_API_KEY="vapi_xxxxxxxxxxxx"
```
**选项 B：交互式设置（推荐）**
```bash
openclaw onboard --auth-choice venice-api-key
```
这将会：
1. 提示你输入 API 密钥（或使用现有的 `VENICE_API_KEY`）
2. 显示所有可用的 Venice 模型
3. 让你选择默认模型
4. 自动配置提供商
**选项 C：非交互式**
```bash
openclaw onboard --non-interactive \
--auth-choice venice-api-key \
--venice-api-key "vapi_xxxxxxxxxxxx"
```
### 3. 验证设置
```bash
openclaw agent --model venice/kimi-k2-5 --message "Hello, are you working?"
```
</Step>
<Step title="验证设置">
```bash
openclaw agent --model venice/kimi-k2-5 --message "Hello, are you working?"
```
</Step>
</Steps>
## 模型选择
设置完成后，OpenClaw 会显示所有可用的 Venice 模型。请根据你的需求进行选择：
- **默认模型**：`venice/kimi-k2-5`，适合强大的私密推理加视觉能力。
- **高能力选项**：`venice/claude-opus-4-6`，适合最强的 Venice 匿名路径。
- **隐私**：选择 “private” 模型以获得完全私密的推理。
- **能力**：选择 “anonymized” 模型，以便通过 Venice 的代理访问 Claude、GPT、Gemini。
- **高能力选项**：`venice/claude-opus-4-6`，适合最强的 Venice 匿名化路径。
- **隐私**：选择“私密”模型以获得完全私密的推理。
- **能力**：选择“匿名化”模型以通过 Venice 的代理访问 Claude、GPT、Gemini。
你可以随时更改默认模型：
@ -111,104 +115,105 @@ openclaw models set venice/claude-opus-4-6
openclaw models list | grep venice
```
## 通过 `openclaw configure` 配置
你也可以运行 `openclaw configure`，选择**模型/身份验证**，然后选择**Venice AI**。
1. 运行 `openclaw configure`
2. 选择 **Model/auth**
3. 选择 **Venice AI**
<Tip>
使用下表为你的使用场景选择合适的模型。
## 我应该使用哪个模型？
| 用例 | 推荐模型 | 原因 |
| 使用场景 | 推荐模型 | 原因 |
| -------------------------- | -------------------------------- | -------------------------------------------- |
| **通用聊天（默认）** | `kimi-k2-5` | 强大的私密推理加视觉能力 |
| **整体质量最佳** | `claude-opus-4-6` | 最强的 Venice 匿名选项 |
| **隐私 + 编码** | `qwen3-coder-480b-a35b-instruct` | 具有大上下文的私密编码模型 |
| **私密视觉** | `kimi-k2-5` | 在不离开 Private 模式的情况下支持视觉 |
| **快速 + 低成本** | `qwen3-4b` | 轻量级推理模型 |
| **整体质量最佳** | `claude-opus-4-6` | 最强的 Venice 匿名化选项 |
| **隐私 + 编码** | `qwen3-coder-480b-a35b-instruct` | 具备大上下文的私密编码模型 |
| **私密视觉** | `kimi-k2-5` | 在不离开私密模式的情况下支持视觉 |
| **快速 + 便宜** | `qwen3-4b` | 轻量级推理模型 |
| **复杂私密任务** | `deepseek-v3.2` | 推理能力强，但不支持 Venice 工具 |
| **未审查** | `venice-uncensored` | 无内容限制 |
| **无审查** | `venice-uncensored` | 无内容限制 |
</Tip>
## 可用模型（共 41 个）
### Private 模型（26 个）- 完全私密，不记录日志
<AccordionGroup>
<Accordion title="私密模型（26 个）— 完全私密，不记录日志">
| 模型 ID | 名称 | 上下文 | 功能 |
| -------------------------------------- | ----------------------------------- | ------- | -------------------------- |
| `kimi-k2-5` | Kimi K2.5 | 256k | 默认、推理、视觉 |
| `kimi-k2-thinking` | Kimi K2 Thinking | 256k | 推理 |
| `llama-3.3-70b` | Llama 3.3 70B | 128k | 通用 |
| `llama-3.2-3b` | Llama 3.2 3B | 128k | 通用 |
| `hermes-3-llama-3.1-405b` | Hermes 3 Llama 3.1 405B | 128k | 通用，工具已禁用 |
| `qwen3-235b-a22b-thinking-2507` | Qwen3 235B Thinking | 128k | 推理 |
| `qwen3-235b-a22b-instruct-2507` | Qwen3 235B Instruct | 128k | 通用 |
| `qwen3-coder-480b-a35b-instruct` | Qwen3 Coder 480B | 256k | 编码 |
| `qwen3-coder-480b-a35b-instruct-turbo` | Qwen3 Coder 480B Turbo | 256k | 编码 |
| `qwen3-5-35b-a3b` | Qwen3.5 35B A3B | 256k | 推理、视觉 |
| `qwen3-next-80b` | Qwen3 Next 80B | 256k | 通用 |
| `qwen3-vl-235b-a22b` | Qwen3 VL 235B（视觉） | 256k | 视觉 |
| `qwen3-4b` | Venice Small（Qwen3 4B） | 32k | 快速、推理 |
| `deepseek-v3.2` | DeepSeek V3.2 | 160k | 推理，工具已禁用 |
| `venice-uncensored` | Venice Uncensored（Dolphin-Mistral） | 32k | 无审查，工具已禁用 |
| `mistral-31-24b` | Venice Medium（Mistral） | 128k | 视觉 |
| `google-gemma-3-27b-it` | Google Gemma 3 27B Instruct | 198k | 视觉 |
| `openai-gpt-oss-120b` | OpenAI GPT OSS 120B | 128k | 通用 |
| `nvidia-nemotron-3-nano-30b-a3b` | NVIDIA Nemotron 3 Nano 30B | 128k | 通用 |
| `olafangensan-glm-4.7-flash-heretic` | GLM 4.7 Flash Heretic | 128k | 推理 |
| `zai-org-glm-4.6` | GLM 4.6 | 198k | 通用 |
| `zai-org-glm-4.7` | GLM 4.7 | 198k | 推理 |
| `zai-org-glm-4.7-flash` | GLM 4.7 Flash | 128k | 推理 |
| `zai-org-glm-5` | GLM 5 | 198k | 推理 |
| `minimax-m21` | MiniMax M2.1 | 198k | 推理 |
| `minimax-m25` | MiniMax M2.5 | 198k | 推理 |
</Accordion>
| Model ID | 名称 | 上下文 | 功能 |
| -------------------------------------- | ----------------------------------- | ------- | -------------------------- |
| `kimi-k2-5` | Kimi K2.5 | 256k | 默认、推理、视觉 |
| `kimi-k2-thinking` | Kimi K2 Thinking | 256k | 推理 |
| `llama-3.3-70b` | Llama 3.3 70B | 128k | 通用 |
| `llama-3.2-3b` | Llama 3.2 3B | 128k | 通用 |
| `hermes-3-llama-3.1-405b` | Hermes 3 Llama 3.1 405B | 128k | 通用，工具已禁用 |
| `qwen3-235b-a22b-thinking-2507` | Qwen3 235B Thinking | 128k | 推理 |
| `qwen3-235b-a22b-instruct-2507` | Qwen3 235B Instruct | 128k | 通用 |
| `qwen3-coder-480b-a35b-instruct` | Qwen3 Coder 480B | 256k | 编码 |
| `qwen3-coder-480b-a35b-instruct-turbo` | Qwen3 Coder 480B Turbo | 256k | 编码 |
| `qwen3-5-35b-a3b` | Qwen3.5 35B A3B | 256k | 推理、视觉 |
| `qwen3-next-80b` | Qwen3 Next 80B | 256k | 通用 |
| `qwen3-vl-235b-a22b` | Qwen3 VL 235B（视觉） | 256k | 视觉 |
| `qwen3-4b` | Venice Small（Qwen3 4B） | 32k | 快速、推理 |
| `deepseek-v3.2` | DeepSeek V3.2 | 160k | 推理，工具已禁用 |
| `venice-uncensored` | Venice Uncensored（Dolphin-Mistral） | 32k | 未审查，工具已禁用 |
| `mistral-31-24b` | Venice Medium（Mistral） | 128k | 视觉 |
| `google-gemma-3-27b-it` | Google Gemma 3 27B Instruct | 198k | 视觉 |
| `openai-gpt-oss-120b` | OpenAI GPT OSS 120B | 128k | 通用 |
| `nvidia-nemotron-3-nano-30b-a3b` | NVIDIA Nemotron 3 Nano 30B | 128k | 通用 |
| `olafangensan-glm-4.7-flash-heretic` | GLM 4.7 Flash Heretic | 128k | 推理 |
| `zai-org-glm-4.6` | GLM 4.6 | 198k | 通用 |
| `zai-org-glm-4.7` | GLM 4.7 | 198k | 推理 |
| `zai-org-glm-4.7-flash` | GLM 4.7 Flash | 128k | 推理 |
| `zai-org-glm-5` | GLM 5 | 198k | 推理 |
| `minimax-m21` | MiniMax M2.1 | 198k | 推理 |
| `minimax-m25` | MiniMax M2.5 | 198k | 推理 |
### Anonymized 模型（15 个）- 通过 Venice 代理
| Model ID | 名称 | 上下文 | 功能 |
| ------------------------------- | ------------------------------ | ------- | ------------------------- |
| `claude-opus-4-6` | Claude Opus 4.6（通过 Venice） | 1M | 推理、视觉 |
| `claude-opus-4-5` | Claude Opus 4.5（通过 Venice） | 198k | 推理、视觉 |
| `claude-sonnet-4-6` | Claude Sonnet 4.6（通过 Venice） | 1M | 推理、视觉 |
| `claude-sonnet-4-5` | Claude Sonnet 4.5（通过 Venice） | 198k | 推理、视觉 |
| `openai-gpt-54` | GPT-5.4（通过 Venice） | 1M | 推理、视觉 |
| `openai-gpt-53-codex` | GPT-5.3 Codex（通过 Venice） | 400k | 推理、视觉、编码 |
| `openai-gpt-52` | GPT-5.2（通过 Venice） | 256k | 推理 |
| `openai-gpt-52-codex` | GPT-5.2 Codex（通过 Venice） | 256k | 推理、视觉、编码 |
| `openai-gpt-4o-2024-11-20` | GPT-4o（通过 Venice） | 128k | 视觉 |
| `openai-gpt-4o-mini-2024-07-18` | GPT-4o Mini（通过 Venice） | 128k | 视觉 |
| `gemini-3-1-pro-preview` | Gemini 3.1 Pro（通过 Venice） | 1M | 推理、视觉 |
| `gemini-3-pro-preview` | Gemini 3 Pro（通过 Venice） | 198k | 推理、视觉 |
| `gemini-3-flash-preview` | Gemini 3 Flash（通过 Venice） | 256k | 推理、视觉 |
| `grok-41-fast` | Grok 4.1 Fast（通过 Venice） | 1M | 推理、视觉 |
| `grok-code-fast-1` | Grok Code Fast 1（通过 Venice） | 256k | 推理、编码 |
<Accordion title="匿名化模型（15 个）— 通过 Venice 代理">
| 模型 ID | 名称 | 上下文 | 功能 |
| ------------------------------- | ------------------------------ | ------- | ------------------------- |
| `claude-opus-4-6` | Claude Opus 4.6（通过 Venice） | 1M | 推理、视觉 |
| `claude-opus-4-5` | Claude Opus 4.5（通过 Venice） | 198k | 推理、视觉 |
| `claude-sonnet-4-6` | Claude Sonnet 4.6（通过 Venice） | 1M | 推理、视觉 |
| `claude-sonnet-4-5` | Claude Sonnet 4.5（通过 Venice） | 198k | 推理、视觉 |
| `openai-gpt-54` | GPT-5.4（通过 Venice） | 1M | 推理、视觉 |
| `openai-gpt-53-codex` | GPT-5.3 Codex（通过 Venice） | 400k | 推理、视觉、编码 |
| `openai-gpt-52` | GPT-5.2（通过 Venice） | 256k | 推理 |
| `openai-gpt-52-codex` | GPT-5.2 Codex（通过 Venice） | 256k | 推理、视觉、编码 |
| `openai-gpt-4o-2024-11-20` | GPT-4o（通过 Venice） | 128k | 视觉 |
| `openai-gpt-4o-mini-2024-07-18` | GPT-4o Mini（通过 Venice） | 128k | 视觉 |
| `gemini-3-1-pro-preview` | Gemini 3.1 Pro（通过 Venice） | 1M | 推理、视觉 |
| `gemini-3-pro-preview` | Gemini 3 Pro（通过 Venice） | 198k | 推理、视觉 |
| `gemini-3-flash-preview` | Gemini 3 Flash（通过 Venice） | 256k | 推理、视觉 |
| `grok-41-fast` | Grok 4.1 Fast（通过 Venice） | 1M | 推理、视觉 |
| `grok-code-fast-1` | Grok Code Fast 1（通过 Venice） | 256k | 推理、编码 |
</Accordion>
</AccordionGroup>
## 模型发现
当设置了 `VENICE_API_KEY` 时，OpenClaw 会自动从 Venice API 发现模型。如果 API 不可达，它会回退到静态目录。
设置 `VENICE_API_KEY` 后，OpenClaw 会自动从 Venice API 发现模型。如果 API 无法访问，它会回退到静态目录。
`/models` 端点是公开的（列出模型时无需鉴权），但推理需要有效的 API 密钥。
`/models` 端点是公开的（列出模型无需身份验证），但推理需要有效的 API 密钥。
## 流式传输和工具支持
| 功能 | 支持情况 |
| -------------------- | ------------------------------------------------------- |
| **流式传输** | ✅ 所有模型 |
| **函数调用** | ✅ 大多数模型（请检查 API 中的 `supportsFunctionCalling`） |
| **视觉/图像** | ✅ 标记有 “Vision” 功能的模型 |
| **JSON 模式** | ✅ 通过 `response_format` 支持 |
| -------------------- | ---------------------------------------------------- |
| **流式传输** | 所有模型 |
| **函数调用** | 大多数模型（请检查 API 中的 `supportsFunctionCalling`） |
| **视觉/图像** | 标记为具有“视觉”功能的模型 |
| **JSON 模式** | 通过 `response_format` 支持 |
## 定价
Venice 使用基于积分的系统。当前费率请查看 [venice.ai/pricing](https://venice.ai/pricing)：
- **Private 模型**：通常成本更低
- **Anonymized 模型**：与直接 API 定价相近，外加少量 Venice 费用
- **私密模型**：通常成本更低
- **匿名化模型**：与直接 API 定价相近，外加少量 Venice 费用
## 对比：Venice 与直接 API
### Venice（匿名化）与直连 API 对比
| 方面 | Venice（Anonymized） | 直接 API |
| 方面 | Venice（匿名化） | 直连 API |
| ------------ | ----------------------------- | ------------------- |
| **隐私** | 元数据已去除、请求匿名化 | 关联到你的账户 |
| **隐私** | 元数据已剥离，请求已匿名化 | 关联到你的账户 |
| **延迟** | +10-50ms（代理） | 直连 |
| **功能** | 支持大多数功能 | 完整功能 |
| **计费** | Venice 积分 | 提供商计费 |
@ -216,13 +221,13 @@ Venice 使用基于积分的系统。当前费率请查看 [venice.ai/pricing](h
## 使用示例
```bash
# 使用默认的私密模型
# 使用默认私密模型
openclaw agent --model venice/kimi-k2-5 --message "Quick health check"
# 通过 Venice 使用 Claude Opus（匿名）
# 通过 Venice 使用 Claude Opus（匿名化）
openclaw agent --model venice/claude-opus-4-6 --message "Summarize this task"
# 使用未审查模型
# 使用无审查模型
openclaw agent --model venice/venice-uncensored --message "Draft options"
# 使用带图像的视觉模型
@ -234,56 +239,77 @@ openclaw agent --model venice/qwen3-coder-480b-a35b-instruct --message "Refactor
## 故障排除
### API 密钥无法识别
<AccordionGroup>
<Accordion title="API 密钥未被识别">
```bash
echo $VENICE_API_KEY
openclaw models list | grep venice
```
```bash
echo $VENICE_API_KEY
openclaw models list | grep venice
```
请确认该密钥以 `vapi_` 开头。
请确保密钥以 `vapi_` 开头。
</Accordion>
### 模型不可用
<Accordion title="模型不可用">
Venice 模型目录会动态更新。运行 `openclaw models list` 查看当前可用的模型。某些模型可能暂时离线。
</Accordion>
Venice 模型目录会动态更新。运行 `openclaw models list` 以查看当前可用模型。有些模型可能会暂时离线。
<Accordion title="连接问题">
Venice API 地址为 `https://api.venice.ai/api/v1`。请确认你的网络允许 HTTPS 连接。
</Accordion>
</AccordionGroup>
### 连接问题
<Note>
更多帮助：[故障排除](/zh-CN/help/troubleshooting) 和 [常见问题](/zh-CN/help/faq)。
</Note>
Venice API 地址为 `https://api.venice.ai/api/v1`。请确保你的网络允许 HTTPS 连接。
## 高级配置
## 配置文件示例
```json5
{
env: { VENICE_API_KEY: "vapi_..." },
agents: { defaults: { model: { primary: "venice/kimi-k2-5" } } },
models: {
mode: "merge",
providers: {
venice: {
baseUrl: "https://api.venice.ai/api/v1",
apiKey: "${VENICE_API_KEY}",
api: "openai-completions",
models: [
{
id: "kimi-k2-5",
name: "Kimi K2.5",
reasoning: true,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 256000,
maxTokens: 65536,
<AccordionGroup>
<Accordion title="配置文件示例">
```json5
{
env: { VENICE_API_KEY: "vapi_..." },
agents: { defaults: { model: { primary: "venice/kimi-k2-5" } } },
models: {
mode: "merge",
providers: {
venice: {
baseUrl: "https://api.venice.ai/api/v1",
apiKey: "${VENICE_API_KEY}",
api: "openai-completions",
models: [
{
id: "kimi-k2-5",
name: "Kimi K2.5",
reasoning: true,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 256000,
maxTokens: 65536,
},
],
},
],
},
},
},
},
}
```
}
```
</Accordion>
</AccordionGroup>
## 链接
## 相关内容
- [Venice AI](https://venice.ai)
- [API 文档](https://docs.venice.ai)
- [定价](https://venice.ai/pricing)
- [状态](https://status.venice.ai)
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
</Card>
<Card title="Venice AI" href="https://venice.ai" icon="globe">
Venice AI 官网和账户注册。
</Card>
<Card title="API 文档" href="https://docs.venice.ai" icon="book">
Venice API 参考和开发者文档。
</Card>
<Card title="定价" href="https://venice.ai/pricing" icon="credit-card">
当前 Venice 积分费率和套餐。
</Card>
</CardGroup>