1. 为什么要在 WSL2 里跑 hermes agenthermes agent 是一个能在终端里直接对话、调用工具、读写文件的命令行智能体。它最大的特点是轻量不需要图形界面一条hermes命令就能进入交互模式适合放在 Linux 环境里长期挂着跑。而 WSL2 正好给了 Windows 用户一个几乎零成本的 Linux 环境不用装双系统不用买云主机文件系统性能也接近原生。把这两者拼在一起你得到的是一个「Windows 桌面 Linux 终端智能体」的组合。日常写代码、跑脚本、让 agent 帮你查资料改文件全都在同一个窗口里完成。对零基础用户来说这套方案的门槛其实比想象中低——真正容易卡住的地方只有三个WSL2 装不上、hermes agent 装完找不到命令、以及 API Key 到处散落不好管理。这篇教程就围绕这三点展开。前半段带你把 WSL2 和 hermes agent 装好后半段重点讲配置文件settings.json的骨架怎么写以及怎么用 TaoToken 的统一 Key 把模型通道接进去。装完之后你只需要维护一份 Key换模型、换工具都不用再翻来覆去改环境变量。适合谁看Windows 10/11 用户、没怎么用过 Linux 命令行的新手、以及手上已经有 TaoToken 账号但不知道怎么接到命令行工具里的人。全程命令都可以直接复制遇到报错我在第 5 节列了常见情况。2. 前置准备WSL2 环境与 TaoToken 统一 Key2.1 确认 Windows 版本和虚拟化WSL2 对系统有硬性要求。Windows 10 需要版本号 1903 以上、内部版本 18362 以上Windows 11 全系列都支持。按Win R输入winver回车就能看到当前版本。如果版本太低先去 Windows 更新里升级。硬件方面CPU 要支持虚拟化。近十年的 Intel 和 AMD 处理器基本都支持但需要在 BIOS/UEFI 里把虚拟化开关打开通常标为 VT-x 或 AMD-V。这个开关不开WSL2 启动时会直接报错。内存建议 8GB 起步跑 agent 加编译任务时 16GB 会更从容。2.2 开启 WSL 相关功能以管理员身份打开 PowerShell依次执行两条命令dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完必须重启电脑配置才会生效。如果你更习惯图形界面按Win R输入optionalfeatures在弹出的窗口里勾选「适用于 Linux 的 Windows 子系统」和「虚拟机平台」两项效果一样。2.3 安装 Ubuntu 并指定安装盘重启后在管理员 PowerShell 里执行wsl --install -d Ubuntu-24.04 --location D:\WSL\Ubuntu-d Ubuntu-24.04指定安装 Ubuntu 24.04 LTS这是当前稳定的长期支持版。--location D:\WSL\Ubuntu把整个 Linux 系统装到 D 盘避免 C 盘被慢慢吃满——这个参数很多人不知道等 C 盘红了才后悔。安装过程会下载几百兆资源。完成后自动弹出终端窗口依次设置 UNIX 用户名建议小写、无中文空格和密码。密码输入时屏幕不显示字符这是 Linux 的正常行为输完回车即可。看到Installation successful!就成功了。进入系统后先更新软件包索引sudo apt update sudo apt upgrade -y2.4 拿到 TaoToken 统一 Keyhermes agent 需要一个模型提供商的 API Key 才能对话。传统做法是每个提供商单独申请、单独配置换模型就要改一次配置。TaoToken 的思路是给你一个统一入口一个 Key 走通多个模型通道配置里只维护一份凭证。先去官网注册并登录https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content登录后在控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite创建完记得立刻复制Key 只在弹窗里显示一次。这个 Key 就是后面settings.json里要填的东西。API 的基础地址是https://taotoken.net/api注意这个地址不带任何查询参数配置里直接写它就行。如果你后面想确认有哪些模型可用可以打开模型对话页面看一眼https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite3. 安装 hermes agent 并写对 settings.json3.1 安装 hermes agent在 Ubuntu 终端里执行官方安装脚本curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash如果这条命令因为网络原因拉不下来可以换成带镜像前缀的版本curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash安装完成后刷新一下 shell 配置让新命令生效source ~/.bashrc然后输入hermes能看到欢迎界面就说明装好了。如果提示command not found先确认~/.bashrc里有没有被追加 PATH没有的话手动加一行echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc3.2 配置文件放在哪hermes agent 的配置默认放在用户目录下的.hermes文件夹里主文件就是settings.json。你可以用内置命令直接打开编辑hermes config edit也可以手动定位ls -la ~/.hermes/看到settings.json就对了。这个文件是 JSON 格式结构不复杂但括号和逗号必须严格配对多一个逗号都会导致解析失败。下面给一份可以直接抄的骨架。3.3 可复制的 settings.json 骨架{ provider: { name: taotoken, type: openai-compatible, base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514 }, tools: { web: true, terminal: true, file: true, browser: false }, ui: { theme: dark, stream: true }, gateway: { enabled: false, port: 8787 } }几个字段解释一下。provider.type写openai-compatible因为 TaoToken 的 API 通道兼容 OpenAI 的请求格式hermes agent 能直接识别。base_url填https://taotoken.net/api不要在后面加/v1之类的后缀工具会自己拼接路径。api_key换成你在控制台复制的那串。model填你想用的模型名具体可用列表在模型对话页面能看到。tools里四个开关对应四种能力web是联网搜索和网页提取terminal是执行 shell 命令file是读写本地文件browser是浏览器自动化。新手建议先开前三个browser依赖额外的浏览器内核装起来麻烦等用熟了再开。注意api_key是敏感信息别把这份settings.json提交到 Git 仓库。如果一定要版本管理把 Key 抽到环境变量里配置里写api_key: ${TAOTOKEN_API_KEY}然后在~/.bashrc里export TAOTOKEN_API_KEYsk-xxx。3.4 用环境变量兜底有些版本的 hermes agent 会优先读环境变量。为了保险可以在~/.bashrc末尾加两行export TAOTOKEN_API_KEYsk-你的TaoToken密钥 export OPENAI_BASE_URLhttps://taotoken.net/api改完执行source ~/.bashrc。这样即使settings.json里的 Key 写错了工具也能从环境变量里拿到正确的值。两处都配好基本不会出现认证失败。4. 启动验证与成功结果4.1 先做一次配置自检改完配置别急着对话先让工具自己检查一遍hermes config这条命令会把当前生效的配置打印出来。重点看三处base_url是不是https://taotoken.net/apiapi_key是不是以sk-开头且没有多余空格model是不是你想要的模型名。如果这里显示的还是旧值说明配置文件没保存成功或者你改的是另一个路径下的文件。4.2 发一条测试请求确认配置无误后直接启动hermes进入交互界面后输入一句简单的话比如「用一句话解释什么是递归」。如果配置正确你会看到模型流式返回的答案一个字一个字往外蹦。第一次响应可能稍慢因为要建立连接后面就快了。想更直接地验证 API 通道是否通可以用 curl 单独打一发curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}] }返回 JSON 里带choices字段就说明通道没问题。如果这里报 401是 Key 错了报 404是base_url或模型名写错了报连接超时检查网络。4.3 验证工具调用光能对话还不够hermes agent 的价值在于调工具。在交互界面里输入帮我看看当前目录下有哪些文件如果file工具启用正常它会列出目录内容。再试一句搜索一下 WSL2 的内存限制怎么调整web工具启用的话它会返回搜索结果摘要。这两个动作能跑通说明工具链和模型通道都接好了。4.4 常用命令速查装好之后日常会用到这几条hermes # 进入对话 hermes setup # 重新走配置向导 hermes config # 查看当前配置 hermes config edit # 直接编辑 settings.json hermes update # 升级到最新版 hermes gateway install # 安装网关服务支持消息和定时任务hermes gateway install这条适合想让 agent 常驻后台、定时跑任务的场景。新手先不用碰等基础对话稳定了再说。5. 本篇常见报错排查5.1 wsl --install 报「虚拟化未启用」现象是安装命令直接失败提示需要开启虚拟化。解决方法是进 BIOS/UEFI找到 Intel VT-x 或 AMD-V 选项打开。不同主板菜单位置不一样一般在 Advanced 或 CPU Configuration 里。开完保存重启再执行wsl --install。5.2 hermes 命令找不到装完脚本后输入hermes提示command not found九成是 PATH 没刷新。先执行source ~/.bashrc还不行就检查~/.local/bin在不在 PATH 里echo $PATH | tr : \n | grep local没有输出就手动加进去然后重新source。5.3 认证失败 401settings.json里的api_key最常见的问题是复制时带了空格或换行。用hermes config看打印出来的值如果 Key 前后有空白重新编辑文件删掉。另一个可能是 Key 已经失效去控制台重新创建一个https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite5.4 模型名报 404model字段填的模型名如果不在可用列表里请求会返回 404。去模型对话页面确认一下当前支持的模型名复制准确的字符串填进去。注意模型名大小写敏感别自己改。5.5 settings.json 解析失败启动时报 JSON 解析错误通常是多了一个逗号或者少了一个引号。JSON 不允许最后一个字段后面有逗号。把文件贴到任意 JSON 校验工具里过一遍红色标记的位置就是问题所在。改完保存重新hermes config确认。5.6 工具调用没反应对话正常但让它读文件、搜网页时没动作检查settings.json里tools对应的开关是不是true。如果开了还是不行看终端有没有权限报错——terminal工具执行命令时如果碰到需要 sudo 的操作会卡住等密码这时候在交互界面里手动输入密码即可。6. 把统一 Key 用顺手的几个建议配置跑通之后真正省事的地方在于你只需要维护一份 Key。以后想换模型改settings.json里的model字段就行base_url和api_key都不用动。想加新工具改tools里的开关。整个配置文件就一个地方要记不用在多个提供商后台之间来回切换。如果你打算长期用 hermes agent 做编码或者跑自动化任务可以了解一下 Coding Plan它针对高频调用场景做了额度优化https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite接入文档里对settings.json各字段有更细的说明遇到本文没覆盖的字段可以去查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite最后提醒一句settings.json改完一定要用hermes config确认生效别改完直接对话不然报错了你都不知道是配置没读到还是 Key 有问题。这个习惯能帮你省掉一大半排查时间。
hermes agent 零基础安装和配置教程：WSL2 下用 TaoToken 统一 Key 打通 settings.json
1. 为什么要在 WSL2 里跑 hermes agenthermes agent 是一个能在终端里直接对话、调用工具、读写文件的命令行智能体。它最大的特点是轻量不需要图形界面一条hermes命令就能进入交互模式适合放在 Linux 环境里长期挂着跑。而 WSL2 正好给了 Windows 用户一个几乎零成本的 Linux 环境不用装双系统不用买云主机文件系统性能也接近原生。把这两者拼在一起你得到的是一个「Windows 桌面 Linux 终端智能体」的组合。日常写代码、跑脚本、让 agent 帮你查资料改文件全都在同一个窗口里完成。对零基础用户来说这套方案的门槛其实比想象中低——真正容易卡住的地方只有三个WSL2 装不上、hermes agent 装完找不到命令、以及 API Key 到处散落不好管理。这篇教程就围绕这三点展开。前半段带你把 WSL2 和 hermes agent 装好后半段重点讲配置文件settings.json的骨架怎么写以及怎么用 TaoToken 的统一 Key 把模型通道接进去。装完之后你只需要维护一份 Key换模型、换工具都不用再翻来覆去改环境变量。适合谁看Windows 10/11 用户、没怎么用过 Linux 命令行的新手、以及手上已经有 TaoToken 账号但不知道怎么接到命令行工具里的人。全程命令都可以直接复制遇到报错我在第 5 节列了常见情况。2. 前置准备WSL2 环境与 TaoToken 统一 Key2.1 确认 Windows 版本和虚拟化WSL2 对系统有硬性要求。Windows 10 需要版本号 1903 以上、内部版本 18362 以上Windows 11 全系列都支持。按Win R输入winver回车就能看到当前版本。如果版本太低先去 Windows 更新里升级。硬件方面CPU 要支持虚拟化。近十年的 Intel 和 AMD 处理器基本都支持但需要在 BIOS/UEFI 里把虚拟化开关打开通常标为 VT-x 或 AMD-V。这个开关不开WSL2 启动时会直接报错。内存建议 8GB 起步跑 agent 加编译任务时 16GB 会更从容。2.2 开启 WSL 相关功能以管理员身份打开 PowerShell依次执行两条命令dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完必须重启电脑配置才会生效。如果你更习惯图形界面按Win R输入optionalfeatures在弹出的窗口里勾选「适用于 Linux 的 Windows 子系统」和「虚拟机平台」两项效果一样。2.3 安装 Ubuntu 并指定安装盘重启后在管理员 PowerShell 里执行wsl --install -d Ubuntu-24.04 --location D:\WSL\Ubuntu-d Ubuntu-24.04指定安装 Ubuntu 24.04 LTS这是当前稳定的长期支持版。--location D:\WSL\Ubuntu把整个 Linux 系统装到 D 盘避免 C 盘被慢慢吃满——这个参数很多人不知道等 C 盘红了才后悔。安装过程会下载几百兆资源。完成后自动弹出终端窗口依次设置 UNIX 用户名建议小写、无中文空格和密码。密码输入时屏幕不显示字符这是 Linux 的正常行为输完回车即可。看到Installation successful!就成功了。进入系统后先更新软件包索引sudo apt update sudo apt upgrade -y2.4 拿到 TaoToken 统一 Keyhermes agent 需要一个模型提供商的 API Key 才能对话。传统做法是每个提供商单独申请、单独配置换模型就要改一次配置。TaoToken 的思路是给你一个统一入口一个 Key 走通多个模型通道配置里只维护一份凭证。先去官网注册并登录https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content登录后在控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite创建完记得立刻复制Key 只在弹窗里显示一次。这个 Key 就是后面settings.json里要填的东西。API 的基础地址是https://taotoken.net/api注意这个地址不带任何查询参数配置里直接写它就行。如果你后面想确认有哪些模型可用可以打开模型对话页面看一眼https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite3. 安装 hermes agent 并写对 settings.json3.1 安装 hermes agent在 Ubuntu 终端里执行官方安装脚本curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash如果这条命令因为网络原因拉不下来可以换成带镜像前缀的版本curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash安装完成后刷新一下 shell 配置让新命令生效source ~/.bashrc然后输入hermes能看到欢迎界面就说明装好了。如果提示command not found先确认~/.bashrc里有没有被追加 PATH没有的话手动加一行echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc3.2 配置文件放在哪hermes agent 的配置默认放在用户目录下的.hermes文件夹里主文件就是settings.json。你可以用内置命令直接打开编辑hermes config edit也可以手动定位ls -la ~/.hermes/看到settings.json就对了。这个文件是 JSON 格式结构不复杂但括号和逗号必须严格配对多一个逗号都会导致解析失败。下面给一份可以直接抄的骨架。3.3 可复制的 settings.json 骨架{ provider: { name: taotoken, type: openai-compatible, base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514 }, tools: { web: true, terminal: true, file: true, browser: false }, ui: { theme: dark, stream: true }, gateway: { enabled: false, port: 8787 } }几个字段解释一下。provider.type写openai-compatible因为 TaoToken 的 API 通道兼容 OpenAI 的请求格式hermes agent 能直接识别。base_url填https://taotoken.net/api不要在后面加/v1之类的后缀工具会自己拼接路径。api_key换成你在控制台复制的那串。model填你想用的模型名具体可用列表在模型对话页面能看到。tools里四个开关对应四种能力web是联网搜索和网页提取terminal是执行 shell 命令file是读写本地文件browser是浏览器自动化。新手建议先开前三个browser依赖额外的浏览器内核装起来麻烦等用熟了再开。注意api_key是敏感信息别把这份settings.json提交到 Git 仓库。如果一定要版本管理把 Key 抽到环境变量里配置里写api_key: ${TAOTOKEN_API_KEY}然后在~/.bashrc里export TAOTOKEN_API_KEYsk-xxx。3.4 用环境变量兜底有些版本的 hermes agent 会优先读环境变量。为了保险可以在~/.bashrc末尾加两行export TAOTOKEN_API_KEYsk-你的TaoToken密钥 export OPENAI_BASE_URLhttps://taotoken.net/api改完执行source ~/.bashrc。这样即使settings.json里的 Key 写错了工具也能从环境变量里拿到正确的值。两处都配好基本不会出现认证失败。4. 启动验证与成功结果4.1 先做一次配置自检改完配置别急着对话先让工具自己检查一遍hermes config这条命令会把当前生效的配置打印出来。重点看三处base_url是不是https://taotoken.net/apiapi_key是不是以sk-开头且没有多余空格model是不是你想要的模型名。如果这里显示的还是旧值说明配置文件没保存成功或者你改的是另一个路径下的文件。4.2 发一条测试请求确认配置无误后直接启动hermes进入交互界面后输入一句简单的话比如「用一句话解释什么是递归」。如果配置正确你会看到模型流式返回的答案一个字一个字往外蹦。第一次响应可能稍慢因为要建立连接后面就快了。想更直接地验证 API 通道是否通可以用 curl 单独打一发curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}] }返回 JSON 里带choices字段就说明通道没问题。如果这里报 401是 Key 错了报 404是base_url或模型名写错了报连接超时检查网络。4.3 验证工具调用光能对话还不够hermes agent 的价值在于调工具。在交互界面里输入帮我看看当前目录下有哪些文件如果file工具启用正常它会列出目录内容。再试一句搜索一下 WSL2 的内存限制怎么调整web工具启用的话它会返回搜索结果摘要。这两个动作能跑通说明工具链和模型通道都接好了。4.4 常用命令速查装好之后日常会用到这几条hermes # 进入对话 hermes setup # 重新走配置向导 hermes config # 查看当前配置 hermes config edit # 直接编辑 settings.json hermes update # 升级到最新版 hermes gateway install # 安装网关服务支持消息和定时任务hermes gateway install这条适合想让 agent 常驻后台、定时跑任务的场景。新手先不用碰等基础对话稳定了再说。5. 本篇常见报错排查5.1 wsl --install 报「虚拟化未启用」现象是安装命令直接失败提示需要开启虚拟化。解决方法是进 BIOS/UEFI找到 Intel VT-x 或 AMD-V 选项打开。不同主板菜单位置不一样一般在 Advanced 或 CPU Configuration 里。开完保存重启再执行wsl --install。5.2 hermes 命令找不到装完脚本后输入hermes提示command not found九成是 PATH 没刷新。先执行source ~/.bashrc还不行就检查~/.local/bin在不在 PATH 里echo $PATH | tr : \n | grep local没有输出就手动加进去然后重新source。5.3 认证失败 401settings.json里的api_key最常见的问题是复制时带了空格或换行。用hermes config看打印出来的值如果 Key 前后有空白重新编辑文件删掉。另一个可能是 Key 已经失效去控制台重新创建一个https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite5.4 模型名报 404model字段填的模型名如果不在可用列表里请求会返回 404。去模型对话页面确认一下当前支持的模型名复制准确的字符串填进去。注意模型名大小写敏感别自己改。5.5 settings.json 解析失败启动时报 JSON 解析错误通常是多了一个逗号或者少了一个引号。JSON 不允许最后一个字段后面有逗号。把文件贴到任意 JSON 校验工具里过一遍红色标记的位置就是问题所在。改完保存重新hermes config确认。5.6 工具调用没反应对话正常但让它读文件、搜网页时没动作检查settings.json里tools对应的开关是不是true。如果开了还是不行看终端有没有权限报错——terminal工具执行命令时如果碰到需要 sudo 的操作会卡住等密码这时候在交互界面里手动输入密码即可。6. 把统一 Key 用顺手的几个建议配置跑通之后真正省事的地方在于你只需要维护一份 Key。以后想换模型改settings.json里的model字段就行base_url和api_key都不用动。想加新工具改tools里的开关。整个配置文件就一个地方要记不用在多个提供商后台之间来回切换。如果你打算长期用 hermes agent 做编码或者跑自动化任务可以了解一下 Coding Plan它针对高频调用场景做了额度优化https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite接入文档里对settings.json各字段有更细的说明遇到本文没覆盖的字段可以去查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite最后提醒一句settings.json改完一定要用hermes config确认生效别改完直接对话不然报错了你都不知道是配置没读到还是 Key 有问题。这个习惯能帮你省掉一大半排查时间。
