proxy.enabled · OPENCLAW_PROXY_URL · eight-step runbook · VNC checks
OpenClaw v2026.4.27 formalizes operator-managed outbound HTTP forward-proxy routing for the runtime: enable via configuration (proxy.enabled, proxy.proxyUrl) or shell-only OPENCLAW_PROXY_URL, with strict validation of http:// forward-proxy URLs and cleanup of proxy dispatcher state on exit. The same release tightens Gateway boot behavior and continues the migration toward manifest-first plugin metadata, which changes how long “cold start” feels when provider discovery or pricing refreshes compete for bandwidth. If you deploy inside a bank, OEM, or regional office that mandates a single egress host, the failure mode is rarely “OpenClaw forgot proxy support” — it is loopback console traffic being dragged through the wrong path or TLS interception breaking halfway through model catalog downloads. This guide separates inbound reverse-proxy TLS (how users reach Gateway) from outbound forward-proxy policy (how Gateway reaches OpenAI, Anthropic, Slack APIs, etc.), gives an eight-step runbook, a symptom matrix, four ticket-grade facts, and a VNC checklist on a rented Mac. Pair it with corporate desktop/VNC access triage and Gateway reverse proxy hardening — they solve different edges of the graph.
macOS “Automatic proxy configuration” helps Safari and many GUI apps, but Node-based CLIs frequently ignore it unless you export classic variables such as HTTP_PROXY. OpenClaw’s explicit knobs reduce guesswork: you declare the forwarder once at the OpenClaw layer, validate scheme, and rely on shutdown hooks to avoid stale dispatcher wiring after rotations. That does not automatically enroll Chrome profiles used by Meet or browser automation — those still honor their own proxy policies — so your runbook must mention both stacks.
Release notes also highlight loopback-only Gateway bypass semantics: punching local Control UI traffic through a corporate MITM often yields confusing WebSocket failures that look like application bugs. Treat “localhost console” and “internet APIs” as two routing tables; copying one row into the other is how midnight incidents begin.
Operator intent: audited egress with rotating credentials instead of ad hoc exports in twelve shell profiles.
TLS realities: transparent proxies must present corporately trusted roots to OpenClaw’s TLS stack; otherwise you will chase phantom “model outage” errors.
Separation from inbound: terminating TLS on nginx/Caddy in front of Gateway does not magically configure upstream fetch behavior — keep docs distinct.
Secrets hygiene: align proxy passwords with SecretRef workflows where applicable.
Telemetry: capture handshake timings before and after proxy enablement; attach them to change tickets.
Use the matrix as a routing function for on-call engineers. When the last column reads “misread as …”, stop repeating that playbook.
| Symptom | Investigate first | Then | Misread as |
|---|---|---|---|
| Gateway healthy but channels stall minutes | Outbound catalog/pricing fetch blocked by proxy | Plugin manifest regeneration path | “Telegram plugin regression” |
| 407 / proxy auth loops | Mismatched credentials between launchd and interactive shells | PAC file overriding explicit URL | “Provider rate limit” |
| Control UI WS failures | Browser forced through corporate proxy for localhost | Missed Upgrade headers on reverse proxy | “OpenClaw SSL bug” |
| Spiky CPU during boot only | Parallel manifest scans | Disk contention on small cloud disks | “Need bigger LLM” |
Measure boot-to-ready and channel-ready independently; merge them only after both timelines are green.
v2026.4.27 also ships broader reliability work (Telegram bounds, Slack socket timeouts, Gateway prewarm ordering). If your regression coincides with unrelated channel fixes, bisect by temporarily disabling nonessential plugins rather than toggling proxy twice per minute.
Execute sequentially on a staging host that mirrors production egress. Document proxy URL, authentication domain, and emergency bypass approval ID before touching prod.
Pin versions: confirm openclaw --version reports v2026.4.27 (or your pinned patch) and note Node distribution.
Archive configs: tarball config roots plus launchd plist or systemd unit fragments.
Raw egress test: from the same service account, run curl -v against two providers and the corporate PAC fetch URL if any.
Apply OpenClaw proxy: enable structured keys or export OPENCLAW_PROXY_URL for the daemon environment only; avoid duplicating conflicting legacy HTTP_PROXY unless required.
Doctor gate: run openclaw doctor; fix schema warnings before restart loops waste quota.
Restart & timestamp: log wall-clock from process start to first healthy channel marker.
Low-risk chat probe: send a minimal prompt without heavy tooling on two channels.
Publish notes: link this change to common error patterns for future triage.
export OPENCLAW_PROXY_URL="http://proxy.corp.example.com:8080" openclaw doctor openclaw gateway restart
Note: Keys evolve; trust openclaw doctor and official docs over copy-pasted YAML fragments.
Perform under the same macOS user as the Gateway service. SSH tailing logs alone misses browser-side proxy overrides.
| Check | How | Pass |
|---|---|---|
| System proxy | Network settings / PAC. | Matches declared policy; no drift. |
| Control UI | Browser devtools Network tab. | WS 101; no mixed content. |
| Daemon env | inspect parent environment. | Matches ticketed values. |
| Dual curl | Two providers through proxy. | Stable TLS without retries. |
| Channel probe | Low-risk message. | No retry storm. |
Renting a dedicated cloud Mac isolates proxy experiments from your laptop’s roaming Wi‑Fi profiles: you snapshot one image, prove the stack, then promote — cheaper than debugging PAC wars during an outage on a single shared ultrabook.
Inbound TLS vs outbound forward-proxy responsibilities.
Read →Reach the Mac before tuning OpenClaw egress.
Read →Large upgrades alongside networking changes.
Read →No automatic replacement — align both deliberately and watch for PAC overrides.
Keep localhost console traffic exempt; send upstream HTTPS via the approved forwarder.
Check Gateway boot timeline and outbound TLS before reinstalling bundles.
CLI covers much; browser-facing checks still need VNC-level verification.
Outbound proxy support turns opaque “why is Slack wedged” incidents into routable networking tickets — but only if you respect loopback semantics and capture timelines.
Owning one laptop that hops Wi‑Fi networks weekly makes PAC testing noisy; a rented Apple Silicon Mac gives you a stationary sandbox.
Need that sandbox under NDA-friendly turnover? Use VNCMac: primary button to the purchase page, compare plans on the home page, then rerun section five on the node.