Complete Guide to Installing and Deploying Claude Code: Configure Your AI Coding Tool from Scratch

What Is Claude Code

Claude Code is an AI coding tool released by Anthropic that helps you write code, debug projects, and understand codebases—essentially an AI programmer on standby around the clock. The biggest difference between it and traditional AI assistants like ChatGPT is: it can directly operate on local files.

Claude Code falls into the category of "Agentic AI"—it doesn't just passively answer questions, but proactively executes multi-step tasks. Agentic AI represents a paradigm shift in AI from a "question-answering tool" to an "autonomous executor": capable of planning autonomously, executing multi-step tasks, and dynamically adjusting behavior based on environmental feedback. The core of this paradigm lies in the "Agent Loop"—under a single user instruction, the model can autonomously initiate dozens of rounds of tool calls, with the result of each call injected as new context to drive the next decision, until the task goal is achieved or a manual confirmation checkpoint is triggered.

To understand the essence of Agentic AI, it needs to be distinguished from traditional RPA (Robotic Process Automation): RPA relies on predefined rule scripts and halts upon encountering exceptions; whereas Agentic AI possesses "contextual reasoning" capability, able to re-plan its path mid-task based on exception information returned by tools. This characteristic enables Claude Code to diagnose the root cause of problems and attempt multiple repair strategies like a real developer when facing complex coding scenarios such as "project dependency conflicts" and "test case failures," rather than simply erroring out and exiting.

Claude Code's Agentic capability is built on the "Tool Use" mechanism: this mechanism was first officially introduced by OpenAI in June 2023 and became an industry standard—its underlying principle is that the model learns to recognize when an external function needs to be called and outputs structured call parameters, which the host program parses and executes, injecting the results back into the context, forming an iterative loop of "model reasoning → tool execution → result feedback." In Claude Code, this means the model not only outputs text but can also call predefined tool functions (such as reading files, executing shell commands, searching codebases), and continue reasoning with the tool's return results as new context, forming a closed loop of perception-decision-execution. It's worth noting that tool-calling capability is not merely a prompt-engineering trick, but a model capability achieved through dedicated fine-tuning—during the training phase, Anthropic used a large number of "function call examples" to teach the model when to trigger tools, how to construct valid JSON parameters, and how to integrate tool return values into subsequent reasoning chains. This allows Claude to accurately determine whether a tool call is needed even when handling ambiguous instructions, rather than generating hallucinatory "fake execution."

Behind it lies Anthropic's Claude 3.5/3.7 series of large models, featuring an ultra-long context window (up to 200K tokens). The 200K-token context window is one of Claude's core competitive advantages: 1K tokens is roughly equivalent to 50-80 lines of code, so 200K tokens means it can hold approximately 10,000-16,000 lines of code—enough to cover an entire medium-sized codebase. From an information-theory perspective, the value of an ultra-long context lies not only in the capacity itself but also in eliminating "context-switching cost"—traditional AI tools require manually splitting tasks and submitting them in batches when handling large projects, whereas Claude Code can maintain a "global view" of the entire codebase within a single session, understanding implicit dependencies between modules without the developer having to manually explain them.

It's worth mentioning that implementing an ultra-long context is not just about simply expanding the buffer. The computational complexity of the attention mechanism grows as O(n²) with sequence length, which means expanding the context from 4K to 200K theoretically increases the computation by about 2,500 times. Anthropic overcame this bottleneck by improving the attention mechanism (such as research into variants like sparse attention and sliding-window attention) and optimizing inference infrastructure (including efficient management of the KV Cache), enabling Claude Code to understand a project's complete dependency relationships and cross-file references without truncation. This is fundamentally different from completion tools like GitHub Copilot: Copilot primarily does line-level/block-level code completion, whereas Claude Code can understand project architecture, trace dependencies across files, execute terminal commands, and iteratively modify based on output results.

This means Claude Code can read your entire codebase, edit files, and execute commands. When encountering errors, there's no need to manually copy-paste them into a chat window—you can directly have it view the error message, pinpoint the cause, modify the code, and even run the project to verify the results.

In addition, Claude Code supports deep integration with mainstream IDEs. Whether it's VS Code or the JetBrains suite (IDEA, etc.), it can work seamlessly, truly embedding AI capabilities into the daily development workflow.

Environment Setup: Node.js and Git

Before installing Claude Code, you need to confirm two basic environments: Node.js and Git.

