ai2saveai2save

Hermes Agent Configuration Tutorial

The models, vendors, and custom endpoints for Hermes Agent are stored in ~/.hermes/config.yaml; sensitive information like API Key is stored in ~/.hermes/.env. ai2save uses the OpenAI Compatible interface, and Base URL is https://ai2save.com/v1.

1. Create API Key

  1. Open https://ai2save.com/keys.
  2. Create a key and select the group that contains the target model.
  3. Copy the complete sk-... Key.
  4. Record the real model ID displayed in the console, for example, gpt-5.5.

2. Recommended Use of the Built-in Wizard

Run in the terminal:

hermes model

Select according to the instructions:

Custom endpoint (self-hosted / vLLM / etc.)

Enter in order:

API base URL: https://ai2save.com/v1
API key: sk-your-api-key
Model name: gpt-5.5

The wizard will write these values into ~/.hermes/config.yaml. Do not write Base URL to .env; Hermes officially stipulates that the model endpoint configuration comes from config.yaml.

3. Manually Edit the Configuration File

Edit ~/.hermes/config.yaml:

model:
  provider: custom
  default: gpt-5.5
  base_url: https://ai2save.com/v1
  key_env: AI2SAVE_API_KEY

Field Description:

  • provider: custom: Use any OpenAI Compatible endpoint.
  • default: Default model ID, must match the model ID opened in the console exactly.
  • base_url: Must include /v1, Hermes will request /chat/completions based on this.
  • key_env: Points to the environment variable name where the key is stored.

Edit ~/.hermes/.env:

AI2SAVE_API_KEY=sk-your-api-key

.env stores sensitive information, config.yaml stores non-sensitive model configuration. Do not commit .env to Git.

4. Use configuration commands to write

You can also use the commands provided by Hermes to avoid YAML indentation errors:

hermes config set model.provider custom
hermes config set model.default gpt-5.5
hermes config set model.base_url https://ai2save.com/v1
hermes config set model.key_env AI2SAVE_API_KEY
hermes config set AI2SAVE_API_KEY sk-your-api-key
hermes config check

AI2SAVE_API_KEY is an uppercase environment variable name, and Hermes will automatically write ~/.hermes/.env.

5. Restart and Verify

  1. Completely exit the current Hermes session or Gateway.
  2. Restart Hermes.
  3. Start a new session and send a short question.
  4. Enter /model in the session to confirm that the current model is custom/gpt-5.5 or gpt-5.5.

Temporarily use a specified model:

hermes chat --provider custom --model gpt-5.5

For the first verification, it is recommended to disable parallel tasks and complex tools, and only send short texts. After authentication and model connectivity are established, gradually enable tools such as terminal, web, and file.

6. Common Errors

  • 401 / invalid_api_key: AI2SAVE_API_KEY does not exist or the value is incomplete. Execute hermes config get model.key_env to check the reference.
  • 404 / model not found: model.default is not a real model ID open in the console.
  • Connection failed: base_url should be https://ai2save.com/v1; do not write it as https://ai2save.com.
  • Configuration not effective: The old OPENAI_BASE_URL only affects openai-api Provider, it will not automatically apply to custom; check config.yaml for model.base_url.
  • YAML parsing failed: Do not have duplicate model: blocks; merge all fields in the same block.
  • Tool call exception: First ensure the model supports tool calling, and use a short text request to establish a baseline before enabling the toolset.