Skip to main content

Connect OpenClaw

Use Primex as a custom model provider for OpenClaw's local agent turns. This guide uses Chat Completions, with the openai-completions adapter. Choose an eligible model in OpenClaw Setup. This configures the reasoning model; it does not install a Primex MCP server.

Install and configure​

The reviewed release, OpenClaw 2026.10.8, requires Node.js 24.22.1 or newer in the 24.x series, or 26.12.1 or newer. Follow OpenClaw's official installation instructions. For a version-matched npm installation:

Shell
npm install -g openclaw@2026.10.8
export PRIMEX_API_KEY=YOUR_API_KEY

Merge this into ~/.openclaw/openclaw.json, replacing both model placeholders with the same exact Primex offering ID. Keep existing agents, providers, tools and approval settings.

JSON
{
"agents": {
"defaults": {
"model": { "primary": "primex/YOUR_LIVE_CHAT_MODEL" },
"timeoutSeconds": 60
}
},
"models": {
"mode": "merge",
"providers": {
"primex": {
"baseUrl": "https://gateway.primexos.com/v1",
"apiKey": "${PRIMEX_API_KEY}",
"api": "openai-completions",
"models": [
{ "id": "YOUR_LIVE_CHAT_MODEL", "name": "Primex model" }
]
}
}
}
}

OpenClaw resolves ${PRIMEX_API_KEY} from the environment of its process. Export it in the shell that launches the client. A separately running service needs its own environment configuration; changing your shell does not update that service. Never paste a key into an agent conversation or commit it with the config.

The model-aware Setup configuration also includes contextWindow and maxTokens when the selected offering publishes them. Use those current values rather than OpenClaw's generic model defaults. If either limit is unavailable, confirm it before loading long histories or enabling lengthy agent tasks. The 60-second setting bounds an agent turn; it is not proof that every underlying request has that deadline or that automatic retries are disabled.

See the official custom-provider reference. Other adapters, image inputs, reasoning options, fallback models and auxiliary requests need their own model and feature verification.

Verify a local turn​

Use a disposable agent workspace and send one short prompt:

Shell
openclaw agent --local --agent main --session-id primex-first-request \
--message "Hello from Primex" --json

Read the returned answer and inspect its requests in Usage. --local runs the agent locally without requiring a running OpenClaw Gateway. Keep channel delivery and scheduled tasks disabled for this first check.

Next, place a harmless README in the disposable workspace and ask the agent to read its first heading. Keep your tool approvals and confirm that a file-read result leads to a final model answer. A text response alone does not verify tools. One task can make several model calls; inspect Usage and use a dedicated key with an appropriate spending cap before broader work.

OpenClaw's local cost estimate can default to zero when its provider cost table is missing. That estimate is not a Primex bill; use Usage for the actual charge.

Common fixes​

  • Model missing: match primex/MODEL_ID to the exact ID under the primex provider. Provider registration and selecting a default model are separate.
  • 401: check that the launching process can read PRIMEX_API_KEY, and that the key is active. A service may still have an older environment.
  • Incomplete package lifecycle: install with package scripts enabled. The reviewed package's launcher requires its postinstall step to complete.
  • Wrong endpoint: this configuration calls /v1/chat/completions; a model with only Responses or Messages support cannot use this adapter.
  • Context or output error: reconcile the configured limits with the selected model's current Catalog values. Do not assume upstream defaults apply.
  • Tool, reasoning or parameter error: check published capabilities and remove unsupported options. Tool success, fallback routing and background execution need separate checks for each selected model.
  • Timeout or uncertain outcome: inspect Usage before repeating the task. A client error does not establish that no provider work or charge occurred.

See Errors & limits for request and billing investigation.

Remove the configuration​

Restore your previous default model and remove the primex provider. Remove the key from each shell or service environment you configured, restart affected processes, and revoke the dedicated Primex key if it is no longer needed. Keep unrelated providers and agent settings.

Need help connecting? Report a setup issue.