Fix: Claude Code 403 "Request not allowed" on macOS with Proxy/VPN (China & Region-restricted Areas)

Open 💬 2 comments Opened Mar 3, 2026 by KanTong0626

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/troubleshooting

Section/Topic

Network Configuration / Proxy Setup for Region-restricted Areas

Current Documentation

The troubleshooting docs say: "Behind a proxy: corporate proxies can interfere with API requests. See network configuration for proxy setup." But it doesn't explain that the terminal and Desktop app don't inherit system proxy settings, which causes persistent 403 errors for all users in region-restricted areas.

What's Wrong or Missing?

Root Cause

Claude Code's API requests go through a different endpoint than the regular claude.ai chat interface. If you're in a region where Anthropic services are restricted (e.g., China), your browser may route through your proxy/VPN correctly, but the terminal and the Desktop app do not inherit your system proxy settings.

Key diagnostic evidence:

# Browser/chat works fine through system proxy
curl https://api.anthropic.com/v1/models
# ✅ Returns: {"type":"error","error":{"type":"authentication_error",...}}
# (authentication error = network is working, just no API key provided)

# But without proxy, direct connection gets blocked
curl https://claude.ai
# ❌ 302 redirect to https://www.anthropic.com/app-unavailable-in-region

The critical issue: macOS GUI apps (including Claude Desktop) and terminal sessions do NOT automatically use your VPN/proxy even when "Set as System Proxy" is enabled in your proxy client (Clash/ClashX/V2Ray/Surge etc.).

Solution

Step 1: Fix CLI (Terminal)

Add proxy environment variables to your shell config:

# For Clash (default port 7890), add to ~/.zshrc or ~/.bashrc:
echo 'export https_proxy=http://127.0.0.1:7890' >> ~/.zshrc
echo 'export http_proxy=http://127.0.0.1:7890' >> ~/.zshrc
echo 'export all_proxy=socks5://127.0.0.1:7890' >> ~/.zshrc
source ~/.zshrc

Note: Replace 7890 with your actual proxy port. Check your proxy client settings for the correct port number.

Then clean up and re-authenticate:

rm -rf ~/.claude
claude auth login

Verify with /status inside Claude Code — you should see:

Login method: Claude Max Account (not "Claude API Account")
Proxy: http://127.0.0.1:7890**

Step 2: Fix Desktop App

The Claude Desktop app is an Electron app that does NOT read ~/.zshrc. Two approaches:

Option A: Launch with proxy env vars (quick test)

open -a "Claude" --env https_proxy=http://127.0.0.1:7890 --env http_proxy=http://127.0.0.1:7890

Option B: Set system-level env vars (permanent)

launchctl setenv https_proxy http://127.0.0.1:7890 launchctl setenv http_proxy http://127.0.0.1:7890 launchctl setenv all_proxy socks5://127.0.0.1:7890

Then launch Claude Desktop normally. Note: launchctl setenv does not persist across reboots. To make it permanent, create a LaunchAgent plist or add these commands to a login script.

Step 3: Verify

In Claude Code (CLI or Desktop), type /status and confirm:

Login method: Claude Max Account or Claude Pro Account

Proxy: shows your proxy address

Model: should show the model tier matching your subscription

Diagnostic Commands

If you're still having issues, use these to diagnose:

# 1. Check if proxy is set in terminal echo $HTTP_PROXY $HTTPS_PROXY $ALL_PROXY # 2. Test API connectivity through proxy curl --proxy http://127.0.0.1:7890 https://api.anthropic.com/v1/models # 3. Check if you're being region-blocked curl -v https://claude.ai 2>&1 | grep "location" # If you see "app-unavailable-in-region", you need a proxy # 4. Check DNS resolution nslookup api.anthropic.com 8.8.8.8

Environment

macOS (Apple Silicon / Intel)

Claude Code v2.1.63 (npm install)

Proxy: ClashX / Clash Verge / V2Ray / Surge

Subscription: Claude Pro or Max

Region: China (applies to any region-restricted area)

Related Issues

#24485 — Desktop app persistent 403 after CLI works fine (macOS)

#1613 — API Error: 403 "Request not allowed"

#8747 — API Error 403 Please run /login

#18816 — Authentication loop with 403 error

#12383 — Desktop always shows "Claude API Account" instead of subscription

TL;DR

Claude Code needs proxy env vars explicitly set. Your browser uses system proxy, but the terminal and Electron apps don't. Set https_proxy, http_proxy, and all_proxy in both your shell config AND via launchctl setenv for the Desktop app.

Suggested Improvement

Add a dedicated section to the troubleshooting docs for users in region-restricted areas (e.g., China). The docs should explain:

Terminal and Electron apps do NOT inherit system proxy settings, even when "Set as System Proxy" is enabled in Clash/V2Ray/Surge

Users must explicitly set https_proxy, http_proxy, and all_proxy environment variables

For CLI: add proxy exports to ~/.zshrc

For Desktop app: use launchctl setenv or launch with open -a "Claude" --env https_proxy=...

Without proxy, /status shows "Claude API Account" instead of "Claude Max Account", and all API calls return 403

See the full solution in the "What's Wrong or Missing" section above.

Impact

High - Prevents users from using a feature

Additional Context

Related issues: #24485, #1613, #8747, #18816, #12383

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