Tarayıcı denetim API'si

​

Denetim API’si (isteğe bağlı)

• Durum/başlatma/durdurma: GET /, GET /doctor, POST /start, POST /stop, POST /reset-profile
• Profiller: GET /profiles, POST /profiles/create, DELETE /profiles/:name
• Sekmeler: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId, POST /tabs/action
• Anlık görüntü/ekran görüntüsü: GET /snapshot, POST /screenshot
• Eylemler: POST /navigate, POST /act
• Kancalar: POST /hooks/file-chooser, POST /hooks/dialog
• İndirmeler: POST /download, POST /wait/download
• İzinler: POST /permissions/grant
• Hata ayıklama: GET /console, POST /pdf
• Hata ayıklama: GET /errors, GET /requests, GET /dialogs, POST /trace/start, POST /trace/stop, POST /highlight
• Ağ: POST /response/body
• Durum: GET /cookies, POST /cookies/set, POST /cookies/clear
• Durum: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
• Ayarlar: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password> veya bu parola ile HTTP Basic kimlik doğrulaması

• Bu bağımsız geri döngü tarayıcı API’si, güvenilir proxy veya Tailscale Serve kimlik üst bilgilerini kullanmaz.
• gateway.auth.mode, none veya trusted-proxy ise bu geri döngü tarayıcı rotaları, kimlik taşıyan bu modları devralmaz; bunları yalnızca geri döngüde tutun.

​

/act hata sözleşmesi

{ "error": "<message>", "code": "ACT_*" }

• ACT_KIND_REQUIRED (HTTP 400): kind eksik veya tanınmıyor.
• ACT_INVALID_REQUEST (HTTP 400): eylem yükü normalleştirme veya doğrulamadan geçemedi.
• ACT_SELECTOR_UNSUPPORTED (HTTP 400): selector desteklenmeyen bir eylem türüyle kullanıldı.
• ACT_EVALUATE_DISABLED (HTTP 403): evaluate (veya wait --fn) yapılandırma tarafından devre dışı bırakıldı.
• ACT_TARGET_ID_MISMATCH (HTTP 403): üst düzey veya toplu targetId, istek hedefiyle çakışıyor.
• ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): eylem, mevcut oturum profilleri için desteklenmiyor.

​

Playwright gereksinimi

• ARIA anlık görüntüleri
• Sekme başına CDP WebSocket kullanılabilir olduğunda rol tarzı erişilebilirlik anlık görüntüleri (--interactive, --compact, --depth, --efficient). Bu, inceleme ve referans keşfi için bir geri dönüş seçeneğidir; Playwright birincil eylem motoru olmaya devam eder.
• Sekme başına CDP WebSocket kullanılabilir olduğunda yönetilen openclaw tarayıcısının sayfa ekran görüntüleri
• existing-session / Chrome MCP profillerinin sayfa ekran görüntüleri
• Anlık görüntü çıktısından existing-session referans tabanlı ekran görüntüleri (--ref)

• navigate
• act
• Playwright’ın yerel AI anlık görüntü biçimine bağlı AI anlık görüntüleri
• CSS seçicili öğe ekran görüntüleri (--element)
• tam tarayıcı PDF dışa aktarımı

​

Docker Playwright kurulumu

OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

​

Çalışma biçimi (dâhilî)

​

CLI hızlı başvuru

openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep    # canlı bir anlık görüntü yoklaması ekle
openclaw browser start
openclaw browser start --headless # tek seferlik yerel yönetilen başsız başlatma
openclaw browser stop            # yalnızca bağlanma/uzak CDP üzerinde öykünmeyi de temizler
openclaw browser reset-profile   # profilin tarayıcı verilerini Çöp Kutusu'na taşır
openclaw browser tabs
openclaw browser tab             # geçerli sekmenin kısayolu
openclaw browser tab new
openclaw browser tab new --label research
openclaw browser tab label abcd1234 research
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://example.com
openclaw browser focus abcd1234
openclaw browser close abcd1234

