Claude Code in China: A 5-Minute Setup Guide

Claude Code in China: A 5-Minute Setup Guide

Author: CodeGateway team · Published: 2026-04-29 · Last updated: 2026-05-03 · Reading time: 10 min

Contents

• TL;DR — the short answer
• Why Claude Code is hard to use from inside China
• What CodeGateway is
• Performance and reliability
• 5-minute setup
• Your first session: from "explain this repo" to "refactor it"
• Comparison: VPN tunnel / community proxies / self-hosted / CodeGateway
• Pricing: tiered markup and the new-user starting credit
• Security: keys, data flow, audit trails
• FAQ
• References and external reading

TL;DR — the short answer

TL;DR: for developers in mainland China, the most stable way to run Anthropic Claude Code is to point it at CodeGateway. One curl sets up the environment, you'll be running Sonnet / Opus / Haiku from your terminal in 5 minutes, billed per token, and new sign-ups get a $2 starting credit.

This article walks the full setup, shares our measured numbers from inside the GFW, and compares CodeGateway with the obvious alternatives (VPN, community proxies, self-hosting).

Why Claude Code is hard to use from inside China

Claude Code is Anthropic's CLI coding agent, released in 2025. Unlike IDE-integrated tools (Cursor, GitHub Copilot), it runs straight in the terminal and can autonomously read and write multiple files, run commands, run tests, and inspect the output — exactly the kind of work that normally has you ping-ponging between editor and shell (refactors, cross-file edits, TDD).

From inside mainland China, you hit infrastructure-level problems before you can even use it:

• Anthropic's official endpoint (api.anthropic.com) is not reachable. The tool itself is fine — it's open source, installs cleanly. The endpoint it calls just isn't routable from CN networks.
• VPN tunnels are flaky in practice. A VPN works in dev, but the long-lived SSE streams Claude Code relies on get cut, the rate limits dance around, and the account-flagging risk over a month of usage is non-trivial.
• Community proxies are a mixed bag. API keys end up logged on someone else's box (privacy leak), the books are opaque, services come and go, billing models contradict each other (per-call vs per-byte).
• Compliance teams care about this. The intermediate hops have to be auditable. Anyone in finance, healthcare, or B2G has hard requirements here.

CodeGateway is built specifically to address those four points.

What CodeGateway is

CodeGateway is a stable proxy for the Anthropic Claude API, deployed on Cloudflare's global edge, fully wire-compatible with the Anthropic Messages API. On the Claude Code side, the only thing you change is to point ANTHROPIC_BASE_URL at the CodeGateway endpoint (https://api.codegateway.dev). Everything else — request shape, streaming, prompt caching — works exactly the same.

Core characteristics:

• Solid infrastructure: deployed on Cloudflare's global edge. China-mainland users land on the closest of HK / NRT / SIN. The underlying Anycast network has documented stability for these three corridors.
• Drop-in API compatibility: same messages endpoint, SSE streaming, prompt caching. No code changes inside Claude Code.
• Token-based billing: no monthly subscription, no minimum spend, balances never expire. Billed on the actual input/output tokens consumed, using the same token rules Anthropic publishes.
• Observable: the dashboard breaks each call down to token counts, cache hit/miss, latency, and cost — filterable by time range and API key.
• $2 starting credit: every new account gets $2 on signup. At the current 1.5x starter markup that's roughly 440K Sonnet 4.6 input tokens — enough to run a full mid-sized project setup test plus your first refactor.

Performance and reliability

Gateway-layer load test (measured)

In April 2026 we ran a 100-concurrent, 5-minute load test against the gateway layer — 1,406 total requests, steady-state. Headlines:

• Error rate: 0.00% — all 1,406 requests succeeded
• Gateway TTFB P50 ≈ 300 ms
• Gateway TTFB P95 ≈ 750 ms
• Proxy-layer overhead ≈ 100–200 ms
• 100-concurrent connection stability: no timeouts, no SSE stream drops

In practice that means the latency CodeGateway adds is a rounding error compared with the model's own generation time (typically 1–10 s depending on output length). Under moderate-to-high concurrency the gateway stays steady with zero error rate.

End-to-end latency from inside China (monitoring in progress)

[End-to-end latency data being collected] — we're running a 30-day end-to-end latency and connectivity sweep across major mainland cities (Beijing / Shanghai / Shenzhen / Guangzhou / Chengdu) on the major ISPs, weekdays and weekends. This section will be updated the moment data lands (target: end of May 2026).

Until those numbers ship, here's what we can say from infrastructure first principles. CodeGateway sits on Cloudflare's global edge; Anycast routes to the nearest PoP. Mainland-China users typically land at HK, NRT, or SIN — physical distance 1500–3000 km, speed-of-light round trip under 30 ms. Observable latency is dominated by cross-border egress bandwidth and ISP routing quality, not the proxy itself.

Cloudflare's public global network quality data puts the China-to-Hong-Kong corridor at P50 50–100 ms on weekdays, P99 200–350 ms. For Claude Code that translates roughly to:

• Non-streaming calls (e.g. /init generating CLAUDE.md): 100–200 ms round trip — indistinguishable from hitting the official API.
• Streaming calls (long sessions): TTFB of 300–500 ms, then tokens flow. Feels equivalent to the official API in practice, since inter-token latency from the model itself is already 30–80 ms.

Once the 30-day sweep wraps we'll publish per-city, per-time-of-day, per-ISP P50/P95/P99 plus 7×24 connectivity rate.

5-minute setup

Step 1 — Create an account

Open codegateway.dev and sign up — email or GitHub OAuth. After signup you land on the dashboard with a $2 balance ready to spend ($2.00).

Step 2 — Create an API key

Dashboard → API Keys → Create key. Generated keys start with sk-cg- followed by a 32-character body and checksum.

Important: the full key is shown once, at creation time. Closing the page leaves only the masked first-4 / last-4 visible. Save it to a password manager (1Password, Bitwarden) or your project's .env right away, and make sure .env is in .gitignore. Full guidance in the API Key Security Best Practices doc.

Step 3 — One-line install

We ship an install script that detects and installs the Claude Code CLI, writes ~/.claude/settings.json, and appends the env vars to your shell profile.

macOS / Linux (bash or zsh):

curl -s https://codegateway.dev/setup.sh | bash -s -- --key sk-cg-YOUR_KEY

Windows (PowerShell, run as Administrator):

& { $key='sk-cg-YOUR_KEY'; iwr -useb https://codegateway.dev/setup.ps1 | iex }

What the script does:

• Checks for Node.js (≥ 18); prompts you if it's missing
• Installs the CLI via npm i -g @anthropic-ai/claude-code
• Writes ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev",
    "ANTHROPIC_AUTH_TOKEN": "sk-cg-YOUR_KEY"
  }
}

• Appends the same env vars to ~/.bashrc / ~/.zshrc / $PROFILE (the original is backed up as .bak)
• Prints a verification command to run

If you'd rather not run the script (compliance, locked-down corp machines), the manual setup is documented in the Claude Code 5-minute setup reference doc.

Step 4 — Verify

claude --version    # version output means the CLI is installed
cd /path/to/your/project
claude              # opens the REPL

The REPL shows a > prompt when configuration is good. On first launch Claude Code reads the CLAUDE.md in your project root (if present) for context.

Your first session: from "explain this repo" to "refactor it"

Most developers' first instinct with Claude Code is to use it like ChatGPT or Cursor — "write me a function", copy, paste. That's a tiny slice of what it does. The fundamental difference between Claude Code and an IDE-embedded assistant is that it can drive your filesystem and run commands.

From any Git project, run claude and try a few prompts:

Walk me through this project — directory structure and main modules.

It will run ls -R, read README.md / package.json / tsconfig.json and any other anchor files, then summarise the structure.

Explain what src/lib/auth.ts does, and which call sites depend on it.

It reads auth.ts end to end, greps for callers, and replies with the call graph included.

Add a unit test for src/api/login.ts using vitest. Cover happy path + error paths.

It scans the surrounding files to understand dependencies, writes the test, runs `npm test` or `pnpm test` to verify, self-corrects on failure, and re-runs until everything's green — without you bouncing between terminal and editor. That's what "agent" actually means here.

More advanced patterns (slash commands, Plan mode, Hooks automation) are covered in the Claude Code Practical Guide.

Comparison: VPN tunnel / community proxies / self-hosted / CodeGateway

How CodeGateway stacks up against the alternatives developers usually try:

The shape of each option: VPN tunnels work around the routing block; community proxies offload infra cost onto someone you don't know; self-hosting trades engineering time for control; CodeGateway offers the engineered middle path — you skip the ops bill, you keep observability, audit logs, and per-token billing.

Side-by-side feature comparison and selection guidance: Claude Code vs Cursor vs GitHub Copilot.

Pricing: tiered markup and the new-user starting credit

CodeGateway prices each request at Anthropic's official rate × a tiered markup keyed off your rolling 90-day spend:

• Tier 1: $0–$10 in the last 90 days, markup 1.5× — about 220K Sonnet 4.6 input tokens per $1
• Tier 2: $10–$50, markup 1.4× — about 238K tokens per $1
• Tier 3: $50–$200, markup 1.3× — about 256K tokens per $1
• Tier 4: $200–$500, markup 1.25× — about 267K tokens per $1
• Tier 5: $500+, markup 1.2× (hard floor — long-term stable) — about 278K tokens per $1

Why a markup at all: CodeGateway pays for Cloudflare infrastructure, cross-border egress, and the monitoring stack that turns the official API into something usable from China. The 1.2× hard floor (20% above list) is the minimum margin we need to keep the service running long-term.

Starting credit: new accounts get $2 with no top-up required. At 1.5× that's roughly 440K Sonnet 4.6 input tokens, enough to:

• Run /init once across a 50K-LOC mid-sized project (generates CLAUDE.md)
• Have Claude Code refactor 10–20 files (reads, edits, runs tests)
• Compare Sonnet vs Haiku vs Opus on a real task

Full tier rules and the dashboard view: Tiered Markups Explained. Top-up flow, refunds, invoices: Top-up & Billing Guide.

Security: keys, data flow, audit trails

The compliance-sensitive shops (finance, healthcare, B2G) care about this section in particular.

• API key storage: we don't store the plaintext API key — only a SHA-256 hash. A database compromise can't be reversed back into a usable key. The sk-cg-...{4-char-suffix} you see in the dashboard is a display ID derived from the hash, not the key itself.
• Request path: client → Cloudflare edge (HTTPS) → Anthropic official API (HTTPS). TLS 1.3 end to end. Prompt content is never persisted on CodeGateway — we record metadata only: timestamp, token counts, model, latency, cost. The prompt text is handled by Anthropic per their published data-usage policy, identical to hitting the official API directly.
• Audit logs: the dashboard surfaces per-call metadata — call time, API key ID, model, input/output tokens, cache hits, latency, cost. Filterable by time range, model, and key.
• Third-party dependencies: the infrastructure stack is Cloudflare (edge + infra) + Anthropic (upstream API) + Stripe (payments) — all SOC 2 / ISO 27001 certified. No mainland-China cloud-vendor dependencies.

For specific compliance questions (data residency, contractual SLAs, paper trail), reach us through the dashboard's feedback widget.

FAQ

Q: How is CodeGateway different from hitting the Anthropic API directly? Where does my data go?

A: Usage-wise it's identical — point ANTHROPIC_BASE_URL at https://api.codegateway.dev and request/response shapes match Anthropic's verbatim. Data path: your client → Cloudflare edge → Anthropic official API. CodeGateway doesn't store prompt content, only metadata (token counts, cost, latency).

Q: I already have an Anthropic API key. Can I use it on CodeGateway?

A: No. CodeGateway issues its own keys (sk-cg- prefix, bound to your CodeGateway balance). Your Anthropic key holds balance with Anthropic — those are two separate billing systems.

Q: Do balances expire? What if I top up and don't use it all?

A: Balances don't expire. Unused self-funded balance can be refunded any time — see the Refund Policy for the details.

Q: Is streaming (Server-Sent Events) supported?

A: Fully. Claude Code and every official SDK default to streaming; CodeGateway proxies the SSE stream at the Cloudflare edge with a 15-second keep-alive heartbeat to prevent intermediate timeouts.

Q: Does prompt caching work?

A: Fully. Claude Sonnet/Opus prompt caching is billed at Anthropic's rules: cache write at 1.25× normal, cache hit at 0.1× normal. With a sizeable system prompt this routinely saves 80%+. See Anthropic's Prompt Caching docs.

Q: I'm getting 5xx — is it CodeGateway's problem?

A: 5xx is almost always Anthropic's upstream being briefly unavailable; CodeGateway transparently passes the error through. Exponential-backoff retry. If you're seeing 10+ minutes of continuous 5xx and Anthropic Status reports green, ping us — full error-code playbook in the Error Troubleshooting Guide.

Q: My corporate network can't reach CodeGateway — what's going on?

A: Common causes: 1) the corporate proxy is blocking *.codegateway.dev — needs allow-listing; 2) the network kills long-lived SSE connections, breaking streaming; 3) corporate TLS interception. IT can usually unblock these — our domain is clean (no DNS-blocklist entries).

Q: Can my whole team share one CodeGateway account?

A: Yes — one account can hold many keys, each labelled per use case (dev, prod, tester). The dashboard breaks usage down per key. Per-key permission scoping (so a developer key sees its own bill instead of the full account's) is on the roadmap; if you need it, file via the dashboard feedback widget.

References and external reading

Internal deep-dives

• Claude Code 5-minute setup reference — manual config, PowerShell troubleshooting
• Claude Code Practical Guide — slash commands, CLAUDE.md project memory, Plan mode
• Claude Code vs Cursor vs Copilot — the three coding tools in depth
• Tiered Markups Explained — 90-day rolling spend, five tiers, top-up lock-in
• Top-up & Billing Guide — Stripe payments, CNY conversion, refunds, invoices
• Error Troubleshooting Guide — 401 / 429 / 500 self-service playbook

External authoritative sources

• Anthropic Claude Code official docs — what the tool does and best practices
• Anthropic Messages API reference — protocol-level details
• Anthropic Prompt Caching docs — caching mechanism and billing rules
• Cloudflare Radar network quality — real-time CN-to-edge latency monitoring