第3章初始配置向导

墨鱼说：🦑 "装好了 Hermes 却不知道怎么张嘴说话？别急，跟着配置向导走一遍，让墨鱼真正'活'起来！"

1. hermes setup — 一键配置向导 🧙

安装好 Hermes Agent 后，第一件事就是运行交互式配置向导：

bash

hermes setup

向导会一步一步引导你完成所有核心配置。整个过程大约 2-3 分钟。

向导配置步骤

步骤	配置项	说明
1	选择 LLM 提供商	选择你要使用的 AI 模型服务商
2	输入 API Key	填入你从服务商获取的密钥
3	选择默认模型	从该服务商的可用模型中选择
4	配置工具权限	选择 Agent 可以使用哪些工具
5	确认并保存	预览配置，确认后写入 `~/.hermes/.env`

TIP

你也可以随时重新运行 hermes setup 来修改配置。向导会自动检测现有配置，并预填你的当前值，无需从头开始。

2. 选择 LLM 提供商 🏪

这是向导中最关键的一步——选择谁来做墨鱼的大脑。Hermes Agent 支持多家 LLM 提供商，各有特色：

提供商对比

提供商	Provider 标识	特点	免费额度	国内直连	推荐指数
Nous Portal	`nous`	官方默认，开箱即用	✅ 有免费额度	❌ 需代理	⭐⭐⭐⭐
GLM (智谱)	`glm`	国产大模型，中文能力强	✅ 有免费额度	✅ 直连	⭐⭐⭐⭐⭐
OpenRouter	`openrouter`	聚合 200+ 模型，灵活切换	✅ 部分模型免费	❌ 需代理	⭐⭐⭐⭐⭐
Kimi (月之暗面)	`kimi`	长上下文，中文理解出色	✅ 有免费额度	✅ 直连	⭐⭐⭐⭐
MiniMax	`minimax`	国产，语音能力强	✅ 有免费额度	✅ 直连	⭐⭐⭐
OpenAI	`openai`	GPT 系列，能力全面	❌ 需付费	❌ 需代理	⭐⭐⭐⭐
Anthropic	`anthropic`	Claude 系列，擅长写作推理	❌ 需付费	❌ 需代理	⭐⭐⭐⭐

如何选择？

你是国内用户，希望开箱即用？
  └─→ 选 GLM 或 Kimi（国内直连，免费额度充足）

你想要最丰富的模型选择？
  └─→ 选 OpenRouter（200+ 模型随你挑）

你想体验官方推荐的默认配置？
  └─→ 选 Nous Portal（免费额度，开箱即用）

你预算充足，追求最强能力？
  └─→ 选 OpenAI 或 Anthropic

3. 获取 API Key 🔑

选好提供商后，你需要一个 API Key（密钥）来让 Hermes 与 LLM 服务通信。下面以国内用户最常用的两个提供商为例，手把手教你获取。

3.1 获取 GLM (智谱) API Key

步骤：

打开智谱开放平台：https://open.bigmodel.cn
点击右上角「注册/登录」，完成账号注册
登录后进入控制台，点击左侧菜单「API Keys」
点击「创建 API Key」，系统会生成一个新的密钥
复制显示的 API Key（格式类似 xxxxxx.xxxxxx）

WARNING

API Key 创建后只会完整显示一次！请务必立即复制并妥善保存。如果忘记了，只能删除重新创建。

配置示例：

bash

# 在 ~/.hermes/.env 中（或通过 hermes setup 自动填入）
LLM_PROVIDER=glm
GLM_API_KEY=你的API密钥
LLM_MODEL=glm-4-flash

3.2 获取 OpenRouter API Key

步骤：

打开 OpenRouter：https://openrouter.ai
点击右上角「Sign In」，使用 Google 或 GitHub 账号登录
登录后点击左侧菜单「Keys」
点击「Create Key」，输入一个名称（如 hermes-agent）
复制生成的 API Key（格式类似 sk-or-v1-xxxxx）