openclaw browser profiles
openclaw browser create-profile --name research --color "#0066CC"
openclaw browser create-profile --name attach --driver existing-session --cdp-url http://127.0.0.1:9222
openclaw browser delete-profile --name research

openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12        # veya rol referansları için --ref e12
openclaw browser screenshot --labels
openclaw browser snapshot
openclaw browser snapshot --format aria --limit 200
openclaw browser snapshot --interactive --compact --depth 6
openclaw browser snapshot --efficient
openclaw browser snapshot --labels
openclaw browser snapshot --urls
openclaw browser snapshot --selector "#main" --interactive
openclaw browser snapshot --frame "iframe#main" --interactive
openclaw browser snapshot --out snapshot.txt
openclaw browser console --level error
openclaw browser errors --clear
openclaw browser requests --filter api --clear
openclaw browser pdf
openclaw browser responsebody "**/api" --max-chars 5000

openclaw browser navigate https://example.com
openclaw browser resize 1280 720
openclaw browser click 12 --double           # veya rol referansları için e12
openclaw browser click-coords 120 340        # görüntü alanı koordinatları
openclaw browser type 23 "hello" --submit
openclaw browser press Enter
openclaw browser hover 44
openclaw browser scrollintoview e12
openclaw browser drag 10 11
openclaw browser select 9 OptionA OptionB
openclaw browser download e12 report.pdf
openclaw browser waitfordownload report.pdf
openclaw browser upload /tmp/openclaw/uploads/file.pdf
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref e12
openclaw browser upload media://inbound/file.pdf
openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
openclaw browser dialog --accept
openclaw browser dialog --dismiss --dialog-id d1
openclaw browser wait --text "Done"
openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
openclaw browser evaluate --fn 'const title = document.title; return title;'
openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'
openclaw browser highlight e12
openclaw browser trace start
openclaw browser trace stop

openclaw browser cookies
openclaw browser cookies set session abc123 --url "https://example.com"
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set theme dark
openclaw browser storage session clear
openclaw browser set offline on
openclaw browser set headers --headers-json '{"X-Debug":"1"}'
openclaw browser set credentials user pass            # kaldırmak için --clear
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
openclaw browser set media dark
openclaw browser set timezone America/New_York
openclaw browser set locale en-US
openclaw browser set device "iPhone 14"

• Aracıya yönelik browser aracı, action=download (gerekli ref ve path) ile action=waitfordownload (isteğe bağlı path) işlevlerini sunar. Her ikisi de kaydedilen indirme URL’sini, önerilen dosya adını ve korumalı yerel yolu döndürür. Yönetilen Playwright profilleri için açık indirme yakalama kullanılabilir; mevcut oturum profilleri desteklenmeyen işlem hatası döndürür.
• Atomik seçici yüklemelerini tercih edin: OpenClaw’ın tek bir istekte hazırlanıp tıklaması için yüklemeyle birlikte tetikleyici --ref değerini iletin. Daha sonraki bir tetikleyici kasıtlıysa yalnızca yolları içeren upload desteklenmeye devam eder. Bir dosya girişini doğrudan ayarlamak için --input-ref veya --element kullanın. dialog bir hazırlama çağrısıdır; iletişim kutusunu tetikleyen tıklama/tuşa basma işleminden önce çalıştırın. Bir eylem kalıcı iletişim kutusu açarsa eylem yanıtı blockedByDialog ve browserState.dialogs.pending içerir; doğrudan yanıt vermek için bu dialogId değerini iletin. OpenClaw dışında işlenen iletişim kutuları browserState.dialogs.recent altında görünür.
• click/type/vb., snapshot kaynağından bir ref gerektirir (sayısal 12, rol başvurusu e12 veya eyleme dönüştürülebilir ARIA başvurusu ax12). CSS seçicileri eylemler için kasıtlı olarak desteklenmez. Görünür görüntü alanı konumu tek güvenilir hedef olduğunda click-coords kullanın.
• İndirme ve iz yolları OpenClaw geçici kökleriyle sınırlandırılmıştır: /tmp/openclaw{,/downloads} (geri dönüş: ${os.tmpdir()}/openclaw/...).
• upload, OpenClaw geçici yüklemeler kökünden ve OpenClaw tarafından yönetilen gelen medyadan dosya kabul eder. Yönetilen gelen medyaya media://inbound/<id>, korumalı alanla göreli media/inbound/<id> veya yönetilen gelen medya dizini içinde çözümlenmiş bir yol olarak başvurulabilir. İç içe medya başvuruları, dizin geçişi, sembolik bağlantılar, sabit bağlantılar ve rastgele yerel yollar yine reddedilir.
• upload, dosya girişlerini --input-ref veya --element aracılığıyla doğrudan da ayarlayabilir.

