Hermes Agent 教程最怕「看着很完整，做完没法验收」。本文融合全网4篇权威教程精华，采用六阶段清单式验收法，覆盖从环境准备、三种安装方式、核心配置到实战案例、进阶用法的全流程，同时针对国内用户做了Kimi大模型专属优化——无需翻墙、中文理解精准、200万超长上下文，彻底解决海外模型网络差、中文弱、成本高的痛点。

本文适配 v0.14.0 最新版本，支持 Linux（Ubuntu 22.04+）、macOS 12+、WSL2 系统，新手跟着清单一步步勾选即可100%跑通，进阶用户可直接查阅架构与功能模块。

先行结论：

  • 新手首选官方一键脚本安装，仅需预先安装 Git
  • 所有配置集中在 ~/.hermes/ 目录，API Key 单独存放在 .env 文件
  • 全程使用 hermes doctor 做健康检查，避免盲目重装
  • 国内用户优选 Kimi 大模型：国内直连无延迟，中文任务准确率比 GPT-4 高15%，价格仅为其1/3，新用户赠送免费额度

一、前置准备与环境要求

1.1 核心特性与版本说明

Hermes Agent 是 Nous Research 推出的开源自我改进型 AI 智能体，核心优势在于：

  • 自我成长：从复杂任务中自动生成可复用技能，越用越贴合你的习惯
  • 持久记忆：四层记忆体系，跨会话记住偏好、项目上下文和解决方案
  • 全平台覆盖：支持 CLI、微信、Telegram、飞书等15+消息平台
  • 灵活部署：最低1核1G VPS即可运行，支持 Docker、SSH 等多种隔离后端

本文基于 2026年5月发布的 v0.14.0 稳定版 编写，修复了旧版本的网络和配置兼容性问题。

1.2 硬件与系统要求

硬件/系统 最低配置 推荐配置 备注

CPU

2核

4核及以上

运行本地模型需8核及以上

内存

4GB

8GB及以上

本地模型运行需16GB+内存

磁盘

10GB可用空间

20GB+可用空间

存储依赖、日志、技能和会话数据

系统

Linux/macOS/WSL2

Ubuntu 22.04/WSL2/macOS 12+

不支持原生 Windows，必须使用 WSL2

网络

可访问 GitHub

稳定网络

搭配 Kimi 无需额外代理

1.3 前置依赖安装

官方安装脚本会自动处理 Python 3.11、Node.js v22、uv、ripgrep 等核心依赖，仅需提前安装 Git：

# Linux (Ubuntu/Debian)
sudo apt update && sudo apt upgrade -y
sudo apt install git -y

# macOS（未安装 Homebrew 先执行第一行）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install git

# 验证安装
git --version

1.4 国内网络加速（必做）

国内环境访问 GitHub、PyPI 速度慢，提前配置以下加速可避免安装失败：

# 1. Git 镜像加速
git config --global url."https://mirror.ghproxy.com/https://github.com".insteadOf "https://github.com"

# 2. pip 阿里云镜像
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set install.trusted-host mirrors.aliyun.com

# 3. npm 腾讯云镜像
npm config set registry https://mirrors.cloud.tencent.com/npm/ --global

1.5 安装前验收清单

复制任何安装命令前，先逐项打勾，确保环境就绪：

检查动作 通过标准 失败先查

系统版本验证

满足上述系统要求

系统升级或更换兼容系统

Git 安装

执行 git --version 输出版本号

Xcode CLT（macOS）或 apt 源（Linux）

网络连通性

curl -I https://raw.githubusercontent.com 和 curl -I https://api.moonshot.cn 均返回 200

代理、DNS、公司防火墙

磁盘空间

可用空间 ≥10GB

清理 ~/Library/Caches（macOS）或 /var/cache（Linux）

Kimi API Key 准备

访问 Kimi 开放平台 注册并生成 Key，保存到密码管理器

Kimi 控制台账单与余额

测试工作区创建

mkdir -p ~/hermes-workspace/{inbox,outbox,scratch,backups} 且 chmod 700 ~/hermes-workspace

路径拼写、磁盘权限

旧配置备份（重装时）

旧 ~/.hermes/ 目录已备份到 ~/hermes-workspace/backups/

勿直接 rm -rf ~/.hermes

二、三种安装方式（分场景推荐）

2.1 方式一：一键脚本安装（新手首选）

最简单、最不易出错的方式，脚本自动完成所有依赖安装和环境配置：