TIP

OpenRouter 提供部分免费模型（如 Llama 系列），无需充值即可体验。付费模型需要先充值 Credits。

配置示例：

bash

# 在 ~/.hermes/.env 中（或通过 hermes setup 自动填入）
LLM_PROVIDER=openrouter
OPENROUTER_API_KEY=你的API密钥
LLM_MODEL=meta-llama/llama-3.1-70b-instruct

3.3 其他提供商速查

提供商	注册地址	API Key 前缀
Nous Portal	portal.nousresearch.com	`nous-`
Kimi (月之暗面)	platform.moonshot.cn	`sk-`
MiniMax	api.minimax.chat	自定义
OpenAI	platform.openai.com	`sk-`
Anthropic	console.anthropic.com	`sk-ant-`

4. hermes model — 切换模型 🔄

配置完成后，你可能想随时切换模型或提供商。不需要重新运行 hermes setup，用 hermes model 命令即可：

查看当前模型

bash

hermes model

输出示例：

当前配置：
  提供商: glm
  模型:   glm-4-flash

列出可用模型

bash

# 列出当前提供商的所有可用模型
hermes model list

# 列出指定提供商的模型
hermes model list --provider openrouter

切换提供商和模型

bash

# 切换到 GLM 提供商
hermes model set --provider glm

# 切换到指定模型
hermes model set --model glm-4-plus

# 一步到位：同时切换提供商和模型
hermes model set --provider openrouter --model meta-llama/llama-3.1-70b-instruct

常用模型推荐

GLM 系列：

模型名称	特点	适用场景
`glm-4-flash`	快速、免费额度多	日常对话、快速问答
`glm-4-plus`	能力更强、推理更好	复杂任务、代码生成
`glm-4-long`	超长上下文	长文档处理

OpenRouter 热门模型：

模型名称	特点	费用
`meta-llama/llama-3.1-70b-instruct`	开源标杆，综合能力强	免费
`google/gemini-2.0-flash-exp`	Google 最新模型	免费
`anthropic/claude-3.5-sonnet`	写作和推理出色	付费
`openai/gpt-4o`	OpenAI 旗舰模型	付费

5. hermes tools — 配置工具 🛠️

Hermes Agent 之所以强大，是因为它可以调用各种工具来完成任务。使用 hermes tools 命令管理工具权限：

查看工具状态

bash

hermes tools list

输出示例：

工具列表：
  ✅ terminal    终端命令执行（已启用）
  ✅ file        文件读写操作（已启用）
  ✅ browser     浏览器访问（已启用）
  ❌ search      网络搜索（未启用）
  ✅ patch       文件编辑（已启用）

启用/禁用工具

bash

# 启用单个工具
hermes tools enable search

# 禁用单个工具
hermes tools disable browser

# 批量启用
hermes tools enable terminal file patch

工具说明

工具	标识	功能	安全说明
终端	`terminal`	执行 shell 命令	⚠️ 可执行任意命令，注意权限
文件	`file`	读取和搜索文件	✅ 只读操作，安全
编辑	`patch`	查找替换编辑文件	⚠️ 会修改文件内容
浏览器	`browser`	访问网页、抓取内容	✅ 只读操作，安全
搜索	`search`	搜索文件内容和名称	✅ 只读操作，安全

安全提示

terminal 工具允许 Agent 执行任意 shell 命令，包括删除文件等危险操作。在不确定的环境下，可以先禁用此工具：

bash

hermes tools disable terminal

等你信任 Agent 的行为后，再按需启用。

6. 配置文件结构 📁

Hermes Agent 的配置文件存放在 ~/.hermes/ 目录下。了解这些文件，能帮你更好地管理和排查问题。

目录结构

~/.hermes/
├── .env              # 核心配置（环境变量）
├── config.yaml       # 高级配置（可选）
├── history/          # 对话历史记录
└── plugins/          # 插件目录

.env 文件详解

