Браузер и веб-поиск: web_search, web_fetch, browser

У агента есть три способа работать с интернетом: поиск (web_search), загрузка страниц (web_fetch) и полноценное управление браузером (browser). Каждый инструмент решает свою задачу — от быстрого поиска до автоматизации сложных веб-форм.

Когда что использовать

Web search

web_search ищет в интернете через настроенный провайдер. Результаты кешируются на 15 минут.

Провайдеры

Автоопределение

Если провайдер не указан, OpenClaw проверяет ключи в порядке приоритета: Brave → MiniMax → Gemini → Grok → Kimi → Perplexity → Firecrawl → Exa → Tavily → DuckDuckGo (бесплатный fallback).

Параметры

web_search(query="запрос", count=5, country="RU", language="ru", freshness="week")

• query — поисковый запрос (обязательно)
• count — количество результатов (1-10, по умолчанию 5)
• country — код страны (ISO 3166-1 alpha-2)
• language — код языка (ISO 639-1)
• freshness — фильтр по времени: day, week, month, year

Конфигурация

{
  "tools": {
    "web": {
      "search": {
        "enabled": true,
        "provider": "brave",
        "maxResults": 5,
        "timeoutSeconds": 30,
        "cacheTtlMinutes": 15
      }
    }
  }
}

X search

x_search — поиск постов в X (Twitter). Использует тот же XAI_API_KEY, что и Grok.

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "xSearch": { "enabled": true }
        }
      }
    }
  }
}

Web fetch

web_fetch загружает страницу по URL и извлекает читаемый контент (HTML → markdown). Не выполняет JavaScript — для JS-heavy сайтов используйте browser.

Как работает

1. Отправляет HTTP GET с Chrome-like User-Agent

2. Запускает Readability (извлечение основного контента)

3. Если Readability не сработал — fallback на Firecrawl (если настроен)

4. Кеширует результат на 15 минут

Параметры

web_fetch(url="https://example.com/article", extractMode="markdown", maxChars=50000)

• url — URL для загрузки (обязательно, только http/https)
• extractMode — формат вывода: markdown (по умолчанию) или text
• maxChars — обрезать вывод до N символов

Firecrawl fallback

Если Readability не справляется, web_fetch может использовать Firecrawl для обхода ботов и лучшего извлечения:

{
  "plugins": {
    "entries": {
      "firecrawl": {
        "enabled": true,
        "config": {
          "webFetch": {
            "apiKey": "fc-..."
          }
        }
      }
    }
  }
}

Безопасность

• Приватные/internal хостнеймы блокируются
• Redirects ограничены (maxRedirects, по умолчанию 3)
• Размер ответа ограничен (maxResponseBytes, по умолчанию 2MB)

Browser

browser — полноценное управление Chromium-браузером через CDP и Playwright. Агент может открывать вкладки, кликать, заполнять формы, делать скриншоты.

Два профиля

openclaw browser status
openclaw browser start
openclaw browser start --headless  # без GUI
openclaw browser open https://example.com
openclaw browser tabs
openclaw browser screenshot
openclaw browser snapshot
openclaw browser stop

Типы снимков (snapshots)

Агент «видит» страницу через снимки accessibility tree:

• AI snapshot (по умолчанию) — numeric refs (12, 23): click 12, type 23 "hello"
• Role snapshot (--interactive) — role refs (e12): click e12
• ARIA snapshot (--format aria) — ARIA refs (ax12)

Refs нестабильны между навигациями — после перехода на новую страницу нужно делать новый snapshot.

Действия

| Действие | Команда |

|———|———|

| Перейти по URL | navigate https://... |

| Кликнуть по элементу | click |

| Ввести текст | type "текст" |

| Выбрать из списка | select "Option" |

| Перетащить | drag |

| Навести курсор | hover |

| Заполнить форму | fill --fields '[...]' |

| Ждать условия | wait --text "Done" --timeout-ms 15000 |

Настройка

{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "headless": false,
    "actionTimeoutMs": 60000,
    "profiles": {
      "openclaw": { "cdpPort": 18800, "color": "#FF4500" },
      "user": { "driver": "existing-session", "attachOnly": true }
    }
  }
}

{
  "browser": {
    "ssrfPolicy": {
      "dangerouslyAllowPrivateNetwork": true
    }
  }
}

Browser skill

Плагин browser поставляет skill browser-automation, который учит агента правильному workflow: проверять статус → делать snapshot → действовать → повторять snapshot → обрабатывать ошибки.

Для профиля coding browser не включён по умолчанию — добавьте явно:

{
  "tools": {
    "profile": "coding",
    "alsoAllow": ["browser"]
  }
}

Практический пример

Типичный workflow агента:

1. web_search("новости AI за сегодня") — найти ссылки

2. web_fetch(url="https://...") — прочитать статью

3. Если нужен логин или JS: browser open https://... → snapshot → click → type

Для автоматизации публикаций:

• Без логина: web_fetch + exec (curl, скрипты)
• С логином: browser с профилем user (ваш реальный Chrome)

Частые ошибки

• web_search возвращает мало результатов. Увеличьте count или смените провайдер.
• web_fetch не видит контент. Сайт может использовать JS — переключайтесь на browser.
• Browser не запускается. Проверьте openclaw browser doctor. На сервере без GUI используйте headless: true.
• Refs устарели. После навигации на новую страницу делайте новый snapshot.

Troubleshooting

Linux: Snap Chromium не запускается

Ошибка: Failed to start Chrome CDP on port 18800

В Ubuntu пакет Chromium по умолчанию — snap-пакет. Snap изоляция через AppArmor мешает OpenClaw управлять процессом браузера. apt install chromium устанавливает заглушку, а не настоящий браузер.

Решение 1 (рекомендуется): Установить Google Chrome:

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt --fix-broken install -y

В конфиге:

{
  "browser": {
    "enabled": true,
    "executablePath": "/usr/bin/google-chrome-stable",
    "headless": true,
    "noSandbox": true
  }
}

chromium-browser --headless --no-sandbox --disable-gpu \
  --remote-debugging-port=18800 \
  --user-data-dir=$HOME/.openclaw/browser/openclaw/user-data \
  about:blank &

[Unit]
Description=OpenClaw Browser (Chrome CDP)
After=network.target

[Service]
ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.openclaw/browser/openclaw/user-data about:blank
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

WSL2 + Windows Chrome

Когда Gateway работает в WSL2, а Chrome — на Windows, нужно настроить удалённый CDP.

Архитектура: Gateway (WSL2) → CDP на Windows:9222 → Chrome на Windows

Шаг 1. Запустите Chrome на Windows: chrome.exe --remote-debugging-port=9222

Шаг 2. Проверьте из WSL2: curl http://WINDOWS_HOST_IP:9222/json/version

Шаг 3. Настройте профиль:

{
  browser: {
    enabled: true,
    defaultProfile: "remote",
    profiles: {
      remote: {
        cdpUrl: "http://WINDOWS_HOST_IP:9222",
        attachOnly: true
      }
    }
  }
}

Важно: Открывайте Control UI как http://127.0.0.1:18789/, не LAN-IP.

Частые ошибки

Что дальше

• Код и файлы — exec, файловые операции, diffs
• Автоматизация — cron, hooks, taskflow
• Инструменты: обзор — три уровня: tools, skills, plugins