Hermes Agent 中文安装教程：macOS、Linux 与 WSL2

安装前准备

先确认本机具备 Git、Node.js、Python 和一个稳定的终端环境。macOS 用户建议使用 Homebrew 管理依赖；Linux 或 WSL2 用户建议先更新系统包，并确认默认 shell、Python 版本和权限设置没有冲突。

最小检查清单

• 能从命令行访问 Git。
• 能读取环境变量。
• 有可用模型 API Key。
• 项目目录不要放在权限受限路径。
• 第一次运行时保留完整日志。

node -v
python3 --version
git --version

macOS 路线

macOS 用户通常用 zsh。安装后如果 `hermes` 找不到，先新开终端，再执行 `source ~/.zshrc`。不要在多个终端配置文件里重复写路径，否则后面升级或卸载会更难排查。

Linux / WSL2 路线

Linux 和 WSL2 用户优先确认当前目录、用户权限和包管理器。Windows 新手建议固定在 WSL2 里完成安装、配置和运行，不要一会儿 PowerShell、一会儿 Ubuntu 终端混用同一套配置。

pwd
whoami
printf '%s\n' "$SHELL"

安装后的第一轮验收

安装完成不等于可用。先跑版本、doctor、setup，再做一次短问答。短问答能返回后，再去配置 Starter 模板、Memory、Skills 和 Gateway。

hermes --version
hermes doctor
hermes setup

常见坑

安装失败通常不是 Agent 本身的问题，而是运行环境没有统一：Python 版本太旧、虚拟环境路径混乱、API Key 没有写入当前 shell、WSL2 无法访问宿主机网络，都会导致启动失败。建议先跑最小示例，再接消息平台和定时任务。

安全提醒

不要把生产系统的高权限 Token 直接交给 Agent。先用只读权限、测试仓库或样例数据跑通。安装阶段只证明环境可用，不代表已经可以接入生产工作流。

还没有真实场景？可以先领取 [Free Starter 模板包](/free-template-pack)，从低风险只读任务开始试跑。