SSHClient 教程：PyQt5 远程终端 + AI Agent 运维助手

管几台 Linux 服务器，Xshell 要收费、PuTTY 功能太简陋、FinalShell 又有广告，想要一个免费、功能全、还能让 AI 帮你干活的 SSH 客户端，SSHClient 就是为这个需求做的：基于 PyQt5 与 paramiko 的 Windows SSH 客户端，带交互式终端、SFTP 文件浏览、CPU/内存/磁盘实时监控，还集成了 OpenAI 兼容的 AI Agent，可以用自然语言让 AI 去远程主机上执行命令、查指标、读写文件。本文从安装、配置到 AI 运维实战，把它完整讲一遍。

一、项目简介

SSHClient（仓库名 sshclient）是 git.cnbugs.com 上 AI-Agent 组织的一个开源项目。它是一个桌面 SSH 客户端，界面用 PyQt5 写，SSH 连接用 paramiko，定位是“Windows 上开箱即用的免费 SSH 客户端”，同时代码兼容 macOS 与 Linux。最大的亮点是内置的 AI Agent：接 OpenAI 兼容的 API（OpenAI、DeepSeek、Kimi、通义千问、Ollama 等），用自然语言下指令，AI 自动调用工具操作远程主机。

• 仓库：git.cnbugs.com/AI-Agent/sshclient
• 语言：Python（PyQt5 + paramiko）
• 平台：Windows 为主，代码兼容 macOS / Linux
• 打包：PyInstaller 打成单文件 exe，约 50-60 MB
• AI：OpenAI 兼容 API，5 个工具自动调用
• 许可证：MIT

二、功能特性总览

模块	说明
多主机管理	增删改查、密码/私钥双认证、配置导入导出、配置持久化到 ~/.sshclient/
远程终端	真实交互式 shell（Xshell 风格）、ANSI 颜色、本地历史、Ctrl+A/E/U/K/W 快捷键
命令片段	20+ 预置常用命令（ss/df/ps/docker/systemctl 等），一键发送到终端，可自定义增删改
SFTP 文件浏览	目录树浏览、上传/下载（带进度条）、新建目录、删除、重命名、双击进入
实时监控	CPU/内存/负载/启动时间/磁盘/网络速率/进程列表，1-10 秒可调刷新间隔
趋势迷你图	CPU 和内存使用率实时折线图，最近 60 个采样点
进程管理	进程表（500 条）、搜索过滤、CPU/内存排序、树形视图、右键杀进程、批量操作
AI Agent	OpenAI 兼容 API（OpenAI / DeepSeek / Moonshot / 通义千问 / Ollama 等），5 个工具自动调用
暗色主题	视图菜单一键切换暗/亮主题，偏好自动持久化
跨平台	代码兼容 Windows / macOS / Linux（PyQt5 + paramiko）

三、适用场景

• 日常运维：同时管多台服务器，终端、文件、监控、进程都在一个窗口里，不用来回切换工具。
• 排障：服务器 CPU 高了、磁盘满了、服务起不来，先让 AI 去看一圈，再按 AI 给的结论动手。
• 批量巡检：用命令片段一键发常用命令（ss、df、ps、docker ps、systemctl status），不用每次手敲。
• 文件传输：传配置文件、拉日志、备份小文件，SFTP 图形界面比 scp 命令直观。
• 新手运维：记不住命令的新手可以用自然语言问 AI，让 AI 在远程主机上执行并解释结果。
• 内网 + 本地模型：接 Ollama 本地模型，AI 对话不出内网，适合对数据敏感的环境。

四、安装与构建

4.1 Windows：双击打包，拿 exe 直接用

最简单的方式是双击 build_windows.bat 打包：

• 安装 Python 3.10+（安装时勾选 Add to PATH）。
• 把整个项目目录拷到 Windows 电脑。
• 双击 build_windows.bat，等 2-3 分钟。
• 产物是 dist\SSHClient.exe，单文件约 50-60 MB，拷给任何人双击就能运行，不用再装 Python。

手动打包的方式也一样简单：

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
pyinstaller build.spec --clean --noconfirm

4.2 Linux/macOS：开发运行与打包

./build.sh        # 一键打包当前平台二进制
python main.py    # 直接开发运行

4.3 测试

source venv/bin/activate
python test_core.py   # 核心模块 smoke test（无网络依赖）
python test_ui.py     # UI 组件加载测试（offscreen 渲染）
python test_e2e.py    # 端到端测试（需本机或可访问的 sshd）

