[OpenClaw 文档]模型--提供商

<Steps>
  <Step title="获取你的 API 密钥">
    在 [Anthropic Console](https://console.anthropic.com/) 中创建 API 密钥。
  </Step>
  <Step title="运行新手引导">
    ```bash
    openclaw onboard
    # choose: Anthropic API key
    ```

    或者直接传入密钥：

    ```bash
    openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
    ```
  </Step>
  <Step title="验证模型可用">
    ```bash
    openclaw models list --provider anthropic
    ```
  </Step>
</Steps>

### 配置示例

```json5
{
  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}
```

<Steps>
  <Step title="确认 Claude CLI 已安装并已登录">
    使用以下命令验证：

    ```bash
    claude --version
    ```
  </Step>
  <Step title="运行新手引导">
    ```bash
    openclaw onboard
    # choose: Claude CLI
    ```

    OpenClaw 会检测并复用现有 Claude CLI 凭证。
  </Step>
  <Step title="验证模型可用">
    ```bash
    openclaw models list --provider anthropic
    ```
  </Step>
</Steps>

<Note>
Claude CLI 后端的设置和运行时细节见 [CLI 后端](/zh-CN/gateway/cli-backends)。
</Note>

### 配置示例

推荐使用规范的 Anthropic 模型引用，并加上 CLI 运行时覆盖：

```json5
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-7" },
      models: {
        "anthropic/claude-opus-4-7": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}
```

旧版 `claude-cli/claude-opus-4-7` 模型引用仍可用于
兼容性，但新配置应将提供商/模型选择保留为
`anthropic/*`，并将执行后端放在提供商/模型运行时策略中。

<Tip>
如果你想要最清晰的计费路径，请改用 Anthropic API 密钥。OpenClaw 还支持来自 [OpenAI Codex](/zh-CN/providers/openai)、[Qwen Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [Z.AI / GLM](/zh-CN/providers/glm) 的订阅式选项。
</Tip>

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { thinking: "adaptive" },
        },
      },
    },
  },
}

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}

```json5
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
    list: [
      { id: "research", default: true },
      { id: "alerts", params: { cacheRetention: "none" } },
    ],
  },
}
```

配置合并顺序：

1. `agents.defaults.models["provider/model"].params`
2. `agents.list[].params`（匹配 `id`，按键覆盖）

这允许一个智能体保持长期缓存，同时让同一模型上的另一个智能体为突发性/低复用流量禁用缓存。

| 命令 | 映射到 |
|---------|---------|
| `/fast on` | `service_tier: "auto"` |
| `/fast off` | `service_tier: "standard_only"` |

```json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-6": {
          params: { fastMode: true },
        },
      },
    },
  },
}
```

<Note>
- 仅注入到直连 `api.anthropic.com` 请求。代理路由会保持 `service_tier` 不变。
- 当同时设置时，显式 `serviceTier` 或 `service_tier` 参数会覆盖 `/fast`。
- 在没有 Priority Tier 容量的账户上，`service_tier: "auto"` 可能会解析为 `standard`。

</Note>

| 属性            | 值                    |
| --------------- | --------------------- |
| 默认模型        | `claude-opus-4-7`     |
| 支持的输入      | 图像、PDF 文档        |

当图像或 PDF 附加到对话时，OpenClaw 会自动
通过 Anthropic 媒体理解提供商进行路由。

```json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { context1m: true },
        },
      },
    },
  },
}
```

OpenClaw 会在请求上将其映射为 `anthropic-beta: context-1m-2025-08-07`。

`params.context1m: true` 也适用于符合条件的 Opus 和 Sonnet 模型的 Claude CLI 后端
（`claude-cli/*`），将这些 CLI 会话的运行时
上下文窗口扩展到与直连 API 行为一致。

<Warning>
需要你的 Anthropic 凭证具备长上下文访问权限。旧版令牌认证（`sk-ant-oat-*`）会被 1M 上下文请求拒绝，OpenClaw 会记录警告并回退到标准上下文窗口。
</Warning>

