gahorouter 文档

English

简体中文

English

简体中文

Appearance

Hermes Integration Guide for the gahorouter API ​

This tutorial assumes you have already registered a gahorouter account and obtained your API Key. Below we only cover how to configure things on the Hermes side.

1. Prerequisites ​

  • A Linux / macOS / WSL2 machine (Windows requires installing WSL2 first)
  • Your gahorouter API Key (a string that looks like sk-xxxx...)
  • The name of the model you want to use (for example, claude-sonnet-4-6)

2. Install the Hermes Agent ​

Open a terminal, paste the following single command, and press Enter:

bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Wait for it to finish (about 1-3 minutes), then run:

bash
source ~/.bashrc

Verify the installation succeeded:

bash
hermes --version

You should see output similar to this:

Hermes Agent v0.9.0 (2026.6.1)

If you get command not found, close the terminal, reopen it, and try again.

3. Understand What Needs to Change ​

All of Hermes's configuration lives in these files:

~/.hermes/config.yaml  <-- main configuration file
~/.hermes/.env         <-- stores the API Key (secret)

We need to do two things:

  1. Write the API Key into the .env file
  2. Point the model settings in config.yaml to gahorouter

4. Configure the API Key ​

4.1 Open the .env File ​

bash
nano ~/.hermes/.env

If you are not familiar with nano, you can also open this file with any text editor.

4.2 Add Your gahorouter API Key ​

Add a line to the file (replace sk-xxx with your own real Key):

ANTHROPIC_API_KEY=sk-xxxYourgahorouterKeyxxx

4.3 Save and Exit ​

If you are using nano: press Ctrl+O to save, Ctrl+X to exit.

5. Configure config.yaml ​

5.1 Open the Configuration File ​

bash
nano ~/.hermes/config.yaml

5.2 Find the model: Section at the Top of the File ​

If this is your first installation, the default may look like this:

yaml
model:
  model: ''
  provider: ''

5.3 Change It to the Following ​

yaml
model:
  base_url: https://console.gahorouter.com
  model: claude-sonnet-4-6
  provider: anthropic

Line-by-line explanation:

  • base_url —— the gahorouter API address, replacing the default api.anthropic.com
  • model —— the name of the model you want to use
  • provider —— always set to anthropic, telling Hermes to use the Anthropic Messages API protocol

5.4 Save and Exit ​

Ctrl+O to save, Ctrl+X to exit.

6. Verify the Configuration ​

6.1 Start Hermes ​

bash
hermes

6.2 Send a Message to Test ​

After entering Hermes, type: hello

If everything is working, you will see a reply from the AI. Congratulations, the configuration succeeded!

6.3 What If You Get an Error? ​

Common errors and their solutions:

  • Error: authentication_error / invalid api key
    • Cause: the API Key is wrong, or it was not written correctly into the .env file
    • Solution: check whether ANTHROPIC_API_KEY in ~/.hermes/.env is correct, with no spaces before or after it
  • Error: connection error / timeout
    • Cause: a network problem; cannot reach gahorouter
    • Solution: check your network and try whether curl https://console.gahorouter.com connects
  • Error: model not found
    • Cause: the model name is misspelled
    • Solution: check the model field in config.yaml and confirm that gahorouter supports this model name
  • Error: Hermes does not respond / uses a different Key
    • Cause: there may be multiple conflicting variables set in .env at the same time
    • Solution: if you only use gahorouter, keep only ANTHROPIC_API_KEY in .env, and delete or comment out the others such as OPENAI_API_KEY, OPENROUTER_API_KEY

7. Complete Configuration File Example ​

Below is a minimal working config.yaml (keeping only the essential parts):

yaml
model:
  base_url: https://console.gahorouter.com
  model: claude-sonnet-4-6
  provider: anthropic
providers: {}
fallback_providers: []
toolsets:
  - hermes-cli
agent:
  max_turns: 90

The corresponding .env file:

ANTHROPIC_API_KEY=sk-YourgahorouterKey

8. Advanced: Configuring Multiple Providers at Once ​

If you also want to use other APIs (for example, DeepSeek), you can add the following at the bottom of config.yaml:

yaml
custom_providers:
  - name: deepseek
    base_url: https://api.deepseek.com
    key_env: DEEPSEEK_API_KEY

Then add to .env:

DEEPSEEK_API_KEY=YourDeepSeekKey

9. Fallback: Automatically Switching to a Backup API ​

When the primary API fails (rate limiting, overload, connection failure), Hermes can automatically switch to a backup API. The entire process requires no manual intervention and is almost imperceptible to the user.

9.1 Trigger Conditions ​

The following situations automatically activate fallback:

  • 429 rate limiting / quota exhausted (the primary API cools down for about 1 hour)
  • 503 / 529 service overload
  • Connection failure / DNS resolution failure
  • Timeout
  • Model does not exist

Trigger logic: after the primary API fails 3 consecutive retries, it automatically switches to the fallback.

Note: fallback is activated only once per session; once activated, the backup API is used for the entire current session.

9.2 Configuring a Single Fallback ​

Add the following at the top level of config.yaml (not inside model, not inside custom_providers):

yaml
fallback_model:
  provider: custom
  model: deepseek-chat
  base_url: https://api.deepseek.com
  api_key_env: DEEPSEEK_API_KEY

At the same time, add the backup API's secret to ~/.hermes/.env:

DEEPSEEK_API_KEY=sk-YourDeepSeekKey

With this configuration, when the gahorouter primary API goes down, it automatically switches to DeepSeek (which can also be another model or provider).

9.3 Configuring a Multi-Level Fallback Chain ​

If you want to configure multiple backup APIs to be tried in order, use fallback_providers (list format):

yaml
fallback_providers:
  - provider: custom
    model: deepseek-chat
    base_url: https://api.deepseek.com
    api_key_env: DEEPSEEK_API_KEY
  - provider: openrouter
    model: anthropic/claude-sonnet-4-6
    # requires OPENROUTER_API_KEY to be written into .env

9.4 Verifying That Fallback Takes Effect ​

When fallback is activated, Hermes displays a prompt at the bottom of the interface:

🔄 Fallback model: deepseek-chat (custom)

The log will also show:

Fallback activated: claude-sonnet-4-6 → deepseek-chat (custom)

9.5 Providers Supported as Fallback ​

Built-in providers (just write the provider name, no base_url needed):

openrouter   -- requires OPENROUTER_API_KEY
zai          -- requires ZAI_API_KEY
kimi-coding  -- requires KIMI_API_KEY
minimax      -- requires MINIMAX_API_KEY
deepseek     -- requires DEEPSEEK_API_KEY (built-in support)

Custom OpenAI-compatible endpoint (requires specifying base_url and api_key_env):

yaml
fallback_model:
  provider: custom
  model: model-name
  base_url: https://your-API-address
  api_key_env: name-of-the-env-var-storing-the-key

9.6 Complete Configuration Example (gahorouter primary + DeepSeek backup) ​

config.yaml:

yaml
model:
  base_url: https://console.gahorouter.com
  model: claude-sonnet-4-6
  provider: anthropic

fallback_model:
  provider: custom
  model: deepseek-chat
  base_url: https://api.deepseek.com
  api_key_env: DEEPSEEK_API_KEY

custom_providers:
  - name: deepseek
    base_url: https://api.deepseek.com
    key_env: DEEPSEEK_API_KEY

.env:

ANTHROPIC_API_KEY=sk-YourgahorouterKey
DEEPSEEK_API_KEY=sk-YourDeepSeekKey