> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt. # 模型高级配置与调试 本文介绍模型高级配置、连接排障、日志和 Trace。 ## 验证模型连接 {#verify-model-connectivity} 运行以下命令，检查已配置的模型能否连接并用于 Midscene： ```bash pnpm dlx @midscene/test@latest model verify ``` 命令读取环境变量，也会加载当前目录下的 `.env`（可选）。`.env` 中的值优先于同名环境变量。 **成功输出示例（节选）** ```text 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. ``` **失败输出示例（节选）** ```text Requests sent: 4. Checks: 3 passed, 1 failed. ❌ Model verify failed with messages: ──────────────────────────────────────── [Vision check - ep-vision (insight)]: 404 Not Found ──────────────────────────────────────── ``` :::info 排查连接失败 如果验证时出现连接错误，可以直接请求模型服务，帮助定位问题。 可选：使用 curl 测试模型 API 以下 `curl` 请求用于检查 Base URL、API Key 和模型名称是否可用。该请求只验证模型 API 的基础连接。它不会检查模型是否满足 Midscene 的兼容性要求。 ```bash 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 配置。 ::: ## 按意图配置模型 {#dedicated-models} 一个默认模型就能满足大多数任务。当任务需要更强的规划、更精确的定位或更好的页面理解能力时，可以为对应意图单独配置更擅长该能力的模型。 你可以为 Planning（规划）、Locate（定位）和 Insight（页面理解）意图分别配置模型。这些配置与默认模型使用相同的参数后缀，含义与下方高级配置参数表一致，只需替换前缀： | 模型 | 环境变量前缀 | | -------- | -------------------------- | | 默认模型 | `MIDSCENE_MODEL_` | | Planning | `MIDSCENE_PLANNING_MODEL_` | | Locate | `MIDSCENE_LOCATE_MODEL_` | | Insight | `MIDSCENE_INSIGHT_MODEL_` | 请为每个专用模型提供完整配置，包括接入地址、API Key（接入方式需要时）、模型名称和 family，并按需添加可选参数。 未单独配置模型的场景使用默认模型。 查看多模型配置示例 保留默认模型，按需添加专用模型。请将占位值和模型名称替换为服务商提供的实际配置。 ```bash # 默认模型 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 单独配置模型时，使用对应的环境变量前缀，详见[按意图配置模型](#dedicated-models)。 | 名称 | 描述 | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MIDSCENE_MODEL_ENDPOINT` | System One API 的完整请求 URL，仅支持 System One 模型（目前为 Jev）。优先于对应模型的 `BASE_URL`，直接使用，不追加路径；设置后无需配置 `BASE_URL`。例如 `https://api.typesafe.ai/v1/systemone`。未设置时，沿用在 Base URL 后追加 `/systemone` 的行为。 | | `MIDSCENE_MODEL_TIMEOUT` | 单次模型请求的超时时间，单位毫秒，默认 `180000`（180 秒），包含响应体读取时间。设为 `0` 禁用此超时限制。 | | `MIDSCENE_MODEL_TEMPERATURE` | 模型采样温度。配置为 `unset` 时不传递温度参数。 | | `MIDSCENE_MODEL_RETRY_COUNT` | AI 调用失败时的重试次数，默认 1（即失败后重试 1 次）。模型请求遇到 HTTP 错误，或模型返回值无法被结构化解析时，都会发起重试 | | `MIDSCENE_MODEL_RETRY_INTERVAL` | AI 调用重试间隔毫秒数，默认 2000 | | `MIDSCENE_MODEL_REASONING_ENABLED` | 控制是否启用模型的原生思考能力，Midscene 默认关闭。详见[模型原生思考](#model-native-reasoning) | | `MIDSCENE_MODEL_REASONING_EFFORT` | 控制模型的原生思考力度，部分模型支持。常用值：`low`、`medium`、`high`。详见[模型原生思考](#model-native-reasoning) | | `MIDSCENE_MODEL_REASONING_BUDGET` | 思考 Token 预算（数字），部分模型支持。详见[模型原生思考](#model-native-reasoning) | | `MIDSCENE_MODEL_RESPONSE_FORMAT` | 结构化响应策略：`auto`（默认）表示 Midscene 会在合适的场景自动使用 `response_format`（Chat Completions）或 `text.format`（Responses）参数指定模型输出的结构化格式（一般是 JSON），来尽可能保证模型返回值能够被结构化解析；`none` 表示不指定上述格式参数，适用于模型不支持结构化输出的情况。 | | `MIDSCENE_MODEL_HTTP_PROXY` | HTTP/HTTPS 代理配置，如 `http://127.0.0.1:8080` 或 `https://proxy.example.com:8080`，优先级高于 `MIDSCENE_MODEL_SOCKS_PROXY` | | `MIDSCENE_MODEL_SOCKS_PROXY` | SOCKS 代理配置，如 `socks5://127.0.0.1:1080` | | `MIDSCENE_MODEL_INIT_CONFIG_JSON` | 覆盖 OpenAI SDK 初始化配置的 JSON，适合设置自定义 Header、查询参数等额外选项。不建议通过它覆盖 `baseURL` 或 `apiKey`；请分别使用 `MIDSCENE_MODEL_BASE_URL` 和 `MIDSCENE_MODEL_API_KEY`，以确保 Midscene 的参数适配与实际请求配置一致。自定义鉴权 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](#model-api-type)。 | | `MIDSCENE_MODEL_AUTH_MODE` | 认证模式：`api-key`（默认）使用配置的 API Key；`siwc` 使用 ChatGPT 授权后保存的凭据，并自动刷新 access token。接入步骤参见[使用 ChatGPT 订阅额度](/zh/chatgpt-subscription.md)。 | | `MIDSCENE_MODEL_STREAM_MODE` | 默认是非流式（`non-stream`）；如果指定为流式（`stream`），会将流式的结果聚合为完整结果再解析。 | ### 使用 Responses API {#model-api-type} Midscene 默认使用 Chat Completions 协议（`openai-chat`）。目前内置模型适配器中，只有 `gpt-5` 和 `gpt-6` 支持切换到 Responses API；其他模型 family 设置 `openai-responses` 会报不支持该协议的错误。 使用 OpenAI 官方接入点时，在对应 GPT 模型配置中设置： ```bash MIDSCENE_MODEL_BASE_URL="https://api.openai.com/v1" MIDSCENE_MODEL_PROTOCOL="openai-responses" ``` 模型名称、API Key 和 family 仍需按[GPT 配置示例](/zh/model-api-setup.md#gpt)填写。Base URL 不要追加 `/responses`，SDK 会自动添加。 Responses API 不限于 OpenAI 官方接入点，也可以用于提供兼容接口的 Azure OpenAI 或其他接入点，但需要确认接入点及所选 GPT 模型支持该协议；仅兼容 Chat Completions 并不代表兼容 Responses。Azure 的配置与已验证场景见[使用 Azure OpenAI 时点击坐标偏移](/zh/faq.md#使用-azure-openai-时点击坐标偏移)。 为 Planning、Locate 或 Insight 单独配置 GPT 模型时，使用对应的 `MIDSCENE_PLANNING_MODEL_PROTOCOL`、`MIDSCENE_LOCATE_MODEL_PROTOCOL` 或 `MIDSCENE_INSIGHT_MODEL_PROTOCOL`。每个模型的协议独立配置，不影响其他模型。 ### 模型原生思考 {#model-native-reasoning} 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_BUDGET` 控制思考 Token 额度，千问 Plus 等系列支持。 - `MIDSCENE_MODEL_REASONING_EFFORT` 控制思考力度，豆包、DeepSeek、Gemini、GPT、腾讯混元、Kimi 等系列支持。 具体模型的适配情况和参数映射以代码实现为准。 不同模型服务商对参数的支持情况不同，具体取值请参考对应服务商的官方文档。对于模型官方接口，如果当前适配不支持某项显式配置，Midscene 会忽略该配置。 其中，OpenRouter 提供了[统一的思考参数](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens)。当 `MIDSCENE_MODEL_BASE_URL` 设置为 `https://openrouter.ai/api/v1` 时，Midscene 对已适配模型使用以下映射： - 思考开关 `MIDSCENE_MODEL_REASONING_ENABLED` → `reasoning.enabled`（GPT 系列通过 `reasoning.effort` 控制）。 - 思考力度 `MIDSCENE_MODEL_REASONING_EFFORT` → `reasoning.effort`（具体模型是否支持以实际模型为准）。 - 思考额度 `MIDSCENE_MODEL_REASONING_BUDGET` → `reasoning.max_tokens`（具体模型是否支持以实际模型为准）。 如果你的模型供应商需要额外指定特殊参数，可以使用 `MIDSCENE_MODEL_EXTRA_BODY_JSON`。例如，通过自建中转调用 OpenRouter 时指定关闭思考： ```bash MIDSCENE_MODEL_EXTRA_BODY_JSON='{"reasoning":{"enabled":false}}' ``` extra JSON 在 Adapter 参数之后合并，同名顶层字段会整体覆盖，不会深度合并。参数是否生效取决于接入点和模型支持。 ## 故障排查 ### 常见配置错误 {#common-configuration-errors} **`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](/zh/model-api-setup.md)。 **Base URL 或模型名称不正确** 确认 `MIDSCENE_MODEL_BASE_URL` 指向服务商的 API 接入地址。该地址通常以 `/v1` 等版本号结尾。请勿添加 `/chat/completions` 或 `/responses`，底层 SDK 会根据所选 API 类型自动添加请求路径。 同时确认 `MIDSCENE_MODEL_NAME` 与该接入地址提供的模型一致。 ### 模型结果不可靠时 {#when-model-results-are-unreliable} 如果模型可以正常连接，但执行了错误操作、未能定位目标或误解了页面内容： - 查看[回放报告](/zh/consume-report-file.md)，确定任务在哪一步出错。 - 尝试更新的受支持模型版本，或使用代表性任务对比不同模型。 - 如果问题集中在规划、定位或页面理解，可以考虑[为对应意图单独配置模型](#dedicated-models)。 模型选择和职责说明见[模型选择指南](/zh/model-selection.md)。 ## 调试能力 ### Debug 日志 需要额外的诊断信息时，可以设置 `DEBUG`。常用选择器包括： - `DEBUG=midscene:ai:profile:stats`：打印模型延迟和 Token 使用量。 - `DEBUG=midscene:ai:call`：打印 AI 响应详情。 - `DEBUG=midscene:*`：打印全部 Midscene Debug 日志。 完整的选择器列表、日志目录和使用注意事项，请参考[运行时配置：Debug 日志](/zh/reference.md#debug-logs)。 生成的[报告文件](/zh/consume-report-file.md)中也包含模型使用量统计。 ### 记录模型调用 设置 `MIDSCENE_RECORD_MODEL_CALL=true`，可以将模型请求、响应和流式 Chunk 写入 JSONL 文件： ```text midscene_run/model-requests/<启动时间>-.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。 :::warning 安全注意事项 模型调用记录包含请求 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`](/zh/reference.md#自定义-openai-客户端) 接收原始 OpenAI 客户端。如果回调返回客户端，该客户端会替换自动包装后的客户端；请在回调内添加所需的追踪 wrapper。如果回调未返回客户端，则保留自动集成。 ### LangSmith LangSmith 是用于调试大语言模型的平台。安装依赖并设置环境变量后，Midscene 可以自动接入 LangSmith。 **安装依赖** ```bash npm install langsmith ``` **设置环境变量** ```bash # 启用 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 的日志： ```log DEBUGGING MODE: langsmith wrapper enabled ``` 如需进行更细粒度的控制，例如只对特定任务启用 LangSmith，请使用 [`createOpenAIClient`](/zh/reference.md#自定义-openai-客户端) 手动包装客户端。 ### Langfuse [Langfuse](https://langfuse.com) 是一个 LLM 可观测性平台。Midscene 集成了 Langfuse 的 `observeOpenAI` wrapper，可以自动追踪 OpenAI API 调用。 Langfuse 的追踪基于 OpenTelemetry，因此需要在应用启动时初始化 OpenTelemetry SDK。 **安装依赖** ```bash npm install @langfuse/openai @langfuse/otel @opentelemetry/sdk-node ``` **初始化 OpenTelemetry** 在应用入口文件的最顶部添加以下代码： ```typescript import { NodeSDK } from "@opentelemetry/sdk-node"; import { LangfuseSpanProcessor } from "@langfuse/otel"; const sdk = new NodeSDK({ spanProcessors: [new LangfuseSpanProcessor()], }); sdk.start(); ``` **设置环境变量** ```bash # 启用 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 的日志： ```log DEBUGGING MODE: langfuse wrapper enabled ``` 这条日志仅表示启用 wrapper，不代表 Trace 已成功发送到 Langfuse。请执行一次模型请求，并在 Langfuse 项目中确认是否收到 Trace。 更多配置和最佳实践请参考 [Langfuse OpenAI 集成文档](https://langfuse.com/integrations/model-providers/openai-js)。 ## 旧版配置 以下配置仍受支持；新配置请使用下表中的替代方式。 | 旧版配置 | 替代方式 / 说明 | | ---------------------------------- | ---------------------------------------------- | | `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` 参数，优先级高于环境变量 |