使用模型 API Key

本文介绍如何使用模型服务商提供的 API Key 接入 Midscene，包括完成配置和验证连接。如果你已有 ChatGPT 订阅，也可以参考使用 ChatGPT 订阅文档中的描述操作。

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

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

如需查询完整参数，请阅读模型配置参考。

支持的模型

支持的模型概览和接入方式见模型选择指南。下面提供各模型的配置示例。

每份配置都需要 Base URL、API Key、模型名称和 MIDSCENE_MODEL_FAMILY。模型系列（MIDSCENE_MODEL_FAMILY）决定了 Midscene 如何适配所选模型。

豆包 Seed 系列

常用模型供应商：火山引擎

模型 `MIDSCENE_MODEL_NAME`	`MIDSCENE_MODEL_FAMILY`	备注
2.x 系列 `doubao-seed-2-1-pro-260915` `doubao-seed-2-1-turbo-260628`	`doubao-seed`	`doubao-seed-2-1-turbo-260628` 定位速度快，且效果也很好，推荐使用。
1.x 系列 `Doubao-Seed-1.6-Vision` `Doubao-Seed-1.8`	`doubao-seed`	1.x 系列为豆包的旧版本模型，综合表现已不具竞争力，建议优先使用 2.x 系列。为兼容已有配置，仍支持 `MIDSCENE_MODEL_FAMILY="doubao-vision"`；新配置建议使用 `doubao-seed`。

环境变量配置示例，以 doubao-seed-2-1-turbo-260628 为例：

🤖 用作默认模型

🎯 用作定位模型

🧠 用作 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-260628"
MIDSCENE_MODEL_FAMILY="doubao-seed"

MIDSCENE_LOCATE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" # 火山引擎地址
MIDSCENE_LOCATE_MODEL_API_KEY="......"
MIDSCENE_LOCATE_MODEL_NAME="doubao-seed-2-1-turbo-260628"
MIDSCENE_LOCATE_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-260628"
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-260628"
MIDSCENE_INSIGHT_MODEL_FAMILY="doubao-seed"

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

MIDSCENE_MODEL_EXTRA_BODY_JSON={"service_tier":"fast"}

千问 Qwen 系列

常用模型供应商：阿里云

模型 `MIDSCENE_MODEL_NAME`	`MIDSCENE_MODEL_FAMILY`	备注
Qwen3.x 系列 `qwen3.7-plus` `qwen3.5-plus` `qwen3.6-plus`	`qwen3`	从定位测评的结果看，推荐顺序为 Qwen3.7 > Qwen3.5 > Qwen3.6。`qwen3.5`、`qwen3.6` 作为旧 family 仍然兼容。
Qwen3-VL 系列 `qwen3-vl-plus`	`qwen3-vl`	作为旧版本模型，不推荐使用。建议优先使用 Qwen3.x 系列。
Qwen2.5-VL 系列 `qwen-vl-max-latest`	`qwen2.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

MIDSCENE_LOCATE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" # 阿里云地址
MIDSCENE_LOCATE_MODEL_API_KEY="......"
MIDSCENE_LOCATE_MODEL_NAME="qwen3.7-plus"
MIDSCENE_LOCATE_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

深度求索 DeepSeek 系列

Midscene 从 v1.12.0 开始支持 DeepSeek。

常用模型供应商：DeepSeek - 图像理解

模型 `MIDSCENE_MODEL_NAME`	`MIDSCENE_MODEL_FAMILY`	备注
DeepSeek V4 系列 `deepseek-flash`（V4.1 Flash） `deepseek-v4-flash-vision-exp`（V4 Flash Vision）	`deepseek`	DeepSeek-V4-Pro 不支持视觉输入，不能用于 Midscene。

环境变量配置示例，以 deepseek-flash 为例：

🤖 用作默认模型

🎯 用作定位模型

🧠 用作 Planning 模型

🔎 用作 Insight 模型

MIDSCENE_MODEL_BASE_URL="https://api.deepseek.com" # DeepSeek API 地址
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="deepseek-flash"
MIDSCENE_MODEL_FAMILY="deepseek"

MIDSCENE_LOCATE_MODEL_BASE_URL="https://api.deepseek.com" # DeepSeek API 地址
MIDSCENE_LOCATE_MODEL_API_KEY="......"
MIDSCENE_LOCATE_MODEL_NAME="deepseek-flash"
MIDSCENE_LOCATE_MODEL_FAMILY="deepseek"

MIDSCENE_PLANNING_MODEL_BASE_URL="https://api.deepseek.com" # DeepSeek API 地址
MIDSCENE_PLANNING_MODEL_API_KEY="......"
MIDSCENE_PLANNING_MODEL_NAME="deepseek-flash"
MIDSCENE_PLANNING_MODEL_FAMILY="deepseek"

MIDSCENE_INSIGHT_MODEL_BASE_URL="https://api.deepseek.com" # DeepSeek API 地址
MIDSCENE_INSIGHT_MODEL_API_KEY="......"
MIDSCENE_INSIGHT_MODEL_NAME="deepseek-flash"
MIDSCENE_INSIGHT_MODEL_FAMILY="deepseek"

Google Gemini 系列

常用模型供应商：Google Gemini

模型 `MIDSCENE_MODEL_NAME`	`MIDSCENE_MODEL_FAMILY`	备注
Gemini 3.x 系列 `gemini-3.5-flash` `gemini-3-flash-preview`	`gemini`	`gemini-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"

