Browser Use’da Özel Bir Araçla CAPTCHA Nasıl Çözülür

Browser Use’da, kendi tarayıcınız üzerinde CAPTCHA çözmek için widget’ın sitekey’ini sayfadan okuyan, CapSkip’ten bir token isteyen ve onu forma yazan özel bir araç kaydedin, ardından sistem mesajında ajana bu aracın var olduğunu söyleyin. Browser Use’da yerel bir Chromium üzerinde CAPTCHA çözme işini bu karşılar; geriye yalnızca ikisinin de varsayılanı 180 saniye olan ve yükseltilmesi gereken iki sınır kalır, çünkü bir reCAPTCHA çözümü ikisinden de uzun sürebilir. Sistem mesajı kısmı isteğe bağlı değildir. Browser Use’un varsayılan sistem prompt’u modele CAPTCHA’ların otomatik olarak çözüldüğünü söyler; bu, Browser Use’un bulut tarayıcılarında doğru, yerel bir Chromium’da ise yanlıştır. Bu yüzden o paragraf olmadan ajan hiç gelmeyecek bir çözümü bekler. Bu rehber, Browser Use CAPTCHA aracını Browser Use 0.13.10 ile doğrulanmış olarak adım adım oluşturuyor.

Neye ihtiyacınız var

• Bir Windows makinesinde çalışan CapSkip. Aşağıdaki araç, görünmez ve Enterprise widget’lar dahil reCAPTCHA v2’yi ve Cloudflare Turnstile widget’ını işler.
• Browser Use’un gerektirdiği Python 3.11 veya üzeri; ayrıca browser-use ve capskip paketinin 1.3.0 veya üzeri bir sürümü. Browser Use, makinede bulduğu bir Chrome veya Chromium’u yönetir.
• Ajana verdiğiniz sohbet modeli hangisiyse onun için bir API anahtarı; Claude için bunu ANTHROPIC_API_KEY olarak ayarlayın. Örnekler Claude Opus 5.5’i, adaptive thinking açık olarak ChatAnthropic üzerinden kullanır ve bu argüman önemlidir: o olmadan Browser Use 0.13.10 modelin araç seçimini zorlar, Claude Opus 5.5 ve Sonnet 5.5 bunu reddeder ve her adım başarısız olur.
• Çözücü için bir adres. Local modunda CapSkip 127.0.0.1 üzerinden yalnızca o cihaza yanıt verir; Server modunda ise ağ adresinizi veya genel IP’nizi dinler, böylece başka bir makinedeki bir ajan onu API üzerinden çağırabilir. İkisi de şurada ayarlanır: bağlantı ayarları.

# Quoted, so cmd.exe does not read >= as a redirect
pip install browser-use "capskip>=1.3.0"

Browser Use yerel bir tarayıcıda CAPTCHA’ları neden görmezden gelir?

Çünkü ona böyle yapması söylenmiştir. Browser Use’un varsayılan ayarlarla kullandığı sistem prompt’undaki tarayıcı kuralları, "CAPTCHAs are automatically solved by the browser" (CAPTCHA’lar tarayıcı tarafından otomatik olarak çözülür) satırını ve ardından onları elle çözmeye çalışmama talimatını içerir. Bu, Browser Use’un CAPTCHA’ları kendi proxy’lerinde çözen ve bunu kütüphaneye bildiren bulut tarayıcılarını anlatır. Kütüphanede buna karşılık gelen bir watchdog vardır; BrowserProfile üzerindeki captcha_solver ayarıyla açılır (varsayılan olarak açıktır) ve bir bulut tarayıcısı çözüm yaparken ajanı duraklatır. Bu watchdog yalnızca o bulut tarayıcılarının gönderdiği olayları dinler.

Kendi makinenizdeki bir Chromium’da böyle bir olay hiçbir zaman gelmez. Ajan widget’ı görür, kurallara inanır ve adımları bitene kadar bekler, sayfayı kaydırır ya da başka bir yol dener. Bir çalıştırma bu şekilde bittiğinde Browser Use kendi bulut tarayıcılarına geçmeyi önerir. Tarayıcıyı kendi donanımınızda tutmak istiyorsanız alternatif, ajana widget’ı gerçekten çözen bir araç vermek ve ona verilen kuralı düzeltmektir.

1. Adım: bir solve_captcha aracı kaydedin

