环境变量
Device Agent 启动时读取当前进程环境变量，并尝试加载 .env，用于首次启动、部署、密钥和环境差异配置；支持配置文件的字段会写入 .device_agent/config.json，HTTP 监听、数据库、A2A 身份和额外 IM 通道等启动项不会写入配置文件。
开发环境中，.env 通常位于仓库根目录；安装版会从安装目录读取 .env。macOS/Linux 默认路径是 ${XDG_DATA_HOME:-$HOME/.local/share}/device-agent/current/.env。如果只想本次启动生效，可以直接在启动命令前设置环境变量。
bash
ENV_FILE="${XDG_DATA_HOME:-$HOME/.local/share}/device-agent/current/.env"
touch "$ENV_FILE"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 接入。
模型和视觉
| 变量 | 说明 |
|---|---|
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。 |
AGENT_GATEWAY_HTTP_TLS_ENABLED | 是否直接以 HTTPS 提供控制台和 HTTP API。未设置时，如果同时提供证书和私钥路径，会自动启用 TLS。 |
AGENT_GATEWAY_HTTP_TLS_CERT_FILE / AGENT_GATEWAY_HTTP_TLS_KEY_FILE | 直接 HTTPS 使用的 TLS 证书和私钥路径。相对路径从 workspace root 解析。 |
AGENT_GATEWAY_HTTP_TLS_PASSPHRASE | 直接 HTTPS 使用的 TLS 私钥密码。 |
VITE_API_BASE_URL | 前端请求 API 的基础地址。通常使用同源代理时不需要设置。 |
VITE_DEVICE_AGENT_PENDING_TIMEOUT_MS | 控制台等待设备智能体创建或响应的超时时间。 |
DATABASE_DRIVER | 数据存储驱动。默认使用本地数据存储；需要 PostgreSQL 时设置为 postgres。 |
DATABASE_URL | PostgreSQL 连接地址，仅在 DATABASE_DRIVER=postgres 时需要。 |
WEBHOOK_CREDENTIAL_MASTER_KEY | PostgreSQL 部署必填的 Base64 编码 32 字节密钥。所有 Gateway 使用相同值。 |
前端变量由前端开发服务或构建过程读取，修改后需要重启前端服务或重新构建。
启用直接 HTTPS
设置证书和配套私钥，然后重启 Device Agent：
bash
AGENT_GATEWAY_HTTP_HOST=0.0.0.0
AGENT_GATEWAY_HTTP_PORT=3000
AGENT_GATEWAY_HTTP_TLS_ENABLED=true
AGENT_GATEWAY_HTTP_TLS_CERT_FILE=/etc/device-agent/fullchain.pem
AGENT_GATEWAY_HTTP_TLS_KEY_FILE=/etc/device-agent/privkey.pem控制台和 HTTP API 随后通过 https://<host>:3000 访问。证书和私钥必须同时配置；相对路径从工作区或安装根目录解析。如果省略 AGENT_GATEWAY_HTTP_TLS_ENABLED，同时提供证书和私钥也会启用 HTTPS；显式设置为 false 时仍使用 HTTP。HTTPS 只加密传输，不提供用户身份认证，因此还需要把访问限制在可信网络或带身份认证的入口内。
浏览器和证书验证步骤见 下载安装。
配置 Webhook 密钥
PostgreSQL 部署通过 openssl rand -base64 32 生成一次 WEBHOOK_CREDENTIAL_MASTER_KEY，在所有 Gateway 中使用相同值，并妥善备份。请勿随意更换。
SQLite 部署不需要配置该变量。连接配置方法见 Webhook。
语音
| 变量 | 说明 |
|---|---|
VOICE_ENABLED | 是否启用语音通道。 |
VOICE_HOST | 语音服务监听地址，默认 127.0.0.1；局域网或服务器访问时设置为 0.0.0.0。 |
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 |
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_ENABLED、WHATSAPP_BRIDGE_URL、WHATSAPP_BRIDGE_TOKEN、WHATSAPP_ALLOW_FROM | |
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_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 接入。
日志
| 变量 | 说明 |
|---|---|
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。 |
日志使用方式见 日志。
工具权限
| 变量 | 说明 |
|---|---|
ENABLE_TOOL_EDITOR_MUTATIONS | 每次启动都会重新应用并持久化工具编辑器的保存/删除权限。 |
ENABLE_FILE_WRITE_TOOL | 每次启动都会重新应用并持久化 write_file 工具权限。 |
ENABLE_EXECUTE_COMMAND_TOOL | 每次启动都会重新应用并持久化 execute_command 工具权限。 |
ALLOWED_EXEC_COMMAND_PREFIXES | 每次启动都会重新应用并持久化允许执行的命令前缀；空值会清空白名单。 |
DANGEROUSLY_BYPASS_TOOL_PERMISSIONS | 仅服务端启动环境生效，不写入 config.json，也不在控制台显示。设为 true 后会绕过文件写入审批、命令审批与白名单、Shell 安全检查和工具编辑器修改限制。这不是沙箱：免审写入可修改可执行源码或工具扩展，命令也会继承 Gateway 进程的主机权限。只有在 Agent、工作区和全部 Gateway Secret 都可信时才能启用。 |
A2A
| 变量 | 说明 |
|---|---|
A2A_ORG_ID / A2A_UNIT_ID | A2A 注册和发现使用的组织与单元身份，默认都是 default。 |
A2A 使用方式见 A2A。