Proxy and API URLs only—not keys or quota
If the UI opens but model calls time out, fail certificate checks, or cannot finish TLS—and the error text has no 401/429/quota—the usual culprit is system proxy, in-app proxy, HTTPS_PROXY, or corporate TLS inspection—not a bad install.
The connection-troubleshooting guide still owns the end-to-end checklist; the API key article owns secrets and billing. This page deep-dives the proxy layer: who forwards traffic, whether the API base URL was rewritten, and whether the certificate chain was replaced. No named “airport”/node vendors, and no bypass recipes for controls you are not authorized to defeat.
Three paths: direct, system proxy, app proxy
Direct: OpeClaw calls the provider Base URL as configured. Fine on home networks without SSL inspection.
System proxy: the OS or a global proxy client owns outbound traffic. If OpeClaw follows the system proxy, a dead system proxy looks like “cannot connect to models.”
App / environment proxy: a custom HTTP(S) proxy in settings, or HTTPS_PROXY injected before launch. It may override the system proxy or apply only to some child processes—follow whatever the current release documents.
- Write down one primary mode: direct, system, or custom—avoid stacking all three.
- Copy the raw error (timeout, CERT, proxy refused) before changing settings.
- Confirm the install source on the download page so menu names match the docs you are reading.
How to verify HTTPS_PROXY and API addresses
Environment: point HTTPS_PROXY (and HTTP_PROXY if required) at a proxy endpoint you are allowed to use, in the format the client docs expect. Put localhost, 127.0.0.1, and intentional LAN ranges in NO_PROXY so Ollama / LM Studio are not forwarded.
In-app: open Model Providers and confirm the Base URL still matches the vendor’s documented official or compatible endpoint. If a “one-click URL rewrite” script pointed you at an unknown host, restore a verifiable URL before debugging proxy knobs.
After changing variables or proxy toggles, fully quit and relaunch. Editing the environment without a restart leaves the old process config. Never put secrets in proxy URL query strings or public screenshots.
Corporate gateways and TLS interception
Many workplaces terminate HTTPS and re-issue certificates with an enterprise CA. Browsers that already trust that CA look fine; a desktop app without the same root shows invalid certificate, peer verification failure, or TLS handshake failed.
Compliant order: confirm SSL inspection with IT → install the enterprise root into the system trust store per policy → request allowlisting for model API hosts if needed → retry in OpeClaw. Do not default to “disable certificate verification.”
If the office network fails but a phone hotspot works, treat it as gateway policy—not a corrupted OpeClaw install. Capture the symptom for the ticket instead of reinstalling in a loop.
Lawful network use and source boundaries
This site only helps you debug configurations on networks you are authorized to use. We do not invent proxy vendor names or teach unauthorized circumvention of enterprise security controls. On work devices, proxy and allowlist rules follow IT policy.
Treat installers and proxy tools as supply-chain risks: prefer the release status on this site’s download page; reject bundled “proxy + crack + one-click model” packages from unknown forwards. If a proxy client crashes, fall back to direct or documented system proxy settings before retesting models.
Traffic through a corporate gateway may be audited. Keep API keys and sensitive prompts within your organization’s data-egress rules—connectivity is not the only goal.
When to leave this page
Errors mention 401 / invalid api key / 429 / quota → use the API key & quota article.
You need the full source → key → port checklist → use the connection-troubleshooting guide; this page is the proxy/TLS deep dive.
Base URL is 127.0.0.1 and the local server or model name is wrong → use local LLM setup, and verify NO_PROXY.
The app never shows a UI → use the won’t-open guide. Need an install entry → check the download page.
Proxy-to-model checklist table (no new claims)
This table only restates the splits above. It does not change “proxy layer vs key layer,” “certificates → IT / enterprise CA,” or “do not disable TLS verification by default.”
| Symptom | Do this first | Common mistake |
|---|---|---|
| Timeout / connection reset | Check system/app proxy and HTTPS_PROXY | Rotate API keys immediately |
| Certificate / TLS handshake failure | Enterprise CA and gateway SSL inspection | Disable cert checks to “make it work” |
| Fails only on corporate Wi-Fi | Ask IT for allowlist or root CA | Reinstall the client repeatedly |
| Cloud OK, local Ollama fails | NO_PROXY for localhost | Force loopback through the global proxy |
| 401 / 429 | API key & quota article | Toggle proxy switches at random |
Proxy UI labels vary; this page does not name third-party node vendors or promise IT turnaround times.
Proxy & Model Connection FAQ
System proxy is on but OpeClaw still cannot reach models—what first?
Separate proxy/TLS failures from key/quota failures. Timeouts, certificate errors, and TLS handshake failures point to system or app proxy and corporate gateways; 401/429 belong on the API key & quota article.
I set HTTPS_PROXY but OpeClaw ignores it. Why?
Match variable names to the current release notes (often HTTPS_PROXY / HTTP_PROXY / NO_PROXY), fully restart the app started from that environment, and check whether an in-app “use system proxy / custom proxy” toggle overrides the shell variables.
Corporate gateway says the certificate is untrusted—should I disable TLS verification?
Do not disable certificate checks just to get online. Install the enterprise root CA via IT, or request an allowlist for the model API host under your policy. Skipping TLS exposes keys to interception risk.
Cloud models work through the proxy but local Ollama fails?
Loopback hosts usually need NO_PROXY (127.0.0.1, localhost). When a global proxy forwards local traffic, local LLMs time out. Keep cloud and local routing rules separate.
Use this with an OpeClaw workflow
Check the current OpeClaw download status first, then save this guide as part of your setup, review, or troubleshooting workflow.