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 转写设置以及常见问题。

属性	值
Provider id	mistral
插件类型	内置，默认启用
认证环境变量	MISTRAL_API_KEY
Onboarding 开关	--auth-choice mistral-api-key
直接 CLI 参数	--mistral-api-key <key>
API 兼容模式	OpenAI 兼容 (openai-completions)
Base URL	https://api.mistral.ai/v1
默认模型	mistral/mistral-large-latest
Embedding 模型	mistral-embed
Voxtral 批量转写	voxtral-mini-latest
Voxtral 实时转写	voxtral-mini-transcribe-realtime-2602

快速开始

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 模型（部分支持图像输入、函数调用、结构化输出等）：

Model ref	输入类型	Context	最大输出	备注
mistral/mistral-large-latest	text, image	262,144	16,384	默认模型
mistral/mistral-medium-2508	text, image	262,144	8,192	Mistral Medium 3.1
mistral/mistral-medium-3-5	text, image	262,144	8,192	Mistral Medium 3.5，支持可调推理
mistral/mistral-small-latest	text, image	128,000	16,384	Mistral Small 4，通过 API 调整推理努力
mistral/pixtral-large-latest	text, image	128,000	32,768	Pixtral
mistral/codestral-latest	text	256,000	4,096	编码模型
mistral/devstral-medium-latest	text	262,144	32,768	Devstral 2
mistral/magistral-small	text	128,000	40,000	支持推理优先

完成 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 提供者。配置字段如下：

设置	配置路径	默认值
API key	plugins.entries.voice-call.config.streaming.providers.mistral.apiKey	回退到 MISTRAL_API_KEY
模型	...mistral.model	voxtral-mini-transcribe-realtime-2602
编码	...mistral.encoding	pcm_mulaw
采样率	...mistral.sampleRate	8000
目标延迟	...mistral.targetStreamingDelayMs	800

示例配置（启用 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 推荐设置](https://huggingface.co/mistralai/Mistral-Medium-3.5-128B)使用 `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。