Hermes Agent setup: installation, API key, Base URL, and custom models

To connect Hermes Agent to BetterToken, prepare an API key, enter the Base URL shown below, and choose a current Model ID from the model plaza.

Key settings

Field	Value
API Key	BetterToken API key
Base URL	`https://bettertoken.ai/v1`
Model	A current Model ID from the model plaza

Prerequisites

The current version of the tool is installed
A BetterToken API key: register and get one
A Model ID from the model plaza

Additional requirements

Copy the exact Model ID from the model plaza.
macOS, Linux, Windows 10/11, or WSL2
A model with at least a 64K context window for Hermes Agent tool use

Install

Install Hermes Agent

Desktop (macOS / Windows)
Linux / macOS / WSL2
Windows PowerShell

Hermes recommends the Desktop installer for macOS and Windows. Download Hermes Desktop and run the installer for your operating system.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

When installation finishes, open a new terminal or reload your shell before running hermes.

Hermes Agent supports native Windows 10 and Windows 11. Open PowerShell or Windows Terminal and run:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Administrator rights are not required. Open a new PowerShell window after installation so the updated User PATH is available.

Verify the installation:

hermes --version
hermes doctor

WSL2 remains supported, but it is optional. Use it when you specifically need a Linux environment or the web dashboard’s embedded terminal pane.

Feature quick reference

Feature	What it is for
Terminal UI	Chat with the agent directly in your terminal
Skills	Save reusable workflows for repeated tasks
MCP	Connect local or remote tool capabilities
Scheduled tasks	Run timed jobs and recurring workflows
Subagents	Split complex work across focused agents
Message gateway	Connect the agent to more message entry points

Manual setup

Use the interactive Hermes Agent model setup as the primary path. Edit the configuration files only when you need a manual setup.

Field	Value
API Key	BetterToken API key
Base URL	`https://bettertoken.ai/v1`
Model	A current Model ID from the model plaza

Setup

Interactive setup
Config files

Run the model selector

Exit any active Hermes chat first, then run:

hermes model

Choose Custom endpoint

Select Custom endpoint (self-hosted / VLLM / etc.) from the provider list.

Fill in the BetterToken config

Enter:

Base URL: https://bettertoken.ai/v1
API Key: your BetterToken API Key
Model: a model ID copied from the model plaza

If Hermes asks for an API mode, choose the OpenAI-compatible Chat Completions option. If it asks for context length, use the value published for that model and make sure it is at least 64K.

Start Hermes Agent

hermes --tui

You can also run hermes to use the classic terminal interface.

The interactive setup is safer because it validates and stores the endpoint for you. For a manual setup, add the non-secret model settings to ~/.hermes/config.yaml:

model:
  default: YOUR_MODEL_ID
  provider: custom
  base_url: "https://bettertoken.ai/v1"

Store the API Key separately in ~/.hermes/.env:

OPENAI_API_KEY=YOUR_API_KEY

On native Windows, these files live under %LOCALAPPDATA%\hermes\ instead of ~/.hermes/. Replace YOUR_MODEL_ID and YOUR_API_KEY, then run hermes doctor before starting Hermes.

Migrate from OpenClaw

If you already use OpenClaw, first check whether your current Hermes Agent version provides the migration command. Run a dry run before changing anything.

hermes claw migrate --dry-run

After you confirm the output, run the migration:

hermes claw migrate

After migration, still review the Hermes Agent Base URL, API Key, and model ID. They should match https://bettertoken.ai/v1, your BetterToken API Key, and a model ID.

Verify the connection

Start Hermes with hermes --tui or hermes, then send this short prompt:

Reply with HERMES_OK only. Do not use tools.

The connection works when Hermes returns HERMES_OK without an authentication, endpoint, or Model ID error. Then try one small read-only task before enabling gateways, scheduled tasks, or additional tools.

Switch models

Run hermes model outside a chat to add or reconfigure a provider. Inside an active chat, use /model to switch between providers and models you already configured. Use the exact Model ID from the model plaza.

Common errors

Error	What to check
`401` or `Unauthorized`	Check the BetterToken API key and remove leading or trailing spaces.
`404`	Check the Base URL and do not append a specific endpoint path.
`model not found`	Copy a current Model ID from the model plaza.
`hermes: command not found`	Open a new terminal after installation, then check the PATH.
Configuration error after update	Run `hermes config check`, then `hermes config migrate` if prompted.

Troubleshooting

If requests fail or return no response, confirm that Base URL is exactly https://bettertoken.ai/v1. Do not append /chat/completions in this field.
If Hermes reports that the model does not exist, confirm that Model is a model ID from the model plaza.
Copy the exact Model ID from the model plaza.
If Hermes still uses the old model, exit the chat, run hermes model, save the custom endpoint again, and start a new chat.
BetterToken usually does not require an extra User-Agent or custom headers. Only add headers when your custom gateway, tenant routing, observability, or caching layer explicitly requires them.

Do not commit real API Keys to your repository. For team-shared setup, prefer environment variables or local config.

Technical details

Protocol, endpoint, and internal provider fields

This setup uses https://bettertoken.ai/v1. The tool appends the OpenAI-compatible endpoint path. Do not add /chat/completions or /responses unless a specific field explicitly requires it.

Getting started

Coding Agent setup

AI application platform setup

Advanced

Hermes Agent setup: installation, API key, Base URL, and custom models

Key settings

Prerequisites

Additional requirements

Install

Install Hermes Agent

Feature quick reference

Manual setup

Setup

Migrate from OpenClaw

Verify the connection

Switch models

Common errors

Troubleshooting

Technical details

Official Hermes references

​Key settings

​Prerequisites

​Additional requirements

​Install

​Install Hermes Agent

​Feature quick reference

​Manual setup

​Setup

​Migrate from OpenClaw

​Verify the connection

​Switch models

​Common errors

​Troubleshooting

​Related FAQ

​Technical details

​Official Hermes references

Key settings

Prerequisites

Additional requirements

Install

Install Hermes Agent

Feature quick reference

Manual setup

Setup

Migrate from OpenClaw

Verify the connection

Switch models

Common errors

Troubleshooting

Related FAQ

Technical details

Official Hermes references