Hermes本地部署全指南(Mac/Linux/WSL2)

周一聊完选哪个，今天开始动手。

Hermes Agent支持三种主流安装方式。Windows用户需要先装WSL2，然后在WSL2里执行安装命令；Mac和Linux用户直接一条命令搞定。

一、安装前准备

系统要求

必备：大模型API Key

Hermes安装后必须配置LLM密钥才能使用。

国内用户首选（无需特殊网络）：

• Kimi：200万字超长上下文，免费额度充足，中文理解和智能体任务表现出色，国内网络稳定
• DeepSeek：国内网络稳定，性价比高

海外/备选：

• OpenRouter：一键切换上百种模型
• Nous Portal：官方原生支持
• Ollama：完全本地离线，隐私优先

二、安装步骤

macOS / Linux 安装（一条命令）

打开终端，执行：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

国内用户建议使用镜像源，速度更快：

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

脚本会自动完成：

• 克隆Hermes Agent仓库
• 安装uv（Python包管理器）
• 创建Python虚拟环境
• 安装所有依赖包（Python 3.11、Node.js等）
• 将hermes命令添加到PATH

安装完成后，刷新环境变量：

source ~/.bashrc   # Bash用户
source ~/.zshrc    # Zsh用户（macOS默认）

验证安装：

hermes --version

如果能正常显示版本号（如v0.8.0+），说明安装成功。

Windows（WSL2）安装（分步详解）

Windows用户需要在WSL2的Linux环境中安装。以下是完整步骤：

第一步：安装WSL2

用管理员身份打开PowerShell，执行：

wsl --install -d Ubuntu-22.04

这条命令会自动完成：

• 启用WSL2功能
• 启用虚拟机平台
• 下载并安装Ubuntu 22.04 LTS

重启电脑。重启后Ubuntu会自动打开，要求设置Linux用户名和密码。

验证WSL2版本：

wsl --list --verbose

应显示VERSION 2。如果显示VERSION 1，执行：

wsl --set-version Ubuntu 2
wsl --set-default-version 2

Hermes在WSL1上无法可靠运行。

第二步：安装Hermes Agent

打开Ubuntu终端，执行：

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

刷新环境变量：

source ~/.bashrc

验证安装：

hermes --version

三、配置与启动

1. 交互式配置向导（推荐新手）

hermes setup

按提示完成配置：

① 选择模型提供商

② 输入API Key

• Kimi：访问 https://platform.moonshot.cn/console 创建API Key
• DeepSeek：访问平台官网获取

③ 消息平台（可跳过）

本地测试选择Skip — set up later，后续可再配置。

看到✓ Setup Complete!即配置完成。

2. 启动Hermes Agent

hermes

看到类似以下的欢迎界面即成功：

Welcome to Hermes Agent!
Type your message or /help for commands

四、常用命令速查

五、新手最常遇到的3个坑

坑1：终端提示找不到hermes命令

原因：安装后shell配置未刷新

解决：

source ~/.bashrc   # 或 source ~/.zshrc

如果还不行，用完整路径：~/.local/bin/hermes

坑2：Windows用户直接在原生环境安装

原因：Hermes对Windows原生支持仍为Early Beta

解决：先装WSL2，在WSL2的Ubuntu终端里执行安装命令。这是官方推荐的唯一可靠方式。

坑3：模型API调用失败

原因：API Key错误、余额不足或配置问题

解决：

1. 检查API Key是否正确，注意不要多复制空格
2. 确认账户有余额
3. 运行诊断命令：hermes doctor

明天预告

部署只是第一步——配置过程中有5个最常见的坑，明天详细拆解，提前帮你避开。

下一篇：Hermes部署中5个最常见坑及解决方案，明天见。