SSH Remote - Cursor Agent Skill

通过 SSH/SCP 连接远程 Linux 服务器执行命令或传输文件的Agent Skill，可用于Cursor/OpenClaw/Claude Code。

基于 Python + paramiko 实现，跨平台支持 Windows 10+ 和 Linux。

项目背景

这个项目的诞生源于一个朴素的愿望：
春节期间不想背着电脑，却又不敢真正离开服务器。

毕竟我们都知道：

• 服务器： 不会过年，但会挑过年宕机 😐
• Bug： 不会拜年，但会在你吃饺子时发来问候 🥟
• 亲戚： 问“什么时候结婚”，你却在想“什么时候重启服务” 🤦‍♂️
• 现实： 你放假，线上不放；你想躺，服务器想你 🫠

于是，这个 SSH Remote Skill 就出现了——
让你在聊天软件里远程运维（接上OpenClaw），假装自己真的在休息。

一句话总结：

“既然逃不掉，那就优雅地被迫在线。”

功能特性

• 远程命令执行 - 通过 SSH 在远程服务器上执行任意命令
• 文件上传 - 通过 SFTP 上传本地文件到远程服务器
• 文件下载 - 通过 SFTP 从远程服务器下载文件到本地
• 目录浏览 - 列出远程服务器目录内容
• JSON 输出 - 支持结构化 JSON 输出，便于 AI Agent 解析
• 自动密码拼接 - 通过密码前缀 + 服务器代码自动生成密码

项目结构

ssh-remote/
├── SKILL.md                 # Cursor Agent Skill 定义文件
├── servers.example.env      # 环境变量配置模板
├── .gitignore
├── README.md
└── scripts/
    ├── requirements.txt     # Python 依赖
    ├── ssh_exec.py          # SSH 远程命令执行脚本
    └── scp_transfer.py      # SCP/SFTP 文件传输脚本

安装

1. 克隆仓库

# 克隆到 Cursor Skills 目录
git clone https://github.com/YOUR_USERNAME/cursor-skill-ssh-remote.git ~/.cursor/skills/ssh-remote

2. 安装 Python 依赖

pip install -r ~/.cursor/skills/ssh-remote/scripts/requirements.txt

或手动安装：

pip install paramiko python-dotenv

3. 配置环境变量

# 复制模板文件
cp ~/.cursor/skills/ssh-remote/servers.example.env ~/.cursor/skills/ssh-remote/.env

# 编辑 .env 填入实际值

.env 配置项说明：

变量	说明	示例
SSH_PASSWORD_PREFIX	密码前缀（密码 = 前缀 + 服务器代码大写）	mypass
SSH_PORT	SSH 端口	22
SSH_USER	SSH 用户名	root
SSH_DOMAIN_SUFFIX	服务器域名后缀	example.com

密码生成规则：SSH_PASSWORD_PREFIX + 服务器代码大写

例如：前缀为 mypass，服务器代码为 us1，则密码为 mypassUS1

自定义密码拼接规则

默认的密码拼接逻辑为：密码 = 前缀 + 服务器代码大写

该逻辑定义在两个文件中：

• scripts/ssh_exec.py 第 54 行
• scripts/scp_transfer.py 第 54 行

password = f"{password_prefix}{server_code.upper()}"

如果你的密码规则不同，修改这一行即可。例如：

# 密码 = 前缀 + 服务器代码小写
password = f"{password_prefix}{server_code.lower()}"

# 密码 = 前缀 + 固定后缀
password = f"{password_prefix}@2024"

# 密码 = 服务器代码 + 前缀
password = f"{server_code.upper()}{password_prefix}"

同时需要更新 SKILL.md 中"服务器连接规则"部分的密码说明，保持 Agent 理解与实际逻辑一致。

使用方法

在 Cursor 中使用（推荐）

将本项目放置到 ~/.cursor/skills/ssh-remote 后，Cursor Agent 会自动识别 SKILL.md 并启用该 Skill。

在 Cursor 中直接用自然语言操作：

• "重启 us1 的 nginx 服务"
• "查看 hk2 的磁盘空间"
• "上传 config.json 到 us1 的 /etc/app/ 目录"
• "下载 us1 的 /var/log/app.log"

命令行独立使用

执行远程命令

python scripts/ssh_exec.py <server_code> "<command>" [--json] [--timeout 30]

示例：

# 重启 nginx
python scripts/ssh_exec.py us1 "systemctl restart nginx" --json

# 查看磁盘空间
python scripts/ssh_exec.py hk2 "df -h" --json

# 带超时参数
python scripts/ssh_exec.py us1 "journalctl -u nginx --no-pager -n 50" --json --timeout 60

上传文件

python scripts/scp_transfer.py upload <server_code> <local_path> <remote_path> [--json]

下载文件

python scripts/scp_transfer.py download <server_code> <remote_path> <local_path> [--json]

列出远程目录

python scripts/scp_transfer.py list <server_code> <remote_path> [--json]

JSON 输出示例

命令执行输出：

{
  "server": "us1",
  "hostname": "us1.example.com",
  "command": "systemctl status nginx",
  "stdout": "● nginx.service - A high performance web server...",
  "stderr": "",
  "exit_code": 0,
  "success": true
}

文件传输输出：

{
  "server": "us1",
  "hostname": "us1.example.com",
  "action": "upload",
  "local_path": "./config.json",
  "remote_path": "/etc/app/config.json",
  "success": true,
  "message": "上传成功: ./config.json -> us1.example.com:/etc/app/config.json (1024 字节)",
  "bytes_transferred": 1024
}

安全机制

敏感信息保护

.env 文件包含密码前缀等敏感信息，已通过 .gitignore 排除，不会被提交到仓库。

命令安全分级

SKILL.md 中定义了三级命令安全分级机制，Cursor Agent 会自动评估命令风险：

级别	行为	示例命令
🔴 禁止级	直接拒绝执行	rm -rf /、mkfs、fork 炸弹等
🟡 危险级	必须向用户确认后执行	rm -rf、reboot、systemctl stop、kill -9 等
🟢 安全级	直接执行	ls、df -h、systemctl status、systemctl restart 等

如需自定义安全规则，编辑 SKILL.md 中的"命令安全分级"部分。

错误排查

错误	可能原因	解决方案
认证失败	密码配置错误	检查 .env 中 SSH_PASSWORD_PREFIX
连接超时	网络不通或端口错误	检查 SSH_PORT 和网络连通性
模块未安装	缺少依赖	执行 pip install paramiko python-dotenv
.env 未找到	配置文件缺失	复制 servers.example.env 为 .env 并填写

License

MIT