MIDSCENE_LOCATE_MODEL_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/" # Google Gemini API 地址
MIDSCENE_LOCATE_MODEL_API_KEY="......"
MIDSCENE_LOCATE_MODEL_NAME="gemini-3.5-flash"
MIDSCENE_LOCATE_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 系列

Info

如果想使用 ChatGPT 订阅接入，请参考使用 ChatGPT 订阅。

常用模型供应商：OpenAI

模型 `MIDSCENE_MODEL_NAME`	`MIDSCENE_MODEL_FAMILY`	备注
GPT-6 系列 `gpt-6-astra` `gpt-6-sol` `gpt-6-luna`	`gpt-6`	GPT-6 Sol 定位准确度出色，且价格仅为 GPT-6 Astra 的五分之一；GPT-6 Luna 价格非常便宜，同时具备良好的视觉定位能力。
GPT-5 系列 `gpt-5.4` `gpt-5.5` `gpt-5.6-sol` `gpt-5.6-terra` `gpt-5.6-luna`	`gpt-5`	GPT-5.4 之前的模型不支持视觉定位，仅可用作 Planning 模型或 Insight 模型。在实际定位测试中，GPT-5.5 和 GPT-5.6 的定位效果明显优于 GPT-5.4，建议优先使用 GPT-5.5 或 GPT-5.6。

使用 API Key

环境变量配置示例，以 gpt-6-sol 为例：

🤖 用作默认模型

🎯 用作定位模型

🧠 用作 Planning 模型

🔎 用作 Insight 模型

MIDSCENE_MODEL_BASE_URL="https://api.openai.com/v1" # OpenAI API 地址；或你的兼容服务地址
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"

MIDSCENE_LOCATE_MODEL_BASE_URL="https://api.openai.com/v1" # OpenAI API 地址；或你的兼容服务地址
MIDSCENE_LOCATE_MODEL_API_KEY="......"
MIDSCENE_LOCATE_MODEL_NAME="gpt-6-sol"
MIDSCENE_LOCATE_MODEL_FAMILY="gpt-6"

MIDSCENE_PLANNING_MODEL_BASE_URL="https://api.openai.com/v1" # OpenAI API 地址；或你的兼容服务地址
MIDSCENE_PLANNING_MODEL_API_KEY="......"
MIDSCENE_PLANNING_MODEL_NAME="gpt-6-sol"
MIDSCENE_PLANNING_MODEL_FAMILY="gpt-6"

MIDSCENE_INSIGHT_MODEL_BASE_URL="https://api.openai.com/v1" # OpenAI API 地址；或你的兼容服务地址
MIDSCENE_INSIGHT_MODEL_API_KEY="......"
MIDSCENE_INSIGHT_MODEL_NAME="gpt-6-sol"
MIDSCENE_INSIGHT_MODEL_FAMILY="gpt-6"

开启 Fast mode（service_tier="fast"）

GPT-5.6 Sol 和 GPT-6 Astra 均支持 Fast mode，可以追加 service_tier 请求体参数启用，以 GPT-5.6 Sol 为例：

MIDSCENE_MODEL_NAME="gpt-5.6-sol"
MIDSCENE_MODEL_FAMILY="gpt-5"
MIDSCENE_MODEL_EXTRA_BODY_JSON='{"service_tier":"fast"}'

按照 OpenAI 官方说明，Fast mode 可获得最高 2～2.5 倍的速度，费率为 Standard 费率的两倍。具体速度、价格和使用限制以官方说明为准。