Node.js is the runtime foundation for Claude Code. Claude Code itself is distributed as an npm package and, once installed, runs as a CLI (Command Line Interface) tool in the local Node.js environment. The reason it requires Node 20+ is that this version introduced stable ES Modules support and a better fetch API, which is the baseline for modern JS toolchains. The role Node.js plays here is not only as a runtime container but also as a bridge between Claude Code and the operating system—low-level operations such as file read/write, process management, and network requests are all completed through Node.js's native APIs, which is why Claude Code can run consistently across platforms (Windows/macOS/Linux).

Open the command line (press Win + R and type CMD), then run the following commands to check your current environment:

node -v
git -v

If the version numbers display correctly, your environment is ready.

If you're missing the above environments, you can download and install them from the official websites. Here I especially recommend using NVM (Node Version Manager) to manage Node.js versions, making it easy to switch at any time. NVM achieves version isolation through a "Shell hijacking" mechanism: during installation, it injects an initialization script into the Shell configuration file; running nvm use essentially modifies the PATH of the current Shell session, placing the bin directory of the target version at the front of the system path so that the system prioritizes that version. NVM-Windows on Windows achieves the equivalent effect through a symbolic link (symlink) mechanism.

This design makes version switching completely transparent to upper-layer toolchains like npm and npx—different projects often depend on different Node versions, and NVM allows multiple versions to coexist on the same machine and be switched as needed, avoiding global environment pollution. It's a standard tool for frontend/full-stack developers. It's worth mentioning that for developers who maintain multiple projects long-term, you can also create a .nvmrc file in the project root directory, write in the required Node version number, and when you run nvm use, NVM will automatically read this file and switch to the corresponding version, achieving "project-aware" version management. This follows the same design philosophy as .python-version (pyenv) in the Python ecosystem and .ruby-version (rbenv) in the Ruby ecosystem: incorporating runtime version requirements into project codebase management so that new members get a consistent development environment right after cloning the project, eliminating the classic "it works on my machine" problem.

Managing Node Versions with NVM

After installing NVM, the common commands are as follows:

nvm -v          # Check NVM version
nvm install 20  # Install Node 20
nvm list        # View installed versions
nvm use 20      # Switch to Node 20

Important Note: Claude Code requires Node version 20 or above. A version that's too low will cause an error immediately during installation. This is the most common pitfall for beginners—please confirm it in advance.

Installing Claude Code

Once the environment is ready, run the following npm command to install Claude Code globally:

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

The -g flag (global) means Claude Code will be installed into Node.js's global bin directory, making the claude command callable from any path. The fundamental difference between global installation and local installation (without -g) lies in where the executable is registered—global installation soft-links the binary entry file to a directory included in the system PATH, whereas local installation only creates an entry under the current project's node_modules/.bin, which must be invoked via npx or npm scripts.

From a package-management architecture perspective, npm's global installation directory is usually located at lib/node_modules (Unix) or node_modules (Windows) under the Node.js installation path, and its exact location can be viewed with npm root -g. When using NVM to manage Node versions, each Node version has its own independent global package directory, which means that after switching Node versions, the globally installed Claude Code may "disappear"—this is a confusion NVM users are prone to encounter. The solution is to re-run the installation command after switching versions, or use the nvm install --reinstall-packages-from parameter to automatically migrate global packages when installing a new version.

After installation is complete, verify success with the following command:

claude -v

Seeing a version number means the installation was successful.

At this point, if you run claude directly, you'll likely see errors like "unable to connect to service" or "Bad Request." The reason is that Claude Code by default accesses Anthropic's overseas service (api.anthropic.com), and under network conditions in China, additional proxy and API configuration is required.

Configuring Network Proxy and API

Setting Proxy Environment Variables

Claude Code needs to continuously communicate with Anthropic's API server at runtime, and this domain is unstable to access under network conditions in China, so requests need to be forwarded through proxy software. HTTP_PROXY and HTTPS_PROXY are conventional environment variables originating from Unix tradition—almost all CLI tools that follow the 12-Factor App principles have built-in logic to read these two variables. Take the Node.js ecosystem as an example: the underlying HTTP client library checks these variables before initiating a request, and if they exist, forwards the request to the proxy server via an HTTP CONNECT tunnel or the SOCKS protocol. Claude Code's network layer also follows this convention, so proxy pass-through can be achieved without modifying any code.

The benefit of setting these variables at the system level (rather than the current Shell session) is that the configuration remains in effect after restarting the terminal, which is suitable for scenarios where the proxy is always resident. Note that some proxy software (such as Clash) provides both HTTP and SOCKS5 protocol ports. Claude Code's Node.js runtime natively supports the HTTP proxy protocol; if you use the SOCKS5 port, you'll need to additionally install middleware like socks-proxy-agent, so it's recommended to prioritize filling in the port corresponding to the HTTP protocol. In addition, some corporate network environments have SSL certificate interception (man-in-the-middle proxies), which may cause certificate validation errors on HTTPS requests. In this case, you need to add the corporate root certificate to Node.js's trust chain (specified via the NODE_EXTRA_CA_CERTS environment variable)—this is another configuration point that enterprise intranet users tend to overlook.