<Steps>
  <Step title="在 Gateway 网关主机上设置 AWS 凭证">
    ```bash
    export AWS_ACCESS_KEY_ID="AKIA..."
    export AWS_SECRET_ACCESS_KEY="..."
    export AWS_REGION="us-east-1"
    # Optional:
    export AWS_SESSION_TOKEN="..."
    export AWS_PROFILE="your-profile"
    # Optional (Bedrock API key/bearer token):
    export AWS_BEARER_TOKEN_BEDROCK="..."
    ```
  </Step>
  <Step title="将 Bedrock 提供商和模型添加到你的配置">
    不需要 `apiKey`。使用 `auth: "aws-sdk"` 配置提供商：

    ```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 提供商，用于模型发现，无需额外配置。
</Tip>

<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 密钥。
  </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>

```json5
{
  plugins: {
    entries: {
      "amazon-bedrock": {
        config: {
          discovery: {
            enabled: true,
            region: "us-east-1",
            providerFilter: ["anthropic", "amazon"],
            refreshInterval: 3600,
            defaultContextWindow: 32000,
            defaultMaxTokens: 4096,
          },
        },
      },
    },
  },
}
```

| 选项 | 默认值 | 说明 |
| ------ | ------- | ----------- |
| `enabled` | auto | 在 auto 模式下，OpenClaw 只有在看到受支持的 AWS 环境变量标记时，才会启用隐式 Bedrock 提供商。设为 `true` 可强制设备发现。 |
| `region` | `AWS_REGION` / `AWS_DEFAULT_REGION` / `us-east-1` | 用于设备发现 API 调用的 AWS 区域。 |
| `providerFilter` | (all) | 匹配 Bedrock 提供商名称（例如 `anthropic`、`amazon`）。 |
| `refreshInterval` | `3600` | 缓存时长，单位为秒。设为 `0` 可禁用缓存。 |
| `defaultContextWindow` | `32000` | 用于已发现模型的上下文窗口（如果你知道模型限制，可覆盖）。 |
| `defaultMaxTokens` | `4096` | 用于已发现模型的最大输出 token 数（如果你知道模型限制，可覆盖）。 |

# 1. Create IAM role and instance profile
aws iam create-role --role-name EC2-Bedrock-Access \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ec2.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

aws iam attach-role-policy --role-name EC2-Bedrock-Access \
  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess

aws iam create-instance-profile --instance-profile-name EC2-Bedrock-Access
aws iam add-role-to-instance-profile \
  --instance-profile-name EC2-Bedrock-Access \
  --role-name EC2-Bedrock-Access

# 2. Attach to your EC2 instance
aws ec2 associate-iam-instance-profile \
  --instance-id i-xxxxx \
  --iam-instance-profile Name=EC2-Bedrock-Access

# 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. 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. Verify models are discovered
openclaw models list

推理配置文件 ID 的形式类似于 `us.anthropic.claude-opus-4-6-v1:0`（区域）或 `anthropic.claude-opus-4-6-v1:0`（全局）。如果其背后的模型已经在发现结果中，该配置文件会继承其完整能力集；否则会应用安全默认值。

不需要额外配置。只要已启用发现，并且 IAM 主体拥有 `bedrock:ListInferenceProfiles`，配置文件就会与基础模型一起出现在 `openclaw models list` 中。

| 层级 | 描述 |
|------|-------------|
| `default` | 标准 Bedrock 层级 |
| `flex` | 为可容忍更长延迟的工作负载提供折扣处理 |
| `priority` | 为延迟敏感型工作负载提供优先处理 |
| `reserved` | 为稳态工作负载提供预留容量 |

通过 `agents.defaults.params` 为 Bedrock 模型请求设置 `serviceTier`（或 `service_tier`），或在 `agents.defaults.models["<model-key>"].params` 中按模型设置：

```json5
{
  agents: {
    defaults: {
      params: {
        serviceTier: "flex", // applies to all models
      },
      models: {
        "amazon-bedrock/mistral.mistral-large-3-675b-instruct": {
          params: {
            serviceTier: "priority", // per-model override
          },
        },
      },
    },
  },
}
```

有效值为 `default`、`flex`、`priority` 和 `reserved`。并非所有模型都支持所有层级。如果请求了不受支持的层级，Bedrock 会返回验证错误。注意：该错误消息有些误导；它可能会说“The provided model identifier is invalid”，而不是指出服务层级不受支持。如果你看到此错误，请检查该模型是否支持所请求的层级。

```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` | 否 | 调试时使用 `"enabled"` 或 `"enabled_full"`；生产环境中省略或设为 `"disabled"`。 |

<Warning>
Gateway 网关使用的 IAM 主体除了标准调用权限外，还必须拥有 `bedrock:ApplyGuardrail` 权限。
</Warning>

```json5
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0", // default
      },
    },
  },
}
```

Bedrock 嵌入使用与推理相同的 AWS SDK 凭证链（实例
角色、SSO、访问密钥、共享配置和 Web 身份）。不需要 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)。

你的应用 → claude-max-api-proxy → Claude Code CLI → Anthropic（通过订阅）
     （OpenAI 格式）              （转换格式）      （使用你的登录）

```bash
npm install -g claude-max-api-proxy

# Verify Claude CLI is authenticated
claude --version
```

# List models
curl http://localhost:3456/v1/models

# Chat completion
curl http://localhost:3456/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

```json5
{
  env: {
    OPENAI_API_KEY: "not-needed",
    OPENAI_BASE_URL: "http://localhost:3456/v1",
  },
  agents: {
    defaults: {
      model: { primary: "openai/claude-opus-4" },
    },
  },
}
```

- 不适用原生仅限 OpenAI 的请求塑形
- 不支持 `service_tier`、不支持 Responses `store`、不支持提示缓存提示，也不支持
  OpenAI 推理兼容负载塑形
- 不会在该代理 URL 上注入隐藏的 OpenClaw 归属 headers（`originator`、`version`、`User-Agent`）

```bash
cat > ~/Library/LaunchAgents/com.claude-max-api.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.claude-max-api</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/node</string>
    <string>/usr/local/lib/node_modules/claude-max-api-proxy/dist/server/standalone.js</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/usr/local/bin:/opt/homebrew/bin:~/.local/bin:/usr/bin:/bin</string>
  </dict>