五、主机管理

左侧点“➕ 新增主机”，填主机名或 IP、端口、用户名、密码（可选私钥文件）。配置持久化到 ~/.sshclient/ 目录，换电脑时可以导出配置再导入。认证支持密码与私钥两种方式，私钥文件直接选本地的 .pem 或 id_rsa，生产服务器建议用私钥 + 禁密码登录的组合。

选中主机点“🔌 连接”，状态指示器变绿后就可以使用。连接信息包括主机、端口、用户名、认证方式，改配置不用重新加主机，直接编辑即可。

六、远程终端与命令片段

“⌨ 终端”Tab 是真实交互式 shell，Xshell 风格：支持 ANSI 颜色、↑↓ 历史回放、Ctrl+A/E/U/K/W 行编辑快捷键，vim、top、htop 这类交互程序都能正常用。

命令片段是提效的关键：工具栏下拉框里有 20+ 预置常用命令（ss、df、ps、docker、systemctl 等），选中后一键发送到终端，不用手敲。点 ⚙ 可以管理自定义片段，把你常用的巡检命令存进去：

# 几个值得存成片段的巡检命令
ss -tlnp                          # 看监听端口
df -h                             # 看磁盘
free -h                           # 看内存
ps aux --sort=-%mem | head -20    # 看最占内存的进程
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
systemctl list-units --type=service --state=failed
journalctl -u nginx -n 50 --no-pager

七、SFTP 文件浏览

“📁 文件”Tab 是 SFTP 图形界面：目录树浏览、双击目录进入、双击文件直接下载；上传、下载带进度条；支持新建目录、删除、重命名。传配置文件、拉日志、备份小文件都在这里完成，不用另开 WinSCP。

注意 SFTP 走的是 SSH 的 22 端口，和终端共用同一条连接，不用额外开端口。传大文件时进度条会显示实时速度，传一半断了可以重新传。

八、实时监控与进程管理

“📊 监控”Tab 点“开始监控”，指标按设定间隔（1-10 秒可调）刷新：CPU、内存用大字突出，下方有实时趋势折线图（最近 60 个采样点），磁盘用进度条，网络显示当前速率。下半区是进程管理表，支持搜索过滤、CPU/内存排序、树形视图、右键杀进程、批量操作。

这个监控是轻量的：它通过 SSH 通道定时在远程执行命令采集指标，不需要在服务器上装 agent。适合临时看一眼服务器状态，不适合替代 Prometheus + Grafana 这种长期监控。

九、AI Agent 配置与使用

AI Agent 是 SSHClient 最有特色的功能。它通过 OpenAI 兼容的 HTTP API 跟大模型对话，并把 5 个工具暴露给模型，模型可以自主决定调用哪个工具、在远程主机上执行操作，再把结果汇总成结论给你。整个过程不需要本地 GPU，配好 API Key 与 endpoint 就能用。

9.1 配置 AI

• 点“⚙ AI 设置”，选择预设（OpenAI / DeepSeek / Kimi / 通义千问 / Ollama）或自定义填 API Key。
• 回到“🤖 AI Agent”Tab，用自然语言提问。

预设	Base URL	模型
OpenAI	https://api.openai.com/v1	gpt-4o-mini
DeepSeek	https://api.deepseek.com/v1	deepseek-chat
Moonshot Kimi	https://api.moonshot.cn/v1	moonshot-v1-8k
通义千问	https://dashscope.aliyuncs.com/compatible-mode/v1	qwen-turbo
智谱 GLM	https://open.bigmodel.cn/api/paas/v4	glm-4-flash
Ollama（本地）	http://127.0.0.1:11434/v1	qwen2.5:7b
自定义	-	任意 OpenAI 兼容端点

9.2 AI 能调用的 5 个工具

这 5 个工具是 AI 操作远程主机的全部手段（以源码 core/ai_agent.py 中的 TOOL_DEFINITIONS 为准）：

工具	作用	关键参数
exec_ssh_command	在远程主机执行一条 shell 命令，返回标准输出、错误与退出码	command（必填），timeout（默认 30 秒，最大 300 秒）
get_system_metrics	获取实时系统指标：CPU 使用率/核心数、内存、磁盘、各网卡收发字节、负载	无参数
list_remote_files	列出远程主机指定目录的文件与子目录	path（默认 /）
read_remote_file	读取远程主机上一个文本文件的内容（最大 8000 字节，超过截断）	path（必填）
upload_local_file	把本地文件上传到远程主机的指定路径	local_path、remote_path（必填）

