Skip to content
CC Switch WikiUnofficial Community Wiki

API Error: Connection refused (ECONNREFUSED) Claude Code

Quick fix

In Windows WSL2 NAT mode, use socat to forward WSL's 127.0.0.1:15721 to the host CC Switch routing port.

Symptom

Section titled “Symptom”
Error output
API Error: Connection refused (ECONNREFUSED)

Cause

Section titled “Cause”

In the default WSL2 NAT mode, `127.0.0.1` inside WSL points to WSL itself, not the Windows host loopback address. After CC Switch writes `http://127.0.0.1:15721/claude-desktop` for the client, a Claude Code session running in WSL connects to itself and cannot reach the host route.

Changing the CC Switch listen address to `0.0.0.0` does not necessarily change the `inferenceGatewayBaseUrl` sent to the client; it remained `127.0.0.1` in the report. The temporary community workaround is to listen on this loopback port in WSL and use `socat` to forward it to the Windows gateway IP.

Fix

Section titled “Fix”

  1. Set the CC Switch route listen address to `0.0.0.0:15721`, then start the route. This may expose it on other Windows network interfaces; restrict access with Windows Firewall.

  2. Install `socat` in WSL: run `sudo apt update`, then `sudo apt install -y socat`.

  3. Get the Windows gateway IP in the WSL NAT network: `WINDOWS_IP="$(ip -4 route show default | awk '/default/ {print $3; exit}')"`.

  4. Start a local forwarder in WSL: `socat TCP4-LISTEN:15721,bind=127.0.0.1,reuseaddr,fork TCP4:"${WINDOWS_IP}":15721`. This forwards WSL's `127.0.0.1:15721` to the CC Switch route on Windows.

  5. Confirm the Agent request address uses `http://127.0.0.1:15721` and retains paths such as `/v1`. Switching providers, reinjecting, or restarting the route may overwrite this address, so check it again.

Affected Versions

Section titled “Affected Versions”
ToolClaude Code
Versionv3.18.0 - v3.20.4（报告为受影响版本）
PlatformsWindowsLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 2 real issues

FAQ

Section titled “FAQ”
Why can't it connect after changing the Listen Address to `0.0.0.0`?
The report shows that although the listen address became `0.0.0.0`, the `inferenceGatewayBaseUrl` written to the Claude Desktop configuration was still `http://127.0.0.1:15721/claude-desktop`, so the WSL session still connected to its own loopback address.
Can the base URL be overridden in WSL's `~/.claude/settings.json`?
It did not work in this report because App-injected process environment variables take priority over `settings.json`.
Section titled “Related problems”
[DISCUSS] Support for pi coding agentThis is a feature request merged into tracking issue #1855; the original post provides no verifiable solution.1 issues mergedCannot start normally: window unresponsive, system requires force quitUpdate CC Switch to 4.0 or the latest version and retry. If it persists, provide the full version, steps, logs, and screenshots.1 issues mergedcmd.exe console window flashesUpdate to 4.0 or the latest version and retry. If it persists, submit the version, system details, reproduction steps, and logs or screenshots.1 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.