# 国内环境推荐（镜像加速，速度更快）
curl -fsSL https://hermes.xaapi.ai/install.sh | bash

# 官方原版（国外环境使用）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装过程说明：

脚本会自动完成：检测 Python 版本 → 创建虚拟环境 → 安装所有依赖 → 配置 PATH 环境变量 → 生成默认配置目录。全程约10-15分钟，无致命错误即可继续。

2.2 方式二：Docker 部署（生产环境首选）

实现环境隔离，避免与系统其他软件冲突，适合长期后台运行：

# 1. 安装 Docker（未安装时执行）
sudo apt install docker.io -y
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER  # 免 sudo 执行 Docker，需重新登录终端

# 2. 拉取官方最新镜像
docker pull nousresearch/hermes-agent:latest

# 3. 创建本地配置目录并启动容器
mkdir -p ~/.hermes/docker-config
docker run -d \
  --name hermes-agent \
  -v ~/.hermes/docker-config:/root/.hermes \
  -p 8080:8080 \
  nousresearch/hermes-agent:latest

# 4. 验证容器运行状态
docker ps | grep hermes-agent

2.3 方式三：源码部署（开发者首选）

适合需要修改源码、二次开发的用户：

# 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
source $HOME/.cargo/env

# 3. 创建虚拟环境并安装依赖
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all]"

# 4. 初始化配置目录
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env

# 5. 配置全局命令
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

2.4 安装验证

无论哪种安装方式，执行以下命令验证安装成功：

# 刷新环境变量
source ~/.bashrc  # bash 用户
source ~/.zshrc   # zsh 用户

# 验证版本
hermes --version
# 预期输出：hermes v0.14.0

# 初步诊断
hermes doctor
# 所有核心项显示 green 即为正常

三、核心配置（Kimi大模型专属优化）

3.1 初始化配置向导

执行全量配置向导，一步步完成基础设置：

hermes setup

向导会引导你选择模型提供商、配置 API Key、设置工作目录和权限，推荐在模型选择步骤直接选择「Moonshot（Kimi）」。

3.2 模型配置（关键步骤：Kimi 专属）

Kimi 是国内用户的最佳选择，核心优势：

  • 国内直连，API 响应速度比海外模型快3-5倍
  • 原生支持200万超长上下文，可一次性处理整本书或整个代码库
  • 中文语义理解准确率行业领先，特别适合会议纪要、文档分析等任务
  • 计费透明，新用户赠送15元免费额度，100万token仅需12元

手动配置 Kimi（推荐）：

  1. 编辑环境变量文件：vim ~/.hermes/.env
  2. 添加 Kimi API Key：

MOONSHOT_API_KEY=sk-your-kimi-api-key-here

  1. 编辑主配置文件：vim ~/.hermes/config.yaml
  2. 设置默认模型为 Kimi 最新版：

default_model: moonshot/kimi-latest model_providers: moonshot: api_key: "${MOONSHOT_API_KEY}" base_url: "https://api.moonshot.cn/v1" timeout: 60

  1. 验证模型配置：

hermes model list #能看到 moonshot/kimi-latest 即为成功

3.3 基础配置清单

检查动作 通过标准 失败先查

密钥文件权限

chmod 600 ~/.hermes/.env，config.yaml 中无明文 Key

是否误将 Key 写入配置文件或提交到 Git

工作目录配置

MESSAGING_CWD=~/hermes-workspace 已写入 .env

路径不存在、误用 iCloud/Dropbox 同步目录

权限模式

terminal.backend: local + approvals.mode: manual（试用阶段）

是否误开 YOLO 模式跳过所有审批

日志配置

~/.hermes/logs/ 目录存在且可写

磁盘满、目录权限不足

工具集配置

仅启用文件读写、终端工具，浏览器/网关后续按需开启

多余工具导致权限面过大

配置完整性检查

hermes config check 无报错

版本升级后未执行 hermes config migrate

四、首次运行与健康检查

4.1 进入交互模式

cd ~/hermes-workspace
hermes  # 进入终端交互界面

4.2 首次运行验收清单

检查动作 通过标准 失败先查

模型连通性测试

发送「你好，回复 OK」，3秒内收到回复，无 API Key 错误

.env 变量名、Kimi 账户余额、网络连接

文件读写测试

输入「在 scratch 目录创建 ping.txt，写入内容 test」，文件成功生成

工作目录权限、macOS 隐私弹窗、审批是否被误拒

日志写入测试

