#Model Configuration Reference

Use this page to look up every Midscene model setting. For supported model names, model families, and copyable setup examples, see Use a model API key. For model roles and combination guidance, see Model Selection Guide. For connection issues, logs, tracing, and call recording, see Model debugging and observability.

#Required settings

You need to set a default model for Midscene; see Model Selection Guide for details.

#Protocol type

Midscene uses OpenAI's Chat Completions protocol by default and also supports the Responses protocol. These are different ways to send requests to models; your use of the Midscene Agent API stays the same. Chat Completions was introduced earlier than Responses and currently has broader support.

Select the protocol through an environment variable: openai-chat (the default) or openai-responses. For example, to use Responses:

MIDSCENE_MODEL_PROTOCOL="openai-responses"

When configuring separate Planning, Locate or Insight models, use the corresponding environment variables. Each model can use a different protocol:

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

Keep in mind:

• Some models or providers may not yet support the Responses protocol. Check with your model provider before using it.
• Even the Chat Completions and Responses APIs from the same provider may use different Base URLs. Confirm the endpoint for each protocol with your provider.
• Midscene may not yet support some providers' Responses API implementations. Confirm compatibility with Midscene before using them.

#Advanced settings (optional)

For a dedicated Planning, Locate, or Insight model, use the corresponding MIDSCENE_PLANNING_MODEL_*, MIDSCENE_LOCATE_MODEL_*, or MIDSCENE_INSIGHT_MODEL_* settings. Streaming is also configured per model using STREAM_MODE with the corresponding prefix. A dedicated model defaults to non-stream and does not inherit the Default model’s streaming setting. Roles without a dedicated model use the complete Default configuration. An explicit per-call stream option takes precedence.

Note: Control replanning behavior with the agent option replanningCycleLimit (defaults to 20, or 40 for vlm-ui-tars), not with environment variables.

#Configure a dedicated Planning model

Set the following if the Planning intent needs a different model:

#Configure a dedicated Locate model

The Locate model handles aiLocate, target localization for actions such as tapping, input, scrolling and dragging, and independent localization and deepLocate within aiAct. Without MIDSCENE_LOCATE_MODEL_NAME, it uses the complete Default model configuration. Once selected, its endpoint, API key and other settings are independent: no per-field inheritance and no automatic fallback after a request fails.

Set the following if the Locate intent needs a different model:

#Configure a dedicated Insight model

Set the following if the Insight intent needs a different model:

#Model-native thinking

The thinking settings below apply to every model role. Use the MIDSCENE_MODEL_ prefix for the Default model, or MIDSCENE_PLANNING_MODEL_, MIDSCENE_LOCATE_MODEL_, and MIDSCENE_INSIGHT_MODEL_ for the corresponding role. Each prefix supports the REASONING_ENABLED, REASONING_EFFORT, and REASONING_BUDGET suffixes. Configure each model independently; support depends on the selected model and its family.

Midscene disables model-native thinking by default for better execution speed and stability. If a model cannot disable native thinking, Midscene reduces it as much as possible by controlling the thinking granularity or budget.

The following environment variables provide a unified Midscene abstraction over provider-specific parameters. The parameters sent to the model depend on MIDSCENE_MODEL_FAMILY.

MIDSCENE_MODEL_REASONING_ENABLED explicitly controls whether model-native thinking is enabled:

• false: Force-disable model-native thinking. This is the Midscene default.
• true: Force-enable model-native thinking.
• default: Follow the model's default behavior. Midscene does not send a parameter that enables or disables thinking, and it ignores explicit MIDSCENE_MODEL_REASONING_BUDGET and MIDSCENE_MODEL_REASONING_EFFORT settings.

The following model families currently support MIDSCENE_MODEL_REASONING_ENABLED:

• Qwen: Maps to enable_thinking.
• Doubao: Maps to thinking.type.
• DeepSeek: Maps to thinking.type.
• Zhipu GLM: Maps to thinking.type.
• GPT-5: Maps to reasoning_effort. Midscene uses medium when enabled and none when disabled.
• Gemini: Maps to thinking_config.thinking_level. Midscene uses medium when enabled and minimal when disabled.
• Kimi K2 series: Maps to thinking.type.
• Xiaomi MiMo: Maps to thinking.type.

MIDSCENE_MODEL_REASONING_BUDGET controls the thinking budget. Qwen currently supports this setting through thinking_budget.

MIDSCENE_MODEL_REASONING_EFFORT controls thinking effort. The following model families currently support it:

• Doubao: Maps to reasoning_effort.
• DeepSeek: Maps to reasoning_effort.
• Gemini: Maps to thinking_config.thinking_level.
• GPT-5: Maps to reasoning_effort.
• Kimi K3 series: Maps to reasoning_effort.

Provider support and accepted values vary. See each provider's official documentation for supported model versions and values. If the current model does not support an explicit setting, Midscene ignores it instead of guessing a provider-specific private parameter.

#Still-compatible configs (not recommended)

The following environment variables are deprecated but still compatible. We recommend migrating to the new configuration approach.

#Legacy model family configuration

#General configuration

#Debugging and observability settings

The following settings enable model diagnostics, tracing, and local call recording. See Model debugging and observability for installation steps, usage examples, troubleshooting, and security guidance.

#Debug logs

For supported DEBUG selectors and log behavior, see Runtime configuration: Debug logs.

#LangSmith

#Langfuse

#Model-call recording