使用模型 API Key

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

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

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

如需查询高级配置参数，请阅读模型高级配置与调试。

支持的模型

模型选型建议和接入方式见模型选择指南。下面提供各模型的配置示例。

每份配置都需要 Base URL、API Key、模型名称和 MIDSCENE_MODEL_FAMILY。MIDSCENE_MODEL_FAMILY 选择模型适配器，决定坐标处理方式、支持的 API 协议，以及思考和输出参数的发送方式。请使用下方对应模型列出的 family 值。

豆包 Seed 系列

Doubao-Seed-2.1 Turbo

查看配置收起配置

模型 `MIDSCENE_MODEL_NAME`	Model family `MIDSCENE_MODEL_FAMILY`	备注
2.x 系列 `doubao-seed-2-1-pro-260915` `doubao-seed-2-1-turbo-260628`	`doubao-seed`	—
1.x 系列 `Doubao-Seed-1.6-Vision` `Doubao-Seed-1.8`	`doubao-seed`	旧版本。

配置示例（doubao-seed-2-1-turbo-260628）：

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"

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

MIDSCENE_MODEL_EXTRA_BODY_JSON={"service_tier":"fast"}

千问 Qwen 系列

Qwen3.7 Plus

查看配置收起配置

模型 `MIDSCENE_MODEL_NAME`	Model family `MIDSCENE_MODEL_FAMILY`	备注
Qwen3.x 系列 `qwen3.7-plus` `qwen3.5-plus` `qwen3.6-plus`	`qwen3`	`qwen3.5`、`qwen3.6` 作为旧 family 仍然兼容。
Qwen3-VL 系列 `qwen3-vl-plus`	`qwen3-vl`	旧版本。
Qwen2.5-VL 系列 `qwen-vl-max-latest`	`qwen2.5-vl`	旧版本。

配置示例（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

以上阿里云示例使用北京地域；英文版示例使用 Alibaba Cloud 新加坡地域。API Key、Base URL 和模型必须属于同一地域。其他地域的配置见地域与接入地址。

深度求索 DeepSeek 系列

DeepSeek V4.1 Flash

查看配置收起配置

Midscene 从 v1.12.0 开始支持 DeepSeek。

模型 `MIDSCENE_MODEL_NAME`	Model family `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）：

MIDSCENE_MODEL_BASE_URL="https://api.deepseek.com"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="deepseek-flash"
MIDSCENE_MODEL_FAMILY="deepseek"

Google Gemini 系列

Gemini 3.5 Flash

查看配置收起配置

模型 `MIDSCENE_MODEL_NAME`	Model family `MIDSCENE_MODEL_FAMILY`	备注
Gemini 4 Argon `gemini-4-argon`	`gemini`	—
Gemini 3.x 系列 `gemini-3.5-flash` `gemini-3-flash-preview`	`gemini`	—

配置示例（gemini-3.5-flash）：

MIDSCENE_MODEL_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="gemini-3.5-flash"
MIDSCENE_MODEL_FAMILY="gemini"

OpenAI GPT 系列

GPT-6 Sol

查看配置收起配置

Info

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

模型 `MIDSCENE_MODEL_NAME`	Model family `MIDSCENE_MODEL_FAMILY`	备注
GPT-6 系列 `gpt-6-astra` `gpt-6-sol` `gpt-6-luna`	`gpt-6`	—
GPT-5 系列 `gpt-5.4` `gpt-5.5` `gpt-5.6-sol` `gpt-5.6-terra` `gpt-5.6-luna`	`gpt-5`	旧版本。

使用 API Key

配置示例（gpt-6-sol）：

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

开启 Fast mode（service_tier="fast"）

GPT-6 Astra 支持 Fast mode，可以追加 service_tier 请求体参数启用：

MIDSCENE_MODEL_NAME="gpt-6-astra"
MIDSCENE_MODEL_FAMILY="gpt-6"
MIDSCENE_MODEL_EXTRA_BODY_JSON='{"service_tier":"fast"}'

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

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

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

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 系列

Kimi K3

查看配置收起配置

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

配置示例（kimi-k3）：

MIDSCENE_MODEL_BASE_URL="https://api.moonshot.cn/v1"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="kimi-k3"
MIDSCENE_MODEL_FAMILY="kimi3" # 如果使用 kimi-k2.6，请改为 "kimi"

小米 MiMo 系列

MiMo V2.6 Pro

查看配置收起配置

模型 `MIDSCENE_MODEL_NAME`	Model family `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）：

MIDSCENE_MODEL_BASE_URL="https://api.xiaomimimo.com/v1"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="mimo-v2.6-pro"
MIDSCENE_MODEL_FAMILY="xiaomi-mimo"

智谱 GLM-V 系列

GLM-5V-Turbo

查看配置收起配置

模型 `MIDSCENE_MODEL_NAME`	Model family `MIDSCENE_MODEL_FAMILY`	备注
GLM-5V 系列 `glm-5v-turbo`	`glm-v`	—
GLM-4.6 系列 `glm-4.6v`	`glm-v`	`glm-4.6v` 是开源模型。

配置示例（glm-5v-turbo）：

MIDSCENE_MODEL_BASE_URL="https://open.bigmodel.cn/api/paas/v4"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="glm-5v-turbo"
MIDSCENE_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

