博客 · AI agents

Hermes Agent GitHub：安装与配置

在 Mac 上使用 Hermes Agent 的 GitHub 仓库：托管安装与开发检出、环境激活、分支与发布渠道、配置文件、更新与故障排查。

作者：Hatmac team2026-11-04阅读约 10 分钟

Hermes Agent 的 GitHub 仓库不只是一个下载地址，Mac 上的每一次安装其实都是这个仓库的一份 git 检出。本文介绍仓库的结构、如何从源码安装、发布与分支如何运作，以及如何在不破坏现有环境的前提下更新或贡献代码。

仓库概览

官方仓库是 github.com/NousResearch/hermes-agent，采用 MIT 许可证，由 Nous Research 维护。Hatmac 与该项目没有关联。你最常接触的部分如下：

路径	内容
---	---
`run_agent.py`、`agent/`	agent 主循环、提示词构建、上下文压缩
`cli.py`、`hermes_cli/`	`hermes` 命令、配置向导、配置管理、`doctor`
`tools/`	自注册的工具和终端后端
`gateway/`	消息 gateway 和各平台适配器
`skills/`、`optional-skills/`	内置技能和官方可选技能
`scripts/install.sh`	Linux 和 macOS 安装脚本
`cli-config.yaml.example`	配置示例，会被复制为 `~/.hermes/config.yaml`
`.env.example`	机密文件示例
`website/docs/`	官方文档的源文件
`CONTRIBUTING.md`、`AGENTS.md`	贡献指南，以及写给 AI 编程助手的说明

从 GitHub 安装的两种方式

官方支持两种方式，适合不同的人。

托管检出（面向使用者）。 官方安装脚本把仓库克隆到 ~/.hermes/hermes-agent，准备好依赖，并在 ~/.local/bin/hermes 放置 hermes 启动器。之后用 hermes update 更新。我们的 Mac mini 安装指南介绍的就是这种方式。
开发检出（面向贡献者和爱折腾的人）。 你自己把仓库克隆到任意位置，并在 shell 中激活它的环境。本文其余部分主要讲这种方式。

有两种捷径不受支持。项目的平台支持页面把通过 PyPI（pip install 或 uv tool install）和 Homebrew（brew install hermes-agent）安装都列为不支持。请使用上面两种方式之一。

macOS 上源码检出的前置条件

贡献指南列出了四项要求：

Git 及 git-lfs 扩展。 Git 随 Apple 的 Command Line Tools 提供（xcode-select --install），git-lfs 可以通过 Homebrew 安装。
Python 3.14。 项目固定要求 >=3.14,<3.15。你不需要自己安装，项目自带的包管理器（PM）会提供固定版本的解释器。
Node.js 和 pnpm，激活时同样会以固定版本提供。
原生编译器，用于编译没有预构建 wheel 的依赖。在 macOS 上，Command Line Tools 已经包含。

xcode-select --install
brew install git-lfs
git lfs install

克隆并激活环境

克隆仓库，然后选择一个单独的数据目录，让实验永远不会碰到生产用的 ~/.hermes：

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
bash
export HERMES_HOME="$HOME/hermes-dev-data"
export HERMES_RUNTIME_DIR="$HERMES_HOME/tools"
source ./activate
hermes --version

注意其中的 bash 这一行。activate 脚本使用 Bash 语法，官方文档提醒不要假定 macOS 默认的 zsh 行为相同。fish 用户可以改用 activate.fish。

首次激活时会下载固定版本的 Python 和工具、同步依赖，并把 hermes 定义为运行当前检出代码的 shell 函数。这个函数只在该工作树内有效，并在此期间屏蔽已安装的 hermes。deactivate 会恢复你的 shell。如果只想运行一条命令而不激活，可以用 scripts/run-in-hermes-env。

不要用原生的 pip 或 uv 命令修改这个环境。uv 是包管理器的内部实现，官方文档明确表示不应以这种方式修改 PM 构建的环境。请用 hermes setup 配置开发数据目录，而不是把生产环境的 key 复制到检出目录里。

分支、标签与发布渠道

