第五册：安装部署全攻略 —— 保姆级部署指南，让 Hermes 在你的机器上跑起来

# 测试 GitHub 访问
ping -c 3 github.com
 
# 测试 PyPI 访问
ping -c 3 pypi.org
 
# 测试 npm 仓库访问
ping -c 3 registry.npmjs.org

# macOS / Linux - 临时设置 HTTP 代理（仅当前终端窗口有效）
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
 
# 如果你使用的是 SOCKS5 代理
export ALL_PROXY=socks5://127.0.0.1:7890
 
# Windows PowerShell - 临时设置代理
$env:http_proxy="http://127.0.0.1:7890"
$env:https_proxy="http://127.0.0.1:7890"

# 配置 Git 使用代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
 
# 验证 Git 代理配置
git config --global --get http.proxy
git config --global --get https.proxy
 
# 取消 Git 代理（安装完成后建议取消）
git config --global --unset http.proxy
git config --global --unset https.proxy

# 临时使用代理安装 Python 包
pip install --proxy http://127.0.0.1:7890 <package_name>
 
# 或者配置 pip 全局代理
pip config set global.proxy http://127.0.0.1:7890
 
# 使用国内镜像源（更推荐长期方案）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 查看当前 npm 源
npm config get registry
 
# 切换到淘宝镜像源
npm config set registry https://registry.npmmirror.com
 
# 验证切换成功
npm config get registry
# 应输出: https://registry.npmmirror.com
 
# 恢复官方源（如需）
npm config set registry https://registry.npmjs.org
 
# 如果你使用 yarn
yarn config set registry https://registry.npmmirror.com
 
# 如果你使用 pnpm
pnpm config set registry https://registry.npmmirror.com

# macOS / Linux
python3 --version
 
# 某些系统可能需要使用 python 而不是 python3
python --version
 
# Windows (PowerShell)
python --version

# macOS (使用 Homebrew)
brew install [email protected]
 
# Ubuntu/Debian
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev python3-pip
 
# Fedora
sudo dnf install python3.11 python3.11-devel

node --version

git --version

# macOS
xcode-select --install
 
# Ubuntu/Debian
sudo apt update
sudo apt install git
 
# Fedora
sudo dnf install git
 
# Windows
# 下载安装程序：https://git-scm.com/download/win

#!/bin/bash
# save as: check-env.sh
 
echo "🔍 Hermes 安装前环境检查"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
# 检查 Python 版本
PYTHON_VERSION=$(python3 --version 2>/dev/null || python --version 2>/dev/null)
if [ -n "$PYTHON_VERSION" ]; then
    echo "✓ Python: $PYTHON_VERSION"
else
    echo "✗ Python: 未安装"
fi
 
# 检查 Node.js
NODE_VERSION=$(node --version 2>/dev/null)
if [ -n "$NODE_VERSION" ]; then
    echo "✓ Node.js: $NODE_VERSION"
else
    echo "✗ Node.js: 未安装"
fi
 
# 检查 Git
GIT_VERSION=$(git --version 2>/dev/null)
if [ -n "$GIT_VERSION" ]; then
    echo "✓ Git: $GIT_VERSION"
else
    echo "✗ Git: 未安装"
fi
 
# 检查磁盘空间
DISK_AVAILABLE=$(df -h ~ | awk 'NR==2 {print $4}')
echo "✓ 磁盘可用空间: $DISK_AVAILABLE"
 
# 检查内存
if command -v free &> /dev/null; then
    MEM_AVAILABLE=$(free -h | awk '/^Mem:/ {print $7}')
    echo "✓ 内存可用: $MEM_AVAILABLE"
fi
 
# 检查网络
echo ""
echo "🌐 网络检查:"
ping -c 1 github.com > /dev/null 2>&1 && echo "✓ GitHub 可访问" || echo "✗ GitHub 无法访问"
ping -c 1 pypi.org > /dev/null 2>&1 && echo "✓ PyPI 可访问" || echo "✗ PyPI 无法访问"
 
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "检查完成！如果有 ✗ 项，请先解决后再安装 Hermes。"

chmod +x check-env.sh
./check-env.sh

brew --version

# 官方安装脚本
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Apple Silicon Mac (M1/M2/M3/M4)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
 
# Intel Mac
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

# 更新 Homebrew 本身和软件包列表
brew update
 
# 升级已安装的软件包（可选，建议执行）
brew upgrade

# 安装 Python 3.11
brew install [email protected]
 
# 将 Python 3.11 链接到 PATH
brew link [email protected] --force
 
# 验证安装
python3 --version
# 应输出: Python 3.11.x

# 通过 Homebrew 安装 pyenv
brew install pyenv
 
# 将 pyenv 初始化代码添加到 shell 配置文件
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
 
# 重新加载 shell 配置
source ~/.zshrc

# 查看可安装的 Python 版本
pyenv install --list | grep "3.11"
 