• --format ai (Playwright ile varsayılan): sayısal başvurular içeren yapay zekâ anlık görüntüsü (aria-ref="<n>").
• --format aria: axN başvurularını içeren erişilebilirlik ağacı. Playwright kullanılabildiğinde OpenClaw, izleyen eylemlerin bunları kullanabilmesi için arka uç DOM kimliklerine sahip başvuruları canlı sayfaya bağlar; aksi durumda çıktıyı yalnızca inceleme amaçlı kabul edin.
• --efficient (veya --mode efficient): kompakt rol anlık görüntüsü ön ayarı. Bunu varsayılan yapmak için browser.snapshotDefaults.mode: "efficient" değerini ayarlayın (bkz. Gateway yapılandırması).
• --interactive, --compact, --depth, --selector, ref=e12 başvurularına sahip bir rol anlık görüntüsünü zorunlu kılar. --frame "<iframe>", rol anlık görüntülerini bir iframe ile sınırlar.
• Playwright ile --labels, üstüne başvuru etiketleri bindirilmiş bir ekran görüntüsü (MEDIA:<path> yazdırır) ve her başvurunun sınırlayıcı kutusunu içeren bir annotations dizisi ekler. screenshot üzerinde Playwright destekli etiketler --full-page, --ref ve --element ile çalışır; snapshot üzerinde eşlik eden ekran görüntüsü yalnızca görüntü alanını kapsar. Mevcut oturum/chrome-mcp profilleri, sayfa ekran görüntülerinde üst katman etiketlerini işler ancak annotations döndürmez veya Playwright’ın tam sayfa/başvuru/öğe izdüşüm yardımcısını kullanmaz. Playwright veya chrome-mcp olmadan etiketli ekran görüntüleri kullanılamaz.
• --urls, keşfedilen bağlantı hedeflerini yapay zekâ anlık görüntülerine ekler.

​

Anlık görüntüler ve başvurular

• Yapay zekâ anlık görüntüsü (sayısal başvurular): openclaw browser snapshot (varsayılan; --format ai)
  • Çıktı: sayısal başvurular içeren bir metin anlık görüntüsü.
  • Eylemler: openclaw browser click 12, openclaw browser type 23 "hello".
  • Başvuru, dahili olarak Playwright’ın aria-ref işlevi aracılığıyla çözümlenir.
• Rol anlık görüntüsü (e12 gibi rol başvuruları): openclaw browser snapshot --interactive (veya --compact, --depth, --selector, --frame)
  • Çıktı: [ref=e12] (ve isteğe bağlı [nth=1]) içeren rol tabanlı bir liste/ağaç.
  • Eylemler: openclaw browser click e12, openclaw browser highlight e12.
  • Başvuru, dahili olarak getByRole(...) aracılığıyla (yinelenenler için ayrıca nth()) çözümlenir.
  • Üstüne e12 etiketleri bindirilmiş bir ekran görüntüsü eklemek için --labels ekleyin. Playwright destekli profillerde bu işlem ayrıca başvuru başına sınırlayıcı kutu meta verilerini (annotations[]) döndürür.
  • Bağlantı metni belirsiz olduğunda ve aracı somut gezinme hedeflerine ihtiyaç duyduğunda --urls ekleyin.
