WebFetch & WebSearch

O ChatCLI inclui duas ferramentas web nativas — @webfetch e @websearch — que permitem ao agent buscar informações na internet e fazer fetch de páginas web sem depender de servidores MCP externos.

As web tools são ferramentas nativas do ChatCLI, disponíveis automaticamente nos modos agent e coder. Não e necessário configurar servidores MCP para usa-las.

@webfetch

Faz o fetch de uma URL, remove o HTML e retorna o conteúdo textual limpo. Ideal para ler documentações, artigos, READMEs e qualquer página web.

Como Funciona

Requisicao HTTP

O ChatCLI faz uma requisicao GET para a URL fornecida com headers padrão de navegador.

Parse HTML

O HTML recebido e parseado usando golang.org/x/net/html, extraindo apenas o conteúdo textual.

Limpeza

Tags de script, style, navegacao e elementos não-textuais são removidos. O texto resultante e limpo e formatado.

Retorno

O conteúdo textual e retornado ao agent como resultado da tool call.

Uso

O LLM invoca @webfetch automaticamente quando precisa acessar conteúdo de uma URL. Você também pode solicitar explicitamente:

Leia a documentação em https://pkg.go.dev/net/http e me explique o tipo Client

Formatos de Argumentos

JSON
Posicional

{
  "tool": "webfetch",
  "args": {
    "url": "https://pkg.go.dev/net/http"
  }
}

webfetch https://pkg.go.dev/net/http

Exemplo

User: Busque o conteúdo de https://go.dev/blog/error-handling-and-go

Agent: Vou buscar o conteúdo da página.

[tool_call: webfetch {"url": "https://go.dev/blog/error-handling-and-go"}]

Resultado: O artigo "Error handling and Go" explica os padroes de
tratamento de erros em Go, incluindo...

O @webfetch respeita redirects (até 10), timeouts (30s) e retorna erros claros para URLs inacessíveis ou com problemas de SSL.

Filtros para payloads grandes

Endpoints como Prometheus /metrics, dumps de configuração ou listagens longas podem facilmente exceder dezenas de milhares de caracteres. O @webfetch aceita um conjunto de parâmetros que aplicam filtragem por linha antes do truncamento, evitando que o miolo útil seja descartado:

Parâmetro	Tipo	Descrição
`filter`	string (regex Go)	Mantém apenas linhas que casam com o regex. Aplicado antes de `exclude` e `from_line`/`to_line`.
`exclude`	string (regex Go)	Descarta linhas que casam com o regex. Aplicado depois de `filter`.
`from_line`	integer	Início da janela na visão filtrada (1-based, inclusivo).
`to_line`	integer	Fim da janela na visão filtrada (1-based, inclusivo).
`save_to_file`	boolean	Persiste o corpo completo (pré-filtro) no scratch dir da sessão e retorna preview + caminho absoluto. Disparado automaticamente quando o corpo excede `CHATCLI_WEBFETCH_AUTOSAVE_BYTES` (default `10000`) e não há filtro/range definido.
`save_path`	string	Sobrescreve o nome do arquivo gerado por `save_to_file` (qualquer prefixo de diretório é descartado — escrita sempre confinada ao scratch).
`max_length`	integer	Tamanho máximo do conteúdo retornado inline (default: 20.000). Conteúdo acima disso é truncado inline — ou auto-salvo no scratch dir via auto-save.
`render`	boolean	Força (`true`) ou suprime (`false`) a renderização headless de páginas JS — ver Renderização de páginas JavaScript. Sem o parâmetro, o modo `auto` decide pela heurística.

Exemplo — filtrar Prometheus por prefixo de métrica:

{
  "url": "http://payments.prod.svc:9090/metrics",
  "filter": "^chatcli_",
  "exclude": "^# HELP|^# TYPE"
}

Exemplo — paginar dentro do payload filtrado:

{
  "url": "http://svc/very-long-changelog",
  "filter": "^- ",
  "from_line": 50,
  "to_line": 80
}

Exemplo — salvar tudo no scratch dir e ler trechos sob demanda depois:

{
  "url": "http://svc/metrics",
  "save_to_file": true
}

Resposta:

[full response saved to /tmp/chatcli-agent-Xy7K3a/scratch/webfetch_1712...txt — 142_318 bytes.
Use read_file with start/end to examine specific ranges.]

