hermes - 💡(How to fix) Fix Bug: Firecrawl web provider ignores Hermes config env values

Summary

The Firecrawl web provider currently reads FIRECRAWL_API_KEY and FIRECRAWL_API_URL only from the raw process environment via os.getenv(). In Hermes, env values may be supplied through the normal Hermes config/env mechanism and are available through hermes_cli.config.get_env_value(), but are not guaranteed to be present in os.environ for every gateway/tool execution path.

This can make a self-hosted Firecrawl instance appear unavailable, or make the provider use stale/missing direct config, even when FIRECRAWL_API_URL is configured correctly in Hermes' .env.

Expected behavior

If FIRECRAWL_API_URL or FIRECRAWL_API_KEY is configured through Hermes' config/env handling, the Firecrawl web provider should see it and web_extract / web_search should use it.

For self-hosted unauthenticated Firecrawl, URL-only config should work from Hermes' .env:

FIRECRAWL_API_URL=http://localhost:3002

Actual behavior

The provider only checks raw process env:

api_key = os.getenv("FIRECRAWL_API_KEY", "").strip()
api_url = os.getenv("FIRECRAWL_API_URL", "").strip().rstrip("/")

If those values are available through get_env_value() but not present in os.environ, direct Firecrawl config is missed.

Affected area

Current main source shape in:

plugins/web/firecrawl/provider.py

Function:

_get_direct_firecrawl_config()

Steps to reproduce

1. Configure Hermes with a self-hosted Firecrawl URL in Hermes' .env / config-env path, but do not export it into the process environment for the execution path being tested.
2. Configure web extraction to use Firecrawl, for example web.extract_backend: firecrawl.
3. Run a gateway/tool path that invokes web_extract.
4. Observe that Firecrawl direct config can be missed because _get_direct_firecrawl_config() only reads os.getenv().

This is a code-level configuration boundary issue; no secret values are needed to reproduce.

Suggested fix

Use Hermes' config-aware env lookup first, with process-env fallback if desired:

def _get_env_value(name: str) -> str:
    try:
        from hermes_cli.config import get_env_value
        value = get_env_value(name)
    except Exception:
        value = None
    if value is None:
        value = os.getenv(name)
    return (value or "").strip()

api_key = _get_env_value("FIRECRAWL_API_KEY")
api_url = _get_env_value("FIRECRAWL_API_URL").rstrip("/")

A direct import of get_env_value() may also be fine if this module can safely depend on hermes_cli.config at import/use time.

Related issues

This appears to be the same bug class as other open/fixed os.getenv() vs Hermes config-env reports:

• #34290: SearXNG web provider ignores Hermes config env values for SEARXNG_URL
• #18757: base_url_env_var uses os.getenv() and misses ~/.hermes/.env values
• #17140: TTS tools failed to read API keys from ~/.hermes/.env because they used os.getenv() instead of get_env_value()
• #15914: credential/config resolution misses values unavailable in os.environ

Environment

• OS: Linux x86_64, Ubuntu kernel 6.8.0-124-generic
• Python: 3.13.5
• Hermes: Hermes Agent v0.15.1 (2026.5.29)

Traceback

No traceback. This is a configuration-resolution bug identified from source and reproduced locally as a provider availability/config mismatch.

Additional context

I am currently carrying a local derived-image patch that replaces the Firecrawl provider's direct os.getenv() reads with hermes_cli.config.get_env_value() for FIRECRAWL_API_KEY and FIRECRAWL_API_URL. That local workaround restored Firecrawl-backed web_extract for gateway/Discord execution paths that read Hermes' persisted .env.

No secrets or private URLs are included in this report.