---
url: https://qiwuadmin.com/features/agent.md
description: >-
  后台里的智能助手：业务人员用自然语言让模型 / 智能体查数据、联网查资料、按要求修改数据，每次修改都先由人确认。APP_AGENT 开关、模型配置（兼容
  OpenAI 接口）、联网搜索、外部 MCP 服务器、工具策略和审批模式、反问、技能、说明与提示词模板、限额与急停、用量、批量执行和安全模型，默认关闭。
---

# 智能助手

**智能助手**是后台里的一个对话页面。业务人员用自然语言提要求，模型 / 智能体就**用后台自己的工具、以这个用户本人的身份**去办：查数据、做汇总、按要求修改数据；需要外部信息时，它联网搜索并阅读网页。凡是要改数据，它都先把“改哪条记录、每个字段的旧值 → 新值、依据哪些来源”列出来，**由人确认后才执行**。

还可以在列表里勾选多条记录，让智能体对每一条批量执行同一个技能（比如“补齐客户信息”），结果进批次审批页，逐条或一次确认。

智能体只通过工具办事：工具就是各模块已有的 MCP 工具（和 [MCP 智能体接入](/features/mcp)用同一份工具清单和同一套检查），再加上内置的联网、计划清单和反问。它不执行命令、不读写服务器上的文件、不操作浏览器。

::: tip 默认关闭
智能助手默认关闭，不需要的项目可以跳过这一页。它运行在现有的 Redis 任务队列和 Socket.IO 推送上，不需要新的服务。完整说明见仓库的[后台智能体文档](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md)。
:::

## 打开开关

| 开关 | 在哪里 | 作用 |
| --- | --- | --- |
| `APP_AGENT` | 服务端环境变量，默认 `false` | 只在启动时读取，改完要重启**全部**服务端实例。关闭时整个模块不加载：`/api/agent/*` 全部返回 404，侧栏、角色授权树和租户套餐里都看不到 **智能体** 菜单组，页面右下角的入口也不出现 |
| `agent.paused` | **系统管理 → 参数设置**，默认 `false`，**只有超级管理员（root）能改** | 急停：改成 `true` 后拒绝新的对话和工具调用，正在运行的对话在半秒内停下；改回 `false` 就恢复。不需要重启，所有实例同时生效 |