.env 文件是 Hermes 的核心配置，采用 KEY=VALUE 格式：

bash

# ===== LLM 配置 =====
LLM_PROVIDER=glm              # 当前提供商
LLM_MODEL=glm-4-flash         # 当前模型
LLM_API_KEY=                   # 通用 API Key（部分提供商使用）

# ===== 提供商专属 Key =====
GLM_API_KEY=your-glm-key            # 智谱 API Key
OPENROUTER_API_KEY=your-router-key  # OpenRouter API Key
OPENAI_API_KEY=your-openai-key      # OpenAI API Key
ANTHROPIC_API_KEY=your-anthropic-key # Anthropic API Key
NOUS_API_KEY=your-nous-key          # Nous Portal API Key
KIMI_API_KEY=your-kimi-key          # Kimi API Key
MINIMAX_API_KEY=your-minimax-key    # MiniMax API Key

# ===== 工具配置 =====
TOOLS_TERMINAL=true           # 是否启用终端工具
TOOLS_FILE=true               # 是否启用文件工具
TOOLS_PATCH=true              # 是否启用编辑工具
TOOLS_BROWSER=true            # 是否启用浏览器工具
TOOLS_SEARCH=true             # 是否启用搜索工具

config.yaml（高级配置）

config.yaml 用于更细致的行为调优，一般情况下你不需要手动编辑它：

yaml

# ~/.hermes/config.yaml 示例
agent:
  max_turns: 30               # 单次任务最大执行轮次
  timeout: 300                # 超时时间（秒）

llm:
  temperature: 0.7            # 生成温度（0-1，越高越随机）
  max_tokens: 4096            # 单次回复最大 token 数

logging:
  level: info                 # 日志级别: debug, info, warning, error
  file: ~/.hermes/hermes.log  # 日志文件路径

墨鱼小贴士 🦑

大多数情况下，hermes setup 和 hermes model/hermes tools 命令已经能完成所有配置。只有当你需要微调 Agent 行为时，才需要手动编辑这些文件。

手动编辑配置文件

如果你想直接编辑 .env 文件：

bash

# 使用你喜欢的编辑器打开
nano ~/.hermes/.env
# 或
vim ~/.hermes/.env
# 或
code ~/.hermes/.env

修改保存后，Hermes 会自动加载新配置，无需重启。

7. hermes doctor — 健康检查 🩺

配置完成后，强烈建议运行一次健康检查，确认一切正常：

bash

hermes doctor

doctor 检查哪些项目？

检查项	说明	通过条件
🐍 Python 环境	Python 版本和虚拟环境	Python >= 3.10
📁 配置目录	`~/.hermes/` 目录是否存在	目录存在且可读写
🔑 API Key	是否已配置有效的 API Key	Key 不为空且格式正确
🌐 网络连通	能否访问 LLM 服务端点	HTTP 请求返回正常
🤖 模型可用	能否成功调用指定模型	API 调用无报错
🛠️ 工具状态	已启用的工具是否正常	依赖项齐全
📦 依赖完整性	所需 Python 包是否安装	所有包版本匹配

正常输出示例

🩺 Hermes Agent 健康检查

✅ Python 环境     — Python 3.12.0 (venv)
✅ 配置目录        — ~/.hermes/ 存在且可读写
✅ API Key         — GLM_API_KEY 已配置
✅ 网络连通        — 成功连接 open.bigmodel.cn
✅ 模型可用        — glm-4-flash 调用正常
✅ 工具状态        — 4/5 已启用, 全部正常
✅ 依赖完整性      — 所有依赖已安装

🎉 一切正常！墨鱼已准备就绪。

遇到问题怎么办？

如果某项检查显示 ❌，hermes doctor 会给出具体的修复建议。常见问题：

❌ API Key — 未配置
   建议: 运行 hermes setup 或手动编辑 ~/.hermes/.env

