HermesPilot

简体中文

English

简体中文

English

Appearance

Hermes Link 快速连接 ​

Hermes Link 是运行在你电脑上的本地连接服务。它负责让 HermesPilot App 安全连接到同一台电脑上的 Hermes Agent，并提供聊天、文件发送、语音输入、Profile 管理、设备管理、日志、用量统计和版本更新状态等能力。

先确认安装位置

Hermes Link 必须和 Hermes Agent 安装、运行在同一个系统环境里。

不要把 Link 装在宿主机，却把 Hermes Agent 跑在 Docker、WSL 或另一个虚拟环境里；也不要把 Link 装在 WSL 里，却让 Hermes Agent 跑在 Windows 宿主机。否则 Link 通常读不到同一份 Hermes 配置、.env、Profile 和本地 127.0.0.1 API，App 会无法连接或无法发送消息。

想先看公网直连？

如果你准备让手机从外网直接连回自己的 Hermes Link，可以先跳到 公网直连。

连接前准备 ​

  • Hermes Agent 已经安装并能在当前系统环境中正常运行。
  • 这台电脑可以访问 HermesPilot Server 和 Relay，用于生成配对二维码与兜底连接路线。
  • HermesPilot App 已登录账号。
  • Node.js 版本为 20.0.0 或更新版本。

在运行 Hermes 的电脑上，按你的系统执行其中一条安装命令。

推荐安装命令：

macOS / Linux / WSL ​

bash
curl -fsSL https://hs.clawpilot.me/install/install.sh | bash

如果这台机器没有 curl，但有 wget，可以改用：

bash
wget -qO- https://hs.clawpilot.me/install/install.sh | bash

Windows PowerShell ​

powershell
irm https://hs.clawpilot.me/install/install.ps1 | iex

安装脚本会读取 HermesPilot Server 当前对外发布的 Link 版本，并安装对应版本；如果暂时无法访问 Server，会回退到 npm 上的最新版本。脚本安装完成后会运行诊断，并尝试重启 Hermes Link，让正在运行的后台服务切到新版本。

如果你更习惯手动安装，可以展开查看 npm 命令
bash
npm install -g @hermespilot/link

安装完成后，会多出一个 hermeslink 命令。

如果安装成功后执行 hermeslink doctor 却提示 command not found，通常不是 Link 没装上，而是 npm 全局 bin 目录没有进入当前 shell 的 PATH。安装脚本会尽量提示具体原因；你也可以先运行这个不依赖 PATH 的诊断命令：

bash
npx --yes @hermespilot/link doctor --install

在 macOS、Linux、WSL 这类 Unix-like 环境里，常见的临时修复是：

bash
export PATH="$(npm prefix -g)/bin:$PATH"

确认可用后，再把同一行加入 ~/.zshrc、~/.bashrc 或你正在使用的 shell 配置文件。Windows 用户需要把 npm prefix -g 输出的目录加入当前用户的 Path，然后重新打开终端。

WSL 里不要混用 Windows npm

如果你在 WSL 里执行 npm prefix -g，结果指向 /mnt/c/...，说明当前很可能是在 WSL 里调用 Windows 版 Node/npm。这种安装会把 hermeslink shim 放到 Windows 环境，WSL shell 不一定能直接找到，也会让 Link 和 Hermes Agent 处在不同系统环境里。建议在 WSL 内安装 Linux 版 Node.js，或把 Hermes Agent 和 Hermes Link 都放在 Windows 宿主机运行。

第二步：生成配对二维码 ​

继续执行：

bash
hermeslink pair

pair 会先做配对前检查：确认 Link 能访问当前 Hermes home、config.yaml、.env，并确认 Hermes API Server 可用。检查通过后，终端会出现二维码和手动配对码。

配对二维码默认 10 分钟有效，成功扫码后会立即失效。首次配对成功后，Link 会在后台启动，并开启开机自启。

第三步：在 App 里扫码 ​

打开 HermesPilot App，进入「连接 Hermes Link」页面，扫描终端里的二维码。

连接成功后，App 会保存这台 Link。后续 App 会优先尝试局域网连接；如果局域网不可用，会继续尝试公网直连或 Relay 兜底路线。

公网直连 ​

如果你的手机经常不在同一局域网里，而你又希望尽量少绕一跳，可以给 Hermes Link 准备一个可从公网访问的入口。

Hermes Link 默认监听 52379 端口。无论你使用家庭宽带还是云服务器，外部访问最终都需要落到运行 Link 的这台机器上的 52379。

  • 家庭宽带 / 家用路由器： 需要在路由器里把外网 52379 端口转发到运行 Hermes Link 的电脑内网 52379。建议同时给这台电脑固定内网 IP，避免 DHCP 变化后端口转发失效。
  • 云服务器 / 远程主机： 记得同时检查云厂商安全组、防火墙，以及系统自身防火墙，确认都已经放行 52379 的入站访问。很多“明明开了端口还是连不上”的问题，都是只放行了其中一层。

