下载安装
本页介绍如何下载、安装并启动设备智能体。完成安装后，你可以打开控制台，开始创建设备智能体并接入 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 服务和模型服务。安装前请确认：
- MQTT 服务地址和认证信息
- 模型服务商、模型名称和 API 密钥
- 浏览器可以访问设备智能体控制台端口，默认为
3000
如果还没有 MQTT 服务，最快方式是让 Agent 创建 Zero EMQX MQTT Broker。它会创建一个临时 Zero EMQX 测试 Broker，并把 MQTTS/WSS 地址和认证信息写入当前配置。该 Broker 实例由 EMQX Cloud 提供。可以直接对 Agent 说：
帮我创建一个 Zero EMQX MQTT Broker 测试实例，并把 MQTT 设置写入当前配置。Agent 创建完成后，在 Settings > MQTT 中保存配置即可应用。也可以在 MQTT 设置页点击 Create test broker，或用命令行创建：
curl -sS -X POST https://zero.emqx.io/v1/instances返回结果里包含 mqtts.uri、wss.uri、credentials.username 和 credentials.password。完整 .env 导出命令，以及 EMQX、EMQX Cloud、EMQX Edge 方案见 准备 MQTT Broker。
下载安装
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配置
设备智能体启动时会读取 .env 文件，用于连接 MQTT 服务和模型服务，并设置或覆盖默认配置。你可以在运行目录中创建 .env。下面的 MQTT 配置请替换为你的 Broker 信息；Zero EMQX、EMQX、EMQX Cloud 和 EMQX Edge 示例见 准备 MQTT Broker：
MQTT_BROKER_URL=mqtt://broker.example.com:1883
MQTT_USERNAME=your-username
MQTT_PASSWORD=your-password
VITE_MQTT_WS_URL=wss://broker.example.com:8084/mqtt
LLM_PROVIDER=openai
LLM_MODEL=gpt-4.1
OPENAI_API_KEY=sk-...启动后，你也可以在控制台的设置页面调整 MQTT、模型、语音和外部接入配置，或直接修改用户目录下的 .device_agent/config.json。更多配置方式见 配置。
启动并验证
启动设备智能体：
device-agent然后打开控制台：
http://127.0.0.1:3000如果需要通过服务器 IP 或局域网地址访问控制台，请在 .env 中设置监听地址。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 启动器。