Configuration File

.device_agent/config.json is the main Device Agent runtime configuration file. Values saved from the console settings page, including MQTT, models, voice, IM, logging, and tool permissions, are written to this file. If the file does not exist, Device Agent creates it at startup from defaults and startup values in .env.

File Location

The runtime home depends on how Device Agent is started:

Runtime	Common Location
Development	<repo>/.device_agent/config.json
Production	~/.device_agent/config.json

Use the Runtime Home line in the startup logs as the source of truth. Uploaded certificates, log files, user skills, and tool extensions are also stored under this runtime home.

File Structure

The configuration file contains these top-level fields:

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

Field	Purpose
mqtt	MQTT broker, browser WebSocket URL, connection behavior, auth, TLS, and topic templates.
models	Primary agent model and vision model.
voice	Voice WebSocket service, voice region, provider, and ASR/TTS settings.
im	Feishu, DingTalk, Discord, Telegram, Slack, and related IM channels.
logging	Log level, console output, file output, and rotation.
permissions	write_file, execute_command, and allowed command prefixes.

Example

This example shows common fields only. The actual file contains the full structure.

{
  "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
    }
  }
}

Editing the File Directly

Direct file edits are useful for backup restore, bulk deployment, or environments without console access. When editing:

• Keep version: 1.
• Use valid JSON. Comments and trailing commas are not allowed.
• Keep {productId} and {deviceId} placeholders in MQTT topic templates.
• TLS certificate paths can be absolute or relative to the runtime home.
• Restart after changing MQTT, IM, voice bind host, voice port, or voice TLS settings.

If the file is invalid, Device Agent reports the configuration path during startup. To recover, back up the current file, remove config.json, and restart Device Agent to regenerate a default configuration.

Relationship with .env

.env writes matching configuration fields at startup. If you edit config.json directly while the same variable still exists in .env, the .env value is written again on the next restart.

Values that are usually kept in .env are deployment differences, such as HTTP bind address, database, A2A identity, and secret injection. Values that are usually kept in config.json are daily MQTT, model, voice, IM, logging, and permission settings maintained from the console.