Claude Code Installation, Configuration, and Secure Authorization Guide

3 hr ago0 views

This guide walks first-time developers and team tool administrators through checking prerequisites, installing Claude Code at the user level, configuring PATH, choosing subscription or API-key authentication, protecting credentials, and authorizing only the correct project directory for a safe first interaction.

Claude Code is an intelligent coding assistant that runs in the terminal. It can read project files, explain code, and help modify code, but it also has access to local directories and authentication credentials. Installation and configuration therefore require care. This article is intended for first-time developers and colleagues responsible for team tool management. After completing the steps below, readers should be able to launch Claude Code, complete authentication, and perform their first interaction in the correct project directory.

The risk boundaries are clear: do not authorize in your home directory or the system root directory, do not write keys into any shared file or screenshot, and do not disable certificate validation just to bypass an error.

1. Prerequisites and Environment Checks

Claude Code is distributed through npm, so you need Node.js and npm installed first. At the time of writing, the official instructions require Node.js 18 or later. Version requirements may change with releases. Before installing, check the official Claude Code installation documentation for the minimum version rather than relying on older tutorials.

Run the following commands in macOS, a Linux terminal, or Windows PowerShell:

node -v
npm -v

If both commands print version numbers, the environment is usable. If a command is not found, install Node.js from the official Node.js website or an organization-approved internal mirror. Do not use installation scripts from unknown sources.

For version switching, use a version manager. On macOS and Linux, nvm is an option; on Windows, nvm-windows is an option. Teams should record the Node.js and npm versions in internal documentation so others can reproduce the same environment.

2. User-Level Installation and PATH Configuration

Global installation with sudo is not recommended. A safer approach is to change the npm global directory to a location under the user directory.

On macOS and Linux, run:

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"

Then add the following line to ~/.zshrc or ~/.bashrc. Save the file and reopen the terminal:

export PATH="$HOME/.npm-global/bin:$PATH"

On Windows, run the following in PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.npm-global" | Out-Null
npm config set prefix "$env:USERPROFILE\.npm-global"

On Windows, npm places executable files directly in the prefix directory, without a bin subdirectory. Open “Edit environment variables for your account,” add %USERPROFILE%\.npm-global to the user variable Path, then close all PowerShell, terminal, and VS Code integrated terminal windows and reopen them.

Install and verify:

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

After installation, close and reopen the terminal before running claude --version. Windows users should also confirm that the VS Code integrated terminal has been restarted; otherwise, it may still use the old PATH.

To pin a version, append @version to the package name. Use a version that the team has already tested.

To locate the command, use which -a claude on macOS and Linux, and where.exe claude on Windows.

If installation fails, check the following table first:

Symptom	Likely cause	Verification command	Resolution
claude: command not found	The global directory is not in PATH	`npm config get prefix`; on macOS/Linux use `echo $PATH`, on Windows use `$env:Path`	Add the prefix directory to PATH and reopen the terminal
EACCES permission error	The global directory is owned by root	macOS/Linux: `ls -ld "$(npm config get prefix)"`; Windows: `$p = npm config get prefix; icacls $p`	Switch to a user-level prefix and do not use sudo
ETIMEDOUT or network timeout	Proxy or mirror configuration is incorrect	`npm config get registry`, `npm ping`	Access through the organization proxy or a compliant mirror
unable to verify the first certificate	The enterprise interception certificate is not trusted	Read the original error message	Set `NODE_EXTRA_CA_CERTS` to the root certificate provided by the organization
Version does not match expectations	An old version is still present	`npm ls -g @anthropic-ai/claude-code`, then check the command location	Run `npm uninstall -g @anthropic-ai/claude-code` and reinstall

If you see a certificate error, do not set NODE_TLS_REJECT_UNAUTHORIZED=0. This disables certificate validation and introduces man-in-the-middle attack risk.

If the command is still not found after modifying PATH, run npm config get prefix and inspect PATH. Confirm that the bin directory or the prefix directory is actually in the list.

3. Choosing an Authentication Method and Protecting Credentials

After running claude for the first time, enter /login in the session to choose an authentication method. The two common modes differ as follows:

Dimension	Subscription account login	API key
Intended user	Individual users who already have the relevant subscription	Team members or services that need usage-based billing and quota management
Login method	Browser authorization, then return to the terminal	Inject through environment variables or a secret management service
Cost model	Billed by subscription plan	Billed by actual usage
Audit granularity	Per individual account	Depends on the organization, plan, and console capabilities; may support differentiation by key or project. Actual capabilities depend on the console; this article does not promise a fixed audit granularity
Main risk	Account shared by multiple people	Key leakage can create cost and data risks

