环境变量索引
本手册中提到的所有环境变量,集中在一张表里。
启用远程构建模式
设置以下两个,把 MCP 服务升级到远程构建模式。见 仅计划模式 vs 远程构建。
| 变量 | 必需? | 默认 | 说明 |
|---|---|---|---|
CONTROL_BASE_URL | 否 | — | 构建服务器的 URL(例如 https://esphome.cloud)。必须包含 scheme。没有这个,所有 build 调用都会返回错误说明当前模式。 |
MCP_AUTH_SECRET | 否 | — | 构建服务器的鉴权 token,从构建服务器主机的 /etc/aegis/secrets.env 拿。当 API key 对待。没有这个,对 /grant/request 的调用会返回 401。 |
espctl CLI 在用户机器上使用
由用户机器上的 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。 |
构建服务器使用(运维关注)
这些不在用户机器上设置 —— 是给运行构建服务器主机的运维。
| 变量 | 必需? | 默认 | 说明 |
|---|---|---|---|
ALLOWED_ORIGINS | 是 | — | 允许调用 /grant/* 和 /signaling/* 的精确 origin 列表(逗号分隔)。包含 scheme;不要用通配符。例:https://esphome.cloud,https://www.esphome.cloud。 |
CONTROL_PUBLIC_BASE_URL | 是 | — | 构建服务器的公开 URL,在某些响应 body 和许可字段中使用。必须与实际部署的 URL 匹配。 |
TURN_EXTERNAL_IP | 是 | — | 备选服务器的公网 IP(通常和构建服务器同一台主机)。 |
MCP_AUTH_SECRET | 是 | — | master 鉴权 token。通过同一个环境变量发给客户端。 |
AGENT_AUTH_SECRET | 是 | — | 构建机器用来向构建服务器注册的鉴权 token。 |
构建机器使用(运维关注)
| 变量 | 必需? | 默认 | 说明 |
|---|---|---|---|
CONTROL_BASE_URL | 是 | — | 构建机器用来查看任务的 URL。必须是可路由 URL,不是 SSH 别名。安装器默认 https://3qMq,在大多数环境里会因 DNS 错误失败 —— 安装后编辑 /etc/aegis/agent.env。 |
AGENT_PUBLIC_IP | 否 | 自动发现 | 构建机器报给构建服务器的公网 IP。未设置时自动发现,但在某些网络限制后自动发现可能不可靠。 |
AGENT_AUTH_SECRET | 是 | — | 向构建服务器注册的鉴权 token。和构建服务器侧值相同。 |
ESPCTL_STORE_ROOT | 是 | — | 构建机器应该使用的工具链 store 路径。 |
RUST_LOG | 否 | info | 日志级别。RUST_LOG=debug 产生详细日志。 |
type-driven-ui 前端使用
这些是 Vite 环境变量,前缀 VITE_。它们在构建时被 bake 进 bundle,
不是运行时读取的。
| 变量 | 必需? | 默认 | 说明 |
|---|---|---|---|
VITE_API_BASE_URL | 否 | (空) | 前端调用构建服务器用的 base URL。空字符串表示同源(在反向代理后部署时推荐)。本地开发针对同机构建服务器,设为 http://localhost:8080。 |
构建系统自动设置
这些通常不手动设置,但出现在一些日志和配置文件里。
| 变量 | 由谁设置 | 说明 |
|---|---|---|
IDF_PATH | 构建机器(在沙箱里) | 沙箱里被选中的 IDF 版本路径。不要在客户端配置中覆盖;让构建机器设。 |
PKG_TEMP_DIR | release 脚本 | makeself 包在构建主机上的暂存位置。 |
TMPDIR | release 脚本 | 打包时使用的临时目录 —— 在构建主机上设置，当 /tmp 是小 tmpfs 时使用。 |
速查:在新用户机器上要设什么
对一个 MCP 用户(CLI/IDE 流程),你只需要在客户端配置(例如
.claude/settings.json)里设两个环境变量:
CONTROL_BASE_URL = https://esphome.cloud # 你的构建服务器 URL
MCP_AUTH_SECRET = <从运维那里拿>
对一个浏览器用户(esphome.cloud 流程),你什么都不用设 —— 浏览器 通过同源 REST API 直接和构建服务器对话。