环境变量
环境变量用于配置服务地址、模型凭据和其他部署参数。
设置环境变量
| 配置范围 | 生效规则 |
|---|---|
| 本地控制台配置 | 每次启动读取进程环境变量和 .env，覆盖同名控制台保存值。 |
| 平台控制台配置 | 环境变量仅用于首次初始化；后续使用控制台保存值，凭据由部署环境注入。 |
| 启动项与部署凭据 | HTTP 监听、数据库、服务身份、A2A 身份和额外 IM 通道始终从部署环境读取；修改后重启受影响的服务。 |
本地开发使用仓库根目录的 .env；安装版使用安装目录中的 .env。macOS/Linux 默认路径如下。仅需本次启动生效时，在启动命令前设置变量。
bash
ENV_FILE="${XDG_DATA_HOME:-$HOME/.local/share}/device-agent/current/.env"
touch "$ENV_FILE"平台环境变量由部署管理员维护，部署与更新见平台部署和平台运维。日常设置见控制台设置；单个智能体的提示词、热词和回复设置见设备智能体配置。
平台提供商
| 变量 | 说明 |
|---|---|
IOT_PLATFORM_PROVIDER_ID | 初始 IoT 平台提供商：default、fleets 或 thingsneural。 |
FLEETS_API_URL | Fleets 管理接口地址。 |
FLEETS_API_KEY / FLEETS_API_SECRET / FLEETS_BEARER_TOKEN | Fleets 认证凭据，由部署环境注入。 |
FLEETS_MQTT_BROKER_URL / FLEETS_MQTT_WEBSOCKET_URL | Fleets MQTT 和浏览器 WebSocket 连接地址。 |
THINGSNEURAL_URL / THINGSNEURAL_API_URL | ThingsNeural 服务地址，后者是兼容别名。 |
THINGSNEURAL_ACCESS_KEY / THINGSNEURAL_SECRET_KEY | ThingsNeural 接入凭据。 |
THINGSNEURAL_PROJECT_ID / THINGSNEURAL_CATEGORY_ID | ThingsNeural 项目和分类标识。 |
THINGSNEURAL_MQTT_URL / THINGSNEURAL_CLIENT_API_URL / THINGSNEURAL_LOGIN_URL | MQTT、客户端接口和登录入口地址。 |
按所选提供商配置参数，接入说明见IoT 平台集成。
MQTT
| 变量 | 说明 |
|---|---|
MQTT_BROKER_URL | 网关与设备端的 Broker 地址，例如 mqtt://localhost:1883。 |
VITE_MQTT_WS_URL | 浏览器的 MQTT WebSocket 地址，例如 ws://localhost:8083/mqtt。 |
MQTT_CLIENT_ID | 网关 MQTT 客户端 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 | 浏览器直连 Broker 时使用的 MQTT 凭据。 |
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。 |
主题模板仅用于 default 提供商；Fleets 和 ThingsNeural 使用各自的原生主题协议：
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。 |
DOUBAO_API_KEY / ARK_API_KEY | doubao 的火山方舟凭据，依次读取 DOUBAO_API_KEY、ARK_API_KEY、LLM_API_KEY；与语音凭据 VOLCENGINE_SPEECH_* 不通用。 |
CLOUDFLARE_API_KEY | Cloudflare Workers AI 或 AI Gateway 的 API Key。 |
CLOUDFLARE_ACCOUNT_ID | Cloudflare 账户 ID，对应控制台字段为空时使用。 |
CLOUDFLARE_GATEWAY_ID | AI Gateway ID，仅用于 cloudflare-ai-gateway，对应控制台字段为空时使用。 |
OPENAI_CODEX_AUTH_FILE | openai-codex 服务商使用的 Codex 认证文件路径。 |
OPENAI_CODEX_ACCESS_TOKEN | openai-codex 服务商使用的访问令牌。 |
AGENT_MAX_ITERATIONS | 智能体单轮任务的最大执行轮次。 |
LLM_REASONING_ENABLED | 是否开启模型推理（思考）能力，默认 false。 |
LLM_REASONING_EFFORT | 推理等级：minimal、low、medium（默认）、high、xhigh、max。仅在启用推理且模型支持时生效，支持范围见控制台。 |
VISION_ENABLED | 是否启用视觉能力。 |
VISION_PROVIDER | auto 沿用支持图像输入的智能体模型；dashscope 使用独立视觉模型。 |
VISION_MODEL | DashScope 视觉模型名称。 |
VISION_API_KEY | DashScope 视觉模型 API Key。 |
VISION_TIMEOUT_MS | 视觉分析超时，单位为毫秒。 |
TYPESAFE_API_KEY | Jev 决策模型 的 API Key。本地作为初始值；平台只注入 Worker。 |
模型与推理选项见大模型配置，视觉选项见视觉模型配置。旧配置 LLM_PROVIDER=kimi 需改为 moonshotai-cn，模型 ID 和 API Key 不变。
auto 沿用智能体模型的 API 配置；选择 dashscope 时需另设 VISION_MODEL 和 VISION_API_KEY。
HTTP、前端和数据存储
HTTP 与前端
| 变量 | 说明 |
|---|---|
AGENT_GATEWAY_HTTP_HOST | 控制台与 API 的监听地址。本地默认 127.0.0.1，服务器或局域网访问用 0.0.0.0；平台以部署配置为准。 |
AGENT_GATEWAY_HTTP_PORT | 控制台和 HTTP API 的监听端口，默认 3000。 |
AGENT_GATEWAY_HTTP_TLS_ENABLED | true 启用直接 HTTPS，false 使用 HTTP；未设置时，成对提供证书与私钥即启用 HTTPS。 |
AGENT_GATEWAY_HTTP_TLS_CERT_FILE / AGENT_GATEWAY_HTTP_TLS_KEY_FILE | HTTPS 证书与私钥路径，须成对配置；相对路径从工作区或安装根目录解析。 |
AGENT_GATEWAY_HTTP_TLS_PASSPHRASE | HTTPS 私钥密码。 |
VITE_API_BASE_URL | 前端 API 基础地址，使用同源代理时通常无需设置。 |
VITE_DEVICE_AGENT_PENDING_TIMEOUT_MS | 控制台等待设备智能体创建或响应的超时，单位为毫秒。 |
VITE_ 变量由前端开发服务或构建过程读取，修改后重启前端或重新构建。
数据存储与服务角色
| 变量 | 说明 |
|---|---|
DATABASE_DRIVER | 本地使用 sqlite（默认）；平台使用 postgres。 |
DATABASE_URL | 平台 PostgreSQL 连接串。生产环境校验证书；sslmode=disable 仅用于本地开发。 |
DEVICE_AGENT_ROLE | 平台角色：cloud-api、cloud-worker、cloud-ingress；cloud-all 在单进程运行所有角色，仅用于开发。 |
认证与授权
| 变量 | 说明 |
|---|---|
AGENT_GATEWAY_API_TOKEN | 可选的服务调用 Bearer Token，至少 32 个字符。 |
AGENT_GATEWAY_CONSOLE_AUTH_ENABLED | 本地设为 true 可启用提供商 SSO，要求 IoT 提供商支持控制台登录；平台对这类提供商自动启用 SSO 校验。 |
AGENT_GATEWAY_CONSOLE_SESSION_SECRET | 提供商控制台登录的会话签名密钥，至少 32 个随机字符，所有 API 副本一致。 |
WEBHOOK_CREDENTIAL_MASTER_KEY | PostgreSQL 部署必需的 Webhook 凭据加密密钥：Base64 编码的 32 字节密钥。 |
DEVICE_AGENT_LICENSE_ADMIN_TOKEN | 导入签名 License 的独立管理凭据，至少 32 个字符，与服务 Token、会话密钥不同；未配置时无法导入。 |
DEVICE_AGENT_PUBLIC_BASE_URL | 控制台公共地址。由反向代理终止 HTTPS 时设置，用于校验浏览器导入 License 的请求来源。 |
DEVICE_AGENT_LICENSE_FILE | 可选的首次激活签名授权文件；后续在 License 授权页续期。 |
服务 Token 只认证服务调用，不提供终端用户身份或角色权限；HTTPS 只加密传输。共享访问需使用可信网络或经认证的入口。
平台服务配置见平台部署，请求授权见 License 授权；设备消费策略由 AI 额度 独立管理。
启用直接 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重启后通过 https://<host>:3000 访问控制台和 HTTP API。浏览器和证书验证见下载安装。
平台监控
部署管理员按交付手册启用指标采集，并在平台 API 服务配置 Prometheus：
| 变量 | 说明 |
|---|---|
DEVICE_AGENT_PROMETHEUS_URL | Prometheus HTTP/HTTPS 基础地址，不能包含凭据、查询参数或片段；未配置时监控不可用。 |
DEVICE_AGENT_PROMETHEUS_NAMESPACE | 可选的命名空间筛选值，须为小写 DNS 标签，与指标的 device_agent_namespace 标签一致。 |
语音
| 变量 | 说明 |
|---|---|
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_ASR_VOCABULARY_ENABLED、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
设置 → 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 |
以下通道仅通过环境变量配置：
| 通道 | 变量 |
|---|---|
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 的主机权限运行；仅在智能体、工作区和全部 Gateway 凭据均可信时启用。
工具权限的覆盖规则见设置环境变量，不提供控制台用户或角色管理。
A2A
| 变量 | 说明 |
|---|---|
A2A_ORG_ID / A2A_UNIT_ID | A2A 注册和发现使用的组织与单元身份，默认都是 default。 |
A2A 使用方式见 A2A。