第二章 五分钟快速上手

一、动手前的 3 分钟准备

我们先确保你不会在动手之后才发现"哎呀少了什么东西"。

1.1 你需要这些东西

1.2 不会打开"终端"怎么办

如果你从来没用过终端，先记住怎么打开它：

• macOS：按 Command + 空格，输入 terminal，回车。
• Linux：通常在应用程序里有"Terminal"或"终端"，或者按 Ctrl + Alt + T。
• Windows：按 Win 键，搜 wsl，回车进入 WSL Ubuntu 终端（如果你还没装 WSL，下面会教）。

打开后会看到一个黑色（或白色）的窗口，光标在闪。这就是终端。你只要会复制粘贴、按回车就够了，本书不要求你手敲任何命令。

1.3 检查 Python 是否就绪

在终端里输入：

python3 --version

回车，你会看到三种结果：

• 看到 Python 3.10.x 或更高（如 Python 3.11.5）：完美，跳到第二节。
• 看到 Python 3.9.x 或更低：版本太老，需要升级。
• 看到 command not found: python3：还没装，需要先装。

如果需要安装/升级 Python

macOS（推荐用 Homebrew）：

# 如果还没装 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Python 3.11
brew install python@3.11

Linux（Ubuntu/Debian）：

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip git curl -y

Windows（先装 WSL2）：

打开 PowerShell（以管理员身份运行）：

wsl --install

重启电脑，会自动进入 Ubuntu。在 Ubuntu 里执行上面 Linux 那段命令。

国内用户网络加速（强烈建议）

如果你在国内，访问 GitHub 经常超时，先做两件事：

# 1) 把 Python 包源换成清华镜像
pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 2) 把 GitHub raw 换成镜像（仅用于下载安装脚本）
# 后面我们会提供镜像版的安装命令

再次运行 python3 --version，看到 Python 3.10 或更高就 OK 了。

二、安装 Hermes Agent（一行命令）

方式一（推荐 95% 的人）：一行命令

打开终端，复制粘贴下面这条命令，回车：

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

这条命令会自动做完五件事：

1. 把 Hermes 仓库克隆到 ~/.hermes/repo/；
2. 安装一个叫 uv 的快速 Python 包管理器；
3. 创建一个独立的 Python 虚拟环境，不污染你系统的 Python；
4. 安装所有依赖；
5. 把 hermes 命令加入你的 PATH。

整个过程视网速 大约 1~3 分钟。看到最后一行类似下面的提示就说明成功了：

✓ Hermes Agent installed successfully!
✓ Run `source ~/.bashrc` (or restart your terminal) to use `hermes`.

国内镜像版安装命令

如果上面那条 curl 一直转圈或失败，用 GitHub 镜像：

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

或者用 fastgit / gitclone 等其他镜像，只要把 https://raw.githubusercontent.com/... 替换成对应镜像即可。

方式二（开发者）：手动克隆

如果你是技术背景、希望对安装过程有完全掌控：

# 1) 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 2) 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# 4) 把 hermes 加入 PATH（在 ~/.bashrc 或 ~/.zshrc 里加一行）
echo 'export PATH="$HOME/hermes-agent/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

方式三（懒人）：Docker 跑

如果你完全不想碰 Python 环境：

docker run -it --name hermes \
  -v ~/.hermes:/root/.hermes \
  -e OPENROUTER_API_KEY=你的key \
  nousresearch/hermes-agent:latest

这种方式一切都在 Docker 容器里，干净但功能受限（无法直接读你电脑的文件，需要挂载目录）。本书后面默认用方式一。

验证安装

无论哪种方式，装完之后关闭终端，重新打开一个（这一步很重要，否则 PATH 不会更新）。然后输入：

hermes --version

看到类似下面的输出就说明成功：

hermes v0.8.0 (build 2026.4.8)

如果看到 command not found: hermes，跳到本章末尾的"5 大常见报错对照表"。

三、第一次配置：3 分钟走完向导

输入：

hermes setup

你会看到一个交互式的彩色向导。它会按顺序问你 5 件事：

第一问：选择 LLM 提供商

? Choose your primary LLM provider:
  > Nous Portal       (Hermes 原生模型，需注册)
    OpenRouter        (200+ 模型，新手最推荐)
    OpenAI            (GPT-4o, GPT-5 等)
    Anthropic         (Claude 系列)
    Ollama            (本地模型，零费用)
    Custom Endpoint   (自建/兼容 OpenAI 接口)

