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
- Open https://ai2save.com/keys.
- Create a key and select the group that contains the target model.
- Copy the complete
sk-...Key. - 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/completionsbased 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
- Completely exit the current Hermes session or Gateway.
- Restart Hermes.
- Start a new session and send a short question.
- Enter
/modelin the session to confirm that the current model iscustom/gpt-5.5orgpt-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_KEYdoes not exist or the value is incomplete. Executehermes config get model.key_envto check the reference. - 404 / model not found:
model.defaultis not a real model ID open in the console. - Connection failed:
base_urlshould behttps://ai2save.com/v1; do not write it ashttps://ai2save.com. - Configuration not effective: The old
OPENAI_BASE_URLonly affectsopenai-apiProvider, it will not automatically apply tocustom; checkconfig.yamlformodel.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.