Claude Code Getting Started Guide: Complete Installation and Configuration Walkthrough

Introduction

Claude Code, the command-line AI coding tool from Anthropic, is rapidly becoming a go-to productivity tool for developers. Anthropic is an AI safety company founded by former core members of OpenAI, known for its Constitutional AI methodology — a training approach that constrains model self-evaluation through a predefined set of "constitutional principles." Unlike RLHF, which relies purely on human feedback, Constitutional AI has the model critique and revise its outputs against a principle set during training, improving interpretability and safety boundary control while reducing annotation costs. The Claude model family consistently achieves top scores on code generation benchmarks like SWE-bench — an authoritative benchmark that evaluates an AI's ability to resolve real GitHub issues, comprising hundreds of actual bug-fix tasks from popular open-source projects. Models must automatically generate code patches that pass test suites, making it the industry's most realistic measure of software engineering capability. Unlike IDE plugin-based tools such as GitHub Copilot and Cursor, Claude Code uses a command-line interaction model that can directly manipulate the file system, execute shell commands, and invoke Git tools, giving it end-to-end capabilities for code generation, debugging, refactoring, and project management.

For newcomers, however, the path from environment setup to API configuration is often riddled with pitfalls. This guide distills systematic, hands-on experience into a complete walkthrough of Claude Code's installation and configuration process, helping you get your first environment up and running as quickly as possible.

The Complete Learning Path: Six Core Modules at a Glance

Before diving in, let's take a look at the full learning path. This curriculum is organized around practical, case-based examples and is divided into six core modules:

1. Quick Start & Configuration: Install Claude Code from scratch, complete basic setup, and run your first commands — this is the starting point for everything else.
2. Core Modes: Switch between working modes based on context to maximize efficiency.
3. CLAUDE.md Global Memory: The core mechanism that lets Claude Code maintain continuous awareness of your project context. Because large language models are stateless by nature (each API call is independent with no retained history), Claude Code simulates "memory" by automatically reading the CLAUDE.md files in the project root and user home directory at the start of each session and injecting their contents into the system prompt. These files typically contain information about the tech stack, coding style guidelines, directory structure conventions, and other background context — significantly reducing repetitive token consumption and improving the consistency and accuracy of Claude's output.
4. Session Management: Keep tasks from spiraling out of control and maintain an efficient execution flow.
5. Resource Monitoring & Batch Tasks: Manage your pace, conserve tokens, and handle long-running scenarios. It's worth noting that Claude Code can consume tens of thousands — or even hundreds of thousands — of tokens in a single session when working with large codebases (since file contents must be injected into the context window), making cost control an important topic for advanced usage.
6. Common Pitfalls & Advanced Techniques: Help Claude understand your task intent more precisely.

This article focuses on the first module — installation and configuration — which is where beginners most commonly get stuck.

Step 1: Set Up the Node.js Runtime Environment

Claude Code runs on Node.js, so you'll need to set up a Node environment first.

Version recommendation: The official tool supports Linux, Mac, and Windows. It's recommended to install the LTS (Long-Term Support) version for better stability and ongoing official support.

Why choose LTS? Node.js follows an even/odd versioning strategy: even-numbered versions (e.g., 18, 20, 22) are LTS releases with 30 months of official security patches and maintenance; odd-numbered versions are only maintained for 6 months and are primarily for validating new features. Claude Code requires Node 20+ because it relies heavily on ES2022+ native features: top-level await allows using await directly at the module level without wrapping it in an async function, greatly simplifying async initialization logic; the Structured Clone API provides efficient deep-copy capabilities supporting a wider range of data types than JSON serialization; and the built-in Fetch API (stable since Node 18) eliminates the need for third-party networking libraries. Together, these three features underpin Claude Code's modern async architecture. If you need to manage different Node versions across multiple projects on the same machine, the nvm (Node Version Manager) tool is recommended for flexible version switching.

Since Claude Code is a relatively new tool, use Node version 20 or higher (the demo environment uses version 22.11).

Verify the installation: After installation, run the following two commands in your terminal. If you see version numbers, your Node environment is ready:

node -v
npm -v

Windows users have two installation options: the MSI installer automatically configures environment variables (the easier option), while the Zip package requires manual environment variable configuration. The MSI installer is recommended for a smoother experience. Mac users should download the PKG package; Linux users should download the corresponding archive.

Step 2: Install Git to Get a Bash Terminal

This step is easy for beginners to overlook, but it's actually critical. Claude Code relies on a Bash command-line terminal when executing tasks, and that Bash environment is provided by Git.

Why does Windows need Git Bash? Windows natively uses CMD and PowerShell, which differ fundamentally from the POSIX shell used on Linux/macOS — path separators, pipe behavior, and environment variable syntax all differ. Git for Windows bundles a MinGW (Minimalist GNU for Windows) environment, which compiles the GNU toolchain as native Windows PE executables rather than relying on a virtualization layer, resulting in faster startup and lower resource usage. This lets Windows users run bash.exe along with lightweight GNU tools like grep, awk, and sed, enabling Shell scripts and POSIX commands. Since Claude Code calls Bash scripts when running automated tasks, bash.exe is a fundamental requirement. If you need fuller Linux compatibility, WSL2 (Windows Subsystem for Linux 2) provides a real Linux kernel environment, but it has a higher setup cost. For beginners, Git Bash is the lighter-weight starting point.

After installation, run the verification command:

git version

If you see a version number and confirm that bash.exe exists on your system, your Git environment is working correctly. There are no strict version requirements for Git — just pick a recent version.

Important reminder: You'll also need to configure an environment variable pointing to the Git Bash terminal for Claude Code later on. It's a good idea to set that up now to avoid errors when Claude can't find Bash during task execution.