对话后 ls -l ~/.hermes/logs/ 有新文件生成

日志级别配置、目录权限

环境持久性测试

关闭终端重新打开，执行 hermes 仍可正常启动

PATH 未持久化、shell 配置文件未加载

终检

hermes doctor 无 blocking 项

按 doctor 提示逐条修复

五、实战案例：会议纪要摘要与待办提取（Kimi优化版）

在专用测试目录完成第一个可验收任务，Kimi 的长文本和中文优势会让输出质量远超其他模型。

5.1 准备测试数据

# 创建测试会议纪要
cat > ~/hermes-workspace/inbox/meeting.txt <<'EOF'
2026年5月20日 项目周会纪要
参会人：张三、李四、王五、赵六
会议主题：Q2 产品迭代进度同步

1. 后端模块（张三负责）
- 已完成用户中心 v2 接口开发，覆盖率95%
- 下周完成 API 文档编写和接口联调，截止5月27日
- 待解决：支付接口回调偶发超时问题，需与第三方对接

2. 前端模块（李四负责）
- 登录页重构已上线，修复了403权限错误
- 正在开发数据可视化大屏，预计5月25日完成初稿
- 待解决：图表渲染性能问题，大数据量下卡顿

3. AI 模块（王五负责）
- 完成 Hermes Agent 与 Kimi 大模型的集成测试
- 调研了本地模型部署方案，对比了 Llama 3 和 Qwen 2
- 周五（5月23日）提交完整的技术选型报告

4. 测试模块（赵六负责）
- 完成 v1.2 版本回归测试，发现3个高优先级bug
- 5月22日前完成bug修复验证
- 下周开始准备 v1.3 版本测试用例
EOF

# 备份原文件
cp ~/hermes-workspace/inbox/meeting.txt ~/hermes-workspace/backups/meeting.txt.bak

5.2 执行任务

在 Hermes 交互界面输入以下指令：

请读取 inbox/meeting.txt 文件，在 outbox/ 目录生成两份文件：
1. summary.md：200字以内的会议摘要，提炼核心进度和风险点
2. todos.md：Markdown 格式的待办清单，每项必须包含负责人、任务内容和截止日期
不要修改 inbox 原文件，不要访问工作区以外的任何路径。

5.3 任务验收清单

检查动作 通过标准 失败先查

输出文件存在

outbox/summary.md 和 outbox/todos.md 已生成

审批是否 pending、模型是否幻觉编造

内容准确性

摘要包含所有核心模块进度，待办清单的负责人和截止日期完全匹配原文

Kimi 模型参数、prompt 约束是否清晰

原文件完整性

diff inbox/meeting.txt backups/meeting.txt.bak 无差异

工具权限、prompt 约束是否生效

日志可追溯

~/.hermes/logs/agent.log 中有本次任务的工具调用记录

日志级别配置

成本控制

Kimi 控制台显示本次 token 用量约500-800，符合预期

是否陷入工具循环、是否使用了过大的模型

权限边界

Agent 未尝试访问 ~/.ssh、~/.hermes/.env 等敏感目录

工具配置、审批模式

六、核心功能与进阶用法

6.1 两种运行模式

  • 单次模式：适合简单一次性任务

hermes "帮我统计当前目录下的文件数量和总大小"

  • 交互模式：适合多轮复杂任务，保持上下文

hermes -i # 进入后可连续提问，输入 /exit 退出

6.2 四层记忆系统

Hermes Agent 的记忆体系让它越用越聪明：

  1. USER.md：存储你的偏好（如编程语言、部署方式、沟通风格）
  2. MEMORY.md：存储环境事实、项目约定、解决方案
  3. 会话搜索：基于 SQLite FTS5 全文搜索历史对话
  4. 外部记忆：支持接入 Honcho、Mem0 等第三方记忆服务 设置持久记忆： hermes "请记住：我常用 Python 开发，偏好 Docker 部署，回复请用中文，不要使用英文缩写"

6.3 技能系统

当 Agent 完成5次以上工具调用的复杂任务后，会自动生成可复用的技能文档：

# 搜索社区技能
hermes skills search kubernetes

# 安装技能
hermes skills install devops/deploy-k8s

# 查看已安装技能
hermes skills list

# 调用技能
/deploy-k8s 帮我部署一个 Nginx 服务

6.4 多平台网关

将 Hermes Agent 连接到微信、Telegram 等平台，随时随地使用：

# 微信连接（国内最实用）
hermes plugins enable wechat
hermes wechat login  # 扫码登录即可

