Hermes

Nous Research's command-line agent, with multi-profile support, toolset management and social platform gateways.

Before you start

You need an API Key with available quota. Copy model names from the model list — they are case-sensitive.

Windows one-click setup

Don't want to edit config.yaml and .env by hand? Install and launch Hermes once first, then use GSS Deploy (Windows one-click setup) to write configuration automatically. Windows only.

Installation

OS	Command
Windows	iex (irm https://hermes-agent.nousresearch.com/install.ps1) (PowerShell, runs natively — no WSL needed)
macOS / Linux	curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

The installer pulls in Python 3.11, uv, Node.js, ripgrep, ffmpeg, Git Bash and other dependencies automatically. Mainstream Linux distributions are supported (Ubuntu, Debian, CentOS, Arch, …).

Don't use sudo

Hermes is designed to install and run as an ordinary user; the install script handles PATH itself.

Verify:

hermes --version
hermes doctor

Configuring the API endpoint

Method 1: Interactive wizard

hermes model

Choose Custom endpoint (self-hosted / VLLM / etc.), then enter:

Prompt	What to enter
API base URL	https://api.smartwan.com/v1
API Key	Your API Key
Model name	Pick one from Models
api_mode	chat_completions

Context length can be left blank for auto-detection. The model list is usually fetched from the endpoint automatically; if that fails, type the model ID by hand.

Method 2: Editing the config by hand

Config file location:

• 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

Put the key in ~/.hermes/.env:

TOKENROUTE_API_KEY=sk-your-token

base_url takes the root path

https://api.smartwan.com/v1 is enough — do not write the full /chat/completions; Hermes appends it itself. And don't add a second /v1 to a URL that already has one.

Set api_mode: chat_completions explicitly rather than relying on auto-detection, which varies between versions.

Verify

hermes doctor
hermes chat

A normal model reply means you're set. For daily use just run hermes; hermes model shows and switches models.

Connecting social platforms

The Hermes gateway can attach the agent to IM platforms so you can talk to it in a chat window.

General flow

The steps are identical regardless of platform:

1. Run the setup wizard

   hermes gateway setup

   Select a platform with the arrow keys, confirm with Enter.

2. Scan a QR code or enter credentials — the terminal displays a QR code; scanning it with the platform's mobile app fetches credentials automatically. If you've already created an app in the developer console, paste the App ID and Secret directly.

3. Configure access control — enter the user IDs allowed to interact (comma-separated) when prompted, or choose open access. Settings are written to ~/.hermes/.env.

4. Start the gateway

   hermes gateway

   It runs in the foreground; a log line like [feishu] Connected means it's connected. Send the bot a message on the platform to test.

One gateway process can serve several platforms at once: run hermes gateway setup again for each, then hermes gateway to start them all. Use /platform list in a session to check each platform's status.

Supported platforms

Platform	Connection	QR setup	Group chat	Media support	Developer console
WeChat	Long polling	✅ QR login	❌	Image / video / file / voice	mp.weixin.qq.com
DingTalk	Stream Mode (WebSocket)	✅ QR credentials	✅ requires @mention	Image / file	open.dingtalk.com
Feishu / Lark	WebSocket / Webhook	✅ QR app creation	✅	Image / file / audio	open.feishu.cn

For app creation, permission requests and credential retrieval, follow each platform's official documentation; on the Hermes side you only enter the credentials in the wizard.

WeChat additionally needs two Python dependencies:

pip install aiohttp cryptography

Running as a background service

Once the connection is confirmed, install it as a system service for start-on-boot and automatic reconnection:

hermes gateway install

Then manage it with these commands, without keeping a terminal open:

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

Check the logs when troubleshooting:

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

Optimizing for Claude models (a separate profile)

Verify tool compatibility per request

On 2026-09-22, claude-sonnet-5 accepted 1, 13 and 32 tool definitions with nested objects, arrays and enums; 32 tools also passed with automatic tool choice. Neither 12 tools nor 7 toolsets is an established fixed limit, and the default profile cannot be described as guaranteed to fail.

A toolset is not the same as an API tool definition. Compatibility also depends on schemas, request size, versions and model routes. The complete default Hermes toolset was not tested in this run.

Use a separate Claude profile when you want separate model and tool settings. The optional tool reduction steps below help diagnose errors; choose tools for your task.

Step 1: Create the profile

Confirm the default profile is already configured for TokenRoute (see above), then clone it:

hermes profile create claude --clone

This copies the default profile's entire configuration (including keys in custom_providers), skills and memories. The profile lives at %LOCALAPPDATA%\hermes\profiles\claude\ on Windows.

Set the model and 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

Keep the same provider and environment variable as above, and make sure this profile can read 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

Step 2: Trim the toolsets

For tool-related errors, reduce tools and restore them gradually. Tool count alone cannot guarantee success.

See what's currently enabled:

hermes -p claude tools list

Disable the extras one by one:

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

These seven toolsets are examples to choose from, not a mandatory combination or a count limit:

Toolset	Purpose	Functions
web	Web search and content extraction	few
terminal	Shell commands and process management	3
file	File read/write, search and editing	4
todo	In-session task planning	1
memory	Persistent cross-session memory	1
clarify	Asking the user for clarification	1
delegation	Delegating tasks to sub-agents	1

Disabling skills leaves the /skill <name> command working (CLI-level commands are unaffected) — the AI simply stops loading skills on its own. To enable a toolset temporarily use hermes -p claude tools enable <name>, and verify the actual request again.

Step 3: Use it

hermes -p claude

After the first launch, type /new to make sure the new configuration takes effect.

In a session, /model → select tokenroute switches between Claude models: claude-sonnet-5, claude-opus-5, claude-haiku-4-5.

One-off query:

hermes -p claude chat -q "your question"

How the two profiles differ

Aspect	Default profile	Claude profile
Launch command	hermes	hermes -p claude
Default model	deepseek-v4-pro	claude-sonnet-5
Available models	Subject to key permissions and routes	Subject to key permissions and routes
Toolsets	Current configuration	Choose for the task; reduce for diagnosis
Config isolation	—	Fully independent

Troubleshooting

"Third-party apps / extra usage" (HTTP 400) — record the complete error and request ID, check model routes, schemas and request size, then reproduce with minimal tools and restore them gradually. This message alone does not prove there are too many tools.

No response after launch — verify connectivity first:

hermes -p claude chat -q "reply: connectivity test" --quiet

A reply means things are working. On error, check the model and provider in hermes -p claude config show.

Model list shows 0 models — check the selected profile, provider, key and catalog request first. A zero count alone does not establish a harmless display issue; collect details using the FAQ.

Requests hang with no response and no error — the credential pool may be marked exhausted. Restart Hermes first, then check your account balance.

Common pitfalls

1. Choose toolsets for the task and verify requests after adding them; do not use a fixed limit of seven
2. Configuration and toolset changes require a Hermes restart or /reset for a new session
3. The provider name is custom:tokenroute, matching name: tokenroute in custom_providers — not custom:api.smartwan.com
4. TokenRoute uses the OpenAI-compatible format (/v1/chat/completions), so explicitly set api_mode: chat_completions
5. The two profiles are fully independent; changing the Claude profile never affects the default one