</dict>
</plist>
EOF

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
```

```
DEEPGRAM_API_KEY=dg_...
```

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "deepgram",
            providers: {
              deepgram: {
                apiKey: "${DEEPGRAM_API_KEY}",
                model: "nova-3",
                endpointingMs: 800,
                language: "en-US",
              },
            },
          },
        },
      },
    },
  },
}

<Steps>
  <Step title="运行登录命令">
    ```bash
    openclaw models auth login-github-copilot
    ```

    系统会提示你访问一个 URL 并输入一次性代码。保持
    终端打开，直到流程完成。
  </Step>
  <Step title="设置默认模型">
    ```bash
    openclaw models set github-copilot/claude-opus-4.7
    ```

    或在配置中：

    ```json5
    {
      agents: {
        defaults: { model: { primary: "github-copilot/claude-opus-4.7" } },
      },
    }
    ```
  </Step>
</Steps>

<Note>
当你已经在 VS Code 中运行 Copilot Proxy，或需要通过它进行路由时选择此项。
你必须启用该插件，并保持 VS Code 扩展运行。
</Note>

# Skip confirmation
openclaw models auth login-github-copilot --yes

# Login and set the default model in one step
openclaw models auth login --provider github-copilot --method device --set-default

openclaw onboard --non-interactive --accept-risk \
  --auth-choice github-copilot \
  --github-copilot-token "$COPILOT_GITHUB_TOKEN" \
  --skip-channels --skip-health

当设备发现被禁用、用户没有 GitHub 认证配置文件、token 交换
失败，或 `/models` HTTPS 调用出错时，内置静态目录会作为可见回退。
如需选择退出并完全依赖静态清单目录（离线 / 隔离网络场景）：

```json5
{
  plugins: {
    entries: {
      "github-copilot": {
        config: { discovery: { enabled: false } },
      },
    },
  },
}
```

| 优先级 | 变量              | 说明                            |
| -------- | --------------------- | -------------------------------- |
| 1        | `COPILOT_GITHUB_TOKEN` | 最高优先级，Copilot 专用 |
| 2        | `GH_TOKEN`            | GitHub CLI token（回退）      |
| 3        | `GITHUB_TOKEN`        | 标准 GitHub token（最低）   |

当设置了多个变量时，OpenClaw 会使用优先级最高的那个。
设备登录流程（`openclaw models auth login-github-copilot`）会将
其 token 存储在认证配置文件存储中，并优先于所有环境
变量。

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "github-copilot",
        // Optional: override the auto-discovered model
        model: "text-embedding-3-small",
      },
    },
  },
}

<Steps>
  <Step title="Choose your endpoint region">
    | 凭证选择               | 端点                           | 地区          |
    | ---------------------- | ------------------------------ | ------------- |
    | `moonshot-api-key`     | `https://api.moonshot.ai/v1`   | 国际版        |
    | `moonshot-api-key-cn`  | `https://api.moonshot.cn/v1`   | 中国          |
  </Step>
  <Step title="Run onboarding">
    ```bash
    openclaw onboard --auth-choice moonshot-api-key
    ```

    或者使用中国端点：

    ```bash
    openclaw onboard --auth-choice moonshot-api-key-cn
    ```
  </Step>
  <Step title="Set a default model">
    ```json5
    {
      agents: {
        defaults: {
          model: { primary: "moonshot/kimi-k2.6" },
        },
      },
    }
    ```
  </Step>
  <Step title="Verify models are available">
    ```bash
    openclaw models list --provider moonshot
    ```
  </Step>
  <Step title="Run a live smoke test">
    当你想验证模型访问和成本跟踪，同时不影响你的常规会话时，
    使用隔离的状态目录：

    ```bash
    OPENCLAW_CONFIG_PATH=/tmp/openclaw-kimi/openclaw.json \
    OPENCLAW_STATE_DIR=/tmp/openclaw-kimi \
    openclaw agent --local \
      --session-id live-kimi-cost \
      --message 'Reply exactly: KIMI_LIVE_OK' \
      --thinking off \
      --json
    ```

    JSON 响应应报告 `provider: "moonshot"` 和
    `model: "kimi-k2.6"`。当 Moonshot 返回使用量元数据时，
    assistant 转录条目会在 `usage.cost` 下存储规范化的
    token 使用量以及估算成本。
  </Step>
</Steps>

### 配置示例

```json5
{
  env: { MOONSHOT_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "moonshot/kimi-k2.6" },
      models: {
        // moonshot-kimi-k2-aliases:start
        "moonshot/kimi-k2.6": { alias: "Kimi K2.6" },
        "moonshot/kimi-k2.5": { alias: "Kimi K2.5" },
        "moonshot/kimi-k2-thinking": { alias: "Kimi K2 Thinking" },
        "moonshot/kimi-k2-thinking-turbo": { alias: "Kimi K2 Thinking Turbo" },
        "moonshot/kimi-k2-turbo": { alias: "Kimi K2 Turbo" },
        // moonshot-kimi-k2-aliases:end
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          // moonshot-kimi-k2-models:start
          {
            id: "kimi-k2.6",
            name: "Kimi K2.6",
            reasoning: false,
            input: ["text", "image"],
            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 262144,
          },
          {
            id: "kimi-k2.5",
            name: "Kimi K2.5",
            reasoning: false,
            input: ["text", "image"],
            cost: { input: 0.6, output: 3, cacheRead: 0.1, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 262144,
          },
          {
            id: "kimi-k2-thinking",
            name: "Kimi K2 Thinking",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 262144,
          },
          {
            id: "kimi-k2-thinking-turbo",
            name: "Kimi K2 Thinking Turbo",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 262144,
          },
          {
            id: "kimi-k2-turbo",
            name: "Kimi K2 Turbo",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 256000,
            maxTokens: 16384,
          },
          // moonshot-kimi-k2-models:end
        ],
      },
    },
  },
}
```

