Hermes Custom LLM Endpoints
How to point Hermes Agent at an LLM endpoint other than the built-in providers' hardcoded URLs. Most relevant when the user has obtained an API key from a third-party proxy, aggregator, or self-hosted OpenAI-compatible service, and the built-in minimax-cn / openai / anthropic providers don't match.
When to use this skill
Use this skill when ANY of the following:
- User has an
sk-...style key from a non-standard provider - User mentions a URL like
https://*.com/v1that isn't in Hermes's built-in provider list hermes chat -q "..."returns 401/404/502 and the error message says the wrong endpoint or wrong key- The user wants to switch from a paid official API to a cheaper proxy
hermes modelinteractive picker has no option for the user's provider
Do NOT use this skill if:
- User is just changing models within the same provider — use
hermes modelorhermes config set model.default <name> - User is using Nous Portal / OpenRouter / DeepSeek (these are built-in providers)
- User wants local Ollama — use the
ollamaprovider, which is built-in
The hardcoded provider base_url trap (CRITICAL)
Hermes's built-in providers (minimax-cn, openai, anthropic, etc.) have hardcoded base URLs in the SDK code. The MINIMAX_BASE_URL / OPENAI_BASE_URL / similar env vars do NOT override them at the agent loop level — Hermes reads the provider's hardcoded URL when constructing the request.
Symptom: .env says MINIMAX_BASE_URL=https://my-proxy.com/v1 and MINIMAX_CN_API_KEY=sk-xxx, but requests still go to https://api.minimaxi.com/v1 and return 401 ("login fail: API secret key invalid") because the proxy key is being sent to the wrong endpoint.
Fix: Switch to the generic OpenAI-compatible custom provider:
hermes config set model.provider custom
hermes config set model.base_url https://my-proxy.com/v1
hermes config set model.api_key sk-xxx-...
hermes config set model.default <model-id>
Then restart the gateway or start a fresh CLI session; hermes config reload is not a valid command, and running gateway/CLI processes read config at startup.
Workflow: probe -> configure -> verify
Never write credentials to .env based on a hunch. Follow this sequence:
1. Probe the endpoint (1-3 second check, no side effects)
Run the bundled probe script:
python ~/.hermes/skills/devops/hermes-llm-endpoints/scripts/probe_endpoint.py \
https://my-proxy.com/v1 sk-xxx-...
Status code meanings:
- exit 0, models listed -> real LLM proxy, key works
- exit 1, 401 -> endpoint up, key rejected (ask user for new key)
- exit 2, 404 -> wrong path, try
/api/v1/modelsor other paths - exit 3,
DNS_FAIL-> fake domain, abort immediately (do not edit .env) - exit 4, 5xx -> upstream unstable, retry 2-3 times before declaring dead
2. Verify the key with a minimal completion
Hit /v1/chat/completions with a tiny ping prompt to confirm the model id exists and the proxy can actually serve completions (not just list models).
3. Configure Hermes
Only after steps 1 and 2 pass, switch to the custom provider:
hermes config set model.provider customhermes config set model.base_url https://my-proxy.com/v1hermes config set model.api_key sk-xxx-...hermes config set model.default <model-id>
Do NOT also write the key to .env for this provider. The model.api_key in config.yaml is authoritative. Setting it in .env too creates two sources of truth and confuses the next agent that reads the file.
4. Verify end-to-end via CLI before restarting the gateway
hermes chat -q "answer with one digit: 1+1=?" -m <model-id>
If this returns the correct answer, the gateway will too — same config, same code path.
5. Restart gateway, then test via the messaging platform
If the gateway is installed as a service, restart it normally:
hermes gateway restart --profile <name>
If the gateway is not installed as a service and is being run manually, hermes gateway restart can stop the current process and then fail with "Gateway service is not installed". In that case, bring it back with a fresh manual run instead of assuming restart succeeded:
hermes gateway status
hermes gateway run
Then verify status/logs and send a real platform message:
hermes gateway status
tail -20 ~/.hermes/profiles/<name>/logs/gateway.log
Then send a real test message from the platform (Feishu DM, Telegram, etc.).
Pitfalls
- Hardcoded provider base_urls — see "The hardcoded provider base_url trap" above. This is the #1 reason custom endpoint configuration silently fails.
- Config changes don't propagate to running gateway — the gateway process reads config at startup. After any
hermes config setchange, restart the gateway if it is installed as a service, or manually relaunch it if it is being run in foreground mode. Ahermes chattest passing does not mean the gateway already updated. hermes gateway restartis service-oriented — on machines where the gateway is running manually and has never been installed as a service,hermes gateway restartcan successfully stop the current gateway and then fail with "Gateway service is not installed". Always follow withhermes gateway status; if it is not running, recover withhermes gateway run.- The redaction-mask character in tool output — when the agent reads a file or tool output that contains a redacted API key, the redacted form may use
***characters. The***glob breaks bash heredocs, pythonreliterals, andwrite_filecontent. Workaround: display the key as a fingerprint (sk-71dd...a605) and rebuild it in code via string concatenation ('sk' + '-' + 'rest') instead of pasting the raw value. Seehermes-secret-handlingfor the redaction layer. - Fake-sounding model names — names like "GPT-5.5" / "GPT-5.4" sound like fake models (they don't exist in OpenAI's official lineup as of 2026-01), but some real proxies do host them. Don't dismiss based on the name; verify by hitting
/v1/models. Dismiss based on the endpoint behavior (DNS fail, 404, etc.). - Boss-control / named profile
.envvs root.env— the root~/.hermes/.envis what thecustomprovider'smodel.api_keyis read from (or directly from config.yaml). Named profile.envfiles are loaded for the gateway runtime env, not for the model config. If the agent edits the wrong file, the gateway will appear to start fine but the model will still use the old key. hermes config setis the only safe way to edit config.yaml — directpatch/sed/write_fileagainstconfig.yamlis rejected with "Refusing to write to Hermes config file: security-sensitive configuration." Usehermes config set KEY VALUEfor all model config changes.- Provider-specific model name conventions — proxies often rename models.
gpt-4on one proxy may be a different model entirely on another. Always cross-check by listing/v1/modelsand matching the id exactly (case-sensitive). - First-call latency / cold upstream — many proxies return 502 on the first request while the upstream connection warms up. If the first chat call 502s but
/v1/modelsworks, retry 1-2 times before declaring the provider broken.
Backup and rollback
Always back up .env before changing credentials:
cp ~/.hermes/.env ~/.hermes/.env.bak.$(date +%Y%m%d_%H%M%S)
Rollback recipe: read the most recent backup with read_file (or cat), then write the original key value back via a python script using .replace() (not re.sub() — the mask character in some keys breaks regex). Always verify the restored key length matches the original.
Verification checklist
After configuring a new endpoint, do these in order:
-
python probe_endpoint.py <url> <key>returns exit 0 -
hermes chat -q "ping" -m <model>returns 200 with content -
hermes config showshowsmodel.provider: customand the expectedbase_url -
hermes gateway restart --profile <name>succeeds -
hermes gateway listshows the profile running - Tail the gateway log — should see the platform connection line ("feishu connected" / "telegram connected" / etc.)
- Send a test message from the messaging platform and confirm the response is on-topic (not an error / fallback)
Files in this skill
references/moosecloud-cc.md— specifics for moosecloud.cc (15 models, gpt-5.4 stable, gpt-5.5 upstream 502)references/third-party-fastapi-llm-config.md— 给 FastAPI 后端项目(不是 Hermes 自身)配 LLM key 的完整流程(HG-小红书 → ZH-知乎 实战):9 步 + minimax/DeepSeek/硅基流动/OpenRouter 配置模板 + @lru_cache() 陷阱 + Windows 端口占用 + DEBUG 开关 + 注册测试账号 + 流式响应验证references/clone-and-rename-fastapi-project.md— 克隆 + 改名 + 跑通整个 FastAPI 项目(HG-小红书 → ZH-知乎 实战):10 步流程(复制目录 → 批量改名 → 改 .env → Docker 镜像源 → PostgreSQL → venv → npm → 端口冲突 → DEBUG → 端到端验证),混合部署避开 docker.1ms.run 镜像残缺scripts/probe_endpoint.py— re-runnable endpoint probe (no credentials baked in, takes URL+key as args, returns typed exit codes)