1. Hermes Agent 安装前我踩过的环境坑Hermes Agent 是一个可以跑在终端里的智能体框架能调用工具、执行命令、读写文件适合想在自己机器上搭一套可编排 Agent 的开发者。它本体是 Python 写的但浏览器工具、部分技能又依赖 Node.js所以从零安装时最容易被两件事卡住一是系统自带的 Python 版本太低二是 Node.js 根本没装。这篇记录就是围绕这两个运行时把 uv 管 Python、Node.js 补浏览器依赖、再接入 TaoToken 的完整链路走一遍。我这次用的是一台 CentOS 的云主机root 身份操作。官方给了一键脚本但脚本内部其实做了很多判断先找系统 Python找不到就装 uv再用 uv 拉一个独立的 Python 3.11接着克隆源码、建虚拟环境、装核心依赖最后写命令链接和配置文件。整个过程里 Node.js 是默认跳过的所以后面第一次运行hermes时它会反过来问你装不装浏览器引擎这时候才补 Node.js。如果你只是想让 Agent 能对话、能跑终端命令其实不装 Node.js 也能用但网页浏览、部分技能会缺失。我的建议是一步到位把 Node.js 22 LTS 也装上省得后面反复折腾。下面按实际执行顺序拆开讲每一步都给可复制的命令和预期输出你照着敲基本不会偏。需要提前说明的是安装脚本会从镜像源拉取速度取决于你的网络环境Python 3.11 那一步我实测等了五分多钟耐心点别中断。另外所有配置最终都落在~/.hermes/目录下搞清楚这个目录结构后面排障会轻松很多。2. 用 uv 管理 Python 并补齐 Node.js 运行时2.1 一键脚本到底做了什么先执行官方镜像脚本curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash脚本会打印 7 个步骤的进度。第 1 步识别系统我这里是linux (centos)。第 2 步检查系统 Python 是否 3.11CentOS 自带的通常是 3.6 或 3.9直接判定不合格于是转向 uv。它会下载 uv 安装脚本并装到/root/.local/bin装完提示你把该目录加进 PATHsource $HOME/.local/bin/env接着 uv 开始装 Python 3.11输出类似Installed Python 3.11.15 in 5m 18s cpython-3.11.15-linux-x86_64-gnu (python3.11)这里有个 warning 说/root/.local/bin不在 PATH 里脚本后面会自动往.bashrc、.bash_profile、.profile里追加所以不用手动处理但当前 shell 需要source ~/.bashrc才生效。2.2 源码克隆与虚拟环境第 4 步从 CNB.cool 的 Git 镜像克隆源码到~/.hermes/hermes-agent仓库接近 200MB输出里能看到Receiving objects: 100% (96745/96745), 195.20 MiB。第 5 步用刚装好的 Python 3.11 建虚拟环境。第 6 步装核心依赖走的是清华 PyPI 镜像https://pypi.tuna.tsinghua.edu.cn/simple默认只装核心依赖浏览器、RL 训练这类体积大的扩展会跳过。第 7 步写命令和配置创建hermes命令链接到~/.local/bin/hermes生成~/.hermes/.env、~/.hermes/config.yaml、~/.hermes/SOUL.md并把 90 个内置技能同步到~/.hermes/skills/。看到Done: 90 new, 0 updated就说明技能同步完成。2.3 补装 Node.js 22 LTS脚本跑完后执行source ~/.bashrc再敲hermes它会检测到浏览器引擎缺失并询问是否安装Browser engine (Chromium, for web browsing tools) is not installed. Install now? [Y/n]回车确认后它先检查 Node.js发现没有于是自动下载node-v22.22.3-linux-x64.tar.xz并解压到~/.hermes/node/。这一步是浏览器工具的前置条件装完 Chromium 相关依赖才能正常拉起。如果你当时选了跳过后面想补可以手动进源码目录装cd ~/.hermes/hermes-agent npm install装完用hermes doctor和hermes tools list检查工具状态。我这边装完 Node.js 后工具可用类别从 4/10 提升到了包含浏览器自动化的更多项。3. 接入 TaoToken 的 config.yaml 与 settings.json 骨架3.1 先拿 Key 再改配置Hermes Agent 的模型接入走的是 provider 机制配置向导里有一长串 provider 可选包括各种直连 API 和自定义端点。我们要做的是把它指向 TaoToken 的统一通道。先去控制台创建 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contenthermes_agent_setuputm_campaignrewrite拿到形如sk-xxxx的 Key 后编辑密钥文件nano ~/.hermes/.env写入以下环境变量片段把 Key 换成你自己的# TaoToken 统一接入 OPENAI_API_KEYsk-你的TaoToken密钥 OPENAI_BASE_URLhttps://taotoken.net/api这里用OPENAI_API_KEY和OPENAI_BASE_URL是因为 Hermes 的 OpenAI 兼容 provider 会读取这两个变量TaoToken 提供 OpenAI 兼容接口所以直接复用最省事。如果你更习惯用配置文件而不是环境变量可以改~/.hermes/config.yaml。3.2 config.yaml 骨架config.yaml是 Hermes 的主配置模型和 provider 部分大致长这样你可以按需替换 model 字段model: provider: openai name: claude-sonnet-4-5 base_url: https://taotoken.net/api api_key_env: OPENAI_API_KEY agent: max_iterations: 90 tool_progress: all compression_threshold: 0.50 terminal: backend: local注意api_key_env指向的是环境变量名不是 Key 本身这样密钥不会明文写进 yaml。provider 填openai表示走 OpenAI 兼容协议base_url 指向 TaoToken 的 API 地址。3.3 settings.json 骨架有些技能和工具会读取独立的settings.json放在~/.hermes/下用来声明模型 ID 和端点。骨架如下{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model_id: claude-sonnet-4-5, timeout: 120, max_retries: 3 }三件套对齐一下Base URL 是https://taotoken.net/apiKey 是控制台创建的那串Model ID 按你实际要用的模型填。改完保存重新加载 shell 让环境变量生效source ~/.bashrc4. 验证请求与安装后自检命令4.1 用 hermes doctor 做基础体检配置改完先跑体检命令hermes doctor它会检查 Python 环境、依赖完整性、配置文件语法、密钥是否可读。如果.env里 Key 写错或 base_url 拼错这一步通常会给出提示。我建议每次改完配置都跑一次比直接启动聊天再报错要快。4.2 一条自检命令验证能否发起请求最直接的验证是让 Agent 发一次真实请求。用非交互模式跑一条简单指令hermes -p 用一句话说明你现在使用的模型名称如果接入正常你会看到它返回模型自述内容说明请求已经打到 TaoToken 并成功拿到响应。如果卡住或报错重点看下面几类信息。也可以进交互模式手动测hermes进去后随便问一句观察终端有没有401、connection refused之类的字样。成功的话模型回复会正常流式输出。4.3 确认工具链状态再跑一次工具列表hermes tools list对比安装时的 4/10补了 Node.js 后浏览器自动化应该变成可用。文本转语音、终端命令、任务规划这几类本来就是可用的。视觉分析、图像生成这些需要额外 Key 的类别按需再配。5. 本篇常见报错排查5.1 401 Unauthorized最常见的就是 Key 不对或没生效。先确认.env里的OPENAI_API_KEY没有多余空格和引号然后确认当前 shell 真的加载了echo $OPENAI_API_KEY如果输出为空说明source ~/.bashrc没执行或写错了文件。还有一种情况是 Key 创建后没复制完整去控制台重新生成一个再试。5.2 local proxy failed / connection refused这类报错通常是 base_url 写错或者本机网络到taotoken.net不通。先测连通性curl -I https://taotoken.net/api如果返回 4xx 说明网络通、是鉴权或路径问题如果直接超时检查 DNS 和出网策略。注意 base_url 结尾不要多加/v1TaoToken 的兼容路径以文档为准写错路径会返回 404 而不是 401容易误判。5.3 reading choices 相关解析错误如果日志里出现类似reading choices的字段解析失败多半是返回体不是预期的 OpenAI 格式常见原因是 model 名填错导致上游返回了错误结构或者 base_url 指向了非兼容端点。核对config.yaml里的name和base_url确保 model ID 是 TaoToken 支持的。5.4 OAuth 与 provider 选择冲突配置向导里有一堆 OAuth 类 provider比如某些订阅登录方式。如果你之前选过 OAuth provider又在.env里写了 OpenAI 兼容变量可能出现 provider 冲突表现为一直提示未配置。解决办法是明确指定 providerhermes setup model在向导里选custom (direct API)或Custom endpoint手动填 base_url 和 Key避免和 OAuth 逻辑打架。5.5 Node.js 装了但浏览器工具仍不可用确认 Node 解压路径在 PATH 里~/.hermes/node/bin/node -v如果命令找不到手动加进 PATH 或重新跑cd ~/.hermes/hermes-agent npm install。装完再hermes doctor复查。6. 后续接入与长期使用建议环境搭好之后日常使用其实就三件事改配置、跑任务、看日志。配置集中在~/.hermes/config.yaml和~/.hermes/.env日志在~/.hermes/logs/会话数据在~/.hermes/sessions/。出问题先翻日志比盲猜快得多。如果你打算长期用它跑编码或 Agent 任务建议把模型接入固定下来别每次重装都重新配。TaoToken 的 Coding Plan 适合高频编码场景模型对话入口适合临时验证模型效果接入文档里有各语言的调用示例模型对话https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contenthermes_agent_setuputm_campaignrewrite Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contenthermes_agent_setuputm_campaignrewrite 接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contenthermes_agent_setuputm_campaignrewrite最后提醒一个实操细节uv 装的 Python 和虚拟环境都在~/.hermes/下如果你换机器或重装系统这个目录整个备份走恢复后基本能直接跑省去重新拉依赖的五分钟。Node.js 那部分如果不想每次重下也可以把~/.hermes/node/一起打包。