Another common misconception worth mentioning: on Windows, environment variables are divided into two scopes: "user variables" and "system variables." User variables take effect only for processes of the currently logged-in account, while system variables take effect for all users and system services. For proxy configuration, it's recommended to set them at the user-variable level—this ensures Claude Code reads them correctly while avoiding affecting the network behavior of system-level services, following the principle of minimal impact scope.

Close the current terminal, open the system Environment Variables settings panel, and create the following two variables, filling in the address and port corresponding to your proxy software (the port number should be configured according to your actual proxy software; common values are 7890, 1080, etc., and must match the actual listening port of proxy software like Clash or V2RayN):

After configuration is complete, save and confirm.

Configuring API Credentials

If you need to use a third-party API service, you can skip the official login process and directly modify the configuration file.

Go to the C-drive user directory, find the hidden .claude.json file under your current username, add the corresponding configuration in JSON format, paying attention to comma and indentation conventions, and after modifying, save with Ctrl + S. .claude.json follows the standard convention of a "user-level configuration file," stored in the user's home directory (~), with a priority higher than the default configuration during global installation but lower than the override directives in the project-level CLAUDE.md—this layered configuration mechanism allows users to set general preferences globally while customizing personalized behavior for specific projects.

From the perspective of configuration-file design philosophy, the naming convention starting with a dot in .claude.json comes from Unix tradition, indicating a "hidden file," typically storing a user's private credentials (API Key) and personal preference settings. Such files should not be committed to version control systems—if you use Git to manage your project, be sure to exclude .claude.json in .gitignore to prevent your API Key from accidentally leaking into a public repository. This is a fundamental rule of development security practices.

Managing API Providers with CC Switch

If you need to frequently switch API providers, it's recommended to install CC Switch for unified management. Download the corresponding installation package from GitHub, making sure to identify the correct project. During installation, you can customize the storage path and just click Next all the way through to finish.

CC Switch is essentially a graphical environment-variable manager that helps users quickly switch between multiple API providers, saving the step of manually editing configuration files. Domestic providers such as MiniMax, Zhipu AI, and Alibaba Cloud Bailian generally offer "OpenAI-compatible interfaces"—this interface specification has become the de facto standard protocol for AI service providers. Its rise stems from the ecosystem inertia accumulated through OpenAI's first-mover advantage: once mainstream frameworks like LangChain and LlamaIndex first supported the OpenAI format, later providers would bear extremely high integration costs if they were incompatible. Its core is reusing OpenAI's REST API specification, including the /v1/chat/completions endpoint, message format (role/content structure), and streaming output (SSE) protocol.

Worth understanding in depth is the key role of the SSE (Server-Sent Events) protocol in AI streaming output: compared to polling and WebSocket, SSE is a one-way server-push protocol implemented over an ordinary HTTP long connection. Its working principle is: after the client initiates an HTTP request, the connection remains open, and the server continuously pushes data chunks over the same connection in the format data: {...}\n\n. In AI streaming-output scenarios, an SSE message is pushed immediately as each token is generated, which lets users see the "character-by-character generation" effect rather than waiting for a complete response. For long code-generation tasks, this interaction-experience optimization is especially critical—users can judge in real time during generation whether the direction is correct and interrupt early if necessary, rather than waiting dozens of seconds only to see a result that may deviate entirely from expectations.

Developers only need to replace the base_url with the third-party provider's address to connect to different underlying models using the same set of code, enabling Claude Code to seamlessly interface with domestic providers through a middle layer. From a technical implementation perspective, Claude Code internally abstracts API requests into a call layer compatible with the OpenAI SDK, which means as long as a provider strictly implements this specification (including finish_reason, the usage statistics field, and the tool_calls structure for tool calls), Claude Code can switch seamlessly—but note that some domestic providers differ in their support for streaming output or long contexts, so it's recommended to test stability with simple instructions before actual use.

Adding and Switching Providers

After running CC Switch, click the "+" button to select multiple API providers from the built-in list.

Taking MiniMax as an example, the steps are as follows:

1. Subscribe to a plan: Choose a suitable plan on the MiniMax official website
2. Obtain the API Key: Go to the API page and copy the corresponding key
3. Fill it into CC Switch: Paste the API Key into the corresponding field, keeping the other parameters at their defaults
4. Click "Add" then click "Enable" to complete the provider switch

Verifying the Installation