# 安装 Python 3.11.9（选择最新的 3.11.x 版本）
pyenv install 3.11.9
 
# 设置全局默认 Python 版本
pyenv global 3.11.9
 
# 验证
python --version
# 应输出: Python 3.11.9

# 查看已安装的 Python 版本
pyenv versions
 
# 在当前目录使用特定 Python 版本（仅当前文件夹有效）
pyenv local 3.11.9
 
# 在当前终端会话使用特定 Python 版本
pyenv shell 3.11.9
 
# 卸载某个 Python 版本
pyenv uninstall 3.10.12

# 通过 Homebrew 安装 Node.js
brew install node
 
# 验证安装
node --version
# 应输出: v22.x.x 或更高
 
# 同时验证 npm（Node.js 的包管理器）
npm --version

# 安装/更新 Git
brew install git
 
# 验证
git --version

# 方式一：使用官方推荐的一键安装脚本（推荐）
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh
 
# 方式二：如果方式一网络不通，可以先克隆仓库再手动安装
git clone https://github.com/NousResearch/hermes.git ~/hermes
cd ~/hermes
pip install -e .

# 检查 Hermes 版本
hermes --version
 
# 或者
hermes -v
 
# 运行系统诊断
hermes doctor

# 更新软件包列表
sudo apt update
 
# 升级已安装的软件包
sudo apt upgrade -y
 
# 安装必要的构建工具和依赖
sudo apt install -y \
    curl \
    wget \
    git \
    build-essential \
    libssl-dev \
    zlib1g-dev \
    libbz2-dev \
    libreadline-dev \
    libsqlite3-dev \
    llvm \
    libncursesw5-dev \
    xz-utils \
    tk-dev \
    libxml2-dev \
    libxmlsec1-dev \
    libffi-dev \
    liblzma-dev

# 添加 deadsnakes PPA（提供最新 Python 版本的第三方仓库）
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
 
# 安装 Python 3.11 及配套工具
sudo apt install -y python3.11 python3.11-venv python3.11-dev python3.11-distutils
 
# 验证安装
python3.11 --version
# 应输出: Python 3.11.x
 
# 安装 pip for Python 3.11
curl -sS https://bootstrap.pypa.io/get-pip.py | python3.11
 
# 验证 pip
python3.11 -m pip --version

# 安装 pyenv
curl https://pyenv.run | bash
 
# 将 pyenv 添加到 ~/.bashrc
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
 
# 重新加载配置
source ~/.bashrc
 
# 使用 pyenv 安装 Python 3.11.9
pyenv install 3.11.9
pyenv global 3.11.9
 
# 验证
python --version

# 使用 NodeSource 安装脚本安装 Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
 
# 验证
node --version
npm --version

# 一键安装
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh
 
# 或者手动安装
git clone https://github.com/NousResearch/hermes.git ~/hermes
cd ~/hermes
python3.11 -m pip install -e .

hermes --version
hermes doctor

# 自动安装 WSL2 和默认的 Ubuntu 发行版
wsl --install

# 启用 WSL
wsl --set-default-version 2
 
# 查看可用的 Linux 发行版
wsl --list --online
 
# 安装 Ubuntu 22.04
wsl --install -d Ubuntu-22.04

sudo apt update && sudo apt upgrade -y

# 安装依赖
sudo apt install -y curl wget git build-essential libssl-dev zlib1g-dev \
    libbz2-dev libreadline-dev libsqlite3-dev llvm libncursesw5-dev \
    xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
 
# 安装 Python 3.11
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3.11-dev python3.11-distutils
curl -sS https://bootstrap.pypa.io/get-pip.py | python3.11
 
# 安装 Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
 
# 安装 Hermes
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh
 
# 验证
hermes --version

# 访问 C 盘
cd /mnt/c
ls
 
# 访问 D 盘
cd /mnt/d
ls
 
# 访问你的 Windows 用户目录
cd /mnt/c/Users/你的Windows用户名/Desktop

# 在 WSL 中创建一个工作目录
mkdir -p ~/workspace
 
# 同时在 Windows 的文档目录也创建一个快捷方式
# 在 Windows PowerShell 中执行：
# New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\workspace" -Target "\\wsl$\Ubuntu-22.04\home\你的用户名\workspace"

# 方式一：通过 Homebrew 安装（推荐）
brew install --cask docker
 
# 方式二：手动下载安装
# 访问 https://www.docker.com/products/docker-desktop/
# 下载 macOS 版本并安装

# 以 Ubuntu 为例
# 1. 卸载旧版本（如有）
sudo apt remove docker docker-engine docker.io containerd runc
 
# 2. 安装依赖
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release
 
# 3. 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
 
# 4. 添加 Docker 软件源
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 
# 5. 安装 Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
 
# 6. 将当前用户加入 docker 组（免 sudo 使用 docker）
sudo usermod -aG docker $USER
 
# 7. 验证安装
docker --version
docker compose version

