# 配置文件

`.device_agent/config.json` 是 Device Agent 的主要运行配置文件。控制台设置页保存的 MQTT、模型、语音、IM、日志和工具权限都会写入这个文件。启动时，如果文件不存在，Device Agent 会根据默认值和 `.env` 中的启动配置自动创建。

## 文件位置

运行目录由启动方式决定：

| 运行方式 | 常见位置 |
| --- | --- |
| 开发环境 | `<repo>/.device_agent/config.json` |
| 生产运行 | `~/.device_agent/config.json` |

以启动日志中的 `Runtime Home` 为准。证书上传、日志文件、用户技能和工具扩展也会放在同一个运行目录下的子目录中。

## 文件结构

配置文件包含这些顶层字段：

```json
{
  "version": 1,
  "mqtt": {},
  "models": {},
  "voice": {},
  "im": {},
  "logging": {},
  "permissions": {}
}
```

| 字段 | 用途 |
| --- | --- |
| `mqtt` | MQTT Broker、浏览器 WebSocket 地址、连接参数、认证、TLS 和主题模板。 |
| `models` | 主智能体模型和视觉模型。 |
| `voice` | 语音 WebSocket 服务、语音区域、服务商和 ASR/TTS 参数。 |
| `im` | 飞书、钉钉、Discord、Telegram、Slack 等 IM 通道。 |
| `logging` | 日志级别、控制台输出、文件输出和日志轮转。 |
| `permissions` | `write_file`、`execute_command` 和允许执行的命令前缀。 |

## 示例

以下示例只展示常用字段。实际文件会包含完整结构。

```json
{
  "version": 1,
  "mqtt": {
    "brokerUrl": "mqtt://broker.example.com:1883",
    "wsUrl": "wss://broker.example.com:8084/mqtt",
    "clientId": "device-agent-gateway",
    "protocolVersion": 5,
    "username": "device-agent",
    "password": "secret",
    "tls": {
      "enabled": false,
      "rejectUnauthorized": true,
      "caFile": "",
      "certFile": "",
      "keyFile": "",
      "keyPassphrase": "",
      "serverName": ""
    },
    "topics": {
      "deviceCommand": "device-agent/{productId}/device/{deviceId}/commands",
      "deviceResponse": "device-agent/{productId}/device/{deviceId}/responses",
      "telemetry": "v1/{productId}/{deviceId}/telemetry",
      "event": "v1/{productId}/{deviceId}/event"
    }
  },
  "models": {
    "agent": {
      "provider": "openai",
      "model": "gpt-4.1",
      "baseUrl": "",
      "apiKey": "sk-...",
      "codexAuthFile": "",
      "maxIterations": 40
    },
    "vision": {
      "enabled": true,
      "provider": "auto",
      "model": "",
      "apiKey": "",
      "timeoutMs": 60000
    }
  }
}
```

## 直接修改文件

直接修改配置文件适合备份恢复、批量部署或无法访问控制台的环境。修改时注意：

- 保留 `version: 1`。
- 使用合法 JSON，不要写注释或尾随逗号。
- MQTT 主题模板需要保留 `{productId}` 和 `{deviceId}` 占位符。
- TLS 证书路径可以是绝对路径，也可以是相对运行目录的路径。
- 修改 MQTT、IM、语音监听地址、端口或 TLS 后需要重启。

如果配置文件格式不合法，Device Agent 启动时会报错并指出配置路径。需要恢复时，可以先备份当前文件，再删除 `config.json`，让 Device Agent 在下次启动时重新生成默认配置。

## 与 `.env` 的关系

`.env` 会在启动时写入同名配置项。直接修改 `config.json` 后，如果 `.env` 里仍然存在同名变量，下次启动时 `.env` 的值会再次覆盖文件中的值。

适合长期保留在 `.env` 的内容通常是部署环境差异，例如 HTTP 监听地址、数据库、A2A 身份和密钥注入。适合保留在 `config.json` 的内容是控制台中日常维护的 MQTT、模型、语音、IM、日志和权限配置。