• 简体中文

      • 模型高级配置与调试

      本文介绍模型高级配置、连接排障、日志和 Trace。

      验证模型连接

      运行以下命令，检查已配置的模型能否连接并用于 Midscene：

      pnpm dlx @midscene/test@latest model verify

      命令读取环境变量，也会加载当前目录下的 .env（可选）。.env 中的值优先于同名环境变量。

      成功输出示例（节选）

      Model role  Check                Result  Requests  Time
planning    Text response        PASS    1         820 ms
insight     Image understanding  PASS    1         1250 ms
locate      AI locate            PASS    1         1460 ms
default     Text response        PASS    1         760 ms

Requests sent: 4. Checks: 4 passed, 0 failed.
✅ Model verify passed.

      失败输出示例（节选）

      Requests sent: 4. Checks: 3 passed, 1 failed.
❌ Model verify failed with messages:
────────────────────────────────────────

[Vision check - ep-vision (insight)]: 404 Not Found

────────────────────────────────────────
      排查连接失败

      如果验证时出现连接错误，可以直接请求模型服务，帮助定位问题。

      可选：使用 curl 测试模型 API

      以下 curl 请求用于检查 Base URL、API Key 和模型名称是否可用。该请求只验证模型 API 的基础连接。它不会检查模型是否满足 Midscene 的兼容性要求。

      MIDSCENE_MODEL_BASE_URL='替换为你的 baseUrl'
MIDSCENE_MODEL_API_KEY='替换为你的 API Key'
MIDSCENE_MODEL_NAME='替换为你的 model name'
# MIDSCENE_MODEL_PROTOCOL="openai-responses" # 使用 Responses API 时取消本行注释；默认使用 Chat API。

if [ "$MIDSCENE_MODEL_PROTOCOL" = "openai-responses" ]; then
  model_endpoint="responses"
  model_input_field="input"
else
  model_endpoint="chat/completions"
  model_input_field="messages"
fi

curl -X POST "${MIDSCENE_MODEL_BASE_URL%/}/${model_endpoint}" \
  -H "Authorization: Bearer ${MIDSCENE_MODEL_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "'"${MIDSCENE_MODEL_NAME}"'",
  "'"${model_input_field}"'": [
    {
      "role": "user",
      "content": "What is 1+1?"
    }
  ]
}'

      如果 curl 请求成功，但 Midscene 验证命令失败，说明模型 API 可以连接。请继续检查模型能力和 Midscene 配置。

      按意图配置模型

      一个默认模型就能满足大多数任务。当任务需要更强的规划、更精确的定位或更好的页面理解能力时，可以为对应意图单独配置更擅长该能力的模型。

      你可以为 Planning（规划）、Locate（定位）和 Insight（页面理解）意图分别配置模型。这些配置与默认模型使用相同的参数后缀，含义与下方高级配置参数表一致，只需替换前缀：

      模型环境变量前缀
      默认模型MIDSCENE_MODEL_
      PlanningMIDSCENE_PLANNING_MODEL_
      LocateMIDSCENE_LOCATE_MODEL_
      InsightMIDSCENE_INSIGHT_MODEL_

      请为每个专用模型提供完整配置，包括接入地址、API Key（接入方式需要时）、模型名称和 family，并按需添加可选参数。

      未单独配置模型的场景使用默认模型。

      查看多模型配置示例

      保留默认模型，按需添加专用模型。请将占位值和模型名称替换为服务商提供的实际配置。

      # 默认模型
export MIDSCENE_MODEL_BASE_URL="https://..."
export MIDSCENE_MODEL_API_KEY="..."
export MIDSCENE_MODEL_NAME="qwen3.8-flash"
export MIDSCENE_MODEL_FAMILY="qwen3"

# Planning 规划模型
export MIDSCENE_PLANNING_MODEL_BASE_URL="https://..."
export MIDSCENE_PLANNING_MODEL_API_KEY="..."
export MIDSCENE_PLANNING_MODEL_NAME="gpt-6-astra"
export MIDSCENE_PLANNING_MODEL_FAMILY="gpt-6"

# Locate 定位模型
export MIDSCENE_LOCATE_MODEL_BASE_URL="https://..."
export MIDSCENE_LOCATE_MODEL_API_KEY="..."
export MIDSCENE_LOCATE_MODEL_NAME="gemini-3.5-flash"
export MIDSCENE_LOCATE_MODEL_FAMILY="gemini"

