前置条件
一个简短的、你真正需要的清单。
在你的电脑上
| 是什么 | 用来干嘛 |
|---|---|
espctl 程序 | 它是你的 AI 工具和构建服务器之间的桥。下载现成的二进制文件就行,不需要从源码构建。 |
| 一个支持 MCP 的 AI 工具 | Claude Code、Cursor、Claude Desktop、Codex CLI 或 OpenCode。挑你已经在用的那个。见第二部分 — 客户端配置。 |
| 一个互联网连接 | 只在真正构建的时候要。如果你只想看一看、规划一下(不真的构建),可以离线用。 |
就这些。你不需要:
- 在本地装 ESP-IDF。构建服务器有。
- Python、C/C++ 工具链或者其他编译器。构建服务器也有。
- Rust 工具链。只有从源码自己构建 espctl 才需要 —— 而你不需要这么 做,因为有现成的下载。
在网络上
真正构建的时候,你的电脑通过和浏览器一样的端口(80/443)和构建 服务器对话。没什么特别的。
如果你的网络很严格、把 UDP 全屏蔽了,构建仍然能跑 —— 只是会走 一个慢一点的备选路径。你不需要配置任何东西;这是自动的。
一个账号
你需要构建服务器给你的访问密钥。把它当密码看：不要粘到截图里、 不要传到公开仓库、如果觉得别人可能看到了就换一个。
如果你用 esphome.cloud,访问密钥在你注册 的时候发。如果你跑自己的构建服务器,运维会给你一个。
拿到密钥后,保存它:
espctl login --token <你的访问密钥>
这会把你的凭据存到 ~/.config/espctl/credentials.json,CLI 用法
只需要这个就够了。MCP 服务器模式（AI 工具集成）还需要在 AI 工具
的配置里设置 CONTROL_BASE_URL 和 MCP_AUTH_SECRET ——
见快速开始第 3 步。
快速 checklist
- 硬盘上有
espctl,你知道完整路径 - 装了一个支持 MCP 的 AI 工具（Claude Code、Cursor、Codex、 OpenCode 或 Claude Desktop）
- 来自构建服务器的访问密钥
- 跑过
espctl login --token <密钥>（CLI 用法） - 在 AI 工具配置里设了
CONTROL_BASE_URL+MCP_AUTH_SECRET（MCP 服务器模式）
都齐了,直接看快速开始。