• English

      • Model Configuration Reference

      Use this page to look up every Midscene model setting. For supported model names, model families, and copyable setup examples, see Supported models and setup. For model roles and combination guidance, see Model strategy. 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 strategy for details.

      NameDescription
      MIDSCENE_MODEL_API_KEYModel API key for OpenAI-compatible HTTP providers, e.g., "sk-abcd...". Not required when MIDSCENE_MODEL_BASE_URL="codex://app-server"; see Use Codex App Server
      MIDSCENE_MODEL_BASE_URLAPI endpoint URL, usually ending with a version (e.g., /v1); do not append /chat/completion here since the underlying sdk will add it automatically
      MIDSCENE_MODEL_NAMEModel name
      MIDSCENE_MODEL_FAMILYModel family, determine the way of dealing with the coordinates

      Advanced settings (optional)

      If you configure a dedicated Insight or Planning model, model-related MIDSCENE_MODEL_* settings in this section only take effect for the Insight or Planning intent when you configure the corresponding MIDSCENE_INSIGHT_MODEL_* or MIDSCENE_PLANNING_MODEL_* setting.

      NameDescription
      MIDSCENE_MODEL_TIMEOUTHard timeout for AI API calls in milliseconds (default intent). Defaults to 180000 (180s). Set to 0 to disable the hard timeout and let the request run indefinitely (only a caller-provided AbortSignal will cancel it). Note: Midscene controls the full request lifetime, not just the time until the first response header arrives, so stalled body reads can still be terminated cleanly
      MIDSCENE_MODEL_TEMPERATURESampling temperature for model responses
      MIDSCENE_MODEL_RETRY_COUNTNumber of retries when AI call fails, default 1 (i.e., retry once after failure). Retries occur when the model request encounters an HTTP error or when the model response cannot be structurally parsed
      MIDSCENE_MODEL_RETRY_INTERVALInterval between retries in milliseconds, default 2000
      MIDSCENE_MODEL_REASONING_ENABLEDControls whether model-native thinking is enabled. Midscene disables it by default. See Model-native thinking
      MIDSCENE_MODEL_REASONING_EFFORTControls model-native thinking effort, supported by some models. Common values: low, medium, high. See Model-native thinking
      MIDSCENE_MODEL_REASONING_BUDGETThinking token budget (number), supported by some models. See Model-native thinking
      MIDSCENE_MODEL_RESPONSE_FORMATStructured response strategy: auto (default) lets Midscene automatically use response_format in appropriate scenarios to specify a structured output format (usually JSON), making the model response as suitable for structured parsing as possible; none does not set response_format, for models that do not support structured output.
      MIDSCENE_MODEL_HTTP_PROXYHTTP/HTTPS proxy, e.g., http://127.0.0.1:8080 or https://proxy.example.com:8080. Takes precedence over MIDSCENE_MODEL_SOCKS_PROXY
      MIDSCENE_MODEL_SOCKS_PROXYSOCKS proxy, e.g., socks5://127.0.0.1:1080
      MIDSCENE_MODEL_INIT_CONFIG_JSONJSON blob that overrides the OpenAI SDK initialization config. Use defaultHeaders for custom auth headers; extra_headers and extraHeaders are accepted as aliases
      MIDSCENE_MODEL_EXTRA_BODY_JSONJSON blob merged into each chat completion request body. Unlike MIDSCENE_MODEL_INIT_CONFIG_JSON (which configures the SDK client), this is spread into every completion.create() call sent to the model, e.g. enabling thinking mode in vLLM: '{"chat_template_kwargs":{"enable_thinking":true}}'

      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 Insight model

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

      NameDescription
      MIDSCENE_INSIGHT_MODEL_API_KEYAPI key
      MIDSCENE_INSIGHT_MODEL_BASE_URLAPI endpoint URL (omit the trailing /chat/completion)
      MIDSCENE_INSIGHT_MODEL_NAMEModel name
      MIDSCENE_INSIGHT_MODEL_FAMILYModel family
      MIDSCENE_INSIGHT_MODEL_TIMEOUTOptional; timeout for Insight intent AI API calls in milliseconds
      MIDSCENE_INSIGHT_MODEL_TEMPERATUREOptional; sampling temperature for Insight intent responses
      MIDSCENE_INSIGHT_MODEL_RETRY_COUNTOptional; same effect as MIDSCENE_MODEL_RETRY_COUNT
      MIDSCENE_INSIGHT_MODEL_RETRY_INTERVALOptional; same effect as MIDSCENE_MODEL_RETRY_INTERVAL
      MIDSCENE_INSIGHT_MODEL_HTTP_PROXYOptional; same effect as MIDSCENE_MODEL_HTTP_PROXY
      MIDSCENE_INSIGHT_MODEL_SOCKS_PROXYOptional; same effect as MIDSCENE_MODEL_SOCKS_PROXY
      MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSONOptional; same effect as MIDSCENE_MODEL_INIT_CONFIG_JSON
      MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSONOptional; same effect as MIDSCENE_MODEL_EXTRA_BODY_JSON
      MIDSCENE_INSIGHT_MODEL_RESPONSE_FORMATOptional; controls the structured response strategy in appropriate Insight scenarios

      Configure a dedicated Planning model

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

      NameDescription
      MIDSCENE_PLANNING_MODEL_API_KEYAPI key
      MIDSCENE_PLANNING_MODEL_BASE_URLAPI endpoint URL (omit the trailing /chat/completion)
      MIDSCENE_PLANNING_MODEL_NAMEModel name
      MIDSCENE_PLANNING_MODEL_FAMILYModel family
      MIDSCENE_PLANNING_MODEL_TIMEOUTOptional; timeout for Planning intent AI API calls in milliseconds
      MIDSCENE_PLANNING_MODEL_TEMPERATUREOptional; sampling temperature for Planning intent responses
      MIDSCENE_PLANNING_MODEL_RETRY_COUNTOptional; same effect as MIDSCENE_MODEL_RETRY_COUNT
      MIDSCENE_PLANNING_MODEL_RETRY_INTERVALOptional; same effect as MIDSCENE_MODEL_RETRY_INTERVAL
      MIDSCENE_PLANNING_MODEL_HTTP_PROXYOptional; same effect as MIDSCENE_MODEL_HTTP_PROXY
      MIDSCENE_PLANNING_MODEL_SOCKS_PROXYOptional; same effect as MIDSCENE_MODEL_SOCKS_PROXY
      MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSONOptional; same effect as MIDSCENE_MODEL_INIT_CONFIG_JSON
      MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSONOptional; same effect as MIDSCENE_MODEL_EXTRA_BODY_JSON
      MIDSCENE_PLANNING_MODEL_RESPONSE_FORMATOptional; controls the structured response strategy in appropriate Planning scenarios

      Model-native thinking

      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.
      • 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.
      • 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.

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

      Legacy model family configuration

      NameDescriptionNew approach
      MIDSCENE_USE_DOUBAO_VISIONDeprecated. Enables Doubao vision modelUse MIDSCENE_MODEL_FAMILY="doubao-vision"
      MIDSCENE_USE_QWEN3_VLDeprecated. Enables Qwen3-VL modelUse MIDSCENE_MODEL_FAMILY="qwen3-vl"
      MIDSCENE_USE_QWEN_VLDeprecated. Enables Qwen2.5-VL modelUse MIDSCENE_MODEL_FAMILY="qwen2.5-vl"
      MIDSCENE_USE_GEMINIDeprecated. Enables Gemini modelUse MIDSCENE_MODEL_FAMILY="gemini"
      MIDSCENE_USE_VLM_UI_TARSDeprecated. Enables UI-TARS modelUse MIDSCENE_MODEL_FAMILY="vlm-ui-tars"

      General configuration

      NameDescriptionNew approach
      OPENAI_API_KEYDeprecated but supportedPrefer MIDSCENE_MODEL_API_KEY
      OPENAI_BASE_URLDeprecated but supportedPrefer MIDSCENE_MODEL_BASE_URL
      MIDSCENE_OPENAI_INIT_CONFIG_JSONDeprecated but supportedPrefer MIDSCENE_MODEL_INIT_CONFIG_JSON
      MIDSCENE_OPENAI_HTTP_PROXYDeprecated but supportedPrefer MIDSCENE_MODEL_HTTP_PROXY
      MIDSCENE_OPENAI_SOCKS_PROXYDeprecated but supportedPrefer MIDSCENE_MODEL_SOCKS_PROXY

      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

      NameDescription
      MIDSCENE_LANGSMITH_DEBUGSet to 1 to enable Midscene's automatic LangSmith integration
      LANGCHAIN_API_KEYLangSmith API key
      LANGCHAIN_TRACINGSet to true to enable LangSmith tracing
      LANGCHAIN_ENDPOINTLangSmith service endpoint

      Langfuse

      NameDescription
      MIDSCENE_LANGFUSE_DEBUGSet to 1 to enable Midscene's automatic Langfuse integration
      LANGFUSE_PUBLIC_KEYLangfuse public key
      LANGFUSE_SECRET_KEYLangfuse secret key
      LANGFUSE_BASE_URLLangfuse service URL

      Model-call recording

      NameDescription
      MIDSCENE_RECORD_MODEL_CALLSet to true to write model requests, responses, and streaming chunks to local JSONL files