# 环境变量

Device Agent 启动时读取工作区根目录的 `.env`，用于首次启动、部署、密钥和环境差异配置；支持配置文件的字段会写入 `.device_agent/config.json`，HTTP 监听、数据库、A2A 身份和额外 IM 通道等启动项不会写入配置文件。

```bash
cp .env.example .env
```

## MQTT

| 变量 | 说明 |
| --- | --- |
| `MQTT_BROKER_URL` | 网关和设备端连接 MQTT Broker 的地址，例如 `mqtt://localhost:1883`。 |
| `VITE_MQTT_WS_URL` | 浏览器连接 MQTT Broker 的 WebSocket 地址，例如 `ws://localhost:8083/mqtt`。 |
| `MQTT_CLIENT_ID` | 网关连接 MQTT Broker 时使用的客户端 ID。 |
| `MQTT_PROTOCOL_VERSION` | MQTT 协议版本，支持 `4` 和 `5`。 |
| `MQTT_KEEPALIVE_SECONDS` / `MQTT_KEEP_ALIVE_SECONDS` | Keep Alive 时间。 |
| `MQTT_CONNECT_TIMEOUT_MS` | 连接超时时间。 |
| `MQTT_AUTO_RECONNECT` | 是否自动重连。 |
| `MQTT_RECONNECT_PERIOD_MS` | 重连间隔。 |
| `MQTT_CLEAN_START` | 是否使用 Clean Start。 |
| `MQTT_SESSION_EXPIRY_INTERVAL_SECONDS` | MQTT 5 会话过期时间。 |
| `MQTT_USERNAME` / `MQTT_PASSWORD` | 网关和设备侧常用 MQTT 认证信息。 |
| `VITE_MQTT_USERNAME` / `VITE_MQTT_PASSWORD` | 浏览器侧 MQTT 认证信息。只在确实需要浏览器直连 Broker 时使用。 |

TLS 相关变量：

| 变量 | 说明 |
| --- | --- |
| `MQTT_TLS_ENABLED` | 启用 MQTT TLS。 |
| `MQTT_TLS_INSECURE` | 设置为 `true` 时关闭服务端证书校验。 |
| `MQTT_TLS_REJECT_UNAUTHORIZED` | 是否校验服务端证书。 |
| `MQTT_TLS_CA_FILE` | CA 证书路径。 |
| `MQTT_TLS_CERT_FILE` | 客户端证书路径。 |
| `MQTT_TLS_KEY_FILE` | 客户端私钥路径。 |
| `MQTT_TLS_KEY_PASSPHRASE` | 客户端私钥密码。 |
| `MQTT_TLS_SERVER_NAME` | TLS Server Name。 |

主题模板变量：

```bash
MQTT_TOPIC_PRODUCT_IN=device-agent/{productId}/in
MQTT_TOPIC_PRODUCT_OUT=device-agent/{productId}/out
MQTT_TOPIC_DEVICE_IN=device-agent/{productId}/device/{deviceId}/in
MQTT_TOPIC_DEVICE_OUT=device-agent/{productId}/device/{deviceId}/out
MQTT_TOPIC_DEVICE_COMMAND=device-agent/{productId}/device/{deviceId}/commands
MQTT_TOPIC_DEVICE_RESPONSE=device-agent/{productId}/device/{deviceId}/responses
MQTT_TOPIC_TELEMETRY=v1/{productId}/{deviceId}/telemetry
MQTT_TOPIC_EVENT=v1/{productId}/{deviceId}/event
MQTT_TOPIC_NTP_REQUEST=device-agent/{productId}/device/{deviceId}/ntp/request
MQTT_TOPIC_NTP_RESPONSE=device-agent/{productId}/device/{deviceId}/ntp/response
```

主题模板需要保留 `{productId}` 和 `{deviceId}` 占位符。更多主题和消息格式见 [MQTT 接入](../../device-access/mqtt.md)。

## 模型和视觉

| 变量 | 说明 |
| --- | --- |
| `LLM_PROVIDER` | 主智能体模型服务商。 |
| `LLM_MODEL` | 主智能体模型名称。 |
| `LLM_BASE_URL` | 自定义模型服务地址，常用于 OpenAI 兼容接口或本地模型服务。 |
| `LLM_API_KEY` | 通用模型 API Key。 |
| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `KIMI_API_KEY` / `QWEN_API_KEY` | 对应服务商的 API Key。 |
| `OPENAI_CODEX_AUTH_FILE` | `openai-codex` 服务商使用的 Codex 认证文件路径。 |
| `OPENAI_CODEX_ACCESS_TOKEN` | `openai-codex` 服务商使用的访问令牌。 |
| `AGENT_MAX_ITERATIONS` | 智能体单轮任务的最大执行轮次。 |
| `VISION_ENABLED` | 是否启用视觉能力。 |
| `VISION_PROVIDER` | 视觉服务商，支持 `auto` 和 `dashscope`。 |
| `VISION_MODEL` | 视觉模型名称。 |
| `VISION_API_KEY` | 视觉模型 API Key。 |
| `VISION_TIMEOUT_MS` | 视觉分析超时时间。 |