Özel araçlar, bir Tools örneği üzerinde tools.action dekoratörüyle kaydedilen async fonksiyonlardır. Browser Use özel parametreleri adlarına göre enjekte eder: browser_session size canlı oturumu, page_url ise geçerli sayfanın adresini verir. Aracın iki küçük JavaScript parçasına ihtiyacı vardır: biri widget’ı bulmak, diğeri token’ı doldurmak için.

FIND = """() => {
  const w = document.querySelector(
    '.g-recaptcha[data-sitekey], .cf-turnstile[data-sitekey]');
  if (!w) return null;
  return {
    kind: w.classList.contains('cf-turnstile') ? 'turnstile' : 'recaptcha',
    sitekey: w.dataset.sitekey,
    invisible: w.dataset.size === 'invisible' || w.tagName !== 'DIV',
    enterprise: !!document.querySelector(
      'script[src*="recaptcha/enterprise.js"]'),
    callback: w.dataset.callback || null,
  };
}"""

FILL = """(kind, token, callback) => {
  const name = kind === 'turnstile' ? 'cf-turnstile-response'
                                    : 'g-recaptcha-response';
  const fields = document.querySelectorAll(`[name="${name}"]`);
  fields.forEach(f => { f.value = token; });
  if (callback && typeof window[callback] === 'function') {
    window[callback](token);
  }
  return fields.length;
}"""

İkisi de ok fonksiyonu (arrow function) olarak yazılmıştır, çünkü sayfa nesnesinin evaluate metodu başka hiçbir şeyi kabul etmez. Bu metot ek argümanları JSON olarak geçirir ve her zaman bir dize döndürür: bir nesne JSON olarak kodlanmış hâlde, bir sayı rakamlarıyla, null ise boş bir dize olarak döner. FILL, token’ı widget’ın oluşturduğu yanıt alanına yazar ve widget bir data-callback bildiriyorsa orada adı geçen fonksiyonu çağırır, çünkü bazı formlar alanı okumak yerine o callback’i bekler.

FIND, çözümün bağlı olduğu iki şeyi de okur. Bir düğmeye bağlı bir widget, data-size özniteliği olmasa bile görünmezdir; bu yüzden div olmayan her g-recaptcha öğesi görünmez sayılır. Google’ın enterprise.js script’ini yükleyen bir sayfa ise reCAPTCHA Enterprise olarak çözülür, çünkü Enterprise widget’ları standart olanlarla aynı işaretlemeyi kullanır.

@tools.action(
    "Solve the reCAPTCHA v2 or Cloudflare Turnstile widget on the current "
    "page. Call it after the other fields are filled, then submit the form "
    "unless the page has already moved on."
)
async def solve_captcha(browser_session: BrowserSession, page_url: str):
    page = await browser_session.must_get_current_page()
    raw = await page.evaluate(FIND)
    widget = json.loads(raw) if raw else None
    if not widget:
        return ActionResult(error="No reCAPTCHA or Turnstile widget found.")

    try:
        if widget["kind"] == "turnstile":
            result = await solver.turnstile(widget["sitekey"], page_url)
        else:
            extra = {"invisible": 1} if widget["invisible"] else {}
            result = await solver.recaptcha(
                widget["sitekey"], page_url,
                enterprise=int(widget["enterprise"]), **extra)
    except CapSkipError as exc:
        return ActionResult(error=f"CapSkip did not solve it: {exc!r}")

    filled = await page.evaluate(
        FILL, widget["kind"], result["code"], widget["callback"])
    if filled == "0":
        return ActionResult(error="Solved, but no response field to fill.")
    return ActionResult(
        extracted_content=f"Solved the {widget['kind']} CAPTCHA on {page_url} "
                          "and filled in the token. Submit the form now, "
                          "unless the page has already moved on.",
    )

Açıklama dizesi, model hangi eylemi yapacağına karar verirken okuduğu şeydir; bu yüzden aracın ne yaptığının yanı sıra ne zaman çağrılacağını da söyler. Başarı mesajı yalnızca extracted_content içine girer. Bir ActionResult ayrıca long_term_memory de ayarlarsa Browser Use modele belleği gösterir ve içeriği atar; dolayısıyla içeriğe konmuş "Submit the form now" gibi bir talimat modele hiç ulaşmaz. Her başarısızlık, bir istisna olarak değil, modelin okuyup tepki verebileceği bir hata içeren bir ActionResult olarak döner.