蚂蚁百灵 Ant Ling

Ling-3.0-flash-VL

查看配置收起配置

MIDSCENE_MODEL_BASE_URL="https://api.ant-ling.com/v1"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="Ling-3.0-flash-VL"
MIDSCENE_MODEL_FAMILY="ant-ling"

截图尺寸

我们观察到，图片最长边超过 2000 像素时，定位精度可能下降。建议通过 Agent 的 screenshotShrinkFactor 参数缩放图片。

Jev（实验性）

Jev 1.14.0

查看配置收起配置

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

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

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

# Planning
MIDSCENE_PLANNING_MODEL_BASE_URL="https://api.typesafe.ai/v1"
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"
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"
MIDSCENE_INSIGHT_MODEL_API_KEY="......"
MIDSCENE_INSIGHT_MODEL_NAME="jev-1.14.0"
MIDSCENE_INSIGHT_MODEL_FAMILY="jev"

将相应模型职责配置为 Jev 后，各类任务的处理方式如下：

定位：由 Jev 执行元素定位。
Insight：aiBoolean、aiAssert 和 aiWaitFor 由 Jev 执行判断；aiQuery、aiString、aiNumber 和 aiAsk 由通用默认模型处理。
任务规划：aiAct 中，单击、双击、返回等简单动作由 Jev 规划；输入、滚动等复杂动作由默认模型规划。

上述模型选择依据任务所需的能力。Jev 请求失败时，不会自动切换至默认模型。

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

注意事项

请求地址：使用 Base URL 时，需要包含 /v1，例如 https://api.typesafe.ai/v1，Midscene 会自动追加 /systemone。如果你的接入点未使用 /systemone 路径，可以通过对应模型的 Endpoint 配置完整请求地址，例如 MIDSCENE_LOCATE_MODEL_ENDPOINT="https://example.com/custom/decision"。Endpoint 优先于 Base URL，Midscene 不会再追加路径。
图像输入限制：目前 Jev 最新版本支持的图片最长边仅为 1568 像素，需要通过 Agent 的 screenshotShrinkFactor 参数控制截图尺寸。为避免多次缩放影响图片质量，并兼容 Jev 未来版本的图片尺寸要求，Midscene 不会按照 Jev 某个版本的尺寸要求自动缩放图片。

设置环境变量

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"

通过 `.env` 文件配置

Midscene Test 的脚手架配置会加载配置文件旁的 .env，默认保留已有环境变量。手写配置需要显式加载文件或由 Shell / CI 提供环境变量，详见加载环境变量。旧版 YAML 脚本运行器（@midscene/cli）会自动读取工作目录中的 .env。

使用 Midscene Test 时，在生成的测试项目目录中将 .env.example 复制为 .env，填入模型配置后运行 pnpm test，详见创建测试项目。使用旧版 YAML 脚本运行器时，在运行 midscene 命令的目录中创建 .env。

.env 文件内容示例：

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

.env 中的每一行都不需要添加 export。使用旧版 YAML 脚本运行器时，当前 Shell 中已有的同名变量默认优先于 .env；可通过 --dotenv-override 让文件中的值优先。

JavaScript SDK

Midscene SDK 从 process.env 读取模型配置。编写测试脚本时，可以在自己的测试项目中安装 dotenv，将模型配置放入项目根目录的 .env 文件，并在脚本入口添加 import 'dotenv/config'，然后从项目根目录运行脚本。请在创建 Agent 前加载配置。

其他兼容模型

以下小参数模型也与 Midscene 兼容，主要面向自动化场景。它们对部署硬件的要求较低，但处理复杂任务或大尺寸截图的能力可能受限。选择前，请结合实际任务和部署条件进行评估。

智谱 AutoGLM 系列

AutoGLM-Phone-9B

查看配置收起配置

智谱 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 系列

UI-TARS 1.5

查看配置收起配置

你可以在火山引擎上使用已部署的 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"

下一步

验证模型连接 — 检查已配置的模型能否在 Midscene 中正常使用。
按意图配置模型 — 为规划、定位或页面理解配置专用模型，并查看可展开的配置示例。
常见配置错误 — 排查模型家族、API 地址或模型名称错误。
模型结果不可靠时 — 排查操作错误、目标遗漏或页面理解偏差。

#使用模型 API Key

#支持的模型

#豆包 Seed 系列

#千问 Qwen 系列

#深度求索 DeepSeek 系列

#Google Gemini 系列

#OpenAI GPT 系列

#月之暗面 Kimi 系列

#小米 MiMo 系列

#智谱 GLM-V 系列

#蚂蚁百灵 Ant Ling

#Jev（实验性）

#设置环境变量

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

#通过 .env 文件配置

#其他兼容模型

#智谱 AutoGLM 系列

#UI-TARS 系列

#下一步

使用模型 API Key

支持的模型

豆包 Seed 系列

千问 Qwen 系列

深度求索 DeepSeek 系列

Google Gemini 系列

OpenAI GPT 系列

月之暗面 Kimi 系列

小米 MiMo 系列

智谱 GLM-V 系列

蚂蚁百灵 Ant Ling

Jev（实验性）

设置环境变量

在当前 Shell 中设置环境变量

通过 `.env` 文件配置

其他兼容模型

智谱 AutoGLM 系列

UI-TARS 系列

下一步