• ARIA anlık görüntüsü (ax12 gibi ARIA başvuruları): openclaw browser snapshot --format aria
  • Çıktı: yapılandırılmış düğümler hâlinde erişilebilirlik ağacı.
  • Eylemler: anlık görüntü yolu, başvuruyu Playwright ve Chrome arka uç DOM kimlikleri üzerinden bağlayabildiğinde openclaw browser click ax12 çalışır.
• Playwright kullanılamıyorsa ARIA anlık görüntüleri inceleme için yine yararlı olabilir ancak başvurular eyleme dönüştürülemeyebilir. Eylem başvurularına ihtiyaç duyduğunuzda --format ai veya --interactive ile yeniden anlık görüntü alın.
• Ham CDP geri dönüş yolu için Docker kanıtı: pnpm test:docker:browser-cdp-snapshot, Chromium’u CDP ile başlatır, browser doctor --deep komutunu çalıştırır ve rol anlık görüntülerinin bağlantı URL’lerini, imleçle eyleme dönüştürülebilir hâle getirilen öğeleri ve iframe meta verilerini içerdiğini doğrular.

• Başvurular gezinmeler arasında kararlı değildir; bir işlem başarısız olursa snapshot komutunu yeniden çalıştırın ve yeni bir başvuru kullanın.
• /act, değiştirme sekmesini kanıtlayabildiğinde eylemle tetiklenen değişimden sonra geçerli ham targetId değerini döndürür. İzleyen komutlar için kararlı sekme kimliklerini/etiketlerini kullanmaya devam edin.
• Rol anlık görüntüsü --frame ile alındıysa rol başvuruları bir sonraki rol anlık görüntüsüne kadar bu iframe ile sınırlıdır.
• Bilinmeyen veya eski axN başvuruları, Playwright’ın aria-ref seçicisine geçmek yerine hemen başarısız olur. Bu gerçekleştiğinde aynı sekmede yeni bir anlık görüntü alın.

​

Tarayıcı toplu işlem CLI’si

• CLI: JSON dizisini standart girdiden okumak için openclaw browser batch --actions '<json>', openclaw browser batch --actions-file plan.json veya openclaw browser batch --actions-file -. --continue, stopOnError=false değerini ayarlar; varsayılan davranış ilk hatada durmaktır. --target-id, toplu işlemin tamamını tek bir sekmeyle sınırlar.
• Başvuru yaşam döngüsü: başvurular, toplu işlemden önceki bir snapshot çalıştırmasından gelir (anlık görüntü iç içe bir eylem değildir). Gezinmeyi tetikleyen bir click veya DOM’u değiştiren bir evaluate gibi sayfa durumunu değiştiren iç içe bir eylem, toplu işlemin geri kalanı için önceki başvuruları geçersiz kılabilir. Durum değiştiren eylemleri önce yerleştirin veya yeniden anlık görüntü aldıktan sonra izleyen bir toplu işleme bölün. Gezinme ve yeniden anlık görüntü alma işlemleri toplu işlemin dışında gerçekleşir (openclaw browser navigate / snapshot); çünkü open, navigate ve snapshot, /act türleri değildir.
• Hedef kimliği çakışmaları: iç içe bir eylem targetId değerini atlayabilir veya istek düzeyindeki targetId değerini yineleyebilir; farklı bir sekmeye çözümlenen açık bir iç içe targetId, herhangi bir eylem çalışmadan önce ACT_TARGET_ID_MISMATCH ile reddedilir. Toplu eylemler tasarım gereği isteğin sekmesini paylaşır.
• Hata özeti: yanıt, sırasıyla her eylem için bir girdi içeren { "results": [{ "ok": true }, { "ok": false, "error": "<message>" }, ...] } değeridir. stopOnError varsayılan olduğunda dizi ilk hatada sona erer; --continue ile her eylemi kapsar. Başarısız olan herhangi bir girdi CLI’nin sıfır olmayan kodla çıkmasına neden olur; betikler için tam ve sıralı yanıtı korumak üzere --json iletin.

