# 控制台

**控制台** 是 QwenPaw 内置的 Web 管理界面。运行 `qwenpaw app` 后，在浏览器中打开
`http://127.0.0.1:8088/` 即可进入。

**在控制台中你可以：**

- 和 QwenPaw 实时对话
- 启用/禁用/配置消息频道
- 管理所有聊天会话
- 管理定时任务和心跳
- 编辑 QwenPaw 的人设和行为文件
- 开关/导入技能以定制 QwenPaw 的能力
- 开关工具
- 管理MCP客户端
- 修改运行配置
- 管理多智能体
- 配置 LLM 提供商并选择使用的模型
- 管理工具所需的环境变量
- 管理工具和技能的安全功能
- 查看 LLM Token 消耗统计
- 配置对语音消息的处理方式

左侧侧边栏列出所有功能，分为 **聊天**、**控制**、**工作区**、**设置** 四组，点击即可
切换页面。下面按顺序逐一介绍每个功能的操作方法。

> **看不到控制台？** 请确认前端已构建，构建方式见 [CLI](./cli)。

---

## 聊天

> 侧边栏：**聊天 → 聊天**

这是你和 QwenPaw 对话的地方。打开控制台后默认就是这个页面。

![聊天](https://img.alicdn.com/imgextra/i1/O1CN01ikrU3k1TRdNESHtzV_!!6000000002379-2-tps-3822-2070.png)

**选择模型：**
聊天页面右上角可以为当前智能体选择需要使用的模型。

**发送消息：**
在底部输入框中输入内容，按 **Enter** 或点击发送按钮（↑），QwenPaw 会实时回复。

**语音输入：**
发送区支持**语音输入**（需浏览器与系统麦克风权限）。处理方式与 **语音转写** 中的设置一致（例如先转写再交给模型）。

**附件：**
发送区支持上传**附件**，包括文档、图片、音视频等（以界面提示为准，单文件有大小上限）。

**新建会话：**
点击聊天页面右上角 **新建聊天** 按钮，开始一段全新的对话。每个会话独立保存各自的对话记录。

**切换会话：**
点击聊天页面右上角 **聊天历史** 按钮，即可查看及切换历史聊天内容。

**删除会话：**
在聊天历史栏中，点击任意会话条目右侧的 **垃圾桶** 按钮即可删除。

---

<!-- TODO: 看一下收件箱要不要换位置 -->

## 收件箱

> 侧边栏：**收件箱 → 收件箱**

收件当前用于集中处理审批时间，接收定时任务与心跳的执行结果，适合做统一回看与处理。

**查看未读：**
收件箱入口会显示未读提示点。进入后可处理未读内容，避免遗漏关键通知。

**审批：**
所有 Agent 在 console channel 的聊天中触发的需要审批的内容，都会出现在收件箱的审批页面中。

![todo](https://img.alicdn.com/imgextra/i1/O1CN01SYaJiY1iBLX2ue6K6_!!6000000004374-2-tps-2966-1858.png)

你可以在这个页面对来自所有agent的审批内容进行统一操作（批准/拒绝/取消任务）。审批操作有倒计时，结束时未操作则 **默认拒绝**。在该页面进行的审批操作与在聊天页面弹窗进行操作时同步的。

**推送消息：**
当前用户可在定时任务和心跳的页面自行选择这两种任务的执行结果是否推送到收件箱。点击任意消息可以查看执行详情，包括执行轨迹。

![todo](https://img.alicdn.com/imgextra/i3/O1CN014IeD9J1xljELLdZL9_!!6000000006484-2-tps-2984-1882.png)

---

## 频道

> 侧边栏：**控制 → 频道**

在这里管理各消息频道（Console、钉钉、飞书、Discord、QQ、微信、iMessage等）的开关和凭据。

![频道](https://img.alicdn.com/imgextra/i1/O1CN01sDfcFb1kfEcUB66Va_!!6000000004710-2-tps-3810-2064.png)

**启用一个频道：**

1. 点击你要配置的频道卡片。

2. 右侧滑出配置面板，打开 **已启用** 开关。

3. 填写该频道必需的凭证——每个频道的需求不同，详情请见[频道配置](./channels)。

4. 点 **保存**，几秒内自动生效，无需重启。

**禁用一个频道：**
打开同一个配置面板，关闭 **已启用** 开关，然后 **保存**。

> 各平台的凭据获取步骤，请看 [频道配置](./channels)。

---

## 会话

> 侧边栏：**控制 → 会话**

在这里查看、筛选和清理所有频道的聊天会话。

![会话](https://img.alicdn.com/imgextra/i4/O1CN01JTBZoq1KxOIIRuL6J_!!6000000001230-2-tps-3822-2070.png)

**查找会话：**
在搜索框中输入用户名过滤，或用下拉菜单按频道筛选，表格会即时更新。

**重命名会话：**
点击某行的 **编辑** 按钮 → 修改名称 → 点 **保存**。

**删除单条会话：**
点击某行的 **删除** 按钮 → 弹窗确认即可。

**批量删除：**
勾选要删除的行 → 点击出现的 **批量删除** 按钮 → 确认。

---

## 定时任务

> 侧边栏：**控制 → 定时任务**

在这里创建和管理 QwenPaw 按时间自动执行的定时任务。

![定时任务](https://img.alicdn.com/imgextra/i1/O1CN01UqMEHK1g2WfLs2wUQ_!!6000000004084-2-tps-3822-2070.png)

**创建新任务：**

> 如果定时任务没有创建成功，可以参考 [FAQ](https://qwenpaw.agentscope.io/docs/faq) 的 **定时任务错误排查** 寻找原因

创建定时任务的 **最简单的方式是直接与 QwenPaw 对话**，让他为你创建。例如你想在钉钉上收到喝水提醒，则在钉钉上与 QwenPaw 对话：“帮我创建一个定时任务，每隔 5 分钟提醒我喝水。”创建完成后，可以在控制台的定时任务页面看到创建好的定时任务。

另外一种方式是在控制台页面创建：

1. 点击 **创建任务** 按钮。

2. 按区域填写表单：
   - **基本信息** —— 给任务一个 ID（如 `job-001`）、一个名称（如「每日摘要」），
     并打开启用开关。
   - **调度** —— 可选择执行时间；如果选项不满足需求，可填写 **Cron 表达式**（五段式，如 `0 9 * * *` = 每天 9:00）。时区默认采用当前智能体的用户时区，可在此修改。
   - **任务类型及内容**
     - 选择 **text**：发送**消息内容**中的固定文本
     - 选择**agent**：填写**请求内容**，会定时向QwenPaw转发content.text中的请求文本
   - **投递** —— 选择目标频道（如 Console、钉钉）、目标用户、目标会话ID以及分发模式
     （**流式** = 实时发送，**最终** = 完成后一次性发送）。
   - **高级选项** —— 按需调整最大并发数、超时时间和宽限时间。
3. 点 **保存**。

**启用 / 禁用任务：**
点击行内的开关即可。

**编辑任务：**
先**禁用**需要编辑的任务，点击 **编辑** 按钮 → 修改任意字段 → **保存**。

**立即执行一次：**
点击 **立即执行** → 确认，任务会马上运行一次。

**删除任务：**
先**禁用**需要删除的任务，点击 **删除** → 确认。

---

## 心跳

> 侧边栏：**控制 → 心跳**

![心跳](https://img.alicdn.com/imgextra/i4/O1CN01jW2DeC1QIWeM4HHBM_!!6000000001953-2-tps-3822-2070.png)

为**当前选中的智能体**配置定时「自检」：按间隔把 `HEARTBEAT.md` 里的内容当作用户消息发给 QwenPaw，并可把回复投递到指定目标。

**常用项：**

- **启用**：打开后才会按间隔执行。
- **间隔**：数字 + 单位（分钟 / 小时）。
- **投递目标**：`main` 仅在主会话执行；`last` 可把结果发到上次与用户对话的频道。
- **活跃时段**（可选）：仅在一天内指定时间段内触发，避免夜间打扰。

修改后 **保存** 生效。文案与语义详见 [心跳](./heartbeat)。

---

## 文件

> 侧边栏：**工作区 → 文件**

在这里编辑定义 QwenPaw 人设和行为的文件——SOUL.md、AGENTS.md、
HEARTBEAT.md 等——全部在浏览器中完成。

> **多智能体：** 从 **v0.1.0** 开始，QwenPaw 支持**多智能体**功能。
> 您可以在同一个 QwenPaw 实例中运行多个独立的智能体，每个智能体拥有独立的
> 工作区、配置、记忆和对话历史。智能体之间还可以互相协作。在控制台顶部可以切换当前操作的智能体。
> 详见 [多智能体](./multi-agent)。

![文件](https://img.alicdn.com/imgextra/i4/O1CN01Buqn3J1YJSNgrz9eY_!!6000000003038-2-tps-3822-2070.png)

**编辑文件：**

1. 点击文件列表中的文件名（如 `SOUL.md`）。
2. 文件内容出现在编辑器中，关闭预览按钮，修改内容。
3. 点 **保存** 生效，或点 **重置** 放弃修改并重新加载。

**查看每日记忆：**
如果存在 `MEMORY.md`，点击旁边的 **▶** 箭头可展开按日期分组的条目，点击某个日期
即可查看或编辑当天的记忆。

**下载整个工作区：**
点击 **下载** 按钮，工作区会打包为 `.zip` 文件保存到本地。

**上传 / 恢复工作区：**
点击 **上传** 按钮 → 选择 `.zip` 文件（最大 100 MB），当前工作区文件会被替换。
适合在不同机器之间迁移或从备份恢复。

---

## 技能

> 侧边栏：**工作区 → 技能**

在这里管理扩展 QwenPaw 能力的技能（如读取 PDF、创建 Word 文档、获取新闻等），更详细的内容请看 [Skills](./skills)。

![技能](https://img.alicdn.com/imgextra/i1/O1CN015rwm8V24Aoc48bGTp_!!6000000007351-2-tps-3822-2070.png)

**启用技能：**
点击技能卡片底部的 **启用** 链接，立即生效。

**禁用技能：**
点击 **禁用** 链接，同样立即生效。

**查看技能详情：**
点击技能卡片可查看完整说明。

**编辑技能：**

点击技能卡片 → 关闭内容预览 → 修改技能内容 → 点击保存。

**添加技能：**

页面右上角的 **添加技能** 下拉是所有添加方式的统一入口：

- **创建技能**：输入技能名称（如 `weather_query`）和技能内容（Markdown 格式，
  需包含 `name` 和 `description`），点 **创建**。
- **从技能池载入**：在弹窗中勾选要载入当前智能体的技能，点 **确认**。
- **通过Zip上传**：选择本地技能 **zip** 文件即可导入。
- **通过URL上传**：粘贴技能 URL（弹窗内列出受支持来源与示例，点击示例可填入），
  点 **确认**。
- **浏览市场**：页面切换到内嵌的技能市场，搜索或按分类浏览，点卡片上的
  **保存** 安装到当前智能体；点 **返回**（或浏览器后退）回到技能列表。

**将技能同步到技能池：**

1. 点击 **同步到技能池**。
2. 选择想要同步到技能池中的技能。
3. 点击 **确认**。

**删除技能：**
点击卡片上的 **删除** → 二次确认即可删除。如果技能当前处于启用状态，会自动先
禁用再删除。

---

## 工具

> 侧边栏：**工作区 → 工具**

![工具](https://img.alicdn.com/imgextra/i1/O1CN01Ofuk2I1pH1kRvkwcr_!!6000000005334-2-tps-3822-2070.png)

按**内置工具名称**单独开启或关闭（如读文件、执行命令、浏览器等）。关闭后该 Agent 在对话中无法调用该工具。

可使用顶部的 **全部启用** / **全部禁用** 批量操作。变更即时作用于**当前智能体**。

---

## MCP

> 侧边栏：**工作区 → MCP**

在这里启用/禁用/删除**MCP**，或者创建新的客户端。

![MCP](https://img.alicdn.com/imgextra/i2/O1CN01J0qnP91bQH7nxR2ww_!!6000000003459-2-tps-3822-2070.png)

**创建客户端**
点击右上角的**创建客户端**，填写必要信息，点击**创建**，可以看到MCP客户端列表中新增内容。

## 运行配置

> 侧边栏：**工作区 → 运行配置**

![运行配置](https://img.alicdn.com/imgextra/i2/O1CN01isFubh1fmxDTGufCc_!!6000000004050-2-tps-3810-2064.png)

本页集中配置**当前智能体**的运行参数，分多块卡片，改完后点底部 **保存**（**重置** 可重新拉取服务端数据）。

- **React 智能体**：界面语言、用户时区、最大迭代次数、最大上下文长度等。
- **LLM 自动重试**：最大重试次数等。
- **LLM 并发限流**：最大并发请求数等。
- **上下文管理**：最大输入长度等。
- **上下文压缩配置**：上下文压缩阈值比例等。
- **工具结果压缩配置**：最新工具结果范围等。
- **记忆总结配置**：自动搜索最大结果数等。
- **向量模型配置**：是否启用 Embedding 缓存等。

更细的机制说明见 [上下文](./context) 和 [配置与工作目录](./config)。

---

## 智能体管理

> 侧边栏：**设置 → 智能体管理**

![智能体管理](https://img.alicdn.com/imgextra/i3/O1CN01mG2dkX1GHTaJLMjWo_!!6000000000597-2-tps-3822-2070.png)

创建、编辑、启用/禁用或删除智能体；列表中的 **描述** 会用于多智能体协作时的分工判断，建议写清用途。

Console 页面左上角的 **当前智能体** 用于切换当前操作对象；**智能体管理** 页面修改的是各智能体的元数据（名称、描述、自定义工作区路径等）。详见 [多智能体](./multi-agent)。

---

## 模型

> 侧边栏：**设置 → 模型**

在这里配置 LLM 提供商，并选择默认模型。详情请见 [Models](./models)。

![模型](https://img.alicdn.com/imgextra/i2/O1CN01ardjB01FvwzCXWW2f_!!6000000000550-2-tps-3810-2064.png)

在本页面，你可以：

- 配置云端提供商（ModelScope、DashScope、OpenAI、Anthropic 等）
- 配置本地提供商（llama.cpp、Ollama、LM Studio）
- 通过填写 API 详情添加自定义提供商
- 选择智能体默认使用的模型

---

## 技能池

> 侧边栏：**设置 → 技能池**

在这里对技能做全局管理，更详细的内容请看 [Skills](./skills)。

![技能池](https://img.alicdn.com/imgextra/i2/O1CN014Kpiia1OW9CKI06jN_!!6000000001712-2-tps-3822-2070.png)

在当前页面，可对技能做以下操作：

- 广播技能到具体的智能体
- 更新内置技能到最新版本
- 通过 **添加技能** 入口添加：创建技能、通过Zip上传、通过URL上传、
  浏览市场（市场中点 **保存** 即保存到技能池）
- 编辑技能
- 删除技能

---

## 环境变量

> 侧边栏：**设置 → 环境变量**

在这里管理 QwenPaw 的工具和技能在运行时需要的环境变量（如 `TAVILY_API_KEY`）。

![环境变量](https://img.alicdn.com/imgextra/i2/O1CN01EIfkyk1mR9epvvu5G_!!6000000004950-2-tps-3822-2070.png)

**添加变量：**

1. 点击底部的 **+ 添加变量**。
2. 输入变量名（如 `TAVILY_API_KEY`）和对应的值。
3. 点击 **保存**。

**编辑变量：**
修改已有行的 **Value** 字段，然后点 **保存**。
（变量名保存后为只读，如需改名请先删除再新建。）

**删除变量：**
点击行右侧的 **🗑** 图标 → 二次确认后删除。

**批量删除：**
勾选要删除的行 → 点工具栏的 **删除** → 二次确认后删除。

> **注意：** 环境变量值的有效性需要用户自行保证，QwenPaw 只负责存储和加载。
>
> 更多说明见 [配置 — 环境变量](./config#环境变量)。

---

## 安全

> 侧边栏：**设置 → 安全**

![安全](https://img.alicdn.com/imgextra/i4/O1CN01APDb151R02HB3zHet_!!6000000002048-2-tps-3822-2070.png)

分 **工具防护**、**文件防护**、**技能扫描器** 等页签：分别控制危险工具参数拦截、敏感路径访问拦截、技能包安全扫描策略。

在页内开关、改规则后 **保存**。详情请见 [安全](./security)。

---

## Token 消耗

> 侧边栏：**设置 → Token 消耗**

![token消耗](https://img.alicdn.com/imgextra/i2/O1CN01hK1Elq270gie8c8NX_!!6000000007735-2-tps-3810-2064.png)

在这里查看一段时间内的 LLM Token 消耗，按日期和模型统计。

**查看消耗：**

1. 选择日期范围（默认最近 30 天）。
2. 点击 **刷新** 获取数据。
3. 页面展示总 Token 数、总调用次数、按模型和按日期的明细。

**通过对话查询：**

在聊天中直接问 QwenPaw「最近用了多少 token？」或「帮我看看 token 消耗」，Agent 会调用 `get_token_usage` 工具并返回统计结果。

> 数据存储在 `~/.qwenpaw/token_usage.json`，可通过 `QWENPAW_TOKEN_USAGE_FILE` 环境变量自定义文件名。详见 [配置 — 环境变量](./config#环境变量)。

---

## 语音转写

> 侧边栏：**设置 → 语音转写**

![语音转写](https://img.alicdn.com/imgextra/i2/O1CN01yddyyw1HwWhQnbqwR_!!6000000000822-2-tps-3822-2070.png)

配置**各频道发来的语音/音频**在进入模型前的处理方式（与聊天里的语音输入、频道语音消息共用这套设置）。

- **音频模式**：**自动** — 先按下方转写设置转成文字再交给模型（多数模型适用）；**原生** — 直接把音频当附件交给模型（仅部分支持音频的模型可用）。
- **转写后端**：**关闭**；**Whisper API**；**本地 Whisper**。

**Whisper API 安装配置：**

1. 在 [模型](#模型) 中添加兼容 OpenAI 的提供商。
2. 确认该提供商支持 `audio/transcriptions`，并已配置有效 API Key。
3. 回到本页，将该提供商选为 Whisper API 后端。

**本地 Whisper 安装配置：**

1. 使用系统包管理器安装 `ffmpeg`。
2. 在运行 QwenPaw 的 Python 环境中安装可选依赖：`pip install "qwenpaw[whisper]"`。
3. 重启 QwenPaw，然后在本页选择 **本地 Whisper**。

可用以下命令验证本地安装：

```bash
ffmpeg -version
python -c "import whisper; print('openai-whisper installed')"
```

保存后对新收到的语音生效。详情以页面内说明为准。

---

## 快速索引

| 页面       | 侧边栏路径        | 你能做什么                         |
| ---------- | ----------------- | ---------------------------------- |
| 聊天       | 聊天 → 聊天       | 对话、语音输入、附件、管理会话     |
| 频道       | 控制 → 频道       | 启用/禁用频道、填写凭据            |
| 会话       | 控制 → 会话       | 筛选、重命名、删除会话             |
| 定时任务   | 控制 → 定时任务   | 创建/编辑/删除任务、立即执行       |
| 心跳       | 控制 → 心跳       | 间隔、投递目标、活跃时段           |
| 文件       | 工作区 → 文件     | 编辑人设文件、记忆、上传/下载      |
| 技能       | 工作区 → 技能     | 启用/禁用、创建/Zip/URL/市场添加   |
| 工具       | 工作区 → 工具     | 按名称开关内置工具                 |
| MCP        | 工作区 → MCP      | 管理 MCP 客户端                    |
| 运行配置   | 工作区 → 运行配置 | 迭代/上下文/重试/压缩/摘要/嵌入等  |
| 智能体管理 | 设置 → 智能体     | 增删改智能体、启用/禁用            |
| 模型       | 设置 → 模型       | 提供商、下载本地模型、选择活跃模型 |
| 技能池     | 设置 → 技能池     | 内置技能和可复用共享技能的来源仓库 |
| 环境变量   | 设置 → 环境变量   | 工具与技能用到的 Key 等            |
| 安全       | 设置 → 安全       | 工具守卫、技能扫描、文件防护       |
| Token 消耗 | 设置 → Token 消耗 | 按日期/模型查看用量                |
| 语音转写   | 设置 → 语音转写   | 音频模式、Whisper API/本地转写     |

---

## 相关页面

- [配置与工作目录](./config) —— 配置字段、提供商、环境变量
- [频道配置](./channels) —— 各频道的接入步骤和凭据获取
- [技能](./skills) —— 内置技能说明和自定义技能编写
- [心跳](./heartbeat) —— 心跳配置
- [上下文](./context) —— 压缩与上下文机制
- [安全](./security) —— Web 登录、工具守卫与文件防护详解
- [CLI](./cli) —— 命令行参考
- [多智能体](./multi-agent) —— 多智能体配置、管理与协作