❌ 网络连通 — 无法连接 open.bigmodel.cn
   建议: 检查网络连接，国内用户无需代理即可访问智谱服务

❌ 模型可用 — API 返回 401 Unauthorized
   建议: API Key 无效或已过期，请重新获取

8. 快速测试：第一次对话 💬

所有配置完成后，是时候和墨鱼聊上几句了！

启动 Hermes

bash

hermes

你会看到欢迎界面：

🦑 Hermes Agent v0.x.x
   提供商: glm | 模型: glm-4-flash
   工具: terminal, file, patch, browser, search

>

试试这些问题

> 你好，墨鱼！请介绍一下你自己

> 帮我看看当前系统信息

> 列出当前目录下的文件

> 用 Python 写一个快速排序算法

墨鱼小贴士 🦑

第一次对话可能稍慢（模型冷启动），后续会快很多。如果长时间无响应，按 Ctrl+C 取消，然后运行 hermes doctor 检查网络。

常用交互命令

命令	说明
`/help`	查看帮助
`/model`	查看当前模型
`/tools`	查看工具状态
`/clear`	清空对话历史
`/exit` 或 `Ctrl+C`	退出 Hermes

小结

本章我们完成了 Hermes Agent 的核心配置，让墨鱼真正"活"了起来：

hermes setup — 交互式向导，一步一步完成初始配置
选择 LLM 提供商 — 根据场景选择合适的 AI 大脑
获取 API Key — GLM 和 OpenRouter 的详细注册流程
hermes model — 随时切换提供商和模型
hermes tools — 灵活管理工具权限
配置文件 — 了解 ~/.hermes/.env 和 config.yaml 的结构
hermes doctor — 一键检查所有配置是否正确
第一次对话 — 和墨鱼打个招呼，验证一切正常

墨鱼 🦑 已经有了大脑、有了工具、有了记忆。接下来，让我们把它接入你的聊天平台！

👉 下一章：第4章聊天平台接入

第3章 初始配置向导 ​

1. hermes setup — 一键配置向导 🧙 ​

向导配置步骤 ​

2. 选择 LLM 提供商 🏪 ​

提供商对比 ​

如何选择？ ​

3. 获取 API Key 🔑 ​

3.1 获取 GLM (智谱) API Key ​

3.2 获取 OpenRouter API Key ​

3.3 其他提供商速查 ​

4. hermes model — 切换模型 🔄 ​

查看当前模型 ​

列出可用模型 ​

切换提供商和模型 ​

常用模型推荐 ​

5. hermes tools — 配置工具 🛠️ ​

查看工具状态 ​

启用/禁用工具 ​

工具说明 ​

6. 配置文件结构 📁 ​

目录结构 ​

.env 文件详解 ​

config.yaml（高级配置） ​

手动编辑配置文件 ​

7. hermes doctor — 健康检查 🩺 ​

doctor 检查哪些项目？ ​

正常输出示例 ​

遇到问题怎么办？ ​

8. 快速测试：第一次对话 💬 ​

启动 Hermes ​

试试这些问题 ​

常用交互命令 ​

小结 ​

第3章初始配置向导

1. hermes setup — 一键配置向导 🧙

向导配置步骤

2. 选择 LLM 提供商 🏪

提供商对比

如何选择？

3. 获取 API Key 🔑

3.1 获取 GLM (智谱) API Key

3.2 获取 OpenRouter API Key

3.3 其他提供商速查

4. hermes model — 切换模型 🔄

查看当前模型

列出可用模型

切换提供商和模型

常用模型推荐

5. hermes tools — 配置工具 🛠️

查看工具状态

启用/禁用工具

工具说明

6. 配置文件结构 📁

目录结构

.env 文件详解

config.yaml（高级配置）

手动编辑配置文件

7. hermes doctor — 健康检查 🩺

doctor 检查哪些项目？

正常输出示例

遇到问题怎么办？

8. 快速测试：第一次对话 💬

启动 Hermes

试试这些问题

常用交互命令

小结