agent-skills/autonomous-ai-agents/hermes-agent/references/custom-openai-compatible-providers.md

Custom OpenAI-Compatible Providers in Hermes

When a provider isn't built-in but offers an OpenAI-compatible /v1 endpoint, add it manually to config.yaml.

Steps

1. Find the base URL and API key env var — usually /v1 at the provider's domain.

2. List available models:

   curl -s "https://<provider>/v1/models" \
     -H "Authorization: Bearer $API_KEY" \
     --max-time 15 | python3 -m json.tool
   

   Note model id, input_modalities, context_length, supported_features.

3. Add provider to config.yaml via Python (don't hand-edit YAML — indentation errors break everything):

   import yaml, json, os
   
   config_path = os.path.expanduser("~/.hermes/config.yaml")
   with open(config_path) as f:
       config = yaml.safe_load(f)
   
   # Read API key from .env
   api_key = ""
   with open(os.path.expanduser("~/.hermes/.env")) as f:
       for line in f:
           if line.startswith("YOUR_KEY_PREFIX="):
               api_key = line.strip().split("=", 1)[1]
               break
   
   config.setdefault("providers", {})["your-provider"] = {
       "api_key": api_key,
       "base_url": "https://provider.example.com/v1",
       "available_models_json": json.dumps([
           {"id": "model-id", "name": "Display Name"},
       ]),
       "model": "default-model-id",
       "model_display_name": "Default Display Name"
   }
   
   with open(config_path, "w") as f:
       yaml.dump(config, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
   

4. Verify with a test call:

   curl -s "https://provider.example.com/v1/chat/completions" \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model":"model-id","messages":[{"role":"user","content":"hi"}],"max_tokens":100}'
   

5. Use the model: hermes -m your-provider/model-id or via hermes model picker.

Provider Config Fields

Field	Required	Notes
api_key	Yes	Actual key value, not env var reference
base_url	Yes	Must end with /v1 (or /v1/)
available_models_json	Yes	JSON string of [{id, name}] array
model	No	Default model ID
model_display_name	No	Human-readable default model name
api_mode	No	Only set if non-standard (e.g. anthropic-messages for MiniMax). Omit for OpenAI-compatible.
protocol	No	Usually leave as ''

Pitfalls

• Don't hand-edit YAML — use Python yaml.safe_load + yaml.dump to avoid indentation corruption.
• api_key must be the actual value, not $ENV_VAR — Hermes doesn't resolve env vars inside provider config (only in .env).
• No api_mode needed for OpenAI-compatible — only set this for providers with custom protocols (Anthropic Messages, etc.).
• reasoning field in responses — some providers (SenseNova, DeepSeek) return a reasoning field in the message object. Hermes handles this natively for reasoning-capable models.
• Model discovery — always call /v1/models first; don't guess model IDs from documentation (they change).

Known Custom Providers

Provider	Base URL	Key Env Var	Models
SenseNova	https://token.sensenova.cn/v1	SN_API_KEY	sensenova-6.7-flash-lite, deepseek-v4-flash, sensenova-u1-fast