基于 CLI 的 SSH 代理工具，按 ssh-mcp-server 的能力映射为 Agent 可调用的远端操作能力。
远程执行 · 文件上传 · 文件下载 · 连接配置 · 命令白名单 · 命令黑名单 · Agent Skill 集成
AI 一键安装 · 手动安装 · 配置 · 卸载和清理 · 许可证 · 友情链接
中文 | English
本项目参考 classfang/ssh-mcp-server 的 SSH 操作能力设计，改写为独立 CLI 形式。感谢原项目提供的思路和能力基础。
- 解放双手，自动运维服务器
- 部署代码，更新部署docker
- 配置nginx,配置证书
- 所有ssh能做到的事情
- 列出本地配置中的 SSH 服务器连接
- 在指定远端服务器上执行命令
- 上传本地文件到远端服务器，支持临时文件、断点续传和失败重试
- 从远端服务器下载文件到本地
- 通过命令黑白名单限制可执行命令
上传会先写入远端 <remotePath>.part 临时文件，并写入 <remotePath>.part.meta 续传元数据；完成后校验大小，再 rename 为正式目标文件。上传中断后，下次上传同一个本地文件到同一个远端路径会从已有 .part 大小继续。
--no-cache 上传可用 Ctrl+C 停止当前进程；daemon 模式可用 agentsshcli stop-daemon 停止连接池进程，但它会影响同一 daemon 内其它任务，不是精确取消单个上传。
安装请阅读 https://github.com/sleepinginsummer/agent-ssh-cli/blob/main/AI_INSTALL.md，按说明安装 CLI 并添加 `SKILL.md`。
- Node.js
>= 18 - npm
>= 8 - 系统支持 Windows / macOS / Linux
- 本机网络可访问目标 SSH 服务器
- 如使用私钥认证，私钥文件需对当前用户可读
- 预编译平台包支持 macOS arm64/x64、Linux x64/arm64、Windows x64
exec --timeout <ms>: 单次命令超时，默认30000upload/download --timeout <ms>: 传输总超时，默认不限制（大文件允许长时间运行）upload/download --recursive: 递归传输目录，保持相对路径；符号链接不跟随，指向目录的链接跳过、指向文件的链接上传其内容- 下载支持断点续传：中断后本地保留
.part文件，下次自动从断点继续 exec/upload/download --json: 输出结构化 JSON（exitCode/stdout/stderr），exitCode为远端命令真实退出码，便于脚本和 AI 解析agentsshcli init-config: 生成默认配置文件到~/.agent-ssh-cli/config.jsonagentsshcli stop-daemon: 停止当前配置对应的 SSH 缓存进程- 远端会话异常终止时提示
[remote] 会话异常终止（无退出状态），不会静默返回成功
- 全局安装：
npm install -g agent-ssh-cli
agentsshcli --help- 导入 SKILL.md:
打开 SKILL.md，将其添加到 agent 中。
初始化配置（格式参数和ssh-mcp-server一致）：
mkdir -p ~/.agent-ssh-cli编辑 ~/.agent-ssh-cli/config.json，填写真实连接信息。默认配置文件也可以通过环境变量覆盖：
可以通过以下环境变量修改配置地点
AGENT_SSH_CONFIG=/path/to/config.json配置文件是数组，每一项是一台服务器：
name: 连接名，必须唯一host: SSH 主机地址username: SSH 用户名password/passwordRef/privateKey: 认证方式，密码、密码引用、私钥三类认证只能保留一种port: SSH 端口，默认22passphrase: 私钥口令，仅配合privateKey使用socksProxy: SOCKS5 代理地址，例如socks5://127.0.0.1:1080；也可省略协议写成127.0.0.1:1080jumpHost: 跳板机连接名，填写配置文件中另一台机器的namepty: 是否分配伪终端，默认false，也可通过exec --pty临时开启allowedLocalPaths: 兼容旧配置字段，当前不限制本地路径commandWhitelist: 命令白名单正则数组commandBlacklist: 命令黑名单正则数组
commandWhitelist 和 commandBlacklist 使用 JavaScript RegExp 语法，不是 POSIX 正则；空白字符请写成 \\s，不要写 [:space:]。
完整示例见 example.config.json。~/.agent-ssh-cli/config.json 保存真实连接信息。
为防止配置文件中的密码泄露，密码认证会在第一次使用该服务器时被动加密保存：首次写入明文 password 后，执行 exec、upload 或 download 连接该服务器时，CLI 会把密码加密保存到配置目录下的 secrets.json，生成本地 secret.key，并把配置中的 password 置空、写入 passwordRef。后续运行通过 passwordRef 解密认证；如需修改密码，把空的 password 重新填成新密码，下次连接会自动覆盖旧密文。
参考配置
[
{
"name": "密码服务器",
"host": "192.0.2.10",
"port": 22,
"username": "root",
"password": "",
"passwordRef": "agentsshcli:密码服务器",
"jumpHost": "jump-server",
"commandBlacklist": [
"(^|[;&|()\\s])rm(\\s|$)",
"(^|[;&|()\\s])shutdown(\\s|$)",
"(^|[;&|()\\s])reboot(\\s|$)"
]
},
{
"name": "jump-server",
"host": "198.51.100.20",
"port": 22,
"username": "ubuntu",
"privateKey": "/path/to/jump_key",
"passphrase": "******",
"socksProxy": "socks5://127.0.0.1:1080"
},
{
"name": "密钥服务器",
"host": "198.51.100.10",
"port": 22,
"username": "deploy",
"privateKey": "/path/to/id_rsa",
"passphrase": "******",
"pty": false,
"allowedLocalPaths": [
"./tmp",
"./dist"
],
"commandWhitelist": [
"^pwd$",
"^ls(\\s|$)",
"^cat\\s+/var/log/app\\.log$"
],
"commandBlacklist": [
"(^|[;&|()\\s])rm(\\s|$)",
"(^|[;&|()\\s])shutdown(\\s|$)",
"(^|[;&|()\\s])reboot(\\s|$)"
]
}
]测试命令
agentsshcli list
agentsshcli exec --no-cache 密码服务器 "pwd"
agentsshcli exec --pty 密码服务器 "tty"
agentsshcli exec 密码服务器 --command-file ./script.sh --timeout 60000完成安装!
更新到最新版：
npm install -g agent-ssh-cli@latest卸载:
npm uninstall -g agent-ssh-cli
npm cache clean --force
#删除配置文件
rm -rf ~/.agent-ssh-cli