Hermes

Nous Research 的命令行 Agent，支持多 Profile、工具集管理和社交平台网关。

开始之前

需要一个 API Key 和账户可用额度，模型名从模型列表复制（大小写敏感）。

Windows 一键配置

不想手动编辑 config.yaml 和 .env？先安装并至少启动一次 Hermes，再使用 GSS Deploy（Windows 一键配置）自动写入配置。仅支持 Windows。

安装

系统	命令
Windows	`iex (irm https://hermes-agent.nousresearch.com/install.ps1)`（PowerShell，原生运行，不需要 WSL）
macOS / Linux	`curl -fsSL https://hermes-agent.nousresearch.com/install.sh \| bash`

安装器会自动装好 Python 3.11、uv、Node.js、ripgrep、ffmpeg 和 Git Bash 等依赖。Linux 支持主流发行版（Ubuntu、Debian、CentOS、Arch 等）。

不要用 sudo

Hermes 设计为以普通用户身份安装运行，安装脚本会自行处理 PATH。

验证：

hermes --version
hermes doctor

配置 API 端点

方式一：交互式向导

hermes model

选 Custom endpoint (self-hosted / VLLM / etc.)，然后填：

提示项	填什么
API base URL	`https://api.smartwan.com/v1`
API Key	你的 API Key
Model name	从模型列表选
api_mode	`chat_completions`

上下文长度可留空自动检测。模型列表通常能从端点自动拉取，拉不到就手输模型 ID。

方式二：手动编辑配置

配置文件位置：

Linux / macOS：~/.hermes/config.yaml
Windows：%LOCALAPPDATA%\hermes\config.yaml

custom_providers:
  - name: tokenroute
    base_url: https://api.smartwan.com/v1
    key_env: TOKENROUTE_API_KEY
    api_mode: chat_completions

model:
  provider: custom:tokenroute
  default: deepseek-v4-pro

密钥写进 ~/.hermes/.env：

TOKENROUTE_API_KEY=sk-你的Token

base_url 填根路径

填 https://api.smartwan.com/v1 即可，不要写成完整的 /chat/completions——Hermes 会自行拼接。也不要在已带 /v1 的地址后再加一个 /v1。

建议显式写上 api_mode: chat_completions，别依赖不同版本下的自动检测。

验证

hermes doctor
hermes chat

能正常返回模型回复即成功。日常启动直接 hermes，hermes model 查看和切换模型。

对接社交平台

Hermes 网关可以把 Agent 接到 IM 平台，在聊天窗口里直接对话。

通用流程

不管接哪个平台，步骤一样：

运行配置向导
```
hermes gateway setup
```
方向键选平台，Enter 确认。
扫码或手动填凭据 — 终端会显示二维码，用对应平台的手机 App 扫码即可自动获取凭据；已在开发者后台建好应用的，也可以直接粘贴 App ID、Secret
配置访问控制 — 按提示输入允许交互的用户 ID（逗号分隔），或选开放访问。设置写入 ~/.hermes/.env
启动网关
```
hermes gateway
```
前台运行，看到 [feishu] Connected 之类日志即连接成功，在平台里给机器人发消息测试。

一个网关进程可同时连多个平台：重复跑 hermes gateway setup 配置不同平台，再 hermes gateway 一次性启动全部。会话里 /platform list 查看各平台状态。

支持的平台

平台	连接方式	扫码创建	群聊	媒体支持	开发者后台
微信	长轮询	✅ 扫码登录	❌	图片 / 视频 / 文件 / 语音	mp.weixin.qq.com
钉钉	Stream Mode (WebSocket)	✅ 扫码获取凭据	✅ 需 @提及	图片 / 文件	open.dingtalk.com
飞书 / Lark	WebSocket / Webhook	✅ 扫码创建应用	✅	图片 / 文件 / 音频	open.feishu.cn

各平台的应用创建、权限申请和凭据获取以官方文档为准；Hermes 侧只需在向导里填入凭据。

微信额外需要装两个 Python 依赖：

pip install aiohttp cryptography

后台服务

确认连接正常后装成系统服务，开机自启、断线自动重连：

hermes gateway install

之后用这几个命令管理，不必一直开着终端：

hermes gateway start
hermes gateway stop
hermes gateway restart
hermes gateway status

排查问题看日志：

tail -f ~/.hermes/logs/gateway.log

Claude 模型优化（独立 Profile）

工具兼容性需要按请求验证

2026-09-22，claude-sonnet-5 接受了 1、13、32 个含嵌套对象、数组和枚举的工具定义；32 个工具在自动选择模式下也成功。因此不能将 12 个工具或 7 个工具集写成固定上限，也不能断言默认 Profile 必然失败。

