速览：全平台支持一键部署，Linux/macOS/WSL2 可使用 curl 脚本、Windows 适配 PowerShell 脚本；中国大陆用户优先选用国内镜像源，安装速度更快、运行更稳定。部署完成后通过 hermes setup 配置模型与 API 密钥，国内环境优选** **Kimi 大模型，无需特殊网络，中文理解能力、长文本处理及智能体任务表现优异，配置完成后执行 hermes 即可启动使用。

重点核心：Hermes Agent v0.8.0及以上版本原生支持Kimi（Moonshot）大模型，旧版本无Kimi选项，本教程全程安装最新版，国内无需特殊网络，完美适配Kimi长文本、文档解析、中文智能体任务。

本教程适配：Windows、macOS、Linux、WSL2、Android Termux 全平台

安全声明：本文所有安装脚本为官方镜像正规文件，可放心使用；介意远程脚本执行的用户可选择文末手动安装方式。

一、系统与环境前置准备（必看）

1.1 系统支持要求

• Windows：Win10（2004+）、Win11；推荐WSL2部署（最稳定，无报错）
• macOS：Big Sur 11.0+，适配Intel/Apple Silicon芯片
• Linux：Ubuntu20.04+、Debian11+、Fedora36+、Arch 主流发行版
• Android：Termux 最新版本（需开启存储权限）

1.2 网络与权限规范（避坑核心）

• 国内用户：优先使用国内镜像源，无需国际网络，可直接使用Kimi、智谱、通义千问
• 海外模型（OpenAI、Gemini、Anthropic）：需要具备国际网络访问能力
• Linux/macOS：禁止使用sudo执行安装脚本，自动安装至用户目录，加权限会导致环境错乱
• Windows：PowerShell需管理员身份运行，规避路径权限限制

1.3 平台前置配置（新手必做）

Windows 用户专属前置（解决脚本运行报错）

Windows默认拦截远程脚本，需提前放行，管理员PowerShell执行：

Set-ExecutionPolicy RemoteSigned -Scope Process

输入 Y 确认，仅当前会话生效，安全无风险。

WSL2 一键安装（推荐）：管理员PowerShell执行，重启电脑自动部署Ubuntu子系统

wsl --install

1.4 大模型选择与API密钥获取（国内优选）

安全提醒：API密钥为私密凭证，禁止截图、分享、公开传播，避免额度被盗刷。

国内在线模型（无特殊网络要求，新手优选）

• Kimi（月之暗面/Moonshot）【推荐】：200万字超长上下文、中文最优、智能体任务适配完美，免费额度充足，使用成本低。
• 登录Kimi网站获取API Key，访问 https://platform.moonshot.cn/console 点击登录
• 点击左侧的API Key管理，创建API Key，复制弹出的密钥字符，密钥格式：sk\-kimi\-xxxx

海外在线模型（需国际网络）

• OpenAI、Anthropic、Google Gemini、OpenRouter、Nous Portal

本地离线模型（无网络、纯隐私）

基于Ollama部署，完全离线运行，推荐 nous-hermes2 专属模型，内存≥8G可流畅运行

二、全平台一键安装（推荐新手）

所有脚本自动安装Python3.11、uv包管理器、源码、环境变量，无需手动配置依赖

2.1 Linux / macOS / WSL2（最稳定）

国内镜像源（优先使用，速度最快）

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

国际官方源（海外用户使用）

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

安装后必执行（刷新环境变量）

# bash 用户
source ~/.bashrc
# zsh 用户
source ~/.zshrc

永久生效：直接关闭当前终端，重新打开新终端即可

2.2 Windows 原生 PowerShell

管理员身份运行，统一管道格式，无报错

国内镜像源（推荐）

irm https://res1.hermesagent.org.cn/install.ps1 | iex

国际官方源

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

安装路径：%LOCALAPPDATA%\\hermes，安装完成重启PowerShell

2.3 Android Termux

先切换清华镜像源提升速度，开启存储权限，执行Linux同款命令

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

三、手动安装（开发者/安装失败备用）

# 1. 克隆完整源码（含子模块）
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 2. 安装uv包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. 创建虚拟环境
uv venv

# 4. 激活虚拟环境
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# 5. 安装核心依赖
uv pip install -e .

# 6. 启动配置向导
hermes setup

四、核心配置（重点：Kimi模型配置）

关键前置校验：确保版本≥v0.8.0，否则无Kimi选项

hermes version  # 查看版本
hermes update   # 一键升级到最新版

4.1 新手推荐：交互式配置向导

hermes setup

按提示选择模型：Moonshot/Kimi（列表中Moonshot=Kimi，为官方统一命名），输入Kimi API密钥，国内节点默认稳定直连。

4.2 快速切换Kimi模型（极简指令）

# 打开模型列表，直接选择Kimi/Moonshot
hermes model

4.3 本地Ollama模型配置（离线使用）

1. 先安装 Ollama客户端
2. 启动后台服务

ollama serve

1. 拉取Hermes专属模型并配置

ollama pull nous-hermes2
hermes model --local ollama:nous-hermes2

五、启动与常用指令

# 1. 前台交互式聊天（日常使用推荐）
hermes

# 2. 后台常驻服务（服务器挂机使用）
hermes start

# 3. 停止后台服务
hermes stop

# 4. 查看当前所有配置
hermes config show

# 5. 模型管理
hermes model

# 6. 一键更新版本
hermes update

# 7. 卸载Hermes
hermes uninstall

六、高频踩坑问题汇总

6.1 安装提示依赖缺失

Linux/debian/ubuntu 执行：

sudo apt install git curl build-essential python3-venv

6.2 终端提示 hermes: 未找到命令

刷新环境变量或重启终端，Windows手动添加 %LOCALAPPDATA%\\hermes\\bin 到系统PATH

6.3 模型连接失败/401密钥错误

• 核对API密钥是否正确、是否过期
• 检查账号是否有可用额度
• 国内用户优先选择 kimi\-coding\-cn国内节点

6.4 报错排查

所有运行日志路径：Linux/macOS \~/\.hermes/logs、Windows %LOCALAPPDATA%\\hermes\\logs

七、补充说明

• 国内镜像版默认跳过浏览器、WhatsApp桥接等海外依赖，不影响核心AI对话、智能体任务使用
• 如需完整扩展功能，可进入源码目录执行：uv pip install \-e \&\#39;\.\[all\]\&\#39;
• 所有配置文件统一存放于 \~/\.hermes/ 目录，重装不会丢失自定义配置