​

Gelişmiş bekleme seçenekleri

• URL’yi bekleme (Playwright tarafından glob kalıpları desteklenir):
  • openclaw browser wait --url "**/dash"
• Yükleme durumunu bekleme:
  • openclaw browser wait --load networkidle
  • Yönetilen openclaw ve ham/uzak CDP profillerinde desteklenir. existing-session sürücüsünü kullanan profiller (varsayılan user profili dâhil) networkidle değerini reddeder; bunlarda --url, --text, bir seçici veya --fn beklemelerini kullanın.
• Bir JS koşulunu bekleme:
  • openclaw browser wait --fn "window.ready===true"
• Bir seçicinin görünür hâle gelmesini bekleme:
  • openclaw browser wait "#main"

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

​

Hata ayıklama iş akışları

1. openclaw browser snapshot --interactive
2. click <ref> / type <ref> kullanın (etkileşimli modda rol başvurularını tercih edin)
3. Yine başarısız olursa Playwright’ın neyi hedeflediğini görmek için openclaw browser highlight <ref>
4. Sayfa olağan dışı davranıyorsa:
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. Ayrıntılı hata ayıklama için bir iz kaydedin:
   • openclaw browser trace start
   • sorunu yeniden oluşturun
   • openclaw browser trace stop (TRACE:<path> yazdırır)

​

JSON çıktısı

openclaw browser --json status
openclaw browser --json snapshot --interactive
openclaw browser --json requests --filter api
openclaw browser --json cookies

​

Durum ve ortam ayarları

• Çerezler: cookies, cookies set, cookies clear
• Depolama: storage local|session get|set|clear
• Çevrimdışı: set offline on|off
• Üst bilgiler: set headers --headers-json '{"X-Debug":"1"}' (veya konumsal biçim set headers '{"X-Debug":"1"}')
• HTTP temel kimlik doğrulaması: set credentials user pass (veya --clear)
• Coğrafi konum: set geo <lat> <lon> --origin "https://example.com" (veya --clear)
• Medya: set media dark|light|no-preference|none
• Saat dilimi / yerel ayar: set timezone ..., set locale ...
• Cihaz / görüntü alanı:
  • set device "iPhone 14" (Playwright cihaz ön ayarları)
  • set viewport 1280 720

​

Güvenlik ve gizlilik

• openclaw tarayıcı profili, oturum açılmış oturumlar içerebilir; bunu hassas veri olarak değerlendirin.
• browser act kind=evaluate / openclaw browser evaluate ve wait --fn sayfa bağlamında rastgele JavaScript çalıştırır. İstem enjeksiyonu bunu yönlendirebilir. İhtiyacınız yoksa browser.evaluateEnabled=false ile devre dışı bırakın.
• openclaw browser evaluate --fn bir işlev kaynak kodunu, ifadeyi veya deyim gövdesini kabul eder. Deyim gövdeleri asenkron işlevler olarak sarmalanır; bu nedenle geri almak istediğiniz değer için return kullanın. Sayfa tarafındaki işlevin varsayılan değerlendirme zaman aşımından daha uzun sürmesi gerekebilirse --timeout-ms <ms> kullanın.
• Oturum açma ve bot karşıtı önlemlere ilişkin notlar (X/Twitter vb.) için Tarayıcıda oturum açma + X/Twitter’da gönderi yayımlama bölümüne bakın.
• Gateway/Node ana makinesini özel tutun (yalnızca geri döngü veya tailnet).
• Uzak CDP uç noktaları güçlüdür; bunları tünelleyin ve koruyun.

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // isteğe bağlı tam eşleşme izni
    },
  },
}

​

İlgili

• Tarayıcı - genel bakış, yapılandırma, profiller, güvenlik
• Tarayıcıda oturum açma - sitelerde oturum açma
• Tarayıcı Linux sorunlarını giderme
• Tarayıcı WSL2 sorunlarını giderme