Install Claude Code on Windows: PowerShell and Gateway Setup

Claude Code runs fine on Windows, but most guides assume macOS or Linux, so Windows users end up guessing at environment variables and PATH issues. This guide covers a clean install on native Windows, the PowerShell configuration to route Claude Code through a gateway endpoint, the WSL alternative, and the errors that account for nearly every failed first run.

Native Windows or WSL?

Both work. Choose based on where your projects live:

• Native Windows (PowerShell): your repos are on C: and you use Windows tooling. Simplest if you do not already use WSL.
• WSL: your repos live inside a Linux filesystem, or your team's scripts assume bash. Claude Code behaves exactly as on Linux.

Do not mix them: an install inside WSL is invisible to PowerShell and vice versa. Pick one and configure it fully.

Install on Native Windows

You need Node.js 18 or newer. Check first, then install Claude Code globally:

node --version
npm install -g @anthropic-ai/claude-code
claude --version

If claude --version prints a version number, the install is done. If PowerShell says the command is not recognized, close and reopen the terminal first — npm updates PATH for new sessions, not existing ones.

Point Claude Code at the Gateway

Claude Code reads two environment variables: the Anthropic base URL and an auth token. With Zivv the base URL is the root domain — no /v1 suffix, which is the opposite of OpenAI-style clients and a frequent copy-paste mistake.

For the current PowerShell session:

$env:ANTHROPIC_BASE_URL = "https://zivv.pro"
$env:ANTHROPIC_AUTH_TOKEN = "sk-your-key-here"
claude

Get the sk- key from the API Keys page in the console — register if you have not. If Claude Code starts and answers a prompt, the routing works.

Make It Permanent

Session variables vanish when the terminal closes. Persist them at the user level:

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://zivv.pro", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-your-key-here", "User")

Two things people miss:

1. Persistent variables apply to new terminals only. Every already-open PowerShell window keeps its old environment — close them all.
2. If a variable is set both persistently and in your PowerShell profile, the profile wins for that session. Keep the configuration in one place.

To confirm what Claude Code will actually see, open a fresh terminal and run echo $env:ANTHROPIC_BASE_URL.

WSL Notes

Inside WSL, treat it as a Linux install. Install Node via your distro's method, then:

npm install -g @anthropic-ai/claude-code
echo 'export ANTHROPIC_BASE_URL=https://zivv.pro' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-your-key-here' >> ~/.bashrc
source ~/.bashrc
claude

Common WSL-specific traps:

• Windows environment variables do not automatically flow into WSL. Set them in ~/.bashrc (or ~/.zshrc), not in Windows.
• If which npm prints a path starting with /mnt/c/, you are calling the Windows npm from inside WSL. Install Node inside the distro instead.
• Keep the project inside the WSL filesystem (for example under ~/projects) — file operations across /mnt/c are slow and occasionally flaky.

Common Errors

Each response code maps to a specific cause — the error reference lists them, and the Claude Code guide keeps the canonical setup steps current.

First Run Checklist

Before starting real work, run one throwaway session and confirm the whole chain:

1. Open a fresh terminal (so persistent variables are loaded)
2. Run claude inside a small project folder
3. Ask it to read a file and summarize it — this proves file access and API routing in one step
4. Check the console's usage page: the request should appear against your key within moments

If usage shows up, the configuration is done and everything after this is normal Claude Code work. If Claude Code responded but no usage appears, you are almost certainly still authenticated against a different endpoint in that terminal — re-check the environment variables there.

Which Model Group to Use

Through the gateway, Claude Code can run against pay-as-you-go Claude models such as claude-sonnet-5 or the Opus tier for harder work. Heavy users should look at the Claude MAX group, which serves Claude Code over the native Anthropic protocol from a subscription account pool — no rate-limit feel during long sessions. The trade-offs between subscription and API billing are covered in the subscription vs API comparison.

FAQ

Do I need both `ANTHROPIC_AUTH_TOKEN` and an Anthropic account login? No. With the base URL and token set, Claude Code authenticates against the gateway and no Anthropic login is needed.

Can I keep an official Anthropic setup and a gateway setup side by side? Yes — use session-level $env: variables to override per terminal, and leave the persistent ones as your default.

Does the same key work in Cursor and Cline too? Yes, one key covers all clients; only the base URL format differs per protocol. See the vibe coding page for per-client settings.

PowerShell blocks npm scripts with an execution policy error. Is that Claude Code's fault? No, it is a PowerShell policy on .ps1 shims. Run npm from a terminal where your organization's policy allows it, or use npm.cmd.

Wrap-Up

The whole setup is one install command and two environment variables — the only Windows-specific work is persisting them correctly and remembering that new values need new terminals. Create a key, set the two variables, and Claude Code on Windows behaves exactly like it does everywhere else. Get a key here.