OpenClaw 接入 Mistral 模型与 Voxtral 语音转写：从 API 密钥到流式 STT 的完整配置指南

OpenClaw 接入 Mistral 模型与 Voxtral 语音转写：从 API 密钥到流式 STT 的完整配置指南

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

OpenClaw 通过官方插件@openclaw/mistral-provider将 Mistral 的模型能力接入 Agent 运行时：既可作为 OpenAI 兼容的 Chat Completions 提供方，也可承担 Voxtral 批量音频转写、Voice Call 实时流式 STT 以及mistral-embed记忆向量化四条核心管线。本文以 docs/providers/mistral.md 为主线，结合 extensions/mistral 插件的实际源码，逐步讲解从安装、onboarding、模型选型到语音与记忆配置的完整链路，读完即可在 OpenClaw 中落地 Mistral 全家桶。

一、插件总览：一个插件，四个契约

mistral是 OpenClaw 的官方外部提供方插件，其核心元数据定义在 extensions/mistral/openclaw.plugin.json 中：enabledByDefault为true，类别为models，并通过contracts字段同时注册了 embedding、media understanding 与 realtime transcription 三类能力契约。从整体看，它向 OpenClaw 运行时暴露了四条能力管线：

插件注册行为可在 extensions/mistral/index.ts 中直接看到：register(api)依次注册 embedding、media understanding、realtime transcription 三个提供方。插件的核心属性如下：

providerEndpoints声明该插件的公网端点为api.mistral.ai，setup.providers声明的环境变量即MISTRAL_API_KEY，providerAuthChoices则定义了名为mistral-api-key的 onboarding 认证选项，其 CLI 参数正是--mistral-api-key。Base URL 与默认模型常量由 extensions/mistral/model-definitions.ts 从插件清单中直接读取，保证文档、清单与运行时三处一致。

二、快速开始：安装、认证与首个模型

1. 安装插件并重启网关

openclaw plugins install @openclaw/mistral-provider openclaw gateway restart

安装完成后重启 Gateway，插件按onStartup: false的懒加载策略在需要时激活，注册的四个能力契约随即生效。

2. 创建 API 密钥

在 Mistral Console（console.mistral.ai）创建 API 密钥。该密钥是后续所有管线（对话、转写、实时 STT、embedding）的共用凭据，通过MISTRAL_API_KEY环境变量注入。

3. 运行 onboarding

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

或直接传入密钥：

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

onboarding 背后执行的是 extensions/mistral/onboard.ts 中定义的预设：将mistral/mistral-large-latest设为 primary 模型，解析出providerId: "mistral"、api: "openai-completions"、baseUrl为 Mistral 官方地址，并注册Mistral作为默认模型别名。

4. 在配置中设置默认模型

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

5. 验证模型可用

openclaw models list --provider mistral

三、内置 LLM 目录：模型矩阵与选型

插件的模型目录固化在 extensions/mistral/openclaw.plugin.json 中，并支持discovery.mistral: "refreshable"的实时发现模式。文档记录的模型矩阵如下：

从插件清单看，三个弃用模型（mistral-medium-2508、devstral-medium-latest）均带有"status": "deprecated"与"replacedBy": "mistral-medium-3-5"标记，选型时会被 OpenClaw 自动引导到替代模型。清单中还固化了各模型的成本信息（每百万 token 美元计价，input/output/cacheRead/cacheWrite 四档），例如mistral-large-latest为 0.5/1.5/0.05/0，mistral-small-latest为 0.15/0.6/0.015/0，mistral-medium-3-5为 1.5/7.5/0.15/0，codestral-latest为 0.3/0.9/0.03/0——这为按成本选择模型提供了直接依据。

在修改配置前，可浏览插件目录中的完整模型行（含隐藏/弃用项）：

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

无需启动 Gateway 即可冒烟测试某个模型：

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

从 extensions/mistral/api.ts 的传输补丁可以看出 Mistral 模型的底层行为：请求体使用max_tokens字段（而非 OpenAI 的max_completion_tokens），supportsStore: false、supportsPromptCacheKey: true（支持提示词缓存键），这与 Mistral API 的缓存计费模型相对应。另外 extensions/mistral/index.ts 还实现了上下文溢出错误的识别逻辑，当响应包含mistral ... input too long或token limit ... exceeded模式时，OpenClaw 会据此触发上下文溢出处理。

四、Voxtral 批量音频转写：媒体理解管线

Voxtral 是 Mistral 的音频模型家族，批量转写走 OpenClaw 的媒体理解（media understanding）管线。在tools.media下声明 Mistral 作为音频模型提供方：

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

实现层面，extensions/mistral/media-understanding-provider.ts 注册了capabilities: ["audio"]的提供方，defaultModels.audio为voxtral-mini-latest，autoPriority.audio为50，转写请求通过transcribeOpenAiCompatibleAudio发送到https://api.mistral.ai/v1的/v1/audio/transcriptions端点。也就是说，媒体理解路径默认使用/v1/audio/transcriptions，Mistral 的默认音频模型是voxtral-mini-latest；当你的 Agent 收到语音类附件时，OpenClaw 会按此配置将音频交给 Mistral 转成文本。

五、Voice Call 流式 STT：Voxtral Realtime

mistral插件同时将 Voxtral Realtime 注册为 Voice Call 的流式 STT 提供方，实现边说话边出字幕的低延迟转写。相关配置项如下：