Burada senkron CapSkip istemcisini değil, AsyncCapSkip’i kullanın. Browser Use tarayıcı bağlantısını aracınızla aynı event loop üzerinde çalıştırır ve bloklayan bir çözüm, sürdüğü boyunca bunların hepsini dondurur. Python’da AsyncCapSkip bir takma ad değil, gerçek bir asyncio istemcisidir.

2. Adım: ajana aracın var olduğunu söyleyin

Araçları ajana verin ve sistem mesajına bir paragraf ekleyin. extend_system_message varsayılan prompt’un sonuna eklenir, dolayısıyla düzeltmesi gereken kuraldan sonra gelir.

EXTRA = (
    "This browser does not solve CAPTCHAs on its own, whatever the rules "
    "above say. When a page shows a reCAPTCHA or Turnstile widget, fill in "
    "the other fields, call solve_captcha, then submit the form unless the "
    "page has already moved on. Never click the CAPTCHA checkbox or "
    "challenge yourself."
)

agent = Agent(
    task="Sign up at https://example.com/signup with YOUR_EMAIL.",
    llm=ChatAnthropic(model="claude-opus-5-5", thinking={"type": "adaptive"}),
    tools=tools,
    extend_system_message=EXTRA,
    step_timeout=420,
)

O paragraftaki sıralama önemlidir. Bir reCAPTCHA token’ı yalnızca yaklaşık iki dakika geçerlidir; bunu reCAPTCHA token ömrü kılavuzu açıklıyor. Üstelik her model adımı saniyeler sürer. Önce çözüp ardından uzun bir formu doldurmak, token’ın gönderimden önce süresinin dolmasına yol açabilir; bu yüzden ajana en son çözmesi söylenir. Bir model üçünü de, yani yazmayı, çözmeyi ve gönder düğmesine tıklamayı tek bir adımda yapabilir ve Browser Use bir adımın eylemlerini sırayla çalıştırır. Sayfanın zaten ilerlemiş olabileceğine dair koşul görünmez widget’lar içindir. Onların callback’i formu genellikle kendisi gönderir; dolayısıyla FILL onu çağırdığında sayfa çoktan ilerlemiş olur ve ikinci bir tıklama yalnızca başarısız olur.

ChatAnthropic üzerindeki thinking argümanı süs değildir. Browser Use, Claude’dan bir sonraki eylemini bir araç çağrısıyla ister ve 0.13.10 sürümünde, thinking olmadan bu araç seçimini zorlar. Claude Opus 5.5 ve Sonnet 5.5 zorlanmış bir araç seçimini 400 hatasıyla reddeder, dolayısıyla ajan her adımda başarısız olur. Adaptive thinking açıkken Browser Use aracı seçmeyi modele bırakır ve istek geçer.

3. Adım: 180 saniyelik iki sınırı yükseltin

Browser Use’da bir CAPTCHA çözümü iki ayrı saatin içine sığmak zorundadır ve ikisinin de varsayılanı 180 saniyedir.

• Eylem başına sınır. Her eylem, BROWSER_USE_ACTION_TIMEOUT_S ortam değişkeninden okunan bir zaman aşımıyla sarılır ve ajan hiçbir zaman kendi değerini geçirmez. Değişken yalnızca bir kez, Browser Use araç modülünü ilk yüklediğinde okunur; Agent veya Tools içe aktarıldığında bu yükleme gerçekleşir. Dolayısıyla değişkeni bundan sonra ayarlamanın hiçbir etkisi olmaz.
• Adım zaman aşımı. Agent’ın step_timeout değeri bir adımın tamamını kapsar: sayfa durumunun hazırlanmasını, Browser Use’un modele bağlı olarak 90 saniyeye kadar süre tanıdığı model çağrısını ve adımdaki her eylemi.

Öbür tarafta SDK bir reCAPTCHA’yı en fazla 300 saniye (recaptchaTimeout) boyunca yoklar; CapSkip’in kendi reCAPTCHA ayarları da bir göreve bir thread beklemek için en fazla 250 saniye, çözmek için de 250 saniye daha tanır. Çoğu çözüm çok daha erken biter, ancak bir kuyruk ya da yavaş bir proxy bir çözümü 180 saniyenin ötesine taşıyabilir. İki sınır da varsayılan değerlerindeyken önce adım zaman aşımı devreye girer, çünkü adım eylemden önce başlamıştır; ajan da adımın 180 saniye sonra zaman aşımına uğradığını bildirir. Yalnızca step_timeout değerini yükseltirseniz bu kez eylem sınırı devreye girer: çözümü yoklamanın ortasında iptal eder ve ölü bir CDP WebSocket’inden söz ederek tarayıcının yanıt vermiyor olabileceğini bildirir. Bu mesaj burada yanıltıcıdır. Tarayıcıda sorun yoktur; çözüm yalnızca sınırdan uzun sürmüştür. İki sınırı da SDK’nın süresinin üzerine ayarlayın.

