#模型配置参考

本页汇总 Midscene 的全部模型配置。如需查看支持的模型名称、模型 family 和可复制的配置示例，请参考使用模型 API Key。如需了解模型职责和组合方式，请参考模型选择指南。如需排查连接问题、查看日志、采集 Trace 或记录调用，请参考模型调试与可观测性。

#必选配置

你需要为 Midscene 配上一个默认模型，详见 模型选择指南 文档。

#协议类型

Midscene 默认使用 OpenAI 的 Chat Completions 协议，同时也支持 Responses 协议。两者是向模型发送请求的不同方式，不影响 Midscene Agent API 的使用。Chat Completions 是 OpenAI 较早推出的协议，Responses 是后推出的协议，目前 Chat Completions 的支持范围更广。

通过环境变量选择协议：openai-chat（默认）或 openai-responses。例如，使用 Responses 协议：

MIDSCENE_MODEL_PROTOCOL="openai-responses"

为 Planning、Locate 或 Insight 单独配置模型时，使用对应的环境变量，各模型的协议可以分别设置：

MIDSCENE_PLANNING_MODEL_PROTOCOL="openai-responses"
MIDSCENE_LOCATE_MODEL_PROTOCOL="openai-responses"
MIDSCENE_INSIGHT_MODEL_PROTOCOL="openai-responses"

注意事项：

• 部分模型或供应商可能尚不支持 Responses 协议，使用前请向模型供应商确认支持情况。
• 即使是同一供应商提供的 Chat Completions 和 Responses API，也可能使用不同的 Base URL，请向模型供应商确认对应的接入地址。
• Midscene 对部分模型供应商的 Responses API 可能尚未完成适配，使用前请确认 Midscene 的兼容性支持。

#高阶配置（可选）

如果你为 Planning、Locate 或 Insight 配置了独立模型，请使用对应的 MIDSCENE_PLANNING_MODEL_*、MIDSCENE_LOCATE_MODEL_* 或 MIDSCENE_INSIGHT_MODEL_* 设置该模型的参数。流式模式也按模型独立配置，使用对应前缀的 STREAM_MODE。专用模型未设置时默认为 non-stream，不会继承默认模型的流式设置；未配置专用模型时，该职责使用完整的默认模型配置。单次调用显式指定的 stream 选项优先生效。

提示：通过 Agent 的 replanningCycleLimit 入参控制重规划次数（默认 20，vlm-ui-tars 为 40），不再使用环境变量。

#为 Planning 意图单独配置模型

如果你想为 Planning 意图单独配置模型，需额外配置以下字段：

#为 Locate 意图单独配置模型

定位模型负责 aiLocate、点击/输入/滚动/拖拽等动作中的目标定位，以及 aiAct 内的独立定位和 deepLocate。未配置 MIDSCENE_LOCATE_MODEL_NAME 时使用完整的默认模型配置；配置后，地址、API Key 和其他参数独立读取，不从默认模型逐字段继承，也不在调用失败后自动切换模型。

如果你想为 Locate 意图单独配置模型，需额外配置以下字段：

#为 Insight 意图单独配置模型

如果你想为 Insight 意图单独配置模型，需额外配置以下字段：

#模型原生思考

以下思考参数适用于所有模型职责。默认模型使用 MIDSCENE_MODEL_ 前缀；Planning、Locate 和 Insight 分别使用 MIDSCENE_PLANNING_MODEL_、MIDSCENE_LOCATE_MODEL_ 和 MIDSCENE_INSIGHT_MODEL_ 前缀，后缀均为 REASONING_ENABLED、REASONING_EFFORT 或 REASONING_BUDGET。各模型独立配置，实际支持情况取决于该模型及其 family。

Midscene 默认关闭模型原生思考，以获得更好的执行速度和稳定性。如果模型不支持关闭原生思考，Midscene 会通过控制思考粒度或限制思考额度，尽可能减少模型的原生思考。

以下环境变量是 Midscene 对不同模型服务商参数的统一抽象。实际发送给模型的参数由 MIDSCENE_MODEL_FAMILY 决定。

MIDSCENE_MODEL_REASONING_ENABLED 显式控制是否启用模型原生思考：

• false：强制关闭模型原生思考，也是 Midscene 的默认行为。
• true：强制启用模型原生思考。
• default：遵循模型的默认行为。Midscene 不发送启用或关闭思考的参数，并忽略显式配置的 MIDSCENE_MODEL_REASONING_BUDGET 和 MIDSCENE_MODEL_REASONING_EFFORT。

目前支持 MIDSCENE_MODEL_REASONING_ENABLED 的模型系列及参数映射如下：

• Qwen：对应 enable_thinking。
• 豆包：对应 thinking.type。
• DeepSeek：对应 thinking.type。
• 智谱 GLM：对应 thinking.type。
• GPT-5：对应 reasoning_effort。启用时使用 medium，关闭时使用 none。
• Gemini：对应 thinking_config.thinking_level。启用时使用 medium，关闭时使用 minimal。
• Kimi K2 系列：对应 thinking.type。
• 小米 MiMo：对应 thinking.type。

MIDSCENE_MODEL_REASONING_BUDGET 控制模型的思考额度。目前 Qwen 系列支持该配置，对应 thinking_budget。

MIDSCENE_MODEL_REASONING_EFFORT 控制模型的思考力度。目前支持以下模型系列：

• 豆包：对应 reasoning_effort。
• DeepSeek：对应 reasoning_effort。
• Gemini：对应 thinking_config.thinking_level。
• GPT-5：对应 reasoning_effort。
• Kimi K3 系列：对应 reasoning_effort。

不同模型服务商支持的参数和值不同。具体取值和适用模型版本请参考对应服务商的官方文档。如果当前模型不支持某项显式配置，Midscene 会忽略该配置，不会猜测服务商的私有参数。

#仍兼容的模型配置（不推荐）

以下环境变量已废弃但仍然兼容，建议尽快迁移到新的配置方式。

#旧版模型类型配置

#通用配置

#调试与可观测性配置

以下配置用于启用模型诊断、Tracing 和本地调用记录。安装步骤、使用示例、问题排查和安全说明。请参考模型调试与可观测性。

#Debug 日志

支持的 DEBUG 选择器和日志行为请参考运行时配置：Debug 日志。

#LangSmith

#Langfuse

#模型调用记录