如需复用 Codex CLI 登录，请参考使用 Codex App Server。

使用 GPT 时，请注意以下事项：

使用 GPT 做 UI 定位至少需要 GPT-5.4，Midscene 不支持更早的版本。
按照 OpenAI 的文档，GPT-5 在处理非拉丁字母文本、字号太小的文本时效果可能不理想，参见 Images and Vision guide。
OpenAI 在 computer use 文档中提到，他们观察到 1440x900 和 1600x900 这两种截图尺寸上通常能获得比较好的效果，详见 Computer use guide。因此，建议按照 OpenAI 的推荐对截图尺寸进行调整。在 Midscene 中，你可以通过 Agent 参数里的 screenshotShrinkFactor 控制截图压缩倍率。如果是浏览器自动化，还可以通过浏览器 viewport 指定页面的尺寸和比例。
使用 Azure OpenAI 的 Chat Completions API 时，"detail": "original" 可能未被正确处理，从而造成点击坐标偏移。遇到此问题时，可以切换到 Responses API。详见使用 Azure OpenAI 时点击坐标偏移。

月之暗面 Kimi 系列

常用模型供应商：Moonshot AI 开放平台

模型 `MIDSCENE_MODEL_NAME`	`MIDSCENE_MODEL_FAMILY`	备注
K3 系列 `kimi-k3`	`kimi3`	根据 Kimi 的文档，K3 始终开启思考模式，无法关闭，且推理强度默认为 `max`
K2.x 系列 `kimi-k2.5` `kimi-k2.6`	`kimi`	—

环境变量配置示例，以 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"

MIDSCENE_LOCATE_MODEL_BASE_URL="https://api.moonshot.cn/v1" # Moonshot AI API 地址
MIDSCENE_LOCATE_MODEL_API_KEY="......"
MIDSCENE_LOCATE_MODEL_NAME="kimi-k3"
MIDSCENE_LOCATE_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 API 开放平台

模型 `MIDSCENE_MODEL_NAME`	`MIDSCENE_MODEL_FAMILY`	备注
V2.x 系列 `mimo-v2.6-pro` `mimo-v2.6-flash` `mimo-v2.6-pro-ultraspeed` `mimo-v2.5`	`xiaomi-mimo`	2.6 全系列支持多模态；2.5 仅 Omni 系列支持多模态输入。

环境变量配置示例，以 mimo-v2.6-pro 为例：

🤖 用作默认模型

🎯 用作定位模型

🧠 用作 Planning 模型

🔎 用作 Insight 模型

MIDSCENE_MODEL_BASE_URL="https://api.xiaomimimo.com/v1" # 小米 MiMo API 地址
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="mimo-v2.6-pro"
MIDSCENE_MODEL_FAMILY="xiaomi-mimo"

MIDSCENE_LOCATE_MODEL_BASE_URL="https://api.xiaomimimo.com/v1" # 小米 MiMo API 地址
MIDSCENE_LOCATE_MODEL_API_KEY="......"
MIDSCENE_LOCATE_MODEL_NAME="mimo-v2.6-pro"
MIDSCENE_LOCATE_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.6-pro"
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.6-pro"
MIDSCENE_INSIGHT_MODEL_FAMILY="xiaomi-mimo"

智谱 GLM-V 系列

常用模型供应商：Z.AI（国际）、BigModel（国内）