# Insight 页面理解模型
export MIDSCENE_INSIGHT_MODEL_BASE_URL="https://..."
export MIDSCENE_INSIGHT_MODEL_API_KEY="..."
export MIDSCENE_INSIGHT_MODEL_NAME="gpt-6.1-sol"
export MIDSCENE_INSIGHT_MODEL_FAMILY="gpt-6"

      高阶配置（可选）

      配置参数参考

      为 Planning、Locate 或 Insight 单独配置模型时，使用对应的环境变量前缀，详见按意图配置模型。

      名称描述
      MIDSCENE_MODEL_TIMEOUT单次模型请求的超时时间，单位毫秒，默认 180000（180 秒），包含响应体读取时间。设为 0 禁用此超时限制。
      MIDSCENE_MODEL_TEMPERATURE模型采样温度
      MIDSCENE_MODEL_RETRY_COUNTAI 调用失败时的重试次数，默认 1（即失败后重试 1 次）。模型请求遇到 HTTP 错误，或模型返回值无法被结构化解析时，都会发起重试
      MIDSCENE_MODEL_RETRY_INTERVALAI 调用重试间隔毫秒数，默认 2000
      MIDSCENE_MODEL_REASONING_ENABLED控制是否启用模型的原生思考能力，Midscene 默认关闭。详见模型原生思考
      MIDSCENE_MODEL_REASONING_EFFORT控制模型的原生思考力度，部分模型支持。常用值：low、medium、high。详见模型原生思考
      MIDSCENE_MODEL_REASONING_BUDGET思考 Token 预算（数字），部分模型支持。详见模型原生思考
      MIDSCENE_MODEL_RESPONSE_FORMAT结构化响应策略：auto（默认）表示 Midscene 会在合适的场景自动使用 response_format（Chat Completions）或 text.format（Responses）参数指定模型输出的结构化格式（一般是 JSON），来尽可能保证模型返回值能够被结构化解析；none 表示不指定上述格式参数，适用于模型不支持结构化输出的情况。
      MIDSCENE_MODEL_HTTP_PROXYHTTP/HTTPS 代理配置，如 http://127.0.0.1:8080 或 https://proxy.example.com:8080，优先级高于 MIDSCENE_MODEL_SOCKS_PROXY
      MIDSCENE_MODEL_SOCKS_PROXYSOCKS 代理配置，如 socks5://127.0.0.1:1080
      MIDSCENE_MODEL_INIT_CONFIG_JSON覆盖 OpenAI SDK 初始化配置的 JSON。自定义鉴权 header 请使用 defaultHeaders；extra_headers 和 extraHeaders 也会作为别名兼容
      MIDSCENE_MODEL_EXTRA_BODY_JSON合并到每次模型请求体中的 JSON。与 MIDSCENE_MODEL_INIT_CONFIG_JSON（配置 SDK 客户端）不同，此参数会展开到每次发送到模型的协议请求体中，例如在 vLLM 中启用思考模式：'{"chat_template_kwargs":{"enable_thinking":true}}'
      MIDSCENE_MODEL_PROTOCOL模型 API 协议：openai-chat（默认）或 openai-responses。后者的适用范围见使用 Responses API。
      MIDSCENE_MODEL_AUTH_MODE认证模式：api-key（默认）使用配置的 API Key；siwc 使用 ChatGPT 授权后保存的凭据，并自动刷新 access token。接入步骤参见使用 ChatGPT 订阅额度。
      MIDSCENE_MODEL_STREAM_MODE默认是非流式（non-stream）；如果指定为流式（stream），会将流式的结果聚合为完整结果再解析。

      使用 Responses API

      Midscene 默认使用 Chat Completions 协议（openai-chat）。目前内置模型适配器中，只有 gpt-5 和 gpt-6 支持切换到 Responses API；其他模型 family 设置 openai-responses 会报不支持该协议的错误。

      使用 OpenAI 官方接入点时，在对应 GPT 模型配置中设置：

      MIDSCENE_MODEL_BASE_URL="https://api.openai.com/v1"
