Hermes Agent SSH远程连接失败需依次检查：一、启用并验证本地SSH服务；二、配置gateway参数（host/port/user/identity_file）；三、修复密钥认证（生成专用密钥、部署公钥、验证免密登录）；四、排查防火墙与SELinux拦截；五、调试启动并查看日志。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试通过 SSH 远程连接 Hermes Agent 所在节点以启用 gateway 模式或执行远程任务，但连接失败或超时，则可能是由于 SSH 服务配置、网络策略或 Agent 网关参数不匹配所致。以下是针对 Hermes Agent SSH 远程连接的配置步骤与常见故障修复方法：
一、启用并验证本地 SSH 服务
SSH gateway 功能依赖于目标节点运行 OpenSSH 服务且监听有效端口。若服务未启动或版本过旧，Hermes Agent 将无法建立安全隧道。
1、检查 SSH 服务状态：执行 sudo systemctl status ssh（Linux）或 Get-Service -Name sshd | Select-Object Status, Name（PowerShell 中 WSL2）。
2、若服务未运行，启动它：执行 sudo systemctl start ssh 或 Start-Service sshd。
3、确认 SSH 版本不低于 OpenSSH 8.9：执行 ssh -V，输出应类似 OpenSSH_9.6p1, LibreSSL 3.3.6。
4、若版本过低，升级系统包管理器并更新：Ubuntu 执行 sudo apt update && sudo apt install --only-upgrade openssh-server。
二、配置 Hermes Agent 的 SSH gateway 参数
Hermes Agent 使用 hermes gateway 命令启动 SSH 网关时，需显式指定主机地址、端口、用户及密钥路径，否则默认参数将导致认证失败或连接拒绝。
1、编辑 Agent 配置文件：~/.hermes/config.yaml，在 gateway 区块下添加如下字段：
2、设置 host: "192.168.1.100"（替换为实际目标 IP）。
3、设置 port: 22（若非标准端口，如 2222，需同步修改 SSH 服务监听端口）。
4、设置 user: "hermes"（该用户必须已在目标节点创建并具备 shell 登录权限）。
5、设置 identity_file: "~/.ssh/id_rsa_hermes"（确保私钥存在且权限为 600）。
三、修复 SSH 密钥认证失败
Agent 启动 gateway 时若提示 Permission denied (publickey)，说明公钥未正确部署至目标节点的 ~/.ssh/authorized_keys 文件中，或私钥格式不兼容。
1、生成专用密钥对（避免复用主密钥）：执行 ssh-keygen -t ed25519 -C "hermes-gateway@local" -f ~/.ssh/id_rsa_hermes。
2、将公钥复制到目标节点：执行 ssh-copy-id -i ~/.ssh/id_rsa_hermes.pub hermes@192.168.1.100。
3、若 ssh-copy-id 不可用，手动追加公钥内容至目标节点的 ~hermes/.ssh/authorized_keys，并执行 chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys。
4、验证密钥可免密登录：执行 ssh -i ~/.ssh/id_rsa_hermes hermes@192.168.1.100 -o ConnectTimeout=5，成功则直接进入 shell。
四、排查防火墙与 SELinux 干预
即使 SSH 服务运行正常，系统级防火墙或强制访问控制策略可能拦截入站连接，导致 Hermes Agent gateway 日志中出现 Connection timed out 或 Connection refused。
1、检查 UFW（Ubuntu）是否启用：执行 sudo ufw status verbose，确认 22/tcp 端口状态为 ALLOW。
2、若被拒绝，添加规则：执行 sudo ufw allow 22/tcp。
3、检查 SELinux（CentOS/RHEL）：执行 getenforce，若返回 Enforcing，临时设为宽容模式：sudo setenforce 0。
4、永久允许 SSH 端口：执行 sudo semanage port -a -t ssh_port_t -p tcp 22（需先安装 policycoreutils-python-utils）。
五、验证 Hermes Agent gateway 启动与日志输出
启动 gateway 后若无响应或立即退出，需检查其运行上下文与实时日志，确认是否加载了正确的 SSH 配置及是否捕获到连接请求。
1、以调试模式启动：执行 hermes gateway --debug。
2、观察终端输出中是否包含 SSH gateway listening on :8080（HTTP 接口）与 SSH server started on 0.0.0.0:2222（SSH 监听端口）。
3、若提示 failed to load config: config.yaml not found，确认配置文件路径为 ~/.hermes/config.yaml 且语法合法（YAML 缩进必须为空格，不可用 Tab）。
4、查看完整日志流：执行 journalctl -u hermes-gateway -f（systemd 管理）或检查 ~/.hermes/logs/gateway.log。
