Open Claw Integration Guide¶
This guide covers the maintained OpenClaw integration for Primr.
Primr is exposed to OpenClaw through primr-mcp. Skills and workflows should treat MCP as the source of truth for current modes, defaults, status, and outputs.
Portable package and maintained deployment¶
OpenClaw is listed in the Agent Plugins v1 compatible-client registry for
Agent Skills and MCP transports. The experimental agent-plugin/ directory is
therefore a portable discovery option. Its MCP entry launches the bare primr
executable, which must already be installed and discoverable by OpenClaw.
The deployment below remains Primr's maintained OpenClaw integration because it includes the pinned sandbox build, explicit environment wiring, and Primr's OpenClaw workflows. Loading either package only discovers skills and MCP configuration. It does not launch research or authorize provider spend.
Prerequisites¶
-
Python 3.12+
-
Primr installed
-
OpenClaw installed
-
XAI_API_KEYfor the standard default workflow,GEMINI_API_KEYfor premium mode, or both -
Optional:
SEARCH_API_KEYandSEARCH_ENGINE_IDif you want Google Custom Search instead of DuckDuckGo
Installation¶
1. Install Primr¶
2. Copy the OpenClaw assets and pinned build inputs¶
The sandbox image is built from the same source and dependency lock snapshot as the installed release. Keep these files together in the OpenClaw build context.
# Linux/macOS
cp -r openclaw/* ~/.openclaw/
cp pyproject.toml MANIFEST.in README.md ~/.openclaw/
cp -r src ~/.openclaw/src
mkdir -p ~/.openclaw/deploy
cp deploy/build-requirements.lock deploy/runtime-requirements.lock ~/.openclaw/deploy/
# Windows
xcopy /E /I /Y openclaw %USERPROFILE%\.openclaw
xcopy /E /I /Y src %USERPROFILE%\.openclaw\src
if not exist %USERPROFILE%\.openclaw\deploy mkdir %USERPROFILE%\.openclaw\deploy
copy /Y pyproject.toml %USERPROFILE%\.openclaw\
copy /Y MANIFEST.in %USERPROFILE%\.openclaw\
copy /Y README.md %USERPROFILE%\.openclaw\
copy /Y deploy\build-requirements.lock %USERPROFILE%\.openclaw\deploy\
copy /Y deploy\runtime-requirements.lock %USERPROFILE%\.openclaw\deploy\
3. Configure environment variables¶
export XAI_API_KEY="your-xai-api-key"
export GEMINI_API_KEY="your-gemini-api-key"
# Optional fallback search config
export SEARCH_API_KEY="your-google-search-api-key"
export SEARCH_ENGINE_ID="your-search-engine-id"
4. Verify the installation¶
What the integration provides¶
Skills¶
-
primr-research: estimate, start, and monitor research jobs -
primr-strategy: estimate and generate strategy deliverables from existing reports -
primr-qa: run QA and diagnostics
Workflow¶
research-pipeline: estimate, approval, execution, and monitoring for a full research runstrategy-pipeline: estimate, approval, and governed strategy generation from an existing report
Operating model¶
-
Read
primr://research/modesbefore advising on mode selection. -
Call
estimate_runbefore starting new research work and show the user the expected cost/time. -
The packaged research workflow propagates the approved estimate as
max_estimated_cost_usdintoresearch_company, and the packaged strategy workflow does the same forgenerate_strategy. MCP enforcement is on by default for every transport. -
Treat
fullas the standard end-to-end mode. - Expect long runtimes: standard runs are often 35-50 minutes, and premium multi-vendor runs can take 75-120 minutes.
-
Build around async monitoring and reconnection, not one long blocking session.
-
Use
premiumonly when the user explicitly wants maximum-depth research. -
Use
primr://research/status,wait_for_status_change, orcheck_jobsfor monitoring. -
After completion, read
primr://output/artifacts/by_job/{job_id}before requesting report previews. It returns compact artifact metadata for the owned job without report body content, which keeps OpenClaw workflows from loading large reports unless a downstream step explicitly needs them. - If QA artifacts are attached, read
primr://output/qa_summary/by_job/{job_id}for compact score/status/count metadata without loading detailed QA text. - When OpenClaw needs cost, timing, approval, or artifact-count metadata, read
primr://output/usage_summary/by_job/{job_id}instead of loading the full run manifest. - When OpenClaw needs citation/source appendix health, read
primr://output/source_summary/by_job/{job_id}instead of loading the full report. - When OpenClaw needs scrape trace health, read
primr://output/trace_summary/by_job/{job_id}instead of loading trace logs. - When OpenClaw needs claim verification trust score, claim counts, status
counts, first-party downgrade counts, or source-reference counts, read
primr://output/verification_summary/by_job/{job_id}instead of loading raw claims, source URLs, search queries, explanations, or report body content. - When OpenClaw needs label-calibration counts, inference source-copy counts,
evidence-review count buckets, judge provenance, or judge-agreement metadata,
read
primr://output/calibration_summary/by_job/{job_id}instead of loading raw claims, source URLs, evidence reviews, rationales, or report body content. - MCP resource reads are audit-logged with normalized resource kind, hashed URI, hashed result body, job id when present, granted scopes, duration, and outcome. The audit log does not persist raw URI query values or resource bodies. A2A skill calls are audit-logged with hashed message/result payloads, hashed caller ids, granted scopes, duration, outcome, and job id when present, without raw message text, task ids, URLs, report paths, raw results, or caller ids.
Troubleshooting¶
primr-mcp is not found¶
API keys are missing or incorrect¶
Confirm the relevant provider key is available in the environment passed to OpenClaw.
A run looks stuck¶
-
Read
primr://research/status -
Check whether
possibly_stuckis true -
Use
cancel_jobonly if the run is no longer making progress
Docker sandbox¶
docker build -f openclaw/Dockerfile.primr -t primr-sandbox .
docker run -e XAI_API_KEY -e GEMINI_API_KEY -e SEARCH_API_KEY -e SEARCH_ENGINE_ID -v ./output:/workspace/output primr-sandbox