新手推荐选 OpenRouter——一个 API Key 通吃 200+ 模型，方便切换。 如果你想零费用试试，选 Ollama（需要先装 Ollama，下面会讲）。 如果你在国内不方便用海外服务，选 Custom Endpoint，下一章我们会教你怎么填 Kimi、DeepSeek 的接口地址。

我们这一章先选 OpenRouter 走通流程，下一章再讲完整的模型选择。

第二问：填 API Key

? Enter your OPENROUTER_API_KEY:

如果你还没有 OpenRouter 的 Key：

1. 打开 https://openrouter.ai 注册一个账号（用 GitHub / Google 账号一键登录即可）；
2. 进入 "Keys" 页面，点 "Create Key"，给它取个名（如 "hermes-test"），生成一个以 sk-or-v1- 开头的字符串；
3. 充值 5 美元（OpenRouter 是按用量付费，5 美元够你用很久）；
4. 把 Key 粘贴回终端。

如果你不想用 OpenRouter（国内或预算原因），按 Ctrl + C 退出向导，跳到 第三章 看完整方案。

第三问：选择默认模型

? Choose default model:
  > anthropic/claude-sonnet-4    (推荐，性价比高)
    anthropic/claude-opus-4      (最强，但贵)
    openai/gpt-4o                (均衡)
    google/gemini-pro-1.5        (长上下文)
    meta/llama-3-70b-instruct    (开源便宜)

新手选 anthropic/claude-sonnet-4——智能足够，价格友好（约 0.003 美元/千 token，够你聊很多了）。

第四问：选择执行后端

? Choose terminal backend:
  > local      (本地，最快、最方便，新手必选)
    docker     (隔离沙箱，安全但需要 Docker)
    ssh        (远程服务器执行，进阶用)

新手选 local——直接在你本地电脑上执行命令，最简单。等你熟悉之后，第十章会教你怎么改成 docker 沙箱模式更安全。

第五问：是否启用记忆系统

? Enable persistent memory?  (Y/n)

直接按回车（默认 Y）。这是 Hermes 区别于 ChatGPT 的核心特性，必须打开。

完成

向导结束后会提示：

✓ Setup complete!
✓ Your config is saved to ~/.hermes/config.yaml
✓ Run `hermes` to start chatting.

健康检查

为了确认一切就绪，运行：

hermes doctor

你会看到一份体检报告：

Hermes Agent Health Check
─────────────────────────
✓ Configuration valid
✓ API key present (OpenRouter)
✓ API connectivity OK (latency: 142ms)
✓ Memory system initialized
✓ Terminal backend (local) reachable
✓ Skills directory writable (~/.hermes/skills)
─────────────────────────
All checks passed.

每一项都是绿色 ✓，就 OK 了。如果有红色 ✗，照着提示修。

四、第一个任务：让它整理你的下载文件夹

万事俱备。打开终端，输入：

hermes

你会看到欢迎界面，光标在 >>> 后面闪烁。这就是 Hermes 的交互模式。

我们直接给它布置第一个任务。复制下面这段，粘贴进去（一段提示词可以跨行，按回车提交）：

你好 Hermes，我们第一次合作。请帮我做一件事：

1. 看一下我的 ~/Downloads 文件夹，按文件类型分一下类：
   - 图片（jpg/png/gif/webp/heic）放到 Downloads/图片/
   - 视频（mp4/mov/mkv）放到 Downloads/视频/
   - 文档（pdf/docx/xlsx/pptx/md/txt）放到 Downloads/文档/
   - 压缩包（zip/rar/7z/tar.gz）放到 Downloads/压缩包/
   - 安装包（dmg/pkg/exe/msi/deb）放到 Downloads/安装包/
   - 其他归到 Downloads/其他/

2. 在真正动手前，先告诉我你打算移动多少个文件、各类多少个，等我说"OK"再执行。

3. 不要动以下文件夹：任何已经存在的子文件夹都不要进去。

4. 完成后告诉我"实际移动了多少、跳过了多少、用了多少时间"。

按回车，看看 Hermes 的反应。它大概会这样工作（中间过程都是它自动做的，你能看见）：

[Hermes] 收到。我先扫描一下 ~/Downloads 看看有什么。
[tool: file.list_directory(path="~/Downloads")]
[Hermes] 我看到 47 个文件。让我按类型统计一下：

  类型     数量    总大小
  ────    ────   ────────
  图片      18    142 MB
  视频       3    1.2 GB
  文档      14    78 MB
  压缩包     4    324 MB
  安装包     5    1.5 GB
  其他       3    2 MB

  打算建 6 个新子文件夹并移动这 47 个文件，约 3.3 GB 数据。

  请回复 "OK" 我就开始执行。