[primeiros ~50K chars do conteúdo]

O agente pode então emitir um read_file apontando para o caminho absoluto retornado, escolhendo o intervalo exato de linhas que importa.

save_to_file sempre confina escritas a CHATCLI_AGENT_TMPDIR. Se save_path for um caminho absoluto ou contiver .., apenas o filepath.Base é usado, e a escrita é validada para garantir que o resultado fica dentro do scratch dir.

Auto-save inteligente

Quando o LLM chama @webfetch sem filtro, exclude, range ou save_to_file explícito, e o body retornado supera o threshold de auto-save, o ChatCLI promove o fetch automaticamente para modo save_to_file=true. Isso protege o contexto contra páginas gigantes sem obrigar o modelo a saber o tamanho de antemão. Default: bodies acima de 10.000 bytes (configurável via CHATCLI_WEBFETCH_AUTOSAVE_BYTES) passam pelo auto-save. O resultado inline fica em um preview compacto (~5.000 chars) e a resposta começa com um marker explícito:

[auto-saved: response was 142318 bytes — too large to inline.
 Full body is at /tmp/chatcli-agent-.../scratch/webfetch_1712....txt.
 Preview below; use read_file with start/end or rerun with
 filter/from_line/to_line for specific ranges.]

[primeiros ~5000 chars do texto extraído]
...(auto-truncated — full body saved to disk)

Para desativar ou relaxar o auto-save — por exemplo, em batches offline onde o agente precisa do body inteiro inline — suba o threshold:

export CHATCLI_WEBFETCH_AUTOSAVE_BYTES=1000000   # 1 MB — efetivamente desabilitado para a maioria das páginas

Ou, na chamada específica, passe filter (mesmo que .*), from_line/to_line explícitos, ou save_to_file com false. Presença de qualquer um desses desabilita a promoção automática.

Ver Eficiência de Tokens para o contexto completo dessa decisão.

Renderização de páginas JavaScript (SPA)

Páginas que constroem o conteúdo no client (SPAs, tabelas montadas via JavaScript) retornam um “casco” vazio no fetch estático — <div id="root"> e bundles, sem o conteúdo real. O @webfetch resolve isso com uma cadeia de escalonamento:

Fetch estático

Sempre o primeiro passo. Páginas server-rendered param aqui — zero custo extra.

Detecção de shell JS

