• 简体中文
  • 配置你的模型

    一个快速默认配置

    Midscene 需要配置多模态模型来操作界面。若只想先跑起来,可以直接使用下方示例的环境变量配置快速开始。

    示例使用阿里云的 Qwen3.x,它易于获取,是一个通用且稳妥的选择:

    export MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
    export MIDSCENE_MODEL_API_KEY="your-api-key"
    export MIDSCENE_MODEL_NAME="qwen3.7-plus"
    export MIDSCENE_MODEL_FAMILY="qwen3"

    如需了解全部受支持模型及不同的环境变量配置方式,请继续往下阅读。

    支持的模型

    以下是 Midscene 正式支持的模型。配置模型时,除大模型通常需要的 Base URL、API Key 和模型名称外,还需要额外声明正确的 MIDSCENE_MODEL_FAMILY,用于标记模型所属的系列,以获得最佳的效果适配。

    模型选择技巧
    • 对于同一厂商的模型,优先使用新版本。新版本通常会在效果、速度和价格上带来更好的综合体验,不建议在旧版本上投入过多调优成本。
    • 对于不同厂商的模型,在效果、速度和价格上可能有较大差距。建议使用你的代表性任务进行小规模对比,再选择最适合实际场景的模型。
    • Midscene 支持多模型配合。通常只需配置一个默认模型,即可完成界面定位和操作;但通过单独配置 Planning 和 Insight 模型,能发挥不同模型在性能、价格等方面的优势,获得更好的综合效果。更多信息可参考高阶特性:多模型配合

    豆包 Seed 系列

    模型版本常用模型名称对应 MODEL_FAMILY备注
    2.x 系列Doubao-Seed-2.1-turboDoubao-Seed-2.0-Litedoubao-seedDoubao-Seed-2.1-turbo 目前私有测评集中定位速度最快,且定位效果也很好,推荐使用。
    1.x 系列Doubao-Seed-1.6-VisionDoubao-Seed-1.8doubao-seed1.x 系列为豆包的旧版本模型,综合表现已不具竞争力,建议优先使用 2.x 系列。

    环境变量配置示例,以 doubao-seed-2.1-turbo 为例:

    🎯 用作默认模型
    🧠 用作 Planning 模型
    🔎 用作 Insight 模型
    MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" # 火山引擎地址
    MIDSCENE_MODEL_API_KEY="...."
    MIDSCENE_MODEL_NAME="doubao-seed-2.1-turbo"
    MIDSCENE_MODEL_FAMILY="doubao-seed"

    如果你的火山引擎账号已开通低延迟模式(Fast),可以追加以下请求体参数来使用该能力。通常可将模型响应速度提升约 30% 至 50%。

    MIDSCENE_MODEL_EXTRA_BODY_JSON={"service_tier":"fast"}
    兼容性说明

    为兼容已有配置,仍支持 MIDSCENE_MODEL_FAMILY="doubao-vision";新配置建议使用 doubao-seed

    千问 Qwen 系列

    模型版本常用模型名称对应 MODEL_FAMILY备注
    Qwen3.x 系列qwen3.7-plusqwen3.5-plusqwen3.6-plusqwen3从定位测评的结果看,推荐顺序为 Qwen3.7 > Qwen3.5 > Qwen3.6。qwen3.5qwen3.6 作为旧 family 仍然兼容。
    Qwen3-VL 系列qwen3-vl-plusqwen3-vl作为旧版本模型,不推荐使用。建议优先使用 Qwen3.x 系列。
    Qwen2.5-VL 系列qwen-vl-max-latestqwen2.5-vl作为旧版本模型,不推荐使用。建议优先使用 Qwen3.x 系列。

    环境变量配置示例,以 qwen3.7-plus 为例:

    🎯 用作默认模型
    🧠 用作 Planning 模型
    🔎 用作 Insight 模型
    MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" # 阿里云地址
    MIDSCENE_MODEL_API_KEY="......"
    MIDSCENE_MODEL_NAME="qwen3.7-plus"
    MIDSCENE_MODEL_FAMILY="qwen3" # 如果你使用了其他版本的 Qwen,需要替换为对应的 model family

    Gemini 系列

    模型版本常用模型名称对应 MODEL_FAMILY备注
    Gemini 3.x 系列gemini-3.5-flashgemini-3-flash-previewgeminigemini-3.5-flash 是目前我们私有测评集中定位表现最好的模型。

    环境变量配置示例,以 gemini-3.5-flash 为例:

    🎯 用作默认模型
    🧠 用作 Planning 模型
    🔎 用作 Insight 模型
    MIDSCENE_MODEL_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/" # Google Gemini API 地址
    MIDSCENE_MODEL_API_KEY="......"
    MIDSCENE_MODEL_NAME="gemini-3.5-flash"
    MIDSCENE_MODEL_FAMILY="gemini"

    GPT 系列

    • 常用模型供应商:OpenAI
    模型版本常用模型名称对应 MODEL_FAMILY备注
    GPT-5 系列gpt-5.4gpt-5.5gpt-5.6-solgpt-5.6-terragpt-5.6-lunagpt-5GPT-5.4 之前的模型不支持视觉定位,仅可用作 Planning 模型或 Insight 模型。在实际定位测试中,GPT-5.5 和 GPT-5.6 的定位效果明显优于 GPT-5.4,建议优先使用 GPT-5.5 或 GPT-5.6。

    环境变量配置示例,以 gpt-5.5 为例:

    🎯 用作默认模型
    🧠 用作 Planning 模型
    🔎 用作 Insight 模型
    MIDSCENE_MODEL_BASE_URL="https://api.openai.com/v1" # OpenAI API 地址;或你的兼容服务地址
    MIDSCENE_MODEL_API_KEY="sk-..."
    MIDSCENE_MODEL_NAME="gpt-5.5"
    MIDSCENE_MODEL_FAMILY="gpt-5"

    你也可以通过使用 Codex App Server(OAuth,无需 API Key) 使用 GPT。

    GPT-5 使用注意事项
    • 使用 GPT 做 UI 定位时,目前只支持使用 gpt-5.4 及以后的模型。因为为了获得最佳的定位效果,需要在发送图片时指定 "detail": "original" 参数,这一参数仅在 gpt-5.4 及后续模型上可用,gpt-5.4-minigpt-5.4-nano 等更小的 GPT-5 变体以及前代模型不支持 original 参数,会导致报错。详情请参考 Images and Vision guideComputer use guide
    • 按照 OpenAI 的文档,GPT-5 在处理非拉丁字母文本、字号太小的文本时效果可能不理想,参见 Images and Vision guide
    • OpenAI 在 computer use 文档中提到,他们观察到 1440x9001600x900 这两种截图尺寸上通常能获得比较好的效果,详见 Computer use guide。因此,建议按照 OpenAI 的推荐对截图尺寸进行调整。在 Midscene 中,你可以通过 Agent 参数里的 screenshotShrinkFactor 控制截图压缩倍率。如果是浏览器自动化,还可以通过浏览器 viewport 指定页面的尺寸和比例。
    • 使用 Azure OpenAI 时,Azure 可能不会正确处理 "detail": "original",从而造成点击坐标偏移。详见 使用 Azure OpenAI 时点击坐标偏移
    • 如果你使用的是更老版本的 GPT-5,建议只将其用作规划模型,并搭配其他多模态模型完成定位,参考多模型组合示例
    模型原生思考

    Midscene 默认关闭模型原生思考,以获得最佳的执行速度和稳定性。如需为上面任意模型开启,设置 MIDSCENE_MODEL_REASONING_ENABLED="true" 即可。部分模型系列还支持 MIDSCENE_MODEL_REASONING_BUDGETMIDSCENE_MODEL_REASONING_EFFORT 等额外控制项。详见模型原生的思考模式

    月之暗面 Kimi 系列

    模型版本常用模型名称对应 MODEL_FAMILY备注
    K3 系列kimi-k3kimi3根据 Kimi 的文档,K3 始终开启思考模式,无法关闭,且推理强度默认为 max
    K2.x 系列kimi-k2.5kimi-k2.6kimi

    环境变量配置示例,以 kimi-k3 为例:

    🎯 用作默认模型
    🧠 用作 Planning 模型
    🔎 用作 Insight 模型
    MIDSCENE_MODEL_BASE_URL="https://api.moonshot.cn/v1" # Moonshot AI API 地址
    MIDSCENE_MODEL_API_KEY="......"
    MIDSCENE_MODEL_NAME="kimi-k3"
    MIDSCENE_MODEL_FAMILY="kimi3" # 如果使用 kimi-k2.6,请改为 "kimi"

    小米 MiMo 系列

    模型版本常用模型名称对应 MODEL_FAMILY备注
    V2.x 系列mimo-v2.5xiaomi-mimo仅 Omni 系列支持多模态输入;Pro 系列是文本模型,不能用于 Midscene 视觉任务。

    环境变量配置示例,以 mimo-v2.5 为例:

    🎯 用作默认模型
    🧠 用作 Planning 模型
    🔎 用作 Insight 模型
    MIDSCENE_MODEL_BASE_URL="https://api.xiaomimimo.com/v1" # 小米 MiMo API 地址
    MIDSCENE_MODEL_API_KEY="......"
    MIDSCENE_MODEL_NAME="mimo-v2.5"
    MIDSCENE_MODEL_FAMILY="xiaomi-mimo"

    智谱 GLM-V 系列

    模型版本常用模型名称对应 MODEL_FAMILY备注
    GLM-5V 系列glm-5v-turboglm-v
    GLM-4.6 系列glm-4.6vglm-vglm-4.6v 是开源模型。

    环境变量配置示例,以 glm-5v-turbo 为例:

    🎯 用作默认模型
    🧠 用作 Planning 模型
    🔎 用作 Insight 模型
    MIDSCENE_MODEL_BASE_URL="https://open.bigmodel.cn/api/paas/v4" # BigModel API 地址;Z.AI 使用 https://api.z.ai/api/paas/v4
    MIDSCENE_MODEL_API_KEY="......"
    MIDSCENE_MODEL_NAME="glm-5v-turbo"
    MIDSCENE_MODEL_FAMILY="glm-v"

    了解更多关于 GLM-4.6V 开源模型

    配置环境变量的方式

    请将所有模型配置项放置在系统环境变量中,Midscene 会自动读取这些环境变量。

    以下介绍一些常见方法,你也可以使用自己项目中的其他配置方案。

    方法一:在系统中设置环境变量

    在 Midscene Chrome 插件中,你也可以使用这种 export KEY="value" 配置格式

    # 替换为你自己的 API Key
    export MIDSCENE_MODEL_BASE_URL="https://.../compatible-mode/v1"
    export MIDSCENE_MODEL_API_KEY="sk-abcde..."
    export MIDSCENE_MODEL_NAME="qwen3.7-plus"
    export MIDSCENE_MODEL_FAMILY="qwen3"

    方法二:编写 .env 文件(适用于命令行工具)

    在项目的运行路径下创建一个 .env 文件,并添加以下内容,Midscene 的命令行工具默认会读取这个文件。

    MIDSCENE_MODEL_BASE_URL="https://.../compatible-mode/v1"
    MIDSCENE_MODEL_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"
    MIDSCENE_MODEL_NAME="qwen3.7-plus"
    MIDSCENE_MODEL_FAMILY="qwen3"

    请注意:

    1. 这里不需要在每一行前添加 export
    2. 只有 Midscene 命令行工具会默认读取这个文件。如果使用 JavaScript SDK,请参考下一条手动加载。

    方法三:引用 dotenv 库配置环境变量

    dotenv 是一个零依赖的 npm 包,用于将 .env 文件加载到 Node.js 的环境变量 process.env 中。

    我们的 demo 项目 使用了这种方式。

    # 安装 dotenv
    npm install dotenv --save

    在项目根目录下创建一个 .env 文件,并添加以下内容。注意这里不需要在每一行前添加 export

    MIDSCENE_MODEL_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"

    在脚本中导入 dotenv 模块,导入后它会自动读取 .env 文件中的环境变量。

    import 'dotenv/config';

    其他兼容模型

    以下是一些与 Midscene 兼容、面向自动化场景的小参数模型。它们的参数规模较小,对部署硬件要求更低;但在处理复杂任务或较大页面截图时,能力可能受限。建议先结合实际任务与部署条件进行评估,再选择合适的模型。

    智谱 AutoGLM 系列

    智谱 AutoGLM 是智谱 AI 推出的开源移动端 UI 自动化模型,模型尺寸为 9B。

    Z.AI(国际)BigModel(国内) 获取 API Key 后,可以使用以下配置:

    MIDSCENE_MODEL_BASE_URL="https://open.bigmodel.cn/api/paas/v4" # 或 https://api.z.ai/api/paas/v4
    MIDSCENE_MODEL_API_KEY="......"
    MIDSCENE_MODEL_NAME="autoglm-phone" # 模型名以平台实际模型名为准
    MIDSCENE_MODEL_FAMILY="auto-glm" # 或 "auto-glm-multilingual"

    关于 MIDSCENE_MODEL_FAMILY 配置

    AutoGLM 提供了两个版本的模型,通过 MIDSCENE_MODEL_FAMILY 区分:

    • auto-glm - 对应 AutoGLM-Phone-9B,针对中文环境优化
    • auto-glm-multilingual - 对应 AutoGLM-Phone-9B-Multilingual,支持英语等其他语言场景

    请根据你的应用语言选择合适的版本。

    Note

    AutoGLM 更适合移动端的交互与操作流程。如果要使用 aiAssertaiQuery 等需要页面理解或断言的 API,请额外配置一组 MIDSCENE_INSIGHT_MODEL_... 环境变量,让独立的 Insight 模型负责页面理解。具体可参考模型策略中关于多模型配合的介绍。

    了解更多关于智谱 AutoGLM

    UI-TARS 系列

    你可以在 火山引擎 上使用已部署的 doubao-1.5-ui-tars

    MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
    MIDSCENE_MODEL_API_KEY="...."
    MIDSCENE_MODEL_NAME="ep-2025..." # 来自火山引擎的推理接入点 ID 或模型名称
    MIDSCENE_MODEL_FAMILY="vlm-ui-tars-doubao-1.5"

    关于 MIDSCENE_MODEL_FAMILY 配置

    MIDSCENE_MODEL_FAMILY 用于指定 UI-TARS 版本,使用以下值之一:

    • vlm-ui-tars:用于模型版本 1.0
    • vlm-ui-tars-doubao:用于在火山引擎上部署的模型版本 1.5(与 vlm-ui-tars-doubao-1.5 等效)
    • vlm-ui-tars-doubao-1.5:用于在火山引擎上部署的模型版本 1.5
    Info

    旧版本使用 MIDSCENE_USE_VLM_UI_TARS=DOUBAOMIDSCENE_USE_VLM_UI_TARS=1.5 配置,该配置仍然兼容但已废弃,建议迁移到 MIDSCENE_MODEL_FAMILY

    迁移对应关系:

    • MIDSCENE_USE_VLM_UI_TARS=1.0MIDSCENE_MODEL_FAMILY="vlm-ui-tars"
    • MIDSCENE_USE_VLM_UI_TARS=1.5MIDSCENE_MODEL_FAMILY="vlm-ui-tars-doubao-1.5"
    • MIDSCENE_USE_VLM_UI_TARS=DOUBAOMIDSCENE_MODEL_FAMILY="vlm-ui-tars-doubao"

    多模型组合示例

    关于组合多个模型的更多信息,可查阅 高阶特性:多模型配合

    下面以 GPT-5.4 用于 Planning/Insight、Qwen 3.5 负责视觉为例。GPT-5.4 处理重度推理(Planning 和/或 Insight),Qwen 3.5 专注视觉定位。独立的 Planning 和 Insight 模型可按需启用,不需要同时开启。

    # 默认多模态模型:Qwen 3.5
    export MIDSCENE_MODEL_BASE_URL="https://..."       # Qwen 3.5 接口地址
    export MIDSCENE_MODEL_API_KEY="..."                # 你的 Qwen 3.5 API Key
    export MIDSCENE_MODEL_NAME="qwen3.5-plus"
    export MIDSCENE_MODEL_FAMILY="qwen3.5"
    
    # Planning 模型:GPT-5.4
    export MIDSCENE_PLANNING_MODEL_API_KEY="sk-..."    # 你的 GPT-5.4 API Key
    export MIDSCENE_PLANNING_MODEL_BASE_URL="https://..."
    export MIDSCENE_PLANNING_MODEL_NAME="gpt-5.4"
    export MIDSCENE_PLANNING_MODEL_FAMILY="gpt-5"
    
    # Insight 模型:GPT-5.4
    export MIDSCENE_INSIGHT_MODEL_API_KEY="sk-..."     # 你的 GPT-5.4 API Key
    export MIDSCENE_INSIGHT_MODEL_BASE_URL="https://..."
    export MIDSCENE_INSIGHT_MODEL_NAME="gpt-5.4"
    export MIDSCENE_INSIGHT_MODEL_FAMILY="gpt-5"

    更多

    更多高阶配置请查看 全部配置项 文档。

    模型服务连接问题排查

    Midscene 内置了一个模型验证命令,用于排查模型服务的连通性问题和基础的兼容性问题。

    将你的模型配置放在 .env 文件中,然后运行下面的模型验证命令,验证当前模型配置是否能支撑 Midscene 正常运行:

    # 如果当前项目已安装 @midscene/cli,可以使用本地的 midscene 命令
    npx midscene model verify
    
    # 如果当前项目未安装 @midscene/cli,或想要使用最新版
    npx @midscene/cli@latest model verify

    这个命令会读取当前工作目录下的 .env 文件,同时打开 Dotenv 的 debug 日志,且 .env 中的变量会覆盖已有的 shell 环境变量。

    为了单独排查模型服务的基础连接性问题,你也可以直接运行下面这段最小化的 curl 请求。

    MIDSCENE_MODEL_BASE_URL='替换为你的 baseUrl'
    MIDSCENE_MODEL_API_KEY='替换为你的 API Key'
    MIDSCENE_MODEL_NAME='替换为你的 model name'
    
    curl -X POST "${MIDSCENE_MODEL_BASE_URL%/}/chat/completions" \
      -H "Authorization: Bearer ${MIDSCENE_MODEL_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
      "model": "'"${MIDSCENE_MODEL_NAME}"'",
      "messages": [
        {
          "role": "user",
          "content": "What is 1+1?"
        }
      ]
    }'