Hermes

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

安装

系统	命令
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）

用 Claude 必读

Claude 模型经 TokenRoute 路由到 Anthropic API 时有工具 schema 复杂度限制——请求里工具定义过多（约 12 个以上复杂工具）会直接触发 HTTP 400。

而 Hermes 默认启用 20+ 个工具集，直接拿默认 Profile 调 Claude 必然失败。

解决办法：建一个独立的 Claude Profile，只留 7 个核心工具集，用 hermes -p claude 启动。配置完全隔离，不影响默认 Profile 继续用 DeepSeek、GPT 等模型。

第一步：创建 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:gss
hermes -p claude config show

最终配置应包含：

model:
  default: claude-sonnet-5
  provider: custom:gss
  base_url: https://api.smartwan.com/v1
  api_key: sk-你的Token      # 从默认 Profile 继承，无需重填

custom_providers:
  - name: GSS
    base_url: https://api.smartwan.com/v1
    api_key: sk-你的Token
    model: claude-sonnet-5

第二步：精简工具集

这一步决定 Claude 能不能用

必须精简到 7 个工具集，否则每次请求都会 400。

先看当前启用了哪些：

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 → 选 GSS 可切换 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`
可用模型	全部	仅 Claude 系列
工具集	20+ 全开	7 个核心
配置隔离	—	完全独立

排查

报 "Third-party apps / extra usage"（HTTP 400） — 工具集超了。hermes -p claude tools list 看数量，多的用 tools disable 关掉，改完 /reset 或重启。

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

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

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

模型列表显示 0 个 — 已知显示问题。跑一次 hermes -p claude tools list 触发配置刷新后重启。仍为 0 也不影响使用。

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

几个容易踩的点

工具集数量必须守住 7 个，加新工具集前先确认不会触发限制
所有配置和工具集改动要重启 Hermes 或 /reset 开新会话才生效
Provider 名写 custom:gss，要和 custom_providers 里 name: GSS 对应，不是 custom:api.smartwan.com
TokenRoute 走 OpenAI 兼容格式（/v1/chat/completions），这里不需要设 api_mode
两个 Profile 完全独立，改 Claude Profile 不会影响默认 Profile

安装​

配置 API 端点​

方式一：交互式向导​

方式二：手动编辑配置​

验证​

对接社交平台​

通用流程​

支持的平台​

后台服务​

Claude 模型优化（独立 Profile）​

第一步：创建 Profile​

第二步：精简工具集​

第三步：使用​

两个 Profile 的差别​

排查​

几个容易踩的点​

安装