<Note>
Kimi Coding 使用不同于 Moonshot（`moonshot/...`）的 API 密钥和提供商前缀（`kimi/...`）。稳定的 API 模型引用是 `kimi/kimi-for-coding`；旧版引用 `kimi/kimi-code` 和 `kimi/k2p5` 仍可接受，并会规范化为该 API 模型 ID。
</Note>

<Steps>
  <Step title="Run onboarding">
    ```bash
    openclaw onboard --auth-choice kimi-code-api-key
    ```
  </Step>
  <Step title="Set a default model">
    ```json5
    {
      agents: {
        defaults: {
          model: { primary: "kimi/kimi-for-coding" },
        },
      },
    }
    ```
  </Step>
  <Step title="Verify the model is available">
    ```bash
    openclaw models list --provider kimi
    ```
  </Step>
</Steps>

### 配置示例

```json5
{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi/kimi-for-coding" },
      models: {
        "kimi/kimi-for-coding": { alias: "Kimi" },
      },
    },
  },
}
```

在 Web 搜索部分选择 **Kimi**，以存储
`plugins.entries.moonshot.config.webSearch.*`。

| 设置                | 选项                                                                 |
| ------------------- | -------------------------------------------------------------------- |
| API 区域            | `https://api.moonshot.ai/v1`（国际版）或 `https://api.moonshot.cn/v1`（中国） |
| Web 搜索模型        | 默认为 `kimi-k2.6`                                                   |

{
  plugins: {
    entries: {
      moonshot: {
        config: {
          webSearch: {
            apiKey: "sk-...", // or use KIMI_API_KEY / MOONSHOT_API_KEY
            baseUrl: "https://api.moonshot.ai/v1",
            model: "kimi-k2.6",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "kimi",
      },
    },
  },
}

- `thinking: { type: "enabled" }`
- `thinking: { type: "disabled" }`

通过 `agents.defaults.models.<provider/model>.params` 按模型配置：

```json5
{
  agents: {
    defaults: {
      models: {
        "moonshot/kimi-k2.6": {
          params: {
            thinking: { type: "disabled" },
          },
        },
      },
    },
  },
}
```

OpenClaw 还会为 Moonshot 映射运行时 `/think` 级别：

| `/think` 级别       | Moonshot 行为          |
| -------------------- | -------------------------- |
| `/think off`         | `thinking.type=disabled`   |
| 任何非 off 级别    | `thinking.type=enabled`    |

<Warning>
启用 Moonshot 思考时，`tool_choice` 必须为 `auto` 或 `none`。为保持兼容性，OpenClaw 会将不兼容的 `tool_choice` 值规范化为 `auto`。
</Warning>

Kimi K2.6 还接受可选的 `thinking.keep` 字段，用于控制
`reasoning_content` 的多轮保留。将其设置为 `"all"` 可在轮次之间保留完整
推理；省略它（或将其保留为 `null`）则使用服务器
默认策略。OpenClaw 只会为
`moonshot/kimi-k2.6` 转发 `thinking.keep`，并会从其他模型中移除它。

```json5
{
  agents: {
    defaults: {
      models: {
        "moonshot/kimi-k2.6": {
          params: {
            thinking: { type: "enabled", keep: "all" },
          },
        },
      },
    },
  },
}
```

若要在自定义 OpenAI 兼容提供商上强制严格清理，请设置 `sanitizeToolCallIds: true`：

```json5
{
  models: {
    providers: {
      "my-kimi-proxy": {
        api: "openai-completions",
        sanitizeToolCallIds: true,
      },
    },
  },
}
```

使用内置 K2.6 定价时，包含输入、输出
和缓存读取 token 的流式用量也会转换为本地估算的美元费用，用于
`/status`、`/usage full`、`/usage cost`，以及基于转录记录的会话
计费。

- Kimi Web 搜索使用 `KIMI_API_KEY` 或 `MOONSHOT_API_KEY`，并默认使用 `https://api.moonshot.ai/v1` 和模型 `kimi-k2.6`。
- 如有需要，可在 `models.providers` 中覆盖定价和上下文元数据。
- 如果 Moonshot 为某个模型发布了不同的上下文限制，请相应调整 `contextWindow`。

<Tabs>
  <Tab title="International">
    <Steps>
      <Step title="Run onboarding">
        ```bash
        openclaw onboard --auth-choice minimax-global-oauth
        ```

        这会针对 `api.minimax.io` 进行身份验证。
      </Step>
      <Step title="Verify the model is available">
        ```bash
        openclaw models list --provider minimax-portal
        ```
      </Step>
    </Steps>
  </Tab>
  <Tab title="China">
    <Steps>
      <Step title="Run onboarding">
        ```bash
        openclaw onboard --auth-choice minimax-cn-oauth
        ```

        这会针对 `api.minimaxi.com` 进行身份验证。
      </Step>
      <Step title="Verify the model is available">
        ```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>

<Tabs>
  <Tab title="International">
    <Steps>
      <Step title="Run onboarding">
        ```bash
        openclaw onboard --auth-choice minimax-global-api
        ```

        这会将 `api.minimax.io` 配置为基础 URL。
      </Step>
      <Step title="Verify the model is available">
        ```bash
        openclaw models list --provider minimax
        ```
      </Step>
    </Steps>
  </Tab>
  <Tab title="China">
    <Steps>
      <Step title="Run onboarding">
        ```bash
        openclaw onboard --auth-choice minimax-cn-api
        ```

        这会将 `api.minimaxi.com` 配置为基础 URL。
      </Step>
      <Step title="Verify the model is available">
        ```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"],
            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"],
            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 风格的增量块发出 `reasoning_content`，而不是原生 Anthropic thinking blocks；如果隐式保持启用，可能会把内部推理泄露到可见输出中。
</Warning>

<Note>
API key 设置使用 `minimax` 提供商 ID。模型引用遵循 `minimax/MiniMax-M2.7` 格式。
</Note>

| 身份验证选项 | 说明 |
| --- | --- |
| `minimax-global-oauth` | 国际 OAuth（Coding Plan） |
| `minimax-cn-oauth` | 中国 OAuth（Coding Plan） |
| `minimax-global-api` | 国际 API key |
| `minimax-cn-api` | 中国 API key |

{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "minimax/image-01" },
    },
  },
}

