Pencarian web

Alat web_search mencari di web menggunakan penyedia yang Anda konfigurasi dan mengembalikan hasil. Hasil di-cache berdasarkan kueri selama 15 menit (dapat dikonfigurasi).

OpenClaw juga menyertakan x_search untuk postingan X (sebelumnya Twitter) dan web_fetch untuk pengambilan URL ringan. Pada fase ini, web_fetch tetap lokal sementara web_search dan x_search dapat menggunakan xAI Responses di balik layar.

Mulai cepat

openclaw configure --section web

await web_search({ query: "OpenClaw plugin SDK" });

await x_search({ query: "dinner recipes" });

Memilih penyedia

Perbandingan penyedia

Deteksi otomatis

Pencarian web OpenAI native

Model OpenAI Responses langsung menggunakan alat web_search ter-hosting OpenAI secara otomatis ketika pencarian web OpenClaw diaktifkan dan tidak ada penyedia terkelola yang dipatok. Ini adalah perilaku milik penyedia di Plugin OpenAI bawaan dan hanya berlaku untuk lalu lintas API OpenAI native, bukan URL dasar proksi yang kompatibel dengan OpenAI atau rute Azure. Tetapkan tools.web.search.provider ke penyedia lain seperti brave untuk mempertahankan alat web_search terkelola bagi model OpenAI, atau tetapkan tools.web.search.enabled: false untuk menonaktifkan pencarian terkelola dan pencarian OpenAI native.

Pencarian web Codex native

Runtime server aplikasi Codex menggunakan alat web_search ter-hosting Codex secara otomatis ketika pencarian web diaktifkan dan tidak ada penyedia terkelola yang dipilih. Pencarian ter-hosting native dan alat dinamis web_search terkelola OpenClaw saling eksklusif, sehingga pencarian terkelola tidak dapat melewati pembatasan domain native. OpenClaw menggunakan alat terkelola ketika pencarian ter-hosting tidak tersedia, dinonaktifkan secara eksplisit, atau diganti oleh penyedia terkelola yang dipilih. OpenClaw menjaga ekstensi mandiri web.run Codex tetap dinonaktifkan karena lalu lintas server aplikasi produksi menolak namespace web yang ditentukan pengguna.

• Konfigurasikan pencarian native di bawah tools.web.search.openaiCodex
• Tetapkan tools.web.search.provider: "codex" untuk menyediakan Codex Hosted Search sebagai penyedia web_search terkelola untuk model induk apa pun. Setiap panggilan menjalankan giliran server aplikasi Codex efemeral yang dibatasi dan gagal jika Codex tidak memancarkan item webSearch ter-hosting.
• mode: "cached" adalah preferensi default, tetapi Codex menyelesaikannya menjadi akses eksternal langsung untuk giliran server aplikasi tanpa pembatasan; tetapkan "live" untuk meminta akses langsung secara eksplisit
• Tetapkan tools.web.search.provider ke penyedia terkelola seperti brave untuk menggunakan web_search terkelola OpenClaw sebagai gantinya
• Tetapkan tools.web.search.openaiCodex.enabled: false untuk tidak menggunakan pencarian ter-hosting Codex; penyedia terkelola lain tetap tersedia
• Membatasi permukaan alat native Codex juga menjaga web_search terkelola tetap tersedia
• Ketika allowedDomains ditetapkan, fallback terkelola otomatis gagal tertutup jika pencarian ter-hosting tidak tersedia sehingga daftar izin native tidak dapat dilewati
• Jalankan khusus LLM dengan alat dinonaktifkan menonaktifkan pencarian native dan terkelola
• tools.web.search.enabled: false menonaktifkan pencarian terkelola dan native

Perubahan kebijakan pencarian Codex efektif persisten memulai thread terikat baru sehingga thread server aplikasi yang sudah dimuat tidak dapat mempertahankan akses pencarian ter-hosting yang kedaluwarsa. Pembatasan sementara per giliran menggunakan thread terbatas sementara dan mempertahankan binding yang ada untuk dilanjutkan nanti.