`VISION_PROVIDER=auto` 时，系统会尝试复用主智能体模型的图像输入能力。使用独立视觉模型时，设置 `VISION_PROVIDER=dashscope`、`VISION_MODEL` 和 `VISION_API_KEY`。

## HTTP、前端和数据存储

| 变量 | 说明 |
| --- | --- |
| `AGENT_GATEWAY_HTTP_HOST` | 控制台和 HTTP API 的监听地址，默认 `127.0.0.1`。需要服务器 IP 或局域网访问时设置为 `0.0.0.0`。 |
| `AGENT_GATEWAY_HTTP_PORT` | 控制台和 HTTP API 的监听端口，默认 `3000`。 |
| `VITE_API_BASE_URL` | 前端请求 API 的基础地址。通常使用同源代理时不需要设置。 |
| `VITE_DEVICE_AGENT_PENDING_TIMEOUT_MS` | 控制台等待设备智能体创建或响应的超时时间。 |
| `VITE_FF_A2A_MARKETPLACE_ENABLE` | 是否显示 A2A Marketplace 相关入口。 |
| `VITE_DEVICE_ACCESS_CONTROL_BASE_URL` | 设备接入控制服务地址，用于小程序等外部访问控制场景。 |
| `DATABASE_DRIVER` | 数据存储驱动。默认使用本地数据存储；需要 PostgreSQL 时设置为 `postgres`。 |
| `DATABASE_URL` | PostgreSQL 连接地址，仅在 `DATABASE_DRIVER=postgres` 时需要。 |

前端变量由前端开发服务或构建过程读取，修改后需要重启前端服务或重新构建。

## 语音

| 变量 | 说明 |
| --- | --- |
| `VOICE_ENABLED` | 是否启用语音通道。 |
| `VOICE_HOST` | 语音服务监听地址。 |
| `VOICE_PORT` | 语音服务监听端口，默认 `3001`。 |
| `VITE_ASR_SAMPLE_RATE` | 浏览器采集语音时使用的 ASR 采样率。 |
| `VOICE_REGION` | 语音区域，支持 `cn`、`us`、`eu` 和 `global`。 |
| `VOICE_TLS_ENABLED` | 是否启用语音服务 TLS。 |
| `VOICE_TLS_CERT_FILE` / `VOICE_TLS_KEY_FILE` | 语音服务 TLS 证书和私钥路径。 |
| `VOICE_TLS_PASSPHRASE` | 语音服务 TLS 私钥密码。 |

语音服务商变量：

| 服务商 | 变量 |
| --- | --- |
| 火山引擎 | `VOLCENGINE_SPEECH_APP_ID`、`VOLCENGINE_SPEECH_ACCESS_KEY`、`VOLCENGINE_ASR_RESOURCE_ID`、`VOLCENGINE_ASR_LANGUAGE`、`VOLCENGINE_TTS_RESOURCE_ID`、`VOLCENGINE_TTS_VOICE`、`VOLCENGINE_TTS_VOICES`、`VOLCENGINE_TTS_EXPLICIT_LANGUAGE`、`VOLCENGINE_TTS_SAMPLE_RATE` |
| 阿里云 DashScope | `ALIYUN_DASHSCOPE_API_KEY`、`ALIYUN_ASR_MODEL`、`ALIYUN_ASR_LANGUAGE`、`ALIYUN_TTS_MODEL`、`ALIYUN_TTS_VOICE`、`ALIYUN_TTS_VOICES`、`ALIYUN_TTS_SAMPLE_RATE` |
| AWS | `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_REGION`、`AWS_TRANSCRIBE_LANGUAGE_CODE`、`AWS_POLLY_VOICE`、`AWS_POLLY_SAMPLE_RATE` |
| ElevenLabs | `ELEVENLABS_API_KEY`、`ELEVENLABS_API_ENDPOINT`、`ELEVENLABS_ASR_MODEL_ID`、`ELEVENLABS_ASR_LANGUAGE`、`ELEVENLABS_TTS_MODEL_ID`、`ELEVENLABS_TTS_VOICE`、`ELEVENLABS_TTS_VOICES`、`ELEVENLABS_TTS_SAMPLE_RATE` |