工具集数量不等于 API 工具定义数量。兼容性还与 schema、请求体大小、版本和模型渠道有关；完整 Hermes 默认工具组合没有在本轮验证。

需要分别管理模型和工具时，可创建独立的 Claude Profile。下面的精简工具步骤用于排障，可按任务需要选择。

第一步：创建 Profile

先确认默认 Profile 已配好 TokenRoute（见上文），然后克隆：

hermes profile create claude --clone

会复制默认 Profile 的全部配置（含 custom_providers 里的密钥）、技能和记忆。Profile 路径 %LOCALAPPDATA%\hermes\profiles\claude\（Windows）。

设置模型和 Provider：

hermes -p claude config set model.default claude-sonnet-5
hermes -p claude config set model.provider custom:tokenroute
hermes -p claude config show

最终配置沿用上文的 Provider 和环境变量；确认该 Profile 能读取 TOKENROUTE_API_KEY：

model:
  default: claude-sonnet-5
  provider: custom:tokenroute

custom_providers:
  - name: tokenroute
    base_url: https://api.smartwan.com/v1
    key_env: TOKENROUTE_API_KEY
    api_mode: chat_completions

第二步：精简工具集

需要定位工具相关错误时，先减少工具，再逐步恢复；工具数量本身不能保证成功。

先看当前启用了哪些：

hermes -p claude tools list

逐条禁用多余的：

hermes -p claude tools disable browser
hermes -p claude tools disable code_execution
hermes -p claude tools disable vision
hermes -p claude tools disable image_gen
hermes -p claude tools disable tts
hermes -p claude tools disable skills
hermes -p claude tools disable session_search
hermes -p claude tools disable cronjob
hermes -p claude tools disable computer_use

以下是可按任务选用的 7 个工具集示例，并非必须保留的组合或数量上限：

工具集	功能	函数数
`web`	网络搜索和内容提取	少量
`terminal`	终端命令和进程管理	3
`file`	文件读写、搜索和编辑	4
`todo`	会话内任务规划	1
`memory`	跨会话持久记忆	1
`clarify`	向用户提问澄清	1
`delegation`	子代理任务委派	1

禁用 skills 后 /skill 名称 命令仍然可用（CLI 层命令不受影响），只是 AI 不再主动加载技能。临时开某个工具集用 hermes -p claude tools enable <name>，并重新验证实际请求。

第三步：使用

hermes -p claude

首次启动后输入 /new 确保新配置生效。

会话里 /model → 选 tokenroute 可切换 Claude 系列模型：claude-sonnet-5、claude-opus-5、claude-haiku-4-5。

单次查询：

hermes -p claude chat -q "你的问题"

两个 Profile 的差别

项目	默认 Profile	Claude Profile
启动命令	`hermes`	`hermes -p claude`
默认模型	`deepseek-v4-pro`	`claude-sonnet-5`
可用模型	以 Key 授权和渠道为准	以 Key 授权和渠道为准
工具集	以当前配置为准	按任务需要选择；可精简排障
配置隔离	—	完全独立

排查

报 "Third-party apps / extra usage"（HTTP 400） — 先记录完整错误及请求 ID，检查模型渠道、schema 和请求体；用最小工具集复现，再逐步恢复。不能仅凭该消息判断工具过多。

启动后无响应 — 先验证连通：

hermes -p claude chat -q "回复：测试连通性" --quiet

收到中文回复说明正常。报错就查 hermes -p claude config show 里的 model 和 provider。

模型列表显示 0 个 — 先检查所选 Profile 的 Provider、Key 与目录请求。不能仅凭显示为 0 就认定是无害的显示问题；按常见问题收集错误。

请求卡死、无响应也无报错 — 可能是凭据池被标记 exhausted。先重启 Hermes，再检查账户余额。

几个容易踩的点

工具集按任务选择；新增后验证实际请求，不采用固定 7 个上限
所有配置和工具集改动要重启 Hermes 或 /reset 开新会话才生效
Provider 名写 custom:tokenroute，要和 custom_providers 里 name: tokenroute 对应，不是 custom:api.smartwan.com
TokenRoute 走 OpenAI 兼容格式（/v1/chat/completions），建议显式设置 api_mode: chat_completions
两个 Profile 完全独立，改 Claude Profile 不会影响默认 Profile

安装​

配置 API 端点​

方式一：交互式向导​

方式二：手动编辑配置​

验证​

对接社交平台​

通用流程​

支持的平台​

后台服务​

Claude 模型优化（独立 Profile）​

第一步：创建 Profile​

第二步：精简工具集​

第三步：使用​

两个 Profile 的差别​

排查​

几个容易踩的点​

安装