What is Hermes Agent?
Hermes Agent is an open-source personal agent from Nous Research with persistent memory, tool use, and skills.
This Hermes Agent setup uses its built-in Tencent TokenHub provider and stores TOKENHUB_API_KEY in the documented environment file. Select an available model from the live catalog before testing a safe task. Hermes Agent can combine persistent memory, skills, tools, and different user interfaces, but those interfaces do not replace the underlying provider configuration. Install from the official Nous Research project, protect the environment file, and evaluate tool success, context needs, latency, and operating cost on a real but low-risk task.
Hermes Agent can route model requests through TokenHub's OpenAI compatible API gateway. Keep the official installation flow, then replace only the API key, Base URL, and model ID.
The TokenHub endpoint used by this guide is https://us-api.tokenhub.com/v1/chat/completions.
When to use it
Start in a small repository or test project. First ask the tool to read files, explain code, or produce a plan; only then enable edits, terminal commands, or agent automation.
Install or open the tool
Follow the official Hermes Agent documentation to install or open the tool. If menus or command names differ, prefer the current official documentation.
For CLI tools, confirm the executable works before adding TokenHub credentials:
hermes --versionPrepare TokenHub credentials
Create a TokenHub API key and choose a model from the TokenHub model list that fits this tool.
export TOKENHUB_API_KEY="sk-..."Keep the key in your local shell, IDE secret storage, or the secure API key field of the tool. Do not commit it to the repository.
Configure TokenHub persistently
Use the tool configuration file or settings page first. This avoids the common problem where a terminal sees the environment variable but the IDE, plugin, or new window does not.
Provider values
| Field | Value |
|---|---|
| Provider | OpenAI Compatible or Custom |
| Base URL | https://us-api.tokenhub.com/v1 |
| API Key | The value of TOKENHUB_API_KEY |
| Model | gpt-4.1 or another TokenHub model ID |
Settings file locations
| Field | Value |
|---|---|
| Secret | ~/.hermes/.env |
| Provider and model config | ~/.hermes/config.yaml |
| Named custom provider | tokenhub-custom |
TOKENHUB_API_KEY=sk-...custom_providers:
- name: tokenhub-custom
base_url: '__API_BASE_URL__/v1'
key_env: TOKENHUB_API_KEY
api_mode: chat_completions
model:
provider: 'custom:tokenhub-custom'
default: 'gpt-4.1'This follows Hermes' current named custom provider schema: base_url is the OpenAI-compatible Base URL, key_env reads the secret without writing it into YAML, and api_mode: chat_completions selects /v1/chat/completions.
Always keep the custom: prefix. Hermes treats bare tokenhub as a built-in provider alias; custom:tokenhub-custom unambiguously selects this self-hosted endpoint.
/model custom:tokenhub-custom:gpt-4.1hermes chatHermes stores the named custom provider, Base URL, API mode, and default model in ~/.hermes/config.yaml. The API key remains in ~/.hermes/.env. You can also run hermes model, select Custom Endpoint, and enter the same values interactively.
If the tool separates chat, edit, apply, and fast models, use the same TokenHub model for the first test. Split models later by cost, latency, and reasoning strength.
Temporary environment variables for debugging
Use temporary variables only to confirm the key, network, and model name. After validation, move the same values into the persistent configuration above.
export TOKENHUB_API_KEY="sk-..."Verify the connection
Test with a read-only prompt first, confirming that the model can read context without changing files. Then test edits, Apply, or agent tasks.
Read the project README and summarize it in three sentences. Do not modify any files.After a successful prompt, check TokenHub request logs for model name, endpoint, token usage, and billing group.
Troubleshooting
| Symptom | Fix |
|---|---|
| 401 or authentication failure | Confirm TOKENHUB_API_KEY is valid and saved in the same terminal, IDE, or client profile. |
| 404 or model not found | Use a model ID that exists in your TokenHub workspace and matches the selected protocol. |
| Wrong endpoint | Keep the Base URL exactly as shown. OpenAI-compatible tools usually need /v1; Claude-compatible tools usually do not. |
| Request timeout | Check network access to https://us-api.tokenhub.com, proxy settings, and workspace allowlists. |
| Tool uses another model | Recheck every chat, edit, apply, fast, and autocomplete model slot. |
Choose a compatible Hermes Agent model
Hermes Agent setup FAQ
Which provider should I select in Hermes Agent?
Select Tencent TokenHub in hermes model. Its documented provider ID is tencent-tokenhub, with tokenhub as an alias.
Where should the TokenHub API key go?
Store TOKENHUB_API_KEY=... in ~/.hermes/.env, which is the credential file Hermes Agent documents for this provider.
Why should I not hard-code a model from this guide?
The Tencent TokenHub catalog is live and available models can change. Choose a model shown by hermes model or enter an exact currently available ID.
How are Hermes Agent and Nous Research related?
Hermes Agent is an open-source agent project from Nous Research. Company funding or valuation searches are outside this integration guide.
How should I compare Hermes Agent with OpenClaw?
Use the same real task to compare deployment, memory, skills, channel integrations, tool reliability, model cost, and maintenance complexity.
References
This setup is based on TokenHub and official documentation, last verified on 2026-09-04.