环境变量索引

本手册中你需要在自己的电脑上设置的环境变量,集中在一张表里。

启用远程构建模式

设置以下两个,把 MCP 服务升级到远程构建模式。见仅计划模式 vs 远程构建。

变量	必需?	默认	说明
`CONTROL_BASE_URL`	否	—	构建服务器的 URL(例如 `https://esphome.cloud`)。必须包含 scheme。没有这个,所有 `build` 调用都会返回错误说明当前模式。
`MCP_AUTH_SECRET`	否	—	访问构建服务器的鉴权 token,从控制面签发。当 API key 对待;泄露或怀疑泄露就立即换。没有这个,对 `/grant/request` 的调用会返回 401。

由你机器上的 espctl CLI 读取(尤其是 espctl ide sync)。全部都不强制要求 —— 都有回落路径。

变量	必需?	默认	说明
`DEFAULT_IDF_VERSION`	否	—	当 `--idf-version`、`.idf-version`、`.espctl.toml` 里的 `[idf_version]` 都没指定 IDF 版本时的最后兜底。`espctl ide sync` 和部分构建路径会用。
`ESPCTL_SYSROOT`	否	`~/.espctl/sysroot`	本地 IDE sysroot 的根目录。每个版本的 sysroot 落在 `<base>/<idf-version>/` 下。
`ESPCTL_SERVER`	否	已登录的服务器地址 → `https://esphome.cloud`	`espctl ide sync` 的服务器 URL 覆盖。`--server` 标志的优先级再高一点。
`ESPCTL_ALLOW_INSECURE`	否	未设置	设为 `1` 时允许非 HTTPS 的服务器 URL(仅本地开发用)。影响 `espctl login` 和 `espctl build --remote`。

如果你自己构建网页前端,这些是 Vite 环境变量,前缀 VITE_。它们在构建时被 bake 进 bundle,不是运行时读取的。

变量	必需?	默认	说明
`VITE_API_BASE_URL`	否	(空)	前端调用构建服务器用的 base URL。空字符串表示同源(在反向代理后部署时推荐)。本地开发针对同机构建服务器,设为 `http://localhost:8080`。

对一个 MCP 用户(CLI/IDE 流程),你只需要在客户端配置(例如 .claude/settings.json)里设两个环境变量:

CONTROL_BASE_URL   = https://esphome.cloud            # 你的构建服务器 URL
MCP_AUTH_SECRET    = <控制面给你的访问密钥>

对一个浏览器用户(esphome.cloud 流程),你什么都不用设 —— 浏览器通过同源 REST API 直接和构建服务器对话。