Skip to content
CC Switch WikiUnofficial Community Wiki

Unexpected status 502 Bad Gateway：Codex

Quick fix

Set NO_PROXY=127.0.0.1,localhost,::1 in ~/.codex/.env so Codex connects directly to the local CC Switch port.

Symptom

Section titled “Symptom”
Error output
Unexpected status 502 Bad Gateway: Unknown error, url: http://127.0.0.1:15721/v1/responses

Cause

Section titled “Cause”

Codex reads the system proxy and environment variables such as `HTTP_PROXY` and `HTTPS_PROXY`. Requests intended for the local CC Switch `/v1/responses` endpoint may be intercepted by proxy software such as Clash. The proxy cannot handle the local request correctly and returns 502. Multiple users confirmed that direct routing for localhost and 127.0.0.1, or setting `NO_PROXY`, resolved the issue.

The reported behavior varies. Disabling the system proxy, using TUN mode, or changing Clash rules worked for some users. Others reported that errors persisted in TUN mode and that rule mode and global mode behaved differently. The maintainer also noted that a 502 may be passed through from the upstream provider, or caused by connection, timeout, or TLS failures between CC Switch and the upstream service. If local direct routing does not help, investigate the upstream network.

Fix

Section titled “Fix”

  1. Check whether `HTTP_PROXY` or `HTTPS_PROXY` is set in `~/.codex/.env`. On Windows, also check the system proxy settings.

  2. Add direct routing for local addresses to `~/.codex/.env`. The `7890` below is the proxy port from the issue; use your actual port if it differs.

    ~/.codex/.env
    HTTP_PROXY=http://127.0.0.1:7890/
    HTTPS_PROXY=http://127.0.0.1:7890/
    NO_PROXY=127.0.0.1,localhost,::1

  3. Use Codex to access CC Switch again. Multiple users confirmed that creating or modifying the `.env` file resolved the issue.

  4. If the error persists, temporarily disable the Clash system proxy or switch to TUN mode and retry. These methods worked for some Windows and macOS users, but not in every report.

  5. If bypassing the local proxy still returns 502, check whether the upstream provider is returning 502 and whether the CC Switch connection to the upstream service has connection, timeout, or TLS errors.

Affected Versions

Section titled “Affected Versions”
ToolCodex
Version受影响报告：CC Switch 3.14.1 - 3.16.4
PlatformsWindowsmacOS

Source Issues

Section titled “Source Issues”

This page is distilled from 7 real issues

FAQ

Section titled “FAQ”
How can I fix this error when the latest CC Switch still returns it after connecting to DeepSeek and enabling routing?
First, set `NO_PROXY=127.0.0.1,localhost,::1` in `~/.codex/.env`. Affected users confirmed that the issue came from a conflict between local routing and the Clash proxy. Disabling Clash also restored normal operation.
Why does it still fail after configuring direct routing for localhost and 127.0.0.1 in Clash?
Some users in the thread reported that direct-routing rules did not work. Set `NO_PROXY` in Codex's own `~/.codex/.env`, or temporarily disable the system proxy. If it still fails, follow the maintainer's guidance and check upstream responses and connection, timeout, or TLS problems.
Will switching to TUN mode always fix it?
No. Switching to TUN mode immediately restored service in the main report, but another user still encountered the error after enabling TUN. A more reliable approach is to confirm that Codex does not proxy requests to `127.0.0.1` and `localhost`.
Why does Claude Code work while only Codex fails?
Related reports show that with the same CC Switch configuration and upstream service, Claude Code worked while the Codex desktop app, VSCode extension, and CLI all failed. The thread attributes this to Codex reading the system proxy or environment variables, causing the local `/v1/responses` request to be intercepted by the proxy.
Section titled “Related problems”
Provider API Key Overwritten: After Codex Restart or SwitchUpgrade to cc-switch v4.0.0 or later to prevent provider keys from overwriting each other and restore the official login state.6 issues mergedThe `content[].thinking` in thinking modeSome variants remain unresolved: upgrade to a version with the thinking history normalization fix; for Codex routed through DeepSeek, use a version with the…13 issues merged"Failed to upload "image.png"" screenshot upload failedThis is not a cc-switch error. GitHub failed to upload the screenshot. Re-upload it or paste the error as text so maintainers can see it.10 issues merged

This is an unofficial community wiki with no affiliation to the cc-switch authors or the project itself. Its content is compiled from the project's public GitHub issues. This site distributes no software.