9.3 使用示例

回到 AI Agent Tab，用自然语言提问，AI 会自动调用工具并给出结论：

• “帮我看 CPU 为什么这么高”——AI 会调 get_system_metrics 看指标，再调 exec_ssh_command 查最占 CPU 的进程，最后告诉你哪个进程、什么原因。
• “找出 /var/log 下最大的 10 个文件”——AI 调 exec_ssh_command 执行 du 排序，把结果列出来。
• “重启 nginx 服务”——AI 调 exec_ssh_command 执行 systemctl restart nginx，再确认服务状态。

AI 的工作方式是多轮工具调用：单轮最多 8 个工具调用步骤（max_steps=8），避免死循环；每轮先调工具拿真实数据，再回答，不凭空猜测；对破坏性操作（rm -rf、kill -9、systemctl stop、重启等）会先向你确认；回复用中文，给出可执行的结论和命令。工具返回的结果超过 6000 字符会被截断，避免撑爆上下文。

从代码层面看，AI Agent 的调用方式也很简单（core/ai_agent.py）：

from core.ai_agent import AIAgent

# 初始化：API Key + 兼容端点 + 模型
agent = AIAgent(
    api_key="sk-xxxx",
    base_url="https://api.deepseek.com/v1",
    model="deepseek-chat",
)

# 一轮对话：user_message 是你的问题，
# tool_executor 是执行工具的回调（工具名, 参数）-> 文本结果
answer = agent.chat(
    "帮我看 CPU 为什么这么高",
    tool_executor=executor,
)
print(answer)

十、AI 安全注意事项

这一点必须单独强调：AI Agent 可以执行任意命令，安全边界由你自己把控。

• API Key 权限：README 明确建议使用只读权限的 API Key，或者在 prompt 中限定危险操作前需确认。
• 破坏性操作要确认：AI 的系统提示词里写了，对 rm -rf、kill -9、systemctl stop、重启等操作务必先确认，不要为了省事关掉这个约束。
• 生产环境慎用：先在测试机上跑顺了，确认 AI 的行为符合预期，再用到生产主机；重要操作先在终端里手动确认一遍。
• 本地模型：对数据敏感的环境用 Ollama 本地模型，对话不出内网，API Key 也不用交给第三方。
• 工具返回截断：read_remote_file 最多读 8000 字节，工具结果超过 6000 字符会被截断，看大文件时让 AI 分段读，不要一次读整个日志。

十一、测试与故障排查

问题	解决
python 不识别	安装 Python 时勾选 Add Python to PATH
打包失败 ModuleNotFoundError	用 pip install <module> 后重新打包
exe 启动黑窗闪过	已用 console=False，如还出现请检查杀毒软件
SSH 连接超时	检查防火墙、22 端口、目标主机 sshd 是否运行
AI 设置测试连接失败	检查 API Key 是否正确、Base URL 是否可访问、代理设置

十二、运维建议

• 配置备份：主机配置存在 ~/.sshclient/，定期备份这个目录，换电脑直接恢复。
• 私钥管理：私钥文件不要放在共享目录，设好文件权限，生产主机优先用私钥认证、禁密码登录。
• AI 模型选择：日常排障用便宜的模型（如 deepseek-chat、qwen-turbo）就够了，复杂任务再切强模型；本地 Ollama 适合内网与隐私场景。
• 监控不是替代品：内置监控适合临时看一眼，长期监控还是用 Prometheus + Grafana，告警用专门的告警系统。
• 升级：拉新代码后重新打包 exe 覆盖旧文件即可，配置在 ~/.sshclient/ 里不受影响。

SSHClient 把终端、SFTP、监控、进程管理这四件运维每天都要用的事收进一个窗口，再叠加一个能真正动手干活的 AI Agent：查指标、找大文件、重启服务，一句话就能让 AI 去执行。它的定位不是替代 Xshell，而是给想要“免费 + AI 辅助”的运维一个开箱即用的选择。先在 Windows 上打个 exe 跑一周，AI 排障顺手了，再把它变成主力客户端。

注意：还有一个名字很像的项目叫 ssh-client（带连字符），那是 Electron + TypeScript 写的另一个桌面 SSH 客户端，也有 AI 功能，但和这个 PyQt5 的 SSHClient 是两个不同的项目，不要混淆。关于 ssh-client 的详细介绍，见本站另一篇教程《智能SSH终端教程：Electron + AI 助手的远程运维桌面客户端》。