After all configuration is complete, reopen CMD and run claude. The first launch requires completing the following initialization operations:

• Select the interface theme
• Confirm whether to trust the current folder (choose to trust)

The "trust folder" confirmation step is not a formality but an important security boundary setting—Claude Code will only exercise file read/write and command execution permissions on directories the user explicitly trusts, following the "Principle of Least Privilege": an AI agent should only perform operations within the scope explicitly authorized by the user, preventing accidental modification of system files or sensitive data outside the project.

From a security architecture perspective, this design is analogous to the operating system's "Sandbox" mechanism. Modern operating systems prevent programs from accessing resources beyond their authority through process isolation, while Claude Code's directory-trust mechanism implements similar boundary control at the application layer. It's worth noting that when Claude Code executes Shell commands, it has the same system permissions as the current user, which means if it's run under a high-privilege account and the entire file system is trusted, the AI could theoretically modify any file. Therefore, the recommendation is: for team collaboration scenarios, run claude in the project root directory and trust that directory rather than the entire user home directory; for sensitive projects involving production environment configuration, you can combine explicit prohibitions in CLAUDE.md (such as "do not modify any .env files") to build dual protection.

After entering the interactive interface, type "hello" and press Enter to test. If you receive a normal reply, it means Claude Code has successfully completed installation and configuration and can be officially put into use.

Advanced: Use CLAUDE.md to Make the AI Understand Your Project

After installation and configuration are complete, it's strongly recommended to create a CLAUDE.md file for each project. This is Claude Code's project-level configuration file; once placed in the project root directory, it will be automatically loaded each time a session starts. You can write in it project architecture descriptions, tech-stack conventions, code-style requirements, a list of files that must not be modified, and so on—essentially providing the AI programmer with an "onboarding handbook."

This design concept comes from "system prompt engineering." The System Prompt occupies the highest-priority position in the large language model's interaction architecture—in the attention mechanism of the Transformer architecture, the system prompt serves as the first segment of context, and its Token embedding vectors produce a continuous "attention weight bias" on all subsequent generation processes, thereby stably influencing the model's output style and constraint adherence. From a cognitive-science analogy, the System Prompt is like setting a "cognitive framework" for working memory, so that all subsequent information is interpreted within this framework—this is also why a well-formatted System Prompt has a more lasting influence on model behavior than scattered user instructions.

CLAUDE.md references the "convention over configuration" design philosophy of GitHub's .editorconfig and others, turning the system-prompt mechanism into a file that is persistent: Claude Code automatically injects its content into the system-prompt position each time a session starts, so the AI always has project context. This solves the fundamental limitation of large language models being "stateless"—the model itself does not remember historical sessions, but through structured context injection, it can simulate the effect of being "familiar with the project."

An effective CLAUDE.md typically includes: the project tech stack and directory structure, core files prohibited from automatic modification, code-style preferences, common Shell command references, and explanations of business-domain terminology. For team collaboration, CLAUDE.md can also be committed to the Git repository and reviewed and version-managed like code, ensuring that every member gets consistent AI behavior when using Claude Code.

It's worth noting that the content of CLAUDE.md itself also needs to be written with a "prompt engineering" mindset: being too verbose takes up the precious context window, while being too brief lacks guidance value. It's recommended to follow the "structure-first" principle, organizing information with Markdown headings and lists so the model can quickly locate key constraints; at the same time, place the most important prohibitions (such as "do not modify schema files") near the front of the file, leveraging the attention mechanism's higher weighting of the first segment to reinforce the constraint effect.

A practical advanced tip is to add "counterexample descriptions" to CLAUDE.md: besides describing the expected code style, explicitly list common anti-patterns (such as "do not use the any type" or "do not manipulate the DOM directly; use Vue reactive data-driven approaches uniformly"). Such negative constraints often correct model behavior more precisely than positive descriptions, especially for legacy projects with historical technical debt.

Summary: Four Key Steps to Installing Claude Code

Step	Content	Notes
1. Prepare the base environment	Install Node.js (≥20) and Git	A Node version that's too low will cause installation to fail
2. Install Claude Code	npm global installation	Run claude -v to verify
3. Solve network issues	Configure system proxy environment variables	Users in China must configure these; the port must match the proxy software
4. Connect to API services	Manage providers via CC Switch	Supports providers compatible with the OpenAI protocol, such as MiniMax

For users in China, network proxy and API configuration are the two main hurdles. Once you get through them, Claude Code's powerful local file operations and code-understanding capabilities will significantly improve development efficiency. Afterward, you can further explore advanced usage such as CLAUDE.md configuration and workflow orchestration, truly integrating AI coding into actual project development.

Key Takeaways