# 拉取最新版本的 Hermes 镜像
docker pull nousresearch/hermes:latest
 
# 或者拉取特定版本
docker pull nousresearch/hermes:v1.2.0
 
# 查看已拉取的镜像
docker images | grep hermes

# 运行 Hermes 容器
docker run -it --rm \
  --name hermes \
  -v ~/.hermes:/opt/data \
  -e OPENAI_API_KEY="your-api-key-here" \
  nousresearch/hermes:latest

# 先创建主机上的数据目录
mkdir -p ~/.hermes
 
# 运行容器并挂载数据卷
docker run -it --rm \
  --name hermes \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes:latest

# docker-compose.yml
version: "3.8"
 
services:
  hermes:
    image: nousresearch/hermes:latest
    container_name: hermes
    restart: unless-stopped
    volumes:
      - ~/.hermes:/opt/data
      - ~/workspace:/workspace
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    stdin_open: true
    tty: true
    networks:
      - hermes-network
 
networks:
  hermes-network:
    driver: bridge

# 在 docker-compose.yml 所在目录执行
 
# 启动服务（后台运行）
docker compose up -d
 
# 查看运行状态
docker compose ps
 
# 查看日志
docker compose logs -f hermes
 
# 进入容器内部
docker compose exec hermes bash
 
# 停止服务
docker compose down
 
# 停止服务并删除数据卷（慎用！）
docker compose down -v

# .env 文件（放在 docker-compose.yml 同目录，不要提交到 Git！）
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-your-anthropic-key
DEEPSEEK_API_KEY=sk-your-deepseek-key

# 查看正在运行的容器
docker ps
 
# 查看所有容器（包括已停止的）
docker ps -a
 
# 停止容器
docker stop hermes
 
# 启动已停止的容器
docker start hermes
 
# 重启容器
docker restart hermes
 
# 删除容器
docker rm hermes
 
# 强制删除运行中的容器
docker rm -f hermes
 
# 查看容器日志
docker logs hermes
 
# 实时查看日志
docker logs -f hermes
 
# 进入运行中的容器
docker exec -it hermes bash
 
# 从容器内复制文件到主机
docker cp hermes:/opt/data/config.yaml ~/.hermes/config.yaml
 
# 从主机复制文件到容器
docker cp ~/.hermes/config.yaml hermes:/opt/data/config.yaml
 
# 查看容器资源使用情况
docker stats hermes

# macOS / Linux 终端直接连接
ssh root@你的服务器IP
 
# 示例
ssh [email protected]
 
# 如果指定了非标准端口（如 2222）
ssh -p 2222 root@你的服务器IP

passwd

# 创建新用户
useradd -m -s /bin/bash hermes
 
# 设置密码
passwd hermes
 
# 将用户加入 sudo 组
usermod -aG sudo hermes
 
# 切换到新用户
su - hermes

# 本地电脑执行
ssh-keygen -t ed25519 -C "[email protected]"
 
# 将公钥复制到服务器
ssh-copy-id hermes@你的服务器IP

# 编辑 SSH 配置文件
sudo nano /etc/ssh/sshd_config
 
# 修改以下配置
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
 
# 重启 SSH 服务
sudo systemctl restart sshd

# Ubuntu/Debian
sudo apt install ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
 
# 查看防火墙状态
sudo ufw status

# 安装 fail2ban
sudo apt install fail2ban
 
# 启动服务
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
 
# 查看封禁状态
sudo fail2ban-client status sshd

# 1. 系统更新
sudo apt update && sudo apt upgrade -y
 
# 2. 安装依赖
sudo apt install -y curl wget git build-essential libssl-dev \
    zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \
    llvm libncursesw5-dev xz-utils tk-dev libxml2-dev \
    libxmlsec1-dev libffi-dev liblzma-dev software-properties-common
 
# 3. 安装 Python 3.11
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3.11-dev python3.11-distutils
curl -sS https://bootstrap.pypa.io/get-pip.py | python3.11
 
# 4. 安装 Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
 
# 5. 安装 Hermes
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh
 
# 6. 验证
hermes --version
hermes doctor

# 安装 screen
sudo apt install -y screen
 
# 创建一个新的 screen 会话
screen -S hermes
 
# 在 screen 中启动 Hermes
hermes
 
# 按 Ctrl+A，然后按 D， detach 会话（程序继续在后台运行）
# 注意：是先按 Ctrl+A，松开后再按 D
 
# 重新连接会话
screen -r hermes
 
# 查看所有 screen 会话
screen -ls
 
# 终止会话
screen -X -S hermes quit

# 安装 tmux
sudo apt install -y tmux
 
# 创建新会话
tmux new -s hermes
 
# 在 tmux 中启动 Hermes
hermes
 
# 分离会话：按 Ctrl+B，然后按 D
 
# 重新连接会话
tmux attach -t hermes
 
# 查看所有会话
tmux ls
 