示例配置：

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

从源码看，extensions/mistral/realtime-transcription-provider-factory.ts 中固化了全套默认值：WebSocket 地址wss://api.mistral.ai、模型voxtral-mini-transcribe-realtime-2602、采样率8000、编码pcm_mulaw、目标流式延迟800ms，另有连接超时10s、关闭超时5s、最大重连5次、重连间隔1s、发送队列上限2 MiB等健壮性参数。会话建立后，客户端通过input_audio.append（base64 音频帧）上送音频，收到session.created后回发session.update声明audio_format（编码 + 采样率），并持续消费transcription.text.delta（流式增量，用于输出实时字幕）、transcription.segment（完整句段）与transcription.done（收尾）三类事件；关闭时依次发送input_audio.flush与input_audio.end。

编码归一化逻辑（源码 L76-L106）接受mulaw/ulaw/g711_ulaw/pcm_mulaw等别名归一到pcm_mulaw，也支持pcm_s16le、pcm_s32le、pcm_f16le、pcm_f32le、pcm_alaw。需要特别留意的是：

OpenClaw 默认将 Mistral 实时 STT 配置为pcm_mulaw@ 8 kHz，这样 Voice Call 可以直接转发 Twilio 媒体帧。仅当上游流本身已是原始 PCM 时，才改用encoding: "pcm_s16le"并配套匹配的sampleRate。

这意味着默认组合专为 Twilio 电话媒体流优化，改动编码前必须先确认上游音频格式。该提供方还有autoSelectOrder: 45的自动选择优先级，且isConfigured会同时检查配置项与MISTRAL_API_KEY环境变量。

六、高级配置：推理强度、记忆向量化与端点

1. 可调推理（reasoning_effort）

mistral/mistral-small-latest、mistral/mistral-small-2603与mistral/mistral-medium-3-5支持在 Chat Completions API 上通过reasoning_effort调节推理强度：none最小化输出中的额外思考，high则在最终答案前呈现完整思考轨迹。OpenClaw 会把会话的 thinking 级别映射到 Mistral API：

该映射在 extensions/mistral/api.ts 中即为源码事实：MISTRAL_SMALL_LATEST_REASONING_EFFORT_MAP将 off/minimal 映射到none，其余全部映射到high；resolveMistralCompatPatch仅对上述三个模型开启supportsReasoningEffort。同时 extensions/mistral/index.ts 的resolveThinkingProfile只为这三个模型暴露off/high两档 thinking 级别，默认off。

警告：避免将 Medium 3.5 推理模式与temperature: 0组合使用。Mistral HTTP API 已被反馈在reasoning_effort="high"加temperature: 0时返回 400 错误。要么不设置 temperature，要么先关闭/调至 minimal thinking（使 OpenClaw 发送reasoning_effort: "none"）再设置低 temperature。

模型级作用域的 Medium 3.5 推理配置示例：

{ agents: { defaults: { model: { primary: "mistral/mistral-medium-3-5" }, models: { "mistral/mistral-medium-3-5": { params: { thinking: "high" }, }, }, }, }, }

注意：目录中其他 Mistral 模型不使用该参数。Mistral 原生的 Magistral 推理模型已弃用，应改用 Mistral Small 4 或 Mistral Medium 3.5 上的可调推理。

2. 记忆向量化：mistral-embed

Mistral 可通过/v1/embeddings为 OpenClaw 的记忆检索提供向量（默认模型mistral-embed）：

{ memory: { search: { provider: "mistral" }, }, }

实现上，extensions/mistral/embedding-provider.ts 以DEFAULT_MISTRAL_EMBEDDING_MODEL = "mistral-embed"创建远程 embedding 客户端，normalizeMistralModel支持剥离mistral/前缀并回退默认模型，错误信息统一以mistral embeddings failed为前缀；extensions/mistral/memory-embedding-adapter.ts 负责将其适配到 OpenClaw 记忆主机引擎。这样 Agent 的记忆检索向量即可完全托管给 Mistral。

3. 认证与 Base URL

• Mistral 认证使用MISTRAL_API_KEY，通过 Bearer header 传递（实时 STT 的 WebSocket 握手同样使用Authorization: Bearer <key>，见 realtime-transcription-provider-factory.ts）。
• 提供方 Base URL 默认为https://api.mistral.ai/v1，接受标准 OpenAI 兼容的 chat-completions 请求形态；实时 STT 的 WebSocket 默认端点则是wss://api.mistral.ai，且可通过MISTRAL_REALTIME_BASE_URL环境变量覆盖（源码 L108-L118 会自动把 http/https 归一为 ws/wss 并剔除/v1路径后缀）。
• Onboarding 默认模型为mistral/mistral-large-latest。
• 仅当 Mistral 明确发布你需要使用的区域端点时，才在models.providers.mistral.baseUrl下覆盖 Base URL。

七、相关文档

• 模型选择指南：提供方选择、模型引用格式与故障切换行为。
• 媒体理解节点：音频转写配置与提供方选择。
• 音频相关节点：OpenClaw 中音频能力的整体设计。

本文所有配置与默认值均以当前仓库的 docs/providers/mistral.md 与 extensions/mistral 插件源码为准，结合 api.test.ts、media-understanding-provider.test.ts、realtime-transcription-provider.test.ts 等测试文件可进一步验证各契约的边界行为。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw