When the CLI throws timeouts, doubt the model first and the wire second
Social timelines still treat every stalled AI tool as “another outage,” but terminal clients narrate failure with frustrating ambiguity. Claude Code may print generic network errors during login, hang after you approve the browser tab, or lose long streaming responses halfway through a refactor. Those patterns overlap with overloaded API clusters, yet they also match domestic transit that drops overseas TCP, middleboxes that kill idle HTTP/2 streams, and resolver paths that return addresses your split routing stack never tags as Anthropic. Before you swap models or keys, separate symptoms: TLS handshakes that never finish point to path problems; crisp HTTP 529 bodies with JSON detail point upstream. Most home labs see the former while blaming the latter.
The CLI stack makes the diagnosis harder because it is heterogeneous. One subprocess might call the public REST surface on api.anthropic.com, another might talk to console.anthropic.com for key management, and onboarding flows can bounce through claude.ai tabs that spawn deep links back into the binary. Any one of those legs can be direct while the others wander through a half-configured HTTP_PROXY, which feels random until you read connection logs. Your goal is to make every leg visible, stable, and explicitly proxied when policy demands it—without turning your laptop into an all-or-nothing VPN.
Why browsers behave while terminals betray you
Chromium reads the macOS or Windows system proxy table and applies it to each tab with minimal drama. Many CLI runtimes do not. Go’s default client honors HTTPS_PROXY only when the environment is clean and consistent; Node-based agents may spawn worker processes that drop inherited variables; Rust binaries compiled with different feature flags can bypass CONNECT tunnels unless you wrap them carefully. A curl run in one terminal window and Claude Code in another can therefore diverge even though both “use Clash.” The practical fix is not memorizing six export lines in every shell profile—it is elevating capture to the OS dataplane with TUN so the policy applies before userland squabbles over environment blocks.
TUN is not magic; it is disciplined interception. Packets that would have taken a lossy default route toward a saturated international peer instead land in Clash, where split routing decides whether they should ride a low-loss offshore node or remain DIRECT for domestic SaaS. That is the same architecture recommended for Discord voice and QUIC-heavy apps, except here the payload is HTTPS to Anthropic. Once TUN is stable, the only remaining arguments are about YAML, not about why one terminal session forgot its proxy variables yesterday.
Corporate laptops: TUN competes with other VPN kernel extensions. If IT mandates Always-On VPN, test in a lab machine first. You remain responsible for policy compliance—this article addresses transport, not employment agreements.
Make TUN the default plane for coding agents
Start by installing a maintained Meta-class GUI such as Clash Verge Rev, enable its service or helper components on Windows, approve the network extension on macOS, then flip TUN on with a stack you can explain—system when you want the host kernel to own the adapter, gvisor when you need user-space isolation from other security products. The detailed trade-offs live in our gvisor versus system stack guide; pick one, document it in your README, and stop rotating blindly whenever latency spikes.
After TUN lifts, validate capture with something dumber than AI: a plain curl -I https://api.anthropic.com from the same user session that launches Claude Code. If the handshake time collapses compared to the no-proxy baseline, you are on the right route. If it fails instantly, your subscription node may block UDP or mishandle TLS 1.3—fix the outbound before blaming the CLI. Remember that WSL2 guests do not automatically inherit Windows TUN; mirror the mixed-port strategy from our WSL2 Git and npm guide or run Clash inside Linux when your agent lives entirely in that VM.
Step-by-step: from blank profile to predictable Anthropic routing
Treat the following as a checklist you can paste into runbooks for teammates who “already had Clash working in Chrome.”
- Reproduce without Clash: note baseline latency and whether failures are connection timeouts versus HTTP errors. If both setups fail identically, fix ISP routing first.
- Enable TUN and disable conflicting VPNs temporarily: confirm the virtual interface comes up and Clash logs show inbound SYNs.
- Add Anthropic-oriented rules above catch-alls: minimally
DOMAIN-SUFFIX,anthropic.com,AI-OutboundandDOMAIN-SUFFIX,claude.ai,AI-Outbound, using your real proxy group label. - Reload the profile and test OAuth: watch SNIs during browser handoff; stray third-party domains should not accidentally MATCH to
DIRECTif your policy forbids it. - Align DNS: set
nameserver-policyfor critical suffixes if your upstream resolver wanders; extendfake-ip-filterwhen LAN or console hosts must bypass synthetic answers. - Stress the API: run a short completion or a long streaming job; compare retry counts before and after edits.
YAML you can defend in code review
Remote rule providers are convenient until they update on Tuesday and shuffle your ordering story. Keep a compact local block for AI vendors even if you trust curators—ten lines of explicit suffix rules beat an hour of guessing why Claude Code suddenly matches a Chinese CDN bucket. Illustrative lines:
# Local AI routing block — replace AI-Outbound with your group name
DOMAIN-SUFFIX,claude.ai,AI-Outbound
DOMAIN-SUFFIX,anthropic.com,AI-Outbound
# Optional tighter splits if you meter API differently from marketing sites:
# DOMAIN,api.anthropic.com,AI-API
# DOMAIN,console.anthropic.com,AI-Console
Place those lines below RFC1918 bypasses and above GEOIP,CN,DIRECT or broad MATCH entries. If you consume community lists, read the ACL4SSR versus Loyalsoldier comparison so you understand whether “AI” domains are truly included or merely rumored. After edits, use the Clash UI to preview the first matching rule for a test URL—if the answer surprises you, reorder locally before you blame Anthropic capacity.
Proxy groups: choose boring stability over leaderboard throughput
Speed-test screenshots rarely correlate with resilient streaming to LLM APIs. Lower packet loss and predictable NAT behavior matter more than shaving five milliseconds on a single ping. Configure url-test or fallback groups with timeouts that match how aggressively the Claude Code client retries, label servers by city honestly, and avoid constantly chasing “the fastest node” if that node resets tunnels during peak evening hours. Pair group tuning with endpoint tests that mirror reality—small HTTPS GET for health, then a multi-minute streamed completion—to catch middlebox kill behavior early.
DNS, FakeIP, and the illusion of random CLI failures
FakeIP is powerful because it lets Clash answer synthetic addresses for domains that should be policy-controlled, but it punishes sloppy fake-ip-filter lists. If your shell resolves console.anthropic.com through a public resolver while Clash assumes a different pathway, you can match the wrong outbound, see RST storms, or succeed once per boot until caches diverge. Read the deep dive in Meta core DNS leak prevention before you flip knobs randomly.
Operational habit: for every stubborn timeout, log hostname, resolver IP, and the first Clash policy attached to the SYN. When those three disagree, fix DNS before you RMA your subscription. The same discipline keeps MCP servers sane when they call remote models from editors that mix localhost and cloud traffic.
Sniffer optional: If HTTPS SNI alone is too coarse, Clash Meta’s Sniffer can recover domain names for stubborn flows—but enable it deliberately and audit privacy impact. Start without Sniffer when simple suffix rules already match your logs.
Verification rituals that survive midnight debugging
Checklists beat vibes. Reserve ten minutes after each profile change: reload Clash, open logs, run two curls from Terminal, launch Claude Code, and capture whether OAuth completes without a second browser refresh. If anything regresses, roll back the last YAML chunk rather than stacking speculative fixes. Long streaming jobs deserve their own pass—some ISPs only show packet loss after sixty seconds of upstream upload, which is exactly how code agents behave during big diffs.
- Log discipline: filter for
api.anthropic.comand your chosen outbound; spikes of SYN retransmits mean path, not prompts. - DNS cross-check: compare
digoutput with Clash DNS logging for the same label when FakeIP is enabled. - Rollback proof: disabling TUN should restore baseline routing without rebooting; if not, clean duplicate routes introduced by experiments.
FAQ
Why does Claude Code time out in the terminal when the Claude website works?
Browsers honor system proxy tables; many CLIs ignore them unless you export environment variables in every shell session. TUN captures both uniformly so split routing applies before subprocess quirks surface.
Is HTTP_PROXY enough instead of TUN?
It can be, until a worker process spawns without inherited variables or uses libraries that bypass classic CONNECT proxies. For agent-style tools that orchestrate many binaries, TUN is the lower-surprise default.
Which Anthropic domains should I add?
Start with suffix coverage for anthropic.com and claude.ai, then refine with explicit DOMAIN lines for API and console hosts if you need different outbound groups. Always confirm SNIs from logs—CDNs shift.
Can WSL2 break Claude Code even if Windows Clash works?
Yes. The Linux virtual NIC is separate. Bridge it using mixed ports or run Clash inside WSL with its own TUN instance so the namespace that hosts your repo is the namespace that enforces YAML.
Tradeoffs and honest limits
Routing offshore for research convenience may conflict with data residency policies; document what leaves your network and why. Aggressive DIRECT rules can speed local CDNs but strand AI traffic on congested peering during international incidents. Maintenance matters—budget quarterly YAML reviews alongside API key rotation so Claude Code stays boringly reliable instead of lottery reliable.
Clash cannot fix genuine upstream saturation, buggy client releases, or ISP bufferbloat. It can stop you from pinning long completions to paths your national carrier treats as scavenger class traffic, and it can eliminate the class of bugs where the browser tab works because it used TUN while the terminal did not.
Closing thoughts
Claude Code is an Anthropic product, but the failures that drive developers to forums are often ICMP-quiet TCP stories. Putting the CLI on the same Clash dataplane as the rest of the OS—especially via TUN—turns “mystery timeout” into a log line you can grep. Pair explicit suffix rules with honest DNS policy, test streaming workloads instead of one-shot pings, and keep local YAML blocks you can explain in a design doc.
Many all-in-one proxy tools either force everything through a single tunnel with no fine-grained split control or dump you into hand-edited fragments scattered across operating systems without a consistent UI. Clash keeps high-level policy in one Meta-compatible profile: TUN when you need it, rule-based split routing when you do not, and documentation-aligned knobs for DNS that reduce FakeIP whiplash. If you are still wireshark-ing every Claude Code release, download Clash and apply the steps above so terminal agents, browsers, and background jobs finally agree on how they reach Anthropic.