配置文件

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

文件位置

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

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

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

文件结构

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

{
  "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 和允许执行的命令前缀。

示例

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

{
  "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、日志和权限配置。