常见问题
安装、配置、迁移、升级过程中遇到的高频问题速查，帮你快速排除。
安装与启动
当前推荐 Windows 用户使用 WSL2 运行 Hermes，这是最稳定的方案。如果你有 Termux/Android 设备，也可以直接安装。直装 Windows 版本可能遇到工具依赖缺失的问题，我们的教程以 WSL2 和 Termux 为主。
某些终端输入法可能与交互式向导不兼容。你可以按 Ctrl+C 退出后，手动编辑 ~/.hermes/config.yaml 创建初始配置，然后 Day 2 再补充 API key。
可能会。建议将 Termux 设为无限制电池策略，并在运行 gateway 时执行 termux-wake-lock。
模型与 API
Hermes 支持多种模型提供商，你可以使用 Anthropic Claude、阿里通义千问、智谱 AI 等国产模型。只需在 config.yaml 中更换对应的 base_url 和 api_key。推荐使用 hermes model 交互式向导配置，或直接编辑 ~/.hermes/.env。
可能是 key 格式不兼容或 base_url 丢失。运行 hermes model 查看已配置的 provider，并手动检查 ~/.hermes/config.yaml 补全 base_url。
表示遇到速率限制，建议换 provider 或在 config.yaml 中设置 fallback_model。
平台与机器人
请检查 webhook 地址是否更新为 Hermes 的服务地址，并确认 BotFather 中的 token 仍然有效。如果是轮询方式，请确保没有其他服务在占用该 token。也可以用 hermes status 查看连接状态。
检查事件订阅里是否已正确勾选“消息”事件，确认 webhook 地址使用 HTTPS，并且服务器能够正常访问飞书的推送服务。
除了 Telegram 和飞书，还支持 Discord、Slack、WhatsApp、Signal、Matrix、Email、Home Assistant、Mattermost、钉钉、企业微信、BlueBubbles、SMS 等。
迁移与升级
手动备份即可：tar -czf ~/hermes-backup.tar.gz -C ~ .hermes/，会备份配置、技能和记忆。
运行 hermes doctor 自动诊断常见问题，或 hermes status 查看当前配置摘要。
三步：1) pip install --upgrade hermes-agent；2) hermes version 确认版本；3) 如配置文件格式有变化，运行 hermes setup 自动迁移。
使用 pip 升级即可：pip install --upgrade hermes-agent。升级后建议重新检查 hermes version 确认版本。