
OpenClaw 接入 Mistral 模型与 Voxtral 语音转写从 API 密钥到流式 STT 的完整配置指南【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 通过官方插件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 运行时暴露了四条能力管线能力管线契约承载模型Chat Completionsopenai-completionsOpenAI 兼容mistral/mistral-large-latest默认媒体理解批量转写mediaUnderstandingProvidersvoxtral-mini-latestVoice Call 流式 STTrealtimeTranscriptionProvidersvoxtral-mini-transcribe-realtime-2602记忆向量化embeddingProvidersmistral-embed插件注册行为可在 extensions/mistral/index.ts 中直接看到register(api)依次注册 embedding、media understanding、realtime transcription 三个提供方。插件的核心属性如下属性值Provider idmistral插件openclaw/mistral-provider认证环境变量MISTRAL_API_KEYOnboarding 标记--auth-choice mistral-api-key直接 CLI 标记--mistral-api-key keyAPI 形态OpenAI 兼容openai-completionsBase URLhttps://api.mistral.ai/v1默认模型mistral/mistral-large-latestEmbedding 模型mistral-embedVoxtral 批量转写voxtral-mini-latestVoxtral 实时转写voxtral-mini-transcribe-realtime-2602providerEndpoints声明该插件的公网端点为api.mistral.aisetup.providers声明的环境变量即MISTRAL_API_KEYproviderAuthChoices则定义了名为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 Consoleconsole.mistral.ai创建 API 密钥。该密钥是后续所有管线对话、转写、实时 STT、embedding的共用凭据通过MISTRAL_API_KEY环境变量注入。3. 运行 onboardingopenclaw onboard --auth-choice mistral-api-key或直接传入密钥openclaw onboard --mistral-api-key $MISTRAL_API_KEYonboarding 背后执行的是 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的实时发现模式。文档记录的模型矩阵如下Model ref输入上下文最大输出说明mistral/mistral-large-latesttext, image262,14416,384默认模型Mistral Large 3mistral/mistral-medium-3-5text, image262,1448,192Mistral Medium 3.5支持可调推理mistral/mistral-small-latesttext, image262,14416,384Mistral Small 4 latest支持reasoning_effort可调mistral/mistral-small-2603text, image262,14416,384Mistral Small 4 固定版支持reasoning_effort可调mistral/codestral-latesttext128,0004,096编程专用mistral/mistral-medium-2508text, image128,0008,192已弃用隐藏改用 Medium 3.5mistral/devstral-medium-latesttext262,14432,768已弃用隐藏改用 Medium 3.5从插件清单看三个弃用模型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/0mistral-small-latest为 0.15/0.6/0.015/0mistral-medium-3-5为 1.5/7.5/0.15/0codestral-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_tokenssupportsStore: 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-latestautoPriority.audio为50转写请求通过transcribeOpenAiCompatibleAudio发送到https://api.mistral.ai/v1的/v1/audio/transcriptions端点。也就是说媒体理解路径默认使用/v1/audio/transcriptionsMistral 的默认音频模型是voxtral-mini-latest当你的 Agent 收到语音类附件时OpenClaw 会按此配置将音频交给 Mistral 转成文本。五、Voice Call 流式 STTVoxtral Realtimemistral插件同时将 Voxtral Realtime 注册为 Voice Call 的流式 STT 提供方实现边说话边出字幕的低延迟转写。相关配置项如下设置项配置路径默认值API keyplugins.entries.voice-call.config.streaming.providers.mistral.apiKey回退到MISTRAL_API_KEY模型...mistral.modelvoxtral-mini-transcribe-realtime-2602编码...mistral.encodingpcm_mulaw采样率...mistral.sampleRate8000目标流式延迟...mistral.targetStreamingDelayMs800示例配置{ 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.appendbase64 音频帧上送音频收到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_effortmistral/mistral-small-latest、mistral/mistral-small-2603与mistral/mistral-medium-3-5支持在 Chat Completions API 上通过reasoning_effort调节推理强度none最小化输出中的额外思考high则在最终答案前呈现完整思考轨迹。OpenClaw 会把会话的 thinking 级别映射到 Mistral APIOpenClaw thinking 级别Mistralreasoning_effortoff/minimalnonelow/medium/high/xhigh/adaptive/maxhigh该映射在 extensions/mistral/api.ts 中即为源码事实MISTRAL_SMALL_LATEST_REASONING_EFFORT_MAP将 off/minimal 映射到none其余全部映射到highresolveMistralCompatPatch仅对上述三个模型开启supportsReasoningEffort。同时 extensions/mistral/index.ts 的resolveThinkingProfile只为这三个模型暴露off/high两档 thinking 级别默认off。警告避免将 Medium 3.5 推理模式与temperature: 0组合使用。Mistral HTTP API 已被反馈在reasoning_efforthigh加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-embedMistral 可通过/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 URLMistral 认证使用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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考