常见问题 (FAQ)

基本使用

如何切换模型？

运行 hermes model 命令，会弹出交互式列表，显示所有可用模型（按提供商分组）。选择后即保存为默认模型。

也可以在启动时通过 -m 选项临时指定模型：

bash

hermes -m gpt-4o
hermes -m claude-3-5-sonnet-20241022

或直接在配置文件中设置：

bash

hermes config set model claude-3-5-sonnet-20241022

如何检查安装是否正常？

运行诊断命令：

bash

hermes doctor

如需自动修复发现的问题：

bash

hermes doctor --fix

hermes doctor 会检查：

Python 版本兼容性
依赖包完整性
API 密钥配置
网络连通性
配置文件格式

支持哪些操作系统？

平台	支持状态
Linux	完全支持
macOS	完全支持
WSL2（Windows Subsystem for Linux）	支持（推荐方式）
Windows 原生（CMD / PowerShell）	不支持

如果你使用 Windows，请安装 WSL2（Ubuntu 22.04 或更高版本），然后在 WSL2 终端内安装和使用 Hermes。

如何添加 API 密钥？

编辑 ~/.hermes/.env 文件：

bash

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

添加对应提供商的密钥：

bash

ANTHROPIC_API_KEY=sk-ant-xxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxx
GEMINI_API_KEY=xxxxxxxx

保存后重启 Hermes 即可生效。也可以通过 hermes setup 向导交互式配置。

终端后端

应该用 Docker 后端还是本地后端？

对比项	本地后端	Docker 后端
配置复杂度	简单，开箱即用	需要安装 Docker
隔离性	无隔离，命令直接在主机执行	完全隔离，不影响主机环境
安全性	较低（工具可访问所有文件）	较高（沙箱环境）
性能	快（无容器启动开销）	稍慢（首次启动需拉取镜像）
适合场景	个人开发、受信任环境	生产环境、多用户、不可信代码执行

建议：

个人日常使用：选 local（默认）
执行不可信代码或需要隔离：选 docker
远程服务器：选 ssh

切换后端：

bash

hermes config set terminal.backend docker

记忆系统

记忆内容为什么没有立即更新？

Hermes 的记忆系统在会话结束后才会将新记忆写入存储。因此：

当前会话中新产生的记忆，下次启动时才会注入到上下文
如果需要立即使用某段信息，直接在当前对话中提及即可

查看已存储的记忆：

bash

hermes memory

会话管理

如何重置/清除会话？

删除当前会话（或所有会话）：

bash

# 删除指定会话
hermes sessions delete <会话ID>

# 交互式浏览并删除
hermes sessions browse

# 清理旧会话（保留最近 20 个）
hermes sessions prune --keep 20

如何导出会话或配置数据？

导出会话记录：

bash

# 导出为 Markdown 格式
hermes sessions export <会话ID> --format markdown > session.md

# 导出为 JSON 格式
hermes sessions export <会话ID> --format json > session.json

导出配置文件（Profile）：

bash

hermes profile export <配置名称> > my-profile.yaml

备份所有数据：

整个 ~/.hermes/ 目录包含所有配置、会话历史和记忆数据，直接打包即可备份：

bash

tar -czf hermes-backup.tar.gz ~/.hermes/

网关与消息平台

网关会触发速率限制吗？

Hermes 网关本身不设置速率限制，但上游 AI 提供商（如 Anthropic、OpenAI）有各自的 API 速率限制。

如果遇到限流错误（429），可以：

在 .env 中配置备用 API 密钥轮换
适当增加消息间隔
使用 hermes cron 将批量任务分散到不同时间执行

模型与提供商

支持 Ollama / 本地模型吗？

是的，Hermes 支持通过 Ollama 运行本地模型。

确保 Ollama 已安装并运行：
bash
```
ollama serve
ollama pull llama3.2
```
在 .env 中配置：
bash
```
OLLAMA_BASE_URL=http://localhost:11434
```
启动时指定 Ollama 提供商和模型：
bash
```
hermes --provider ollama -m llama3.2
```

或通过 hermes model 在模型列表中选择 Ollama 下的本地模型。

支持哪些 AI 提供商？

Hermes 支持以下主流提供商（通过 .env 配置对应的 API 密钥即可启用）：

Anthropic（Claude 系列）
OpenAI（GPT-4o、o1 系列）
Google（Gemini 系列）
Mistral
Groq（超快速推理）
Ollama（本地模型）
OpenRouter（聚合多家提供商）
Together AI
Perplexity
以及更多兼容 OpenAI API 格式的提供商

故障排查

Hermes 启动后没有响应怎么办？

检查 API 密钥是否正确配置：hermes doctor
测试网络连接是否正常
查看日志文件：~/.hermes/logs/hermes.log
尝试以详细模式启动：hermes -v

工具调用一直失败怎么办？

bash

# 检查工具列表是否正常加载
hermes tools

# 查看具体错误信息
hermes -v

# 重置为本地终端后端（排除 Docker 问题）
hermes config set terminal.backend local

如何完全重置 Hermes 到初始状态？

bash

# 先备份数据
cp -r ~/.hermes/ ~/.hermes-backup/

# 删除所有配置和数据
rm -rf ~/.hermes/

# 重新运行初始化向导
hermes setup

常见问题 (FAQ) ​

基本使用 ​

如何切换模型？ ​

如何检查安装是否正常？ ​

支持哪些操作系统？ ​

如何添加 API 密钥？ ​

终端后端 ​

应该用 Docker 后端还是本地后端？ ​

记忆系统 ​

记忆内容为什么没有立即更新？ ​

会话管理 ​

如何重置/清除会话？ ​

如何导出会话或配置数据？ ​

网关与消息平台 ​

网关会触发速率限制吗？ ​

模型与提供商 ​

支持 Ollama / 本地模型吗？ ​

支持哪些 AI 提供商？ ​

故障排查 ​

Hermes 启动后没有响应怎么办？ ​

工具调用一直失败怎么办？ ​

如何完全重置 Hermes 到初始状态？ ​

更多帮助 ​

常见问题 (FAQ)

基本使用

如何切换模型？

如何检查安装是否正常？

支持哪些操作系统？

如何添加 API 密钥？

终端后端

应该用 Docker 后端还是本地后端？

记忆系统

记忆内容为什么没有立即更新？

会话管理

如何重置/清除会话？

如何导出会话或配置数据？

网关与消息平台

网关会触发速率限制吗？

模型与提供商

支持 Ollama / 本地模型吗？

支持哪些 AI 提供商？

故障排查

Hermes 启动后没有响应怎么办？

工具调用一直失败怎么办？

如何完全重置 Hermes 到初始状态？

更多帮助