{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "minimax/music-2.6",
      },
    },
  },
}

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "minimax/MiniMax-Hailuo-2.3",
      },
    },
  },
}

这会防止 MiniMax 的流式端点在 OpenAI 风格的 delta 分块中发出 `reasoning_content`，从而避免内部推理泄露到可见输出中。

```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"],
      },
    },
  },
}
```

- 升级到 **2026.1.12**（或从源码 `main` 运行），然后重启 gateway。
- 运行 `openclaw configure` 并选择一个 **MiniMax** 认证选项，或
- 手动添加匹配的 `models.providers.minimax` 或 `models.providers.minimax-portal` 块，或
- 设置 `MINIMAX_API_KEY`、`MINIMAX_OAUTH_TOKEN`，或 MiniMax auth profile，以便注入匹配的提供商。

请确保模型 id **区分大小写**：

- API-key 路径：`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
```

<Steps>
  <Step title="运行新手引导">
    ```bash
    openclaw onboard --auth-choice opencode-zen
    ```

    或者直接传入密钥：

    ```bash
    openclaw onboard --opencode-zen-api-key "$OPENCODE_API_KEY"
    ```
  </Step>
  <Step title="将 Zen 模型设为默认值">
    ```bash
    openclaw config set agents.defaults.model.primary "opencode/claude-opus-4-6"
    ```
  </Step>
  <Step title="验证模型可用">
    ```bash
    openclaw models list --provider opencode
    ```
  </Step>
</Steps>

<Steps>
  <Step title="运行新手引导">
    ```bash
    openclaw onboard --auth-choice opencode-go
    ```

    或者直接传入密钥：

    ```bash
    openclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
    ```
  </Step>
  <Step title="将 Go 模型设为默认值">
    ```bash
    openclaw config set agents.defaults.model.primary "opencode-go/kimi-k2.6"
    ```
  </Step>
  <Step title="验证模型可用">
    ```bash
    openclaw models list --provider opencode-go
    ```
  </Step>
</Steps>