模型 `MIDSCENE_MODEL_NAME`	`MIDSCENE_MODEL_FAMILY`	备注
GLM-5V 系列 `glm-5v-turbo`	`glm-v`	—
GLM-4.6 系列 `glm-4.6v`	`glm-v`	`glm-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"

MIDSCENE_LOCATE_MODEL_BASE_URL="https://open.bigmodel.cn/api/paas/v4" # BigModel API 地址；Z.AI 使用 https://api.z.ai/api/paas/v4
MIDSCENE_LOCATE_MODEL_API_KEY="......"
MIDSCENE_LOCATE_MODEL_NAME="glm-5v-turbo"
MIDSCENE_LOCATE_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 开源模型

GitHub: https://github.com/zai-org/GLM-V
Hugging Face: https://huggingface.co/zai-org/GLM-4.6V

Jev（实验性）

Jev 是一个做选择的模型，可以用它选择下一步动作、定位界面元素，以及判断条件是否成立。它的优势是速度快、成本低，但不适用于需要复杂推理的任务。

Midscene 对 Jev 的支持是实验性的。

模型供应商：TypeSafe

先配置并保留一个通用模型的默认配置（MIDSCENE_MODEL_*），再追加下面的 Jev 配置。 Jev 用于 Planning、Locate 和 Insight，无法处理的任务仍由通用默认模型完成。默认模型的配置方式参见多模型组合。

复制以下配置，将 Planning、Locate 和 Insight 配置为 Jev：

# Planning
MIDSCENE_PLANNING_MODEL_BASE_URL="https://api.typesafe.ai/v1" # TypeSafe 官方 API 地址
MIDSCENE_PLANNING_MODEL_API_KEY="......"
MIDSCENE_PLANNING_MODEL_NAME="jev-1.14.0"
MIDSCENE_PLANNING_MODEL_FAMILY="jev"

# Locate
MIDSCENE_LOCATE_MODEL_BASE_URL="https://api.typesafe.ai/v1" # TypeSafe 官方 API 地址
MIDSCENE_LOCATE_MODEL_API_KEY="......"
MIDSCENE_LOCATE_MODEL_NAME="jev-1.14.0"
MIDSCENE_LOCATE_MODEL_FAMILY="jev"

# Insight
MIDSCENE_INSIGHT_MODEL_BASE_URL="https://api.typesafe.ai/v1" # TypeSafe 官方 API 地址
MIDSCENE_INSIGHT_MODEL_API_KEY="......"
MIDSCENE_INSIGHT_MODEL_NAME="jev-1.14.0"
MIDSCENE_INSIGHT_MODEL_FAMILY="jev"

Jev 使用 TypeSafe 的 System One 协议，不使用 OpenAI 协议。OpenAI 的部分模型配置不适用于 Jev，包括温度、原生思考、响应格式和流式输出等。

图像输入限制

Jev 要求输入图像的最长边不超过 1568 像素，因此 Midscene 会对超出限制的图像进行等比缩放，并在定位后将结果映射回原图坐标。不足 280 像素的边会补白。该图像处理逻辑后续可能调整。

设置环境变量

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

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

多模型配置示例

模型职责与组合思路见模型选择指南。下面展示默认模型与 Planning、Locate、Insight 模型的配置方式。

保留必填的默认模型配置，再按需添加专用模型；未配置的职责使用默认模型。每个专用模型的服务地址、API Key、模型名称和 family 都需要独立填写。请将示例中的占位值和模型名称替换为服务商提供的实际配置。

# 默认模型
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"

修改配置后，按设置环境变量中的方式重新加载，再运行验证配置中的命令。

其他兼容模型

以下小参数模型也与 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 更适合移动端交互。aiAssert 和 aiQuery 等 API 需要理解页面。使用这些 API 时，请通过 MIDSCENE_INSIGHT_MODEL_... 环境变量配置独立的 Insight 模型。详情请参考模型选择指南。

了解更多关于智谱 AutoGLM

GitHub: https://github.com/zai-org/Open-AutoGLM
Hugging Face: https://huggingface.co/zai-org/AutoGLM-Phone-9B

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"

下一步

在模型选择指南中了解何时使用 Default、Planning 和 Insight 模型。
在模型配置参考中查询全部环境变量。
在模型调试与可观测性中排查连接和兼容性问题。

#使用模型 API Key

#支持的模型

#豆包 Seed 系列

#千问 Qwen 系列

#深度求索 DeepSeek 系列

#Google Gemini 系列

#OpenAI GPT 系列

#月之暗面 Kimi 系列

#小米 MiMo 系列

#智谱 GLM-V 系列

#Jev（实验性）

#设置环境变量

#在当前 Shell 中设置环境变量

#通过 CLI 加载 .env

#通过 dotenv 为 JavaScript SDK 加载 .env

#验证配置

#多模型配置示例

#其他兼容模型

#智谱 AutoGLM 系列

#UI-TARS 系列

#下一步

使用模型 API Key

支持的模型

豆包 Seed 系列

千问 Qwen 系列

深度求索 DeepSeek 系列

Google Gemini 系列

OpenAI GPT 系列

月之暗面 Kimi 系列

小米 MiMo 系列

智谱 GLM-V 系列

Jev（实验性）

设置环境变量

在当前 Shell 中设置环境变量

通过 CLI 加载 `.env`

通过 dotenv 为 JavaScript SDK 加载 `.env`

验证配置

多模型配置示例

其他兼容模型

智谱 AutoGLM 系列

UI-TARS 系列

下一步