How to Configure Claude Code on Windows to Use a Compatible Model API
Learn how to install Claude Code on Windows, configure a compatible model endpoint with PowerShell environment variables, verify the connection, and troubleshoot common setup issues. The guide also covers API key handling and security considerations.
1. Understand the relationship between the client and the model service
A coding assistant has two parts. The client runs locally, where it reads project files, displays the interface, and invokes tools. A remote large language model service generates the code. The client sends requests over the network, so switching model services usually requires changing only the request endpoint and access key—not reinstalling the client.
Some model providers offer endpoints compatible with the Anthropic API format. If the client supports setting an endpoint through environment variables, you can point it to one of these endpoints. Compatibility and supported features depend on the provider and the client version, so check their current documentation.
2. Prerequisites
Before you begin, confirm that:
- Node.js is installed. The LTS release is recommended; check the client’s official documentation for the exact version requirement. Node.js 18 or later is generally required.
- Your network can reach the npm registry and the provider’s API endpoint.
- You have created a dedicated API key for this machine in the provider’s console. A separate key can be revoked independently if it is exposed.
- Your user account can modify its own environment variables. Administrator privileges are not required.
In PowerShell, check that Node.js and npm are available:
node -vnpm -v
If both commands return version numbers, the environment is ready. If either command is not recognized, install Node.js and reopen the terminal.
3. Allow the current user to run local scripts
Windows’ default script execution policy may prevent PowerShell profile files from loading, which can affect the steps below. Run:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
This setting applies only to the current user. It allows local scripts to run while continuing to block unsigned scripts downloaded from the internet.
4. Install the command-line coding assistant
Install the client:
npm install -g @anthropic-ai/claude-code
After installation, check npm’s global installation directory and locate the claude command:
npm prefix -gwhere.exe claude
npm prefix -g prints the global installation directory, which is typically %APPDATA%\npm. If where.exe claude returns no result, that directory may not be in PATH; follow the next section to fix it.
5. Update the user PATH
PATH is the list of directories Windows searches for executable files. If npm’s global directory is not in PATH, the terminal cannot find the claude command.
Back up the user-level PATH before editing it. The script below creates a backup and appends only npm’s global directory to the user-level PATH; it does not copy the system-level PATH into the user-level setting.
$npmDir = (npm prefix -g).Trim()$userPath = [Environment]::GetEnvironmentVariable("Path", "User")# Back up the original user PATH$backup = Join-Path $env:USERPROFILE "user_path_backup.txt"$userPath | Out-File -FilePath $backup -Encoding utf8# Append the directory only if it is not already presentif ($userPath -notlike "*$npmDir*") {[Environment]::SetEnvironmentVariable("Path", "$userPath;$npmDir", "User")Write-Output "Added the npm global directory to the user PATH"} else {Write-Output "The npm global directory is already in the user PATH"}
Close and reopen the terminal, then run where.exe claude to confirm that Windows can find the command. If other programs stop working after the change, use user_path_backup.txt to restore the previous user-level PATH. You can also inspect and edit it in Windows’ environment variables settings.
6. Configure the model endpoint
1. Save the API key
Do not put the key directly in the configuration file. Instead, save it as a user environment variable and have the profile reference it. Replace the placeholder with your actual key:
[Environment]::SetEnvironmentVariable("CODING_ASSISTANT_KEY", "your_actual_key", "User")
On a shared device, avoid this approach and use Windows Credential Manager or another secret-management tool.
2. Create and edit the PowerShell profile
PowerShell loads the file specified by $PROFILE when it starts. Create the file if it does not exist, then open it:
if (!(Test-Path $PROFILE)) { New-Item -Type File -Path $PROFILE -Force }notepad $PROFILE
Add the following lines in Notepad, replacing the placeholders in angle brackets with the values provided in your service provider’s documentation:
# ========== Coding assistant model configuration ==========$env:ANTHROPIC_BASE_URL = "<compatible endpoint URL from the provider documentation>"$env:ANTHROPIC_AUTH_TOKEN = $env:CODING_ASSISTANT_KEY$env:ANTHROPIC_MODEL = "<model name from the provider documentation>"# ==========================================================
The settings are used as follows:
ANTHROPIC_BASE_URL: The provider’s compatible endpoint. Copy the value from its documentation; do not guess it.ANTHROPIC_AUTH_TOKEN: The access key, referenced here through the environment variable you set earlier.ANTHROPIC_MODEL: The default model name. It must match the name listed by the provider.
If your client version supports a setting for an auxiliary lightweight model, such as ANTHROPIC_SMALL_FAST_MODEL, you can add it according to the documentation. Variable names may vary between versions, so consult the current client documentation rather than relying on memory.
Save and close the file, then reopen the terminal to load the settings. These variables will be loaded automatically in future terminal sessions. If you later change PATH, the execution policy, or the profile, repeat the relevant checks from Sections 4 through 6.
7. Verify the configuration
Check the setup in this order:
- Run
claudein the terminal to start the client. - In the interactive interface, enter
/modeland confirm that the displayed model name matches your configuration. - You can ask the model to identify itself as an additional check, but its response is not definitive. Use the
/modeloutput and the provider console’s request records as your primary sources. - Send a simple coding request, then check the provider console for a corresponding request record.
If /model shows the wrong model or the provider console shows no request, the request may not be reaching the configured endpoint. Review the settings in Section 6.
8. Common issues
| Symptom | Possible cause | What to do |
|---|---|---|
The claude command is not recognized |
The npm global directory is not in the user PATH |
Run npm prefix -g to check the directory, update PATH as described in Section 5, and reopen the terminal |
| Variables must be set again every time the terminal opens | The profile was not updated or did not load | Run echo $PROFILE to check the profile path, review the execution policy, and reopen the terminal |
| Authentication fails | The key is missing, expired, or a placeholder was not replaced | Check the value of CODING_ASSISTANT_KEY and confirm the key’s status in the provider console |
| The model cannot be found | The model name is incorrect or your account does not have access to it | Compare ANTHROPIC_MODEL with the provider’s model list |
| Requests time out or the connection fails | The network cannot reach the endpoint | Run Test-NetConnection -ComputerName <hostname> -Port 443 to check connectivity, and adjust the network if needed |
| Some features do not work | The provider’s API does not implement all of the client’s capabilities | Check the provider documentation for supported features and, if necessary, choose another model or provider |
9. Compliance and security
- Review Anthropic’s terms of service and API terms, as well as those of your chosen provider, to confirm that your intended use and location are permitted.
- Never put a real key in source code, scripts, or documentation, and do not commit configuration files containing keys to a repository or share them with others.
- If a key may have been exposed, revoke it immediately in the provider console and generate a replacement.
- Do not send personal information, unreleased sensitive code, or regulated data to a third-party model service unless you have verified the provider’s data-handling practices.
