• 简体中文
  • 支持的模型与配置

    本文帮助你选择 Midscene 支持的模型、完成首次配置,并验证模型连接。

    本页列出的模型配置,本质上都是环境变量。你可以根据使用方式提供这些配置:

    • 使用 Playground 时,在设置页面直接粘贴本页的配置文本。
    • 使用 SDK 或命令行工具时,按照设置环境变量中的说明加载配置。

    如需了解模型职责,请阅读模型策略。如需查询完整参数,请阅读模型配置参考

    支持的模型

    Midscene 支持使用以下多模态模型操作界面。每份配置都需要 Base URL、API Key、模型名称和 MIDSCENE_MODEL_FAMILY。模型系列(MIDSCENE_MODEL_FAMILY)决定了 Midscene 如何适配所选模型。

    豆包 Seed 系列

    模型版本常用模型名称MIDSCENE_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 系列。为兼容已有配置,仍支持 MIDSCENE_MODEL_FAMILY="doubao-vision";新配置建议使用 doubao-seed

    环境变量配置示例,以 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 Tier),可以追加以下请求体参数来使用该能力。通常可将模型响应速度提升约 30% 至 50%。

    MIDSCENE_MODEL_EXTRA_BODY_JSON={"service_tier":"fast"}

    千问 Qwen 系列

    模型版本常用模型名称MIDSCENE_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

    Google Gemini 系列

    模型版本常用模型名称MIDSCENE_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"

    OpenAI GPT 系列

    • 常用模型供应商:OpenAI
    模型版本常用模型名称MIDSCENE_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)

    如果你已经通过 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 确认登录状态。
    已知限制

    相比于直接调用 OpenAI 兼容 API,我们观察到这种方式可能耗时更长、token 消耗更多,具体原因还在排查中。

    使用 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,建议只将其用作规划模型,并搭配其他多模态模型完成定位,参考多模型组合示例

    月之暗面 Kimi 系列

    模型版本常用模型名称MIDSCENE_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 系列

    模型版本常用模型名称MIDSCENE_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 系列

    模型版本常用模型名称MIDSCENE_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 从环境变量读取模型配置。请选择与你的使用方式对应的方法,也可以沿用项目已有的环境变量管理方式。

    在当前 Shell 中设置环境变量

    以下示例适用于 Bash 和 Zsh。变量只在当前 Shell 会话及其启动的子进程中有效。

    # 将全部值替换为所选模型服务商提供的配置
    export MIDSCENE_MODEL_BASE_URL="https://替换为你的模型服务地址/v1"
    export MIDSCENE_MODEL_API_KEY="替换为你的 API Key"
    export MIDSCENE_MODEL_NAME="替换为你的模型名称"
    export MIDSCENE_MODEL_FAMILY="替换为你的模型对应的 family"

    通过 CLI 加载 .env

    在运行 midscene 命令时所在的目录中创建 .env 文件。@midscene/cli 会自动读取这个文件。

    # 将全部值替换为所选模型服务商提供的配置
    MIDSCENE_MODEL_BASE_URL="https://替换为你的模型服务地址/v1"
    MIDSCENE_MODEL_API_KEY="替换为你的 API Key"
    MIDSCENE_MODEL_NAME="替换为你的模型名称"
    MIDSCENE_MODEL_FAMILY="替换为你的模型对应的 family"

    .env 中的每一行都不需要添加 export。运行 YAML 任务时,当前 Shell 中已有的同名变量默认优先于 .env。如需让 .env 覆盖它们,请使用 --dotenv-override

    midscene model verify 是例外。该命令会使用 .env 中的值覆盖当前 Shell 中的同名变量。

    通过 dotenv 为 JavaScript SDK 加载 .env

    Midscene JavaScript SDK 直接读取 Node.js 进程中的模型配置环境变量(process.env)。如果 Shell、容器或部署平台已经提供这些变量,无需安装 dotenv。如果配置保存在 .env 文件中,可以使用 dotenv 将文件中的变量加载到 process.env

    npm
    yarn
    pnpm
    bun
    deno
    npm install dotenv

    在运行脚本时所在的目录中创建 .env 文件:

    # 将全部值替换为所选模型服务商提供的配置
    MIDSCENE_MODEL_BASE_URL="https://替换为你的模型服务地址/v1"
    MIDSCENE_MODEL_API_KEY="替换为你的 API Key"
    MIDSCENE_MODEL_NAME="替换为你的模型名称"
    MIDSCENE_MODEL_FAMILY="替换为你的模型对应的 family"

    在创建 Midscene Agent 之前导入 dotenv:

    import 'dotenv/config';

    如果当前 Shell 已有同名变量,dotenv 默认保留现有值。Midscene 示例项目也使用了这种加载方式。

    验证配置

    设置环境变量后,运行以下任一命令:

    # 使用当前项目中安装的 CLI
    npx midscene model verify
    
    # 或使用最新版本的 CLI
    npx @midscene/cli@latest model verify

    如果验证失败,请阅读模型调试与可观测性

    配置多个模型(可选)

    多模型配置不是必需项。大多数场景只需配置默认模型,即可完成 UI 定位和操作。仅当复杂规划或页面理解需要使用独立模型时,才需要配置 Planning 模型或 Insight 模型。你可以只配置其中一个,也可以同时配置两者。

    如需了解何时组合多个模型,请阅读模型策略

    以下示例使用 Qwen 3.5 作为默认模型,负责视觉定位。GPT-5.4 作为 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 兼容,主要面向自动化场景。它们对部署硬件的要求较低,但处理复杂任务或大尺寸截图的能力可能受限。选择前,请结合实际任务和部署条件进行评估。

    智谱 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,支持英语等其他语言场景

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

    Info

    AutoGLM 更适合移动端交互。aiAssertaiQuery 等 API 需要理解页面。使用这些 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"

    下一步