API Error: Connection refused (ECONNREFUSED) Claude Code

Quick fix

在 Windows 的 WSL2 NAT 模式中，用 socat 将 WSL 的 127.0.0.1:15721 转发到宿主机 CC Switch 路由端口。

Symptom

报错原文复制

API Error: Connection refused (ECONNREFUSED)

Cause

WSL2 默认 NAT 模式下，WSL 内的 `127.0.0.1` 指向 WSL 自身，并不等同于 Windows 宿主机的回环地址。CC Switch 向客户端写入 `http://127.0.0.1:15721/claude-desktop` 后，运行在 WSL 内的 Claude Code 会话会连接到自身，因此无法到达宿主机路由。

仅将 CC Switch 的监听地址改为 `0.0.0.0` 不一定会改变下发给客户端的 `inferenceGatewayBaseUrl`；报告中该地址仍为 `127.0.0.1`。社区临时方案是在 WSL 内监听该回环端口，并用 `socat` 转发至 Windows 网关 IP。

Fix

1. 1

   将 CC Switch 路由监听地址设为 `0.0.0.0:15721`，然后启动路由。注意该监听方式可能暴露到其他 Windows 网络接口，应通过 Windows 防火墙限制访问。

2. 2

   在 WSL 中安装 `socat`：`sudo apt update`，然后执行 `sudo apt install -y socat`。

3. 3

   获取 WSL NAT 网络中的 Windows 网关 IP：`WINDOWS_IP="$(ip -4 route show default | awk '/default/ {print $3; exit}')"`。

4. 4

   在 WSL 中启动本地转发：`socat TCP4-LISTEN:15721,bind=127.0.0.1,reuseaddr,fork TCP4:"${WINDOWS_IP}":15721`。此命令会把 WSL 的 `127.0.0.1:15721` 转发到 Windows 上的 CC Switch 路由。

5. 5

   确认 Agent 请求地址使用 `http://127.0.0.1:15721`，并保留原有的 `/v1` 等路径。切换提供商、重新注入或重启路由后，CC Switch 可能覆盖该地址，需要再次检查。

Affected Versions

ToolClaude Code

Versionv3.18.0 - v3.20.4（报告为受影响版本）

PlatformsWindowsLinux

Source Issues

本页汇总自 2 个真实 issue

• #5661win10 系统下wsl2不能使用镜像模式，这使得cc的路由根本无法导航
• #7877[Bug] 本地路由 + WSL：下发给客户端的网关地址固定为 127.0.0.1，WSL 内会话必然 ECONNREFUSED（v3.20.4 仍复现，见 #5661）

FAQ

把 Listen Address 改成 `0.0.0.0` 为什么仍然无法连接？

报告显示监听地址虽已变为 `0.0.0.0`，但写入 Claude Desktop 配置的 `inferenceGatewayBaseUrl` 仍是 `http://127.0.0.1:15721/claude-desktop`，WSL 内会话仍会连接到自身回环地址。

能否在 WSL 的 `~/.claude/settings.json` 覆盖 base URL？

该报告中无法生效，因为 App 注入的进程环境变量优先级高于 `settings.json`。

相关问题

[DISCUSS] 支持 pi coding agent这是功能请求，维护者已将其合并至统一追踪 issue #1855，原帖未提供可验证的解法。1 issues merged无法正常启动，窗口无响应，被系统要求force quit将 CC Switch 更新到经过相关功能重构的 4.0 或最新版本后重试；若仍复现，提交完整版本、步骤、日志和截图。1 issues mergedcmd.exe console window flashes先更新到 4.0 或最新版本重试；若仍闪窗，请提交版本、系统、完整复现步骤及日志或截图。1 issues merged