更多说明见 [语音交互](../../usage/voice.md)。

## IM

这些通道也可以在控制台设置页配置：

| 通道 | 变量 |
| --- | --- |
| 飞书 | `FEISHU_ENABLED`、`FEISHU_APP_ID`、`FEISHU_APP_SECRET`、`FEISHU_ENCRYPT_KEY`、`FEISHU_VERIFICATION_TOKEN`、`FEISHU_ALLOW_FROM` |
| 钉钉 | `DINGTALK_ENABLED`、`DINGTALK_CLIENT_ID`、`DINGTALK_CLIENT_SECRET`、`DINGTALK_ALLOW_FROM` |
| Discord | `DISCORD_ENABLED`、`DISCORD_BOT_TOKEN`、`DISCORD_ALLOW_FROM` |
| Telegram | `TELEGRAM_ENABLED`、`TELEGRAM_BOT_TOKEN`、`TELEGRAM_ALLOW_FROM` |
| Slack | `SLACK_ENABLED`、`SLACK_BOT_TOKEN`、`SLACK_APP_TOKEN`、`SLACK_SIGNING_SECRET`、`SLACK_ALLOW_FROM`、`SLACK_CHANNEL_DIRECT_ENABLED` |

额外 IM 通道目前只支持环境变量，不会出现在控制台设置页：

| 通道 | 变量 |
| --- | --- |
| WhatsApp | `WHATSAPP_ENABLED`、`WHATSAPP_BRIDGE_URL`、`WHATSAPP_BRIDGE_TOKEN`、`WHATSAPP_ALLOW_FROM` |
| QQ | `QQ_ENABLED`、`QQ_APP_ID`、`QQ_APP_SECRET`、`QQ_TOKEN`、`QQ_SANDBOX`、`QQ_ALLOW_FROM` |
| Matrix | `MATRIX_ENABLED`、`MATRIX_HOMESERVER_URL`、`MATRIX_ACCESS_TOKEN`、`MATRIX_AUTOJOIN`、`MATRIX_ALLOW_FROM` |
| MoChat | `MOCHAT_ENABLED`、`MOCHAT_SERVER_URL`、`MOCHAT_TOKEN`、`MOCHAT_BOT_NAME`、`MOCHAT_ALLOW_FROM` |
| Email | `EMAIL_ENABLED`、`EMAIL_IMAP_HOST`、`EMAIL_IMAP_PORT`、`EMAIL_IMAP_USER`、`EMAIL_IMAP_PASSWORD`、`EMAIL_IMAP_TLS`、`EMAIL_SMTP_HOST`、`EMAIL_SMTP_PORT`、`EMAIL_SMTP_USER`、`EMAIL_SMTP_PASSWORD`、`EMAIL_SMTP_TLS`、`EMAIL_FROM_ADDRESS`、`EMAIL_POLL_INTERVAL_MS`、`EMAIL_ALLOW_FROM` |

更多说明见 [IM 接入](../../integrations/im.md)。

## 日志

| 变量 | 说明 |
| --- | --- |
| `LOG_LEVEL` | 日志级别，支持 `debug`、`info`、`warn`、`error`。 |
| `LOG_CONSOLE_ENABLED` | 是否输出到控制台。 |
| `LOG_FILE_ENABLED` | 是否输出到文件。 |
| `LOG_DIR` | 日志目录。相对路径会解析到运行目录下。 |
| `LOG_MAX_SIZE_MB` | 单个日志文件最大大小。 |
| `LOG_RETENTION_DAYS` | 日志保留天数。 |
| `LOG_MAX_TOTAL_SIZE_MB` | 日志文件总大小上限。 |
| `LOG_TIMEZONE` | 日志文件时间使用 `system` 或 `utc`。 |

日志使用方式见 [日志](../logs.md)。

## 工具权限

| 变量 | 说明 |
| --- | --- |
| `ENABLE_TOOL_EDITOR_MUTATIONS` | 写入工具编辑器保存/删除权限初始值。 |
| `ENABLE_FILE_WRITE_TOOL` | 写入 `write_file` 工具权限初始值。 |
| `ENABLE_EXECUTE_COMMAND_TOOL` | 写入 `execute_command` 工具权限初始值。 |
| `ALLOWED_EXEC_COMMAND_PREFIXES` | 写入允许执行的命令前缀初始值。 |

## A2A

| 变量 | 说明 |
| --- | --- |
| `A2A_ORG_ID` / `A2A_UNIT_ID` | A2A 注册和发现使用的组织与单元身份，默认都是 `default`。 |

A2A 使用方式见 [A2A](../../usage/a2a.md)。