{
  env: { OPENCODE_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
}

- provider 级密钥只会发送到该 provider 的 Ollama 主机。
- `agents.*.memorySearch.remote.apiKey` 只会发送到其远程嵌入主机。
- 纯 `OLLAMA_API_KEY` 环境变量值会被视为 Ollama Cloud 约定，默认不会发送到本地或自托管主机。

<Steps>
  <Step title="运行新手引导">
    ```bash
    openclaw onboard
    ```

    从 provider 列表中选择 **Ollama**。
  </Step>
  <Step title="选择你的模式">
    - **Cloud + Local** — 本地 Ollama 主机加上通过该主机路由的云模型
    - **Cloud only** — 通过 `https://ollama.com` 使用托管 Ollama 模型
    - **Local only** — 仅使用本地模型

  </Step>
  <Step title="选择模型">
    `Cloud only` 会提示输入 `OLLAMA_API_KEY` 并建议托管云端默认值。`Cloud + Local` 和 `Local only` 会要求提供 Ollama base URL，发现可用模型，并在所选本地模型尚不可用时自动拉取。若 Ollama 报告了已安装的 `:latest` 标签，例如 `gemma4:latest`，设置过程只会显示该已安装模型一次，而不会同时显示 `gemma4` 和 `gemma4:latest`，也不会再次拉取裸别名。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以获取云端访问权限。
  </Step>
  <Step title="验证模型可用">
    ```bash
    openclaw models list --provider ollama
    ```
  </Step>
</Steps>

### 非交互模式

```bash
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk
```

也可以指定自定义 base URL 或模型：

```bash
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk
```

<Steps>
  <Step title="选择云端或本地">
    - **Cloud + Local**：安装 Ollama，使用 `ollama signin` 登录，并通过该主机路由云端请求
    - **Cloud only**：使用带有 `OLLAMA_API_KEY` 的 `https://ollama.com`
    - **Local only**：从 [ollama.com/download](https://ollama.com/download) 安装 Ollama

  </Step>
  <Step title="拉取本地模型（仅本地）">
    ```bash
    ollama pull gemma4
    # or
    ollama pull gpt-oss:20b
    # or
    ollama pull llama3.3
    ```
  </Step>
  <Step title="为 OpenClaw 启用 Ollama">
    对于 `Cloud only`，使用你的真实 `OLLAMA_API_KEY`。对于由主机支持的设置，任何占位符值都可用：

    ```bash
    # Cloud
    export OLLAMA_API_KEY="your-ollama-api-key"

    # Local-only
    export OLLAMA_API_KEY="ollama-local"

    # Or configure in your config file
    openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"
    ```
  </Step>
  <Step title="检查并设置你的模型">
    ```bash
    openclaw models list
    openclaw models set ollama/gemma4
    ```

    或在配置中设置默认值：

    ```json5
    {
      agents: {
        defaults: {
          model: { primary: "ollama/gemma4" },
        },
      },
    }
    ```
  </Step>
</Steps>

在设置期间使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama base URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以获取云端访问权限。当主机已登录时，OpenClaw 还会建议托管云端默认值，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。

如果主机尚未登录，OpenClaw 会让设置保持为仅本地，直到你运行 `ollama signin`。

在设置期间使用 **Cloud only**。OpenClaw 会提示输入 `OLLAMA_API_KEY`，设置 `baseUrl: "https://ollama.com"`，并填充托管云模型列表。此路径**不**需要本地 Ollama 服务器或 `ollama signin`。

`openclaw onboard` 期间显示的云模型列表会从 `https://ollama.com/api/tags` 实时填充，上限为 500 条，因此选择器反映的是当前托管目录，而不是静态种子。如果 `ollama.com` 在设置时无法访问或未返回模型，OpenClaw 会回退到之前的硬编码建议，确保新手引导仍能完成。

OpenClaw 当前建议 `gemma4` 作为本地默认值。

# See what models are available
ollama list
openclaw models list

OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/llama3.2:latest \
    --prompt "Reply with exactly: pong" \
    --json

OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/qwen2.5vl:7b \
    --prompt "Describe this image in one sentence." \
    --file ./photo.jpg \
    --json

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
  pnpm test:live -- extensions/ollama/ollama.live.test.ts

ollama pull mistral

ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"

openclaw infer image describe \
  --file ./photo.jpg \
  --model ollama/qwen2.5vl:7b \
  --json

{
  agents: {
    defaults: {
      imageModel: {
        primary: "ollama/qwen2.5vl:7b",
      },
    },
  },
}

{
  models: {
    providers: {
      ollama: {
        models: [
          {
            id: "qwen2.5vl:7b",
            name: "qwen2.5vl:7b",
            input: ["text", "image"],
            params: { num_ctx: 2048, keep_alive: "1m" },
          },
        ],
      },
    },
  },
  tools: {
    media: {
      image: {
        timeoutSeconds: 180,
        models: [{ provider: "ollama", model: "qwen2.5vl:7b", timeoutSeconds: 300 }],
      },
    },
  },
}

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
  pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.ts

{
  id: "qwen2.5vl:7b",
  name: "qwen2.5vl:7b",
  input: ["text", "image"],
  contextWindow: 128000,
  maxTokens: 8192,
}

```bash
export OLLAMA_API_KEY="ollama-local"
```

<Tip>
如果设置了 `OLLAMA_API_KEY`，你可以在提供商条目中省略 `apiKey`，OpenClaw 会为可用性检查填充它。
</Tip>

```json5
{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [
          {
            id: "kimi-k2.5:cloud",
            name: "kimi-k2.5:cloud",
            reasoning: false,
            input: ["text", "image"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}
```

```json5
{
  models: {
    providers: {
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://ollama-host:11434", // No /v1 - use native Ollama API URL
        api: "ollama", // Set explicitly to guarantee native tool-calling behavior
        timeoutSeconds: 300, // Optional: give cold local models longer to connect and stream
        models: [
          {
            id: "qwen3:32b",
            name: "qwen3:32b",
            params: {
              keep_alive: "15m", // Optional: keep the model loaded between turns
            },
          },
        ],
      },
    },
  },
}
```

<Warning>
不要向 URL 添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用不可靠。请使用不带路径后缀的基础 Ollama URL。
</Warning>

```bash
ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4
```

此路径会让配置保持最小化。除非你想手动定义模型，否则不要添加 `models.providers.ollama` 块。

```json5
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            reasoning: true,
            input: ["text"],
            params: {
              num_ctx: 32768,
              thinking: false,
              keep_alive: "15m",
            },
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "ollama/qwen3.5:9b" },
    },
  },
}
```

`contextWindow` 是 OpenClaw 侧的上下文预算。`params.num_ctx` 会随请求发送给 Ollama。当你的硬件无法运行模型完整声明的上下文时，请保持二者一致。

```bash
export OLLAMA_API_KEY="your-ollama-api-key"
```

```json5
{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [
          {
            id: "kimi-k2.5:cloud",
            name: "kimi-k2.5:cloud",
            reasoning: false,
            input: ["text", "image"],
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "ollama/kimi-k2.5:cloud" },
    },
  },
}
```

```bash
ollama signin
ollama pull gemma4
```

```json5
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        models: [
          { id: "gemma4", name: "gemma4", input: ["text"] },
          { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama/gemma4",
        fallbacks: ["ollama/kimi-k2.5:cloud"],
      },
    },
  },
}
```

```json5
{
  models: {
    providers: {
      "ollama-fast": {
        baseUrl: "http://mini.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        contextWindow: 32768,
        models: [{ id: "gemma4", name: "gemma4", input: ["text"] }],
      },
      "ollama-large": {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 420,
        contextWindow: 131072,
        maxTokens: 16384,
        models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama-fast/gemma4",
        fallbacks: ["ollama-large/qwen3.5:27b"],
      },
    },
  },
}
```

当 OpenClaw 发送请求时，会剥离活动提供商前缀，因此 `ollama-large/qwen3.5:27b` 会以 `qwen3.5:27b` 到达 Ollama。

```json5
{
  agents: {
    defaults: {
      experimental: {
        localModelLean: true,
      },
      model: { primary: "ollama/gemma4" },
    },
  },
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        contextWindow: 32768,
        models: [
          {
            id: "gemma4",
            name: "gemma4",
            input: ["text"],
            params: { num_ctx: 32768 },
            compat: { supportsTools: false },
          },
        ],
      },
    },
  },
}
```

仅当模型或服务器在工具 schema 上会可靠失败时，才使用 `compat.supportsTools: false`。它会用智能体能力换取稳定性。
`localModelLean` 会从智能体表面移除浏览器、cron 和消息工具，但它不会改变 Ollama 的运行时上下文或思考模式。对于会循环或把响应预算花在隐藏推理上的小型 Qwen 风格思考模型，请将它与显式的 `params.num_ctx` 和 `params.thinking: false` 搭配使用。

{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}

{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}

# Ollama daemon visible to this machine
curl http://127.0.0.1:11434/api/tags

# OpenClaw catalog and selected model
openclaw models list --provider ollama
openclaw models status

# Direct model smoke
openclaw infer model run \
  --model ollama/gemma4 \
  --prompt "Reply with exactly: ok"

{
  tools: {
    web: {
      search: {
        provider: "ollama",
      },
    },
  },
}

{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [{ id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text"] }],
      },
    },
  },
  tools: {
    web: {
      search: { provider: "ollama" },
    },
  },
}

如果你需要改用 OpenAI 兼容端点（例如在只支持 OpenAI 格式的代理后面），请显式设置 `api: "openai-completions"`：

```json5
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: true, // default: true
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}
```

此模式可能无法同时支持流式传输和工具调用。你可能需要在模型配置中用 `params: { streaming: false }` 禁用流式传输。

当 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: [...]
      }
    }
  }
}
```

你可以为该 Ollama 提供商下的每个模型设置提供商级别的 `contextWindow`、`contextTokens` 和 `maxTokens` 默认值，然后在需要时按模型覆盖它们。`contextWindow` 是 OpenClaw 的提示词和压缩预算。原生 Ollama 请求会保持 `options.num_ctx` 未设置，除非你显式配置 `params.num_ctx`，因此 Ollama 可以应用自己的模型、`OLLAMA_CONTEXT_LENGTH` 或基于 VRAM 的默认值。要在不重建 Modelfile 的情况下限制或强制 Ollama 的每请求运行时上下文，请设置 `params.num_ctx`；无效、零、负数和非有限值会被忽略。OpenAI 兼容的 Ollama 适配器仍会默认根据已配置的 `params.num_ctx` 或 `contextWindow` 注入 `options.num_ctx`；如果你的上游拒绝 `options`，请用 `injectNumCtxForOpenAICompat: false` 禁用它。

原生 Ollama 模型条目还接受 `params` 下的常见 Ollama 运行时选项，包括 `temperature`、`top_p`、`top_k`、`min_p`、`num_predict`、`stop`、`repeat_penalty`、`num_batch`、`num_thread` 和 `use_mmap`。OpenClaw 只转发 Ollama 请求键，因此不会把 OpenClaw 运行时参数（如 `streaming`）泄漏给 Ollama。使用 `params.think` 或 `params.thinking` 发送顶层 Ollama `think`；`false` 会为 Qwen 风格的思考模型禁用 API 级别思考。

```json5
{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        models: [
          {
            id: "llama3.3",
            contextWindow: 131072,
            maxTokens: 65536,
            params: {
              num_ctx: 32768,
              temperature: 0.7,
              top_p: 0.9,
              thinking: false,
            },
          }
        ]
      }
    }
  }
}
```

按模型设置的 `agents.defaults.models["ollama/<model>"].params.num_ctx` 也可用。如果两者都已配置，显式提供商模型条目优先于智能体默认值。

```bash
openclaw agent --model ollama/gemma4 --thinking off
openclaw agent --model ollama/gemma4 --thinking low
```

你也可以设置模型默认值：

```json5
{
  agents: {
    defaults: {
      models: {
        "ollama/gemma4": {
          thinking: "low",
        },
      },
    },
  },
}
```

按模型设置的 `params.think` 或 `params.thinking` 可以为特定已配置模型禁用或强制 Ollama API 思考。当活动运行只有隐式默认 `off` 时，OpenClaw 会保留这些显式模型参数；非 off 运行时命令（如 `/think medium`）仍会覆盖活动运行。

```bash
ollama pull deepseek-r1:32b
```

不需要额外配置。OpenClaw 会自动标记它们。

| 属性 | 值 |
| ------------- | ------------------- |
| 默认模型 | `nomic-embed-text`  |
| 自动拉取 | 是 — 如果本地不存在该嵌入模型，会自动拉取 |

查询时嵌入会为需要或推荐检索前缀的模型使用检索前缀，包括 `nomic-embed-text`、`qwen3-embedding` 和 `mxbai-embed-large`。记忆文档批次保持原始格式，因此现有索引不需要格式迁移。

要选择 Ollama 作为记忆搜索嵌入提供商：

```json5
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        remote: {
          // Default for Ollama. Raise on larger hosts if reindexing is too slow.
          nonBatchConcurrency: 1,
        },
      },
    },
  },
}
```

对于远程嵌入主机，请将凭证限定在该主机范围内：

```json5
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        model: "nomic-embed-text",
        remote: {
          baseUrl: "http://gpu-box.local:11434",
          apiKey: "ollama-local",
          nonBatchConcurrency: 2,
        },
      },
    },
  },
}
```

对于原生 `/api/chat` 请求，OpenClaw 还会将思考控制直接转发给 Ollama：`/think off` 和 `openclaw agent --thinking off` 会发送顶层 `think: false`，除非配置了显式的模型 `params.think`/`params.thinking` 值；而 `/think low|medium|high` 会发送匹配的顶层 `think` 强度字符串。`/think max` 会映射到 Ollama 的最高原生强度，即 `think: "high"`。

<Tip>
如果你需要使用 OpenAI 兼容端点，请参见上面的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。
</Tip>

常见证据：

- Windows 侧反复出现 WSL2 重启或终止
- WSL2 启动后不久，`app.slice` 或 `ollama.service` 中 CPU 占用较高
- 来自 systemd 的 SIGTERM，而不是 Linux OOM-killer 事件

当 OpenClaw 检测到 WSL2、启用了带有 `Restart=always` 的 `ollama.service`，并且可见 CUDA 标记时，会记录启动警告。

缓解措施：

```bash
sudo systemctl disable ollama
```

在 Windows 侧将以下内容添加到 `%USERPROFILE%\.wslconfig`，然后运行 `wsl --shutdown`：

```ini
[experimental]
autoMemoryReclaim=disabled
```

在 Ollama 服务环境中设置更短的 keep-alive，或者只在需要时手动启动 Ollama：

```bash
export OLLAMA_KEEP_ALIVE=5m
ollama serve
```

参见 [ollama/ollama#11317](https://github.com/ollama/ollama/issues/11317)。

```bash
ollama serve
```

验证 API 是否可访问：

```bash
curl http://localhost:11434/api/tags
```

```bash
ollama list  # 查看已安装内容
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # 或另一个模型
```

```bash
# 检查 Ollama 是否正在运行
ps aux | grep ollama

