hermes-web-backends
Fix or configure Hermes web_search/web_extract backends.
- License 许可
- MIT
- 最近更新
- 2026-11-03
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- hermes-web-backends
- author
- OraMesLita (curator)
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "hermes", "web", "search", "extract", "backend", "searxng", "firecrawl", "tavily", "exa", "config" ], "related_skills": [ "hermes-agent", "mcp-server-patterns" ] } }
- description
- Fix or configure Hermes web_search/web_extract backends.
02 资源文件 1
- 参考文档references/web-provider-docs.md2.8 KB
03 SKILL.md 正文
Hermes Web Search & Extract Backends
Configuring and troubleshooting which provider powers web_search / web_extract in Hermes. Providers are plugins under $HERMES_HOME/hermes-agent/plugins/web/<name>/ (built-in, kind: backend), selected via web.* config keys. Reference: references/web-provider-docs.md (verbatim docs excerpt).
Provider capability matrix
| Provider | Env var (in $HERMES_HOME/.env) | Search | Extract | Key needed? |
|---|---|---|---|---|
| firecrawl (default) | FIRECRAWL_API_KEY (or FIRECRAWL_API_URL self-hosted) | ✔ | ✔ | yes (or self-host) |
| searxng | SEARXNG_URL | ✔ | — | no (self-hosted) |
| parallel | PARALLEL_API_KEY | ✔ | ✔ | yes |
| tavily | TAVILY_API_KEY | ✔ | ✔ | yes (free tier: app.tavily.com) |
| exa | EXA_API_KEY | ✔ | ✔ | yes (free tier: exa.ai) |
| ddgs | (pip install ddgs) | ✔ | — | no |
| brave-free | — | ✔ | — | no |
Hard fact: there is NO keyless extract backend. Extract always needs firecrawl/tavily/exa/parallel (or self-hosted Firecrawl). Search can be free via searxng/ddgs/brave-free.
Config keys & resolution
web:
backend: searxng # fallback: firecrawl | searxng | parallel | tavily | exa | ddgs | brave-free
search_backend: searxng # optional per-capability override (mix free search + paid extract)
extract_backend: firecrawl # optional per-capability override
extract_char_limit: 15000
- Explicit
web.search_backend/web.extract_backendwin for their capability. - If
web.backendis unset → auto-detect from keys: SEARXNG_URL → searxng; EXA_API_KEY → exa; TAVILY_API_KEY → tavily; PARALLEL_API_KEY → parallel; else firecrawl. - Registry fallback order (filtered by capability): firecrawl → parallel → tavily → exa → searxng → brave-free → ddgs.
Fix recipe: "ddgs is a search-only backend and cannot extract"
Symptom: web_extract errors with Set web.extract_backend to firecrawl, tavily, exa, or parallel (because web.backend: ddgs is search-only).
- Search — point at the user's searxng (free, works live):
H="$HERMES_HOME" printf '\nSEARXNG_URL=http://<instance-ip:port>\n' >> "$H/.env" hermes config set web.backend searxng - Extract — needs a keyed provider. User signs up (free tiers: Tavily 1k credits/mo, Firecrawl 500/mo, Exa), then:
printf '\nTAVILY_API_KEY=<key>\n' >> "$H/.env" hermes config set web.extract_backend tavily - Verify: call
web_search— results mean provider resolution worked.
web.* config changes take effect LIVE (per-call registry resolution) — no session reset needed (verified 2026-08-06). This differs from toolset changes, which need /reset.
Pitfalls
- $HOME trap:
~/.hermesmay NOT be the real home. Always use$HERMES_HOME(on Panomete's box:C:\Users\Admin\AppData\Local\hermes;~/.hermesdoes not exist).hermes config get webreads the right file regardless. - Use
hermes config set KEY VAL— never hand-edit config.yaml. .envvars are read via config-aware lookup (os.environ first, then$HERMES_HOME/.env) so gateway sessions/delegate children see them too.- The searxng MCP server config (config.yaml →
mcp.servers.searxng.env.SEARXNG_URL) is SEPARATE from the native web backend — fixing one does not fix the other. MCP searxng'sweb_url_readCAN extract, so it's the workaround while native extract is unconfigured. - Never print
.envvalues; list key names only:grep -oE '^[A-Z_0-9]+=' "$H/.env". - Docs: https://hermes-agent.nousresearch.com/docs/user-guide/configuration → "Web Search Backends". If
web_extractis broken, curl the docs page and strip HTML with python (re.sub(r'<[^>]+>', ' ', ...)) — avoids the broken extract path entirely. - Self-hosted Firecrawl: set FIRECRAWL_API_URL, key becomes optional (server-side
USE_DB_AUTHENTICATION). Needs Docker — check daemon state first (Panomete's Docker was DOWN at 2026-08-05). - Provider plugins only advertise capabilities they implement (
supports_search/supports_extract); registry routes each call to the right provider. - Do NOT retry
web_extractwhen the error is "search-only backend." Retrying with the same backend (or another search-only backend) returns the same error. The only productive paths are: (a)curl -sL "<url>"to bypass the extract path entirely, (b)web_searchfor finding information, or (c) asking the user to set up a keyed extract backend (tavily/firecrawl/exa/parallel). A retry loop wastes turns.
Signup links
- Tavily: https://app.tavily.com/home · Exa: https://exa.ai · Firecrawl: https://firecrawl.dev · Parallel: https://parallel.ai
04 同仓库更多 Skills
project-spec-docs
Fill/update project_spec docs (templates, MM handoffs).
penpot-mcp
Penpot MCP: connect, verify, and fix streaming via nginx.
nginx-streaming-proxy
Configure nginx for streaming endpoints (SSE, MCP, WS).
branding-ci
Use for brand/CI identity, style guides, and brand docs.
yuanbao
Yuanbao (元宝) groups: @mention users, query info/members.
slidev
Create and present web-based slidedecks for developers using Slidev with Markdown, Vue components, code highlighting, animations, and interactive features. Use when building technical presentations, conference talks, code walkthroughs, teaching materials, or developer decks.