# 控制台设置

控制台设置页位于 Device Agent 控制台左侧导航的 **设置**。页面按实际功能分为 MQTT、模型、语音、IM 和权限五个标签页。每个标签页都有刷新和保存操作；保存失败时会显示错误，保存成功后会写入 `.device_agent/config.json`。

![控制台设置页](../../images/docs/operate-reference/configuration/zh/01-settings-ui.png)

## 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 配置保存后，当前已经建立的 MQTT 连接不会自动切换。页面会通过网关状态提示是否需要重启。

## 模型

模型标签页分为主智能体模型和视觉模型。

| 区域 | 配置内容 | 说明 |
| --- | --- | --- |
| 主智能体模型 | 服务商、模型、API Key、最大执行轮次、Base URL | 用于设备智能体建模、对话、工具调用和设备控制。模型列表来自运行时模型目录。 |
| Codex 认证 | Access Token 或 `~/.codex/auth.json` | 当服务商选择 `openai-codex` 时显示。 |
| 视觉模型 | 是否启用、服务商、模型、API Key、超时时间 | 视觉能力用于摄像头图像、截图和多模态输入分析。 |

视觉模型支持 `auto` 和 `dashscope`。`auto` 会优先复用主智能体模型；如果主模型不支持图像输入，视觉分析不可用。`dashscope` 需要单独配置模型和 API Key。

## 语音

语音标签页配置语音通道和语音服务商。语音 WebSocket 地址会在页面中只读展示，默认是 `ws://127.0.0.1:3001/ws/voice`。

| 配置内容 | 说明 |
| --- | --- |
| 启用语音 | 控制语音通道是否可用。 |
| 语音服务商 | 支持火山引擎、阿里云 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 接入](../../integrations/im.md)。

## 权限

权限标签页控制设备智能体可用的本地工具权限。

| 权限 | 说明 |
| --- | --- |
| `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`。