Mistral 插件在 OpenClaw 中注册了聊天补全、媒体理解（Voxtral 批量转写）、Voice Call 实时语音转写和记忆嵌入四种合约。配置时先获取 API Key，运行 openclaw onboard --auth-choice mistral-api-key 或直接传递密钥，设置默认模型后通过 openclaw models list --provider mistral 验证。默认模型 mistral/mistral-large-latest，Voxtral 批量转写使用 voxtral-mini-latest，实时 STT 使用 voxtral-mini-transcribe-realtime-2602。高级配置包括可调推理（reasoning_effort）和记忆嵌入（memorySearch.provider: "mistral"）。

Mistral 接入 OpenClaw：配置、模型列表与 Voxtral 音频转写 #

OpenClaw 内置了 Mistral 插件（enabledByDefault: true），注册了四个合约：聊天补全、媒体理解（Voxtral 批量转写）、Voice Call 实时语音转写（Voxtral Realtime）和记忆嵌入（mistral-embed）。本页说明配置步骤、内置模型目录、Voxtral 转写设置以及常见问题。

快速开始 #

1. 获取 API Key
   在 Mistral Console 创建 API Key。

2. 运行 onboarding

   openclaw onboard --auth-choice mistral-api-key

   或直接传入密钥：

   openclaw onboard --mistral-api-key "$MISTRAL_API_KEY"

3. 设置默认模型
   在配置中指定：

   {
     env: { MISTRAL_API_KEY: "sk-..." },
     agents: { defaults: { model: { primary: "mistral/mistral-large-latest" } } },
   }

4. 验证模型可用性

   openclaw models list --provider mistral

内置模型目录 #

OpenClaw 当前内置以下 Mistral 模型（部分支持图像输入、函数调用、结构化输出等）：

完成 onboarding 后，可不启动 Gateway 快速测试 Medium 3.5：

openclaw infer model run --local \
  --model mistral/mistral-medium-3-5 \
  --prompt "Reply with exactly: mistral-ok" \
  --json

查看完整内置模型目录：

openclaw models list --all --provider mistral --plain

音频转写（Voxtral） #

批量转写（媒体理解） #

在媒体理解管道中使用 Voxtral 进行批量音频转写：

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
      },
    },
  },
}

媒体转写路径为 /v1/audio/transcriptions。Mistral 的默认音频模型是 voxtral-mini-latest。

Voice Call 实时流式 STT #

Mistral 插件注册了 Voxtral Realtime 作为 Voice Call 流式 STT 提供者。配置字段如下：

示例配置（启用 Voxtral Realtime）：

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "mistral",
            providers: {
              mistral: {
                apiKey: "${MISTRAL_API_KEY}",
                targetStreamingDelayMs: 800,
              },
            },
          },
        },
      },
    },
  },
}

注意：OpenClaw 默认将 Mistral 实时 STT 编码设为 pcm_mulaw、采样率 8 kHz，以便 Voice Call 直接转发 Twilio 媒体帧。只有当上游流已经是原始 PCM 时，才使用 encoding: "pcm_s16le" 并匹配对应的 sampleRate。

高级配置 #

可调推理（Adjustable reasoning）

`mistral/mistral-small-latest`（Mistral Small 4）和 `mistral/mistral-medium-3-5` 支持通过 API 参数 `reasoning_effort` 调节推理强度（`none` 最小化额外思考，`high` 在最终答案前显示完整思考过程）。Mistral 建议 Medium 3.5 用于智能体和编码场景时设置 `reasoning_effort="high"`。

OpenClaw 将会话中的 **thinking** 级别映射到 Mistral 的 API：

| OpenClaw thinking 级别                          | Mistral `reasoning_effort` |
| ------------------------------------------------ | -------------------------- |
| **off** / **minimal**                            | `none`                     |
| **low** / **medium** / **high** / **xhigh** / **adaptive** / **max** | `high`     |

::: warning 不要在 Medium 3.5 推理模式下同时设置 temperature: 0。Mistral HTTP API 会因 reasoning_effort="high" 加 temperature: 0 返回 400 错误。要么不设置 temperature 让 Mistral 使用默认值，要么按照 Medium 3.5 推荐设置使用 temperature: 0.7。如果需要确定性回答，请关闭推理（off/minimal），这样 OpenClaw 会发送 reasoning_effort: "none"，然后才降低 temperature。 :::

示例：为 Medium 3.5 配置推理模式：
```json5
{
  agents: {
    defaults: {
      model: { primary: "mistral/mistral-medium-3-5" },
      models: {
        "mistral/mistral-medium-3-5": {
          params: { thinking: "high" },
        },
      },
    },
  },
}
```

::: info 其他内置 Mistral 目录模型不使用此参数。若需 Mistral 原生推理优先行为，请使用 magistral-* 模型。 :::

记忆嵌入（Memory embeddings）

Mistral 可通过 `/v1/embeddings` 提供记忆嵌入服务，默认模型 `mistral-embed`。启用记忆搜索：
```json5
{
  memorySearch: { provider: "mistral" },
}
```

认证与 Base URL

- Mistral 认证使用 `MISTRAL_API_KEY`（Bearer header）。
- 提供商 Base URL 默认为 `https://api.mistral.ai/v1`，接受标准 OpenAI 兼容的 chat-completions 请求格式。
- Onboarding 默认模型为 `mistral/mistral-large-latest`。
- 仅在 Mistral 明确发布需要使用的区域端点时，通过 `models.providers.mistral.baseUrl` 覆盖 Base URL。

相关文档 #

• 模型选择 – 选择提供商、模型引用和故障转移行为。
• 媒体理解 – 音频转写设置和提供商选择。

常见问题 #

为什么 openclaw onboard --auth-choice mistral-api-key 后模型还是不可用？ #

检查是否已设置 MISTRAL_API_KEY 环境变量，且配置文件中 agents.defaults.model.primary 正确指定了模型（如 mistral/mistral-large-latest）。运行 openclaw models list --provider mistral 查看已注册的 Mistral 模型。

Voxtral 实时转写（Voice Call）返回 400 错误怎么办？ #

确认 encoding 和 sampleRate 是否匹配 Twilio 或上游流的格式。默认 pcm_mulaw 和 8000 Hz 适用于 Twilio。如果使用其他来源，需改为 pcm_s16le 并设置正确的采样率。

Mistral Medium 3.5 推理模式加上 temperature: 0 报错？ #

这是 Mistral API 的限制：reasoning_effort="high" 不允许 temperature: 0。可将 temperature 留空或设为 0.7，或者关闭推理模式（thinking: off/minimal）再使用 temperature: 0。