NativePort
Sign in Get a key
← How-to

How to use OpenClaw with NativePort

Wire OpenClaw's custom-provider onboarding to NativePort's unified inference endpoint: the one required config fix and a real tool-call round trip.

OpenClaw is a personal AI assistant and multi-channel agent gateway: one runtime that holds a conversation, runs local tools, and talks across chat channels, all driven by whichever model you configure. It doesn’t ship a model of its own — every agent needs a provider to think with. Point OpenClaw’s built-in custom-provider mechanism at NativePort’s unified inference endpoint, and the same key and balance covering NativePort’s other search, scraping, browser-automation and voice APIs also covers OpenClaw’s model calls. Switching models later is a one-line id change on both sides, with no separate OpenAI or Anthropic account to stand up first. This guide wires up that one connection; it doesn’t replace OpenClaw’s own channels, tools or memory, and it isn’t a substitute for OpenClaw itself.

What you’ll need

  • A NativePort API key. Sign up to get a key and $5 in credits.
  • OpenClaw’s current stable release (2026.7.1-2 at the time of writing) and its runtime prerequisite: Node 22.22.3+, 24.15+, or 25.9+ (Node 26 is the default/recommended runtime; Node 23 isn’t supported).
  • Install with the official script:
curl -fsSL https://openclaw.ai/install.sh | bash

On Windows: iwr -useb https://openclaw.ai/install.ps1 | iex. Via npm instead: npm install -g openclaw@latest (npm 12+ needs --allow-scripts openclaw appended to the install command), then openclaw onboard --install-daemon.

  • Your NativePort key exported as an environment variable, never hardcoded:
export NATIVEPORT_API_KEY="<your NativePort API key>"

Onboard OpenClaw non-interactively

OpenClaw’s onboarding wizard has a non-interactive mode built for exactly this: pointing it at a generic OpenAI-compatible backend instead of running through the interactive prompts. Its --secret-input-mode ref option is the safe way to do it — it stores a reference to an environment variable in openclaw.json rather than writing your key to disk in plain text. The one catch: for this flow, OpenClaw’s non-interactive path reads that key from a fixed environment variable name, CUSTOM_API_KEY, not whatever name you export it under elsewhere:

export CUSTOM_API_KEY="$NATIVEPORT_API_KEY"

openclaw onboard --non-interactive --accept-risk \
  --mode local --auth-choice custom-api-key \
  --custom-base-url "https://api.nativeport.ai/inference/v1" \
  --custom-model-id "openai/gpt-5.4-mini" \
  --custom-provider-id "nativeport" \
  --custom-compatibility openai \
  --custom-image-input \
  --secret-input-mode ref \
  --workspace ~/.openclaw/workspace
  • --custom-base-url is NativePort’s unified inference path, not the account or docs host.
  • --custom-model-id "openai/gpt-5.4-mini" is NativePort’s canonical model id: the openai/ prefix selects the route, everything after it is OpenAI’s own model name. This is the example model used throughout this guide; NativePort’s live catalog (queried below) is the source of truth for what else is available on your account.
  • --custom-compatibility openai maps to OpenClaw’s Chat Completions transport — the shape NativePort’s /inference/v1 route actually serves. Never openai-responses; that’s a different API shape this route doesn’t speak.
  • --custom-image-input is set because openai/gpt-5.4-mini reports vision support in NativePort’s catalog. Check capabilities.vision for whatever model you use before enabling it (see the catalog check below) — it isn’t a blanket yes across every model.
  • --secret-input-mode ref writes {"source":"env","provider":"default","id":"CUSTOM_API_KEY"} into openclaw.json instead of the literal key. The real key never touches disk.

Once this completes, OpenClaw has written a nativeport provider entry with one model row (openai/gpt-5.4-mini) into ~/.openclaw/openclaw.json. Two things in that generated row need a manual fix before the first real call.

Required fix: compat.supportsStore

OpenClaw’s stable release sends a store field on every completions request by default, regardless of provider. NativePort’s unified endpoint validates against a deliberately narrow, cross-provider field set and rejects anything outside it — store isn’t in that set, so the very first call 400s. The fix is one line, using OpenClaw’s own documented model-row schema. Open openclaw.json, find the generated nativeport/openai/gpt-5.4-mini model row, and add:

"compat": { "supportsStore": false }

With that in place, calls succeed normally — no other change needed.

Fix the wizard’s placeholder metadata

