仅计划模式 vs 远程构建
espctl 有两种运行方式。同一个程序、同一组功能 —— 只是它们实际能做 什么不同。
远程构建是默认行为。 当你运行 espctl build 时,它把你的项目
发给构建服务器并编译。只有你明确要求时,才会进入仅计划模式。
远程构建模式（默认）
这是你大部分时间用的模式。
espctl 把你的项目发给构建服务器,构建服务器（在一个安全的沙箱里） 编译它,编好的固件回到你这里。
你能得到：
- “构建“真的会构建。
- 你能看实时构建日志。
- 编好的固件文件出现,你可以下载或者烧录。
- 你可以在构建服务器上打开一个交互式串口监视器。
espctl 把构建发到哪里？ 按以下顺序检查:
--remote <url>参数,如果你传了的话。espctl login保存的服务器地址（在~/.config/espctl/credentials.json里）。https://esphome.cloud（内置默认值）。
所以如果你跑过一次 espctl login --token <你的令牌>,之后每次
espctl build 都会自动发到你保存的服务器。
仅计划模式
你需要主动要求 —— 传 --local 参数:
espctl build --local --target esp32s3
这种模式下,espctl 可以:
- 看你的项目文件,检查设置是不是合法的
- 一步一步告诉你一次构建会做什么
- 读你硬盘上已有的构建输出（日志、固件文件）
- 告诉你构建服务器会用哪些 ESP-IDF 版本和工具（如果它在线的话）
这种模式下,espctl 不能真的编译任何东西。没有构建在跑。
什么时候有用:
- 你在离线（飞机、火车、会议 WiFi）。
- 你在跑构建之前先审查一下。
- 你在学这个工具能做什么,还不想真正动手。
登录
设置远程构建最简单的方式:
espctl login --token <你的访问密钥>
这会把你的令牌和服务器地址保存到
~/.config/espctl/credentials.json。从此以后,每次 espctl build
都用这些凭据。
凭据文件限制为只有所有者可读写（0600 权限）。如果 espctl 检测到 不安全的权限,会发出警告。
必须 HTTPS。 espctl 默认拒绝非 HTTPS 的服务器地址。 仅在本地开发时,你可以设置环境变量
ESPCTL_ALLOW_INSECURE=1来覆盖这一限制。
MCP 服务器模式（给 AI 工具用的）
当 espctl 作为 MCP 服务器运行（espctl mcp serve）时,模式检测
方式不同 —— 它用环境变量而不是命令行参数:
| 环境变量设了什么 | 模式 |
|---|---|
CONTROL_BASE_URL + MCP_AUTH_SECRET 都设了 | 远程构建 |
| 缺少其中任何一个 | 仅计划 |
这是你的 AI 工具配置文件控制的。当你编辑 .claude/settings.json、
.cursor/mcp.json 等时,你就是在为 MCP 服务器进程设置这些环境变量。
在两种模式之间切换
CLI 用户: 想用仅计划模式就传 --local,不传就是远程构建。
不需要改配置。
MCP 服务器用户: 编辑 AI 工具的配置,在 env 块里加上或删掉
CONTROL_BASE_URL 和 MCP_AUTH_SECRET,然后重启 AI 工具。
不能在会话中间切换。
如果你想两种模式都同时可用,就配置两个不同名字的 espctl 条目
（例如 espctl-local 和 espctl-remote）。大多数 AI 工具允许同时
注册多个 MCP 服务。
espctl 怎么知道自己在哪种模式？
CLI（espctl build）
| 你做了什么 | 模式 |
|---|---|
espctl build（已通过 espctl login 登录） | 远程构建（用保存的服务器） |
espctl build（未登录） | 远程构建 → https://esphome.cloud |
espctl build --remote https://my-server.com | 远程构建到指定地址 |
espctl build --local | 仅计划 |
MCP 服务器（espctl mcp serve）
| 你设了什么 | 模式 |
|---|---|
CONTROL_BASE_URL + MCP_AUTH_SECRET | 远程构建 |
| 缺少其中任何一个环境变量 | 仅计划 |
你随时可以让助手“运行 doctor“来确认 —— 报告里包含你是否已登录 以及构建服务器是否可达。