The selection principle is straightforward. Use subscription account login for personal learning and personal projects. Use API keys for shared team services or when cost allocation is required.

When entering an API key, avoid placing the key directly on the command line, where it may enter shell history.

On macOS and Linux (bash or zsh), use hidden input:

read -rs ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY

On Windows PowerShell, read the key as a secure string:

$secureKey = Read-Host "Enter API key" -AsSecureString
$bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureKey)
$env:ANTHROPIC_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr)
[Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)

Both approaches affect only the current session. For long-term use, place the key in the organization’s secret management service and have a startup script inject it at runtime. Do not permanently write the key into user environment variables or script files for convenience, and do not write it into .zshrc, .bashrc, or a PowerShell profile. These files are read every time a terminal opens and may also be synchronized or backed up.

If a .env file must be used, restrict it to the current user and ensure it does not enter version control. On macOS and Linux, run:

chmod 600 .env

On Windows, run:

icacls .env /inheritance:r /grant:r "$($env:USERNAME):(R)"

Avoid all of the following: writing keys into CLAUDE.md, settings.json, or script comments; displaying keys in shared terminals or screenshots; and sharing the same account or the same key among multiple people.

Keys should be rotated regularly according to organizational policy. Assign separate keys to different projects or members to reduce the impact of a leak. If a leak is suspected, revoke the key in the console immediately and issue a new one.

If authentication fails, troubleshoot in the following order. If browser authorization completes but the terminal does not update, first check whether a proxy is intercepting the local callback, then confirm that the system time and time zone are correct, and then try a different browser or disable blocking extensions before retrying.

If an API key returns 401, first check the variable length without printing the key contents. On macOS and Linux, run echo ${#ANTHROPIC_API_KEY}; on Windows, run $env:ANTHROPIC_API_KEY.Length. A length of 0 means the variable is not set. A clearly abnormal length may mean spaces or newlines were included; read the key again.

If the length is normal but the API still returns 401, the problem is usually the key itself or its permissions. Check whether the key is valid, whether it has expired, whether it has the required permissions, and whether it is restricted by organizational policy. You can sign in to the console to view the key status. During troubleshooting, never print the key contents or paste the key into chat or a ticket.

4. Directory Authorization and First Interaction

Enter the project root directory before launching the tool:

cd ~/work/demo-service
claude

On Windows, use cd C:\work\demo-service to enter the directory, then run claude.

After entering the directory, first confirm the current path with pwd (use Get-Location on Windows), then inspect the contents with ls (use dir on Windows). The first time you enter a directory, the tool asks whether to trust the folder. This is the most important security boundary. Confirm only the project root directory. Do not authorize in your home directory, the system root directory, or directories that contain keys and personal files. If you started in the wrong location, choose to decline, exit, and then enter the correct project root directory before launching again.

Before authorizing, check the following items one by one:

The current path is the project root directory, not the home directory, the system root directory, the desktop, or another broad directory.
The directory does not contain .env, key files, certificates, or personal documents. If it does, move them out first, or confirm that they are included in .gitignore and will not be uploaded.
The directory belongs to you or your team. On a shared machine, first confirm directory ownership and read/write permissions, and ask an administrator to adjust them if necessary.
The project is under version control and the workspace state is clear. If it is not under version control, back it up first.

After confirming everything is correct, choose to trust the directory. Even after trusting it, working in version control is still recommended. Commit or back up current changes first to avoid being unable to roll back after an accidental modification.

For the first interaction, start with read-only commands, such as asking the tool to list the main files or explain what a module does. This verifies that it is reading the correct project content and that the authorization scope matches expectations. After confirming that, ask it to perform modification or deletion operations. Before each modification, review the specific changes and then decide whether to accept them.

If you authorize the wrong directory, exit Claude Code immediately, inspect the trust record for that directory, and revoke trust for it according to the tool settings. After revocation, re-enter the correct project root directory. The exact settings entry point depends on the current official documentation.

5. Conclusion

After completing the configuration in this article, you should have the following capabilities. Node.js and npm versions can be checked, global installation does not depend on sudo, and claude --version outputs the version number normally. The authentication method is selected according to the use case: individual use uses subscription login, while team services use independent API keys injected by a secret management service and not written into shared files. Directory authorization applies only to the project root directory, checks are completed before authorization, and the first interaction starts with read-only commands for verification.