MIDSCENE_MODEL_PROTOCOL="openai-responses"

      模型名称、API Key 和 family 仍需按GPT 配置示例填写。Base URL 不要追加 /responses，SDK 会自动添加。

      Responses API 不限于 OpenAI 官方接入点，也可以用于提供兼容接口的 Azure OpenAI 或其他接入点，但需要确认接入点及所选 GPT 模型支持该协议；仅兼容 Chat Completions 并不代表兼容 Responses。Azure 的配置与已验证场景见使用 Azure OpenAI 时点击坐标偏移。

      为 Planning、Locate 或 Insight 单独配置 GPT 模型时，使用对应的 MIDSCENE_PLANNING_MODEL_PROTOCOL、MIDSCENE_LOCATE_MODEL_PROTOCOL 或 MIDSCENE_INSIGHT_MODEL_PROTOCOL。每个模型的协议独立配置，不影响其他模型。

      模型原生思考

      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 会忽略该配置，不会猜测服务商的私有参数。

      故障排查

      常见配置错误

      MIDSCENE_MODEL_FAMILY 未设置为多模态模型

      如果收到 MIDSCENE_MODEL_FAMILY is not set to a multimodal model with UI localization 错误，请确认已正确配置多模态模型的 MIDSCENE_MODEL_FAMILY 环境变量。

      从 1.0 版本开始，Midscene 推荐使用 MIDSCENE_MODEL_FAMILY 指定多模态模型类型。旧的 MIDSCENE_USE_... 配置仍然兼容，但已经废弃。

      正确的模型 family 和完整配置示例请参考使用模型 API Key。

      Base URL 或模型名称不正确

      确认 MIDSCENE_MODEL_BASE_URL 指向服务商的 API 接入地址。该地址通常以 /v1 等版本号结尾。请勿添加 /chat/completions 或 /responses，底层 SDK 会根据所选 API 类型自动添加请求路径。

      同时确认 MIDSCENE_MODEL_NAME 与该接入地址提供的模型一致。

      模型结果不可靠时

      如果模型可以正常连接，但执行了错误操作、未能定位目标或误解了页面内容：

      • 查看回放报告，确定任务在哪一步出错。
      • 尝试更新的受支持模型版本，或使用代表性任务对比不同模型。
      • 如果问题集中在规划、定位或页面理解，可以考虑为对应意图单独配置模型。

      模型选择和职责说明见模型选择指南。

      调试能力

      Debug 日志

      需要额外的诊断信息时，可以设置 DEBUG。常用选择器包括：

      • DEBUG=midscene:ai:profile:stats：打印模型延迟和 Token 使用量。
      • DEBUG=midscene:ai:call：打印 AI 响应详情。
      • DEBUG=midscene:*：打印全部 Midscene Debug 日志。

      完整的选择器列表、日志目录和使用注意事项，请参考运行时配置：Debug 日志。

      生成的报告文件中也包含模型使用量统计。

      记录模型调用

      设置 MIDSCENE_RECORD_MODEL_CALL=true，可以将模型请求、响应和流式 Chunk 写入 JSONL 文件：

      midscene_run/model-requests/<启动时间>-<pid>.jsonl

      每个进程生成一个文件，每行对应一个 JSON 事件。只有 Node.js 和 Electron 支持写入本地文件。浏览器和 Worker 不会写入本地文件。使用 Codex App Server 时，记录还会包含可获取的协议元数据。

      每个事件的 type 为 request、chunk、response 或 error。事件还包含 executionId，用于关联同一个 execution ID 下的调用及其重试。对于 HTTP 模型请求，这个值也会通过 x-midscene-execution-id Header 发送。不属于报告 execution 的调用（例如连接检查）会使用带 unscoped- 前缀的生成 ID。

      安全注意事项

      模型调用记录包含请求 Body（包括自定义 extraBody）、响应 Header 和 Body、流式响应，以及可能采用 Base64 编码的截图。请求 Header 不会被记录。

      • 仅在排查问题时启用记录。文件可能较大，使用后请妥善保管或删除。记录格式不保证跨版本兼容。
      • 不要将 .env 文件、Trace、Debug 日志或模型调用记录提交到源码仓库。
      • 日志、Trace 和模型调用记录可能包含模型输入、输出或截图，分享前请先检查内容。

      请求追踪 Header

      Midscene 会自动为 OpenAI-compatible HTTP 模型请求添加以下 Header：

      Header值用途
      x-midscene-version当前 @midscene/core 版本标识发起请求的 Midscene 版本
      x-midscene-execution-id当前 execution ID关联同一个 execution ID 下的全部模型请求及其重试，例如一次 aiAct 调用

      不属于报告 execution 的调用（例如连接检查）会使用带 unscoped- 前缀的生成 execution ID。这两个 Header 会被默认发送，如果 MIDSCENE_*_INIT_CONFIG_JSON 中自定义了同名 Header，则会被 Midscene 覆盖。

      可观测性平台

      以下自动集成会包装 OpenAI-compatible HTTP 请求使用的 OpenAI SDK 客户端，不适用于 Codex App Server 或 Jev 的 System One 协议。

      注意事项：

      • LangSmith 和 Langfuse 可以同时启用。
      • 该集成仅支持 Node.js。浏览器环境会抛出错误。
      • createOpenAIClient 接收原始 OpenAI 客户端。如果回调返回客户端，该客户端会替换自动包装后的客户端；请在回调内添加所需的追踪 wrapper。如果回调未返回客户端，则保留自动集成。

      LangSmith

      LangSmith 是用于调试大语言模型的平台。安装依赖并设置环境变量后，Midscene 可以自动接入 LangSmith。

      安装依赖

      npm install langsmith

      设置环境变量

      # 启用 Midscene 的 LangSmith 自动集成