**main** 包含每一个合并的改动。
发布标签标记稳定版本，当前版本请查看仓库的 Releases 和 tags 页面。
stable 渠道是新安装的默认渠道。hermes update 会把托管检出移动到最新的发布标签。

你可以在安装时或之后改变选择：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --channel main
hermes update --set-channel main      # 跟随 main 上的每次提交
hermes update --set-channel stable    # 回到只跟随正式发布
hermes update --check                 # 预览更新会做什么
hermes update --branch some-branch    # 针对其他分支更新

对于别人依赖的 agent 所在的 Mac，请保持 stable。main 留给开发机使用。

配置文件参考

无论哪种安装方式，用户配置都放在检出目录之外的 HERMES_HOME 中：

文件	来源	用途
---	---	---
`config.yaml`	`cli-config.yaml.example`	模型、工具集、终端后端、审批、记忆、gateway
`.env`	`.env.example`	API key、机器人 token 等机密
`auth.json`	OAuth 登录	Nous Portal 等 OAuth 凭据
`SOUL.md`	配置向导	agent 的身份设定
`memories/`、`skills/`	运行时	持久记忆和技能
`state.db`	运行时	支持全文搜索的 SQLite 会话数据库
`cron/`、`logs/`	运行时	定时任务和日志文件

想查看某个选项及其注释时，可以阅读仓库中的 cli-config.yaml.example。更新带来新选项后，hermes config check 会列出缺失项，hermes config migrate 会交互式地补上。各项设置在 Mac 上的作用，请看我们的 Hermes 完整配置指南。

更新：hermes update 还是 git pull

**托管检出请用 hermes update，不要用 git pull。** 它做的不只是拉取代码：

为 config.yaml、.env、auth.json 和定时任务等状态文件做快照；
应用 stable 标签或所选分支，并更新子模块；
编译每次启动 hermes 都会导入的文件，如有文件解析失败就回滚检出；
同步依赖，并重启之前在运行的 gateway。

如果你有本地补丁，不要直接提交到 main。当 main 与上游分叉时，更新会把它重置为 origin/main，并把你原来的提交保存在 refs/hermes-update-backups/ 下的引用中。请把补丁放在自己的分支上，并设置 updates.parked_branch_strategy: update_in_place，这样更新会把上游合并进你的分支。

开发检出直接用 git 即可。拉取后重新激活，让环境与更新后的锁文件同步：

git pull
source ./activate

回馈贡献

贡献指南要求先搜索已有的 issue 和 pull request，并判断改动应该做成技能（说明加脚本）还是工具（带 schema 的 Python 代码）。提交 pull request 前，运行与 CI 相同的检查：

scripts/run_tests.sh
scripts/run_tests.sh tests/agent/ -v
python scripts/check

测试脚本会清除凭据并隔离 HERMES_HOME，所以测试不会影响你的真实环境。如果你修改了 scripts/install.sh，指南要求在 scripts/install.ps1 中做对应修改。

故障排查

现象	可能的解决办法
---	---
安装后提示 `hermes: command not found`	`source ~/.zshrc`，或把 `~/.local/bin` 加入 PATH
在 zsh 中 `source ./activate` 失败	先启动 `bash`，再激活
安装脚本某一步失败	查看 `~/.hermes/logs/install.log`，或加 `--verbose` 重新运行
更新后缺少配置项	`hermes config check`，再 `hermes config migrate`
更新时提示 “git data is damaged”	按官方 Updating 文档中的修复步骤处理
其他问题	运行 `hermes doctor`，并在 GitHub issue 中附上 `hermes dump` 的输出

hermes dump 会生成一份便于分享的纯文本环境摘要，API key 只显示“已设置”或“未设置”。--show-keys 会额外显示每个 key 的前后四个字符，公开发帖时不要加这个参数。

一台独占的 Mac 会让这一切更省心：一个干净的生产 HERMES_HOME，一个开发用的，也不会被笔记本睡眠打断。请看 Mac mini 上的 Hermes，在价格部分比较方案，或阅读如何 24/7 运行 Hermes Agent。

Hermes AgentGitHubsource installgitconfigurationcontributing