Web Scraping in Codex
Füge den Spicrawl-MCP-Server zu Codex hinzu. Er kann dann Webseiten als sauberes Markdown lesen.
Einrichten
Drei Schritte geben Codex die Tools, das Know-how zum Schreiben von Spicrawl-Code und Regeln für beides. Oder erledige alle drei mit spicrawl init --client codex.
Setze deinen API-Schlüssel:
bashexport SPICRAWL_API_KEY=spicrawl_live_... # add to your shell profileFüge den MCP-Server hinzu. Codex liest den Schlüssel bei jeder Verbindung aus
SPICRAWL_API_KEY, sodass der Schlüssel nie in einer Datei landet:bashcodex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEYDas schreibt dasselbe wie diese Konfiguration:
~/.codex/config.toml[mcp_servers.spicrawl] url = "https://mcp.spicrawl.com/mcp" bearer_token_env_var = "SPICRAWL_API_KEY"Nur für ein Projekt lege die Tabelle in
.codex/config.tomlab. Codex liest sie nur in vertrauenswürdigen Projekten.Installiere den Skill:
bashmkdir -p .agents/skills/spicrawl curl -fsSL https://app.spicrawl.com/skill.md -o .agents/skills/spicrawl/SKILL.mdFüge diesen Abschnitt in
AGENTS.mdim Projektstamm ein:AGENTS.md## Web data (Spicrawl) Use Spicrawl to read web pages: the spicrawl_* MCP tools, the `spicrawl` CLI, or POST https://api.spicrawl.com/v1/scrape with `Authorization: Bearer $SPICRAWL_API_KEY` in code. Docs: https://docs.spicrawl.com/llms.txt (append .md to any page URL for Markdown). - Ask for markdown: `response_format: "markdown"` (API default is html); on spicrawl_scrape, `format: "markdown"`. - Check the site's status, not only the HTTP status: `X-Target-Status` header, or `status` in the JSON envelope (spicrawl_scrape with `format: "json"`). 200 is the page; 404/410 mean it does not exist; 403/429/503 mean the site refused, so escalate. - On an error, switch on `code`. Retry only when `retryable` is true, after `retry_after_seconds`. Read `diagnostics.hint` and change what it names first. Never retry ERR::REQUEST::*, ERR::AUTH::* or ERR::LIMIT::QUOTA_EXCEEDED. - Escalate one step at a time and stop at the first that works: plain fetch (1 credit) -> `js_render: true` (3) -> add the user's own `proxy` if they have one. Empty or skeleton content means render; ERR::UPSTREAM::CHALLENGE or a 403 target status means retry once, then the user's own proxy. - Set `max_cost` on every request to the price of the step you intend. - Keep the cache on (default). Set `cache: false` only for prices, stock or other live data. - Trim tokens with `main_content_only` (on by default for markdown), `include_tags`, `exclude_tags`. - For more than 20 URLs, use a batch job (spicrawl_batch_submit / POST /v1/batch). Batch items return html, markdown or text (spicrawl_batch_submit defaults to markdown, POST /v1/batch to html). Extraction, screenshots, actions and sessions are refused with a 400 before anything is charged: scrape those URLs one by one. - With the CLI, read stdout as JSON and branch on the exit code: 3 auth, 4 bad request, 5 limit, 6 site refused or failed, 7 proxy, 8 engine or extraction, 10 network. - Never print or commit SPICRAWL_API_KEY. Log `X-Request-Id` for failures.Prüfe es mit
codex mcp listoder/mcpin einer Session. Du solltest 25spicrawl_*-Tools sehen.
Oder nutze die CLI
Codex arbeitet in einer Shell, daher funktioniert die CLI spicrawl ganz ohne Konfiguration. Sie gibt JSON aus, wenn sie in eine Pipe schreibt, und beendet sich mit einem stabilen Code:
spicrawl scrape https://example.com/pricing --format markdown --max-cost 3 | jq -r .contentIn der Codex Cloud verlass dich nicht auf den MCP-Server. Nutze die CLI oder einfaches HTTP. Setze SPICRAWL_API_KEY als Umgebungsvariable, nicht als Secret, und erlaube api.spicrawl.com im Internetzugang des Agenten.
Eine erste Aufgabe zum Ausprobieren
Starte codex im Projekt und frage:
Use Spicrawl to read https://example.com/pricing as markdown. List each plan with its monthly price.
If the page comes back empty, retry with rendering.Was es kann
Der Server gibt dem Agenten 25 spicrawl_*-Tools. Jeder Aufruf läuft unter deinem API-Schlüssel, mit denselben Limits und Credits wie ein direkter API-Aufruf.
- Eine Seite lesen:
spicrawl_scrapeliefert Markdown (Standard), Text, HTML, JSON oder PDF. - Viele Seiten lesen:
spicrawl_batch_submitstellt bis zu 10.000 URLs in die Warteschlange. Danach folgenspicrawl_batch_statusundspicrawl_batch_results. - Seiten hinter einem Login:
spicrawl_session_createbehält Cookies und Storage über Aufrufe hinweg. - Einen Fehler debuggen:
spicrawl_requests_listundspicrawl_request_get. - Nutzung prüfen:
spicrawl_usage_summaryund die anderen Nutzungs-Tools. Dafür brauchst du einen Schlüssel mit dem Scoperead. - Dinge nachschlagen:
spicrawl_docs_searchundspicrawl_docs_readdurchsuchen und lesen die Spicrawl-Docs.
Ein Tool, spicrawl_browser_connect_url, ist aufgeführt, kommt aber bald. Bei spicrawl_scrape heißt das Rendering-Argument render, nicht js_render wie bei der API.
Gut zu wissen
- Kein Crawling. Spicrawl folgt keinen Links und findet keine Seiten. Gib dem Agenten die URLs.
- Credits pro Anfrage. Ein einfacher Abruf kostet 1 Credit. JavaScript-Rendering kostet 3. Rendering im vollen Browser kostet 8.
- Fehler sind kostenlos. Eine fehlgeschlagene Anfrage kostet 0 Credits.
- Der Cache spart Zeit, keine Credits. Ein Cache-Treffer kostet genauso viel wie der Abruf, der ihn gespeichert hat.
- Begrenze jeden Aufruf. Setze
max_cost, und eine Anfrage, die mehr kosten könnte, wird abgelehnt, bevor sie läuft. - Kommt bald: verwaltete Proxys, Stealth-Modus, ein Remote-Browser und KI-Extraktion aus einem Prompt in einfacher Sprache. Heute kannst du deinen eigenen Proxy mitbringen.
Häufig gestellte Fragen
Wo speichert Codex den Server?
In ~/.codex/config.toml. Um sie nur in einem Projekt zu nutzen, lege dieselbe Tabelle in .codex/config.toml. Codex liest Projektkonfiguration nur in vertrauenswürdigen Projekten.
Kann Codex die CLI statt MCP nutzen?
Ja. Codex arbeitet in einer Shell und kann daher spicrawl scrape URL --format markdown --max-cost 3 ausführen. Die CLI gibt JSON aus, wenn sie gepiped wird, und beendet sich mit einem stabilen Code.
Funktioniert es in der Codex Cloud?
Verlass dich dort nicht auf den MCP-Server. Nutze die CLI oder einfaches HTTP. Setze SPICRAWL_API_KEY als Umgebungsvariable (nicht als Secret) und erlaube api.spicrawl.com im Internetzugang des Agenten.
Warum gibt der Server 401 zurück?
SPICRAWL_API_KEY war in der Shell, die codex gestartet hat, nicht gesetzt. Exportiere ihn und starte eine neue Session.
Was kostet jede Seite?
Ein einfacher Abruf kostet 1 Credit, JavaScript-Rendering 3 und Rendering im vollen Browser 8. Fehlgeschlagene Anfragen kosten 0. Ein Cache-Treffer kostet so viel wie der Abruf, der ihn gespeichert hat. Lass den Agenten bei jeder Anfrage max_cost setzen, damit er nie mehr ausgibt als erwartet.