配置文件

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

文件位置

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

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

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

平台部署使用 PostgreSQL 中的共享配置，各运行服务读取同一份保存结果，部署凭据在启动时注入。平台控制台中的修改不会写入本地 config.json，也不能通过复制或删除此文件迁移、重置平台配置。平台配置与数据的备份见 平台运维，部署参数见 平台部署。

文件结构

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

{
  "version": 1,
  "iotPlatform": {},
  "mqtt": {},
  "models": {},
  "voice": {},
  "im": {},
  "aiCredits": {},
  "logging": {},
  "permissions": {}
}

字段	用途
iotPlatform	当前平台提供商，以及各提供商的连接参数。
mqtt	MQTT Broker、浏览器 WebSocket 地址、连接参数、认证、TLS 和主题模板。
models	主智能体模型、视觉模型和 Jev 决策模型。
voice	语音 WebSocket 服务、语音区域、服务商和 ASR/TTS 参数。
im	飞书、钉钉、Discord、Telegram、Slack 等 IM 通道。
aiCredits	AI 额度策略；设备余额与消费记录使用独立存储，管理界面见 AI 额度。
logging	日志级别、控制台输出、文件输出和日志轮转。
permissions	工具编辑器、write_file、execute_command 和允许执行的命令前缀。

Webhook 连接、工作流、定时任务和设备智能体配置使用各自的数据存储，不属于此文件。智能体卡片 更多 → 配置总览 可编辑语音热词和已有等待反馈，已设置的回答风格在此只读展示。

示例

以下本地运行示例只展示由 Device Agent 直接管理设备时的常用字段。实际文件会包含完整结构；其他提供商应使用其物模型和主题协议。

{
  "version": 1,
  "iotPlatform": {
    "providerId": "default",
    "config": {}
  },
  "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-5.5",
      "baseUrl": "",
      "apiKey": "sk-...",
      "codexAuthFile": "",
      "maxIterations": 40,
      "reasoningEnabled": false,
      "reasoningEffort": "medium"
    },
    "vision": {
      "enabled": true,
      "provider": "auto",
      "model": "",
      "apiKey": "",
      "timeoutMs": 60000
    }
  }
}

直接修改文件

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

• 保留 version: 1。
• 使用合法 JSON，不要写注释或尾随逗号。
• MQTT 主题模板需要保留 {productId} 和 {deviceId} 占位符。
• TLS 证书路径可以是绝对路径，也可以是相对运行目录的路径。
• 修改文件后重启 Device Agent，使配置生效。
• 文件可能包含模型、MQTT、语音或 IM 凭据；备份时按敏感配置保管，避免提交到代码仓库。

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

与 .env 的关系

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

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

平台中，非敏感环境变量只用于首次初始化共享配置，后续以已保存配置为准；部署凭据在每次启动时读取，不会写入普通共享配置字段。ThingsNeural 登录授权获得的平台凭据由授权流程管理。更多变量见 环境变量。