1. 为什么要在 Windows 上折腾 Hermes Agent如果你最近在找能在本地跑起来的 AI AgentHermes Agent 大概率会出现在候选名单里。它由 Nous Research 团队维护定位不是聊天框而是能自己调用工具、执行任务、记住上下文的智能体。支持 DeepSeek、OpenAI、Claude、GLM、Kimi 等 30 多家模型提供商内置 50 多个工具Web 搜索、文件读写、终端执行、图片生成等还有 660 多个可安装技能。说白了你给它一句话它能自己决定要不要联网搜、要不要写脚本、要不要跑命令。但问题也很现实Hermes Agent 官方主推 Linux 和 macOSWindows 用户直接装会遇到一堆坑。Python 依赖编译失败、路径分隔符不对、终端工具调用异常这些都是我实际踩过的。最稳的路子是用 WSL2 跑一个 Ubuntu把 Hermes 装在 Linux 环境里Windows 只负责开终端和浏览器。这篇教程就按这个思路走从 WSL 安装开始到 Python 虚拟环境、Hermes 安装、配置文件初始化最后用 TaoToken 的统一 API 通道把模型服务接进来跑通第一个 Agent 任务。全程命令可复制配置文件给骨架适合第一次接触 AI Agent 的 Windows 用户。2. 前置准备WSL2、Python 与 TaoToken 统一通道2.1 确认 WSL2 状态并安装 Ubuntu先以管理员身份打开 PowerShell检查 WSL 是否就绪wsl --status如果提示未安装适用于 Linux 的 Windows 子系统直接执行wsl --install -d Ubuntu这条命令会自动启用 WSL 功能、装好 WSL2 内核、从商店拉取 Ubuntu。完成后重启电脑。首次启动 Ubuntu 会让你设置 Linux 用户名和密码这个跟 Windows 登录凭据无关sudo 时要用记牢。装完再确认一次版本必须是 2wsl -l -v看到VERSION列是2就对了。如果是1执行wsl --set-version Ubuntu 2转换。2.2 在 Ubuntu 里准备 Python 环境从开始菜单打开 Ubuntu或者 PowerShell 里敲wsl进入。先更新包管理器并装 pip 和 venvsudo apt update sudo apt upgrade -y sudo apt install python3-pip python3-venv -y python3 --versionUbuntu 22.04 自带 Python 3.10够用。接着建项目目录和虚拟环境mkdir -p ~/hermes-agent cd ~/hermes-agent python3 -m venv venv source venv/bin/activate激活后提示符前面会出现(venv)。每次新开终端都要重新source venv/bin/activate这是新手最容易忘的一步。2.3 为什么用 TaoToken 做统一 API 通道Hermes 支持多提供商但如果你每个模型都去单独申请 Key、单独配 base_url配置文件会变得很乱。TaoToken 提供统一的 Key 和 API 通道一个 Key 就能调用多家模型base_url 统一指向https://taotoken.net/api。这样 Hermes 的 config 里只需要维护一套凭证切换模型时改 model 名就行不用动鉴权部分。对本地 Agent 来说这点很实用Agent 经常要在主模型和辅助模型比如视觉、压缩之间切换统一通道能省掉大量重复配置。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解支持的模型清单然后到控制台创建 Key。3. 可复制配置安装 Hermes 并接入 TaoToken3.1 安装 Hermes Agent确保虚拟环境已激活然后pip install hermes-agent hermes --version正常会输出类似Hermes Agent v0.18.0的版本信息。如果 pip 下载慢可以临时换源pip install hermes-agent -i https://pypi.tuna.tsinghua.edu.cn/simple3.2 初始化配置目录首次运行初始化向导hermes setup向导会问提供商、API Key、终端后端等。这里先随便选一个跳过我们后面直接改配置文件更可控。Hermes 的配置目录在 WSL 里通常是~/.config/hermes/Windows 侧对应\\wsl$\Ubuntu\home\你的用户名\.config\hermes\。3.3 config.toml 骨架在~/.config/hermes/config.toml写入以下内容把YOUR_TAOTOKEN_KEY换成你在控制台创建的 Key[model] default deepseek-chat provider openai-compatible base_url https://taotoken.net/api api_key YOUR_TAOTOKEN_KEY [model.fallback] default glm-4-flash provider openai-compatible base_url https://taotoken.net/api api_key YOUR_TAOTOKEN_KEY [auxiliary.vision] model glm-4v-flash provider openai-compatible base_url https://taotoken.net/api api_key YOUR_TAOTOKEN_KEY [terminal] backend local关键点provider统一写openai-compatible因为 TaoToken 的通道兼容 OpenAI 接口格式base_url只写到/api不要自己加/v1Hermes 会按 SDK 规范拼接。3.4 settings.json 与环境变量有些版本 Hermes 会读settings.json做运行时覆盖。在~/.config/hermes/settings.json放{ model: { default: deepseek-chat, provider: openai-compatible, base_url: https://taotoken.net/api }, terminal: { backend: local, timeout: 120 }, context: { compress: true, max_tokens: 128000 } }Key 不建议写进 json用环境变量更安全。编辑~/.bashrc追加export HERMES_API_KEYYOUR_TAOTOKEN_KEY export OPENAI_API_KEYYOUR_TAOTOKEN_KEY export OPENAI_BASE_URLhttps://taotoken.net/api然后source ~/.bashrc生效。Hermes 会优先读环境变量里的 Key配置文件里可以留空或写占位符。4. 验证请求跑通第一个 Agent 任务4.1 单轮验证模型连通性先做最小验证确认 Key 和通道没问题hermes -z 用一句话说明你当前使用的模型名称如果返回正常文本说明模型通道打通了。如果报 401检查 Key 是否复制完整报 404检查 base_url 是否多写了/v1。4.2 交互模式测试工具调用进入交互模式hermes chat在对话里输入搜索一下 Python 虚拟环境的最佳实践总结三条Agent 应该会自动调用web_search工具返回搜索结果并总结。这一步能验证工具链是否正常。如果工具没触发检查[terminal] backend是否为local。4.3 启动 Dashboard 可视化确认hermes dashboard浏览器访问http://localhost:8787。在 Dashboard 里能看到会话列表、工具调用日志、当前模型。点开刚才的会话确认工具调用记录里有web_search条目说明整条链路跑通了。4.4 一个完整的 Agent 任务试试让它写并执行脚本帮我写一个 Python 脚本统计当前目录下所有 .py 文件的行数然后执行它Hermes 会生成代码、调用终端执行、返回结果。如果报错它还会根据错误信息自动修。这就是 Agent 和普通聊天机器人的区别。5. 本篇常见错误排查5.1 API Key 报错api_key is not configured最常见的原因是环境变量没生效。先确认echo $HERMES_API_KEY如果为空说明~/.bashrc没 source或者你开的是新终端但没重新加载。执行source ~/.bashrc后重试。另一个原因是配置文件里api_key写了占位符但环境变量也没设两者至少要有一个有效。5.2 base_url 拼接错误导致 404TaoToken 的 API 地址是https://taotoken.net/api不要写成https://taotoken.net/api/v1。OpenAI SDK 会自己在后面拼/chat/completions你多写一层/v1就变成/api/v1/chat/completions路径对不上。统一只写到/api。5.3 WSL 里 pip 安装编译失败某些依赖需要编译工具。装一下sudo apt install build-essential python3-dev -y然后再pip install hermes-agent。如果还是失败看报错里缺哪个库用 apt 补上。5.4 Dashboard 端口被占用hermes dashboard默认 8787如果被占用会启动失败。换端口hermes dashboard --port 8899然后访问http://localhost:8899。WSL2 的端口会自动映射到 Windows 的 localhost一般不用额外配置防火墙。5.5 跨文件系统性能问题不要把项目放在/mnt/c/下。WSL 访问 Windows 文件系统有性能损耗而且权限模型不兼容Hermes 的文件工具可能报权限错误。项目放~/hermes-agent/需要从 Windows 访问时用\\wsl$\Ubuntu\home\你的用户名\。6. 后续怎么用从跑通到日常跑通第一个任务后你可以按需扩展。想长期做编码或 Agent 自动化建议了解 Coding Plan它更适合高频调用场景想先对比不同模型的表现可以直接在模型对话里试需要管理多个 Key 或查看用量去控制台接入细节和参数说明看接入文档。几个实用建议主模型选性价比高的比如 deepseek-chat辅助视觉模型单独配一个便宜的开启上下文压缩长对话能省不少 token定期hermes skills list看看有没有新技能可装。Hermes 的记忆系统会跨会话保留偏好用久了确实会越来越顺手。最后提醒一句配置文件里的 Key 别提交到 Git用环境变量管理。WSL 里的~/.bashrc也不要随便分享。把这两点做好本地 Agent 就能稳定跑下去了。 
长河君 · 2026/9/27 14:57:50 · 阅读 1.2k Hermes Agent Windows 端完整安装与使用教程——从零开始部署 AI Agent 并接入 TaoToken 统一 API
1. 为什么要在 Windows 上折腾 Hermes Agent如果你最近在找能在本地跑起来的 AI AgentHermes Agent 大概率会出现在候选名单里。它由 Nous Research 团队维护定位不是聊天框而是能自己调用工具、执行任务、记住上下文的智能体。支持 DeepSeek、OpenAI、Claude、GLM、Kimi 等 30 多家模型提供商内置 50 多个工具Web 搜索、文件读写、终端执行、图片生成等还有 660 多个可安装技能。说白了你给它一句话它能自己决定要不要联网搜、要不要写脚本、要不要跑命令。但问题也很现实Hermes Agent 官方主推 Linux 和 macOSWindows 用户直接装会遇到一堆坑。Python 依赖编译失败、路径分隔符不对、终端工具调用异常这些都是我实际踩过的。最稳的路子是用 WSL2 跑一个 Ubuntu把 Hermes 装在 Linux 环境里Windows 只负责开终端和浏览器。这篇教程就按这个思路走从 WSL 安装开始到 Python 虚拟环境、Hermes 安装、配置文件初始化最后用 TaoToken 的统一 API 通道把模型服务接进来跑通第一个 Agent 任务。全程命令可复制配置文件给骨架适合第一次接触 AI Agent 的 Windows 用户。2. 前置准备WSL2、Python 与 TaoToken 统一通道2.1 确认 WSL2 状态并安装 Ubuntu先以管理员身份打开 PowerShell检查 WSL 是否就绪wsl --status如果提示未安装适用于 Linux 的 Windows 子系统直接执行wsl --install -d Ubuntu这条命令会自动启用 WSL 功能、装好 WSL2 内核、从商店拉取 Ubuntu。完成后重启电脑。首次启动 Ubuntu 会让你设置 Linux 用户名和密码这个跟 Windows 登录凭据无关sudo 时要用记牢。装完再确认一次版本必须是 2wsl -l -v看到VERSION列是2就对了。如果是1执行wsl --set-version Ubuntu 2转换。2.2 在 Ubuntu 里准备 Python 环境从开始菜单打开 Ubuntu或者 PowerShell 里敲wsl进入。先更新包管理器并装 pip 和 venvsudo apt update sudo apt upgrade -y sudo apt install python3-pip python3-venv -y python3 --versionUbuntu 22.04 自带 Python 3.10够用。接着建项目目录和虚拟环境mkdir -p ~/hermes-agent cd ~/hermes-agent python3 -m venv venv source venv/bin/activate激活后提示符前面会出现(venv)。每次新开终端都要重新source venv/bin/activate这是新手最容易忘的一步。2.3 为什么用 TaoToken 做统一 API 通道Hermes 支持多提供商但如果你每个模型都去单独申请 Key、单独配 base_url配置文件会变得很乱。TaoToken 提供统一的 Key 和 API 通道一个 Key 就能调用多家模型base_url 统一指向https://taotoken.net/api。这样 Hermes 的 config 里只需要维护一套凭证切换模型时改 model 名就行不用动鉴权部分。对本地 Agent 来说这点很实用Agent 经常要在主模型和辅助模型比如视觉、压缩之间切换统一通道能省掉大量重复配置。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解支持的模型清单然后到控制台创建 Key。3. 可复制配置安装 Hermes 并接入 TaoToken3.1 安装 Hermes Agent确保虚拟环境已激活然后pip install hermes-agent hermes --version正常会输出类似Hermes Agent v0.18.0的版本信息。如果 pip 下载慢可以临时换源pip install hermes-agent -i https://pypi.tuna.tsinghua.edu.cn/simple3.2 初始化配置目录首次运行初始化向导hermes setup向导会问提供商、API Key、终端后端等。这里先随便选一个跳过我们后面直接改配置文件更可控。Hermes 的配置目录在 WSL 里通常是~/.config/hermes/Windows 侧对应\\wsl$\Ubuntu\home\你的用户名\.config\hermes\。3.3 config.toml 骨架在~/.config/hermes/config.toml写入以下内容把YOUR_TAOTOKEN_KEY换成你在控制台创建的 Key[model] default deepseek-chat provider openai-compatible base_url https://taotoken.net/api api_key YOUR_TAOTOKEN_KEY [model.fallback] default glm-4-flash provider openai-compatible base_url https://taotoken.net/api api_key YOUR_TAOTOKEN_KEY [auxiliary.vision] model glm-4v-flash provider openai-compatible base_url https://taotoken.net/api api_key YOUR_TAOTOKEN_KEY [terminal] backend local关键点provider统一写openai-compatible因为 TaoToken 的通道兼容 OpenAI 接口格式base_url只写到/api不要自己加/v1Hermes 会按 SDK 规范拼接。3.4 settings.json 与环境变量有些版本 Hermes 会读settings.json做运行时覆盖。在~/.config/hermes/settings.json放{ model: { default: deepseek-chat, provider: openai-compatible, base_url: https://taotoken.net/api }, terminal: { backend: local, timeout: 120 }, context: { compress: true, max_tokens: 128000 } }Key 不建议写进 json用环境变量更安全。编辑~/.bashrc追加export HERMES_API_KEYYOUR_TAOTOKEN_KEY export OPENAI_API_KEYYOUR_TAOTOKEN_KEY export OPENAI_BASE_URLhttps://taotoken.net/api然后source ~/.bashrc生效。Hermes 会优先读环境变量里的 Key配置文件里可以留空或写占位符。4. 验证请求跑通第一个 Agent 任务4.1 单轮验证模型连通性先做最小验证确认 Key 和通道没问题hermes -z 用一句话说明你当前使用的模型名称如果返回正常文本说明模型通道打通了。如果报 401检查 Key 是否复制完整报 404检查 base_url 是否多写了/v1。4.2 交互模式测试工具调用进入交互模式hermes chat在对话里输入搜索一下 Python 虚拟环境的最佳实践总结三条Agent 应该会自动调用web_search工具返回搜索结果并总结。这一步能验证工具链是否正常。如果工具没触发检查[terminal] backend是否为local。4.3 启动 Dashboard 可视化确认hermes dashboard浏览器访问http://localhost:8787。在 Dashboard 里能看到会话列表、工具调用日志、当前模型。点开刚才的会话确认工具调用记录里有web_search条目说明整条链路跑通了。4.4 一个完整的 Agent 任务试试让它写并执行脚本帮我写一个 Python 脚本统计当前目录下所有 .py 文件的行数然后执行它Hermes 会生成代码、调用终端执行、返回结果。如果报错它还会根据错误信息自动修。这就是 Agent 和普通聊天机器人的区别。5. 本篇常见错误排查5.1 API Key 报错api_key is not configured最常见的原因是环境变量没生效。先确认echo $HERMES_API_KEY如果为空说明~/.bashrc没 source或者你开的是新终端但没重新加载。执行source ~/.bashrc后重试。另一个原因是配置文件里api_key写了占位符但环境变量也没设两者至少要有一个有效。5.2 base_url 拼接错误导致 404TaoToken 的 API 地址是https://taotoken.net/api不要写成https://taotoken.net/api/v1。OpenAI SDK 会自己在后面拼/chat/completions你多写一层/v1就变成/api/v1/chat/completions路径对不上。统一只写到/api。5.3 WSL 里 pip 安装编译失败某些依赖需要编译工具。装一下sudo apt install build-essential python3-dev -y然后再pip install hermes-agent。如果还是失败看报错里缺哪个库用 apt 补上。5.4 Dashboard 端口被占用hermes dashboard默认 8787如果被占用会启动失败。换端口hermes dashboard --port 8899然后访问http://localhost:8899。WSL2 的端口会自动映射到 Windows 的 localhost一般不用额外配置防火墙。5.5 跨文件系统性能问题不要把项目放在/mnt/c/下。WSL 访问 Windows 文件系统有性能损耗而且权限模型不兼容Hermes 的文件工具可能报权限错误。项目放~/hermes-agent/需要从 Windows 访问时用\\wsl$\Ubuntu\home\你的用户名\。6. 后续怎么用从跑通到日常跑通第一个任务后你可以按需扩展。想长期做编码或 Agent 自动化建议了解 Coding Plan它更适合高频调用场景想先对比不同模型的表现可以直接在模型对话里试需要管理多个 Key 或查看用量去控制台接入细节和参数说明看接入文档。几个实用建议主模型选性价比高的比如 deepseek-chat辅助视觉模型单独配一个便宜的开启上下文压缩长对话能省不少 token定期hermes skills list看看有没有新技能可装。Hermes 的记忆系统会跨会话保留偏好用久了确实会越来越顺手。最后提醒一句配置文件里的 Key 别提交到 Git用环境变量管理。WSL 里的~/.bashrc也不要随便分享。把这两点做好本地 Agent 就能稳定跑下去了。