import os

# Before anything imports Agent or Tools from browser_use.
os.environ.setdefault("BROWSER_USE_ACTION_TIMEOUT_S", "330")

from browser_use import Agent  # noqa: E402

# Up to 300 s of SDK polling (a few more for the last poll), one
# model call (90 s for Claude) and the page state, with room to spare.
agent = Agent(task="...", llm=llm, tools=tools,
              extend_system_message=EXTRA, step_timeout=420)

Zaman aşımına uğrayan bir adım, ajanın art arda başarısızlıklarından biri olarak da sayılır ve üst üste beş başarısızlık ajanı durdurur; dolayısıyla fazla dar bir sınır, tek bir yeniden denemeden daha pahalıya mal olur.

CapSkip’i bir sunucuda çalıştırmak

Araç, ajanın yanında, sizin Python sürecinizde çalışır. Önemli olan tarayıcının nerede olduğu değil, bu sürecin nerede çalıştığıdır: oturumun cdp_url değeri başka bir makinedeki bir Chrome’u gösterse bile çözüm yine betiğinizden CapSkip’e gider. Betik ile CapSkip aynı Windows PC’yi paylaştığı sürece 127.0.0.1 doğrudur. Ajan bir VPS’e, bir CI runner’a ya da başka bir makinedeki zamanlanmış bir işe taşındığında loopback yanlış makineyi gösterir ve araç hata olarak bir NetworkException döndürür. CapSkip’i Server moduna alın; o zaman ağ adresinizi veya genel IP’nizi dinler, böylece ajan onu aynı API üzerinden çağırabilir. Rota internetten geçiyorsa statik bir genel IP kullanın, API anahtarı doğrulamasını açın ve bir Windows Firewall kuralıyla portu sınırlayın. Çözücü sizin kendi Windows makinenizde kalır ve ajan kaç CAPTCHA ile karşılaşırsa karşılaşsın çözüm başına ücretlendirme olmaz.

SDK ortam değişkenlerini kendiliğinden okumaz. Tam örnekte olduğu gibi CAPSKIP_HOST, CAPSKIP_PORT ve CAPSKIP_API_KEY değerlerini kodunuzda okuyup AsyncCapSkip’e verin.

Tam çalışan örnek

# pip install browser-use "capskip>=1.3.0"
import asyncio
import json
import os

# Browser Use reads this once, when its tools load, so set it first.
os.environ.setdefault("BROWSER_USE_ACTION_TIMEOUT_S", "330")

from browser_use import ActionResult, Agent, BrowserSession, ChatAnthropic, Tools
from capskip import AsyncCapSkip, CapSkipError

solver = AsyncCapSkip(
    apiKey=os.getenv("CAPSKIP_API_KEY", "capskip"),
    host=os.getenv("CAPSKIP_HOST", "127.0.0.1"),
    port=int(os.getenv("CAPSKIP_PORT", "8080")),
)
tools = Tools()

FIND = """() => {
  const w = document.querySelector(
    '.g-recaptcha[data-sitekey], .cf-turnstile[data-sitekey]');
  if (!w) return null;
  return {
    kind: w.classList.contains('cf-turnstile') ? 'turnstile' : 'recaptcha',
    sitekey: w.dataset.sitekey,
    invisible: w.dataset.size === 'invisible' || w.tagName !== 'DIV',
    enterprise: !!document.querySelector(
      'script[src*="recaptcha/enterprise.js"]'),
    callback: w.dataset.callback || null,
  };
}"""

FILL = """(kind, token, callback) => {
  const name = kind === 'turnstile' ? 'cf-turnstile-response'
                                    : 'g-recaptcha-response';
  const fields = document.querySelectorAll(`[name="${name}"]`);
  fields.forEach(f => { f.value = token; });
  if (callback && typeof window[callback] === 'function') {
    window[callback](token);
  }
  return fields.length;
}"""


