hermes - 💡(How to fix) Fix Credential pool in auth.json silently overrides config.yaml api_key, causing stale-key 429s

Bug Description

When a user updates api_key in config.yaml (e.g. to replace an exhausted key), the credential pool stored in ~/.hermes/auth.json still holds the old key and takes precedence. This causes persistent HTTP 429 "quota exhausted" errors even though the new key in config.yaml is valid and functional.

There is no warning or log message indicating that the credential pool is overriding the config value.

Root Cause (after investigation)

The credential pool in auth.json is populated from environment variables (e.g. XIAOMI_API_KEY). When a key gets exhausted (429), the credential pool marks it as exhausted with a 1-hour cooldown. But:

1. The config.yaml api_key field is ignored when a credential pool entry exists for the same provider
2. Updating config.yaml with a new key does NOT update the credential pool
3. The environment variable XIAOMI_API_KEY in .bashrc is NOT inherited by the systemd-managed gateway service (hermes-gateway.service), so the old key persists in the pool
4. There is no CLI command like hermes auth refresh or hermes auth reset <provider> to easily clear/reload credentials

Steps to Reproduce

1. Configure Hermes with provider xiaomi and api_key: <key_A> in config.yaml
2. Set XIAOMI_API_KEY=<key_A> in .bashrc
3. Start the gateway via systemctl --user start hermes-gateway — key_A gets cached into auth.json → credential_pool.xiaomi
4. Key_A's quota is exhausted (HTTP 429)
5. Update config.yaml to use api_key: <key_B> (a valid key with available quota)
6. Restart the gateway
7. Result: Hermes continues using key_A from the credential pool and keeps getting 429

Workaround

Add Environment="XIAOMI_API_KEY=<new_key>" to ~/.config/systemd/user/hermes-gateway.service, then:

1. Remove xiaomi from auth.json credential pool manually
2. systemctl --user daemon-reload && systemctl --user restart hermes-gateway

Expected Behavior

One of:

• config.yaml api_key should take precedence over the credential pool entry, so updating the config is sufficient
• OR: When a provider's credential pool entry gets 429'd, automatically fall back to the config.yaml api_key
• OR: At minimum, log a clear warning like: "Using cached credential from auth.json credential pool instead of config.yaml api_key"
• OR: Provide a CLI command to clear/refresh the credential pool (e.g. hermes auth reset xiaomi)

Environment

• Hermes version: latest (commit on main as of 2026-05-08)
• OS: Ubuntu 22.04 (Tencent Cloud)
• Provider: xiaomi (custom OpenAI-compatible endpoint)
• Gateway managed by: systemd user service (hermes-gateway.service)