# 终止会话
tmux kill-session -t hermes

# 安装 Nginx
sudo apt install -y nginx
 
# 创建 Nginx 配置文件
sudo nano /etc/nginx/sites-available/hermes

server {
    listen 80;
    server_name yourdomain.com;
 
    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

# 启用配置
sudo ln -s /etc/nginx/sites-available/hermes /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
 
# 安装 Certbot 获取免费 SSL 证书
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com
 
# 按照提示完成证书申请

sudo nano /etc/systemd/system/hermes.service

[Unit]
Description=Hermes Agent
After=network.target
 
[Service]
Type=simple
User=hermes
WorkingDirectory=/home/hermes
Environment="HOME=/home/hermes"
Environment="PATH=/home/hermes/.local/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/home/hermes/.local/bin/hermes chat
Restart=on-failure
RestartSec=5
 
[Install]
WantedBy=multi-user.target

# 重新加载 systemd 配置
sudo systemctl daemon-reload
 
# 设置开机自启
sudo systemctl enable hermes
 
# 启动服务
sudo systemctl start hermes
 
# 查看服务状态
sudo systemctl status hermes
 
# 查看日志
sudo journalctl -u hermes -f
 
# 停止服务
sudo systemctl stop hermes
 
# 重启服务
sudo systemctl restart hermes

# 创建 logrotate 配置
sudo nano /etc/logrotate.d/hermes

# 测试配置是否正确
sudo logrotate -d /etc/logrotate.d/hermes
 
# 手动执行一次轮转
sudo logrotate -f /etc/logrotate.d/hermes

pip install modal

modal token new

import modal
 
# 定义 Modal 应用
app = modal.App("hermes-agent")
 
# 定义容器镜像
image = (
    modal.Image.debian_slim()
    .apt_install("git", "curl", "build-essential")
    .pip_install("hermes-agent")
)
 
# 定义持久化卷
volume = modal.Volume.from_name("hermes-data", create_if_missing=True)
 
@app.function(
    image=image,
    volumes={"/opt/data": volume},
    secrets=[modal.Secret.from_name("hermes-secrets")],
    timeout=3600,  # 1小时超时
)
def run_hermes(prompt: str):
    """运行 Hermes Agent"""
    import subprocess
    import os
 
    # 设置数据目录
    os.environ["HERMES_DATA_DIR"] = "/opt/data"
 
    # 运行 Hermes 命令
    result = subprocess.run(
        ["hermes", "-c", prompt],
        capture_output=True,
        text=True,
        timeout=300
    )
 
    return {
        "stdout": result.stdout,
        "stderr": result.stderr,
        "returncode": result.returncode
    }
 
@app.local_entrypoint()
def main():
    # 本地测试入口
    response = run_hermes.remote("Hello, what can you do?")
    print(response["stdout"])

# 创建 Modal Secret 存储 API Keys
modal secret create hermes-secrets \
  OPENAI_API_KEY=sk-your-key \
  ANTHROPIC_API_KEY=sk-your-key

# 部署到 Modal
modal deploy deploy_modal.py
 
# 调用函数
modal run deploy_modal.py

# macOS
brew install daytona
 
# Linux
curl -fsSL https://download.daytona.io/daytona/install.sh | bash

daytona login

# 创建新的工作区
daytona create hermes-workspace
 
# 选择基础镜像（推荐 Ubuntu 22.04）
# 然后 Daytona 会自动创建一个配置好的开发环境
 
# 进入工作区
daytona ssh hermes-workspace
 
# 在工作区内安装 Hermes（按 Linux 安装流程）
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh
 
# 配置 API Keys
hermes setup

# ~/.hermes/config.yaml
# Hermes 主配置文件
 
# === 核心设置 ===
core:
  # Agent 名称
  name: "Hermes"
 
  # 默认使用的模型提供者
  default_provider: "openrouter"
 
  # 默认模型
  default_model: "anthropic/claude-3.5-sonnet"
 
  # 对话语言
  language: "zh"
 
  # 日志级别: debug, info, warn, error
  log_level: "info"
 
# === 模型配置 ===
models:
  # 分层模型配置（详见第六册第 6 章）
  reasoning:
    provider: "anthropic"
    model: "claude-3.5-sonnet"
 
  execution:
    provider: "openrouter"
    model: "google/gemini-flash-1.5"
 
  fallback:
    - provider: "deepseek"
      model: "deepseek-chat"
    - provider: "openai"
      model: "gpt-4o-mini"
 
# === API Key 配置 ===
# 建议通过环境变量设置，不要在配置文件中硬编码
providers:
  openai:
    api_key: "${OPENAI_API_KEY}"
    base_url: "https://api.openai.com/v1"
 
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"
    base_url: "https://api.anthropic.com"
 
  deepseek:
    api_key: "${DEEPSEEK_API_KEY}"
    base_url: "https://api.deepseek.com"
 
  openrouter:
    api_key: "${OPENROUTER_API_KEY}"
    base_url: "https://openrouter.ai/api/v1"
 
  # Nous Portal：Nous Research 官方提供的统一订阅服务
  # 一个月费涵盖所有接入模型，无需单独购买各平台 Key
  nous:
    api_key: "${NOUS_API_KEY}"
    base_url: "https://portal.nousresearch.com/api/v1"
 
  # 智谱 GLM-5：国产大模型，中文理解优秀
  zhipu:
    api_key: "${ZHIPU_API_KEY}"
    base_url: "https://open.bigmodel.cn/api/paas/v4"
 
  # MiniMax M2.7：国产模型，性价比出色
  minimax:
    api_key: "${MINIMAX_API_KEY}"
    base_url: "https://api.minimax.chat/v1"
 
# === 记忆系统配置 ===
memory:
  # 会话记忆条数
  session_limit: 50
 
  # 持久化记忆开关
  persistent: true
 
  # 向量搜索 Top-K
  vector_top_k: 5
 
# === 工具配置 ===
tools:
  # 启用的工具列表
  enabled:
    - web_search
    - file_read
    - file_write
    - execute_shell
    - github
 
  # 禁用工具（优先级高于 enabled）
  disabled: []
 
# === 技能系统配置 ===
skills:
  # 自动技能发现
  auto_discover: true
 
  # 技能搜索路径
  paths:
    - "~/.hermes/skills/custom"
    - "~/.hermes/skills/downloaded"
 
# === 消息网关配置 ===
gateway:
  # Web 界面端口
  web_port: 8080
 
  # 启用平台
  platforms:
    - telegram
    - discord
 
# === 定时任务配置 ===
cron:
  # 定时任务开关
  enabled: true
 
  # 任务文件路径
  jobs_file: "~/.hermes/cron/jobs.yaml"

# SOUL.md
 
# 这是 Hermes Agent 的人设定义文件
 
# 修改此文件后，Hermes 的行为和回答风格会随之改变
 
## 身份
 
你是一位名叫「墨离」的 AI 助手。
 
## 性格
 
- 沉稳、耐心、善于倾听
- 回答问题时先思考再开口，不急于给出结论
- 喜欢用类比和故事来解释复杂概念
- 偶尔会用温和的幽默调节气氛
 
## 专业领域
 
- Python 编程与软件架构
- 数据分析与可视化
- AI Agent 技术
- 中文写作与编辑
 
## 说话风格
 
- 使用中文回答，除非用户明确要求使用其他语言
- 避免使用过于学术化的术语，尽量通俗易懂
- 重要观点会用「>」引用格式强调
- 分点说明时喜欢用表格整理信息
 
## 行为准则
 
- 不确定的事情会坦诚告知，不编造信息
- 涉及代码时，总是提供完整的可运行示例
- 尊重用户隐私，不主动询问敏感信息
- 当用户情绪激动时，先安抚再解决问题
 
## 禁忌
 
- 不使用机器人口吻（如「作为一个人工智能助手」）
- 不重复用户的问题作为回答开头
- 不过度道歉

# MEMORY.md
 
# 这是 Hermes 的全局记忆文件
 
# 这里存储的信息会在每次对话开始时自动加载
 
## 用户偏好
 
- 用户喜欢简洁的回答，不喜欢冗长的解释
- 用户是程序员，熟悉 Python 和 JavaScript
- 用户通常在晚上 9-11 点使用 Hermes
- 用户对 AI 伦理话题感兴趣
 
## 重要信息
 
- 用户的项目目录：`~/projects/my-startup`
- 用户常用的 API Key 别名：`openai_main`、`deepseek_backup`
- 用户的时区：Asia/Shanghai
 
## 待办事项
 
- [ ] 帮用户调研 MCP 协议的最新进展
- [ ] 记得提醒用户下周的代码评审会议

# USER.md
 
# 用户信息
 
## 基本信息
 
- 称呼：王先生
- 职业：全栈开发者 / 独立创业者
- 所在地：中国，上海
 
## 技术栈
 
- 主要语言：Python、TypeScript
- 框架：React、FastAPI、Django
- 工具：VS Code、Docker、Git
 
## 使用场景
 
- 日常编程辅助和代码审查
- 技术文章写作
- 项目需求分析和文档撰写
- 学习新技术和框架

# ~/.hermes/cron/jobs.yaml
jobs:
  - name: "daily-news-summary"
    description: "每天早上 8 点总结科技新闻"
    schedule: "0 8 * * *"
    command: "搜索今天的科技新闻并总结要点"
    enabled: true
 
  - name: "weekly-report"
    description: "每周五下午生成周报"
    schedule: "0 17 * * 5"
    command: "读取本周的会议纪要，生成周报"
    enabled: false

# 实时查看主日志
tail -f ~/.hermes/logs/hermes.log
 
# 实时查看错误日志
tail -f ~/.hermes/logs/error.log
 
# 搜索特定关键词
grep "ERROR" ~/.hermes/logs/hermes.log

# 查看 Hermes 版本
hermes --version
 
# 查看详细版本信息（包含 Python 版本、操作系统等）
hermes --version --verbose

hermes doctor

# 1. 确认 Python 3.11 已安装
python3.11 --version
 
# 2. 如果已安装但 hermes 调用的是旧版本，创建别名
alias hermes="python3.11 -m hermes"
 
# 3. 或者使用 pyenv 设置全局版本
pyenv global 3.11.9
 
# 4. 如果未安装，参考 2.1 节安装 Python 3.11

# macOS
brew upgrade node
 
# Ubuntu/Debian
# 先卸载旧版本
sudo apt remove nodejs
# 然后重新安装（参考 2.2 节的 NodeSource 安装脚本）
 
# 或者使用 nvm 管理 Node 版本
nvm install 22
nvm use 22
nvm alias default 22

# 方案 1：配置终端代理
export https_proxy=http://127.0.0.1:7890
 
# 方案 2：配置 Git 使用代理
git config --global https.proxy http://127.0.0.1:7890
 
# 方案 3：使用国内镜像加速 Git 克隆
git clone https://ghproxy.com/https://github.com/NousResearch/hermes.git
 
# 方案 4：修改 hosts（临时方案）
# 在 /etc/hosts 中添加 GitHub 的 IP（IP 会变动，需自行查找最新 IP）
sudo sh -c 'echo "140.82.114.4 github.com" >> /etc/hosts'

# 修复权限（macOS / Linux）
# 将 ~/.hermes 目录的所有者改回当前用户
sudo chown -R $(whoami):$(whoami) ~/.hermes
 
# 修复权限位
chmod -R u+rw ~/.hermes
 
# 如果 hermes 命令本身权限不够
chmod +x $(which hermes)

# macOS
xcode-select --install
brew install gcc
 
# Ubuntu/Debian
sudo apt install -y build-essential python3.11-dev libffi-dev
 
# Fedora
sudo dnf install -y gcc python3.11-devel libffi-devel
 
# 然后重新安装依赖
pip install --force-reinstall hermes-agent

# 1. 检查 API Key 是否正确（特别注意是否有尾随空格！）
echo "$OPENAI_API_KEY" | cat -A
# 如果末尾有 "$" 之外的符号（如 " $"），说明有空格
 
# 2. 清理 Key 中的空白字符
export OPENAI_API_KEY=$(echo "$OPENAI_API_KEY" | xargs)
 
# 3. 确认 Key 和提供者匹配
# OpenAI 的 Key 必须以 "sk-" 开头
# Anthropic 的 Key 必须以 "sk-ant-" 开头
# DeepSeek 的 Key 格式为 "sk-xxxxxxxx"
# OpenRouter 的 Key 格式为 "sk-or-v1-xxxxxxxx"
 
# 4. 验证 API Key 是否有效
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
 
# 5. 重新运行 setup 配置
hermes setup
 
# 6. 如果通过环境变量设置，检查环境变量是否生效
# 在 .zshrc 或 .bashrc 中添加：
export OPENAI_API_KEY="sk-your-actual-key"
# 然后运行 source ~/.zshrc 生效

# 查找占用端口的进程
lsof -i :8080
 
# macOS / Linux
# 终止占用进程（将 <PID> 替换为实际的进程 ID）
kill -9 <PID>
 
# 或者修改 Hermes 的端口
# 编辑 ~/.hermes/config.yaml
gateway:
  web_port: 8081  # 改成其他端口

# 查看磁盘使用情况
df -h
 
# 清理 pip 缓存
pip cache purge
 
# 清理 Docker 缓存（如果使用 Docker）
docker system prune -a
 
# 清理 Hermes 日志
rm ~/.hermes/logs/*.log
 
# 压缩数据库（如果数据库文件过大）
sqlite3 ~/.hermes/database/hermes.db "VACUUM;"

# 1. 先备份损坏的数据库
cp ~/.hermes/database/hermes.db ~/.hermes/database/hermes.db.bak
 
# 2. 尝试修复
sqlite3 ~/.hermes/database/hermes.db ".recover" | sqlite3 ~/.hermes/database/hermes_fixed.db
 
# 3. 替换原数据库
mv ~/.hermes/database/hermes_fixed.db ~/.hermes/database/hermes.db
 
# 4. 如果修复失败，可以从备份恢复或重置数据库
# 重置（会丢失所有历史数据）：
rm ~/.hermes/database/hermes.db
hermes doctor

# 方案 1：重新加载 shell 配置（官方推荐第一步）
source ~/.bashrc      # bash 用户
source ~/.zshrc       # zsh 用户
source ~/.config/fish/config.fish  # fish 用户
 
# 方案 2：手动将 ~/.hermes/bin 加入 PATH
echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
 
# 方案 3：在当前终端中临时添加 PATH
export PATH="$HOME/.hermes/bin:$PATH"
 
# 方案 4：查找 hermes 安装位置
ls -la ~/.hermes/bin/hermes
# 或者
find ~ -name "hermes" -type f 2>/dev/null
 
# 方案 5：如果还是找不到，尝试用 Python 模块方式运行
python3 -m hermes --version

# 在管理员 PowerShell 中运行
wsl --install

# 打开 WSL2 终端（Ubuntu）
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh

# 在 /etc/wsl.conf 中添加配置
sudo nano /etc/wsl.conf

[automount]
enabled = true
mountFsTab = false
root = /mnt/
options = "metadata,umask=22,fmask=11"

# 在 Windows PowerShell 中执行
wsl --shutdown

# 确认挂载路径正确
# 主机路径必须写绝对路径
 
# 正确的做法
docker run -v /home/username/workspace:/workspace nousresearch/hermes
 
# 错误的做法（~ 在 Docker 中不会被展开）
docker run -v ~/workspace:/workspace nousresearch/hermes
 
# 如果使用 Docker Compose，确保 volumes 配置正确

# 1. 检查 cron 服务是否启用
hermes cron status
 
# 2. 检查 jobs.yaml 格式是否正确
hermes cron validate
 
# 3. 查看 cron 日志
hermes cron logs
 
# 4. 手动测试任务
hermes cron run daily-news-summary
 
# 5. 确认 Hermes 进程在后台运行（VPS 部署时）
ps aux | grep hermes

# 配置代理排除规则（以 Clash 为例）
# 在 Clash 配置中添加：
# - DOMAIN-SUFFIX,deepseek.com,DIRECT
# - DOMAIN-SUFFIX,moonshot.cn,DIRECT
 
# 或者在终端只代理特定域名
export no_proxy="localhost,127.0.0.1,deepseek.com,moonshot.cn"
 
# 更优雅的方式：配置代理 PAC 规则
# 让浏览器/系统根据域名自动选择是否走代理

# 1. 备份当前配置
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak
 
# 2. 运行配置迁移
hermes migrate
 
# 3. 如果迁移失败，可以重置配置并重新 setup
mv ~/.hermes/config.yaml ~/.hermes/config.yaml.old
hermes setup
 
# 4. 然后手动把旧配置中的 API Key 和自定义设置复制到新配置中

hermes setup

models:
  reasoning:
    provider: "deepseek"
    model: "deepseek-reasoner"
  execution:
    provider: "deepseek"
    model: "deepseek-chat"
  fallback:
    - provider: "openrouter"
      model: "google/gemini-flash-1.5"

cat > ~/.hermes/SOUL.md << 'EOF'
# SOUL.md
 
## 身份
 
你是一位专业、友好的 AI 助手。
 
## 说话风格
 
- 使用中文回答
- 简洁明了，不啰嗦
- 技术问题给出可运行的代码示例
EOF

mkdir -p ~/scripts
cat > ~/scripts/backup-hermes.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="$HOME/hermes-backups"
mkdir -p "$BACKUP_DIR"
tar -czf "$BACKUP_DIR/hermes-$(date +%Y%m%d).tar.gz" -C "$HOME" .hermes/config.yaml .hermes/SOUL.md .hermes/MEMORY.md .hermes/USER.md .hermes/database .hermes/skills/custom .hermes/cron
EOF
chmod +x ~/scripts/backup-hermes.sh

hermes doctor

# LLM API Keys
export OPENAI_API_KEY="sk-your-openai-key"
export ANTHROPIC_API_KEY="sk-your-anthropic-key"
export DEEPSEEK_API_KEY="sk-your-deepseek-key"
export OPENROUTER_API_KEY="sk-your-openrouter-key"
export MOONSHOT_API_KEY="sk-your-moonshot-key"
 
# Hermes 配置
export HERMES_DATA_DIR="/custom/path/to/hermes/data"
export HERMES_CONFIG_PATH="/custom/path/config.yaml"
export HERMES_LOG_LEVEL="debug"
 
# 代理配置
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"

# 编辑 ~/.zshrc
nano ~/.zshrc
 
# 在文件末尾添加环境变量
export OPENAI_API_KEY="sk-your-key"
export DEEPSEEK_API_KEY="sk-your-key"
 
# 保存后生效
source ~/.zshrc

# 编辑 ~/.bashrc
nano ~/.bashrc
 
# 添加环境变量
export OPENAI_API_KEY="sk-your-key"
 
# 保存后生效
source ~/.bashrc

[automount]
enabled = true
 
[interop]
enabled = true
appendWindowsPath = true
 
# 传递特定环境变量到 WSL
[boot]
systemd = true

sudo nano /etc/profile.d/hermes-env.sh

export OPENAI_API_KEY="sk-your-key"
export DEEPSEEK_API_KEY="sk-your-key"

# 清华源（推荐）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
 
# 或阿里云源
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
 
# 验证
pip config get global.index-url

# 淘宝源（已更新域名）
npm config set registry https://registry.npmmirror.com
 
# 验证
npm config get registry

# 方式 1：使用 ghproxy 镜像
git clone https://ghproxy.com/https://github.com/owner/repo.git
 
# 方式 2：配置 Git 使用代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
 
# 方式 3：使用 SSH 协议（通常比 HTTPS 更稳定）
git clone [email protected]:owner/repo.git

# 定期压缩数据库（清理已删除数据占用的空间）
sqlite3 ~/.hermes/database/hermes.db "VACUUM;"
 
# 添加数据库索引（如果查询变慢）
sqlite3 ~/.hermes/database/hermes.db "CREATE INDEX IF NOT EXISTS idx_sessions_created ON sessions(created_at);"
 
# 查看数据库大小
ls -lh ~/.hermes/database/hermes.db

# 启动 Hermes 时限制最大内存为 512MB
ulimit -v 524288 && hermes
 
# 或者在 systemd 服务中添加限制
# 在 hermes.service 的 [Service] 段添加：
# MemoryMax=512M
# MemorySwapMax=0

core:
  max_concurrent_tasks: 3 # 默认可能是 5，低配机器可改为 2-3
  request_timeout: 30 # API 请求超时时间（秒）

# 创建备份目录
mkdir -p ~/hermes-backup-$(date +%Y%m%d)
 
# 备份核心数据
cp -r ~/.hermes/config.yaml ~/hermes-backup-$(date +%Y%m%d)/
cp -r ~/.hermes/SOUL.md ~/hermes-backup-$(date +%Y%m%d)/
cp -r ~/.hermes/MEMORY.md ~/hermes-backup-$(date +%Y%m%d)/
cp -r ~/.hermes/USER.md ~/hermes-backup-$(date +%Y%m%d)/
cp -r ~/.hermes/database ~/hermes-backup-$(date +%Y%m%d)/
cp -r ~/.hermes/skills/custom ~/hermes-backup-$(date +%Y%m%d)/
cp -r ~/.hermes/cron ~/hermes-backup-$(date +%Y%m%d)/
 
echo "备份完成，保存在: ~/hermes-backup-$(date +%Y%m%d)/"

# 卸载 Python 包
pip uninstall hermes-agent -y
 
# 或者如果你使用 pipx 安装
pipx uninstall hermes-agent
 
# 或者如果你从源码安装
cd ~/hermes
pip uninstall -e .

# 删除 Hermes 数据目录
rm -rf ~/.hermes
 
# 从 PATH 中移除 ~/.hermes/bin
# 编辑 ~/.zshrc 或 ~/.bashrc，删除以下行：
# export PATH="$HOME/.hermes/bin:$PATH"
nano ~/.zshrc
 
# 删除环境变量（从 ~/.zshrc 或 ~/.bashrc 中删除相关行）
# 手动删除 export HERMES_... 和 export OPENAI_API_KEY 等行

# 查找并删除残留的 hermes 相关文件
find ~ -name "*hermes*" -type f 2>/dev/null
find ~ -name "*hermes*" -type d 2>/dev/null
 
# 清理 pip 缓存
pip cache purge
 
# 如果使用了 systemd 服务，删除服务文件
sudo rm -f /etc/systemd/system/hermes.service
sudo systemctl daemon-reload
 
# 如果使用了 Docker，删除镜像和容器
docker stop hermes 2>/dev/null
docker rm hermes 2>/dev/null
docker rmi nousresearch/hermes:latest 2>/dev/null

# 创建备份脚本
mkdir -p ~/scripts
cat > ~/scripts/backup-hermes.sh << 'EOF'
#!/bin/bash
 
# Hermes 自动备份脚本
BACKUP_DIR="$HOME/hermes-backups"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_NAME="hermes-backup-$DATE"
 
# 创建备份目录
mkdir -p "$BACKUP_DIR"
 
# 执行备份
tar -czf "$BACKUP_DIR/$BACKUP_NAME.tar.gz" \
    -C "$HOME" \
    .hermes/config.yaml \
    .hermes/SOUL.md \
    .hermes/MEMORY.md \
    .hermes/USER.md \
    .hermes/database \
    .hermes/skills/custom \
    .hermes/cron
 
# 保留最近 30 天的备份，删除旧备份
find "$BACKUP_DIR" -name "hermes-backup-*.tar.gz" -mtime +30 -delete
 
echo "备份完成: $BACKUP_DIR/$BACKUP_NAME.tar.gz"
EOF
 
chmod +x ~/scripts/backup-hermes.sh
 
# 添加到 crontab（每天凌晨 3 点自动备份）
(crontab -l 2>/dev/null; echo "0 3 * * * $HOME/scripts/backup-hermes.sh") | crontab -