Claude Code for Beginners: A Complete Hands-On Guide to Installation and Configuration

Why Claude Code Is Worth Learning From Scratch

Claude Code is a command-line AI programming tool released by Anthropic, and it's quickly becoming a productivity powerhouse for a growing number of developers. Unlike traditional code-completion plugins, it's an intelligent terminal assistant that understands project context and can autonomously carry out tasks. Based on a beginner-friendly hands-on tutorial, this article walks through the complete configuration process for Claude Code—from setting up your environment to a successful login—helping new readers sidestep common pitfalls in one go.

The full learning path is organized into six modules: quick start and configuration, core mode switching, CLAUDE.md global memory, session management, resource monitoring and batch tasks, and finally common pitfalls with advanced tips. This article focuses on the first and most critical module—installation and configuration—because without a properly set up environment, none of the later hands-on work is possible.

Step 1: Set Up the Node.js Runtime Environment

Claude Code is a command-line tool that runs on Node.js, so the very first thing to do is make sure a suitable version of Node.js is installed locally. Here are the specific recommendations:

• Prefer the LTS (Long-Term Support) version, which offers better stability and receives ongoing official maintenance;
• Use at least version 20 or higher, because Claude Code is a new tool and older versions are prone to compatibility issues;
• The tutorial author personally uses version 22.11, which you can use as a reference.

Linux, macOS, and Windows are all supported. After installation, run the two commands node -v and npm -v to verify—if you see the version numbers printed correctly, your Node environment is ready.

Windows users have two installation options: one is to download the MSI installer, which automatically configures environment variables and is simpler to operate; the other is to download the ZIP package, which requires manual configuration of environment variables and offers more flexibility. macOS users should download the PKG or GZ package, while Linux users should choose the tar.gz package.

Step 2: Install Git and the Bash Terminal

This step is easy to overlook, but it's crucial. When Claude Code executes tasks, it needs to invoke the Bash command-line terminal, and on Windows, that Bash environment is provided by the Git Bash that comes bundled with Git.

After installing Git, run git version to verify (there are no special version requirements—just install a recent version). The core purpose of installing Git is to obtain the bash.exe executable located in its installation directory—it essentially simulates a Linux-like mini terminal on Windows, supporting commands like pwd.

If you don't configure Git Bash's environment variables, you'll encounter errors later when you have Claude perform project operations. Therefore, it's recommended to set this up at the very beginning to avoid repeated pitfalls.

Step 3: Install Claude Code via npm

Once your environment is ready, you can officially install the Claude Code itself. When installing via npm, be aware of platform differences:

• Linux/macOS: You need to add sudo when running the install command;
• Windows: Run it directly, no sudo needed.

If your network is slow, it's recommended to configure a domestic npm mirror registry, since the default uses an overseas mirror that may affect download speed. If you already have a VPN setup, whether or not you configure a mirror makes little difference—this command-line tool is small in size and downloads quickly.

After installation, run claude --version to check the version number; seeing the version number means the installation was successful. At this point, you can also type claude --help to view the complete help documentation and command parameter descriptions.

Step 4: Configure a Network Proxy (Essential for Users in Mainland China)

This is the pitfall users in mainland China most commonly encounter. Due to network restrictions, running the claude command directly is very likely to trigger an "unsupported region" error. The solution is to create a configuration file in the project root directory:

1. Create a new .claude folder in the current project;
2. Create a settings.json file inside it;
3. Write in the proxy addresses for HTTP and HTTPS requests, pointing to your VPN proxy service.

Note in particular that this error is inconsistent—sometimes it triggers, sometimes it doesn't. But once the region restriction is triggered, it often keeps throwing errors. If your command-line window doesn't have a global proxy set up, the safest approach is to configure this settings.json in your project ahead of time. If you've already set up a global proxy on an overseas server or locally, you can skip this step.

Step 5: Configure the API Key and Account Authorization

After the network configuration is complete, you'll move on to the most critical authorization step. Claude Code offers two main payment methods:

• Subscription: A fixed monthly fee, suitable for heavy users with large call volumes and frequent usage, with fewer restrictions;
• API Key pay-as-you-go: You pay for exactly what you use, suitable for light users who don't make many calls.

In addition, you can also opt for third-party proxy services (relay services). These services set up their own API Keys and proxy calls to the official interface, potentially offering better prices, and some even provide credits for free trials. Note that when using a third-party service, in addition to configuring the API Key, you must also additionally configure the API base URL (the third-party service's interface address)—just follow the corresponding provider's documentation. When using the official service, there's no need to configure a base URL.

The Login Authorization Process

After running the claude command, you'll enter a guided flow:

1. First, select the interface theme style (light or dark);
2. Next, choose the login method; the program will redirect to the Claude official website to complete authorization (provided you've already registered an account and completed a top-up or subscription);
3. After successful authorization, the system will automatically obtain a token and write it into the local .claude.json configuration file.

If you want to use a custom API Key, after configuring the environment variables, the program will ask "Do you want to use the Key from the current environment variables?"—choose "Yes" to use the Key you configured; the default "No" uses the token automatically obtained from the official website.

Signs of Successful Configuration

After completing all the steps, type claude in the terminal, and you should see the Welcome to Claude Code welcome screen, with the current workspace directory displayed below. Seeing this screen means all environment configuration is correct, and the installation and configuration phase is complete.

If you still see various option prompts instead of the welcome screen, it means the environment isn't fully configured yet—just follow the on-screen prompts to complete it step by step.

Summary

The barrier to entry for Claude Code may seem low, but there are quite a few traps hidden in the environment configuration, especially the two major hurdles faced by users in mainland China: network proxy and Git Bash environment variables. The complete configuration process is summarized as follows:

1. Install Node.js (LTS version, 20 or higher);
2. Install Git to get the Bash terminal;
3. Install Claude Code via npm;
4. Configure a proxy to resolve region restrictions;
5. Configure the API Key and complete authorization login.

Once you've worked through these five steps, you'll have laid a solid foundation for the subsequent core mode switching, CLAUDE.md memory management, and enterprise-level project practice. As the saying goes, a workman must first sharpen his tools—a stable runtime environment is the first cornerstone of mastering Claude Code.