下载安装
下载安装并启动设备智能体后，打开控制台即可创建设备智能体并接入 MQTT 设备。
安装位置
设备智能体支持 macOS、Linux 和 Windows，可以安装到开发电脑、边缘网关、Linux 工控机或私有服务器。 安装环境需要能够访问 MQTT 服务和大模型服务，并开放控制台端口，默认端口为 3000。
- 本地体验：安装在开发电脑上，通过
http://127.0.0.1:3000访问控制台。 - 现场运行：安装在边缘网关、Linux 工控机或私有服务器上，让它靠近设备网络运行，并通过服务器 IP 访问控制台。
建议硬件配置
| 配置 | CPU | 内存 | 磁盘 | 适用场景 |
|---|---|---|---|---|
| 最小配置 | 2 核 | 512 MB | 300 MB 可用空间 | 本地体验、Demo 和小型板端部署 |
| 推荐配置 | 2-4+ 核 | 1 GB+ | 1 GB 可用空间 | 长期稳定现场运行 |
准备
设备智能体需要连接 MQTT Broker 和大模型服务。安装前请确认：
- MQTT 服务地址和认证信息
- 大模型服务商、模型名称和 API Key
- 浏览器可以访问设备智能体控制台端口，默认为
3000
准备 MQTT Broker
如果还没有 MQTT 服务，最快方式是在首次启动时设置 ZERO_EMQX_ENABLED=true。启动时会自动创建一个临时 Zero EMQX Broker，并写入 MQTT 配置。该 Broker 实例由 EMQX Cloud 提供，会自动过期，不适合长期运行。 其他 MQTT Broker 方案见 准备 MQTT Broker。
准备大模型配置
快速体验需要一个支持工具调用的大模型。首次启动时设置 LLM_PROVIDER、LLM_MODEL 和对应 API Key；也可以启动后在控制台 设置 → 模型 中填写。更多服务商、字段和本地模型说明见 大模型配置。
下载安装
macOS 和 Linux
curl -fsSL https://emqx.sh/device-agent | sh
device-agent --versionWindows PowerShell
irm https://emqx.sh/device-agent.ps1 | iex
device-agent --version配置
首次体验建议直接在启动命令前设置环境变量：
ZERO_EMQX_ENABLED=true \
LLM_PROVIDER=openai \
LLM_MODEL=gpt-5.5 \
OPENAI_API_KEY=sk-... \
device-agent已有 MQTT Broker 时，把 ZERO_EMQX_ENABLED=true 换成 MQTT_BROKER_URL、VITE_MQTT_WS_URL、 MQTT_USERNAME 和 MQTT_PASSWORD。长期部署再使用 .env 或 config.json；完整变量见 环境变量，MQTT 示例见 准备 MQTT Broker。
启动并验证
如果上一步没有启动，运行：
device-agent然后打开控制台：
http://127.0.0.1:3000如果需要通过服务器 IP 或局域网地址访问控制台，请设置监听地址。3000 是默认端口，只有需要修改端口时才替换为目标端口：
AGENT_GATEWAY_HTTP_HOST=0.0.0.0
AGENT_GATEWAY_HTTP_PORT=3000如果能进入创建设备智能体流程，并看到 MQTT 连接状态正常，即表示安装可用。
更新
macOS、Linux 和 Windows：
device-agent update更新完成后重启设备智能体。
卸载设备智能体
先停止正在运行的设备智能体。
macOS 和 Linux
删除安装目录和启动器：
rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/device-agent"
rm -f ~/.local/bin/device-agent如需同时删除运行时配置和本地数据：
rm -rf ~/.device_agent如果安装时使用了自定义路径：删除 DEVICE_AGENT_INSTALL_DIR 指向的安装目录，以及 DEVICE_AGENT_BIN_DIR 下的 device-agent 启动器。
Windows PowerShell
删除安装目录和启动器：
$root = Join-Path $env:LOCALAPPDATA "Programs\DeviceAgent"
Remove-Item -LiteralPath $root -Recurse -Force如需同时删除运行时配置和本地数据：
Remove-Item -LiteralPath (Join-Path $HOME ".device_agent") -Recurse -Force如果安装时使用了自定义路径：删除 DEVICE_AGENT_INSTALL_DIR 指向的安装目录，以及 DEVICE_AGENT_BIN_DIR 下的 device-agent.cmd 启动器。