hermes-plugin-custom-user-agent

A small Hermes Agent plugin that injects configurable User-Agent and extra HTTP headers into OpenAI-compatible clients created by Hermes.

It is useful when a custom OpenAI-compatible proxy or upstream expects a specific client identity header, such as Codex CLI-like headers.

Behavior

• The plugin patches openai.OpenAI and openai.AsyncOpenAI client construction inside Hermes.
• It injects headers only when:
  • the plugin is enabled in Hermes config;
  • the plugin config is enabled;
  • the active API mode is allowed, defaulting to codex_responses;
  • the client base_url matches base_urls, if configured.
• It does not inject a default browser User-Agent. Set user_agent explicitly.
• Extra headers are configured through headers, default_headers, or extra_headers.

Install

From a GitHub shorthand:

hermes plugins install owner/hermes-plugin-custom-user-agent --enable

Or from a full Git URL:

hermes plugins install https://github.com/owner/hermes-plugin-custom-user-agent.git --enable

Then restart Hermes / the gateway so the plugin is loaded.

Configuration

Add this to $HERMES_HOME/config.yaml:

plugins:
  enabled:
    - custom-user-agent
  disabled: []

  custom_user_agent:
    enabled: true
    api_modes: [codex_responses]
    base_urls:
      - http://your-openai-compatible-endpoint/v1
    user_agent: "codex_cli_rs/0.132.0 (Ubuntu 24.04; x86_64) WindowsTerminal"
    headers:
      originator: codex_cli_rs

Options

Option	Type	Default	Notes
enabled	bool/string	true	Set false, off, no, or disabled to turn the plugin off internally.
api_modes / apply_to_api_modes / api_mode	string/list	[codex_responses]	Use "*" to apply to all API modes.
base_urls / base_url	string/list	all endpoints	Strongly recommended so the plugin does not affect unrelated providers. Trailing slash is ignored.
user_agent / User-Agent / user-agent	string	none	Explicit User-Agent value to inject.
headers / default_headers / extra_headers	mapping	none	Extra headers to inject, e.g. originator: codex_cli_rs.

Environment override

export HERMES_CUSTOM_USER_AGENT='codex_cli_rs/0.132.0 (Ubuntu 24.04; x86_64) WindowsTerminal'

The environment value overrides the configured user_agent value.

Codex-like header example

Some Codex-style endpoints reject browser-like User-Agent values with HTTP 403. Prefer a Codex-shaped value and restrict the plugin to the endpoint that needs it.

Real Codex CLI headers are shaped like:

User-Agent: codex_cli_rs/<codex-version> (<system-type> <system-version>; <arch>) <terminal-identifier>
originator: codex_cli_rs

Example:

User-Agent: codex_cli_rs/0.132.0 (Ubuntu 24.04; x86_64) WindowsTerminal
originator: codex_cli_rs

Bad idea for Codex-style upstreams:

user_agent: Mozilla/5.0

Verify

hermes plugins list

For network-level verification, point the OpenAI-compatible base URL at a temporary HTTP capture or reverse proxy and inspect the request headers there.

If headers do not appear, check:

1. base_urls matches the endpoint exactly apart from trailing slash.
2. api_modes includes the active mode, usually codex_responses.
3. user_agent is not empty.
4. Extra upstream-required headers, such as originator: codex_cli_rs, are present if needed.
5. Hermes / the gateway was restarted after changing plugin files or config.

Development

This plugin is a standalone Hermes user plugin. The repository root should contain:

plugin.yaml
__init__.py
README.md
after-install.md
LICENSE
examples/config.yaml

Before publishing, remove generated files such as __pycache__ and do not include private endpoints or credentials.