配置你的模型
一个快速默认配置
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 系列
环境变量配置示例,以 doubao-seed-2.1-turbo 为例:
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"
MIDSCENE_PLANNING_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" # 火山引擎地址
MIDSCENE_PLANNING_MODEL_API_KEY="...."
MIDSCENE_PLANNING_MODEL_NAME="doubao-seed-2.1-turbo"
MIDSCENE_PLANNING_MODEL_FAMILY="doubao-seed"
MIDSCENE_INSIGHT_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" # 火山引擎地址
MIDSCENE_INSIGHT_MODEL_API_KEY="...."
MIDSCENE_INSIGHT_MODEL_NAME="doubao-seed-2.1-turbo"
MIDSCENE_INSIGHT_MODEL_FAMILY="doubao-seed"
如果你的火山引擎账号已开通低延迟模式(Fast),可以追加以下请求体参数来使用该能力。通常可将模型响应速度提升约 30% 至 50%。
MIDSCENE_MODEL_EXTRA_BODY_JSON={"service_tier":"fast"}
兼容性说明
为兼容已有配置,仍支持 MIDSCENE_MODEL_FAMILY="doubao-vision";新配置建议使用 doubao-seed。
千问 Qwen 系列
环境变量配置示例,以 qwen3.7-plus 为例:
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
MIDSCENE_PLANNING_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" # 阿里云地址
MIDSCENE_PLANNING_MODEL_API_KEY="......"
MIDSCENE_PLANNING_MODEL_NAME="qwen3.7-plus"
MIDSCENE_PLANNING_MODEL_FAMILY="qwen3" # 如果你使用了其他版本的 Qwen,需要替换为对应的 model family
MIDSCENE_INSIGHT_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" # 阿里云地址
MIDSCENE_INSIGHT_MODEL_API_KEY="......"
MIDSCENE_INSIGHT_MODEL_NAME="qwen3.7-plus"
MIDSCENE_INSIGHT_MODEL_FAMILY="qwen3" # 如果你使用了其他版本的 Qwen,需要替换为对应的 model family
Google Gemini 系列
环境变量配置示例,以 gemini-3.5-flash 为例:
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"
MIDSCENE_PLANNING_MODEL_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/" # Google Gemini API 地址
MIDSCENE_PLANNING_MODEL_API_KEY="......"
MIDSCENE_PLANNING_MODEL_NAME="gemini-3.5-flash"
MIDSCENE_PLANNING_MODEL_FAMILY="gemini"
MIDSCENE_INSIGHT_MODEL_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/" # Google Gemini API 地址
MIDSCENE_INSIGHT_MODEL_API_KEY="......"
MIDSCENE_INSIGHT_MODEL_NAME="gemini-3.5-flash"
MIDSCENE_INSIGHT_MODEL_FAMILY="gemini"
OpenAI GPT 系列
环境变量配置示例,以 gpt-5.5 为例:
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"
MIDSCENE_PLANNING_MODEL_BASE_URL="https://api.openai.com/v1" # OpenAI API 地址;或你的兼容服务地址
MIDSCENE_PLANNING_MODEL_API_KEY="sk-..."
MIDSCENE_PLANNING_MODEL_NAME="gpt-5.5"
MIDSCENE_PLANNING_MODEL_FAMILY="gpt-5"
MIDSCENE_INSIGHT_MODEL_BASE_URL="https://api.openai.com/v1" # OpenAI API 地址;或你的兼容服务地址
MIDSCENE_INSIGHT_MODEL_API_KEY="sk-..."
MIDSCENE_INSIGHT_MODEL_NAME="gpt-5.5"
MIDSCENE_INSIGHT_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-mini、gpt-5.4-nano 等更小的 GPT-5 变体以及前代模型不支持 original 参数,会导致报错。详情请参考 Images and Vision guide 和 Computer use guide。
- 按照 OpenAI 的文档,GPT-5 在处理非拉丁字母文本、字号太小的文本时效果可能不理想,参见 Images and Vision guide。
- OpenAI 在 computer use 文档中提到,他们观察到
1440x900 和 1600x900 这两种截图尺寸上通常能获得比较好的效果,详见 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_BUDGET 和 MIDSCENE_MODEL_REASONING_EFFORT 等额外控制项。详见模型原生的思考模式。
月之暗面 Kimi 系列
环境变量配置示例,以 kimi-k3 为例:
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"
MIDSCENE_PLANNING_MODEL_BASE_URL="https://api.moonshot.cn/v1" # Moonshot AI API 地址
MIDSCENE_PLANNING_MODEL_API_KEY="......"
MIDSCENE_PLANNING_MODEL_NAME="kimi-k3"
MIDSCENE_PLANNING_MODEL_FAMILY="kimi3" # 如果使用 kimi-k2.6,请改为 "kimi"
MIDSCENE_INSIGHT_MODEL_BASE_URL="https://api.moonshot.cn/v1" # Moonshot AI API 地址
MIDSCENE_INSIGHT_MODEL_API_KEY="......"
MIDSCENE_INSIGHT_MODEL_NAME="kimi-k3"
MIDSCENE_INSIGHT_MODEL_FAMILY="kimi3" # 如果使用 kimi-k2.6,请改为 "kimi"
小米 MiMo 系列
环境变量配置示例,以 mimo-v2.5 为例:
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"
MIDSCENE_PLANNING_MODEL_BASE_URL="https://api.xiaomimimo.com/v1" # 小米 MiMo API 地址
MIDSCENE_PLANNING_MODEL_API_KEY="......"
MIDSCENE_PLANNING_MODEL_NAME="mimo-v2.5"
MIDSCENE_PLANNING_MODEL_FAMILY="xiaomi-mimo"
MIDSCENE_INSIGHT_MODEL_BASE_URL="https://api.xiaomimimo.com/v1" # 小米 MiMo API 地址
MIDSCENE_INSIGHT_MODEL_API_KEY="......"
MIDSCENE_INSIGHT_MODEL_NAME="mimo-v2.5"
MIDSCENE_INSIGHT_MODEL_FAMILY="xiaomi-mimo"
智谱 GLM-V 系列
环境变量配置示例,以 glm-5v-turbo 为例:
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"
MIDSCENE_PLANNING_MODEL_BASE_URL="https://open.bigmodel.cn/api/paas/v4" # BigModel API 地址;Z.AI 使用 https://api.z.ai/api/paas/v4
MIDSCENE_PLANNING_MODEL_API_KEY="......"
MIDSCENE_PLANNING_MODEL_NAME="glm-5v-turbo"
MIDSCENE_PLANNING_MODEL_FAMILY="glm-v"
MIDSCENE_INSIGHT_MODEL_BASE_URL="https://open.bigmodel.cn/api/paas/v4" # BigModel API 地址;Z.AI 使用 https://api.z.ai/api/paas/v4
MIDSCENE_INSIGHT_MODEL_API_KEY="......"
MIDSCENE_INSIGHT_MODEL_NAME="glm-5v-turbo"
MIDSCENE_INSIGHT_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"
请注意:
- 这里不需要在每一行前添加
export。
- 只有 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 文件中的环境变量。
其他兼容模型
以下是一些与 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 更适合移动端的交互与操作流程。如果要使用 aiAssert、aiQuery 等需要页面理解或断言的 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=DOUBAO 或 MIDSCENE_USE_VLM_UI_TARS=1.5 配置,该配置仍然兼容但已废弃,建议迁移到 MIDSCENE_MODEL_FAMILY。
迁移对应关系:
MIDSCENE_USE_VLM_UI_TARS=1.0 → MIDSCENE_MODEL_FAMILY="vlm-ui-tars"
MIDSCENE_USE_VLM_UI_TARS=1.5 → MIDSCENE_MODEL_FAMILY="vlm-ui-tars-doubao-1.5"
MIDSCENE_USE_VLM_UI_TARS=DOUBAO → MIDSCENE_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?"
}
]
}'