`APP_AGENT` 和 `APP_MCP` 互不依赖：只开智能助手时，`/api/mcp` 仍然不存在。数据表始终由迁移创建，菜单和示例数据始终由种子写入，打开开关时不需要另外迁移。部署时的注意事项（出口防火墙、密钥）见[部署 · 智能助手](/guide/deploy#智能助手)。

打开后的第一步：

1. 超级管理员在 **智能体 → 智能体设置** 的“模型”页签里添加一个模型提供方（见下节）。没有可用的模型时，对话页提示联系管理员，输入框不能用；
2. 需要联网时，在“联网搜索”页签添加一个搜索服务商；
3. 在 **系统管理 → 角色管理** 里给业务角色勾选 **智能助手**；技能管理、批量执行和用量页要分别授权；
4. 开启[多租户](/features/multi-tenancy)时，先把 **智能体** 菜单组勾进租户套餐，这个租户的角色才能被授权。

**智能体** 菜单组紧跟在首页后面，有四个页面：

| 页面 | 内容 |
| --- | --- |
| **智能体 → 智能助手** | 对话页。批次审批页挂在它下面，不在菜单里显示 |
| **智能体 → 技能管理** | 个人和全租户的技能、提示词模板、租户说明 |
| **智能体 → 智能体设置** | 模型、联网搜索、外部 MCP、工具策略、平台技能、说明与限额。多租户时是平台专属页面，改动只有超级管理员能做 |
| **智能体 → 智能体用量** | 按日、用户或模型汇总的调用次数和 token 用量 |

见仓库的[启用](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#启用)。

## 配置模型

模型经**兼容 OpenAI 的接口**（Chat Completions）接入，国内外常见的模型服务和本地的 Ollama 都能用。在 **智能体 → 智能体设置** 的“模型”页签里，每个提供方填名称、接口地址、密钥和可用的模型，可以设为默认。每个模型还可以标注：是否支持推理强度（对话里可以选低、中、高）、能不能看图片、上下文窗口多大。

| 服务 | 说明 |
| --- | --- |
| DeepSeek、通义千问（阿里云百炼）、Kimi（月之暗面）、智谱、OpenAI | 填各家的接口地址和在各家控制台申请的密钥 |
| Ollama | 装在本机或内网，密钥留空 |

* 智能体依赖模型的**工具调用**（function calling）能力，请选支持它的模型；
* 密钥**只写不读**：加密后存进数据库，页面上只显示“已保存”。改了接口地址必须重新填密钥，原来的密钥不会被发到新地址；
* 每个会话可以从已配置的模型里选一个，没选时用默认提供方的第一个模型；
* 模型服务报错时，页面只显示“模型服务调用失败”和简短原因，不把对方返回的内容原样展示。

各家的接口地址和模型名示例见仓库的[配置模型](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#配置模型)。

## 联网搜索

智能体有两个内置的只读联网工具：一个搜索公网，一个阅读网页。

* 搜索服务目前支持**博查**（国内）和 **Tavily**（海外），在“联网搜索”页签添加，密钥同样加密存库、只写不读。没有配置搜索服务时，不提供搜索；
* 读网页**只能读**这一轮搜索结果里出现过的链接、用户在消息里给出的链接，或者管理员列进白名单的网站，防止网页内容诱导智能体把内部数据拼进网址发出去；
* 系统参数 `agent.web.mode` 设为 `off` 时，完全不提供联网工具。

见仓库的[联网搜索](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#联网搜索)。

## 外部 MCP 服务器

在“外部 MCP”页签里可以接入本系统以外的 MCP 服务器（Streamable HTTP 传输），让智能体也能用它们的工具。

* 鉴权可以不填、填一个请求头令牌，或者用 OAuth 客户端凭据，凭据加密存库、只写不读；
* 默认只能连接公网地址，要指向内网必须由超级管理员明确勾选允许；
* 点“同步”列出服务器上的工具。新工具默认**停用**，管理员逐个启用并设置审批策略；外部服务器自称“只读”不可信，只有管理员明确设为直接执行的工具才不用确认；
* 服务器在调用中途需要用户补充信息时，对话页显示一张表单卡片。

见仓库的[外部 MCP 服务器](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#外部-mcp-服务器)。

## 工具策略和审批模式

“工具策略”页签列出本系统的全部工具，每个设一个审批策略，对所有租户生效：

| 策略 | 含义 |
| --- | --- |
| 直接执行（`auto`） | 只读工具的默认值 |
| 询问（`ask`） | 停下来等发起人确认，写入工具的默认值 |
| 不提供（`deny`） | 智能体看不到这个工具 |

写入工具只能是“询问”或“不提供”，不能设成直接执行。在 MCP 工具页整体停用的工具，智能体同样用不了。

每个会话还可以切换**审批模式**：

* **只读**：只提供只读工具；
* **询问**（默认）：每次写入都要确认；
* **信任本会话**：同一个工具对同一条记录确认过一次后，本会话内不再询问。超级管理员可以用参数 `agent.trust_mode` 关掉这个选项。

审批卡片列出工具、要改的记录、每个字段的旧值 → 新值和这一轮读过的来源，按钮是“确认执行”“本会话内同意”“拒绝”“取消本轮”。拒绝时可以写一句理由，智能体不会再重试。不管哪种模式，**写入都不会在没人确认的情况下执行**。

另外还有**计划模式**：智能体只读，先列出要做的步骤，你确认后再切回执行。

见仓库的[工具策略](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#工具策略)和[对话页](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#对话页)。

## 反问和选项

智能体拿不准时（比如搜到几家名字相近的公司），会停下来问你：一次 1 到 4 个问题，每题 2 到 4 个选项（单选或多选），另有“其他”可以自己填。这一轮会停下等你回答，你也可以选择不回答。你填的文字只当作数据交给模型。

## 对话页

**智能体 → 智能助手** 的用法和常见的桌面聊天软件相似：

* **会话列表**：新建、搜索（标题和消息全文）、改名、置顶、归档、删除，按全部、进行中、未读、置顶筛选；临时会话不进列表，离开就删除；
* **回答**：逐字显示，工具调用可以折叠展开；支持的模型显示“思考”摘要；引用的网页列在回答末尾，回答后给出几条后续建议；
* **分叉、重发和撤回**：可以从任意一条消息分叉出新会话，或编辑最后一条消息后重发；“撤回”删除最后一轮，但**已经执行的修改不会回滚**；
* **分享和导出**：生成只读链接，只有同一租户的人能打开；也可以导出为 Markdown；
* **运行中发消息**：可以“追加到本轮”改方向，也可以“排到下一轮”，随时可以点“停止”；
* **附件**：可以带上已经上传到文件管理的文件，文本类文件、xlsx 的第一张表和图片（交给能看图片的模型）会读给模型；
* **斜杠命令**：输入 `/` 可以新建会话、压缩上下文、切换模型、切换审批模式或计划模式、选技能、插入提示词模板、查看用量等；
* **提醒**：一轮停下等你确认或回答，或者一轮较长的对话完成时，会发站内信提醒；
* **右下角入口**：任意页面右下角的 **智能助手** 按钮带着当前页面打开对话页；在列表页里，智能体还知道你勾选了哪几条。

见仓库的[对话页](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#对话页)。

## 技能

**技能**是一段任务说明，加上这项任务允许用的工具。比如“补齐客户信息”：逐个联网查官网、行业、城市……只填空字段，并写明来源。技能只是说明文字，不含可以执行的代码。

| 范围 | 谁维护 | 谁能用 |
| --- | --- | --- |
| 平台 | 超级管理员，在 **智能体设置** 的“平台技能”页签 | 所有租户的所有用户 |
| 租户 | 有技能管理权限的人，在 **智能体 → 技能管理** | 本租户的用户 |
| 个人 | 自己，在 **智能体 → 技能管理** | 自己 |

同名时个人的优先，其次是租户的，最后是平台的。

* 平时模型只看到技能的名称和描述，判断要用时才读取正文；
* 在输入框里打 `$` 加技能名（或用 `/skills`）可以直接指定技能；技能列了工具时，这一轮只提供这些工具；
* 一次对话做得好，可以点“存成技能”，让模型根据这次对话起草一个个人技能，保存为未启用，检查后再启用；
* 技能可以按 `SKILL.md` 格式导入、导出。

格式和写法见仓库的[技能](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#技能)。

## 说明、语气和提示词模板

* **说明**拼在给模型的系统提示里，依次是：平台说明（超级管理员）→ 租户说明（**技能管理** 页）→ 个人说明（每个人自己写，比如“回答用表格”）；
* **语气**是个人选项：默认、简洁、详细、亲切、正式；
* **提示词模板**是常用的提问，分个人和全租户两种，在输入框里用 `/prompts` 插入。

见仓库的[说明、语气与提示词模板](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#说明语气与提示词模板)。

## 限额、急停和用量

超级管理员可以用系统参数限制成本：每轮最多步数、最长时间和 token 数，每个用户、每个租户每天的 token 数，以及每个用户同时运行的对话数。超出时这一轮停下，并在对话里说明碰到了哪个上限。急停参数 `agent.paused` 见上文。

用量按用户、租户、模型和日期记账：**智能体 → 智能体用量** 按日、用户或模型汇总当前租户的调用次数和输入、输出 token；对话里的 `/status` 显示本会话的上下文用量、本轮和今天的用量与上限。

参数和默认值见仓库的[限额、急停与用量](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#限额急停与用量)。

## 批量执行和“补齐客户信息”示例

模板带了一个示例：**生成示例 → 示例客户** 里预置了几家知名公司，故意留空了一些字段；平台技能 **补齐客户信息** 配了三个工具（查客户、读客户资料、修改客户资料）。

* 在对话页直接说“补齐华为技术有限公司的行业”；
* 或者在示例客户列表里勾选几个客户，点“让智能体补齐”：每个客户开一个会话，按发起人的并发上限依次开始，每处修改都停在审批上；
* 批次审批页列出每一行的状态和待确认的修改，可以逐条确认，也可以“全部确认”或“全部拒绝”。

批量执行要单独授权，而且只能对自己能看到的记录发起。给自己的列表加上批量执行的方法见仓库的[给自己的模块加工具、批量目标与技能](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#给自己的模块加工具批量目标与技能)，示例见[批量执行与“补齐客户信息”示例](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#批量执行与补齐客户信息示例)。

## 安全模型

* **只属于发起人**：会话、审批和提问只有本人能看、能操作，别人打开一律 404；只有发起人本人能确认修改；
* **按用户本人的身份运行**：工具沿用 MCP 的检查（权限点、数据范围、租户和套餐、参数校验、超时、输出里的密钥字段遮蔽）。智能体能做的不会超过发起人自己在页面上能做的；每一轮开始前重新读取身份，用户被停用或删除后就不再继续；
* **写入必须有人确认**：确认之后如果权限、审批模式或策略已经变了，调用照样会被拦下；
* **外部内容不可信**：网页、搜索结果和外部 MCP 的输出都当作“只是数据”交给模型。即使模型被网页诱导去改数据，修改也会停在审批卡片上，卡片列出依据的来源；
* **出站请求只连公网**：读网页和外部 MCP 只连公网地址，每次跳转都重新检查。模型的接口地址不做这项检查（为了本机或内网的 Ollama），只有超级管理员能配置；
* **密钥加密**：模型、搜索服务和外部 MCP 的凭据用 `APP_SECRET` 派生的密钥加密存库，只写不读；更换 `APP_SECRET` 后要重新填写；
* **审计**：每次工具调用（包括被拒的）都在 **系统管理 → 日志管理 → 操作日志** 里记一条，标明来自对话页；被修改的数据，修改人照常记为发起人。

见仓库的[安全模型](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#安全模型)。

## 在演示站体验

[在线演示](/guide/introduction#在线演示)**没有打开**智能助手。要体验，请在自己的安装上打开 `APP_AGENT`，并配置一个模型。

## 已知限制

* 并发对话数是软限制，同时到达的请求可能让一个用户多出一轮；
* 模型、搜索服务和外部 MCP 服务器都是平台配置，租户暂时不能自己添加外部 MCP 服务器；
* 只支持远程 HTTP 的 MCP 服务器，不支持要在服务器上启动进程的 stdio 类服务器；
* 撤回一轮不回滚已经执行的修改；工具超时只结束等待，已经开始的数据库操作无法中断；
* 模型的回答和判断可能出错，审批卡片上的旧值 → 新值和来源请逐条核对。

完整清单见仓库的[已知上限](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/agent.md#已知上限)。

相关功能：

* [MCP 智能体接入](/features/mcp)
* [权限与数据范围](/features/permission)
* [多租户](/features/multi-tenancy)
* [安全基线](/features/security)