配置
Device Agent 提供全局设置和单个设备智能体配置。全局设置负责模型与语音服务、IoT 平台连接、IM 通道和工具权限；单个智能体配置负责角色、时区、识别热词、可用语音工具及回复反馈。
配置入口
| 要调整什么 | 入口 |
|---|---|
| 模型服务商、推理等级、视觉或语音服务 | 设置 → 模型，见控制台设置。 |
| IoT 平台、MQTT、IM 通道、工具权限或 Webhook | 设置中的对应入口。 |
| 一个智能体的提示词、时区、热词、语音工具、身份回复和等待提示 | 智能体卡片 更多 → 配置总览，见设备智能体配置。 |
| 平台设备 AI 额度或请求授权 | 设置 → AI 额度 / License 授权。 |
全局模型设置提供设备智能体可用的模型服务，设备模型则描述属性、动作和事件。调整提示词或回复方式使用配置总览；修改设备能力使用定义设备智能体中的建模入口。
| 入口 | 适用场景 |
|---|---|
| 控制台设置页 | 查看平台提供商、MQTT 和模型，调整语音、IM 通道、工具权限和 Webhook。平台还提供 AI 额度与 License 授权。 |
.device_agent/config.json | 本地运行的备份、迁移、批量部署或无 UI 配置；平台设置通过控制台或部署管理员维护。 |
环境变量 / .env | 首次启动、容器、系统服务、监听地址和密钥注入。 |
本地开发环境中，.env 通常位于仓库根目录；安装版从安装目录读取 .env。查看启动日志中的 Runtime Home 确认配置文件所在运行目录，生产运行时通常为 ~/.device_agent。平台初始配置和凭据由部署管理员维护，见平台部署。
生效规则
| 配置类型 | 本地运行 | 平台部署 |
|---|---|---|
| 主模型、视觉模型 | 控制台保存后立即生效。 | 控制台只读，更改时联系部署管理员。 |
| 单个智能体配置 | 保存后用于后续请求；语音热词在下一次语音连接生效。 | 与本地相同，具体可编辑范围见配置总览。 |
| 工具权限、Webhook | 保存后立即生效。 | 保存后生效；工具权限约束智能体工具，不是用户角色权限。 |
| 语音服务商、模型和音色 | 保存后立即生效；启用状态、监听地址、端口或 TLS 变化需要重启。 | 可调整非敏感参数，保存后相关服务重启生效；密钥在页面只显示配置状态。 |
| MQTT | 控制台保存后重新连接；修改 .env 或配置文件后需要重启。 | 控制台常规设置只读；连接由平台运行服务管理。 |
| IM 通道 | 保存后需要重启。 | 可调整开关、标识和允许来源等非敏感参数，保存后相关服务重启生效。 |
| HTTP、HTTPS、数据库、A2A 身份和部署凭据 | 修改后需要重启。 | 更新部署配置后重启受影响的服务。 |
| Web 前端变量 | 修改后需要重启前端服务或重新构建。 | 修改后需要重启前端服务或重新构建。 |
保存后按页面提示等待生效，需要重启的配置先完成重启，再确认连接和对话正常。平台运行状态见监控。
本地运行时，.env 中的同名变量会在每次启动覆盖控制台配置；需要保留控制台设置时，移除对应变量。平台日常调整使用控制台提供的入口，模型服务和凭据变更联系部署管理员。
最小启动示例
以下示例用于本地运行，平台服务和 PostgreSQL 配置见 平台部署。
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 或同等访问控制。配置方法见 下载安装。
接下来
- 控制台设置项见 控制台设置。
- MQTT Broker 准备方式见 准备 MQTT Broker。
- 大模型见大模型配置，视觉模型见视觉模型配置。
- 语音服务商和语音通道见 语音配置。
- 配置文件结构见 配置文件。
- 启动环境变量见 环境变量。
- 平台设备消费额度见 AI 额度，平台请求额度与有效期见 License 授权。