The onboarding wizard also auto-fills contextWindow, maxTokens and cost on the generated row with generic scaffolding values, the same numbers it writes for any custom-provider model regardless of which one you actually configured — it doesn’t query NativePort’s catalog for real data. Two different sources fix these correctly:

  • cost: pull the live, per-model rate from NativePort’s own catalog rather than trusting the wizard’s placeholder zeros:
curl -s https://api.nativeport.ai/inference/v1/models/openai/gpt-5.4-mini \
  -H "Authorization: Bearer $NATIVEPORT_API_KEY"

This returns the model’s current pricing, capabilities (tools, streaming, vision) and supported_parameters — check it before publishing anything that depends on a specific number, since catalog entries change.

  • contextWindow / maxTokens: NativePort’s catalog response doesn’t carry these fields at all — they’re not part of what the gateway exposes. Source them from OpenAI’s own current published limits for the model id you’re using, not from anything NativePort returns.

Validate and run a model call

openclaw config validate --json
openclaw models status
openclaw infer model run --local --model nativeport/openai/gpt-5.4-mini \
  --prompt "Reply with exactly: pong" --json

infer model run --local is the narrowest possible check: it resolves the configured model and auth and returns a completion, without starting a full agent turn or loading tools. A successful run returns ok: true, the completion text, and populated usage counts. Run it without --json if you’d rather watch the reply arrive live in the terminal — OpenClaw’s custom-provider transport streams by default, and NativePort’s /inference/v1 route serves that stream unbuffered.

Confirm a local file tool works end to end

The model config above is enough for plain text calls. To confirm tool use works too, run a real agent turn against a file in the agent’s configured workspace — OpenClaw’s file tools are constrained to that workspace directory, not an arbitrary path you pass on the command line:

echo "42" > ~/.openclaw/workspace/answer.txt

openclaw agent --local --agent <agentId> \
  --message "Read answer.txt in this directory and reply with exactly: the answer is <contents>" \
  --model nativeport/openai/gpt-5.4-mini --json

Substitute <agentId> with the agent id the onboarding step reported. agent --local runs the full loop: the model requests a file-read tool call, OpenClaw executes it against the workspace, the result replays back to the model as a second turn, and the final reply comes back in the same JSON envelope (ok, status, final, usage, toolSummary). A final value of the answer is 42 confirms the whole round trip — request shaping, tool-call parsing, tool-result replay and the closing reply — went through NativePort cleanly. There’s no separate agent exec subcommand on this release, and no --cwd flag; the workspace set during onboarding (--workspace above) is what scopes file access.

Security

  • Keep CUSTOM_API_KEY (and NATIVEPORT_API_KEY generally) in an environment variable or secret manager, never in a committed config file or a prompt. --secret-input-mode ref is what keeps it out of openclaw.json in the first place — don’t undo that by pasting the literal key back in later.
  • OpenClaw’s tool surface (exec, browser, file access, skills) is entirely client-side; NativePort never sees or executes any of it. Scope what a given agent’s workspace and allowed tools can reach the same way you would for any other agent runtime with shell or filesystem access.
  • No messaging channel needs to be configured to use or test this integration — infer model run --local and agent --local are both channel-free. Configure Telegram, Slack or any other channel only once you actually want the assistant reachable there, and treat each channel’s own credentials as a separate secret from NATIVEPORT_API_KEY.

Troubleshooting

  • 400 naming store. The compat.supportsStore: false fix above wasn’t applied to the model row, or was applied to the wrong provider entry.
  • 400 / model_not_available. The canonical id is real but not enabled for your account right now — re-run the catalog check above and pick from what it actually returns rather than assuming a fixed id always resolves.
  • 401 on every call. CUSTOM_API_KEY isn’t set in the environment openclaw runs in, or the SecretRef in openclaw.json points at a different variable name than what you exported.
  • 402 on every call. The NativePort balance is at $0. Every request fails closed rather than degrading, so top up and retry.
  • 429. Rate-limited; the response carries a retry-after value. OpenClaw’s own key-rotation logic doesn’t help here since there’s only one key configured — expect a real wait.
  • Image input rejected or ignored. Confirm capabilities.vision is actually true for the model id in the catalog check above before setting --custom-image-input; it’s a per-model flag, not a blanket capability.

What this costs

openai/gpt-5.4-mini through this route is metered at NativePort’s real, pass-through rate — $0.75 per 1M input tokens, $0.075 per 1M cached-input tokens, $4.50 per 1M output tokens as of the catalog check above, with no per-call markup. A zero balance fails every request with 402 rather than degrading output. See pricing for the full billing model.

Where to go next