1. Hermes Agent 是什么？四端部署前先搞清楚这件事
Hermes Agent 是一个能在终端里跑起来的 AI 智能体框架，你可以把它理解成一个「住在命令行里的助手」——它能读写文件、执行命令、调用工具，还能在长任务里保持上下文不丢。和普通聊天机器人最大的区别是：它不是只跟你对话，而是真的能动手干活。适合谁用？经常在服务器上折腾的运维、想把手动流程自动化的开发者、以及希望本地留一份可控 Agent 环境的技术爱好者。
我这次要交付的目标很明确：在 Linux、macOS、Windows（含 WSL2 与原生两条路）、Android（Termux）四类系统上，把 Hermes Agent 完整装起来，并且统一通过 TaoToken 的 Key/API 通道接入模型，最后跑一次真实请求验证链路通不通。整套流程走下来，快的话 5 分钟能见到聊天界面，慢的话主要卡在依赖下载和模型配置这两步。
先说清楚一个容易踩的坑：Hermes Agent 本身只是「壳」，它需要外接一个大模型才能思考。所以安装分两段——第一段装 Agent 本体，第二段配模型通道。很多人装完hermes命令能跑，但一聊天就报错，八成是第二段没配对。本文会把这两段拆开讲，每段都给可复制的命令和配置片段。
四端里，Linux 和 macOS 体验最顺，一条 curl 命令搞定；Windows 强烈建议走 WSL2，原生 PowerShell 版本目前还是早期 Beta，偶发路径和权限问题；Android 用 Termux 模拟 Linux 环境，命令和 Linux 完全一致，只是性能受手机限制。下面按平台逐个拆。
在开始之前，确认你的网络能访问 GitHub 和模型 API 端点。国内直连 GitHub 偶尔会慢，这不是 Hermes 的问题，换镜像脚本即可。另外安装脚本会自动处理 Python、Node.js、Git 这些依赖，你不需要提前装，省了很多事。
2. 装之前先备好 TaoToken 通道：统一 Key 与 API 地址
Hermes Agent 支持一堆模型服务商，但如果你每个平台都单独配 Key、单独记 Base URL，四端部署会变成四套配置，维护起来很痛苦。我的做法是统一走 TaoToken 的 API 通道——一个 Key、一个 Base URL，四端共用，换模型只改一个 Model ID 字段。
TaoToken 在这里扮演的角色是「模型接入层」：它把不同厂商的模型能力收敛成一套兼容 OpenAI 格式的接口。对 Hermes Agent 来说，它只需要知道三件事——Base URL 指向哪、用哪个 Key、调哪个 Model ID。这三件套配好，Agent 就能正常发请求。
先拿 Key。打开控制台页面，登录后进入 API Keys 管理，新建一个 Key 并复制保存。这个 Key 只在创建时完整显示一次，丢了就得重建，所以建议直接存进密码管理器。
- 控制台入口：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
- API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
拿到 Key 之后，记下两个固定值，后面四端配置都要用：
| 配置项 | 值 | 说明 |
|---|---|---|
| Base URL | https://taotoken.net/api | 注意结尾不带斜杠，也不加 UTM |
| API Key | sk-开头的一串 | 从 API Keys 页面复制 |
| Model ID | 例如claude-sonnet-4-5等 | 按你订阅的模型填，可在模型对话页确认 |
Model ID 具体填什么，最稳的办法是去模型对话页面实际发一条消息，看它当前可用模型列表里哪个是你想要的，把名字原样抄进配置。不同账号可用的模型不一样，别照抄别人的。
注意：Base URL 一定用
https://taotoken.net/api，不要手动拼/v1或加斜杠。Hermes Agent 内部会自己补路径，你多写一段反而会 404。
如果你还没决定用哪个模型，可以先在模型对话页试几个，确认响应速度和中文理解符合预期，再写进 Agent 配置。这一步花两分钟，能省掉后面反复改配置的麻烦。
- 模型对话体验：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
- 接入文档参考：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
Key 和 Base URL 备齐后，就可以进入各平台安装了。记住这三件套，后面每一端的配置都是围绕它们展开。
3. 四端可复制安装与配置文件片段
这一节是全文的核心，四类系统逐个给命令。所有命令都可以直接复制，路径和字段名保持和官方一致，你照着填就行。
3.1 Linux / macOS / WSL2 一键安装
打开终端，执行官方安装脚本：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash国内网络如果卡在下载，换镜像脚本：
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash装完重新加载 Shell 配置，让hermes命令进 PATH：
source ~/.bashrc # Zsh 用户改用： source ~/.zshrc验证版本：
hermes --version # 正常输出类似 v0.13.03.2 Windows 两条路：WSL2 与原生 PowerShell
WSL2 是推荐路线。以管理员身份打开 PowerShell：
wsl --install重启电脑后进入 Ubuntu 终端，直接复用上面的 Linux 一键安装命令即可。WSL2 里的环境和原生 Linux 一致，后续配置完全通用。
原生 Windows 目前是早期 Beta，装法是用 PowerShell 拉脚本：
iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)国内加速版：
irm https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex原生版装完如果hermes命令找不到，检查%LOCALAPPDATA%\hermes是否在 PATH 里，手动加一下。
3.3 Android（Termux）安装
先从 F-Droid 装 Termux（Google Play 版本更新滞后，不推荐）。打开 Termux 后，命令和 Linux 完全一样：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashTermux 里没有sudo，安装脚本会自动装到用户目录，不需要提权。装完同样source ~/.bashrc再验证。
3.4 手动安装（开发者路线）
想自己控制依赖版本，走手动路线。先克隆仓库含子模块：
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git cd hermes-agent装 uv 包管理器并建虚拟环境：
pip install uv uv venv source .venv/bin/activate # Windows 原生：.venv\Scripts\activate装全部依赖：
uv pip install -e ".[all]"把用户 bin 目录加进 PATH：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc3.5 统一模型配置：把 TaoToken 三件套写进配置
四端装完后，配置模型的方式统一。先跑交互式向导：
hermes setup向导里选择「OpenAI 兼容」或自定义 API 接入方式，然后按提示填三件套。如果你想直接写配置文件，Hermes Agent 的配置目录在~/.hermes/，主配置文件是config.toml。下面是一份可直接复制的片段，把 Key 换成你自己的：
[model] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key = "sk-你的Key粘贴在这里" model_id = "claude-sonnet-4-5" max_tokens = 8192 temperature = 0.7 [agent] auto_approve_tools = false max_iterations = 30如果你更习惯 JSON 格式（部分版本支持settings.json），等价写法：
{ "model": { "provider": "openai-compatible", "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key粘贴在这里", "model_id": "claude-sonnet-4-5", "max_tokens": 8192, "temperature": 0.7 }, "agent": { "auto_approve_tools": false, "max_iterations": 30 } }注意：
base_url结尾不要加/v1，也不要加斜杠。model_id必须和你账号里实际可用的模型名完全一致，大小写敏感。
配置写完后，用hermes doctor检查一遍环境和配置是否被正确读取：
hermes doctor它会逐项列出 Base URL、Key 是否加载、模型是否可达。这一步能提前暴露大部分配置错误。
4. 验证请求：从 hermes doctor 到真实对话跑通
配置写完不代表链路通，必须发一次真实请求才算数。这一节给完整的验证流程和预期输出。
第一步，环境自检：
hermes doctor正常输出会显示配置加载成功、模型端点可达。如果这里就报local proxy failed或连接超时，先别往下走，回到第 5 节排查。
第二步，启动 Agent：
hermes进入交互界面后，先发一条最简单的消息测试：
你好，请用一句话介绍你自己如果模型通道正常，几秒内会返回中文回复。这一步验证的是「Key + Base URL + Model ID」三件套是否全部生效。
第三步，测工具调用能力。Hermes Agent 的核心价值是能动手，所以发一条需要执行命令的指令：
帮我列出当前目录下的文件，并统计有多少个 .md 文件正常情况它会调用 shell 工具执行ls，然后返回统计结果。如果它只是「说」要执行但不真执行，检查auto_approve_tools设置——设为false时每次工具调用需要你手动确认，这是安全设计，不是 bug。
第四步，切换模型验证多模型可用性：
hermes model在列表里换一个 Model ID，再发一条消息，确认新模型也能正常响应。这一步能验证你的 TaoToken 账号下多个模型都可用。
第五步，检查版本和更新通道：
hermes update能正常拉取更新说明安装完整、PATH 正确。
实测下来，从hermes doctor全绿到真实对话返回，正常网络下不超过 30 秒。如果卡在某一步，对照下一节的报错表定位。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
这一节按真实报错逐条给解法，都是我在四端部署时实际撞过的。
401 Unauthorized：Key 无效或没被读取。先确认config.toml里api_key字段没有多余空格或换行；再确认 Key 没有过期或被删。最快的验证方式是直接用 curl 打一次接口：
curl https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"claude-sonnet-4-5","messages":[{"role":"user","content":"hi"}]}'如果 curl 也 401，问题在 Key；如果 curl 通但 hermes 报 401，问题在配置文件路径或字段名。
local proxy failed：通常是 Base URL 写错，或者本地网络到端点不通。检查base_url是否为https://taotoken.net/api，结尾无斜杠无/v1。再确认没有在系统里设过奇怪的 HTTP 代理环境变量，echo $HTTP_PROXY看一下，有就 unset 掉。
Error reading choices / choices 字段为空：这是响应格式不匹配。多半是 Model ID 填错，请求打到了一个不存在的模型，返回体里没有choices。去模型对话页确认当前可用模型名，原样抄进model_id。也可能是max_tokens设得过大超过该模型上限，调小到 8192 再试。
OAuth 相关报错：如果你在向导里选了 OAuth 登录方式而不是 API Key，会走浏览器授权流程。四端里 Termux 和纯终端环境没有浏览器，OAuth 会失败。解决办法是改用 API Key 方式接入，也就是本文推荐的 TaoToken 三件套路线，不依赖浏览器。
hermes 命令找不到：PATH 没生效。Linux/macOS 执行source ~/.bashrc或source ~/.zshrc；Windows 原生检查%LOCALAPPDATA%\hermes是否在系统 PATH；Termux 重开一个会话。
安装脚本下载中断：换镜像脚本重跑，已下载的部分会复用，不会从头来。
权限不足：安装脚本设计上不需要 sudo，全部装到用户目录。如果报权限错，检查~/.local/bin和~/.hermes的属主是不是当前用户，用ls -la看一眼。
排查顺序建议固定：先hermes doctor看它报哪一项，再针对性处理，不要盲目重装。大部分问题集中在 Key、Base URL、Model ID 这三个字段上。
6. 长期跑 Agent 任务，把 Coding Plan 用起来
四端装完、验证通过之后，如果你打算把 Hermes Agent 当成日常编码或长任务助手长期用，单次按量调用在频繁场景下成本不好控。这时候可以看一下 Coding Plan，它更适合高频、长时间的 Agent 工作负载，配合 Hermes 的持续学习特性，能把多轮工具调用的开销压下来。
- 长期编码 / Agent 场景：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
如果你还想在别的编辑器或工具里复用同一套 Key，接入文档里有各客户端的配置示例，Base URL 和 Key 都是同一套，不用重复申请：
- 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
- API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
最后给一个实用技巧：四端部署时，把~/.hermes/config.toml这份配置备份一份到私有仓库或密码管理器。换机器、重装系统时直接还原，省掉重新跑hermes setup的功夫。Key 记得用环境变量注入而不是硬编码进文件，export TAOTOKEN_API_KEY=sk-xxx然后在配置里引用，这样配置文件可以安全地跟着 dotfiles 走。
