On this page: Pain points · Install and gateway cheat sheet · Reproducible steps · Citable parameters · FAQ
This guide is not the LiteLLM Proxy routing story and not the LangGraph tool-node playbook. It stays in Python Haystack pipelines, DocumentStore retrieval, and optional generators while reusing the same loopback OpenClaw gateway contract. For economics and soak tests, pair with multi-model routing acceptance, GenAI observability fields, and the local RAG quota matrix.
Pain points Haystack teams hit on remote Macs
1. Unguarded tool JSON. Agents emit loosely typed arguments. Without schema validation, bad shapes reach the gateway, burn tokens, and pollute logs.
2. Retrieval tail latency. Vector queries against a busy DocumentStore can exceed interactive budgets. Without a timeout fuse, the whole pipeline waits and users blame the model.
3. Retry storms. Copying generic HTTP retry rules onto retrieval repeats expensive work. You need different templates for gateway tools versus vector search.
Install and gateway cheat sheet
| Layer | What to install or run | Notes for Haystack 2.x |
|---|---|---|
| Python stack | python -m venv .venv, then pip install haystack-ai plus your embedder and vector client packages. |
Pin versions in requirements.txt; keep embedding models on disk to avoid cold downloads during demos. |
| Document store | Local dev: embedded or file-backed store; prod-like: container on the same host or loopback TCP. | Mount persistent volumes on the rented Mac so indexes survive reboots; snapshot paths in your runbook. |
| OpenClaw gateway | openclaw gateway listen on 127.0.0.1:PORT with --token-file from the dashboard. |
Tools only; expose through SSH tunnel. Reuse Bearer headers and correlation ids across Haystack components. |
| Health and doctor | openclaw doctor --json after changes; curl /health with the same token as workers. |
Align probes with Haystack pipeline startup so bad tokens fail before you enqueue documents. |
Reproducible wiring: six moves
1. Freeze layout. Create a repo directory with schemas/tools/, pipelines/, and tokens/ ignored by git. Document which Haystack Pipeline variant you run, async or sync, so timeout helpers match the runtime.
2. Bind tools to OpenClaw. Implement a thin client class whose base URL points at http://127.0.0.1:PORT, reads Authorization: Bearer from an environment file, and attaches X-Correlation-Id from Haystack metadata or a fresh UUID per query.
3. Validate with JSON Schema. Before any POST, run jsonschema.validate or a Pydantic model generated from the same schema file the dashboard documents. Reject locally with a structured error that never touches the gateway.
4. Add retriever timeout and fuse. Wrap the retriever call with asyncio.wait_for or a worker pool deadline. Track consecutive timeouts; after two breaches within a sliding window, set retrieval_skipped=true, return zero documents, and include a short reason for the generator.
5. Apply the retry template to gateway calls only. Use exponential backoff with jitter, max three attempts, explicit allow lists for 429 and connect errors, and zero automatic retries on 401. Do not loop the retriever when the fuse is open; wait for cooldown instead.
6. Emit failure summaries. Map gateway HTTP errors and fuse events into one JSON envelope: stage, code, correlation_id, optional schema_id, and hint. Pass that object to the answer component so user facing text admits degraded retrieval instead of hallucinating citations.
Log each envelope next to Haystack pipeline run ids so support can join structured gateway access logs with retrieval timings. When the fuse cools down, emit a single info line so operators know search resumed without a silent state change.
# Sketch: validate then call (conceptual)
# jsonschema.validate(instance=payload, schema=TOOL_SCHEMA)
# resp = session.post(gateway_url, json=payload, timeout=(2, 8))
# retries only inside gateway_session_retry_policy, not around vector searchCitable parameters you can paste into runbooks
- Retriever SLA: default 450 ms deadline for dev, 900 ms for cold indexes; fuse opens after two consecutive breaches.
- Gateway tool HTTP: connect timeout 2 s, read timeout 8 s, backoff base 250 ms with full jitter.
- Failure envelope keys:
stage,code,correlation_id,hint; never embed raw prompts or document bodies.
FAQ: stack boundaries and operations
Should Haystack talk to LiteLLM directly? Keep LiteLLM concerns inside the LiteLLM article. Here the focus is Haystack components plus OpenClaw for governed tools.
When do I choose LangGraph instead? If you need graph-native checkpointing and branching agents, read the LangGraph gateway guide. Haystack shines when retrieval centric pipelines stay linear and testable.
What about pure inference routing without RAG? Use the vLLM OpenAI compatible path for model-only traffic; keep this schema fuse for document heavy workloads.
Public pages (no login): Review pricing and purchase before reserving a node, browse the Help Center, and explore the Tech Blog index for related routing guides.