控制台设置
控制台设置页位于 Device Agent 控制台左侧导航的 设置，包含 MQTT、模型、语音、IM 通道、权限和 Webhook 六个标签页。
MQTT
MQTT 标签页用来配置 Device Agent 连接 MQTT Broker 的方式，也展示当前网关的 MQTT 连接状态。
| 区域 | 配置内容 | 说明 |
|---|---|---|
| 连接地址 | Broker URL、WebSocket URL、Client ID | brokerUrl 供网关和设备侧连接使用；wsUrl 供浏览器通过 MQTT over WebSocket 使用。 |
| 连接参数 | MQTT 版本、Keep Alive、连接超时、自动重连、重连间隔、Clean Start、会话过期时间 | MQTT 5 才会显示会话过期时间。 |
| 认证 | 用户名、密码 | 对应 MQTT Broker 的账号认证。 |
| TLS | TLS 开关、证书校验、CA、客户端证书、客户端私钥、私钥密码、Server Name | 可以上传证书文件，上传后文件会保存到运行目录下的 certificates 目录。 |
| 主题模板 | 文本请求、设备命令、命令响应、遥测、事件、NTP 等主题 | 当前 UI 中只读。需要改主题模板时使用 .env 或配置文件。 |
在控制台保存 MQTT 配置后，Gateway 会使用新配置重新连接。直接修改 .env 或配置文件时，需要重启。Broker 选择和 Zero EMQX 配置见 准备 MQTT Broker。
模型
模型标签页分为主智能体模型和视觉模型。
| 区域 | 配置内容 | 说明 |
|---|---|---|
| 主智能体模型 | 服务商、模型、API Key、最大执行轮次、Base URL | 用于设备智能体建模、对话、工具调用和设备控制。模型列表以当前运行环境为准。 |
| Codex 认证 | Access Token 或 ~/.codex/auth.json | 当服务商选择 openai-codex 时显示。 |
| 视觉模型 | 是否启用、服务商、模型、API Key、超时时间 | 视觉能力用于摄像头图像、截图和多模态输入分析。 |
视觉模型支持 auto 和 dashscope。auto 会优先复用主智能体模型；dashscope 需要单独配置模型和 API Key。大模型服务商、.env 字段、Ollama 和 Codex 认证方式见 大模型配置。
语音
语音标签页配置语音通道和语音服务商。需要接入浏览器、移动端或设备端时，复制 语音连接地址 使用。
| 配置内容 | 说明 |
|---|---|
| 启用语音 | 控制语音通道是否可用。 |
| 语音连接地址 | 复制给浏览器、移动端或设备端使用。 |
| 监听地址和端口 | 默认 127.0.0.1:3001；远程访问时在 .env 中设置 VOICE_HOST=0.0.0.0。 |
| 语音服务商 | 支持火山引擎、阿里云 DashScope、AWS 和 ElevenLabs。 |
| 区域 | 控制可用服务商范围，支持 cn、us、eu 和 global。 |
| 语音识别 | ASR 模型、资源 ID 或语言设置，字段随服务商不同而变化。 |
| 语音合成 | TTS 模型、音色和采样率，字段随服务商不同而变化。 |
| 服务商密钥 | 例如 API Key、Access Key、AWS Key 等。 |
修改服务商、模型、音色和密钥后可以直接保存。启用状态、监听地址、端口或 TLS 变化需要重启服务；远程访问和 .env 示例见 语音配置。
IM 通道
IM 通道标签页用来启用和配置常用第三方聊天平台。当前控制台支持：
| 通道 | 主要配置 |
|---|---|
| 飞书 | App ID、App Secret、Encrypt Key、Verification Token、允许来源 |
| 钉钉 | Client ID、Client Secret、允许来源 |
| Discord | Bot Token、允许来源 |
| Telegram | Bot Token、允许来源 |
| Slack | Bot Token、App Token、Signing Secret、允许来源 |
allowFrom 用于限制允许访问设备智能体的用户或会话来源。多个值可以用逗号或换行分隔。IM 通道在启动时加载，保存后需要重启 Device Agent 才会重新加载通道。
各平台的具体配置见 IM 接入。
权限
权限标签页控制设备智能体可用的本地工具权限。
| 权限 | 说明 |
|---|---|
tool_editor | 允许保存和删除工具编辑器扩展。 |
write_file | 允许智能体写入本地文件。 |
execute_command | 允许智能体执行命令。 |
allowedPrefixes | 限制允许执行的命令前缀，例如 pwd、ls、rg。 |
页面会编辑已保存的 permissions.tools 配置。如果 .env 中设置了 ENABLE_TOOL_EDITOR_MUTATIONS、ENABLE_FILE_WRITE_TOOL、ENABLE_EXECUTE_COMMAND_TOOL 或 ALLOWED_EXEC_COMMAND_PREFIXES，启动时会像其他配置项一样把对应值写入 config.json。
Webhook
Webhook 标签页用于管理 Agent 对话和工作流可复用的出站通知连接。
| 区域 | 配置内容 | 说明 |
|---|---|---|
| 连接 | 名称、平台、HTTPS Webhook URL | 支持飞书、钉钉、Slack 和 Discord 预设；其他服务使用自定义 Webhook。 |
| 认证 | 签名方式、签名 Secret、可选 Headers | 用于目标平台的签名校验或认证。 |
| 消息格式 | JSON Body 模板 | 目标模板支持 {{message}} 变量。 |
| 投递结果 | 可选响应路径和期望值 | 未配置响应条件时，任意 2xx 响应都表示成功。 |
连接支持保存、测试、启停、编辑和删除，不需要重启 Device Agent。测试会真实发送消息；工作流仍在引用连接时不能删除。配置步骤、平台预设和投递限制见 Webhook。