# Telegram 连接
hermes gateway setup telegram
hermes gateway start

6.5 自然语言定时任务

无需编写 cron 表达式，用自然语言设置定时任务：

hermes cron add "每天早上9点，整理昨天的工作邮件，生成摘要发送到我的企业微信"
hermes cron add "每周五下午6点，统计本周代码提交量，生成周报"

七、高频问题排查（分层倒查法）

遇到问题时按以下层级排查，90%的问题都能快速解决：

层级 常见症状 排查方向 解决方案

依赖层

hermes: command not found

PATH 环境变量、~/.local/bin 是否在 PATH

source ~/.bashrc 或手动添加 PATH

网络层

安装超时、模型调用超时

GitHub 连通性、Kimi API 连通性

重新配置国内加速、检查防火墙

配置层

API Key 无效、模型加载失败

.env 变量名、Key 拼写、账户余额

重新生成 Kimi API Key，执行 hermes model 重新配置

权限层

无法写文件、命令被拒

工作目录权限、审批模式、macOS TCC

批准命令、修正目录权限、保持 manual 审批模式

运行层

静默失败、任务无响应

日志文件、hermes doctor 输出

查看 ~/.hermes/logs/errors.log，按提示修复

Kimi 专属问题排查：

  • 报错 Authentication failed for provider 'moonshot'：检查 API Key 是否正确，是否有多余空格
  • 报错 429 Too Many Requests：Kimi API 调用频率超限，稍后重试或升级套餐
  • 输出乱码：确保文件编码为 UTF-8，Kimi 仅支持 UTF-8 编码的文本

八、最佳实践与安全建议

8.1 国内用户最佳实践

  1. 模型选择：全程使用 Kimi 大模型，避免海外模型的网络和中文问题
  2. 权限收敛：试用阶段仅开放必要工具，生产环境使用 Docker 或 SSH 隔离后端
  3. 成本控制：在 Kimi 控制台设置消费限额和用量告警，避免意外扣费
  4. 数据隔离：所有任务在 ~/hermes-workspace 内执行，不要访问个人敏感目录

8.2 安全加固建议

  • 永远不要开启 YOLO 模式，所有危险命令必须手动审批
  • 定期备份 ~/.hermes/ 目录，特别是配置和技能文件
  • 不要将 API Key 写入任何配置文件或提交到代码仓库
  • 从社区安装技能时，先执行 hermes skills inspect <skill> 做安全检查

8.3 版本更新与维护

# 一键脚本安装更新
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# pip 安装更新
pip install --upgrade hermes-agent

# 更新后执行配置迁移
hermes config migrate

8.4 接入生产工作流前的检查清单

再次备份 ~/.hermes/ 目录

确认审批模式符合团队安全策略

在 Kimi 控制台设置了消费限额和告警

人工抽查了10次以上任务的输出质量

阅读了官方安全文档，关闭了不必要的工具和端口

总结

Hermes Agent 是目前最成熟、最易用的开源 AI 智能体之一，搭配 Kimi 大模型后，国内用户可以获得媲美甚至超越海外服务的体验。按照本文的清单式步骤操作，你可以在30分钟内完成从安装到实战的全流程。

Hermes Agent 的核心价值在于自我成长，建议你从简单的文档处理、任务管理开始，逐步让它熟悉你的工作习惯，最终成为你的专属 AI 助手。如果在使用过程中遇到问题，可以参考官方 GitHub Issues 或社区讨论区，也可以尝试用 hermes doctor 进行自我诊断。

「免责声明」：以上页面展示信息由第三方发布，目的在于传播更多信息，与本网站立场无关。我们不保证该信息(包括但不限于文字、数据及图表)全部或者部分内容的准确性、真实性、完整性、有效性、及时性、原创性等。相关信息并未经过本网站证实，不对您构成任何投资建议，据此操作，风险自担，以上网页呈现的图片均为自发上传，如发生图片侵权行为与我们无关，如有请直接微信联系g1002718958。 

# 科技
Logo
科技大视野开发者社区

更多推荐

cover

KADC 2026 | 极致性能，算力无疆——鲲鹏BoostKit 加速 AI 应用创新

avatar 科技大视野开发者社区
cover

2026高端智能家居品牌避坑指南，读懂美学、安全与全场景进化

avatar 科技大视野开发者社区
cover

企业级智能体开发平台哪个好？三维评价体系与5家主流平台分析

avatar 科技大视野开发者社区