配置
Device Agent 可以通过控制台、.device_agent/config.json 或启动环境变量进行配置。日常调整优先使用控制台，部署和批量配置使用配置文件或环境变量。
配置入口
| 入口 | 适用场景 |
|---|---|
| 控制台设置页 | 日常调整 MQTT、模型、语音、IM 通道、权限和 Webhook。 |
.device_agent/config.json | 备份、迁移、批量下发或无 UI 环境。 |
环境变量 / .env | 首次启动、容器、系统服务和密钥注入。 |
开发环境中，.env 通常位于仓库根目录；安装版会从安装目录读取 .env，不是从任意当前目录读取。配置文件运行目录以启动日志中的 Runtime Home 为准，生产运行时通常是 ~/.device_agent。
生效规则
| 配置类型 | 生效方式 |
|---|---|
| 主模型、视觉模型、工具权限、日志、Webhook | 保存后立即生效。 |
| 语音服务商、模型和密钥 | 保存后立即生效；启用状态、监听地址、端口或 TLS 变化需要重启。 |
| MQTT | 控制台保存后会立即重新连接；修改 .env 或配置文件后需要重启。 |
| IM 通道 | 修改后需要重启。 |
| HTTP、HTTPS、数据库和 A2A 身份 | 修改后需要重启。 |
| Web 前端变量 | 修改后需要重启前端服务或重新构建。 |
如果同一配置同时出现在 .env 和控制台中，重启时以 .env 为准。需要保留控制台设置时，请移除 .env 中的同名变量。
最小启动示例
bash
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-5.5
OPENAI_API_KEY=sk-...
AGENT_GATEWAY_HTTP_HOST=127.0.0.1
AGENT_GATEWAY_HTTP_PORT=3000如果需要通过服务器 IP 或局域网访问控制台，将 AGENT_GATEWAY_HTTP_HOST 设置为 0.0.0.0，并按需要调整 AGENT_GATEWAY_HTTP_PORT。
在可信网络中直接访问时，请启用 HTTPS；部署到共享或不可信网络时，还需要使用带身份认证的反向代理、VPN 或同等访问控制。配置方法见 下载安装。