@tools.action(
    "Solve the reCAPTCHA v2 or Cloudflare Turnstile widget on the current "
    "page. Call it after the other fields are filled, then submit the form "
    "unless the page has already moved on."
)
async def solve_captcha(browser_session: BrowserSession, page_url: str):
    page = await browser_session.must_get_current_page()
    raw = await page.evaluate(FIND)
    widget = json.loads(raw) if raw else None
    if not widget:
        return ActionResult(error="No reCAPTCHA or Turnstile widget found.")
    try:
        if widget["kind"] == "turnstile":
            result = await solver.turnstile(widget["sitekey"], page_url)
        else:
            extra = {"invisible": 1} if widget["invisible"] else {}
            result = await solver.recaptcha(
                widget["sitekey"], page_url,
                enterprise=int(widget["enterprise"]), **extra)
    except CapSkipError as exc:
        return ActionResult(error=f"CapSkip did not solve it: {exc!r}")
    filled = await page.evaluate(
        FILL, widget["kind"], result["code"], widget["callback"])
    if filled == "0":
        return ActionResult(error="Solved, but no response field to fill.")
    return ActionResult(
        extracted_content=f"Solved the {widget['kind']} CAPTCHA on {page_url} "
                          "and filled in the token. Submit the form now, "
                          "unless the page has already moved on.",
    )


EXTRA = (
    "This browser does not solve CAPTCHAs on its own, whatever the rules "
    "above say. When a page shows a reCAPTCHA or Turnstile widget, fill in "
    "the other fields, call solve_captcha, then submit the form unless the "
    "page has already moved on. Never click the CAPTCHA checkbox or "
    "challenge yourself."
)


async def main():
    agent = Agent(
        task="Sign up at https://example.com/signup with YOUR_EMAIL, "
             "then report what the page says.",
        # Adaptive thinking lets Browser Use leave the tool choice to Claude.
        llm=ChatAnthropic(model="claude-opus-5-5", thinking={"type": "adaptive"}),
        tools=tools,
        extend_system_message=EXTRA,
        step_timeout=420,
    )
    history = await agent.run(max_steps=25)
    print(history.final_result())


asyncio.run(main())

Bu döngüyü bir checkbox widget’ı, bir düğmeye bağlı görünmez bir widget, bir Enterprise sayfası ve bir Turnstile widget’ı için hazırlanmış test sayfalarına karşı uçtan uca çalıştırdık ve her adımın öngörülebilir olması için model yerine önceden betiklenmiş bir vekil kullandık. Prompt, varsayılan kuralların ardından ek paragrafla birlikte geliyor, solve_captcha modelin seçebileceği eylemler arasında görünüyor, token forma yerleşiyor, data-callback fonksiyonu tetikleniyor, aracın talimatı modele ulaşıyor ve gönderim kabul ediliyor. ChatAnthropic’in gönderdiği isteği de, adaptive thinking ayarının araç seçimini modele bıraktığını doğrulamak için yakaladık. Gerçek bir modelle tek fark, aracın ne zaman çağrılacağına modelin karar vermesidir; açıklama ve ek paragraf da tam bunun içindir. Her iki metodun arkasındaki ham endpoint’ler şurada belgelenmiştir: API referansı.

Sık görülen hatalar ve anlamları

FAQ

Kısa özet

Kendi tarayıcınızda Browser Use CAPTCHA çözümü dört değişiklikten ibarettir; ajan çözücünün makinesinden ayrıldığında buna beşinci bir değişiklik eklenir. Sitekey’i page.evaluate ile okuyan, AsyncCapSkip’i await eden ve token’ı geri yazan, widget’ın bir callback’i varsa onu da çağıran bir solve_captcha aracı kaydedin. Ajanın aracı göndermeden hemen önce çağırması için varsayılan kuralı extend_system_message ile düzeltin. Claude’un isteği kabul etmesi için ChatAnthropic’e adaptive thinking verin. Browser Use yüklenmeden önce BROWSER_USE_ACTION_TIMEOUT_S değerini, Agent üzerinde de step_timeout değerini yükseltin; ikisi de SDK’nın 300 saniyesinin üzerinde olsun. Ajan çözücünün makinesi dışında herhangi bir yerde çalışıyorsa da CapSkip’i Server moduna alın.

• Python paketinin desteklediği tüm CAPTCHA türleri: Python CAPTCHA çözücü sayfası.
• Checkbox ve görünmez widget’ların nasıl çalıştığı: reCAPTCHA v2 çözücü sayfası.

Saatlerce gezinen bir ajan her iki sayfadan birinde bir challenge ile karşılaşabilir; kendi Windows makinenizde çalışan bir captcha atlatma aracı ise her birini çözüm başına ücret almadan çözer.