#模型配置

Midscene 通过读取操作系统中指定的环境变量来完成配置。

Midscene 默认集成了 OpenAI SDK 调用 AI 服务，它限定了推理服务的参数风格，绝大多数模型服务商（或模型部署工具）都提供了满足这种要求的接口。

本篇文档会重点介绍 Midscene 的模型配置参数。如果你对 Midscene 的模型策略感兴趣，请阅读 模型策略。如果你想查看常用模型的配置示例，请阅读 常用模型配置。

#必选配置

你需要为 Midscene 配上一个默认模型，详见 模型策略 文档。

#使用 Codex App Server（OAuth，无需 API Key）

如果你已经通过 Codex CLI 登录（codex login），并希望 Midscene 直接复用该 OAuth 会话，可设置：

export MIDSCENE_MODEL_BASE_URL="codex://app-server"
export MIDSCENE_MODEL_NAME="gpt-5.4" # 或者使用 Codex model/list 可见的其他模型
export MIDSCENE_MODEL_FAMILY="gpt-5"

说明：

• 该模式下不需要 MIDSCENE_MODEL_API_KEY。
• Midscene 会通过 stdio 调用 codex app-server。
• 请确保 codex 在 PATH 中可用，并通过 codex login status 确认登录状态。
• 使用该模式时，无法在发送图片时指定 "detail": "original" 参数，因此无法获得最佳的定位效果。详情请参考 Images and Vision guide 和 Computer use guide。

#高阶配置（可选）

如果你为 Insight 或 Planning 配置了独立模型，那么本节中的模型相关 MIDSCENE_MODEL_* 配置需要使用对应的 MIDSCENE_INSIGHT_MODEL_* 或 MIDSCENE_PLANNING_MODEL_* 配置才能在 Insight 或 Planning 意图时生效。

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

#为 Insight 意图单独配置模型

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

#为 Planning 意图单独配置模型

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

#调试日志开关

通过设置以下配置，可以在命令行打印更多调试日志。 无论是否配置，这些日志都会打印在 ./midscene_run/log 文件夹中。

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

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

#Planning 模型配置

#通用配置

#使用 JavaScript 配置参数

你也可以使用 JavaScript 来为每个 Agent 配置模型参数，详见 API 参考

const agent = new Agent(page, {
  // 通过 modelConfig 配置
  modelConfig: {
    MIDSCENE_MODEL_TIMEOUT: '60000', // 60 秒
    MIDSCENE_MODEL_NAME: 'qwen3-vl-plus',
    // ... 其他配置
  }
});

#常见问题

#如何查看模型的 token 使用情况？

通过在环境变量中设置 DEBUG=midscene:ai:profile:stats，你可以打印模型的使用信息和响应时间。

你也可以在报告文件中查看模型的使用量统计。

#使用 LangSmith

LangSmith 是一个用于调试大语言模型的平台。Midscene 提供了自动集成支持，只需安装依赖并设置环境变量即可。

步骤 1：安装依赖

npm install langsmith

步骤 2：设置环境变量

# 启用 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 后，你应该会看到类似如下的日志：

DEBUGGING MODE: langsmith wrapper enabled

注意：

• LangSmith 和 Langfuse 可以同时启用
• 仅支持 Node.js 环境，浏览器环境会报错
• 如果使用 createOpenAIClient 参数，环境变量方式会被覆盖

如果需要更细粒度的控制（例如只对特定任务启用 LangSmith），可以通过 createOpenAIClient 手动包装客户端。

#使用 Langfuse

Langfuse 是另一个流行的 LLM 可观测性平台。Midscene 已经集成了 Langfuse 的 observeOpenAI wrapper，自动追踪所有 OpenAI API 调用。

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

步骤 1：安装依赖

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

步骤 2：初始化 OpenTelemetry（必需）

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

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

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

步骤 3：设置环境变量

# 启用 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 后，你应该会看到类似如下的日志：

OpenTelemetry SDK initialized for Langfuse tracing
DEBUGGING MODE: langfuse wrapper enabled

了解更多：查看 Langfuse OpenAI 集成文档 获取更多配置选项和最佳实践。

注意：

• LangSmith 和 Langfuse 可以同时启用
• 仅支持 Node.js 环境，浏览器环境会报错
• 如果使用 createOpenAIClient 参数，环境变量方式会被覆盖