---
title: AI Agent
description: 允许客户通过自然语言描述任务来管理其Linux虚拟机——Agent如何通过SSH连接、它可独立运行哪些操作，以及您必须准备好的环境。
url: https://nexcmp.com/zh-cn/docs/ai/ai-agent/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# AI Agent {#ai-agent}

> **后台位置：** System › Settings › AI provider (`/settings/ai`) —— 模块开关与提供商；System › Admin › License & updates (`/license`) —— 模块开关。**前台位置：** AI Agent (`/ai/agent`) 及页面 `/chat/agent`，或聊天内的 **Agent** 模式。

## 功能说明 {#what-it-does}

AI Agent连接到客户自己的Linux虚拟机并通过SSH执行自然语言描述的任务：“检查系统健康状况”、“安装Docker”、“查找最近的错误”、“释放磁盘空间”。它会显示其提议的每个命令及输出。只读命令可以自动运行；任何会更改服务器的操作都需要客户点击**Run**。

## 前提条件 {#requirements}

| 项目 | 要求 |
|---|---|
| AI模块与提供商 | 开启**AI**模块并配置可用的[AI provider](https://nexcmp.com/zh-cn/docs/ai/ai-providers/)。Agent还需要一个支持工具调用的模型。 |
| `openssh-client`面板服务器上 | Agent使用面板自身的`ssh`程序 (`/usr/bin/ssh`) 运行命令。安装程序会安装`openssh-client`；请通过`ssh -V`检查。否则Agent会报告“ssh client is not installed on the panel server”。 |
| 无独立的SSH网关 | 默认安装中会使用内置 SSH，**不需要** `ssh-proxy`Web 终端。只有在启用了可选的 *web SSH* 功能（`feature_ssh_web`）并安装了 `ssh-proxy` 服务时，Agent 才会转而通过 `ssh-proxy` 进行。 |
| 网络 | 面板服务器必须能够通过SSH端口（默认22）访问虚拟机的IP。请检查面板与客户机网络之间的防火墙和安全组。 |
| VM | 客户所有、**运行中**、未锁定、运行**Linux**（拒绝Windows虚拟机），且具有公共或可达的IP地址。 |
| SSH凭据 | 由NexCMP存储的虚拟机登录用户名和密码（在创建虚拟机或重置密码时保存，已加密），或者安装的面板操作密钥。如果两者都不存在，Agent会提示无法登录。 |

## 准备基础设施 {#prepare-the-infrastructure}

1. 检查面板服务器上的SSH客户端：

   ```bash
   ssh -V
   sudo apt-get install -y openssh-client   # only if missing
   ```

2. 检查面板服务器是否可以向客户虚拟机建立SSH连接：

   ```bash
   nc -vz 198.51.100.10 22
   ```

   将地址替换为测试虚拟机的IP。如果失败，请先修复路由或防火墙。
3. 确保客户机允许NexCMP存储的用户通过密码登录（某些云镜像默认禁用），或者在客户机上安装面板的操作密钥。

## 在NexCMP中连接 {#connect-in-nexcmp}

1. 完成[AI provider](https://nexcmp.com/zh-cn/docs/ai/ai-providers/)配置：开启模块、保存提供商、**Test connection**显示绿色。
2. 后台无需配置其他内容。模块开关会使客户门户中显示**AI Agent**入口。
3. 作为客户：打开**AI Agent**，选择一台运行中的服务器并点击**Choose server**。该页面首先使用固定的无害命令探测SSH（不调用AI），并显示*SSH connected*或失败原因。
4. 输入任务或选择一个快速入门（*检查系统健康状况*、*安装 Docker*、*安装 Nginx*、*查找近期错误*、*安全检查*、*释放磁盘空间*）。



## 命令运行方式 {#how-it-runs-commands}

- **来源：**面板服务器，带有系统 `ssh` 客户端，每次一条非交互式命令。目标始终是**数据库中的**虚拟机 IP，绝不使用请求中的 IP；且仅能访问所有者自己正在运行且未被锁定的虚拟机。
- **认证：**存储的密码通过进程环境中的一次性 `SSH_ASKPASS` 助手传递——不会写入磁盘或放入命令行。主机密钥不进行固定（虚拟机会使用新密钥重新安装）。每个命令的输出限制为 200 KB，并且每个命令都有时间限制（60 秒）。
- **Agent 循环：**AI 提出命令并读取输出；一个轮次最多经过 **10 步**后结束。
- **模式：**

  | 模式 | 行为 |
  |---|---|
  | **Confirm** | 每条命令都需等待 **Run**。 |
  | **Auto** | 只有通过严格只读白名单的命令才会自行运行（例如 `df -h`、`ps`、`journalctl`）。其他任何内容，以及解析器无法确切分析的内容（变量、命令替换、重定向到文件），均需等待 **Run**。 |

- **风险标签：**会覆盖或删除文件、写入磁盘、更改账户或 SSH Keys、向外部服务器发送数据、打开原始网络连接、运行混淆代码、下载并运行脚本、关机或重启机器，或者访问其他服务器的命令，即使在 Auto 模式下也始终会显示 **Needs confirmation**。
- **不受信任的输出：**命令输出会作为不受信任的数据显示给模型；其中的指令不会被执行。

## 验证 {#verify}

1. 选择一个正在运行的测试虚拟机。页面显示 *SSH connected*。
2. 询问“检查 CPU、内存和磁盘”。在 Auto 模式下，只读命令将运行，并且回答会进行总结。
3. 询问“安装 Nginx”。安装命令会与 **Run** 和 **Skip** 一起出现；在您按下 **Run** 之前，不会运行任何内容。
4. 顶部的计数器显示今日已使用的 AI 调用次数（例如 `3/300`）。

## 限制与注意事项 {#limits-notes}

- **每日限制：**每个客户每天（UTC）限 300 次 AI 调用；于 00:00 UTC 重置。额度用尽后，Agent 会回答“Daily AI quota reached”。
- **并发：**每个客户同时最多运行 2 个 Agent；一个会话一次运行一个轮次。
- **会话：**每个会话最多 100 条消息，每条消息 4,000 个字符。一个会话属于一个虚拟机；如果虚拟机被删除或转移，旧会话将变为只读。
- **虚拟机已被锁定、已停止或为 Windows 系统：**虚拟机显示为 *Locked*、*Stopped*、*Windows* 或 *No address*，无法被选择。
- **模拟登录：**管理员模拟客户登录时无法使用 Agent 的凭据功能（参见 [Log in as a customer](https://nexcmp.com/zh-cn/docs/customers/login-as/)）。
- **责任：**Agent 可能会犯错。门户会提示客户在运行命令前进行审查。请在您的条款中告知客户，他们需对批准执行的命令负责。
- 关闭AI模块会移除Agent条目，且路由将返回404 `module_disabled`。

## 故障排查 {#troubleshooting}

| 症状 | 原因 | 解决办法 |
|---|---|---|
| “面板服务器未安装ssh client (apt install openssh-client)” | 没有 `ssh` 二进制文件 | `sudo apt-get install -y openssh-client`. |
| “Agent登录失败” / `ssh: no saved credentials for this VM` | 没有存储的密码且没有操作密钥 | 在门户中重置虚拟机密码以便重新保存，或安装操作密钥。 |
| “服务器未及时响应” | 防火墙、SSH 未监听、虚拟机繁忙 | 从面板服务器测试 `nc -vz <ip> 22`；在虚拟机中启动 `sshd`。 |
| “无法在此服务器上连接 SSH” | 路由或安全组 | 允许面板服务器通过端口 22 访问虚拟机。 |
| “虚拟机未运行” / “禁止访问” | 虚拟机已停止、锁定、删除或不属于该客户 | 启动、解锁虚拟机或选择其他虚拟机。 |
| “不可用：N（已停止、已锁定或 Windows）” | 如上所述的原因 | 虚拟机必须为 Linux 系统且处于运行状态。 |
| “SSH 网关暂时不可用” | Web SSH 功能已启用，但 `ssh-proxy` 已宕机 | 启动 `ssh-proxy`，或关闭 Web SSH 功能以使用内置 SSH。 |
| “AI 响应过慢（超过 90 秒）” | 提供商响应缓慢 | 使用更快的模型或降低 **Reasoning effort**。 |
| “已达到每日 AI 配额” | 已使用 300 次调用 | 等待至 00:00 UTC。 |
| “此会话仍在运行” | 另一个轮次正在进行中 | 请等待或按 **Stop**。 |