Heurística: texto extraído fino + sinais estruturais (mount points vazios #root/#app, aviso <noscript>, marcadores de framework — React, Next, Angular, Vue, Nuxt, Svelte, Gatsby, Remix, Flutter).

Render headless via CDP

Um Chromium real renderiza a página (espera load + DOM estável) e o DOM resultante passa pelo mesmo pipeline de extração/filtros/auto-save.

Fallbacks sem browser

Sem browser disponível, o estado embutido __NEXT_DATA__ (Next.js) é recuperado do HTML estático; em último caso, uma nota honesta avisa o modelo que o fetch pode estar incompleto.

Descoberta de browser (ordem): Chrome → Chromium → Edge → Brave → caminho explícito em CHATCLI_WEBFETCH_RENDER_BROWSER → download opt-in de um Chromium pinado (~150 MB, uma vez) com CHATCLI_WEBFETCH_RENDER_AUTOPROVISION=true. Sem API keys, sem serviços externos. Postura de produção: um browser compartilhado por processo (lançamento lazy, reuso com health-check, shutdown após 2 min ocioso), circuit breaker (2 falhas de launch → 5 min de pausa), contexto incógnito por render (cookies nunca vazam entre sites) e SSRF reforçado dentro do browser — cada sub-request da página é validado via interceptação CDP, espelhando o guard do caminho HTTP normal. DOM renderizado limitado a 10 MB.

Variável	Descrição	Default
`CHATCLI_WEBFETCH_RENDER`	`auto` (heurística decide), `always`, `never`	`auto`
`CHATCLI_WEBFETCH_RENDER_TIMEOUT`	Timeout do render em segundos	`25`
`CHATCLI_WEBFETCH_RENDER_BROWSER`	Caminho absoluto para um binário Chromium-based específico	(auto-detect)
`CHATCLI_WEBFETCH_RENDER_AUTOPROVISION`	Permite o download único de um Chromium pinado quando nenhum browser existe	`false`

> @webfetch https://app-spa.example.com/dashboard
Page appears JS-rendered; escalating to headless browser...

@websearch

Realiza uma busca web e retorna os resultados com título, URL e snippet. Suporta dois backends keyless por design — nada de API key externa para cadastrar: DuckDuckGo (scraping HTML) é o default zero-config, e SearxNG self-hosted é o preferido em ambiente corporativo quando você aponta para uma instância interna.

Backends disponíveis

Backend	Requisito	Quando brilha	Quando dói
DuckDuckGo	Nenhum	Default, funciona já, zero config	DDG eventualmente serve interstitial de anti-bot (CAPTCHA) — pode retornar zero resultados
SearxNG self-hosted	`SEARXNG_URL` apontando para a instância	Empresa fechada em rede corporativa — você controla o backend, sem saída para scraping público, agrega vários engines (Bing/Google/Qwant) pela instância	Requer subir um container interno + habilitar JSON no `settings.yml`
Brave Search	Nenhum	Índice próprio e independente (não é meta-busca) — diversidade real quando DDG bloqueia	Scraping HTML; layout pode mudar (parser ancorado em atributos semânticos estáveis)
Mojeek	Nenhum	Índice próprio e independente, crawler britânico	Algumas redes recebem 403 para tráfego automatizado — a cadeia simplesmente avança

Cadeia de fallback

A cada query, o ChatCLI monta uma cadeia ordenada de backends. Se o primeiro falha ou retorna vazio, o próximo é tentado automaticamente. Ordem default (CHATCLI_WEBSEARCH_PROVIDER não setado ou auto):

DuckDuckGo          ← default, sempre disponível
SearxNG             ← só entra na cadeia se SEARXNG_URL estiver setado
Brave Search        ← índice independente, zero config
Mojeek              ← índice independente, zero config

Override explícito para priorizar SearxNG:

export CHATCLI_WEBSEARCH_PROVIDER=searxng
export SEARXNG_URL=https://searx.internal.corp

Resultado: cadeia vira searxng → duckduckgo → brave → mojeek. Os demais continuam como fallback se a instância SearxNG falhar. O mesmo vale para qualquer provider: CHATCLI_WEBSEARCH_PROVIDER=brave move o Brave para o topo e mantém o resto atrás.

Variáveis de ambiente

Variável	Descrição	Default
`CHATCLI_WEBSEARCH_PROVIDER`	Força um backend específico no topo da cadeia: `searxng`, `duckduckgo`, `brave`, `mojeek`, ou `auto`.	`auto`
`SEARXNG_URL`	URL raiz da instância SearxNG (ex.: `https://searx.internal.corp`). Quando setado, SearxNG entra na cadeia.	(não setado)

Comando `/websearch`

Gerenciador interativo do backend preferido. Autocomplete disponível para subcomandos e nomes de provider.

Subcomando	Efeito
`/websearch` ou `/websearch status`	Mostra provider atual + cadeia ativa
`/websearch list`	Lista providers conhecidos e quais estão configurados
`/websearch provider <searxng\|duckduckgo\|brave\|mojeek\|auto>`	Define provider preferido para a sessão (seta `CHATCLI_WEBSEARCH_PROVIDER` no processo)
`/websearch reset`	Remove o override e volta ao modo auto

O /websearch provider é apenas para a sessão corrente. Para persistir, exporte a env no shell ou adicione ao .env.

Configurando SearxNG self-hosted

A instância SearxNG precisa ter a JSON API habilitada — não vem ativa por default. No settings.yml do SearxNG:

search:
  formats:
    - html
    - json

Se você apontar o SEARXNG_URL para uma instância sem JSON habilitado, o ChatCLI retorna um erro acionável ao invés de uma mensagem de decode confusa:

SearxNG did not return JSON (Content-Type="text/html"). Enable JSON in settings.yml: search.formats: [html, json]

A imagem oficial searxng/searxng no Docker Hub sobe em 30 segundos. Em ambiente corporativo, um único container com ingress interno já é suficiente — e resolve o problema de “DDG bloqueado pelo proxy” de uma vez.

Como funciona internamente

Seleção da cadeia

SelectSearchChain() lê CHATCLI_WEBSEARCH_PROVIDER e SEARXNG_URL, retorna uma lista ordenada de backends a tentar.

Tentativa sequencial

Para cada backend na cadeia: chama a função de busca. Se retorna resultados, pára e formata. Se falha ou retorna zero, loga o motivo e avança para o próximo.

Formatação

Resultados viram texto formatado com via <provider> no cabeçalho, numerados com título + URL + snippet.

Formatos de Argumentos

JSON
Posicional

{
  "tool": "websearch",
  "args": {
    "query": "golang rate limiting best practices 2026"
  }
}

websearch golang rate limiting best practices 2026

Exemplo

User: Pesquise como configurar OpenTelemetry com Go

Agent: Vou buscar informações atualizadas sobre isso.

[tool_call: websearch {"query": "opentelemetry go setup tutorial"}]

Search results for: "opentelemetry go setup tutorial" (via DuckDuckGo)

1. Getting Started with OpenTelemetry in Go
   URL: https://opentelemetry.io/docs/languages/go/getting-started/
   Official guide to instrumenting Go applications with OpenTelemetry...

2. OpenTelemetry Go SDK - Complete Guide
   URL: https://example.com/otel-go-guide
   Step-by-step tutorial covering traces, metrics and logs...

O cabeçalho (via DuckDuckGo) ou (via SearxNG) deixa claro qual backend respondeu — útil para diagnosticar por que alguma query não voltou resultado (ex.: DDG serviu CAPTCHA → fallback para SearxNG).

Por que keyless? O ChatCLI é usado em ambientes corporativos onde gerenciar API keys de terceiros (Brave Search, Tavily, SerpAPI) gera atrito operacional — cadastro, rotação, approvals. SearxNG self-hosted resolve fechamento de rede sem custo recorrente; DuckDuckGo cobre o caso casual sem nenhuma config.

Comparacao

Aspecto	@webfetch	@websearch
Proposito	Ler conteúdo de uma URL específica	Buscar na web por uma query
Input	URL	Query de busca
Output	Texto limpo da página	Lista de resultados (título + URL + snippet)
Quando usar	Você sabe a URL exata	Você precisa encontrar informações
Motor	HTTP GET + HTML parser	DuckDuckGo (scraping HTML) + SearxNG (JSON API)

Disponibilidade

As web tools estão disponíveis nos seguintes modos:

Modo	@webfetch	@websearch
Chat	Não	Não
Agent (`/agent`)	Sim	Sim
Coder (`/coder`)	Sim	Sim
One-shot (`-p`)	Sim (com `--agent`)	Sim (com `--agent`)

No modo chat interativo, as web tools não estão disponíveis. Você precisa estar em agent ou coder mode para que o LLM possa invocá-las como tool calls.

WebFetch & WebSearch

@webfetch

Como Funciona

Uso

Formatos de Argumentos

Exemplo

Filtros para payloads grandes

Auto-save inteligente

Renderização de páginas JavaScript (SPA)

@websearch

Backends disponíveis

Cadeia de fallback

Variáveis de ambiente

Comando `/websearch`

Configurando SearxNG self-hosted

Como funciona internamente

Formatos de Argumentos

Exemplo

Comparacao

Disponibilidade

Próximos Passos

MCP Integration

Plugins Agenticos

​@webfetch

​Como Funciona

​Uso

​Formatos de Argumentos

​Exemplo

​Filtros para payloads grandes

​Auto-save inteligente

​Renderização de páginas JavaScript (SPA)

​@websearch

​Backends disponíveis

​Cadeia de fallback

​Variáveis de ambiente

​Comando /websearch

​Configurando SearxNG self-hosted

​Como funciona internamente

​Formatos de Argumentos

​Exemplo

​Comparacao

​Disponibilidade

​Próximos Passos

MCP Integration

Plugins Agenticos

@webfetch

Como Funciona

Uso

Formatos de Argumentos

Exemplo

Filtros para payloads grandes

Auto-save inteligente

Renderização de páginas JavaScript (SPA)

@websearch

Backends disponíveis

Cadeia de fallback

Variáveis de ambiente

Comando `/websearch`

Configurando SearxNG self-hosted

Como funciona internamente

Formatos de Argumentos

Exemplo

Comparacao

Disponibilidade

Próximos Passos