# 或重启 Ollama
ollama serve
```

```bash
openclaw gateway status --deep
curl http://ollama-host:11434/api/tags
```

常见原因：

- `baseUrl` 指向 `localhost`，但 Gateway 网关在 Docker 中或另一台主机上运行。
- URL 使用 `/v1`，这会选择 OpenAI 兼容行为，而不是原生 Ollama。
- 远程主机需要在 Ollama 侧更改防火墙或 LAN 绑定。
- 模型存在于你的笔记本电脑守护进程上，但不在远程守护进程上。

优先使用原生 Ollama 模式：

```json5
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434",
        api: "ollama",
      },
    },
  },
}
```

如果小型本地模型在工具架构上仍然失败，请在该模型条目上设置 `compat.supportsTools: false`，然后重新测试。

如果反复发生，请捕获原始模型名称、当前会话文件，以及本次运行使用的是 `Cloud + Local` 还是 `Cloud only`，然后尝试一个新的会话和一个回退模型：

```bash
openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --json
openclaw models set ollama/gemma4
```

```json5
{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}
```

如果主机本身接受连接很慢，`timeoutSeconds` 也会延长此提供商受保护的 Undici 连接超时。

```json5
{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            params: { num_ctx: 32768, thinking: false },
          },
        ],
      },
    },
  },
}
```

如果 OpenClaw 发送了过多提示词，请先降低 `contextWindow`。如果 Ollama 正在加载对这台机器来说过大的运行时上下文，请降低 `params.num_ctx`。如果生成运行时间过长，请降低 `maxTokens`。