Step 3: Install Claude Code via npm

With the environment ready, you can now install Claude Code. It's an npm-based command-line tool and is small enough that the download completes quickly.

Speed tip: If your internet connection is slow, switching npm to a domestic mirror will noticeably improve download speeds. By default, npm connects to registry.npmjs.org, which has high latency when accessed from within China. Common domestic mirrors include the Taobao NPM mirror (npmmirror.com) and the Tencent Cloud mirror. You can permanently switch with the following command:

npm config set registry https://registry.npmmirror.com

You can also use nrm (npm registry manager) for more convenient management of multiple registry sources. Install it with npm install -g nrm, then run nrm use taobao to switch to the Taobao mirror. The nrm test command measures response latency for each mirror, helping you pick the fastest one. Switching the registry only affects the download source — it has no impact on package functionality. Users with a global proxy configured can skip this step.

After installation, run:

claude --version

If you see a version number (e.g., 1.0.83), the installation was successful. You can also run claude --help to view the help documentation and learn about the available command options.

Step 4: Solve Network Proxy Issues (A Common Beginner Pitfall)

This is the most frequent roadblock for beginners. Without a global proxy or an overseas server, running claude will likely trigger a region restriction error (unsupported region).

Why does region restriction occur? Anthropic's API service is deployed on AWS cloud infrastructure and enforces access restrictions for certain regions based on IP geolocation, which is related to regulatory compliance and service agreements. When Claude Code detects that the request's source IP is in an unsupported region, it returns an unsupported_region error code and terminates the session.

Solution: Create a proxy configuration in your current project directory:

1. Create a .claude folder
2. Inside it, create a settings.json file
3. Enter the HTTP/HTTPS proxy address pointing to your proxy service

Configuring a proxy in settings.json is essentially equivalent to setting the HTTP_PROXY and HTTPS_PROXY environment variables — the standard Unix/Linux environment variable convention. Node.js's underlying network libraries (such as undici and http.request) will automatically read these variables and route requests to the specified proxy server. The proxy server then forwards the local request to a node located in a supported region, which in turn forwards it to the Anthropic API, thereby bypassing the regional IP block.

It's also worth noting that Claude Code's streaming output relies on SSE (Server-Sent Events) long-connection technology — an HTTP-based server push protocol where the server continuously streams text data to the client, allowing model-generated content to be displayed word by word in real time rather than waiting for the entire response to complete. SSE connections are inherently long-lived; if the proxy drops mid-stream, the entire response fails. SOCKS5 proxies operate at the session layer of the OSI model, support both TCP/UDP protocol forwarding, and maintain long connections more stably than application-layer proxies that only support HTTP/HTTPS. For this reason, in some network environments, using a SOCKS5 proxy for Claude Code's streaming output can provide a better experience.

Note that the region error doesn't always appear — domestic network conditions in China are unstable and can vary. But once triggered, the error can persist in a stuck state, so configuring a proxy in advance is a worthwhile precaution. Users whose networks can already access the service stably can skip this step.

Step 5: Configure Your API Key and Authorize Login

The final step is configuring your API key. There are two main approaches:

Option 1: Use the Official Claude API

Visit the Claude website to register an account and generate an API key. The official service offers two billing models:

• Subscription: A fixed monthly fee, ideal for heavy or frequent usage with fewer restrictions.
• Pay-as-you-go: Pay only for what you use, suitable for light users with infrequent API calls.

Token billing explained: The Claude API uses token-based metered billing. Tokens are the basic units of text processing in large language models — one Chinese character typically corresponds to 1.5–2 tokens, while one English token is roughly 4 characters. Claude 3.5 Sonnet is officially priced at approximately $3 per million input tokens and $15 per million output tokens. Since Claude Code can consume tens of thousands to hundreds of thousands of tokens per session when working with large codebases, it's strongly recommended to set a Hard Limit and a Soft Limit (alert threshold) in the Anthropic console before you begin. When triggered, the system will send an email alert or directly suspend API access to prevent unexpected overcharges. In addition, using a .claudeignore file (with syntax similar to .gitignore) to explicitly exclude directories like node_modules, dist, and *.lock files can reduce per-session token consumption by 30%–70% — one of the most direct ways to control costs.

Option 2: Use a Third-Party Proxy Service

If you'd prefer not to use an official key directly, you can opt for a domestic third-party proxy service. These platforms use their own API keys to proxy calls to the official interface. The advantages include solving network access issues, potentially lower pricing, and sometimes free trial credits.

Note: When using a third-party service, in addition to configuring your API Key, you'll also need to set an API Base URL. Refer to the onboarding documentation for the specific platform. This extra step is not required when using the official service.

Login and Authorization Flow

Once your network and key are ready, run claude to enter the setup wizard:

1. Choose a UI theme: Light or dark mode — pick your preference.
2. Authorize login: You'll be redirected to the Claude website's authorization page. After authorizing, an API token is automatically retrieved and written to the local configuration file .claude.json.
3. Key selection: If you want to use your own environment variable key, manually select "Use the key from the current environment variable" in the options (default is No); otherwise, the token automatically retrieved from the official site will be used.

Upon successful authorization, you'll see a success message and the key will be automatically written to the configuration file in your user directory. Run claude and you'll see the Welcome to Claude Code greeting — the entire installation and configuration process is now complete.

Summary

While Claude Code's initial setup involves several steps, the core logic is straightforward: Node environment → Git Bash → npm install → network proxy → API authorization. The two areas most likely to cause problems are the network proxy configuration and the API billing setup.

With the complete workflow covered in this guide, you've cleared the first hurdle to using Claude Code. The real productivity gains from this AI coding tool come from what's next: mastering core mode switching, the CLAUDE.md memory mechanism, session management, and other advanced features.