国内可用 Hermes Agent 一键部署与 Kimi 完整配置教程

速览：全平台支持一键部署，Linux / macOS / WSL2 使用 curl 脚本，Windows 适配 PowerShell 脚本；国内用户优先选国内镜像源，安装更快更稳。部署完成后通过 hermes setup 配置模型与 API 密钥，国内环境推荐 Kimi 大模型，无需特殊网络，中文理解、长文本处理、智能体任务表现都很出色。配置完直接 hermes 就能启动。

关键前提：Hermes Agent v0.8.0 及以上版本原生支持 Kimi（Moonshot）大模型，旧版本没有这个选项。本教程全程安装最新版，国内不用折腾网络，完美适配 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 执行安装脚本，它会自动装到用户目录，加 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 模型配置（离线使用）

先安装 Ollama 客户端，启动后台服务：

ollama serve

拉取 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 '.[all]'

所有配置文件统一存放在 ~/.hermes/ 目录，重装不会丢失自定义配置。