Fix Hermes Connection Refused, 401, and Empty Replies in BenAgent

Most Hermes problems in BenAgent come from one of four places: the gateway is not running, the API server is disabled, the endpoint still requires authentication, or Hermes cannot produce a visible model response. Debug in that order.

Connection refused

Connection refused means BenAgent reached your Mac network stack but nothing accepted the request at the configured host and port. For the default local setup, confirm the gateway is listening on port 8642.

hermes gateway status
hermes gateway stop
hermes gateway start
hermes gateway status

401 or unauthorized

A 401 means Hermes and BenAgent disagree on endpoint authentication. Re-check API_SERVER_KEY and the optional Hermes Bearer token saved in BenAgent, or keep both unset for loopback-only no-auth access.

API_SERVER_ENABLED=true
GATEWAY_ALLOW_ALL_USERS=true

Wrong endpoint path

The default BenAgent Hermes route is /v1/chat/completions. If you intentionally configure /v1/responses, BenAgent changes the payload shape but still sends local history rather than previous_response_id. Do not mix a Responses endpoint with Chat Completions assumptions.

• Default base URL: http://127.0.0.1:8642
• Default path: /v1/chat/completions
• Chat Completions model: hermes-agent
• Continuity: bounded local history in one user message

Empty or invisible reply

If the HTTP request succeeds but BenAgent shows no useful reply, debug Hermes model/provider setup. Run Hermes diagnostics, verify the configured model provider, then test again with a one-sentence prompt.

hermes doctor
hermes model

Known-good test

After each fix, send a small message from BenAgent: 'Reply with one sentence confirming Hermes is connected.' Do not test with cron, tools, or large task instructions until this basic path works.