适合人群
- 想搭建一个 24 小时在线的 AI 助手的开发者
- 对 Hermes Agent 感兴趣但不知道从何入手的新手
- 使用 Windows / macOS / Linux 的用户（Windows 需先装 WSL2）
- 想把 AI Agent 接入 Discord、Telegram 等平台的技术爱好者
准备清单
- 一台能联网的电脑（Windows / macOS / Linux 均可）
- Python 3.11+ 环境（
python --version确认） - Git 已安装（
git --version确认） - 一个支持 64K 以上上下文的 AI 模型 API Key（OpenAI、Anthropic、通义千问等）
安装流程概览
准备环境 → 拉取项目 → 启动并配置
整个安装过程分为三个阶段，Linux/macOS 用户可以用一键脚本搞定，Windows 用户需要先装 WSL2。
一、Linux / macOS 安装
方式一：一键安装（推荐）
执行一条命令，脚本会自动完成所有依赖配置、虚拟环境创建，并将 hermes 命令链接到系统路径：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
方式二：手动安装
如果一键安装遇到问题，可以按以下步骤手动操作。
第一步：克隆仓库
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
⚠️ 必须加上
--recurse-submodules，否则子模块无法正确拉取，后续步骤会失败。如果已经克隆但忘记加这个参数，可以用以下命令补救：
git submodule update --init --recursive
第二步：安装 uv 并创建虚拟环境
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11
第三步：安装依赖
export VIRTUAL_ENV="$(pwd)/venv"
安装全部功能（含 Discord / Telegram / cron 支持）：
uv pip install -e ".[all]"
或仅安装核心功能：
uv pip install -e "."
第四步：启动 Hermes
./hermes
启动成功后会显示欢迎界面，包含当前模型、可用工具和技能列表。
二、Windows 用户：先装 WSL2
⚠️ Hermes Agent 不支持原生 Windows，必须先安装 WSL2，再在 WSL2 终端内执行上述 Linux 安装步骤。
第一步：以管理员身份打开终端
按 Win + X，选择「终端管理员」。
第二步：安装 WSL2
wsl --install
第三步：进入 WSL
wsl
首次进入时会提示创建 Unix 用户名和密码。
💡 输入密码时屏幕不会有任何显示，盲打完成后按回车确认即可。
验证成功标志：终端出现绿蓝相间的提示符（格式为
用户名@主机名:路径$），即说明已成功进入 WSL2 环境。
第四步：在 WSL2 中运行一键安装命令
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
💡 macOS 用户无需以上操作，直接执行一键安装命令即可。
三、启动后配置
启动 Hermes 后会进入模型与服务商选择阶段：
- 国外模型：OpenAI GPT-4、Anthropic Claude 等
- 国内/灵活方案：通义千问等
⚠️ 所选模型必须支持至少 64K context。主流托管模型均满足此要求；若使用本地模型，需手动将 context size 设置为 64K 以上。
选择完成后记得保存配置。
四、接入 Discord
如果你想接入 Discord，需完成以下步骤。
第一步：创建 Discord Bot
进入 Discord Developer Portal，创建新的 Application，再进入 Bot 页面创建机器人。
第二步：打开关键权限
在 Bot → Privileged Gateway Intents 里打开：
- Server Members Intent
- Message Content Intent（最重要，不开则 bot 读不到消息内容）
第三步：复制 Bot Token
在 Bot 页面生成并复制 token。
⚠️ 不要把 token 暴露在公开仓库、文档或聊天群里。一旦泄露，直接重置。
第四步：把 Bot 拉进服务器
进入 OAuth2 → URL Generator，生成邀请链接，将 bot 加入你的服务器。
第五步：获取你的 User ID
- 打开 Discord
- 进入 Settings → Advanced，打开 Developer Mode
- 右键你的用户名，点击 Copy User ID
第六步：在 Hermes 中配置 Discord
方式一：交互式配置
hermes gateway setup
选择 Discord，按提示填写 bot token 和 User ID。
方式二：手动写入配置文件 ~/.hermes/.env
DISCORD_BOT_TOKEN=你的bot_token
DISCORD_ALLOWED_USERS=你的discord_user_id
启动 gateway：
hermes gateway
启动成功后，bot 会在 Discord 中显示在线，可以私信、@或在频道中直接对话。
五、两个关键配置建议
1. Max Iterations（建议设为 90）
能给 agent 留出足够的执行空间，避免复杂任务因轮数限制被截断。
2. Session Reset Mode（建议设为 Never auto-reset）
保留上下文比频繁重置更合理，Hermes 本身依赖连续会话、记忆沉淀和经验复用。
更多高级配置可以参考 Hermes Agent 进阶指南。
常见问题
Q: Windows 用户能直接运行吗？ A: 不能。Hermes Agent 不支持原生 Windows，必须先安装 WSL2，在 WSL2 环境中运行。
Q: clone 时忘记加 --recurse-submodules 怎么办？
A: 执行 git submodule update --init --recursive 即可补救。
Q: Discord Bot 在线但不回复消息？ A: 大概率是没有打开 Message Content Intent。去 Discord Developer Portal → Bot → Privileged Gateway Intents 里检查。
Q: 提示 User not allowed？
A: 你的 Discord 用户 ID 没有正确写进 DISCORD_ALLOWED_USERS 环境变量。
Q: Bot 一直离线？
A: 检查 hermes gateway 是否启动成功，以及 DISCORD_BOT_TOKEN 是否填写错误或已失效。
Q: 推荐用什么模型？ A: Claude Sonnet/Opus 效果最好，通义千问（Qwen）是国内最灵活的选择。模型需支持 64K 以上上下文。
参考来源
下一步建议
- 安装完成后，查看 Hermes Agent 完全入门指南 了解基础用法
- 想深入定制？看 Hermes Agent 进阶指南
- 对 AI Agent 感兴趣？参考 AI Agent 框架对比指南 了解更多选择