你输入 OK 回车，它会真的去做：

[Hermes] 开始执行……
[tool: file.create_directory(...)] ✓
[tool: file.move(...)] ✓
... (47 行)

完成。
  实际移动：47 个文件
  跳过：0 个
  用时：4.2 秒

下次遇到"整理 Downloads"这类任务，我已经把这个流程保存为
Skill: organize-downloads-by-type，可以一键复用。

最后那句话是关键。 Hermes 在做完之后自动写了一份 Skill，下次你只要说"再整理一下下载夹"，它会直接用这个 Skill，不再问你怎么分类。

这就是 Hermes 区别于 ChatGPT 的"会成长"特性的第一次显现。

五、几个让你立刻爽起来的小命令

在 Hermes 交互模式里，输入下面这些斜杠命令试试：

下次重新进入 Hermes，输入：

hermes --continue

它会接着上次的对话继续——这是它的"会议纪要"能力，对长任务特别有用。

六、5 大常见报错与对照解法

报错 1：command not found: hermes

原因：装完没重新打开终端，PATH 没更新。

解法：

# 手动加载一次
source ~/.bashrc      # 如果你用 bash
source ~/.zshrc       # 如果你用 zsh

# 仍然不行？手动加一行到配置文件
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

报错 2：Could not connect to api.openrouter.ai 或 timeout

原因：国内网络访问 OpenRouter 不稳定。

解法：

• 如果有代理，开全局代理后再试；
• 或者切换到国内可用的模型，参考 第三章 的 Kimi/DeepSeek 方案；
• 或者用 Ollama 本地模型，零网络依赖。

报错 3：API key not found / 401 Unauthorized

原因：Key 没填或者填错了（多了空格、引号等）。

解法：

# 看一下 Key 是否真的在里面
hermes config get OPENROUTER_API_KEY

# 如果是空的或者错的，重新设置
hermes config set OPENROUTER_API_KEY sk-or-v1-你的真实key

或者直接编辑 ~/.hermes/.env 文件，注意 Key 两边不要加引号：

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxx

报错 4：Permission denied 当 Hermes 想动你的文件

原因：Hermes 没有权限访问那个目录。

解法：

• 如果是 macOS，第一次访问 ~/Downloads、~/Documents 时系统会弹"是否允许"，点"允许"；
• 如果是 Linux，检查文件权限：ls -la ~/Downloads，必要时 chmod -R u+rw ~/Downloads；
• 如果你执意不想给某些目录权限，在 ~/.hermes/config.yaml 的 tools.file.deny_paths 里加上即可。

报错 5：Memory database locked 或 state.db corrupted

原因：上次 Hermes 没正常退出，数据库锁住了。

解法：

# 1) 强制结束所有 hermes 进程
pkill -f hermes

# 2) 清掉锁文件
rm -f ~/.hermes/state.db-shm ~/.hermes/state.db-wal

# 3) 如果 state.db 也坏了，先备份再重建
cp ~/.hermes/state.db ~/.hermes/state.db.bak
hermes memory rebuild

本章一图回顾

┌─────────────────────────────────────────────────┐
│   1. 装 Python 3.10+                             │
│             ↓                                   │
│   2. curl ... install.sh | bash                 │
│             ↓                                   │
│   3. hermes setup       ← 跟着 5 个问题走        │
│             ↓                                   │
│   4. hermes doctor      ← 体检全 ✓              │
│             ↓                                   │
│   5. hermes             ← 开始聊                │
│             ↓                                   │
│   6. 第一个任务：整理下载文件夹                 │
│             ↓                                   │
│   7. 看 Hermes 自动学到一个 Skill               │
└─────────────────────────────────────────────────┘

下章预告

你已经成功跑起 Hermes 了，但你用的可能是 OpenRouter 的默认模型。 第三章 给它配一颗大脑 会告诉你：

• 200+ 个模型怎么选
• 国内用户的零门槛方案（Kimi + DeepSeek）
• 全本地隐私方案（Ollama）
• 省钱组合：把月费从 200 元压到 50 元的具体配置
• 怎么设预算上限，避免"月底一看 API 账单脸都绿了"

如果你想先看看怎么和 Hermes 写更好的提示词，可以跳到 第四章。