OpenClaw API Key & Model Setup
2026 Complete Install Walkthrough
After you install OpenClaw, it is only an empty shell until a model is connected. A wrong API key, a local inference service that never started, or a default model that does not fit the task can all make OpenClaw look broken. This is still a full 2026 install-and-config walkthrough—we simply go deeper on the model, key, and first-run acceptance chain: when to use cloud vs local, how to store keys safely, and how the Dashboard proves the model is actually being called.
Key → provider → model id → network → logs
Dashboard and probe entry
Cloud / local / hybrid
1Install done ≠ model callable
Whether OpenClaw is actually usable depends far more on whether the model path is connected, keys are stored safely, and the default model fits the job than on whether npm install -g openclaw succeeded. A running gateway and a passing probe on port 18789 only mean the shell is up; real work needs a valid provider/model reference and auth. The sections below walk that chain inside the full install flow.
openclaw models status or a minimal Agent call and confirm upstream HTTP traffic and token usage in the logs.
2Before install: model and key prep
Before you start: ① the provider list your OpenClaw version supports (check official docs); ② a cloud API key and the correct env var name; ③ if you use local inference, a compatible HTTP endpoint already listening and enough RAM; ④ network reachability to the provider API or localhost port. For hybrid setups, be clear which machine runs the gateway and which runs inference.
3Official install and onboarding
Install Node 24 and the CLI, then run openclaw onboard (optionally with --install-daemon) to set the default model and gateway. Verify node -v and that launchd inherits your environment variables—otherwise keys disappear after reboot. For Node 24 and port 18789 details, see the
cold-start runbook.
4Cloud models and API keys
Built-in providers usually need auth only: openclaw onboard --auth-choice openai-api-key (exact flags follow the wizard), or export OPENAI_API_KEY="sk-your-placeholder" then openclaw models set provider/model. For a custom proxy, define models.providers and reference keys with ${ENV} placeholders—never literals. Verify with openclaw models status.
5Local model hookup
Local inference suits privacy and cost control; speed depends on your hardware. In models.providers, set a local baseUrl (e.g. http://127.0.0.1:PORT/v1) and the model id. curl the endpoint first, then start OpenClaw.
6How to accept cloud, local, and hybrid
| Check | Cloud model | Local model | Hybrid |
|---|---|---|---|
| Auth | models status shows provider authenticated |
Local endpoint needs no key or only an internal token | Both configs must appear in status |
| Connectivity | Outbound reachability to provider API | curl local baseUrl |
Probe each path separately—do not mix triage steps |
| Dashboard | 18789 healthy + session shows upstream requests | Logs show local HTTP calls | Primary model in cloud, sensitive steps localcommon |
| Cost / privacy | Pay per call; data leaves the machine | Power and hardware; data stays on device | Define which tasks use which path |
The Dashboard defaults to 127.0.0.1:18789 for gateway status and logs. If the page loads but nothing responds, work through the table row by row.
7First-run smoke test
openclaw agent --local --session-id smoke-test --message "Reply only: model OK" --timeout 90 — if JSON shows the expected provider/model and logs show outbound requests, the model chain is good.
8Model errors vs install errors
openclaw models list and verify provider/model spelling; for custom providers, check models.providers.*.models[].id.lsof -iTCP:18789, then inspect launchd—not a model API issue; do not rotate keys first.9Ongoing maintenance
Rotate keys on a schedule, track catalog changes with models list, and watch billing. After adding a provider, run openclaw models set to change the default primary model.
- 1Prep keys, network, and (optional) local endpoint before install
- 2Accept in four steps:
onboard→models status→ Dashboard → minimal Agent - 3Triage order: key → provider → model id → network/local service → logs
- 4Never commit secrets; separate model issues from port/permission issues
Mac mini makes the model chain easier
Gateway and local inference on macOS share one clear path: Node 24, launchd, and env inheritance work together. Mac mini M4 unified memory is a practical fit for mid-size local model trials; roughly 4W idle power suits 24/7 gateways, and Gatekeeper / FileVault help limit key exposure. If you want onboard and Dashboard acceptance to stay stable, a Mac mini M4 is a strong place to run this stack—and a good time to put that hardware in place.