Hermes Agent 深度教程

Appearance

第二章：安装与配置 ​

2.1 安装 (Linux / macOS) ​

对于 macOS 和 Linux 系统，建议使用官方提供的一键脚本安装（确保环境基于 Python 和 Node.js 生态）：

bash
# 新用户，一行装好
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 装完重载一下 shell
source ~/.bashrc   # zsh 用户换成 source ~/.zshrc

# 老用户，直接更新
hermes update

2.2 Windows 安装指南 ​

避坑警告： Windows 用户切勿直接在 CMD 或 PowerShell 中安装，会报大量环境错误。必须通过 WSL2（Windows Subsystem for Linux）安装。

详细步骤：

  1. 开启 WSL2：以管理员身份打开 PowerShell，运行 wsl --install，随后重启电脑。
  2. 初始化 Ubuntu：重启后，WSL 会自动安装 Ubuntu，根据提示设置用户名和密码。
  3. 更新环境与安装：在 Ubuntu 终端中执行：
    bash
    sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl
# 然后运行上方 Linux 的一键安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

2.3 基础配置详解 ​

配置文件统一存储在 ~/.hermes/config.yaml 中，支持手动使用文本编辑器修改。常用的配置管理命令如下：

bash
hermes config              # 查看当前所有配置
hermes config edit         # 用编辑器打开 config.yaml
hermes config set KEY VAL  # 更改某一项（如 hermes config set terminal.backend docker）
hermes doctor --fix        # 检查环境并尝试自动修复问题
hermes setup               # 运行完整的初始配置向导

2.4 接入国内大模型：火山方舟 Coding Plan ​

为了获得更稳定且低延迟的编码体验，我们推荐使用国内的 火山引擎方舟 Coding Plan。Hermes Agent 官方已完全支持该方案。

接入方式分为“自动化助手”与“手动配置”两种。

方式一：使用 Ark Helper 自动化助手（推荐） ​

Ark Helper 是一个专为编码工具设计的终端助手，能帮你快速、无脑地将火山引擎接入 Hermes。 (注：Ark Helper 暂不支持原生 Windows 系统，Windows 用户需在 WSL2 中运行。)

  1. 安装 Ark Helper：
    bash
    curl -fsSL https://lf3-static.bytednsdoc.com/obj/eden-cn/ylwslo-yrh/ljhwZthlaukjlkulzlp/install.sh | sh
  2. 运行配置向导： 在终端输入 ark-helper 启动向导，按界面提示操作：
    • 选择套餐：[Volcano] Volcano Engine (国内) - Coding Plan
    • 配置 API Key：推荐选择 SSO 登录自动获取，省去去控制台复制的麻烦。
    • 选择默认模型（例如 doubao-seed-2.0-pro 等）。
    • 选择编码工具：选择 Hermes Agent。
    • 最后选择 设置 Volcano Coding Plan (API Key) 到 Hermes Agent，完成后退出。

方式二：手动配置 ​

如果你不想安装额外的助手，也可以直接使用 Hermes 自带的配置命令：

  1. 在终端运行配置命令：
    bash
    hermes model
  2. 按照交互式菜单填写以下信息：
    • Select provider：选择 Custom endpoint（enter URL manually）
    • API base URL：填写 https://ark.cn-beijing.volces.com/api/coding/v3
    • API Key：填入你从火山方舟控制台获取的 API Key（注意输入时屏幕不显示字符）。
    • Model name：支持配置特定名称（如 doubao-seed-2.0-pro、deepseek-v4-pro、kimi-k2.6 等），或配置为 ark-code-latest 以便在云端控制台统一切换。
    • Display name：可以随意起名，例如 volcengine-plan

TIP

Base URL 避坑： 如果你使用的是兼容 OpenAI 协议的工具，请务必填写 https://ark.cn-beijing.volces.com/api/coding/v3。切勿误填为 /api/v3，否则不仅不会消耗 Coding Plan 的免费/专属额度，还会产生额外扣费。

2.5 第一次对话 ​

安装和配置完成后，在终端输入 hermes 或 hermes chat 即可开启对话。

进阶启动命令：

bash
hermes --continue         # 恢复上次没聊完的对话（简写 hermes -c）
hermes chat -q "写个爬虫"   # 单次提问，不进入聊天界面
hermes chat --checkpoints # 开启文件系统检查点，改坏了文件可以通过 /rollback 撤销

在会话中，你可以使用 Alt+Enter 进行多行输入（适合粘贴大段代码）。