Lalu lintas OpenAI ChatGPT Responses langsung juga dapat menggunakan alat web_search ter-hosting OpenAI. Jalur terpisah itu tetap bersifat ikut serta melalui tools.web.search.openaiCodex.enabled: true dan hanya berlaku untuk model openai/* yang memenuhi syarat menggunakan api: "openai-chatgpt-responses".

{  tools: {    web: {      search: {        enabled: true,        // Optional: use Codex Hosted Search from non-Codex parent models too.        provider: "codex",        openaiCodex: {          enabled: true,          mode: "cached",          allowedDomains: ["example.com"],          contextSize: "high",          userLocation: {            country: "US",            city: "New York",            timezone: "America/New_York",          },        },      },    },  },}

Untuk runtime dan penyedia yang tidak mendukung pencarian Codex native, Codex dapat menggunakan fallback web_search terkelola melalui namespace alat dinamis OpenClaw. Gunakan penyedia terkelola eksplisit ketika Anda memerlukan kontrol jaringan spesifik penyedia OpenClaw, bukan pencarian ter-hosting Codex.

Memilih provider: "codex" mengaktifkan plugin codex bawaan dan menggunakan pembatasan tools.web.search.openaiCodex yang sama seperti ditampilkan di atas. Autentikasi app-server Codex terlebih dahulu dengan openclaw models auth login --provider openai. Agen induk dapat menggunakan model atau runtime apa pun; hanya pekerja pencarian terbatas yang berjalan melalui Codex.

Keamanan jaringan

Panggilan penyedia HTTP web_search terkelola menggunakan jalur fetch terlindungi OpenClaw. Untuk host API penyedia tepercaya, OpenClaw mengizinkan jawaban DNS fake-IP dari Surge, Clash, dan sing-box dalam 198.18.0.0/15 dan fc00::/7 hanya untuk nama host penyedia tersebut. Tujuan privat, loopback, link-local, dan metadata lainnya tetap diblokir. Codex Hosted Search adalah pengecualiannya: pekerja terbatasnya mendelegasikan akses jaringan ke alat web_search hosted milik app-server Codex.

Izin otomatis ini tidak berlaku untuk URL web_fetch arbitrer. Untuk web_fetch, aktifkan tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange dan tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange secara eksplisit hanya ketika proxy tepercaya Anda memiliki rentang sintetis tersebut.

Menyiapkan pencarian web

Daftar penyedia dalam dokumentasi dan alur penyiapan disusun secara alfabetis. Deteksi otomatis mempertahankan urutan prioritas terpisah.

Jika tidak ada provider yang ditetapkan, OpenClaw memeriksa penyedia dalam urutan ini dan menggunakan penyedia pertama yang siap:

Penyedia berbasis API terlebih dahulu:

1. Brave -- BRAVE_API_KEY atau plugins.entries.brave.config.webSearch.apiKey (urutan 10)
2. MiniMax Search -- MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY atau plugins.entries.minimax.config.webSearch.apiKey (urutan 15)
3. Gemini -- plugins.entries.google.config.webSearch.apiKey, GEMINI_API_KEY, atau models.providers.google.apiKey (urutan 20)
4. Grok -- xAI OAuth, XAI_API_KEY, atau plugins.entries.xai.config.webSearch.apiKey (urutan 30)
5. Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY atau plugins.entries.moonshot.config.webSearch.apiKey (urutan 40)
6. Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY atau plugins.entries.perplexity.config.webSearch.apiKey (urutan 50)
7. Firecrawl -- FIRECRAWL_API_KEY atau plugins.entries.firecrawl.config.webSearch.apiKey (urutan 60)
8. Exa -- EXA_API_KEY atau plugins.entries.exa.config.webSearch.apiKey; opsional plugins.entries.exa.config.webSearch.baseUrl mengganti endpoint Exa (urutan 65)
9. Tavily -- TAVILY_API_KEY atau plugins.entries.tavily.config.webSearch.apiKey (urutan 70)
10. Parallel -- API Parallel Search berbayar melalui PARALLEL_API_KEY atau plugins.entries.parallel.config.webSearch.apiKey; opsional plugins.entries.parallel.config.webSearch.baseUrl mengganti endpoint (urutan 75)

Penyedia endpoint terkonfigurasi setelah itu:

11. SearXNG -- SEARXNG_BASE_URL atau plugins.entries.searxng.config.webSearch.baseUrl (urutan 200)

Penyedia tanpa kunci seperti Parallel Search (Free), DuckDuckGo, Ollama Web Search, dan Codex Hosted Search hanya tersedia ketika Anda memilihnya secara eksplisit dengan tools.web.search.provider atau melalui openclaw configure --section web. OpenClaw tidak mengirim kueri web_search terkelola ke penyedia tanpa kunci hanya karena tidak ada penyedia berbasis API yang dikonfigurasi.

Model OpenAI Responses adalah pengecualian: saat tools.web.search.provider belum ditetapkan, model tersebut menggunakan pencarian web native OpenAI alih-alih penyedia terkelola di atas. Tetapkan tools.web.search.provider ke parallel-free (atau penyedia lain) untuk merutekannya melalui jalur terkelola.

Konfigurasi

{  tools: {    web: {      search: {        enabled: true, // default: true        provider: "brave", // or omit for auto-detection        maxResults: 5,        timeoutSeconds: 30,        cacheTtlMinutes: 15,      },    },  },}

Konfigurasi khusus penyedia (kunci API, URL dasar, mode) berada di bawah plugins.entries.<plugin>.config.webSearch.*. Gemini juga dapat menggunakan kembali models.providers.google.apiKey dan models.providers.google.baseUrl sebagai fallback berprioritas lebih rendah setelah konfigurasi pencarian web khususnya dan GEMINI_API_KEY. Lihat halaman penyedia untuk contoh. Grok juga dapat menggunakan kembali profil autentikasi OAuth xAI dari openclaw models auth login --provider xai --method oauth; konfigurasi kunci API tetap menjadi fallback.

tools.web.search.provider divalidasi terhadap id penyedia pencarian web yang dideklarasikan oleh manifes plugin bawaan dan terpasang. Salah ketik seperti "brvae" membuat validasi konfigurasi gagal alih-alih diam-diam kembali ke deteksi otomatis. Jika penyedia terkonfigurasi hanya memiliki bukti plugin usang, seperti blok plugins.entries.<plugin> yang tersisa setelah menghapus pemasangan plugin pihak ketiga, OpenClaw menjaga startup tetap tangguh dan melaporkan peringatan agar Anda dapat memasang ulang plugin atau menjalankan openclaw doctor --fix untuk membersihkan konfigurasi usang.

Pemilihan penyedia fallback web_fetch terpisah:

• pilih dengan tools.web.fetch.provider
• atau hilangkan kolom itu dan biarkan OpenClaw mendeteksi otomatis penyedia web-fetch pertama yang siap dari kredensial terkonfigurasi
• web_fetch non-sandbox dapat menggunakan penyedia plugin terpasang yang mendeklarasikan contracts.webFetchProviders; fetch bersandbox mengizinkan penyedia bawaan dan pemasangan plugin resmi terverifikasi, tetapi mengecualikan plugin eksternal pihak ketiga
• plugin Firecrawl resmi menyediakan fallback web-fetch, dikonfigurasi di bawah plugins.entries.firecrawl.config.webFetch.*

Ketika Anda memilih Kimi selama openclaw onboard atau openclaw configure --section web, OpenClaw juga dapat meminta:

• wilayah API Moonshot (https://api.moonshot.ai/v1 atau https://api.moonshot.cn/v1)
• model pencarian web Kimi default (default ke kimi-k2.6)

Untuk x_search, konfigurasikan plugins.entries.xai.config.xSearch.*. Ini menggunakan profil autentikasi xAI yang sama seperti chat, atau kredensial XAI_API_KEY / pencarian web plugin yang digunakan oleh pencarian web Grok. Konfigurasi lama tools.web.x_search.* dimigrasikan otomatis oleh openclaw doctor --fix. Ketika Anda memilih Grok selama openclaw onboard atau openclaw configure --section web, OpenClaw juga dapat menawarkan penyiapan x_search opsional dengan kredensial yang sama. Ini adalah langkah lanjutan terpisah di dalam jalur Grok, bukan pilihan penyedia pencarian web tingkat atas yang terpisah. Jika Anda memilih penyedia lain, OpenClaw tidak menampilkan prompt x_search.

Menyimpan kunci API

{  plugins: {    entries: {      brave: {        config: {          webSearch: {            apiKey: "YOUR_KEY", // pragma: allowlist secret          },        },      },    },  },}

export BRAVE_API_KEY="YOUR_KEY"

Parameter alat

x_search

Kueri x_search mencari posting X (sebelumnya Twitter) menggunakan xAI dan mengembalikan jawaban tersintesis AI dengan sitasi. Ini menerima kueri bahasa alami dan filter terstruktur opsional. OpenClaw hanya mengaktifkan alat x_search xAI bawaan pada permintaan yang melayani panggilan alat ini.

Konfigurasi x_search

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true,            model: "grok-4-1-fast-non-reasoning",            baseUrl: "https://api.x.ai/v1", // optional, overrides webSearch.baseUrl            inlineCitations: false,            maxTurns: 2,            timeoutSeconds: 30,            cacheTtlMinutes: 15,          },          webSearch: {            apiKey: "xai-...", // optional if an xAI auth profile or XAI_API_KEY is set            baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL          },        },      },    },  },}

x_search mem-posting ke <baseUrl>/responses ketika plugins.entries.xai.config.xSearch.baseUrl ditetapkan. Jika kolom itu dihilangkan, ia fallback ke plugins.entries.xai.config.webSearch.baseUrl, lalu tools.web.search.grok.baseUrl lama, dan akhirnya endpoint xAI publik.

Parameter x_search

Contoh x_search

await x_search({  query: "dinner recipes",  allowed_x_handles: ["nytfood"],  from_date: "2026-03-01",});

// Per-post stats: use the exact status URL or status ID when possibleawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

Contoh

// Basic searchawait web_search({ query: "OpenClaw plugin SDK" }); // German-specific searchawait web_search({ query: "TV online schauen", country: "DE", language: "de" }); // Recent results (past week)await web_search({ query: "AI developments", freshness: "week" }); // Date rangeawait web_search({  query: "climate research",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // Domain filtering (Perplexity only)await web_search({  query: "product reviews",  domain_filter: ["-reddit.com", "-pinterest.com"],});

Profil alat

Jika Anda menggunakan profil alat atau daftar izin, tambahkan web_search, x_search, atau group:web:

{  tools: {    allow: ["web_search", "x_search"],    // or: allow: ["group:web"]  (includes web_search, x_search, and web_fetch)  },}

Terkait

• Pengambilan Web -- ambil URL dan ekstrak konten yang dapat dibaca
• Peramban Web -- otomasi peramban penuh untuk situs yang banyak menggunakan JS
• Pencarian Grok -- Grok sebagai penyedia web_search
• Pencarian Web Ollama -- pencarian web tanpa kunci melalui host Ollama Anda