快速开始(5 分钟)
从“什么都没装“到“我的第一次构建成功了“的最快路径。
1. 拿到 espctl 工具
你的电脑上需要 espctl 这个程序。从
aegis 发布页 下载一个现成
的二进制文件,放到硬盘上。记住放在哪里 —— 第 3 步要用它的完整路径。
(你也可以从源码自己编译,但不需要。)
2. 登录
从运营你构建服务器的人那里拿到访问密钥（或者从 esphome.cloud 自己拿），然后运行:
espctl login --token <你的访问密钥>
这会保存你的凭据。从此以后,每次 espctl build 都会自动发到你的
构建服务器。
你不需要装 ESP-IDF,不需要工具链,什么都不需要。这些东西构建服务器 都已经有了。
3. 告诉你的 AI 工具怎么启动 espctl（MCP 服务器）
如果你想让 AI 助手使用 espctl,挑你用的工具,看对应那一章 —— 每一章都只有 3 行配置:
所有工具的形式都一样:你告诉工具去运行 /path/to/espctl mcp serve,
环境变量里带上你的构建服务器地址和访问密钥。（MCP 服务器用环境变量
CONTROL_BASE_URL 和 MCP_AUTH_SECRET —— 这和 espctl login
是分开的,后者是给 CLI 用的。）
重启你的 AI 工具,让它加载新配置。
4. 看看是不是工作了
在你 AI 工具的对话框里问:
你有哪些 espctl 工具?
你应该看到大约 40 件它能做的事 —— build、doctor、
store_versions 等等。如果没看到,看故障排查。
然后问:
运行 doctor。
应该返回一份“healthy“报告。如果有失败,再看看第 2 步的构建服务器 地址和访问密钥。
5. 构建你的第一个固件
打开任何一个 ESP-IDF 项目的目录（或者让助手新建一个），然后说:
帮我构建成 esp32s3 的固件,如果有问题告诉我。
espctl build 默认就是远程构建 —— 不需要 --remote 参数。你的助手会:
- 把构建发给构建服务器。
- 看着它跑（可能要几分钟）。
- 给你结果：要么“构建成功,固件 X KB,这是细分“,要么“构建在第 N 行 失败,这是用大白话讲的错误“。
构建成功后,你可以让助手下载固件文件,或者直接交给烧录器。
5b. 预检硬件(可选)
在烧录之前,CLI 有三个快速命令可以确认板子接好了、准备好了:
# 看哪些串口可见
espctl ports
# 这个端口上是什么芯片?
espctl probe --port /dev/cu.usbmodem1101
# 烧录你构建出来的烧录包
espctl flash ./build/flash_bundle.tar.gz --port /dev/cu.usbmodem1101
完整参考见 固件与烧录,包括用
espctl monitor 查看串口实时输出。
6. 接下来去哪儿
就这些。你已经上路了。