export MIDSCENE_LANGSMITH_DEBUG=1

# LangSmith 配置
export LANGCHAIN_API_KEY="your-langchain-api-key-here"
export LANGCHAIN_TRACING=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
# export LANGCHAIN_ENDPOINT="https://eu.api.smith.langchain.com" # 如果在欧洲区域注册

      Midscene 为模型请求创建 OpenAI 客户端时，会输出启用 wrapper 的日志：

      DEBUGGING MODE: langsmith wrapper enabled

      如需进行更细粒度的控制，例如只对特定任务启用 LangSmith，请使用 createOpenAIClient 手动包装客户端。

      Langfuse

      Langfuse 是一个 LLM 可观测性平台。Midscene 集成了 Langfuse 的 observeOpenAI wrapper，可以自动追踪 OpenAI API 调用。

      Langfuse 的追踪基于 OpenTelemetry，因此需要在应用启动时初始化 OpenTelemetry SDK。

      安装依赖

      npm install @langfuse/openai @langfuse/otel @opentelemetry/sdk-node

      初始化 OpenTelemetry

      在应用入口文件的最顶部添加以下代码：

      import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";

const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});
sdk.start();

      设置环境变量

      # 启用 Midscene 的 Langfuse 自动集成
export MIDSCENE_LANGFUSE_DEBUG=1

# Langfuse 配置
export LANGFUSE_PUBLIC_KEY="your-langfuse-public-key-here"
export LANGFUSE_SECRET_KEY="your-langfuse-secret-key-here"
export LANGFUSE_BASE_URL="https://cloud.langfuse.com" # 🇪🇺 欧洲区域
# export LANGFUSE_BASE_URL="https://us.cloud.langfuse.com" # 🇺🇸 美国区域

      Midscene 为模型请求创建 OpenAI 客户端时，会输出启用 wrapper 的日志：

      DEBUGGING MODE: langfuse wrapper enabled

      这条日志仅表示启用 wrapper，不代表 Trace 已成功发送到 Langfuse。请执行一次模型请求，并在 Langfuse 项目中确认是否收到 Trace。

      更多配置和最佳实践请参考 Langfuse OpenAI 集成文档。

      旧版配置

      以下配置仍受支持；新配置请使用下表中的替代方式。

      旧版配置替代方式 / 说明
      MIDSCENE_USE_DOUBAO_VISION使用 MIDSCENE_MODEL_FAMILY="doubao-vision"
      MIDSCENE_USE_QWEN3_VL使用 MIDSCENE_MODEL_FAMILY="qwen3-vl"
      MIDSCENE_USE_QWEN_VL使用 MIDSCENE_MODEL_FAMILY="qwen2.5-vl"
      MIDSCENE_USE_GEMINI使用 MIDSCENE_MODEL_FAMILY="gemini"
      MIDSCENE_USE_VLM_UI_TARS使用 MIDSCENE_MODEL_FAMILY="vlm-ui-tars"
      OPENAI_API_KEY使用 MIDSCENE_MODEL_API_KEY
      OPENAI_BASE_URL使用 MIDSCENE_MODEL_BASE_URL
      MIDSCENE_OPENAI_INIT_CONFIG_JSON使用 MIDSCENE_MODEL_INIT_CONFIG_JSON
      MIDSCENE_OPENAI_HTTP_PROXY使用 MIDSCENE_MODEL_HTTP_PROXY
      MIDSCENE_OPENAI_SOCKS_PROXY使用 MIDSCENE_MODEL_SOCKS_PROXY
      MIDSCENE_REPLANNING_CYCLE_LIMIT使用 Agent 的 replanningCycleLimit 参数，优先级高于环境变量