# 配置

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`。

## 接下来

- 控制台设置项见 [控制台设置](./configuration/settings-ui.md)。
- 配置文件结构见 [配置文件](./configuration/config-file.md)。
- 启动环境变量见 [环境变量](./configuration/environment-variables.md)。