安全上，不建议长期把未加保护的 52379 裸露在公网。更稳妥的做法是先配置好 TLS、访问控制，或使用 VPN / Tailscale / WireGuard 这类额外保护层，再把公网域名、固定公网 IP 或 VPN 地址填到 HermesPilot App 的手动连接里。

如果你已经准备好了公网入口，App 里可以使用「手动连接」：填写 hermeslink pair 给出的配对码，并把你的公网地址保存为自定义地址。之后 App 会优先尝试这条自定义路线。

日常常用命令 ​

bash
hermeslink status
hermeslink start
hermeslink stop
hermeslink autostart on
hermeslink autostart off
hermeslink doctor
hermeslink logs
hermeslink logs -n 100
hermeslink logs -f
hermeslink logs --error -n 20
hermeslink logs --warn -n 50
hermeslink logs --all --level debug -f
hermeslink logs flush
hermeslink logs flush --all
hermeslink config set log-level <warn|error|info|debug>

常用场景：

  • 查看 Link 与 Hermes 状态：hermeslink status
  • 启动后台服务：hermeslink start
  • 停止后台服务：hermeslink stop
  • 开启或关闭开机自启：hermeslink autostart on/off
  • 查看日志路径：hermeslink logs
  • 查看最近日志：hermeslink logs -n 100
  • 持续跟踪日志：hermeslink logs -f
  • 按级别筛选：hermeslink logs --error -n 20、hermeslink logs --warn -n 50，也可以使用短参数 -e / -w
  • 排障时查看全部来源：hermeslink logs --all --level debug -f
  • 清空 Link 日志：hermeslink logs flush 会清空服务和 Daemon 日志；如果要连 Gateway 日志一起清空，使用 hermeslink logs flush --all
  • 调整日志等级：hermeslink config set log-level <warn|error|info|debug>；info 适合日常使用，warn 和 error 适合减少日志输出，debug 适合排查连接、配对或请求转发问题。修改后如果希望运行中的 daemon 立即按新等级写日志，请执行 hermeslink restart

App 连接后可以做什么 ​

  • 继续与本机 Hermes Agent 对话，并接收流式回复。
  • 从手机发送图片、PDF、音频等文件给 Hermes。
  • 使用语音输入，把任务直接交给 Hermes。
  • 查看 Link、Gateway、Server、设备、日志和用量统计状态。
  • 管理 Hermes Profile、默认模型、定时任务、技能、工具权限和记忆设置。
  • 检查 Hermes Agent 与 Hermes Link 的更新状态。

WSL、Docker 和虚拟机环境 ​

如果你使用 WSL、Docker 或虚拟机，最重要的原则仍然是：Link 和 Hermes Agent 必须在同一个系统环境里。

Docker ​

如果 Hermes Agent 放在 Docker 里，而 Link 跑在宿主机，容器内的 127.0.0.1、文件路径、Hermes home 和宿主机不是同一个环境，Link 很容易读不到正确配置。

如果你坚持使用 Docker，需要把 Link 也放进同一个容器环境，并确保 App 能访问到容器对外暴露的 Link 端口。这类配置差异较大，优先建议改用原生安装。

Windows WSL ​

WSL 默认使用 NAT 网络。根据 Microsoft 的 WSL 网络文档，从 Windows 访问 Linux 应用通常可以用 localhost；但从局域网其他设备访问 WSL 内部服务时，通常不会自动暴露，需要额外配置端口转发、防火墙，或使用较新的 mirrored networking 模式。

如果 Link 安装在 WSL 里，手机在同一 Wi-Fi 下仍然可能连不上 WSL 内的 52379。建议优先使用以下方案：

  1. 能原生安装 Hermes Agent 和 Link 时，优先都安装在 Windows 宿主机。
  2. 如果必须放在 WSL 内，优先使用 Relay 路线。
  3. 如果你明确要让手机直连 WSL 内的 Link，先升级到支持 mirrored networking 的 Windows/WSL 版本，然后在 Windows 用户目录创建或修改 %UserProfile%\.wslconfig：
ini
[wsl2]
networkingMode=mirrored

保存后在 PowerShell 执行：

powershell
wsl --shutdown

重新启动 WSL 后，再运行：

bash
hermeslink config set lan-host <Windows 局域网 IP>
hermeslink restart

如果你不能使用 mirrored networking，可以改用 Windows netsh interface portproxy 做端口转发，并在 Windows 防火墙允许对应端口。但这需要你维护 WSL 的动态 IP，WSL 重启后可能变化，长期稳定性不如 Relay。

参考资料：

如果第一次连不上 ​

  • 先执行 hermeslink status，确认 Link 仍在运行。
  • 执行 hermeslink doctor，确认 Hermes Gateway/API Server 可用。
  • 确认 App 和 Link 使用的是同一套 HermesPilot Server。
  • 确认 Link 与 Hermes Agent 在同一个系统环境，不要跨宿主机、Docker、WSL 混装。
  • 如果你刚改过网络地址，执行 hermeslink config set lan-host <手机可访问的电脑 IP>，然后重新运行 hermeslink pair 或重启 Link。
  • 如果局域网一直不可达，优先使用 Relay 路线完成连接。

HermesPilot

Copyright © 2026 HermesPilot