配置
Device Agent 的配置来自三个入口：控制台设置页、.device_agent/config.json 和工作区根目录的 .env。日常使用优先在控制台设置页修改；自动化部署、首次启动和少量启动参数使用 .env；需要备份、迁移或批量下发时再直接处理配置文件。
配置入口
| 入口 | 适用场景 | 说明 |
|---|---|---|
| 控制台设置页 | 日常调整 MQTT、模型、语音、IM 和工具权限 | 保存后写入 .device_agent/config.json。页面会提示是否需要重启。 |
.device_agent/config.json | 备份、迁移、批量下发、无 UI 环境 | 保存 Device Agent 的主要运行配置。 |
.env | 首次启动、容器或系统服务、环境差异、密钥注入 | 启动时读取。对配置文件支持的字段，会写入或覆盖配置文件中的对应值。 |
开发环境中，运行目录通常是仓库下的 .device_agent；生产运行时通常是用户目录下的 ~/.device_agent。配置文件路径以实际启动日志中的 Runtime Home 为准。
生效规则
| 配置类型 | 保存位置 | 生效方式 |
|---|---|---|
| MQTT 连接、主题、TLS | .device_agent/config.json，可由 .env 写入 | 修改后通常需要重启网关，已建立的 MQTT 连接不会自动切换。 |
| 主模型和视觉模型 | .device_agent/config.json，可由 .env 写入 | 控制台保存后会更新当前运行中的智能体配置。 |
| 语音服务商、语音模型和密钥 | .device_agent/config.json，可由 .env 写入 | 服务已启动时可更新；启用状态、监听地址、端口和 TLS 变化需要重启。 |
| IM 通道 | .device_agent/config.json，可由 .env 写入 | 通道在启动时加载，修改后需要重启。 |
| 工具权限 | .device_agent/config.json，也支持环境变量覆盖 | 控制台保存后立即更新；被环境变量覆盖的项在 UI 中会显示覆盖状态。 |
| 日志 | .device_agent/config.json，可由 .env 写入 | 保存后会更新日志级别和输出策略。 |
| HTTP 监听、数据库、A2A 注册身份、额外 IM 通道 | .env | 仅在启动时读取。 |
| Web 前端变量 | .env | 由前端开发服务或构建过程读取，修改后需要重启前端服务或重新构建。 |
如果同一个字段同时写在 .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-4.1
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。